claude/.claude/tasks/2026-06-27-doc-sync-coupled.md

# Doc-sync Coupled — Implementation Plan (v1)

> Frozen 2026-06-27. Twin of coupled-capitalize ([[BDR-034]]), same PR-stranding
> class — but NOT the same fix. The deferred note ("reorder before FINISH") was
> REFUTED in analysis: doc-syncer commits NOTHING (proven, zero `git commit`/`add`),
> so reordering uncommitted docs still misses the merge/PR. Real fix = REORDER **+**
> CREATE a doc-commit mechanism (it does not exist; memory already had one).
> NO `git add -A` ever — safety lives in the (dynamic) pathspec.

**Goal:** every orchestrator flow that syncs public docs also COMMITS those docs
automatically, on the branch, BEFORE FINISH integrates it — so doc patches reach
the merge/PR instead of stranding uncommitted in the working tree.

**Architecture:** `lib/doc-commit.sh` (surgical commit of ONLY the files doc-sync
patched this run, passed as args, filtered to changed paths, never `-A`, hard-guard
excluding `.claude/`+`CLAUDE.md`) + include `lib/doc-commit.md` referenced by the 2
orchestrators at their doc-sync step. Both orchestrators reordered (doc-sync before
FINISH). Mirror of `memory-commit.sh` + `capitalize-commit.md` with **4 deltas**:

| # | memory-commit (twin) | doc-commit (this) | Why |
|---|---|---|---|
| Δ1 | fixed scope `.claude/memory`+`.claude/tasks` | **dynamic** — patched-file list as args | docs scatter across an enumerable set; commit only what was touched |
| Δ2 | TARGETS `.claude/` | **hard-guard EXCLUDES** `.claude/`+`CLAUDE.md` | BDR-022 — inverse scope; defense-in-depth |
| Δ3 | 2-hash dance (code hash anchored in entries) | **no hash** — docs carry no SHA | LRN-052 — anchoring N-A to docs |
| Δ4 | `chore(memory): <IDs> — <flow>` | `docs: <summary> — <flow>` | separate concern, mirror |

**Consumption = MECHANICAL** ([[LRN-057]] case a, = BDR-034): commit on the branch
before FINISH, the merge carries it. No external-cognitive injection needed.

## Conscious acknowledgments (state them, don't paper over)
- **Partial init-project fix.** After this chantier: ship-feature FULLY fixed;
  init-project PARTIAL — doc-sync ok, but scaffold + 5b-bootstrap-README commit
  gap stays open ([[BLK-010]]). doc-commit must NOT ramasse the bootstrap README —
  not its job (would re-create the over-reach we ban). Do NOT believe init-project
  repaired while the scaffold hole remains.
- **MINOR doc content is non-gated yet auto-committed.** This is a CONSCIOUS choice,
  NOT "same as memory": memory CONTENT was always gated, so auto-commit only ever
  embarked approved entries. doc-sync auto-mode patches MINOR silently (no gate).
  Resolution: surface-don't-block. MINOR is factual (command/param/path/version/dead
  link — same bar as AUTO patches); a blocking gate = friction disproportionate, and
  the PR diff re-shows it. The doc-commit's **visible** surface REPLACES the gate as
  the review surface — `✅ committed README, USAGE — <summary of what changed>`,
  NOT a bare count. Strengthening the MINOR gate itself = separate doc-syncer chantier.

## Global Constraints (verbatim, apply to every task)
- Stage/commit ONLY the files doc-sync patched this run, passed as args. NEVER `git add -A` / `git add .` / `git commit -a`. NEVER stage anything under `.claude/**` or `CLAUDE.md` (hard guard — BDR-022, inverse of memory-commit).
- Dynamic pathspec: filter the passed list to paths with real pending changes (LRN-051 — `git commit -- <no-match>` ABORTS the whole commit; `git add` tolerates). A clean/absent passed path is dropped, not fatal.
- Partial-commit safety: `git commit -- <changed-paths>` ignores the rest of the index → dangling code (untracked OR pre-staged) is never embarked.
- Idempotent: empty list / clean tree → no-op, exit 0, no commit.
- Fail-closed: detached HEAD / merge / rebase / cherry-pick in progress → no commit, skip (exit 3).
- NO hash anchoring — docs carry no SHA (LRN-052). Commit msg `docs: <summary> — <flow>`.
- Surface is VISIBLE: report committed files + a one-line change summary, not just a count.
- shellcheck clean on `lib/doc-commit.sh` + test harness.

## File Structure
| Action | File | Responsibility |
|---|---|---|
| Create | `lib/doc-commit.sh` | dynamic-scope surgical doc commit (CLI + sourceable), inverse-exclusion guard |
| Create | `lib/doc-commit.md` | include protocol (mirror capitalize-commit, 4 deltas, visible surface) |
| Create | `lib/tests/run-doc-commit.sh` | TDD: inverse-exclusion + dynamic-pathspec + dangling + stale-index + idempotent + unsafe, real git fixture |
| Modify | `agents/doc-syncer.md` | add `PATCHED_FILES:` block to OUTPUT (STEP 9) + AUTO MODE (STEP A4); no logic change, callers unaffected |
| Modify | `agents/feater.md` · `bugfixer.md` · `hotfixer.md` | **Task 6b (sweep-found scope expansion)** — wire doc-commit into each DOC SYNC step |
| Modify | `skills/ship-feature/SKILL.md` | reorder DOC SYNC before FINISH + doc-commit include; DELETE HTML comment (lines 196–198); renumber FAILURE PATHS / FINAL OUTPUT |
| Modify | `skills/init-project/SKILL.md` | move SYNC README before FINISH (new STEP 10c) + doc-commit include; renumber `/13` PROGRESS PROTOCOL headers; conscious partial-fix note ([[BLK-010]]) |
| Modify | `README.md` · `USAGE.md` · `CHANGELOG.md` | ref-sweep (README:153, USAGE:196/256) + changelog entry |
| Append | `.claude/memory/` (BDR + LRN) | document the invariant at close |
| Append | `.claude/memory/blockers.md` | BLK-010 scaffold gap, BLK-011 GSD ROADMAP — **done this turn** |

## Tasks
- **Task 1** — `lib/doc-commit.sh` (TDD, same hard requirement as memory-commit:
  every test REALLY EXECUTED with real outputs reported before Task 2 — no presumed
  git behavior; Δ2 + Δ1 especially must be proven on real git).
  - **T1 inverse exclusion (Δ2):** a passed path under `.claude/` (e.g. `.claude/memory/x.md`) or `CLAUDE.md` is REJECTED — not committed, guard fires. The load-bearing delta vs memory-commit; prove it on real git.
  - **T2 dynamic pathspec (Δ1):** pass `[README.md, USAGE.md, DEPLOY.md]` where only README+USAGE changed → commit contains exactly README+USAGE; the clean DEPLOY.md path is filtered, commit does NOT abort (LRN-051).
  - **T3 dangling not embarked:** untracked AND pre-staged non-doc code (`src/x`) NOT in the doc commit, stays untracked/staged.
  - **T4 stale-index:** doc staged as version A, working-tree version B → commit contains B (`git add --` re-stage neutralizes stale index). Mirror of memory T2-bis.
  - **T5 idempotent:** empty list / clean → no-op exit 0, no commit. **T6 unsafe:** detached HEAD / merge in progress → exit 3, no commit.
- **Task 2** — `lib/doc-commit.md` include (WHEN / DO / HARD RULE surgical / ORDERING before FINISH / IDEMPOTENT / VISIBLE-SURFACE report / no-hash note / inverse-scope vs capitalize-commit). State the 2 conscious acknowledgments inline.
- **Task 3** — `agents/doc-syncer.md`: add `PATCHED_FILES:` (newline-separated real paths, or empty) to STEP 9 OUTPUT + AUTO MODE STEP A4. Additive, no logic change, `auto-mode scope:` contract unchanged → callers unaffected (BDR-022 preserved). Future-proofs the isolated-subagent invocation; in-thread, the list is already in hand.
- **Task 4** — ship-feature reorder: STEP 8 = DOC SYNC (was 9, + doc-commit include), STEP 9 = FINISH (was 8). DELETE the twin-chantier HTML comment. Renumber FAILURE PATHS + FINAL OUTPUT refs. Pipeline stays "9-step".
- **Task 5** — init-project reorder: new STEP 10c = DOC SYNC (moved from 12, + doc-commit include) after STEP 10b CAPITALIZE, before STEP 11 FINISH; old STEP 13 GSD → STEP 12. Update PROGRESS PROTOCOL `/13` headers. Add the conscious partial-fix note pointing at [[BLK-010]] (scaffold/bootstrap still open) + [[BLK-011]] (GSD ROADMAP).
- **Task 6** — ref-sweep: README:153, USAGE:196, USAGE:256, CHANGELOG. Grep READS not just WRITES (LRN-002/LRN-045). Result: live refs all fixed in Task 4/5, no old headers survive, historicals left. **Sweep also caught the inline-flow gap → Task 6b.**
- **Task 6b — SCOPE EXPANSION (sweep-found, NOT in the original frozen plan — honesty).** feat/bugfix/hotfix each have a DOC SYNC step that patched docs but committed nothing → docs left dirty (milder than PR-strand, same class; the asymmetry vs memory is the decider — BDR-034 wired ALL flows). Wire doc-commit into each (1-line include + paragraph, mirror of capitalize-commit). Set = the 3 flows that doc-sync, NOT all 4 capitalize flows: commit-change has no DOC SYNC. hotfix IS wired (its DOC SYNC is unconditional; only its CAPITALIZE is skip-by-default; the include no-ops on empty). We extend the mechanical REPLICATION of a built+tested mechanism; we defer NEW work (BLK-010/011).
- **Task 7** — behavioral verify doc (`lib/tests/` end-to-end check, ship-feature + init-project paths) + shellcheck + CHANGELOG entry + close with BDR + LRN. The closing BDR states the surface-replaces-gate choice HONESTLY (MINOR non-gated auto-committed) — not glossed as memory-equivalent.

## Deferred / flagged separate (by design, not omission)
- **[[BLK-010]]** scaffold + bootstrap-README commit gap (init-project; unborn HEAD + worktree) → own chantier. **Flagged this turn.**
- **[[BLK-011]]** GSD STEP 13 ROADMAP.md post-FINISH (3rd post-FINISH artifact) → own thread. **Flagged this turn.**
- Strengthening doc-sync's MINOR gate → separate doc-syncer chantier.
- doc-sync as isolated subagent (vs in-thread) → `PATCHED_FILES:` already future-proofs it; no work now.