feat(doc-syncer): PATCHED_FILES newline output for doc-commit handoff

doc-syncer now emits PATCHED_FILES — every public-doc file created/modified this run, ONE PATH PER LINE — in both STEP 9 OUTPUT (full audit) and AUTO MODE STEP A4 (the path orchestrators call). NONE stays silent (no line → doc-commit sees empty → no-ops). Additive: detection/patching logic and the `auto-mode scope:` input contract are unchanged → callers unaffected.

Separator contract, producer↔consumer aligned + proven: newline is doc-syncer's OUTPUT format (paths carry no newlines); the agent splits on newline and passes EACH path as a SEPARATE argv element to lib/doc-commit.sh. The helper takes argv (no in-band separator) → a path with spaces survives as one argument. lib/doc-commit.md spells this out (never flatten to a space-joined string + re-split, which would mis-split a spaced path the helper then silently drops). New test T7 PROVES it on real git: 'docs/My Guide.md' → committed as one file (28/28, shellcheck clean).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ho5EQCFTSvYamuRtVZpp2d

agents/doc-syncer.md

@@ -719,8 +719,16 @@ CREATED      : <count> files
 REMOVED      : <count> files / sections
 HUMAN PENDING: <count> items (see report above)
 SKIPPED      : <count> (user declined)
+PATCHED_FILES: (one real path per LINE below; "(none)" if no write)
+<path created or modified this run>
+<path created or modified this run>
 ```
 
+`PATCHED_FILES` is the machine-readable handle the doc-commit step (`lib/doc-commit.md`)
+consumes — every public-doc file created or modified this run, ONE PATH PER LINE. Each line
+is passed as a SEPARATE argument to `lib/doc-commit.sh` (newline split, space-safe). It NEVER
+lists `.claude/**` or `CLAUDE.md` (never targets, BDR-022). Empty / `(none)` → doc-commit no-ops.
+
 ---
 
 ## AUTO MODE
@@ -782,8 +790,9 @@ Categorize:
 
 ### STEP A4 — ACT
 
-- **NONE** → exit completely silent. No output.
+- **NONE** → exit completely silent. No output (no `PATCHED_FILES` → the doc-commit step
-- **MINOR** → patch silently. One-line confirmation:
+  sees an empty list and no-ops).
+- **MINOR** → patch silently. One-line confirmation per file:
   `doc-sync: patched <file> (<what changed>)`
 - **SIGNIFICANT** → surface to user before patching:
   ```
@@ -793,6 +802,16 @@ Categorize:
   ```
   Wait for approval.
 
+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).
+
 ---
 
 ## RULES

lib/doc-commit.md

@@ -18,12 +18,13 @@ and any SIGNIFICANT-gated patch), with the code already committed.
   the doc commit strands outside the merge/PR (the exact bug this fixes). See ORDERING.
 
 doc-syncer runs IN-THREAD (the orchestrator loads it), so the list of files it patched is
-already in hand — surfaced as `PATCHED_FILES:` in doc-syncer's OUTPUT. Pass that list.
+already in hand — surfaced as `PATCHED_FILES:` in doc-syncer's OUTPUT, ONE PATH PER LINE.
+Pass each line as a SEPARATE argument (see DO step 3).
 
 ## DO
 
 1. Collect `PATCHED_FILES` — the public-doc paths doc-syncer wrote this run (its OUTPUT
-   block). Empty → nothing to commit; the helper no-ops.
+   block, ONE PATH PER LINE). Empty → nothing to commit; the helper no-ops.
 
 2. Compose — from the patch context the AGENT holds (doc-syncer ran in-thread, so the
    agent knows exactly what changed) — BOTH artifacts:
@@ -34,11 +35,19 @@ already in hand — surfaced as `PATCHED_FILES:` in doc-syncer's OUTPUT. Pass th
    Both are the AGENT's to write — the helper produces NEITHER (its only stdout is the
    hash). This is the load-bearing point of the visible surface: see the rc 0 row.
 
-3. Commit surgically via the helper, passing EXACTLY the patched files, capturing the hash:
+3. Commit surgically via the helper, passing EXACTLY the patched files — each path as a
+   SEPARATE argument (split `PATCHED_FILES` on NEWLINES only), capturing the hash:
 
-       doc_hash=$(bash "$HOME/.claude/lib/doc-commit.sh" commit "<message>" <PATCHED_FILES…>)
+       doc_hash=$(bash "$HOME/.claude/lib/doc-commit.sh" commit "<message>" "<path-1>" "<path-2>" …)
        rc=$?
 
+   SEPARATOR — the helper takes argv (no in-band separator), so a path with spaces
+   (`docs/My Guide.md`) survives as ONE argument and commits correctly (proven, T7). NEVER
+   flatten the list into a single space-joined string and re-split it: that mis-splits a
+   spaced path into garbage args, which the helper's `[ -e ]` filter then silently drops —
+   the spaced doc would strand. Newline is doc-syncer's OUTPUT format (paths carry no
+   newlines); argv is the handoff to the helper.
+
 4. REPORT BY (rc, doc_hash) — handle EVERY exit, not just success:
 
    | rc | doc_hash | meaning | what to do |

lib/tests/run-doc-commit.sh

@@ -12,6 +12,7 @@
 #   T4  stale-staged doc (version A) → commit carries working-tree version B
 #   T5  idempotent — empty list / clean tree → no-op exit 0
 #   T6  unsafe git state (detached HEAD) → exit 3, no commit
+#   T7  path WITH A SPACE passed as one arg → committed (argv is space-safe, no separator)
 #
 # No -e: run every test and report, even after a failure.
 set -uo pipefail
@@ -158,6 +159,20 @@ if [ "$RC" -eq 3 ]; then ok "detached HEAD → exit 3"; else ko "expected 3, got
 if [ "$(git -C "$R" rev-parse HEAD)" = "$BEFORE" ]; then ok "no commit created"; else ko "a commit was created"; fi
 rm -rf "$R"
 
+echo "T7 — path WITH A SPACE passed as one arg → committed (argv is space-safe)"
+R="$(new_repo)"
+mkdir -p "$R/docs"
+printf 'guide baseline\n' >"$R/docs/My Guide.md"
+git -C "$R" add -A; git -C "$R" commit -qm "add spaced doc"
+printf 'feature added\n' >>"$R/docs/My Guide.md"
+run "$R" commit "docs: T7 spaced" "docs/My Guide.md"
+printf '    rc=%s  out(hash)=[%s]\n' "$RC" "$OUT"
+if [ "$RC" -eq 0 ]; then ok "exit 0"; else ko "expected 0, got $RC"; fi
+if [ -n "$OUT" ]; then ok "hash printed (commit made)"; else ko "no hash"; fi
+if git -C "$R" cat-file -e "HEAD:docs/My Guide.md" 2>/dev/null; then ok "spaced path present in HEAD"; else ko "spaced path not committed"; fi
+if [ -z "$(git -C "$R" status --porcelain -- "docs/My Guide.md")" ]; then ok "spaced doc clean (embarked as ONE file, not split)"; else ko "spaced doc still dirty"; fi
+rm -rf "$R"
+
 rm -f "$ERRFILE"
 echo ""
 printf 'RESULT: %d passed, %d failed\n' "$PASS" "$FAIL"