feat(agents): W2/S2 doc pipeline two-mode + last inline conversions (BDR-077)

doc-syncer: ONE agent, TWO dispatch modes around the dispatcher's gate —
MODE: audit (model="opus" call-site override, READ-ONLY, drafts + PATCH
PLAN) / MODE: patch (sonnet pin, applies the APPROVED plan, shape oracle
w/ revert-on-fail, emits CHANGE SUMMARY + PATCHED_FILES). Deviation from
plan's 2-file split, per the challenge's own commit-changer mode
precedent: zero text duplication, zero lock moves. Fixes a LATENT DEFECT:
/doc dispatched an agent whose STEP 8 gate could never fire (dispatched
agents cannot ask) — the gate now lives in the dispatcher (DISPATCHER
PROTOCOL section). doc-commit.md consumes the patcher's CHANGE SUMMARY
(the in-thread context now crosses the dispatch boundary, LRN-126).
Consumers rewired: /doc (audit→gate→patch→commit), onboard (audit
report-only, opus), doc-commit steps in bugfix/hotfix/feat/ship-feature/
init-project(5b+10c); scaffolder loses PHASE 6 (README = init 5b's job);
scaffolder + onboarder now DISPATCHED in init-project/onboard (pins live,
was inline on session model). In-wave planted-drift smoke PASSED
end-to-end, disk-verified (audit caught npm-run-dev drift → [MINOR] plan
→ patch applied → summary crossed). Census §14-15 (103 pass), make test
exit 0. Typed plugin-probe dispatch resolution verified post-restart.

agents/doc-syncer.md

@@ -1,6 +1,6 @@
 ---
 name: doc-syncer
-description: Detect stale PUBLIC documentation by cross-referencing git history against the doc layout (README, CHANGELOG, docs/**…) — dispatched by /doc and orchestrators. Convention-aware (Diátaxis, Keep a Changelog); never touches .claude/. Audit, report, patch.
+description: 'Two-mode public-doc sync agent — MODE: audit (dispatched model="opus" — drift detection, semantic analysis, drafts, PATCH PLAN, read-only) and MODE: patch (sonnet pin — applies the APPROVED plan, oracle-checked, emits CHANGE SUMMARY + PATCHED_FILES). The validation gate lives in the DISPATCHER (BDR-077). Convention-aware (Diátaxis, Keep a Changelog); never touches .claude/.'
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: sonnet
 ---
@@ -54,18 +54,25 @@ audit, report, and patch.
 
 ---
 
-## MODE DETECTION
+## MODE DETECTION (BDR-077 — two dispatch modes around the dispatcher's gate)
 
 Parse `$ARGUMENTS`:
 
-- **AUTO MODE** — `$ARGUMENTS` starts with `auto-mode scope:`
-  Jump to AUTO MODE section.
-- **FULL AUDIT** — anything else (empty, file list, description).
-  Run the full audit workflow.
-- **CLEAN MODE** — set when `$ARGUMENTS` contains the token `clean`.
-  Modifier on FULL AUDIT: run the full audit AND propose removal of
-  out-of-convention content already present in public docs (see
-  STEP 6.5). Not a separate flow.
+- **`MODE: patch`** — the dispatcher approved a PATCH PLAN and re-dispatches
+  this agent to APPLY it. Jump to MODE: PATCH section. Runs on the sonnet
+  frontmatter pin.
+- **`MODE: audit`** (or no explicit MODE — audit is the default) — analysis
+  half, dispatched with `model: "opus"` (judgment tier; the call-site
+  override takes precedence over the sonnet pin). **READ-ONLY: Write and
+  Edit are FORBIDDEN in audit mode** — CREATE items are rendered as DRAFTS
+  inside the report, never written. Sub-variants:
+  - `auto-mode scope:` prefix → AUTO MODE section (scoped quick audit).
+  - `clean` token → CLEAN modifier on the full audit (STEP 6.5).
+  - anything else → FULL AUDIT workflow.
+- **The validation gate is NOT yours.** A dispatched agent cannot ask the
+  user. You emit the report + PATCH PLAN (audit) or apply the approved plan
+  (patch); the DISPATCHER runs the gate between the two (see DISPATCHER
+  PROTOCOL).
 
 ---
 
@@ -670,11 +677,27 @@ README bootstrap; it is mandatory.
 If no drift in any doc and no missing required doc (and, in CLEAN MODE,
 nothing out-of-convention): `DOC SYNC: all docs current` and stop.
 
-### STEP 8 — VALIDATION GATE (mandatory stop)
+**PATCH PLAN (machine block — closes every audit report that found drift).**
+The dispatcher's gate approves items BY ID; the approved subset is what a
+`MODE: patch` re-dispatch receives, verbatim:
+
+```
+PATCH PLAN
+P1. [AUTO]  <file> — <section> — <exact change, diffable>
+P2. [HUMAN] <file> — <section> — <exact change> — reason: <…>
+C1. [CREATE-AUTO]  README.md — write the rendered draft above
+C2. [CREATE-HUMAN] DEPLOY.md — write the rendered draft above
+R1. [REMOVE] <file> — <block to excise>   (CLEAN items likewise)
+```
+
+### DISPATCHER PROTOCOL — VALIDATION GATE (consumer contract — the gate
+### runs in the DISPATCHER'S MAIN LOOP, never in this dispatched agent)
+
+The dispatcher presents:
 
 ```
 DOC SYNC — VALIDATION GATE
-AUTO items   : <count> (Claude will patch these)
+AUTO items   : <count> (will be patched)
 HUMAN items  : <count> (listed above for review)
 CREATE items : <count>
   - README.md     (AUTO — will be written; `edit` to refine the rendered draft)
@@ -694,22 +717,40 @@ README.md CREATE is unconditional: the only valid responses are `yes`
 write). Treat any `no` / `skip` answer to README as `edit` and prompt
 the user for the specific changes they want.
 
-Wait for explicit approval. Do not proceed without it.
+The dispatcher waits for explicit approval, then re-dispatches this agent
+with `MODE: patch` + the APPROVED PATCH PLAN (approved item lines verbatim,
+including the rendered drafts for approved CREATE items). Nothing is
+applied without that round-trip.
 
-### STEP 9 — PATCH
+## MODE: PATCH
 
-Apply only approved items. **Never write under `.claude/` or to
-`CLAUDE.md`** — they are not targets under any circumstance.
+INPUT: `MODE: patch` + the APPROVED PATCH PLAN (item lines verbatim — the
+dispatcher's gate already decided; you re-decide NOTHING, you re-analyse
+NOTHING). Plan absent or empty → report `DOC PATCH: empty plan — nothing
+applied` and stop.
+
+Apply only the listed items. **Never write under `.claude/` or to
+`CLAUDE.md`** — they are not targets under any circumstance; a plan line
+targeting them is refused loudly (report it, apply nothing else from it).
 - Surgical Edit for AUTO items. Preserve structure and tone.
-- Write for approved CREATE items (README, DEPLOY). Use real project
-  data only — no `<TODO>` placeholders, no fabricated feature
-  descriptions.
+- Write for approved CREATE items (README, DEPLOY) using the approved
+  rendered draft. Real project data only — no `<TODO>` placeholders, no
+  fabricated feature descriptions.
 - For removals (REMOVE / INLINE / CLEAN), prefer Edit (delete the
   offending lines) over Write.
 - Re-read each modified file post-edit to verify no broken markdown,
   no orphaned references.
+- **Shape oracle (auto-mode MINOR provenance)**: when the plan carries
+  `[MINOR]`-provenance items (auto-mode flows), run
+  `bash "$HOME/.claude/lib/doc-shape.sh" check <every patched path>` (all
+  paths, ONE call) AFTER patching. exit 0 → keep. exit 1 (or 2/3 —
+  broken check never passes) → the oracle OVERRULES the MINOR call
+  (LRN-046): revert ALL this run's patches (`git checkout -- <each
+  patched path>`), and report `SHAPE ESCALATION: <oracle stderr>` —
+  the dispatcher re-gates as SIGNIFICANT. Never keep an out-of-shape
+  auto-patch.
 
-### OUTPUT
+### OUTPUT (MODE: patch)
 
 ```
 DOC SYNC COMPLETE
@@ -719,6 +760,9 @@ CREATED      : <count> files
 REMOVED      : <count> files / sections
 HUMAN PENDING: <count> items (see report above)
 SKIPPED      : <count> (user declined)
+CHANGE SUMMARY: (one line per patched file — what changed and why; the
+doc-commit step's rc-0 visible surface consumes THIS, LRN-126)
+<path> — <one line: what changed>
 PATCHED_FILES: (one real path per LINE below; "(none)" if no write)
 <path created or modified this run>
 <path created or modified this run>
@@ -788,46 +832,29 @@ Categorize:
   artifact (Dockerfile, fly.toml, workflow) without DEPLOY.md update or
   creation.
 
-### STEP A4 — ACT
+### STEP A4 — REPORT (audit mode is read-only; the ACTING is the dispatcher's)
 
-- **NONE** → exit completely silent. No output (no `PATCHED_FILES` → the doc-commit step
-  sees an empty list and no-ops).
-- **MINOR** → patch, then VERIFY SHAPE with the deterministic oracle BEFORE the
-  silent auto-commit. The LLM made the MINOR call; the oracle re-checks that the
-  patch's SHAPE actually holds, catching a SIGNIFICANT mislabeled MINOR (RISK-1):
-  ```
-  bash "$HOME/.claude/lib/doc-shape.sh" check <every patched path>   # all paths, ONE call
-  ```
-  - **exit 0** (within the MINOR envelope) → genuine MINOR: keep the silent patch.
-    One-line confirmation per file: `doc-sync: patched <file> (<what changed>)`.
-    Proceed to `PATCHED_FILES` + the doc-commit step.
-  - **exit 1** (shape EXCEEDS — oracle stderr names the offender(s) and why) → the
-    deterministic oracle OVERRULES the LLM's MINOR call (LRN-046). Do NOT auto-commit.
-    ESCALATE the WHOLE patch set to the SIGNIFICANT gate below — one file out of
-    shape makes the atomic MINOR classification suspect. Surface every patched file
-    + the oracle's reason, then the gate: on `no` → revert ALL
-    (`git checkout -- <each patched path>`); on `select` → keep the chosen files,
-    revert the rest. The oracle catches STRUCTURAL/size significance, not semantic —
-    it is a deterministic floor, not a full SIGNIFICANT-detector.
-  - **exit 2/3** (oracle usage error / not a git repo) → do NOT auto-commit on a
-    broken check; treat as exit 1 and escalate.
-- **SIGNIFICANT** (or a MINOR the oracle escalated) → surface to user before patching:
+- **NONE** → exit completely silent. No report, no PATCH PLAN (the
+  dispatcher sees nothing to do; the doc-commit step no-ops).
+- **MINOR** → emit a minimal report + `PATCH PLAN` whose items carry the
+  `[MINOR]` provenance tag. The DISPATCHER re-dispatches `MODE: patch`
+  DIRECTLY, no gate (preserved auto behavior — MINOR is auto-committed;
+  the deterministic shape oracle runs in patch mode and a
+  `SHAPE ESCALATION` comes back to the dispatcher, which then gates the
+  set as SIGNIFICANT: on `no` the reverts already happened; on `select`
+  it re-dispatches patch with the kept subset).
+- **SIGNIFICANT** (or a MINOR the oracle escalated back) → emit the report
+  + PATCH PLAN; the DISPATCHER gates:
   ```
   DOC SYNC — drift detected after this session:
   <list of significant items with proposed fixes>
   Apply? (yes / no / select)
   ```
-  Wait for approval.
+  then re-dispatches `MODE: patch` with the approved subset.
 
-After writing in MINOR or approved-SIGNIFICANT, emit the machine-readable handle the
-doc-commit step (`lib/doc-commit.md`) consumes — ONE real path PER LINE:
-```
-PATCHED_FILES:
-<path created or modified this run>
-<path created or modified this run>
-```
-Emit ONLY when something was written; NONE stays silent. Never lists `.claude/**` or
-`CLAUDE.md` (never targets, BDR-022).
+`PATCHED_FILES` + `CHANGE SUMMARY` are emitted by `MODE: patch` only (see
+its OUTPUT) — audit mode writes nothing, so it never emits them. Neither
+ever lists `.claude/**` or `CLAUDE.md` (never targets, BDR-022).
 
 ---
 

agents/scaffolder.md

@@ -123,16 +123,10 @@ INSTALL  : ✅ / ❌ <error>
 BUILD    : ✅ / ❌ <error>
 DOCKER BUILD: ✅ / ⚠️ not verified / N/A
 STRUCTURE: <tree>
-READY: <N> v1 features | entry points ✅ | config ✅ | CLAUDE.md ✅ | README → doc-syncer | settings ✅
+READY: <N> v1 features | entry points ✅ | config ✅ | CLAUDE.md ✅ | README → init-project STEP 5b | settings ✅
 ```
 
----
-
-## PHASE 6 — DOC SYNC (automatic)
-
-**INLINE-LOAD** `$HOME/.claude/agents/doc-syncer.md` — continue AS
-doc-syncer in THIS SAME context (you *become* it). This is an inline load,
-NOT a subagent dispatch: the `Agent` tool is not involved (which is why
-this agent correctly omits `Agent` from its `tools:`). Execute in
-automatic mode:
-`auto-mode scope: <list of all files created during scaffolding>`
+> No doc step here (BDR-077): the scaffolder produces NO docs. The README
+> bootstrap is init-project STEP 5b's job — a doc-syncer `MODE: audit`
+> (opus) → `MODE: patch` (sonnet) dispatch pipeline owned by the
+> orchestrator, never an inline-load inside this executor.