PLAN — Workflow efficiency hardening: thin decomposition of the residual implementation slices

PLAN — Workflow efficiency hardening

• Task: ID-92 — Workflow efficiency hardening — corpus-finding guards, session-lifecycle habits, spec right-sizing
• Subtask: {92.4} PLAN
• Authored: 11/06/2026 (S341) — FRESH Planner instance, distinct from the {92.3} TECH author (Q-PLANNER-2 fresh-per-Subtask discipline)
• Consumes (contract): PRODUCT.md ({92.2}) numbered invariants (§A1, §A1.W, §A2i, §A3, §B3, §B4, §C1-T) + TECH.md ({92.3}) one-to-one Proposed-changes mapping + the net-new §LP clash-free ledger-write hardening. Both read in full.
• Reference inputs: RESEARCH.md ({92.1}, §5 reroute / private-docs canonicality + §8 file-overlap advisory), adoptability-assessment.md, same dir.

Decomposition decision — THIN (real, flat) decomposition

Decision: a REAL but THIN decomposition — a flat list of 8 implementation Subtasks ({92.16}–{92.23}), sibling-only deps, no sub-phases beyond the two sequencing edges TECH mandates. NOT folded into TECH; NOT a heavy phased plan.

Heuristic applied (ID-92’s own {92.9} spec-chain right-sizing, turned on the PLAN tier itself)

{92.9} established that the spec chain is right-sized to the task shape, and {92.4} PLAN is itself subject to that discipline. Three tiers were available: fold-into-TECH (PLAN.md is just a justification, no Subtask list); thin (flat Subtask list, sibling-only deps); heavy (phased plan with checkpoints, chain-dependent slices). The residual work lands on thin, and here is the defence:

Why not fold-into-TECH. Folding is correct only when the residual is genuinely single-slice (one file-ownership boundary, ≤2h, no cross-cutting structure). This residual is not: it spans two repositories — the public KH worktree (§A1, §A1.W, §A3 loop/budget, §B3, §C1-T, §LP) and the private knowledge-hub-docs-site .claude/ checkout (§A2i evaluate-workflow/SKILL.md + workflow-evaluator.md; §B4’s evaluate-findings gate reference) — touches ~15 distinct files, and carries one greenfield code surface (§A1.W CLI, with its own bun run test contract) plus one code-shell surface (§LP worktree-pre-commit.sh guard). Folding would force every Executor to re-derive the cross-repo file-ownership split and the two sequencing edges from prose. The file-ownership boundary alone is load-bearing enough to warrant explicit Subtask records.

Why not heavy. TECH ({92.3}) has already done the per-invariant Proposed-changes mapping and named every file, edit shape, and constraint. The slices are largely file-disjoint and low-interdependency (confirmed by the file-existence sweep below: the only file two themes share is evaluate-workflow/SKILL.md, which TECH’s A2i.2 single-writer rule deliberately collapses into one Subtask). There are exactly two real sequencing edges (A1.W-after-A1; §LP-guard-before-next-wave) and at most one optional sibling-dep (A3→A2i, iff the loop prose names the flag metric). A heavy phased plan with inter-phase checkpoints would manufacture structure the work does not have. The decomposition’s job is therefore to draw clean file-ownership boundaries and encode the two sequencing edges — not to re-specify behaviour TECH already pinned.

Net: 8 Subtasks, flat, sibling-only. Slice-count 8 sits far under the 25-Subtask soft ceiling; independence is high; per-Subtask effort is S–M (markdown-convention edits are S; the §A1.W CLI is the lone M with a real test suite). This is the thin tier by every measure {92.9} names.

Empirical grounding performed before authoring (code-intel orientation + anchor verification)

Mandatory code-intel orientation (cited, not paraphrased) and load-bearing-claim verification, S341, 11/06/2026:

• §A1.W greenfield — CONFIRMED. scripts/kh-output-budget.ts is ABSENT (ls no-such-file). Fresh gitnexus_query({query: "tool output truncation wrapper git diff stat byte budget receipt escape command", repo: "knowledge-hub"}) returned "processes": [] — zero output-budget/truncation-wrapper execution flow. The only truncate/budget symbols in the definition set are embedding-input truncation (scripts/cocoindex_pipeline/flow.py:_truncate_embedding_input) and a test budget helper — a different domain, exactly as TECH cited. No git diff/git show output wrapper, no truncated: true emitter, no --full escape surface exists. §A1.W is greenfield.
• §LP worktree-pre-commit.sh install path — VERIFIED. The hook exists (.claude/skills/session-driver-cmux/scripts/worktree-pre-commit.sh, 2086 bytes, prettier-only) and is copied into every worker worktree’s hooks dir by launch-worker.sh (cp "$HOOK_SOURCE" "${WORKTREE_HOOKS_DIR}/pre-commit"; chmod +x, lines 362/372–373 — verified verbatim). LOW blast radius; no new install plumbing.
• §A1.W prior art — VERIFIED. read-turn.sh carries the truncate-default/--full-recover shape (--full flag line 25, trunc() jq line 114, “first 5 lines” default line 21/109).
• A3/A1.4 existing-surface anchors — VERIFIED. evaluate-workflow/SKILL.md recurring-finding surface (≥3 distinct sessions, canonical-key bucketing, line 118+); failure-modes.md “Checker FAILs three times” ceiling (line 22); task-checker.md per-commit git show --stat mandate (lines 72/77); task-executor.md has no output-size discipline line (A1.4 gap confirmed — grep returned nothing).
• REPO-SPLIT — load-bearing finding (drives the two-repo file-ownership boundary). evaluate-workflow/SKILL.md, evaluate-findings/SKILL.md, and workflow-evaluator.md are NOT in the public KH repo — they live in the private knowledge-hub-docs-site repo’s .claude/ (/Users/liamj/Documents/development/knowledge-hub-docs-site/.claude/skills/evaluate-workflow/SKILL.md
  • .../.claude/agents/workflow-evaluator.md). TECH’s §A2i/§A3-flag/§B4-gate file paths are therefore relative to the docs-site checkout, not the KH worktree. This is the half-done ID-68.28 relocation PRODUCT/TECH flagged. The §A2i Subtask ({92.18}) and the §A2i-naming portion of §B4 edit a different repository than the §A1/§A1.W/§A3-loop/§B3/ §C1-T/§LP Subtasks; their details name the docs-site checkout explicitly.

Subtask records (TM-shape — RETURNED to the Orchestrator, NOT written by the Planner)

Per the §LP protocol this Task hardens, the Planner does not write these into docs/reference/task-list.json. They are returned as ledger-write intents; the Orchestrator applies each via bun scripts/ledger-cli.ts on the MAIN checkout under the single daemon mutex. IDs start at {92.16} ({92.5}–{92.14} DONE, {92.15} DEFERRED).

Slice map → Subtask

Subtask	Theme	Repo	Shape	Depends on
{92.16}	§A1 brief-convention sweep (A1.1–A1.6)	KH	convention	—
{92.17}	§A1.W output-budget wrapper CLI (A1.W.1–A1.W.5)	KH	CLI (greenfield, code-intel)	{92.16}
{92.18}	§A2i guard definitions + A1-metric + A3-flag + evaluator lockstep (A2i.1–A2i.5)	docs-site	convention	—
{92.19}	§A3 resolve-at-source loop + routing + retry-budget (A3.1–A3.5)	KH + docs-site	convention	{92.18} (only if loop prose names the A2i flag metric)
{92.20}	§B3 roadmap-context-at-session-start (B3.1–B3.4)	KH	convention	—
{92.21}	§B4 retro-authoring assist + baseline handoff step (B4.1–B4.7)	KH	convention	—
{92.22}	§C1-T spec-chain tier formalisation (C1-T.1–C1-T.4)	KH	convention	—
{92.23}	§LP clash-free ledger-write protocol — prose surfaces + guard + return-intent contract	KH	convention + code-shell	—

Sequencing edges (the only two TECH mandates)

1. {92.17} after {92.16} (A1.W.5): the brief-convention sweep ships first; the wrapper is the stretch slice sequenced after, so conventions land even if the wrapper slips.
2. {92.23} (§LP guard) before the next wave’s worker launches (TECH §4 rollout caveat): editing worktree-pre-commit.sh affects future worktrees only (per-worktree hook copy at launch); live worktrees keep their installed copy. This is an Orchestrator dispatch-ordering note, not a Subtask-level dependency — {92.23} has no sibling-dep.

Sibling-only verification

All dependencies reference only other {92.x} Subtasks. No cross-Task Subtask dep is expressed. Per A2i.3, the ID-48.23 per-role-field dependency is DISSOLVED by the define-now/wire-later split and MUST NOT appear; it does not. The §A1.W-after-§A1 edge and the optional §A3→§A2i edge are both intra-Task sibling deps. The §LP-before-next-wave edge is dispatch ordering, held at the Orchestrator level, not a Subtask dep.

Slice-by-slice notes (the load-bearing details rationale)

• {92.16} §A1 sweep — KH repo. Owns dispatch-primitives.md (A1.1–A1.3 + the A1.6 “convention-not-block” statement), task-executor.md (A1.4a — new output-size line), task-checker.md (A1.4b — generalise the existing git show --stat mandate beyond git-diff), session-driver-cmux/SKILL.md brief fragments (A1.4c). A1.5 CLAUDE.md-gotcha decision is made here: PLAN rules it lands as a one-line gotcha under Gotchas → General (not skill-local) — the result-size discipline is a standing cross-role convention exactly like the existing worktree-isolation gotchas, so gotcha-visibility is warranted; the bullet adds no new ledger-cli.ts invocation example (RESEARCH §5 clean).
• {92.17} §A1.W CLI — KH repo, the one greenfield code surface, carries the code-intel discipline. New file scripts/kh-output-budget.ts; tests under __tests__/. Full design in TECH §A1.W (command surface, receipt contract, truncation shape, degrade-safe). bun run test (not bun test); behaviour-not-implementation per test-philosophy.md. Sequenced after {92.16}.
• {92.18} §A2i — docs-site repo. Single writer on evaluate-workflow/SKILL.md (A2i.1–A2i.4: the three guard definitions — orchestrator-as- workhorse, A3 thrash-flag, A1 unbounded-output metric — each marked “computed once ID-48.23 per-role fields ship”, each citing corpus evidence) plus workflow-evaluator.md lockstep (A2i.5 — name the three report columns). Two files, one Subtask (TECH’s recommendation: the column-naming must match the definitions exactly). Treat the private-docs path as canonical; do not re-introduce in-repo docs/workflow-evaluation/ paths.
• {92.19} §A3 — spans KH (triage-finding/SKILL.md A3.2 recurrence-aware path; failure-modes.md A3.3/A3.4 bounded-retry budget) and docs-site (evaluate-workflow/SKILL.md A3.1 four-step loop — same file {92.18} owns the flag, but the loop text is A3’s). The A2i.2 single-writer rule means {92.18} owns the flag definition; {92.19} owns the loop/routing/budget text. Sibling-dep {92.19}→{92.18} iff the A3 loop prose references the A2i flag metric name — Executor expresses it only if the reference is actually made. Do not add new hard-coded ledger-cli.ts invocation examples (RESEARCH §5; {90.23} re-points these).
• {92.20} §B3 — KH repo, start-session/SKILL.md Step 2 only. Disjoint from {92.21}.
• {92.21} §B4 — KH repo, handoff/SKILL.md + a brief-fragment convention. Disjoint from {92.20} (B2’s session-carry already landed). References docs-site evaluate-findings as the unchanged adjudication gate (a reference, not an edit — no docs-site write here).
• {92.22} §C1-T — KH repo, three aligned surfaces: spec-driven-implementation/SKILL.md, task-planner.md, workflow-orchestration/SKILL.md + references/lifecycle-detail.md. write-product-spec is droppable from the set (RESEARCH §8). Checker non-blocking note (i): the C1-T.3 edit must make the status_note ≤300-char budget gate (invariant 57) prominent — the spec tier: … marker is appended to status_note and is rejected server-side if over budget.
• {92.23} §LP — KH repo. Three separable parts, TECH §LP: (a) prose surfaces — task-executor.md (NEW worker-obligation statement), workflow-orchestration/SKILL.md (consolidate the 408–421 note as canonical orchestrator-obligation home), session-driver- cmux/SKILL.md (186–202 becomes a cross-reference), CLAUDE.md gotcha (one bullet); (b) code-shell guard — prepend the ledger-block to worktree-pre-commit.sh (touches a .sh); (c) return-intent contract — the final_report.yaml ledger_intents shape (convention attached to the prose). Prose ⟂ guard are independent; PLAN keeps them in one Subtask for cohesion (single §LP owner) but the Executor may slice prose-first/guard-second internally. OQ-T1 (§LP→PRODUCT back-port) is an Orchestrator/PO call — this slice MUST NOT block on it (surfaced below).

Checker gate on PLAN

A Checker gate on {92.4} PLAN IS warranted — a real (thin) decomposition was produced, not a fold. The Checker should verify: (1) sibling-only deps (no cross-Task, no 48.23 dep); (2) the two-repo file-ownership boundary is correctly drawn (docs-site vs KH); (3) the two sequencing edges are encoded; (4) every Subtask description ≤250 / testStrategy ≤300 (budget gate, authored within-budget first-pass per S281); (5) the §A1.W code-intel slice and §LP code-shell slice are correctly flagged as the non-convention surfaces.

Open questions (carried forward for Orchestrator/PO)

OQ	Topic	Disposition
OQ-T1	§LP → PRODUCT back-port	Carried from TECH OQ-T1 — Orchestrator/PO call. TECH recommends YES (add a numbered carryover-discipline invariant, e.g. §B6 “ledger-write ownership”, so §LP has a PRODUCT contract the Checker verifies against). PLAN concurs the protocol is testable behaviour (worker commit of a ledger file is blocked; intent round-trips through final_report.yaml). {92.23} implementation MUST NOT block on this — the §LP slice ships against TECH §LP as the contract; a later PRODUCT back-port (if PO approves) is a separate, non-blocking ledger edit. Planner recommends; does not edit PRODUCT.
OQ-T2	C1-T.3 recording location	Carried from PRODUCT OQ-7 / TECH OQ-T2: status_note (chosen) vs spec-dir marker (rejected). PO to confirm. {92.22} proceeds on status_note per OQ-7; flagged so the Checker knows it is PO-pending, not Planner-invented.
REPO-SPLIT	docs-site .claude/ ownership of §A2i/§A3-flag	Surfaced for Orchestrator dispatch planning (not a blocker): {92.18} and the §A3.1 loop-text portion of {92.19} edit the private docs-site .claude/, a different repo/worktree than the KH-repo Subtasks. The Orchestrator must dispatch those Executors against the docs-site checkout, and route their commits there (the docs-site repo has its own git history). Not an ambiguity in the spec — a dispatch-target fact the decomposition surfaces.