docs(workflow): learnings from the docs-sync repro gate

.kilo_workflow/learnings/background-process-inline-quote-mangling.md

@@ -0,0 +1,18 @@
+# background_process tool mangles inline ruby/perl one-liners — use a runner script
+
+**Symptom:** `background_process start` with a pipeline containing an inline scripting one-liner
+fails immediately: ruby reports `unexpected local variable or method`, perl reports
+`Execution of -e aborted due to compilation errors`. A `$VAR=value; ... > "$VAR/file"` prefix also
+expands empty in the redirect target (`read-only file system: /file.log`).
+
+**Cause:** The tool evaluates the command through an extra eval/quoting layer that mangles nested
+quotes inside single-quoted one-liner programs and breaks variable scoping for the redirect.
+
+**Fix:** Write the whole pipeline (including env vars, `cd`, timestamp filter, log path) as a
+literal shell script file under `$SCRATCH`, `chmod +x` it, and pass only the script path plus
+arguments to `background_process start`. That worked first try. A perl per-line timestamp filter
+that survives inside the script file:
+`perl -ne 'printf "%02d:%02d:%02d %s", (localtime)[2,1,0], $_'`
+(macOS awk has no strftime; ruby/perl are preinstalled.)
+
+Observed 2026-07-28 on this harness (zsh, macOS) during the docs-sync-cli-47f4 repro.

.kilo_workflow/learnings/docs-sync-repro-round-state-reset.md

@@ -0,0 +1,18 @@
+# docs-sync edit-pass repro: reset round state between B1/B2
+
+**Symptom:** A second repro round of `.github/docs-sync/edit.mjs` returns instantly with
+"edit pass complete" while doing no agent work.
+
+**Cause:** `edit.mjs` has no stale-summary cleanup. After each `runKilo` call it checks
+`fs.existsSync(summaryFile)` (`edit.mjs:92`) and returns success immediately — so a leftover
+`docs-sync-out/edit-summary-<n>.json` from the previous round short-circuits the round. Leftover
+doc edits in `packages/kilo-docs` additionally change the agent's starting state (it will skip
+already-documented PRs), breaking comparability between rounds.
+
+**Fix:** Between rounds, in the kilocode worktree:
+`rm -rf docs-sync-out && git checkout -- packages/kilo-docs`, then re-copy the fixtures
+(`worthy.json`, `triage.json`) per the handoff setup. Also delete any stray
+`edit-summary-*.json` / `.docs-sync-summary.json` at the repo root (the agent sometimes drops the
+`docs-sync-out/` prefix; the script tolerates and renames those, see edit.mjs:94-97).
+
+Verified 2026-07-28 in the docs-sync-cli-47f4 repro (kilocode worktree, CLI 7.4.16).