propagate

name	propagate
description	Use when a feature branch is done (or the user asks to sync docs/config) to propagate the branch's changes into every mirror — .env examples, compose files, docs/, wiki/, CHANGELOG. Checker-driven agent fan-out; propose-then-approve (drafts edits in the working tree, never commits).

/propagate — diff-driven doc & config propagation

Design: docs/superpowers/specs/2026-07-03-propagate-doc-sync-design.md. Map (what mirrors what): docs/PROPAGATION.yaml. Checker: pnpm --filter @agora/api check:propagation --diff <base> --json.

Prime directive: propose-then-approve. Draft every edit in the working tree, present a checklist, then STOP. Never commit, never push. The user reviews and commits.

Flow

1. Establish the base

Use an explicit ref if the user gave one as an argument; otherwise git merge-base HEAD root. If the merge-base equals HEAD (working directly on root), fall back to HEAD — the diff is then just uncommitted work. All diffing includes uncommitted changes.

2. Scout (deterministic)

Run the checker and parse its JSON:

pnpm --filter @agora/api check:propagation --diff <base> --json

obligations[] rows are { cls, subject, kind, target, status, note? }. Work only the missing ones; carry advisory rows forward as judgment items; report unparseable rows verbatim in the final checklist (never swallow them). excepted/present need no work.

3. Judgment sweep (one agent, read-only)

Dispatch ONE agent with the full diff (git diff <base> + untracked files) and the list of mapped targets. Its job — it EDITS NOTHING, it returns data:

• Which prose docs beyond the mapped targets are affected? (It should list docs/ and wiki/ filenames and skim candidates before answering.)
• Draft the CHANGELOG [Unreleased] entry (Keep a Changelog sections: Added/Changed/Fixed/Removed).
• For each advisory obligation from the scout: is it real work or ignorable, and why?

4. Fan out drafting agents (parallel, one file : one agent)

Partition by audience cluster so each agent tells one coherent story across related docs. No two agents may touch the same file. Standard clusters (skip any with no work; add clusters for sweep-discovered targets):

• mechanical — .env.*.example ×3 + docker-compose*.yml ×3. Rote edits: match each template's comment style and the LOCAL/CLOUD commented-switch convention; compose entries use KEY: ${KEY:-default} with a brief comment, mirroring existing entries.
• deployment prose — docs/SELF-HOSTING.md + README.md + wiki/Deployment.md (+ CLAUDE.md when env/commands/architecture summaries are affected).
• API contract prose — docs/MANIFEST.md + docs/MODELS.md + wiki/API-Contract.md.
• CHANGELOG — apply the sweep's drafted entry under [Unreleased].

Every drafting agent gets: the relevant diff hunks, its obligation rows, the instruction to match each doc's existing voice/structure/heading style, and the hard rule: if you cannot find a sensible home for content, REPORT it back — do not invent new doc sections.

5. Verify (deterministic again)

Re-run the checker. Every remaining missing/unparseable row must be explained in the checklist (candidate for exceptions: in docs/PROPAGATION.yaml, or a real gap the user must rule on). Then one critic agent, read-only: "Given this diff and these edits, what's still missing — a doc not updated, a removal not scrubbed, a stale wiki page?"

6. Report and stop

Present:

• ✅ propagated (subject → files)
• ⏭️ excepted (with reasons)
• ⚠️ intentionally skipped? (unresolved obligations — offer to add recurring ones to exceptions: in docs/PROPAGATION.yaml)
• ❓ needs your judgment (advisory + anything agents reported instead of guessing)
• 💥 unparseable (checker could not read/parse a mapped target — fix the map or the file)
• git diff --stat of the working tree Then STOP. The user reviews and commits.