tieubao · Sep 16, 2026 · Sep 16, 2026 · Sep 16, 2026 · Sep 16, 2026 · Sep 16, 2026
diff --git a/_meta/BACKLOG.md b/_meta/BACKLOG.md
@@ -37,7 +37,7 @@ Lane = the WORKFLOW.md risk tier (`tiny` / `normal` / `full`).
 |----|-------|--------|-----------------|------|--------|
 | ID-883 | Blocking quality gates opt-out per project: `[gate]` block in kit.toml, one reader in lib/gate/gate-policy.sh, hooks call it #gate #config #adopt | Han 2026-09-16: members adopting the kit did not want the proof-of-done gate; adopt always wrote the marker, so for adopters the gate was mandatory. Keys: proof_of_done, lane_gates, understanding_gate, commit_format; a project .kit.toml or the operator overlay sets one to false and the hook passes from the next fire, logging OFF-BY-CONFIG. Safety gates have no key. The classifier treats .kit.toml as inert so the flip itself owes no proof. Proof: docs/verification/gate-opt-out.md. Follow-up the same day (Han: make them default opt-in with the preset in the config file): the four keys default false, adopt seeds the block with resolved values and per-key comments, install prints the how-to; the operator overlay on Han's machines turns them on (dotfiles feat/kit-gates-on). Proof: docs/verification/gate-opt-in.md | lib/gate/gate-policy.sh, hooks/ship-gate.sh, hooks/anti-rationalization.sh, hooks/commit-format.sh, kit.toml [gate], lib/adopt.sh seed, tests/test-gate-opt-out.sh | normal | shipped feat/gate-opt-out |
 | ID-881 | bin/wrap merge retries transient GitHub failures #wrap #resilience | bin/wrap merge has no retry for a transient GitHub failure (502/503/GraphQL executing-query errors); a real refusal (not mergeable, not green, conflict, draft) must still fail immediately. Operator hand-rolled 3 shell retry loops for ~25 PR merges during a ~90min GitHub outage. Same failure class as memory note hand-rolled-merge-loop-instead-of-wrap-merge.md, a second occurrence, missing retry is the root cause. cmd_merge in lib/wrap/wrap.sh (~line 812, gh pr merge call ~line 917). lane=full. Source: board sweep session 2026-09-13 and 14. Goal draft: .claude/goals/wrap-merge-retry.md in the kit clone. | queued |
-| ID-879 | wrap step 6 and the ledger flush must not commit on the checked-out default branch #wrap #ledger | Sessions commit LAB_LOG lines, ledger flushes and board rows straight onto local main because those writes land in the main checkout; main cannot be pushed, so 29 such commits plus 61 merge commits piled up on one Air by 2026-09-14 (ops-toolkit #2779 drained them). Wrap step 6, the learning-ledger flush and board capture should write on a housekeeping branch or leave the file uncommitted for the next feature PR. Companion guards: ops-toolkit pre-commit refuses commits on main; dotfiles sets pull.ff=only. Source: ops-toolkit session 2026-09-14. | queued |
+| ID-879 | wrap step 6 and the ledger flush must not commit on the checked-out default branch #wrap #ledger | Sessions commit LAB_LOG lines, ledger flushes and board rows straight onto local main because those writes land in the main checkout; main cannot be pushed, so 29 such commits plus 61 merge commits piled up on one Air by 2026-09-14 (ops-toolkit #2779 drained them). Wrap step 6, the learning-ledger flush and board capture should write on a housekeeping branch or leave the file uncommitted for the next feature PR. Companion guards: ops-toolkit pre-commit refuses commits on main; dotfiles sets pull.ff=only. Source: ops-toolkit session 2026-09-14. | shipped [SPEC-291, proof docs/verification/no-default-branch-commit.md] |
 | ID-882 | Dispatch keeps an Attempt state apart from the Task state: a dead or disconnected subagent is an unknown outcome, a grace window precedes LOST, and a result arriving inside the window commits with no second dispatch #kit #dispatch #u-mid #f-mid | Formalises the incident lesson resume-a-dead-subagent-never-respawn-on-its-branch. Shape from VoiceStudio backend/worker/lifecycle.py: TaskState and AttemptState enums with a legal-transition table, mark_disconnected starts grace, lose_attempt on expiry frees the task and excludes that worker, commit_result idempotent on task id so a resumed agent and its replacement cannot both land. Applies to kit:execute retries and megagoal-agent-drive. Contract tests named in ops-toolkit research/2026-09-14-voicestudio-long-running-orchestration.md | shipped [SPEC-290, proof docs/verification/dispatch-attempt-state.md] |
 | ID-878 | session observe: a view that sizes the fixed context entry fee per turn #harness #kit #observability | Every agent turn re-reads a fixed preamble (skills, CLAUDE.md stack, repo memory index, agent roster) before any work. Measured by hand 2026-09-13 at ~96k tokens, about 38% of a 400-turn builder's whole bill. session observe already owns cost and burn over the same transcripts, so the entry-fee view belongs beside them rather than as a sibling script. Wants: per-component breakdown, a trend so ID-902..906 progress is visible, and a per-repo figure since the memory index and CLAUDE.md differ per checkout. lane=full. Source: ops-toolkit research/2026-09-13-token-burn-optimization.md | shipped [SPEC-289, proof lib/session/observe/docs/proof-of-done.md] |
 | ID-877 | gate-ledger: record a whole lane plan in one call #kit #gate | Intent: one verb that takes a rid, a lane, and per-phase dispositions (ran, skipped, override, each with its reason) and writes every GATE line the ship-gate wants, instead of nine hand-typed record/override calls per prose-only PR. Precedent: nothing matched (bin/precedent, 2026-09-13). lane=full (touches lib/gate). Source: the skill-trigger-routing wrap. Goal draft: .claude/goals/gate-ledger-plan-record.md in the kit clone. | shipped [SPEC-287, proof docs/verification/gate-ledger-plan-record.md] |

diff --git a/commands/wrap.md b/commands/wrap.md
@@ -38,7 +38,7 @@ kit_config_get_root wrap.after ""
 
 An empty value means no skill runs on that side, which is the default for both. A named skill runs at its side's position and its report lines fold into step 9's report after the `FYI` line. Both keys resolve with `kit_config_get_root`, so each comes from the operator `kit.toml` or the kit-root `kit.toml` and never from a project `.kit.toml`: they name code this command runs, and a project toml rides inside an untrusted PR.
 
-**Pick the side by what the skill needs.** `wrap.before` runs ahead of step 0, so it sees the session's uncommitted state; a skill that must read a working tree before wrap commits or tidies it belongs there. `wrap.after` runs after step 8 and before the step 9 report, so the landing is already done; a skill that only reads what the session produced belongs there. **`after` is the right side for a knowledge flush**, and the reason is the operator's time: a flush on the `before` side greps every note store while the git work waits behind it, so the landing an operator asked for arrives last. Nothing in a flush informs a board flip or a merge, so nothing is gained by paying for it first.
+**Pick the side by what the skill needs.** `wrap.before` runs ahead of step 0, so it sees the session's uncommitted state; a skill that must read a working tree before wrap commits or tidies it belongs there. `wrap.after` runs after step 8 and before the step 9 report, so the landing is already done; a skill that only reads what the session produced belongs there. **`after` is the right side for a knowledge flush**, and the reason is the operator's time: a flush on the `before` side greps every note store while the git work waits behind it, so the landing an operator asked for arrives last. Nothing in a flush informs a board flip or a merge, so nothing is gained by paying for it first. A seam skill that writes a file into a repo obeys step 2's rule: no commit on a checkout sitting on the default branch, leave the write for the next feature PR.
 
 **Report the outcome, whichever side ran.** Step 9 owes a `**Seam:**` line and the lint fails without it. A seam that never ran because no key was set, and a seam that was silently skipped, are different facts; the `**Built:**` line exists for exactly this reason at step 7b, and the same hole is here. A named skill that fails to run is `SKIPPED: <why>`, never silence.
 
@@ -72,6 +72,8 @@ For every backlog row whose source of truth this session closed, flip it through
 
 Commit any of the operator's own outstanding work under its own name and message. This step is a command-layer judgment call, not a verb: `wrap` owns no commit write. Skip it when nothing of the operator's own is outstanding.
 
+**Never commit on a checkout that has the repo's default branch checked out.** Nobody can push that commit through a PR, so it sits on a local main until someone drains it by hand; one measured machine had accumulated 29 such commits. Leave the file uncommitted for the next feature PR to carry, or move the change onto a branch and commit it there. The same rule binds every file the pass writes: a board row at step 1, an activity line at step 6, anything a seam skill flushes. `board set`, `wrap log` and `wrap stage` each print one warning line when they write into such a checkout; that line is this rule firing, not an error, and the file they wrote is correct.
+
 ### Step 3: merge the operator's own PRs
 
 `wrap.merge_own_prs` false: merge nothing, report every own open PR as `OPEN` under `Shipped`, and say in `FYI` that the knob is off. Steps 4 onward still run.
@@ -104,7 +106,7 @@ Re-run the step 0 check first. Then, in this order: remove the session's own wor
 
 ### Step 6: activity line
 
-Re-run the step 0 check first. Then: `bin/wrap log "<slug>: <one sentence>"`. When the current directory is a git worktree of the repo that holds the configured file, the same repo-relative file inside that worktree is written instead, so the line is committable on the session's branch; the main checkout's copy is left alone. With no `wrap.activity_log` key in the kit-root `kit.toml`, it prints the line and says where it did not land; that is a clean result, not a failure.
+Re-run the step 0 check first. Then: `bin/wrap log "<slug>: <one sentence>"`. When the current directory is a git worktree of the repo that holds the configured file, the same repo-relative file inside that worktree is written instead, so the line is committable on the session's branch; the main checkout's copy is left alone. With no `wrap.activity_log` key in the kit-root `kit.toml`, it prints the line and says where it did not land; that is a clean result, not a failure. When the written file lands in a checkout sitting on the repo's default branch, the verb says so on stderr: leave the line uncommitted for the next feature PR, per step 2.
 
 ### Step 7: understand
 

diff --git a/docs/FEATURES.md b/docs/FEATURES.md
@@ -20,7 +20,7 @@ GENERATED , do not hand-edit. Regenerate: `bash lib/registry/feature-registry.sh
 | `/kit:design` | `[H/I]` | Opt-in interactive solution-design beat between /think and /spec. Explores 2-3 approaches one question at a time, holds for your approval p… | SPEC-003, SPEC-004, SPEC-005 +105 | test-command-emit-sweep.sh, test-command-triggers.sh, test-design-record.sh +21 |
 | `/kit:devs-team` | `[H/I]` | Parallel multi-lens critique of a solution design (the active spec if present, else the decision brief). Dispatches 5 engineering lenses, m… | SPEC-016, SPEC-018, SPEC-019 +11 | test-gate-vocab-recording.sh, test-meta.sh, test-outcome-emit-sweep.sh |
 | `/kit:dispatch` | `[H/I]` | Fire several disjoint VALIDATED specs concurrently, each in its own worktree, then converge. Cross-goal fan-out behind a disjointness gate … | SPEC-002, SPEC-016, SPEC-017 +79 | test-advisor-ledger-emit.sh, test-agent-effectiveness.sh, test-attempt-state.sh +31 |
-| `/kit:docs` | `[H/I]` | Update all project documentation to match the current codebase. Cross-references the diff against every doc file and fixes drift. | SPEC-001, SPEC-002, SPEC-003 +192 | proof-loop-09-scenario-b.sh, run-all.sh, run-workflow.sh +69 |
+| `/kit:docs` | `[H/I]` | Update all project documentation to match the current codebase. Cross-references the diff against every doc file and fixes drift. | SPEC-001, SPEC-002, SPEC-003 +193 | proof-loop-09-scenario-b.sh, run-all.sh, run-workflow.sh +69 |
 | `/kit:draft-agent` | `[H/I]` | Meta-agent agent-builder. From a one-line description, generates a new subagent definition OR a mega-goal sub-goal file and (by default) in… | SPEC-089, SPEC-108, SPEC-139 +1 | test-agent-effectiveness.sh, test-command-emit-sweep.sh, test-meta-agent.sh +1 |
 | `/kit:execute` | `[H/I]` | Autonomous spec execution with verification. Dispatches worker subagents per task, verifies each with task-verifier, retries fixable failur… | SPEC-001, SPEC-003, SPEC-004 +60 | test-break-it.sh, test-gate-vocab-recording.sh, test-hooks.sh +9 |
 | `/kit:explain` | `[H/I]` | Turn a merged change into a literate-diff explainer a human READS to understand: background -> goal + intuition -> a prose-ordered diff -> … | SPEC-050, SPEC-060, SPEC-094 +18 | proof-loop-09-scenario-b.sh, test-boundary-lint.sh, test-command-emit-sweep.sh +11 |
@@ -30,7 +30,7 @@ GENERATED , do not hand-edit. Regenerate: `bash lib/registry/feature-registry.sh
 | `/kit:grill` | `[H/I]` | Universal intake interview: one type-shaped question at a time, each with a recommended answer, until the task is actually understood. Answ… | SPEC-058, SPEC-059, SPEC-063 +21 | test-config-stamp.sh, test-e2e.sh, test-gate-ledger-plan-record.sh +8 |
 | `/kit:kit-health` | `[H/I]` | Run a self-assessment of the kit against its own philosophy. Checks file count, hook performance, source citations, and structural health. | SPEC-001, SPEC-002, SPEC-004 +16 | test-command-emit-sweep.sh, test-meta.sh |
 | `/kit:mega` | `[H/I]` | Turn a multi-objective destination into a sequenced roadmap of dependent sub-goals: decompose, front-load every clarification once, set the… | SPEC-034, SPEC-036, SPEC-088 +34 | proof-loop-09-scenario-b.sh, test-advisor-ledger-emit.sh, test-bin-forwarders.sh +23 |
-| `/kit:next` | `[H/I]` | Pick up the next undone task from the spec. Loads context, shows acceptance criteria, lets you drive the implementation. | SPEC-001, SPEC-002, SPEC-003 +86 | run-all.sh, test-advisor-ledger-emit.sh, test-advisor.sh +34 |
+| `/kit:next` | `[H/I]` | Pick up the next undone task from the spec. Loads context, shows acceptance criteria, lets you drive the implementation. | SPEC-001, SPEC-002, SPEC-003 +87 | run-all.sh, test-advisor-ledger-emit.sh, test-advisor.sh +34 |
 | `/kit:onboard` | `[H/I]` | Guided first-run: detect the install mode, offer /kit:adopt for this repo, pick modules, capture the consumer knobs that make them work, di… | SPEC-199, SPEC-213, SPEC-232 +1 | proof-loop-09-scenario-b.sh, test-command-emit-sweep.sh, test-onboard-detect.sh |
 | `/kit:pitch` | `[H/I]` | Assemble an outward buy-in doc from what a gated run already produced: the spec, the proof-of-done, the implementation-notes, and the gate … | SPEC-140, SPEC-141, SPEC-193 +1 | test-outcome-emit-sweep.sh, test-pitch.sh |
 | `/kit:prototype` | `[H/I]` | Opt-in throwaway-spike beat beside /kit:design. Builds throwaway code that answers ONE design question: a logic/state model driven by hand … | SPEC-075, SPEC-206, SPEC-207 +2 | test-picture-section.sh |
@@ -40,7 +40,7 @@ GENERATED , do not hand-edit. Regenerate: `bash lib/registry/feature-registry.sh
 | `/kit:review` | `[H/I]` | Paranoid code review. Security, architecture, regressions, missing tests, edge cases. Produces actionable TODOS. | SPEC-001, SPEC-002, SPEC-003 +102 | test-adopt.sh, test-advisor-ledger-emit.sh, test-agent-effectiveness.sh +42 |
 | `/kit:ship` | `[H/I]` | Ship: review gate, tests, version bump, changelog, conventional commit, docs update, PR. Complete pipeline from done to merged. | SPEC-001, SPEC-002, SPEC-003 +77 | test-adopt.sh, test-board-mirror.sh, test-cheap-guards.sh +28 |
 | `/kit:spec-validate` | `[H/I]` | Adversarial review of a spec before implementation. 6 specialist lenses attack the spec from different angles (5 advisory, 1 blocking on th… | SPEC-002, SPEC-003, SPEC-004 +58 | test-command-emit-sweep.sh, test-design-record.sh, test-every-step-review.sh +8 |
-| `/kit:spec` | `[H/I]` | Generate a development spec from a feature idea or decision brief. Creates docs/specs/ with structured requirements. | SPEC-001, SPEC-002, SPEC-003 +163 | test-bin-forwarders.sh, test-break-it.sh, test-codex-hooks.sh +47 |
+| `/kit:spec` | `[H/I]` | Generate a development spec from a feature idea or decision brief. Creates docs/specs/ with structured requirements. | SPEC-001, SPEC-002, SPEC-003 +164 | test-bin-forwarders.sh, test-break-it.sh, test-codex-hooks.sh +47 |
 | `/kit:start` | `[H/I]` | Detect project state and suggest the right next command. The entry point for any session. | SPEC-002, SPEC-003, SPEC-004 +42 | test-command-emit-sweep.sh, test-config-stamp.sh, test-e2e.sh +30 |
 | `/kit:test-plan-review-team` | `[H/I]` | Parallel multi-lens adversarial critique of a spec's test plan (the ## Test plan section), with a bounded revise loop that tightens it. Dis… | SPEC-031, SPEC-052, SPEC-062 +10 | test-meta.sh, test-outcome-emit-sweep.sh |
 | `/kit:test-plan` | `[H/I]` | Derive a test-case coverage matrix from a spec's acceptance criteria before /kit:execute. Writes a `## Test plan` section into the active s… | SPEC-004, SPEC-016, SPEC-018 +27 | test-e2e.sh, test-gate-ledger-plan-record.sh, test-gate-vocab-recording.sh +5 |
@@ -50,7 +50,7 @@ GENERATED , do not hand-edit. Regenerate: `bash lib/registry/feature-registry.sh
 | `/kit:verify` | `[H/I]` | Re-run the test levels (task-verifier + integration-verifier + acceptance-verifier + system-verifier) on the current spec/branch read-only,… | SPEC-002, SPEC-003, SPEC-006 +37 | test-break-it.sh, test-codex-hooks.sh, test-command-emit-sweep.sh +8 |
 | `/kit:visual-team` | `[H/I]` | Parallel multi-lens critique of a visual/UI design. Dispatches 5 design lenses, merges findings, reports a verdict. Report-only, downstream… | SPEC-016, SPEC-018, SPEC-019 +10 | test-command-emit-sweep.sh, test-meta.sh |
 | `/kit:wayfind` | `[H]` | Plan a chunk of work too big for one agent session as a shared decision map: map.md + typed decision tickets in the mega-goal folder, resol… | SPEC-206, SPEC-207, SPEC-217 +2 | - |
-| `/kit:wrap` | `[H/I]` | The session-scoped landing step after ship: flips board rows, merges the operator's own green PRs one at a time, checks deploys, tidies bra… | SPEC-020, SPEC-060, SPEC-072 +11 | test-bin-forwarders.sh, test-boundary-lint.sh, test-config-registry.sh +4 |
+| `/kit:wrap` | `[H/I]` | The session-scoped landing step after ship: flips board rows, merges the operator's own green PRs one at a time, checks deploys, tidies bra… | SPEC-020, SPEC-060, SPEC-072 +12 | test-bin-forwarders.sh, test-boundary-lint.sh, test-config-registry.sh +4 |
 
 ## Agents