@event4u/agent-config 9.5.0 → 9.7.0

package/dist/agent-src/commands/project/health.md

@@ -9,9 +9,8 @@ cluster: project
 skills: [quality-tools]
 description: Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything
 suggestion:
-  eligible: true
-  trigger_description: "check project health, what's the state of my docs and modules"
-  trigger_context: "routine health check, no destructive intent"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/research/deep.md

@@ -10,9 +10,8 @@ description: "Read `outline.yaml`, research each item in batches, write per-item
 argument-hint: "[--batch-confirm=each|once|auto]"
 skills: [deep-reading-analyst]
 suggestion:
-  eligible: true
-  trigger_description: "deep research, populate the research scaffold, fill outline.yaml items"
-  trigger_context: "user has run `/research <topic>` and now wants per-item depth"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/research/report.md

@@ -9,9 +9,8 @@ sub: report
 description: "Summarise per-item JSON results from `/research:deep` into `report.md`. Agent renders directly + emits an optional `jq` template for deterministic regeneration. No Python runtime."
 skills: [deep-reading-analyst]
 suggestion:
-  eligible: true
-  trigger_description: "summarise research results, build research report, render outline.yaml results"
-  trigger_context: "user has finished `/research:deep` and wants a single markdown summary"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/review/changes.md

@@ -12,9 +12,8 @@ cluster: review
 skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, judge-synthesis, git-workflow]
 description: Self-review local changes before creating a PR — dispatches to five specialized judges (bug, security, tests, quality, architecture) and consolidates verdicts
 suggestion:
-  eligible: true
-  trigger_description: "self-review my changes, judge this diff before PR"
-  trigger_context: "uncommitted or staged changes pre-PR"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/review/routing.md

@@ -10,9 +10,8 @@ skills: [review-routing, reviewer-awareness]
 description: Compute reviewer roles and matched historical bug patterns for the current diff, using project-local ownership-map.yml and historical-bug-patterns.yml
 argument-hint: "[base-ref head-ref]"
 suggestion:
-  eligible: true
-  trigger_description: "who should review this, suggest reviewers for this PR"
-  trigger_context: "PR open without assigned reviewers"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/roadmap/ai-council.md

@@ -11,9 +11,8 @@ description: Challenge a roadmap with the AI council (deep tier) and refactor fr
 argument-hint: "[roadmap-name | path]"
 council_depth: deep
 suggestion:
-  eligible: true
-  trigger_description: "council on roadmap, challenge this roadmap, stress-test the plan, refactor roadmap from council findings"
-  trigger_context: "existing agents/roadmaps/*.md the user wants reviewed before execution"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/roadmap/create.md

@@ -9,9 +9,8 @@ sub: create
 skills: [agent-docs-writing]
 description: Interactively create a new roadmap file in agents/roadmaps/
 suggestion:
-  eligible: true
-  trigger_description: "create a roadmap for X, plan this work as a roadmap"
-  trigger_context: "multi-phase work without an existing agents/roadmaps/*.md"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/roadmap/materialize.md

@@ -10,9 +10,8 @@ skills: [emit-tickets]
 description: Materialise a roadmap into a self-contained, importable ticket bundle under agents/tickets/
 argument-hint: "[roadmap-path]"
 suggestion:
-  eligible: true
-  trigger_description: "turn this roadmap into tickets, materialise the roadmap, mach Tickets aus der Roadmap"
-  trigger_context: "an existing agents/roadmaps/*.md the user wants decomposed into build-ready tickets"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/roadmap/process-full.md

@@ -10,9 +10,8 @@ skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process every open step across every phase of a roadmap until the file is fully closed. Largest execution scope of the /roadmap cluster — runs continuously across phase boundaries.
 argument-hint: "[roadmap]"
 suggestion:
-  eligible: true
-  trigger_description: "process the whole roadmap, finish the roadmap, komplette roadmap abarbeiten"
-  trigger_context: "existing agents/roadmaps/*.md and user wants the entire file done end-to-end"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/roadmap/process-phase.md

@@ -10,9 +10,8 @@ skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process every open step in the next or current phase of a roadmap, then stop. Default execution scope of the /roadmap cluster.
 argument-hint: "[roadmap]"
 suggestion:
-  eligible: true
-  trigger_description: "process the next phase, finish this phase autonomously, eine phase abarbeiten"
-  trigger_context: "existing agents/roadmaps/*.md and user wants the next phase done end-to-end"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/roadmap/process-step.md

@@ -10,9 +10,8 @@ skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /roadmap cluster — one step in, one step out.
 argument-hint: "[roadmap]"
 suggestion:
-  eligible: true
-  trigger_description: "process the next step, do the next roadmap step, einen schritt abarbeiten"
-  trigger_context: "existing agents/roadmaps/*.md and user wants exactly one step done autonomously"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/skill/preview.md

@@ -10,9 +10,8 @@ description: Non-destructive preview of a skill — its declared steps, executio
 argument-hint: "<skill-name> [--technical]"
 skills: [file-editor]
 suggestion:
-  eligible: true
-  trigger_description: "what does this skill do, preview <skill> before running, what will it change, is it safe, /skill:preview competitive-positioning"
-  trigger_context: "user wants to inspect a skill's declared intent before committing to run it"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/skills/discover.md

@@ -10,9 +10,8 @@ description: Recommend skills for a role — ranked by four explained classes (m
 argument-hint: "[role]"
 skills: [file-editor]
 suggestion:
-  eligible: true
-  trigger_description: "which skills should I use, recommend skills for my role, what fits this work, help me find a skill, /skills:discover sales"
-  trigger_context: "user wants a short, explained skill shortlist instead of scanning the 220-skill catalog"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/sync/gitignore/fix.md

@@ -9,9 +9,8 @@ sub: gitignore
 skills: [sync-gitignore]
 description: Scrub legacy pre-`/agents/` patterns from the consumer's .gitignore (inside or outside the managed block) and re-sync the canonical entries
 suggestion:
-  eligible: true
-  trigger_description: "fix .gitignore garbage, clean up legacy agent-config entries, my .gitignore has stale agent entries, /sync-gitignore is not picking up the right paths"
-  trigger_context: "consumer project carries pre-/agents/ runtime patterns (.agent-chat-history, .agent-prices.md) at the root from an older install"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:
@@ -191,5 +190,5 @@ If the check fails, offer to re-sync the block with the current template:
   ignored-but-tracked detection (Phase 5.2)
 - [`scripts/check_gitignore_freshness.ts`](../../../../src/scripts/check_gitignore_freshness.ts) —
   manifest vs block coverage check (Phase 3.4)
-- [`docs/contracts/agents-layout.md`](../../../../docs/contracts/agents-layout.md) —
+- [`docs/contracts/agents-layout.md`](../../../../../../docs/contracts/agents-layout.md) —
   full classification contract for `agents/` entries

package/dist/agent-src/commands/tdd/green.md

@@ -10,9 +10,8 @@ skills: [test-driven-development]
 description: TDD green phase — write the minimum production code to make the failing test pass; no test edits
 argument-hint: "[failing test | context]"
 suggestion:
-  eligible: true
-  trigger_description: "make the failing test pass"
-  trigger_context: "a failing test exists, ready to implement"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/tdd/red.md

@@ -10,9 +10,8 @@ skills: [test-driven-development]
 description: TDD red phase — enumerate cases, write ONE failing test, watch it fail at an assertion (not an import error)
 argument-hint: "[behavior to test]"
 suggestion:
-  eligible: true
-  trigger_description: "write the failing test first"
-  trigger_context: "starting a new behavior test-first"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/tdd/refactor.md

@@ -10,9 +10,8 @@ skills: [test-driven-development]
 description: TDD refactor phase — clean up (rename, deduplicate) while keeping the test green
 argument-hint: "[target | context]"
 suggestion:
-  eligible: true
-  trigger_description: "refactor while the test stays green"
-  trigger_context: "test is green, ready to clean up"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/team/adversarial.md

@@ -11,9 +11,8 @@ description: Thin wrapper — adversarial cross-model review on a named focus vi
 cluster: team
 sub: adversarial
 suggestion:
-  eligible: true
-  trigger_description: "adversarial cross-model review, attack this change with a second model, stress-test the diff with GPT, hostile review by another model"
-  trigger_context: "ai_team.enabled is true AND single-model self-review found nothing or the stakes are high — escalate the Attack-Defend-Revise frame to a second strong model"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/team/review.md

@@ -10,9 +10,8 @@ description: Thin wrapper — cross-model review of the current diff via the off
 cluster: team
 sub: review
 suggestion:
-  eligible: true
-  trigger_description: "team review, second model review, cross-model review of my changes, GPT drüberschauen lassen, review the diff with another strong model"
-  trigger_context: "ai_team.enabled is true AND there is an uncommitted / staged diff the user wants a second strong model to review with repo access"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/team-knowledge/bootstrap.md

@@ -9,9 +9,8 @@ sub: bootstrap
 description: One-shot deterministic seed for a fresh project's knowledge layer — stages template pages from real config/directory detection, never LLM-invented claims. Review-then-commit.
 skills: []
 suggestion:
-  eligible: true
-  trigger_description: "bootstrap the knowledge base, seed project knowledge, initialize agents/knowledge, onboard this project's knowledge layer"
-  trigger_context: "a project has no agents/knowledge/ typed pages yet and the user wants a starting baseline"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/team-knowledge/consolidate.md

@@ -9,9 +9,8 @@ sub: consolidate
 description: Review pending typed knowledge-observation events and file them into agents/knowledge/ pages as a human-reviewed batch — never writes without approval.
 skills: [file-editor]
 suggestion:
-  eligible: true
-  trigger_description: "consolidate knowledge events, review pending observations, file captured knowledge, promote knowledge candidates"
-  trigger_context: "pending events have accumulated in agents/knowledge/intake/ and are ready for review"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/tests/create.md

@@ -9,9 +9,8 @@ sub: create
 skills: [test-case-discovery, pest-testing, quality-tools]
 description: Write meaningful tests for the current branch — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
 suggestion:
-  eligible: true
-  trigger_description: "write tests for these changes, add tests for this branch"
-  trigger_context: "code changes on the branch without matching test changes"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/tests/e2e-heal.md

@@ -11,9 +11,8 @@ skills: [playwright-testing]
 description: Find, debug, and fix failing Playwright E2E tests
 argument-hint: "[test-file | ci-run-url]"
 suggestion:
-  eligible: true
-  trigger_description: "fix the failing E2E tests, playwright tests are red"
-  trigger_context: "failing test output from tests/e2e/"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/tests/e2e-plan.md

@@ -11,9 +11,8 @@ skills: [playwright-testing]
 description: Explore the application and create a structured E2E test plan in Markdown
 argument-hint: "[url | feature-area]"
 suggestion:
-  eligible: true
-  trigger_description: "plan E2E tests for this feature, what should we cover in playwright"
-  trigger_context: "new feature or page added without tests/e2e/ coverage"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/tests/execute.md

@@ -10,9 +10,8 @@ skills: [pest-testing, quality-tools]
 description: Run the project's test suite — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
 argument-hint: "[file | filter] [--include-e2e] [--include-slow] [--php]"
 suggestion:
-  eligible: true
-  trigger_description: "run the tests, execute the test suite"
-  trigger_context: "code changes pending verification"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/video/from-script.md

@@ -11,9 +11,8 @@ argument-hint: "<path-to-script.md> [--mode preview|commit] [--max-spend-usd <us
 personas: [hollywood-director, ai-video-technical-director]
 skills: [scene-expander, video-director, pixar-storyteller, character-consistency, motion-choreographer]
 suggestion:
-  eligible: true
-  trigger_description: "render a video from a script, full AI video pipeline, multi-scene generation"
-  trigger_context: "user supplies a Markdown script with `## Scene N` headings and wants a final MP4"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/video/from-song.md

@@ -11,9 +11,8 @@ argument-hint: "<images-dir> <song-file> [--mode preview|commit] [--brief <text>
 personas: [hollywood-director, ai-video-technical-director]
 skills: [song-to-script, scene-expander, video-director, character-consistency, motion-choreographer, prompt-validator]
 suggestion:
-  eligible: true
-  trigger_description: "make a music video from a song, turn a track into a video, lip-sync clip from images and audio, AI music video"
-  trigger_context: "user supplies an audio file plus reference images and wants a final MP4 cut to the song"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/video/scene.md

@@ -11,9 +11,8 @@ argument-hint: "<idea> [--mode preview|commit] [--image-provider <id>] [--video-
 personas: [hollywood-director, ai-video-technical-director]
 skills: [scene-expander, video-director, character-consistency, motion-choreographer]
 suggestion:
-  eligible: true
-  trigger_description: "render a single video scene, iterate on one shot, test a prompt without a full script"
-  trigger_context: "user supplies a one-line scene idea and wants a single clip, no multi-scene stitching"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/video/stitch.md

@@ -11,9 +11,8 @@ argument-hint: "<project-slug> [--skip-scene <id>] [--continue]"
 personas: [ai-video-technical-director]
 skills: []
 suggestion:
-  eligible: true
-  trigger_description: "re-stitch existing video clips, rebuild final MP4 after edits, ffmpeg concat existing scenes"
-  trigger_context: "user has edited clips in `<project>/scenes/*/` and wants the final.mp4 rebuilt without paying for re-renders"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/video/storyboard.md

@@ -11,9 +11,8 @@ argument-hint: "<path-to-script.md> [--image-provider <id>]"
 personas: [hollywood-director]
 skills: [scene-expander, video-director, character-consistency]
 suggestion:
-  eligible: true
-  trigger_description: "build a storyboard, contact sheet of scenes, image-only preview, validate a script visually before video render"
-  trigger_context: "user wants to see all scenes as stills before committing to motion calls"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/worktree/cleanup.md

@@ -10,9 +10,8 @@ skills: [worktree-lifecycle, git-workflow]
 description: Safe worktree removal gate — refuses while the branch holds commits on no other ref; never force-deletes
 argument-hint: "[worktree-path]"
 suggestion:
-  eligible: true
-  trigger_description: "clean up the worktrees, remove the finished worktree"
-  trigger_context: "git worktree list shows worktrees whose branches are merged"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/worktree/create.md

@@ -10,9 +10,8 @@ skills: [worktree-lifecycle, using-git-worktrees]
 description: Create a governed worktree and write its scope-lock note — propose-once branch naming, host-native primitive preferred
 argument-hint: "[task] [branch-name]"
 suggestion:
-  eligible: true
-  trigger_description: "do this in a worktree, isolate this task, spawn a worktree for X"
-  trigger_context: "parallel or exploratory work while the current branch is mid-work"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/worktree/status.md

@@ -9,9 +9,8 @@ sub: status
 skills: [worktree-lifecycle, git-workflow]
 description: List active worktrees — ownership (scope lock), dirty state, ahead/behind, merge-readiness incl. verification evidence
 suggestion:
-  eligible: true
-  trigger_description: "which worktrees are active, is this worktree merge-ready, worktree overview"
-  trigger_context: "git worktree list shows more than the main working tree"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/commands/worktree/verify.md

@@ -10,9 +10,8 @@ skills: [worktree-lifecycle, verify-completion-evidence]
 description: Run the scoped verification for a worktree's declared change — narrow probes matched to the diff, never the full CI pipeline
 argument-hint: "[worktree-path | branch]"
 suggestion:
-  eligible: true
-  trigger_description: "verify the worktree change, prove this worktree is ready"
-  trigger_context: "a governed worktree with committed changes but no verification evidence attached"
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
 workspaces:
   - agent-config-maintainer
 packs:

package/dist/agent-src/contexts/contracts/command-suggestion-flow.md

@@ -91,6 +91,16 @@ suggestion:
   cooldown: 30m            # longer than global default
 ```
 
+## Eligibility invariant — cluster sub-commands route via their head
+
+A `/cluster:sub` command (frontmatter `sub:` set) is **not** independently
+suggestion-eligible: `suggestion.eligible: false`. The cluster HEAD is the
+journey that self-suggests; the sub-command is reached by routing from the head
+(the `/fix:route` template) or by its explicit `/cluster:sub` name — which
+always works. This keeps the proactive surface to a few journeys, not one
+entry point per mode (9.4.0 review; `road-to-surface-consolidation`, council
+2026-07-20). Standalone commands (no `sub:`) and cluster heads may be eligible.
+
 ## Subordination — when to stay silent
 
 The rule lists four senior gates that outrank suggestion. The agent

package/dist/agent-src/rules/downstream-changes.md

@@ -45,7 +45,36 @@ After editing any file, search for **all** of these:
 | **Config / bindings** | Search service providers, config files | Update class references in DI bindings |
 | **API schemas / OpenAPI** | Check controller attributes | Update if response structure changed |
 | **Routes** | Search `routes/` for controller references | Update after controller rename/move |
-| **Documentation** | Search `agents/`, `docs/` for references | Update if behavior or API changed |
+| **Documentation** | Search `agents/`, `docs/`, `README`, examples for references | Update the doc that **describes** the changed surface — see Doc-Impact below |
+
+## Doc-Impact — docs follow code (same change)
+
+```
+A CHANGE TO A PUBLIC SURFACE IS INCOMPLETE UNTIL THE DOC THAT
+DESCRIBES IT IS UPDATED IN THE SAME CHANGE. A DOC MAKING A CLAIM
+THE CODE NOW CONTRADICTS IS A BROKEN CHANGE, NOT A STYLE NIT.
+```
+
+**Public surfaces** whose change triggers a doc update: HTTP route /
+endpoint · exported function / class signature · CLI command or flag ·
+config / settings key · env var · DB schema or migration · event
+payload. Update the doc that describes it — README, API / OpenAPI docs,
+AGENTS.md, code examples, CHANGELOG — in the same commit.
+
+**Drift = a falsifiable-claim contradiction**, not incompleteness. Fire
+when a reader following the doc would be misled: an endpoint that no
+longer exists, a wrong return type, a renamed key, a broken example. Do
+**not** fire on "the doc could be more detailed" — completeness is a
+quality nit, not drift.
+
+**Escape hatch** (no false-positive fatigue): refactor-only / no
+public-surface change → no doc obligation. If a surface changed but
+genuinely needs no doc edit, state the one-line reason instead of
+editing a doc to satisfy the rule.
+
+Detection + the framework-agnostic surface→doc map (Laravel / Symfony /
+Next.js / Python / Go) live in [`agent-docs-writing`](../skills/agent-docs-writing/SKILL.md)
+§ Doc-Impact — run it after every code change.
 
 ## Breaking changes
 
@@ -78,3 +107,4 @@ After completing all downstream changes:
 3. **No broken types / signatures** — project's type-checker (PHPStan / Psalm, TypeScript, mypy / pyright, `go vet`, `cargo check`).
 4. **No stale references** — grep for the old name / namespace / import path to confirm zero results.
 5. **No own-orphans** — the same sweep applied to the new diff: identifiers whose last reference disappeared in a file this diff touched are removed in the same diff (see [`minimal-safe-diff § Own-orphan cleanup`](minimal-safe-diff.md#own-orphan-cleanup)); pre-existing dead code stays.
+6. **No doc drift** — a public surface changed this diff has its describing doc updated (or the one-line no-doc-needed reason stated), per Doc-Impact above.

package/dist/agent-src/skills/agent-docs-writing/SKILL.md

@@ -189,29 +189,47 @@ After making changes, check if docs need updating:
 - **Structural changes** → update affected docs in `./agents/`
 - **New patterns** → update or create guideline docs
 
-## Doc sync check (after code changes)
+## Doc-Impact — the mandatory check after every code change
 
-After completing a significant code change, run this mental checklist:
+This is the detection procedure the [`downstream-changes`](../../rules/downstream-changes.md)
+§ Doc-Impact obligation points at. **Run it after every code change** — the
+*detection* is non-optional; the human still confirms the actual edit.
 
-| What changed | Doc to check |
+**Step 1 — did a public surface change?** Framework-agnostic surface list:
+
+| Public surface changed | Doc that describes it — update in the same change |
 |---|---|
-| Database schema (migration) | `agents/reference/docs/database-setup.md` |
-| New API endpoint | OpenAPI annotations, `AGENTS.md` API section |
-| New module created | Create `{module_root}/{Module}/{agent_folder}/` (resolve via `modules.root_paths` + `modules.agent_folder`) |
-| Service/repository signature changed | Check if referenced in `agents/reference/docs/services-and-repos.md` |
-| New environment variable | `.env.example`, `AGENTS.md` environment section |
-| Docker/compose change | `agents/reference/docs/docker.md`, `Makefile` documentation |
-| New Artisan command | `AGENTS.md` commands section |
-| New pattern/convention introduced | Relevant guideline in `.augment/guidelines/` |
-
-**When unsure** — ask with numbered options:
+| HTTP route / endpoint (Laravel `routes/`, Next.js `app/api`, FastAPI/Express handlers, Go mux) | OpenAPI / API reference, `README` usage, `AGENTS.md` API section |
+| Exported function / class / method signature | The doc/example that calls it; `agents/reference/docs/services-and-repos.md` if referenced |
+| CLI command or flag | `README` usage, `AGENTS.md` commands section, `--help` text |
+| Config / settings key | Settings doc, `README` config section, schema/example file |
+| Environment variable | `.env.example`, `AGENTS.md` environment section |
+| DB schema / migration | `agents/reference/docs/database-setup.md` |
+| Event payload / job constructor | The listener/consumer doc that documents the contract |
+| New module | `{module_root}/{Module}/{agent_folder}/` (resolve via `modules.root_paths` + `modules.agent_folder`) |
+| New pattern / convention | Relevant guideline in `.augment/guidelines/` |
+| Architectural decision | [`adr-create`](../adr-create/SKILL.md) — numbered ADR + index regen |
+
+**Step 2 — apply the fire/no-fire test.** Drift is a **falsifiable-claim
+contradiction**, not incompleteness:
+
+- **FIRE** (doc is now wrong — a reader would be misled): endpoint no longer
+  exists, wrong return type, renamed key, removed flag, broken code example.
+- **DO NOT FIRE** (completeness / quality only): the doc is high-level and
+  omits a new internal detail it never claimed to list; "could be clearer".
+
+**Step 3 — escape hatch.** Refactor-only / no public-surface change → no doc
+obligation. Surface changed but genuinely needs no doc edit → state the
+one-line reason; never edit a doc just to satisfy the rule (false-positive
+fatigue is worse than a missed nit).
+
+**When a doc edit IS needed but you are unsure of the wording** — flag it with
+numbered options; do NOT auto-rewrite prose without the user's knowledge:
 ```
 > 1. Yes — update the docs
-> 2. No — leave as-is
+> 2. No — leave as-is (reason: …)
 ```
 
-Do NOT auto-update docs without the user's knowledge. Flag what needs updating and let the user decide.
-
 ## Rules
 
 - All `.md` files must be in **English**.