PRODUCT — Workflow efficiency hardening: programmatic guards, session-lifecycle habits, spec right-sizing

PRODUCT — Workflow efficiency hardening

• Task: ID-92 — Workflow efficiency hardening — corpus-finding guards, session-lifecycle habits, spec right-sizing
• Subtask: {92.2} PRODUCT
• Authored: 08/06/2026 (untracked workflow-evaluation session)
• Consumes: RESEARCH.md ({92.1}, §1–§8) + adoptability-assessment.md (install-vs-adapt-vs-pattern re-read), same dir. This spec carries the OQ-1..8 resolutions and the adoption dispositions the RESEARCH deferred to PRODUCT.
• Provenance of decisions: product-owner ratification 08/06/2026 (bench-harness / treehouse-binary / no-mistakes → backlog; A1 wrapper → in-scope stretch slice). All other OQ resolutions are RESEARCH-recommended defaults carried here for review.

Summary

ID-92 hardens the agent-SDLC workflow against three classes of inefficiency surfaced by the 7-day corpus investigation (2.716B flat tokens / 19,078 requests) and the product-owner workflow notes: (A) programmatic guards against unbounded tool outputs, orchestrator-as-workhorse drift, and recurring-issue thrash; (B) session-lifecycle habits for roadmap context and retro authoring; (C) spec-chain right-sizing. The “users” of this feature are the SDLC roles — Orchestrator, Executor, Checker, Curator, the workflow-evaluator — plus the session-lifecycle skills (handoff, start-session) and the human contributor. Each guard / convention is consumed as skill-file prose or, for the A1 stretch slice, a CLI emitting truncation receipts.

Problem

The corpus investigation showed the costliest inefficiencies are behavioural, not data-layer: 130 oversized tool results / 17.1MB in 7 days (a single 4.7MB git diff, a 469KB mempalace_search, a 467KB gitnexus detect_changes); 24/460 transcripts above 400K peak context — all 24 orchestrator mains doing executor-grade work inline on the most expensive thread class; and dispatches at >3× their role’s median request count (135 / 127 / 139-request runs) that both consume and cause multi-turn burn. The product-owner notes add session-lifecycle and spec-right-sizing opportunities. The cheap quick-wins already landed ({92.5–92.14}); this spec governs the residual behavioural slices and records the adoption dispositions.

gitnexus orientation (cited from RESEARCH §“Code-intelligence orientation”, same index, 07/06/2026 — not re-run): the ID-92 fix surfaces are overwhelmingly markdown workflow artefacts (.claude/skills/*, .claude/agents/* — out of the code-intel allowlist). The only code-touching surface is lib/workflow-evaluation/token-rollup.ts (patchReportWithRollup / runCli — 1 direct caller, "processes": [], isolated, LOW blast radius); scripts/analyze_claude_session_tokens.py is Python (ast-dataflow does not cover) and is 48.23 scope. The A1 stretch wrapper (§A1.W) is a greenfield CLI surface — no existing symbols match.

Scope

Already landed (reference only — not governed by this spec): A2ii context-economics education ({92.5}); B1 affirmative-carryover convention ({92.6}); B2 sandbox/allowlist carryover ({92.7}); B5 curator-docket convention ({92.8}); C1 PRODUCT/TECH “always→ conditional” language flip ({92.9}); C2 research-scope-widened ({92.10}); using-git- worktrees npm→bun + symlink fix ({92.11}); gh-axi adopt ({92.12}); chrome-devtools-axi adopt ({92.13}); lavish-axi trial ({92.14}).

Governed by this spec (the residual slices → {92.4} PLAN decomposes into implementation Subtasks):

• §A1 — unbounded-output brief conventions + the tool-boundary wrapper stretch slice (W).
• §A2i — guard definitions in evaluate-workflow prose (define-now / wire-later).
• §A3 — recurring-issue thrash flag + resolve-at-source loop.
• §B3 — roadmap context at session start.
• §B4 — fresh-context retro-authoring assist + the missing baseline handoff retro step.
• §C1-T — spec-chain tier formalisation (named tiers / who decides / where recorded — the residual {92.9} explicitly deferred here).

Behavior

Invariants are prefixed by theme so TECH.md / PLAN.md can reference them directly. “The skill states…” means the named .claude/skills/* or .claude/agents/* markdown carries the prose such that an agent consuming it at dispatch time behaves as described.

§A1 — Unbounded tool outputs

A1.1 The dispatch-brief composition convention (workflow-orchestration/references/ dispatch-primitives.md) states a result-size discipline that every code-/diff-/ search-touching brief must carry: prefer --stat-first then targeted expansion; expect hard size bounds on raw dumps; filter-at-source (paginate, scope, name fields) before a tool emits into context.

A1.2 The convention names the specific high-risk tools observed in the corpus and their at-source mitigation: git diff/show → --stat first, then path-scoped or head-bounded hunks; mempalace_search → default (no-wing) query then client-side filter, not broad dumps; gitnexus detect_changes → git diff --name-only as the authoritative scope fallback in worktrees (where the index is “never”); large grep → -l/-c first.

A1.3 The convention states a report-to-file-return-path rule for load-bearing artefacts that can exceed the 64K tool-output cap (two observed cap hits on worker handoff reports): a sub-agent writes the full report to a file and returns the path + a short summary, never the full body inline. Truncation of a load-bearing artefact at the cap is the failure this prevents.

A1.4 task-executor.md carries an output-size discipline line (it currently has none); task-checker.md’s existing per-commit git show --stat mandate is generalised beyond git-diff to the same result-size discipline; session-driver-cmux brief fragments carry the discipline so sub-orchestrator dispatches inherit it.

A1.5 A one-line CLAUDE.md gotcha candidate records the result-size discipline as a standing convention (PLAN decides whether it lands as a gotcha bullet or stays skill-local).

A1.6 None of A1.1–A1.5 introduces a programmatic block — they are conventions (discipline). The durable enforcement is the wrapper (A1.W); until it ships, discipline is the form, and this is stated explicitly so the limitation is known, not hidden.

§A1.W — Tool-boundary output wrapper (stretch slice, in scope)

A1.W.1 A KH-owned CLI wrapper exists over the highest-volume output-emitting commands (at minimum git diff/git show; search is a candidate) that enforces an output budget at the source rather than relying on agent discipline. The wrapper is the durable form of the A1 doctrine (“enforce at source, never via agent discipline”).

A1.W.2 When wrapped output exceeds the budget, the wrapper truncates with a receipt: the emitted text carries a machine-visible marker (truncated: true), the original_length (or byte count), and a ready-to-run escape command (--full or equivalent) that re-emits the untruncated output. The consumer (agent) can always recover the full output in one step; nothing is silently dropped.

A1.W.3 Truncation preserves the diagnostically useful ends: --stat-first for diffs; head+tail (not head-only) for command output where failures appear at the end. A truncated diff still shows the file-level summary; a truncated log still shows the last lines.

A1.W.4 The wrapper degrades safely: if the underlying command fails, the wrapper surfaces the real exit code and stderr (no swallowing); if output is under budget, it passes through unchanged with no marker. The wrapper is opt-in via the brief conventions (A1.1) — it does not silently replace raw git for un-briefed callers.

A1.W.5 The wrapper is a stretch slice: PLAN sequences it after A1.1–A1.5 such that the brief conventions ship even if the wrapper slips. The wrapper’s scope is bounded to the named commands — it is not a general shell-output interceptor (that is the gsh “be the interpreter” model, explicitly out of scope).

§A2i — Guard definitions (define-now / wire-later)

A2i.1 evaluate-workflow/SKILL.md states the definitions of three guards in prose now, each with thresholds and a response protocol, and each explicitly marked “computed once the ID-48.23 per-role fields ship” so the reader knows the metric is defined-but-not-yet-wired:

• Orchestrator-as-workhorse: flag a session where peak_context > 400K AND sub:main flat-token ratio < 0.2. Response: name it as the orchestrate-don’t-implement anti-pattern; route to the workflow-evaluator’s recurring-finding surface.
• Recurring-issue thrash (the A3 flag): flag a dispatch whose request count is > 3× the role median. Response: the resolve-at-source loop (§A3).
• Unbounded-output detection (the A1 metric): flag a session whose tool-results dir bytes exceeds a stated threshold. Response: surface the offending tool + brief for the A1 convention to be tightened.

A2i.2 All three definitions land in one evaluate-workflow/SKILL.md edit (single writer on one file) — the A1 detection-metric and the A3 thrash-flag are folded into this same edit rather than authored by three separate Subtasks.

A2i.3 The wiring (reading the 48.23 per-role/peak/per-dispatch fields and computing the flags) is a later slice, not gated inside ID-92. This dependency on ID-48.23 (still pending) MUST NOT be expressed as a Subtask-level dependency (sibling-only constraint); it is satisfied by the define-now/wire-later split. The Task record already rules “skill-file subtasks do not block on 48.23”.

A2i.4 The guard definitions reference the corpus evidence (the 24/460 >400K-peak finding; the 135/127/139-request thrash instances; the 17.1MB/4.7MB output findings) so a reader understands why each threshold sits where it does.

A2i.5 workflow-evaluator.md (agent doc) is updated in lockstep so the evaluator role knows the three flags exist as report columns once wired — the report-column set is named even while the values read “pending 48.23”.

§A3 — Recurring-issue thrash: resolve-at-source loop

A3.1 evaluate-workflow/SKILL.md’s existing recurring-finding surface (bucket by canonical key, flag count ≥ 3 across distinct sessions) is extended from “surface the pattern” into a four-step resolve-at-source loop: (1) flag → (2) diagnose root cause → (3) fix at the source (skill / brief / gotcha) → (4) verify the recurrence drops in the next sweep. The loop terminates on verified-drop, not on first-flag.

A3.2 triage-finding/SKILL.md gains a recurrence-aware path: a recurrence-class finding is committed work (per the §0 committed-work rule) and routes to the Task List, not the backlog. The decision tree names “is this a recurrence of a prior flagged finding?” as a branch.

A3.3 workflow-orchestration/references/failure-modes.md generalises the existing “3 Checker FAILs → escalate” ceiling into a bounded-retry budget for fix-dispatch loops: a fix-Executor re-dispatch loop has a stated request/iteration ceiling, and on hitting it the loop pauses for human decision rather than thrashing — converting an unbounded >3×-median loop into a structural ceiling-then-pause.

A3.4 The loop does not re-litigate findings already marked ignored/won’t-fix unless materially different (no-mistakes round-history discipline): a recurrence flag fires on genuinely-recurring issues, not on re-surfacing a closed decision.

A3.5 The A3 flag itself lives in the §A2i evaluate-workflow edit (one writer); §A3’s own Subtask defines the loop + routing + budget text. If the loop prose references the flag’s metric name, that is the only sibling-dep between the A3 and A2i Subtasks; otherwise they are independent.

§B3 — Roadmap context at session start

B3.1 start-session/SKILL.md Step 2 reads the roadmap theme that owns the session’s active Task, resolved via the active Task’s capability_theme field — a single owning-theme record (~1–2KB of the 23KB / 12-theme roadmap). (OQ-1 resolution: owning- theme only — token cost is near-free and the read stays drift-resistant as the roadmap grows; the all-titles and full-roadmap options are recorded as rejected alternatives.)

B3.2 The read is strategic context, not a history dump: it surfaces the owning theme’s title + current intent so the session has the “why this Task matters” in-window. It does not pull theme history, prior-session notes, or unrelated themes.

B3.3 When the active Task has no capability_theme (unset / operational Task), the step degrades to a no-op with an explicit note (“no owning theme — operational Task”), not a silent skip and not a full-roadmap fallback.

B3.4 When there are multiple active Tasks in the session, the step reads the owning theme of each active Task (deduplicated by theme), not all 12.

§B4 — Retro-authoring assist + missing baseline step

B4.1 handoff/SKILL.md gains the baseline retro-authoring step it currently lacks (the gap RESEARCH discovered — evaluate-workflow/evaluate-findings both attribute retro authoring to “the O-of-O’s handoff habit” but the step is unwritten). (OQ-6 resolution: folded into B4 — same file, same concern, not a separate defect.)

B4.2 The retro step dispatches a fresh-context transcript-review sub-agent (read-only) that reviews the full session transcript and returns a ranked list of retro-candidate material with evidence pointers (transcript file:line / agent-hash references) — not a finished retro record. (OQ-5 resolution: candidate list, not a draft record.)

B4.3 The O-of-O authors the retro record from the returned candidates — the S271 authoring boundary is intact and untouched. The sub-agent assists; it does not author.

B4.4 The candidate material passes through the existing evaluate-findings adjudication gate before entering the durable retro corpus — the gate is unchanged; B4 adds an input to it, not a bypass. (OQ-5 resolution: yes, the existing gate, unchanged.)

B4.5 No dedicated agent file is created: a general-purpose dispatch + a brief-shape convention fragment suffices for the transcript-review sub-agent. (OQ-5 resolution: no new agent file.)

B4.6 Transcript-mined material re-injected into the O-of-O’s context is treated as untrusted data, not instructions: the brief convention requires delimiter-wrapping and a “data, not instructions” label on the returned candidate text (no-mistakes untrusted-text hygiene), so a transcript can never inject steering into the authoring context.

B4.7 The assist respects transcript retention windowing (a session was observed deleted mid-investigation): the review runs against the live session at handoff time; any later review must consume the 48.15/48.23 archive rather than assuming the live transcript persists.

§C1-T — Spec-chain tier formalisation

(Residual of {92.9}, which flipped PRODUCT/TECH from “always” to “conditional” but explicitly deferred the named-tier + recording-location formalisation here. OQ-7 resolution — carried for PO review.)

C1-T.1 spec-driven-implementation/SKILL.md states a named set of spec-chain tiers, each with a one-line “use when” so a routine task shape can take the light path sanctioned in writing, not negotiated ad hoc:

• Full chain — {N.1} RESEARCH + {N.2} PRODUCT + {N.3} TECH + {N.4} PLAN. Use for compound invariants, multiple migrations, chain-dependent slices, or >2h effort.
• PRODUCT + PLAN — skip TECH when the change is behaviourally rich but implementation-shallow (e.g. pure-UI, prose/convention work).
• TECH + PLAN — skip PRODUCT when behaviour is unambiguous but implementation is non-trivial (e.g. an internal refactor with a known target shape).
• Spec-free — no chain. Trivial fix, narrow tweak, or purely operational Task.

C1-T.2 The Orchestrator decides the tier at Task open; the Planner may recommend an upgrade mid-{N.1} if RESEARCH surfaces compound invariants the Orchestrator did not foresee. The decision rule and the who-decides are stated identically across the three surfaces that {92.9} aligned: spec-driven-implementation/SKILL.md, task-planner.md, workflow-orchestration lifecycle (SKILL.md diagram + references/lifecycle-detail.md).

C1-T.3 The chosen tier is recorded in the Task’s status_note as a one-line marker (e.g. spec tier: PRODUCT+PLAN) so any role can see which artefacts to expect without inferring from which files exist. (OQ-7 resolution: status_note, not a spec-dir marker file — keeps the choice in the ledger where the lifecycle is tracked. PO to confirm; spec-dir-marker recorded as the rejected alternative.)

C1-T.4 The tiers do not erode the heavy path: choosing a light tier is a recorded decision with a stated “use when”, and an under-specified Task that later reveals compound invariants escalates to a heavier tier (recorded as a status_note update), never silently proceeds under-specified.

Adoption dispositions

Disposition of every surveyed tool, ratified 08/06/2026. “Backlog” = recorded as a backlog candidate with the scope noted; the Curator owns the write.

Tool	Disposition	Scope / note
gh-axi	Adopted	{92.12}.
chrome-devtools-axi	Adopted	{92.13}. Sandbox-bypass note (B2 overlap).
lavish-axi	Adopted	{92.14}; PO enabling playbook hooks async. Sub-agent/orchestration test → {92.15} deferred.
using-git-worktrees fix	Done	{92.11} npm→bun + symlink awareness.
axi bench harness	Backlog	Conditions-matrix A/B instrument. High effort; evaluate-workflow retro lane stays the interim observational instrument. Re-promote when a guard needs A/B before standardising.
treehouse binary	Backlog	cmux-lane provisioning rewire + build-cache (.next) in symlinkDirectories/.worktreeinclude. Config-fix already captured most value ({92.11}). Branch-model reconciliation noted.
no-mistakes	Backlog	Scoped to the human-PR pre-PR path only (--skip=ci, lint=bun lint, test=bun run test). Daemon + bare-repo footprint; collides with agent machinery if run whole.
acpx	Watch	PO-ratified PRODUCT/WATCH. Heterogeneous-agent dispatch (codex/gemini/cursor) only; alpha — pin + thin adapter. Re-evaluate when upstream drops the alpha notice and KH needs non-Claude dispatch. Collapses to pattern-only if never needed.
axi SDK / gsh / acp-mock	No action	Pattern-only; structural blockers named in adoptability §(iii).

Open questions — resolution table

OQ	Topic	Resolution
OQ-1	B3 roadmap scope	Owning-theme only via capability_theme (B3.1).
OQ-2	A2i def vs wiring	Define-now / wire-later; one evaluate-workflow writer (A2i.1–A2i.3).
OQ-3	ToolSearch deferral	No-action — keep deferral. Regime distinction: the bench found lazy loading net-negative when most tools are used; KH defers a large mostly-unused MCP set (coolify/supabase/mempalace), a different regime where deferral still wins. Briefs may name a per-role core set for eager loading, but no programmatic change is in ID-92 scope. (Cannot A/B this now — bench harness → backlog.)
OQ-4	A1 enforcement locus	Discipline now + wrapper in-scope as stretch slice (§A1 + §A1.W).
OQ-5	B4 assist + gating	Candidate list (not draft); through evaluate-findings gate; general-purpose dispatch, no new agent file (B4.2–B4.5).
OQ-6	Missing handoff retro step	Folded into B4 (B4.1).
OQ-7	C1 tier shape	Named tiers; Orchestrator decides at Task-open, Planner may recommend upgrade; recorded in status_note (§C1-T). PO to confirm recording location.
OQ-8	B1 placement	Closed by {92.6} (workflow-orchestration carryover para + triage-finding failure-mode item 9).

Decomposition note (input to {92.3} TECH / {92.4} PLAN)

This Task itself takes the PRODUCT + (TECH) + PLAN tier: RESEARCH done, PRODUCT here. Whether {92.3} TECH is warranted is a Planner call — the slices are markdown-convention edits plus one greenfield CLI (the A1.W wrapper), which is the one slice that genuinely benefits from a TECH pass (CLI surface, receipt format, command scope). Candidate implementation Subtasks map ~1:1 to the Behavior themes:

• A1 brief-convention sweep (A1.1–A1.5) — dispatch-primitives.md, task-executor.md, task-checker.md, session-driver-cmux fragments. Independent.
• A1.W wrapper (A1.W.1–A1.W.5) — greenfield CLI; TECH-worthy; sequenced after A1.
• A2i guard definitions (A2i.1–A2i.5) — one evaluate-workflow/SKILL.md writer + workflow-evaluator.md; absorbs the A1-metric + A3-flag definitions.
• A3 loop + routing + budget (A3.1–A3.5) — evaluate-workflow, triage-finding, failure-modes.md. Sibling-dep on A2i only if it references the flag metric name.
• B3 roadmap read-in (B3.1–B3.4) — start-session/SKILL.md.
• B4 retro assist + baseline step (B4.1–B4.7) — handoff/SKILL.md + brief fragment.
• C1-T tier formalisation (C1-T.1–C1-T.4) — spec-driven-implementation, task-planner.md, workflow-orchestration lifecycle surfaces.

File-overlap advisory (carried from RESEARCH §8): B3 + B4 touch start-session/handoff respectively — no overlap with each other now that B2 has landed. Sibling-only constraint: the A2i↔48.23 data dependency is dissolved by define-now/ wire-later; no cross-Task Subtask dep is expressed. ID-90 ledger churn / ID-68.28 corpus relocation: A3 (triage-finding/workflow-orchestration) and A2i (evaluate-workflow corpus paths) edits must not add new hard-coded ledger-cli.ts examples or re-introduce in-repo docs/workflow-evaluation/ paths — treat the private-docs path as canonical (RESEARCH §5).