RESEARCH — Workflow efficiency hardening: corpus-finding guards, session-lifecycle habits, spec right-sizing

RESEARCH — Workflow efficiency hardening: corpus-finding guards, session-lifecycle habits, spec right-sizing

• Task: ID-92 — Workflow efficiency hardening — corpus-finding guards, session-lifecycle habits, spec right-sizing
• Subtask: {92.1} RESEARCH
• Session: untracked workflow-evaluation session (authored 07/06/2026)
• Provenance: corpus investigation S-prior (token-investigator subagent over the full 7-day ~/.claude/projects corpus, journaled into ID-48.23) + product-owner rough workflow notes (restructured into the {92.1} digest); ID-92 opened from the ID-48.23 promotion — 48.23 stays the data-layer slice, ID-92 is the action-side companion.
• Companion input: external-repo-survey.md (same dir) — mechanism-level survey of nine kunchenguid repos (axi family, treehouse, no-mistakes, gsh, acp-mock, acpx), authored 07/06/2026 by three parallel survey agents. Satisfies the C2 external-source requirement self-referentially. Provenance caveat carried forward: kunchenguid/acpx is a stale fork (01/05/2026) of openclaw/acpx (live upstream, 2,830 stars); acpx mechanisms cited below are from the fork snapshot, representative of upstream architecture.
• Post-research update (08/06/2026): a companion adoptability-assessment.md (same dir) re-reads the survey through an install-vs-adapt-vs-pattern lens and re-tiers §6’s ranked candidates — gh-axi + chrome-devtools-axi are light adopts (not pattern-only); treehouse is largely redundant with our harness worktree.symlinkDirectories knob (the real win was a stale-skill fix). ID-92 banked the quick-wins as Subtasks {92.5–92.14}: {92.5–92.11} landed (6 prose conventions + worktree fix), {92.12 gh-axi} + {92.13 chrome-devtools-axi} adopted, {92.14 lavish-axi} trialling. §6/§7/§8 below predate that re-read — PRODUCT.md carries the current synthesis + OQ resolutions.

---

Context

Code-intelligence orientation (Inv 2)

Run against the knowledge-hub GitNexus index:

• gitnexus_query({query: 'workflow evaluation token rollup session corpus metrics', repo: 'knowledge-hub'}) returned no relevant execution flows — the two matched processes (proc_163_procurementdetailpag “ProcurementDetailPage → UseBidTransitions”, priority 0.104; proc_11_get “GET → CreateClient”, priority 0.07) are unrelated procurement/pipeline flows. The workflow-evaluation surface appears only as standalone definitions: Function:lib/workflow-evaluation/token-rollup.ts:patchReportWithRollup (lines 283–329, module “Workflow-evaluation”) and Function:lib/workflow-evaluation/token-rollup.ts:runCli (lines 379–419).
• gitnexus_context({name: 'patchReportWithRollup'}) — incoming calls: runCli (same file) only; outgoing: none indexed; "processes": []. 1 direct caller, no flow participation — an isolated-surface finding, mirroring the ID-90 RESEARCH finding for the ledger-CLI surface: the symbols exist and are indexed, but nothing in the product runtime calls them. Verdict level: LOW.
• gitnexus_context({name: 'rollupTokenUsage'}) — Symbol 'rollupTokenUsage' not found. The ID-48.23 brief names rollupTokenUsage as the impact-analysis target; the actual exported surface of lib/workflow-evaluation/token-rollup.ts is patchReportWithRollup / runCli. Minor symbol-name drift in the 48.23 brief — flagged to the Orchestrator in the {92.1} report (48.23 scope, not ID-92).

Interpretation: ID-92’s fix surfaces are overwhelmingly markdown workflow artefacts (.claude/skills/*, .claude/agents/* — out-of-scope for the code-intel allowlist per the workflow-orchestration baseline). The only code-touching candidate surfaces are lib/workflow-evaluation/token-rollup.ts (LOW blast radius, isolated) and scripts/analyze_claude_session_tokens.py (Python — ast-dataflow does not cover; 48.23 scope anyway).

Empirical verification note (OQ-3 / Q-EX2 discipline)

No third-party external-library APIs are cited in this document. The external-repo survey describes third-party repo mechanisms as design references — nothing below mandates importing or calling any symbol from those repos, so the pre-ratification import-and-call check is not applicable. All KH-internal file:line claims below were read from the working tree on 07/06/2026.

Re-verification scope

The {92.1} digest notes predate parts of the ID-68 (repo visibility / docs relocation) and ID-90 (server-ledger cutover) work. Per the dispatch mandate, every Theme A–C item below was re-verified on 07/06/2026 against:

• Task 90 record + 90.17 / 90.21 journals (spec chain {90.1–4} ratified; records {90.5–13} done, {90.14–23} pending; cutover NOT yet live — scripts/ledger-cli.ts remains the sanctioned mutation path today).
• Task 68 record + 68.28 journal (Phase-0 complete; 68.28 pending — docs/workflow-evaluation/ confirmed still in-repo).
• The named fix surfaces, all confirmed present: .claude/skills/workflow-orchestration/ (SKILL.md 452 lines + 7 reference files), .claude/skills/triage-finding/SKILL.md (403), .claude/skills/handoff/SKILL.md (124), .claude/skills/start-session/SKILL.md (110), .claude/skills/spec-driven-implementation/SKILL.md (224), .claude/agents/task-planner.md (482), .claude/skills/evaluate-workflow/SKILL.md (401), .claude/skills/evaluate-findings/SKILL.md (522), plus .claude/agents/{task-executor,task-checker,workflow-curator,workflow-evaluator}.md and .claude/skills/session-driver-cmux/.

Verdict vocabulary: CURRENT (gap exists as described; fix surface valid) / PARTIALLY SUPERSEDED (part of the item already landed via named work; residual slice identified) / SUPERSEDED (fully covered by named work; no ID-92 action).

---

§1 Problem statement + corpus evidence

The 7-day corpus investigation (460 usage-bearing transcripts; corrected baseline 2.716B flat tokens / 19,078 API requests — fresh 0.2% / cache-write 4.8% / cache-read 94.2%; cost-weighted 493.5M units) surfaced three classes of workflow inefficiency that are behavioural, not data-layer:

1. Unbounded tool outputs entering agent context: 130 persisted oversized tool results totalling 17.1MB in 7 days, including a single 4.7MB git diff (cbe21df7…/tool-results/blhq3sy1f.txt), a 469KB mempalace_search result, and a 467KB gitnexus detect_changes result.
2. Orchestrator-as-workhorse: 24/460 transcripts exceeded 400K peak context — all 24 were orchestrator mains (zero subagents, zero worker mains). The worst three (701K / 597K / 589K peaks) had 1–2 spawns each: executor-grade work done inline on the most expensive thread class (1h-TTL cache writes, 49% of corpus flat spend).
3. Recurring-issue thrash: dispatches at >3× their role’s median request count — a 135-request general-purpose run (median 14, bl-220 memo-serde), a 127-request checker run for one backlink fix, a 139-request executor ({68.25}). Recurring issues both consume multi-turn budget and cause it downstream when left unresolved at source.

Alongside these, the product-owner notes identified session-lifecycle habits (Theme B) and spec-chain right-sizing (Theme C) opportunities. Analyzer caveat carried from the 48.23 journal: the corpus figures above use the corrected message.id-deduplicated baseline (naive row summing inflates 2.2–2.6×; verified on transcript 8c3ea5e4…: 724 rows → 329 distinct ids, naive output 582,450 vs correct 216,780). ID-92 consumes the 48.23 measurement substrate; it does not re-derive it.

Important scoping inheritance from the ID-92 Task record: skill-file subtasks do not block on 48.23 — guard definitions can land in skill prose now; programmatic wiring lands when the 48.23 data layer ships.

---

§2 Theme A — programmatic guards

A1 — Unbounded tool outputs

Digest claim. 4.7MB git diff, 469KB mempalace_search, 467KB gitnexus detect_changes persisted; 130 oversized results / 17.1MB in 7 days. Fix surface: executor/checker/sub-orchestrator brief conventions + relevant skill files — --stat-first discipline, result-size guards, paginate/filter-at-source. Detection metric (tool-results dir bytes per session) validated.

Verification verdict: CURRENT — with one piece of partial prior art. .claude/agents/task-checker.md already mandates per-commit git show --stat <commit> (lines 67, 72; reiterated at 324, 403, 534) — but that is checker-only and diff-only. Verified absent everywhere else: the dispatch-brief composition list in workflow-orchestration/references/dispatch-primitives.md carries no result-size item; task-executor.md has no output-size discipline; session-driver-cmux briefs have none; no skill addresses mempalace_search / gitnexus_detect_changes result-size hygiene. The detection metric is NOT in the evaluate-workflow §7 metric set (verified: five metrics — token-per-role, duplicated reads, redundant dispatches E1/E6, megaturns, coordination overhead E3/E4 — no tool-results-bytes metric). The 48.23 journal also validated a related brief-convention fix: two observed 64K output-cap hits on worker handoff reports — truncation risk on load-bearing artefacts; convention fix is “write report to file, return path + summary”, likewise absent from current brief conventions.

External-pattern evidence (survey). The strongest theme in the survey, with complete reference implementations:

• gh-axi: diff/log truncation with original_length receipt + ready-to-run --full escape command; body-cleaning pass (URL shortening, image/quote stripping) before truncation.
• gsh: hard interpreter caps — exec 50KB with model-visible "truncated": true flag; view_file 100KB with middle-out truncation (head + tail preserved); --stat-first + head -1000-bounded diff context as a worked example of our exact guard.
• acpx: --suppress-reads filter-at-source + artifact externalisation (“large payloads become content-addressed artifact refs; only small scalars inline”) — the direct fix shape for multi-MB outputs landing in context.
• chrome-devtools-axi: head+tail truncation (40% head / 60% tail) for command output where the failure is at the end.
• Doctrine note (axi cross-repo synthesis): “enforce output budgets at the source with truncation receipts and escape hatches, never via agent discipline”. Our near-term fix surface is brief conventions (discipline); the survey’s position is that tool-boundary enforcement is the durable form — see §7 OQ-4.

Candidate fix surface. workflow-orchestration/references/dispatch-primitives.md (brief composition list — add result-size guard + report-to-file items), task-executor.md, task-checker.md (generalise beyond git-diff), session-driver-cmux brief fragments, plus a one-bullet CLAUDE.md gotcha candidate. Metric wiring (tool-results dir bytes per session) → evaluate-workflow SKILL.md metric set (see A2i dependency note).

A2 — Orchestrator-as-workhorse

Digest claim. Two-part fix: (i) programmatic guard — flag peak > 400K AND sub:main flat ratio < 0.2 (both fields already computed by analyzer); (ii) workflow-orchestration skill education — the worst-3 pattern shows the orchestrate-don’t-implement contract is not internalised by every session.

Verification verdict (A2i — guard wiring): CURRENT. Verified: evaluate-workflow/SKILL.md §7 metric set has no peak-context or spawn-ratio metric. Its per-role attribution is itself flagged “v2 follow-up” (metric 1) pending ID-48.23, which is still pending. The guard’s two input fields (peak per-turn context high-water mark; per-role/sub:main flat split) are 48.23 slice-2 deliverables — the guard wiring therefore soft-depends on the 48.23 data layer, while the guard definition (thresholds, response protocol) can land in skill prose now. This is a cross-Task data dependency the {92.4} PLAN must NOT express as a Subtask dependency (sibling-only constraint) — see §8.

Verification verdict (A2ii — skill education): CURRENT. Verified: workflow-orchestration/SKILL.md states the contract (“The Orchestrator does not write production code…”, “The Orchestrator never invokes a sub-agent inline”) — yet all 24 >400K-peak sessions were orchestrator mains. The contract exists; the economics do not: nothing in the skill explains WHY inline work on the main thread is the most expensive possible shape (1h-TTL writes; every turn re-sends the growing context), and nothing names the observed anti-pattern signature (high peak + near-zero spawn ratio) so a session can self-diagnose.

External-pattern evidence (survey).

• axi bench causal finding: “each extra turn re-sends the entire growing context, so the savings from a smaller initial context are consumed by accumulation across additional turns” — turn count dominates cost. This is the quantitative backing for the education pass.
• gsh per-turn cost footer (523 in (80% cached) · 324 out · 1.2s) — the observability primitive that would make workhorse-drift visible live rather than post-hoc.
• acpx acp/action/compute node taxonomy + “the worker is not the workflow engine” — deterministic mechanics never consume reasoning context; the codified inverse of our anti-pattern.
• treehouse pooled worktrees — lowers the marginal cost of spawning a subagent, removing the main excuse for orchestrator-inline work (per-dispatch stale-start + dependency-reinstall tax).

Candidate fix surface. A2i: evaluate-workflow/SKILL.md (metric set + report columns) + workflow-evaluator.md agent doc. A2ii: workflow-orchestration/SKILL.md (a short “context economics” subsection: the turn-cost finding, the 400K/0.2 signature, the corpus evidence) — education, not new rules.

A3 — Recurring-issue thrash

Digest claim. Thrashing flag (dispatch requests >3× role median) validated against three corpus instances. New loop: flag → diagnose root cause → fix at source (skill/brief/gotcha) → verify recurrence drops. Product-owner instinct: recurring issues also CAUSE multi-turn burn, so programmatic identification + resolution is core workflow-evaluator value.

Verification verdict: CURRENT (extension of existing machinery). Verified: evaluate-workflow/SKILL.md already has the recurring-finding surface (the C5 guard: bucket findings by canonical key, flag count >= 3 across distinct sessions, surface to O-of-O — “flag the pattern, let the O-of-O decide”). What is absent: (a) the thrashing flag itself (>3× role-median requests per dispatch) is not in the metric set — it needs per-dispatch request counts from the 48.23 per-role join (same soft dependency as A2i); (b) the resolve-at-source loop — the existing skill stops at “surface the pattern”; there is no defined follow-through (diagnose → fix at skill/brief/gotcha source → verify recurrence drops in the next sweep), and no routing convention for what a recurrence-class finding becomes (the triage-finding decision tree has no recurrence-aware path).

External-pattern evidence (survey).

• no-mistakes round-history injection (“do NOT re-report findings under user_chose_to_ignore unless materially different”) + bounded auto-fix budgets per step with forced human pause at the limit — “the cleanest anti-thrash mechanism surveyed”; converts unbounded >3×-median thrash into a structural ceiling. Directly applicable to our checker/fixer re-dispatch loops.
• gh-axi error-translation table with embedded remediation commands — converts recurring tool-failure stderr into a one-shot fix path instead of flag→diagnose→retry.
• acpx routable failure outcomes (timed_out routes via a switch edge instead of thrashing or dying) + TUNING.md colocated decision journals (Change / Reason / what-we-decided-NOT-to-do) — the fix-at-source loop made into a written artefact.
• chrome-devtools-axi STALE_REF fail-loud — converts a silent-failure→confusion→thrash loop into an immediate, self-describing retry signal.

Candidate fix surface. Flag: evaluate-workflow/SKILL.md metric set (with A2i, same wiring wave). Loop: evaluate-workflow/SKILL.md recurring-finding section (extend “surface” into the four-step loop) + workflow-evaluator.md + a recurrence-aware note in triage-finding (a recurrence-class finding is committed work per the §0 committed-work rule — it routes to the Task List). Bounded-retry budgets for fix-Executor loops: workflow-orchestration/references/failure-modes.md (pattern 3 currently caps Checker FAILs at three — generalise the ceiling-then-pause shape to fix-dispatch request budgets).

---

§3 Theme B — session-lifecycle habits

B1 — Subtask-not-backlog + carryover discipline

Digest claim. If work should be a subtask, make it one rather than backlog; completion may carry over across sessions. Fix surface: triage-finding decision logic + workflow-orchestration carryover conventions.

Verification verdict: PARTIALLY SUPERSEDED (by the S300 committed-work rule + the handoff Session Carry section). Verified: triage-finding/SKILL.md Step 2 now carries the committed-work rule as a top-of-tree gate — “A finding that is committed work … routes to the Task List … NOT the backlog. The commitment test: have we committed to doing this? Yes → Task List; not yet → Backlog. Rationale: bl-216–221 (S300) were concrete critical-path defects mis-filed to the backlog” — which is the routing half of B1, already landed. And handoff/SKILL.md Step 3 already includes a ”## Session Carry” section (“Anything which was intended for the previous session, but wasn’t completed”). Residual slice: the carryover convention is nowhere stated affirmatively — i.e. an explicit line that in-flight Subtasks survive session boundaries as in_progress/pending records rather than being demoted to backlog at session close, and that session-close triage must not use the backlog as a parking lot for started work. That one-paragraph convention belongs in workflow-orchestration (or handoff), plus a matching entry in triage-finding’s “Failure modes to avoid” list.

External-pattern evidence (survey). no-mistakes “intent is required, pass it from the conversation, don’t re-derive” mirrors the discipline; lavish-axi SessionStart ambient open-sessions list is carryover made automatic.

Candidate fix surface. workflow-orchestration/SKILL.md (one short carryover convention) + triage-finding/SKILL.md failure-modes list. Small — a candidate for merging with another Theme-B slice at PLAN time.

B2 — Sandbox/allowlist carryover

Digest claim. Recurring sandbox friction (canonical example: zsh word-split quirk) should produce explicit guidance at session boundaries: /handoff emits allowlist candidates + bypass notes; /start-session ingests them.

Verification verdict: CURRENT. Verified: zero occurrences of “sandbox” or “allowlist” in handoff/SKILL.md or start-session/SKILL.md (grep on 07/06/2026). The handoff template’s “Session deltas” section could carry these today but nothing prompts for them; start-session has no ingestion step.

External-pattern evidence (survey).

• acpx pre-run permission resolution — a flow declares its minimum permission mode + whether it needs an explicit operator grant; the runner resolves the effective mode and fails fast before any work if the grant is missing; granted mode propagates through every reuse path. The survey’s strongest B2 hit: converts the carryover habit into an enforced contract at dispatch time.
• axi-sdk hooks.ts — marker-based idempotent SessionStart hook install/repair: machine-emitted ambient state at session start rather than human-remembered notes.
• treehouse — the pool persists environment state across sessions; “the worktree IS the carryover”.

Candidate fix surface. handoff/SKILL.md (add an “allowlist candidates + sandbox bypass notes” prompt to Step 2’s question list and a slot in the template) + start-session/SKILL.md (ingestion step). A fail-fast declared-permissions convention for dispatch briefs (acpx-shaped) is a stretch goal — note for PRODUCT.

B3 — Roadmap-context at session start

Digest claim. Read the roadmap item owning the session’s active task during /start-session so strategic context is in-window. Open design question: which item(s), how much to read (token cost vs context value).

Verification verdict: CURRENT. Verified: start-session/SKILL.md Step 2 reads Mempalace diary + task-list recent journals + continuation prompt; zero occurrences of “roadmap”. New empirical input on the open design question: docs/reference/product-roadmap.json is 23KB total across 12 themes (~1–2KB per theme record) — a single owning-theme read is near-free; the token-cost concern in the digest is empirically small at current roadmap size. The design question reduces to which theme(s) (owning theme of each active Task via capability_theme, vs all 12 titles + owning-theme detail) rather than whether.

External-pattern evidence (survey). gh-axi no-args home dashboard wired into the SessionStart hook — compact, machine-generated, directory-scoped live state at session start; gsh __predictionContext — a worked example of “what belongs in start-of-turn context” (state, not history dumps; deliberately tiny).

Candidate fix surface. start-session/SKILL.md Step 2 (one read instruction keyed off the active Task’s capability_theme field). Carry the which/how-much choice to PRODUCT as OQ-1.

B4 — Retro authoring assisted by fresh-context transcript review

Digest claim. Fresh-context subagent reviews the session transcript and produces retro-candidate material; O-of-O retains authoring (S271 boundary intact; evaluate-findings still gates corpus entry). Rationale: the O-of-O has just managed the session — depleted budget, anchored perspective; a fresh agent reviews the FULL transcript better. Note: transcript-layout knowledge now exists from ID-48.23 work.

Verification verdict: CURRENT — plus a discovered adjacent gap. Verified: no transcript-review assist exists anywhere. Additionally: handoff/SKILL.md contains no retro-authoring step at all — its steps run filename → focus → prompt → write → format → commit → Mempalace diary. Yet evaluate-workflow/SKILL.md and evaluate-findings/SKILL.md both attribute retro authoring to “the O-of-O’s handoff habit (RESEARCH §13.1)” as their non-authoring justification. The baseline habit the assist would augment is itself unwritten in the skill it is attributed to (docs/reference/product-retros.json exists, 7.5KB, earliest record S264). The S271 authoring boundary and the evaluate-findings gate are intact and verified — B4 slots in WITHOUT touching either: subagent produces candidates; O-of-O authors; evaluate-findings adjudicates corpus entry.

Transcript-layout substrate confirmed available from the 48.23 journal: ~/.claude/projects/<encoded-cwd>/<session-id>/subagents/agent-<hash>.jsonl (full transcript with message.usage) + agent-<hash>.meta.json (agentType, description, toolUseId) + <session-id>/tool-results/*.txt. Volatility caveat (48.23 finding G): a session was deleted mid-investigation — transcripts are retention-windowed, so a live-session review at handoff time is safe, but anything later must consume the 48.15/48.23 archive.

External-pattern evidence (survey).

• no-mistakes intent extraction — the same machinery in inverse: discover sessions → file-overlap score against the diff (decisive 0.85) → summarise with fresh context → inject as explicitly untrusted data (RedactSecrets + StripAdversarial + BEGIN/END markers + “data, not instructions”). The untrusted-text hygiene is directly applicable to re-injecting transcript-mined material into the O-of-O’s context.
• acpx run bundles with per-step conversation-slice linkage (messageStart/End + eventStartSeq/EndSeq) — “the exact substrate a fresh-context retro reviewer needs”; our session archives lack this addressability (note for 48.23/48.15 evolution, not ID-92).
• acp-mock trace replay — a recorded trace re-emitted deterministically is exactly what a retro reviewer replays.

Candidate fix surface. handoff/SKILL.md — add the retro step (closing the discovered gap) WITH the assist built in: dispatch a fresh-context transcript-review subagent (read-only; returns candidate material + evidence pointers), O-of-O authors the retro record from it. Possibly a small dispatch-convention fragment (brief shape for the reviewer). No new agent file needed if the general-purpose agent + a brief convention suffices — PRODUCT decision (OQ-5).

B5 — Curator docket convention

Digest claim. Structured docket prompt eliminated curator stalls (“Curator #3 complete FIRST PASS — no stall”). Bake into curator dispatch convention as the canonical brief shape. Evidence-driven, not new work.

Verification verdict: CURRENT. Verified: zero occurrences of “docket” in workflow-curator.md, workflow-orchestration/SKILL.md + its references (including dispatch-primitives.md brief-composition list), and session-driver-cmux. The curator agent doc’s input contract (finding packet + task context fields) is well-specified for triage inputs, but the session-validated docket shape that eliminated stalls is captured nowhere.

External-pattern evidence (survey).

• lavish-axi playbook-per-artifact-shape — “structurally identical to what B5 docket prompts want: a small catalog of typed, fetch-on-demand prompt templates rather than ad-hoc dispatch prose”; plus next_step imperative fields in tool output keeping agents on-protocol mid-task.
• no-mistakes composable sanitised prompt fragments (execution-context, intent, round-history, steering) instead of monolithic briefs.
• acpx .pi/prompts/landpr.md — structured, versioned dispatch prompts as repo artifacts.

Candidate fix surface. workflow-curator.md (canonical docket shape section) and/or workflow-orchestration/references/dispatch-primitives.md (Curator-brief composition entry). The source docket text must be recovered from the originating session’s artefacts — the Orchestrator should attach it to the {92.x} dispatch brief.

---

§4 Theme C — spec-chain right-sizing

C1 — Right-size the chain

Digest claim. Allow PRODUCT or TECH (+ PLAN) instead of the full four-artefact chain when the task shape warrants. Fix surface: spec-driven-implementation skill + task-planner agent doc.

Verification verdict: PARTIALLY SUPERSEDED — the gap is internal inconsistency, not absence. Verified: spec-driven-implementation/SKILL.md already carries right-sizing pragmatism — “Be pragmatic: not every change needs specs”; tech spec “when warranted” with explicit criteria; “For pure UI changes, the product spec is often useful while the tech spec may be unnecessary”; RESEARCH and PLAN both conditional. BUT .claude/agents/task-planner.md presents {N.2} PRODUCT as “always, for every Task (unless the Task is purely operational…)” and {N.3} TECH as “always, after {N.2}”, and the workflow-orchestration lifecycle diagram + references/lifecycle-detail.md show PRODUCT/TECH as unconditional chain links (only {N.1}/{N.4} marked conditional). The Planner/Orchestrator surfaces mandate what the spec skill already relaxes. Residual slice: align the three surfaces and add an explicit decision rule — which artefact subset per task shape, who decides (Orchestrator at Task open vs Planner recommendation), and where the decision is recorded.

External-pattern evidence (survey).

• acpx scoped validation matrices (“docs-only → check:docs only”) + “no new node” defaults — “written right-sizing rules that let routine task shapes take the light path without eroding the heavy path”. The key transferable property: the light path is sanctioned in writing, not negotiated ad hoc.
• no-mistakes per-run --skip=<steps> push options — sanctioned chain right-sizing per task shape.
• lavish-axi plan playbook + annotation loop — a lighter-weight spec-review chain for tasks that don’t warrant the full {N.1–N.4}.

Candidate fix surface. spec-driven-implementation/SKILL.md (the decision rule), task-planner.md (“always” → conditional language), workflow-orchestration/SKILL.md + references/lifecycle-detail.md (lifecycle diagram annotations). One subtask with C2 (same files).

C2 — RESEARCH.md scope widened beyond codebase

Digest claim. Research subtasks should not be codebase-scoped only; include online research, IMS, and other external sources where relevant. Fix surface: spec-driven-implementation + write-product-spec skills, task-planner agent doc.

Verification verdict: CURRENT (and satisfied self-referentially for ID-92 by the external-repo survey). Verified: task-planner.md’s {N.1} RESEARCH section directs only task-specific domain skills (claude-api, supabase-postgres-best-practices, etc.) plus the mandatory gitnexus/ccc code-intel orientation — all codebase/tooling-scoped; no direction toward online research, external repo survey, IMS, or market sources. write-product-spec/SKILL.md likewise (its only “web” mentions are UI personas). Notably the capability already exists in the environment — deep-research skill, WebSearch/WebFetch deferred tools — it is simply not routed into the {N.1} convention. This document’s own production (three parallel survey agents over nine external repos, theme-mapped) is the worked example the convention should cite.

External-pattern evidence (survey). acpx coverage-roadmap doc tracking implementation against the external evolving ACP spec — “a standing habit of diffing internal state against an external source of truth” (the survey’s own weak-C2 mapping).

Candidate fix surface. task-planner.md {N.1} section (add external-source lanes: online/deep-research, external repo survey, IMS/market docs — with the Q-EX2 empirical-verification discipline extended to externally-sourced API claims), spec-driven-implementation/SKILL.md (research-scope sentence). write-product-spec is a lighter touch than the digest implies (PRODUCT consumes research; the scope rule lives upstream) — PLAN may drop it from the file set.

---

§5 Theme D — reroute record (out of ID-92 scope)

Listed for completeness; all four reroutes verified landed on 07/06/2026.

Item	Substance	Rerouted to	Verified
D1	ledger-cli get dotted-path quirk (get 69.2 → not-found while the subtask exists)	ID-90.17 (transport client must not replicate; dotted-path case added to parity/port test set; CLI-side fix optional given P3 retirement)	Journal block present in 90.17 details (07/06/2026)
D2	Sub-orchestrator mirror hand-edits (2 of 5 cmux sub-orchestrators hand-edited the .md mirror instead of using ledger-cli)	ID-90.21 (soak watch; structural fix = server write-gates; interim fallback = restrict ledger writes to orchestrator/dedicated roles if soak slips)	Journal block present in 90.21 details (07/06/2026)
D3	Relocate ledgers + everything-scripted (emeraldcave example)	Superseded by the ID-90 server-ledger pivot (spec chain ratified; records {90.5–13} done)	Task 90 record verified in_progress
D4	Move docs/workflow-evaluation/ out of in-repo docs	ID-68.28 (relocation residual)	Journal block present in 68.28 details; docs/workflow-evaluation/sessions/ confirmed still in-repo; ${KH_PRIVATE_DOCS_DIR}/workflow-evaluation/ does NOT yet exist while evaluate-workflow/SKILL.md already references it — relocation half-done, exactly as journaled. A stray docs/reference/workflow-evaluation/s280-first-run.md also exists (68.28 sweep candidate).

Cross-task coordination notes for ID-92 (consequences of D, not new scope):

1. ID-90 ledger-surface churn. triage-finding, update-roadmap-backlog, and workflow-orchestration embed bun scripts/ledger-cli.ts invocations throughout. ID-90’s P3 retirement chain ({90.22}/{90.23}) will re-point these. ID-92 subtasks amending those same skill files (B1, B5, A3-routing) should avoid adding NEW hard-coded ledger-cli invocation examples, or note them for the {90.23} docs pass.
2. ID-68.28 corpus relocation. A2i/A3 metric wiring touches evaluate-workflow/SKILL.md, whose corpus/report paths already point at ${KH_PRIVATE_DOCS_DIR}/workflow-evaluation/ while the data still lives in-repo. Wiring subtasks should treat the private-docs path as canonical (matching the skill) and not re-introduce in-repo paths.

---

§6 External survey synthesis — transferable doctrine + ranked adoption candidates

The transferable doctrine (condensed from the survey’s three syntheses)

1. Turn count dominates cost — every turn re-sends the growing context. Batch at the tool boundary (scripts, pre-computed aggregates) rather than coaching agents to be terse. [A2]
2. Enforce output budgets at the source — truncation-with-receipt (truncated: true, original_length, ready-to-run --full escape) at the tool boundary; “never via agent discipline”. [A1]
3. Make recurring failures structural, not behavioural — round-history injection, bounded retry budgets with forced human pause, error tables with embedded remediation, fail-loud staleness, definitive empty states, idempotent no-ops. Thrash loops cannot form when non-ok outcomes are routable. [A3]
4. Inject compact live state at session start; put imperative protocol into tool output — SessionStart ambient context (machine-generated, directory-scoped), next_step fields in structured output rather than hoping briefs were read. [B2/B3/B5]
5. Single source of truth + drift gates for agent-facing artefacts — generated SKILL.md with --check in CI; convention enforced by machine, not memory. [A3-adjacent]
6. Untrusted-text hygiene for transcript-mined material — redact, adversarial-strip, delimiter-wrap, label “data, not instructions” before re-injection. [B4]
7. Measure interventions before standardising — conditions-matrix (CLAUDE.md variants × tasks × repeats) + LLM judge + JSONL token accounting. [novel — instrument]

Ranked adoption candidates (effort × leverage)

#	Candidate	Source mechanism	Theme	Effort	Leverage	Notes
1	A1 guard kit as brief conventions: --stat-first, hard size expectations, head+tail truncation guidance, filter-at-source flags, report-to-file-return-path for >64K artefacts	gsh interpreter caps; gh-axi receipt shape; acpx --suppress-reads/artifact refs	A1	Low (markdown sweep)	High — 17.1MB/7-days observed; 4.7MB single diff; 2× 64K cap hits on load-bearing reports	Discipline form now; tool-boundary wrapper is the durable follow-on (OQ-4)
2	Round-history + bounded-retry budget for fix-dispatch loops (“don’t re-litigate ignored findings; pause at the limit”)	no-mistakes round model	A3	Medium (convention + journal-block shape)	High — directly targets the 127/135/139-request thrash class	Generalises the existing “3 Checker FAILs → escalate” pattern
3	Session-boundary carryover contract: /handoff emits allowlist candidates + sandbox notes; /start-session ingests; stretch: declared-permissions fail-fast in dispatch briefs	acpx pre-run permission resolution; axi SessionStart hooks	B2	Low	Medium-high — recurring friction, zero current coverage
4	Context-economics education block + anti-pattern signature (peak>400K, spawn-ratio<0.2) in workflow-orchestration	axi turn-cost finding; gsh cost footer; acpx “worker is not the workflow engine”	A2ii	Low	Medium-high — all 24 worst sessions are this one pattern	Guard wiring (A2i) follows the 48.23 data layer
5	Fresh-context transcript-review retro assist with untrusted-text hygiene	no-mistakes intent extraction (inverse); acp-mock/acpx replay substrate	B4	Medium	Medium — quality-of-retros play; also closes the missing handoff retro step	S271 boundary untouched
6	Docket/playbook catalogue for Curator (and later other role) dispatches	lavish-axi playbooks; no-mistakes prompt fragments	B5	Low	Medium — session-validated stall fix	Needs source docket text from originating session
7	Written right-sizing rules for the spec chain (scoped-validation-matrix shape)	acpx scoped matrices + “no new node” defaults; no-mistakes --skip	C1/C2	Low	Medium — removes per-Task chain negotiation
8	Conditions-matrix bench harness for measuring workflow interventions (A/B a guard before standardising)	axi bench-github/bench-browser	novel	High	Medium (long-run)	NOT an ID-92 subtask — backlog candidate; evaluate-workflow lane is the interim instrument
9	Pooled reset-on-acquire worktrees (dirty + process-scan reclamation)	treehouse	A2-enabler	High	Medium	NOT ID-92 — backlog candidate; automates two existing CLAUDE.md gotchas

Candidates 8–9 are recorded for Curator routing (backlog), not for {92.4} decomposition.

---

§7 Open questions for PRODUCT

1. B3 — which roadmap context, how much? Empirical input: the roadmap is 23KB / 12 themes (~1–2KB per theme). Options: (a) owning theme only, resolved via the active Task’s capability_theme; (b) all 12 theme titles + owning-theme detail; (c) full roadmap. Token cost is small in all options at current size; pick on context-value + drift-as-roadmap-grows grounds.
2. A2i/A3 — guard definition vs wiring, given the 48.23 dependency. The Task record rules that skill-file subtasks do not block on 48.23. Recommended shape for PRODUCT to ratify: guard definitions (thresholds: peak>400K AND sub:main flat ratio<0.2; dispatch requests >3× role median; tool-results bytes per session) land in evaluate-workflow prose NOW with an explicit “computed once the 48.23 fields ship” marker; programmatic wiring is a later slice. Alternative: reroute the wiring slice into ID-48 as a new subtask (keeps ID-92 purely behavioural). Sibling-only constraint forbids expressing this as a Subtask-level cross dep either way.
3. ToolSearch / deferred-tool configuration. The axi bench found lazy tool loading (ToolSearch-style) net-negative — 2-turn discovery overhead + a new failure mode (can’t find the tool; 22-turn spirals) — when most tools get used. Our harness defers a large MCP set (coolify, supabase, mempalace…) of which most go unused in a typical session — a different regime where deferral likely still wins. Should PRODUCT take a position (e.g. keep deferral, but eager-load the per-role core set named in dispatch briefs), or record as no-action with the regime distinction noted?
4. A1 enforcement locus. Brief-discipline (this Task’s cheap form) vs tool-boundary enforcement (the survey doctrine: truncation receipts at source, “never via agent discipline” — e.g. a wrapped git diff/search CLI emitting receipts + escape hatches). Is a wrapper in ID-92 scope as a stretch slice, a follow-on backlog item, or out? Recommended: discipline now, wrapper as backlog candidate with the gh-axi/gsh shapes cited.
5. B4 — assist artefact + gating. What does the transcript-review subagent return (ranked retro-candidate list with evidence pointers vs a draft retro record), does its output pass through evaluate-findings adjudication before the O-of-O authors (recommended: yes — the existing gate, unchanged), and is a dedicated agent file warranted or does a general-purpose dispatch + brief convention suffice?
6. B4 adjacent — the missing handoff retro step. RESEARCH discovered handoff/SKILL.md lacks the retro-authoring step that evaluate-workflow/evaluate-findings attribute to it. Does PRODUCT fold “write the baseline retro step into handoff” into B4’s invariant set (recommended — same file, same concern), or treat as a separate defect?
7. C1 — decision rule shape. Who decides the chain subset (Orchestrator at Task open, with the Planner able to recommend an upgrade mid-{N.1}?), what are the named tiers (e.g. full chain / PRODUCT+PLAN / TECH-only+PLAN / spec-free), and where is the choice recorded (Task status_note vs the spec dir itself)?
8. B1 residual placement. Does the affirmative carryover convention live in workflow-orchestration (orchestrator-facing) or handoff (session-close-facing), or one line in each pointing at a single canonical statement?

---

§8 Decomposition hint refinement (input to {92.4} PLAN — not the decomposition itself)

The digest’s ~9 atomic candidates hold, with the following research-driven adjustments:

Candidate (digest)	Refinement	Sibling-dep note
A1 brief-convention sweep	Confirmed. Widen file set: dispatch-primitives.md, task-executor.md, task-checker.md (generalise existing --stat discipline), session-driver-cmux fragments. Include the report-to-file-return-path convention (64K cap finding).	Independent
A2i guard metric wiring	Recast as “guard definitions in evaluate-workflow prose now; wiring marker for when 48.23 fields ship” — avoids the forbidden cross-Task Subtask dep (48.23 is pending; ID-92 Task record already rules no blocking). Fold the A1 detection metric (tool-results bytes) and the A3 thrashing flag into this same evaluate-workflow edit to avoid three writers on one file.	Independent under the recast; absorbs metric-definition slices of A1/A3
A2ii orchestration education pass	Confirmed. Cite the axi turn-cost finding + the 400K/0.2 corpus signature.	Independent
A3 flag→fix loop definition	Confirmed, narrowed: the flag moves into the A2i metric subtask; this subtask defines the loop (evaluate-workflow recurring-finding section + workflow-evaluator agent + triage-finding recurrence note + bounded-retry generalisation in failure-modes.md).	Sibling-dep on the A2i subtask only if the loop text references the flag’s metric name; otherwise independent
B1 triage-finding amendment	Confirmed but shrunk (committed-work rule + Session Carry already landed) — one carryover convention paragraph + one failure-mode bullet. Candidate for folding into the B2 handoff/start-session subtask if PLAN prefers fewer records.	Independent
B2 handoff/start-session sandbox carryover	Confirmed.	File-overlap with B3 (start-session) and B4 (handoff) — see below
B3 roadmap read-in	Confirmed; keyed off capability_theme; design choice from OQ-1.	File-overlap with B2
B4 transcript-review retro assist	Confirmed. Include the missing baseline retro step in handoff (per OQ-6). Apply untrusted-text hygiene doctrine.	File-overlap with B2
B5 curator docket convention	Confirmed. Orchestrator must supply the source docket text in the dispatch brief.	Independent
C1+C2 spec-skill right-sizing (one subtask)	Confirmed as one subtask. File set: spec-driven-implementation, task-planner.md, workflow-orchestration lifecycle surfaces. write-product-spec likely droppable from the set (scope rule lives upstream).	Independent

File-overlap advisory for PLAN: B2, B3, B4 collectively touch only two files (start-session/SKILL.md: B2-ingest + B3; handoff/SKILL.md: B2-emit + B4). Either (a) keep the concern-cut (three subtasks) with sibling deps forcing sequential execution, or (b) re-cut by file into two subtasks (“session-open context” = B2-ingest + B3; “session-close emission” = B2-emit + B4 + retro step). Both satisfy sibling-only; (b) yields cleaner file ownership for parallel dispatch. PLAN’s call.

Out of decomposition (route to Curator): bench-harness instrument (§6 #8) and pooled-worktree mechanism (§6 #9) — backlog candidates, not ID-92 subtasks.

No sibling-only violations surfaced. The only cross-Task pull (A2i ↔ 48.23 data layer) is dissolved by the define-now/wire-later recast, consistent with the Task record’s “skill-file subtasks do not block on it”.