@event4u/agent-config 8.4.1 → 8.6.0

package/dist/agent-src/commands/{review-changes.md → review/changes.md}

@@ -5,8 +5,10 @@ pack: engineering-base
 intent: "Multi-judge review of the current diff — bugs, security, tests, quality, architecture"
 routes_to: [code-review, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens]
 replaces: []
-tier: 1
-visibility: advanced
+tier: 2
+visibility: internal
+sub: changes
+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:
@@ -72,11 +74,11 @@ PR body, commit messages) and runs independently. The judges are:
 
 | Sub-skill | Focus |
 |---|---|
-| [`judge-bug-hunter`](../skills/judge-bug-hunter/SKILL.md) | Correctness, null-safety, edge cases, races, error handling |
-| [`judge-security-auditor`](../skills/judge-security-auditor/SKILL.md) | AuthZ/AuthN, injection, secrets, unsafe deserialization, SSRF, XSS |
-| [`judge-test-coverage`](../skills/judge-test-coverage/SKILL.md) | Missing assertions, uncovered branches, over-mocking, regression-test gaps |
-| [`judge-code-quality`](../skills/judge-code-quality/SKILL.md) | Naming, SRP, DRY, dead code, consistency with codebase conventions |
-| [`architecture-review-lens`](../skills/architecture-review-lens/SKILL.md) | Layer violations, dependency direction, leaky abstractions, cross-service contract drift |
+| [`judge-bug-hunter`](../../skills/judge-bug-hunter/SKILL.md) | Correctness, null-safety, edge cases, races, error handling |
+| [`judge-security-auditor`](../../skills/judge-security-auditor/SKILL.md) | AuthZ/AuthN, injection, secrets, unsafe deserialization, SSRF, XSS |
+| [`judge-test-coverage`](../../skills/judge-test-coverage/SKILL.md) | Missing assertions, uncovered branches, over-mocking, regression-test gaps |
+| [`judge-code-quality`](../../skills/judge-code-quality/SKILL.md) | Naming, SRP, DRY, dead code, consistency with codebase conventions |
+| [`architecture-review-lens`](../../skills/architecture-review-lens/SKILL.md) | Layer violations, dependency direction, leaky abstractions, cross-service contract drift |
 
 The five judges weight equally in the consolidated verdict — none
 overrides another.
@@ -89,7 +91,7 @@ Pick dispatch mode based on diff size and environment:
 - **Parallel** — if `subagents.max_parallel` in `.agent-settings.yml` is
   ≥ 5 and subagent dispatch is available, run all five concurrently
   following the `do-in-parallel` pattern in
-  [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md);
+  [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md);
   the five judges operate on the same diff but produce independent
   reports, so no shared-state risk
 
@@ -130,19 +132,19 @@ If picked **2** → continue with internal judges only.
 
 ### 5. Consolidate
 
-Consolidate via [`judge-synthesis`](../skills/judge-synthesis/SKILL.md) — the
-canonical cross-judge aggregation format. It consumes the step-4 verdict blocks
-(plus any 4b council blocks) and produces one report:
+Consolidate via [`judge-synthesis`](../../skills/judge-synthesis/SKILL.md) — the
+canonical cross-judge aggregation format. It consumes the verdict blocks from
+step 4 (plus any external council blocks from 4b) and produces one report:
 
 - A side-by-side verdict table (one row per judge, its own verdict word)
-- **Consensus** findings flagged by ≥2 judges — highest-confidence items
+- **Consensus** findings flagged by ≥2 judges — the highest-confidence items
 - **Conflicts** where judges disagree on the same target — surfaced, not
   silently resolved
 - A **must-fix / should-fix / advisory** split, each entry tagged with the
   judge(s) that raised it
 
-No single quality score; never auto-gates — it structures the verdicts so the
-next step's decision is informed.
+`judge-synthesis` emits no single quality score and never auto-gates — it
+structures the verdicts so the next step's decision is informed.
 
 ### 6. Decide next steps
 
@@ -153,11 +155,11 @@ next step's decision is informed.
 - If all five returned `apply` → the diff is ready; report and stop
 
 **Opt-in (never auto-on):** when the `revise` findings are *test-driven*
-(failing checks, not subjective craft) and you want bounded auto-repair before
-re-review, hand off to
-[`verify-repair-loop`](../skills/verify-repair-loop/SKILL.md) — a
+(failing checks, not subjective craft) and you want bounded auto-repair
+before re-review, hand off to
+[`verify-repair-loop`](../../skills/verify-repair-loop/SKILL.md) — a
 generate→run→revise→re-run loop gated by a numeric threshold, then a judge
-confirms. Surface as a single follow-up line; do not auto-invoke.
+confirms. Surface it as a single follow-up line; do not auto-invoke.
 
 ### 7. Quality tools (verbosity-gated)
 
@@ -173,7 +175,7 @@ Per `verbosity.routine_confirmations` (default `false`):
   If yes, hand off to the project's quality workflow (e.g.
   `/quality-fix` or the equivalent configured command). The quality and
   test runners are resolved per-stack via the
-  [`toolchain-resolver`](../contexts/execution/toolchain-resolver.md), so
+  [`toolchain-resolver`](../../contexts/execution/toolchain-resolver.md), so
   the hand-off adapts to PHP / JS-TS / Python / Go / Rust rather than
   assuming one stack.
 
@@ -212,13 +214,13 @@ Per `verbosity.routine_confirmations` (default `false`):
 ## See also
 
 - [`/prepare-for-review`](prepare-for-review.md) — updates `main` and merges the full base-branch chain into the target branch (used by step 1)
-- [`judge-synthesis`](../skills/judge-synthesis/SKILL.md) — the cross-judge consolidation format used in step 5 (consensus / conflicts / must-fix, no opaque score)
-- [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — dispatch and model-pairing rules
+- [`judge-synthesis`](../../skills/judge-synthesis/SKILL.md) — the cross-judge consolidation format used in step 5 (consensus / conflicts / must-fix, no opaque score)
+- [`subagent-orchestration`](../../skills/subagent-orchestration/SKILL.md) — dispatch and model-pairing rules
 - [`/do-and-judge`](do-and-judge.md) — implementer + judge loop for a single change
-- [`verify-repair-loop`](../skills/verify-repair-loop/SKILL.md) — opt-in test-verdict-gated iterate-to-green loop (step 6 hand-off); judge confirms after the numeric gate
+- [`verify-repair-loop`](../../skills/verify-repair-loop/SKILL.md) — opt-in test-verdict-gated iterate-to-green loop (step 6 hand-off); judge confirms after the numeric gate
 - [`/judge`](judge.md) — standalone judge, no review-changes dispatch
-- [`code-review`](../skills/code-review/SKILL.md) — human-oriented review patterns (tone, feedback handling)
-- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
+- [`code-review`](../../skills/code-review/SKILL.md) — human-oriented review patterns (tone, feedback handling)
+- [`role-contracts`](../../../docs/guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
 
 ## References
 

package/dist/agent-src/commands/{review-routing.md → review/routing.md}

@@ -1,9 +1,11 @@
 ---
 model_tier: high
 name: review-routing
-pack: meta
+pack: engineering-base
 tier: 2
 visibility: internal
+sub: routing
+cluster: review
 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
 suggestion:
@@ -19,11 +21,13 @@ packs:
 # review-routing
 
 > **Intentionally a command, not a skill** (ADR-057, road-to-6.2.0 Step 7b).
-> Meta-tool that debugs task-routing itself. A skill reached only by
-> description-match cannot debug a broken description-matcher (circular
-> dependency); the explicit `/review-routing` command is the guaranteed
-> debug-bypass. Skill-conversion gate **declined**; the `review-routing` skill
-> remains the implementation this command dispatches to.
+> This is a meta-tool used to debug task-routing itself. Converting it to a
+> skill would make it reachable *only* by description-match — useless when the
+> description-matcher is the thing being debugged (a circular dependency). The
+> explicit `/review-routing` command is the guaranteed debug-bypass, reachable
+> regardless of routing health. The `replaces:`/skill-conversion gate is
+> therefore **declined**; the `review-routing` skill below remains the
+> implementation this command dispatches to.
 
 ## Instructions
 
@@ -31,9 +35,9 @@ Produce a review-routing block for the current diff — owner-mapped
 reviewer roles plus any matched historical bug patterns — so the author
 knows *who* to request and *what* to test before opening a PR.
 
-Dispatches to [`review-routing`](../skills/review-routing/SKILL.md) for
+Dispatches to [`review-routing`](../../skills/review-routing/SKILL.md) for
 the core resolution logic. The rule
-[`reviewer-awareness`](../rules/reviewer-awareness.md) governs reviewer
+[`reviewer-awareness`](../../rules/reviewer-awareness.md) governs reviewer
 choice, routing, and data handling.
 
 ### 1. Gather the diff
@@ -45,7 +49,7 @@ choice, routing, and data handling.
 
 ### 2. Dispatch to the skill
 
-Invoke [`review-routing`](../skills/review-routing/SKILL.md) with the
+Invoke [`review-routing`](../../skills/review-routing/SKILL.md) with the
 changed-file list. The skill:
 
 1. Loads `ownership-map.yml` and `historical-bug-patterns.yml` (both
@@ -56,7 +60,7 @@ changed-file list. The skill:
 5. Returns the structured block.
 
 If neither data file exists, the skill returns the generic fallback
-from [`reviewer-awareness`](../rules/reviewer-awareness.md). That is
+from [`reviewer-awareness`](../../rules/reviewer-awareness.md). That is
 valid output — do not invent owners.
 
 ### 3. Present the result
@@ -72,7 +76,7 @@ Append, if present:
 - **Staleness warning** — ownership map > 6 months old.
 - **Required tests** — extracted from matched historical patterns, as a
   follow-up checklist the author must honour before claiming completion
-  ([`verify-before-complete`](../rules/verify-before-complete.md)).
+  ([`verify-before-complete`](../../rules/verify-before-complete.md)).
 
 ### 4. Decide next step
 
@@ -86,7 +90,7 @@ After the block, ask:
 ```
 
 - On **1**: hand off to
-  [`create-pr-description`](../skills/create-pr:description-only/SKILL.md).
+  [`create-pr-description`](../../skills/create-pr:description-only/SKILL.md).
 - On **2**: respect CODEOWNERS — request the *roles* resolved to people
   by the consumer's own mapping, never invent usernames.
 - On **3**: the user wants to curate the map first. Stop.
@@ -116,11 +120,11 @@ After the block, ask:
 
 ## See also
 
-- [`review-routing`](../skills/review-routing/SKILL.md) — the resolver
-- [`reviewer-awareness`](../rules/reviewer-awareness.md) — role vocabulary + data-source rules
-- [`review-routing-data-format`](../docs/guidelines/agent-infra/review-routing-data-format.md)
+- [`review-routing`](../../skills/review-routing/SKILL.md) — the resolver
+- [`reviewer-awareness`](../../rules/reviewer-awareness.md) — role vocabulary + data-source rules
+- [`review-routing-data-format`](../../../docs/guidelines/agent-infra/review-routing-data-format.md)
   — YAML schemas
-- [`create-pr-description`](../skills/create-pr:description-only/SKILL.md) —
+- [`create-pr-description`](../../skills/create-pr:description-only/SKILL.md) —
   consumes the routing block
-- [`verify-before-complete`](../rules/verify-before-complete.md) —
+- [`verify-before-complete`](../../rules/verify-before-complete.md) —
   consumes the `required_test` list

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

@@ -0,0 +1,61 @@
+---
+model_tier: medium
+name: review
+disable-model-invocation: true
+pack: engineering-base
+intent: "Review dispatcher — multi-judge self-review of the current diff, or reviewer routing"
+routes_to: [review-changes, review-routing]
+replaces: []
+tier: 1
+visibility: advanced
+description: Review orchestrator — routes to changes (five-judge self-review of the local diff) and routing (compute reviewer roles + historical bug patterns)
+cluster: review
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "review my changes before the PR, who should review this diff"
+  trigger_context: "uncommitted or staged changes pre-PR, or an open PR without reviewers"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /review
+
+Top-level orchestrator for the `/review` family — pre-PR self-review and
+reviewer selection.
+
+> Preparing the **branch** for a human review pass (update main, merge the
+> branch chain)? That is the standalone
+> [`/prepare-for-review`](prepare-for-review.md).
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/review changes` | `commands/review/changes.md` | Self-review local changes before creating a PR — five specialized judges (bug, security, tests, quality, architecture), consolidated verdicts |
+| `/review routing` | `commands/review/routing.md` | Compute reviewer roles + matched historical bug patterns for the current diff (ownership-map.yml, historical-bug-patterns.yml) |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/review <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the corresponding `commands/review/<sub>.md` file and
+   follow its `## Instructions` (or `## Steps`) section verbatim.
+4. If the sub-command is unknown or missing, print the menu and ask — do not
+   guess:
+
+   > 1. changes — five-judge self-review of the local diff (pre-PR)
+   > 2. routing — suggest reviewers + surface matched historical bug patterns
+
+## Rules
+
+- **Verdict only, never auto-fix.** `/review changes` reports findings; fixes
+  are a separate, user-authorized step.
+- **Do NOT chain sub-commands.** One `/review <sub>` per turn.
+- If the user invokes `/review` with no argument, **show the menu** — do not
+  guess which sub-command they meant.

package/dist/agent-src/commands/security-audit-config.md

@@ -21,11 +21,11 @@ packs:
 
 ## Instructions
 
-Audit a consumer's **assembled** agent config for the prompt-injection +
-supply-chain risks behind the "rules-file backdoor" and MCP tool-poisoning
-classes; report an A–F score per category mapped to the OWASP Top 10 for
-Agentic Applications. Consumer-facing counterpart to the suite's own
-`lint_agent_security` self-audit gate.
+Audit a consumer's **assembled** agent configuration for the prompt-injection
+and supply-chain risks behind the "rules-file backdoor" and MCP tool-poisoning
+attack classes, and report an A–F score per category mapped to the OWASP Top 10
+for Agentic Applications. This is the consumer-facing counterpart to the
+suite's own `lint_agent_security` self-audit gate.
 
 ### 1. Run the static audit
 
@@ -33,36 +33,37 @@ Agentic Applications. Consumer-facing counterpart to the suite's own
 ./scripts-run src/scripts/security_audit_config --root <repo> --json
 ```
 
-(omit `--root` to audit the current repo). Reuses the Phase-1 detection library
-under the containment convention
-([`security-lint-containment`](../docs/guidelines/agent-infra/security-lint-containment.md)),
-so doc/example files don't tank the score. Scans instruction files (`CLAUDE.md`,
-`AGENTS.md`, `.cursor/rules`, `.github/copilot-instructions.md`, `.clinerules`,
-`.windsurfrules`), MCP configs (`.mcp.json`, `.cursor/mcp.json`,
-`claude_desktop_config.json`), settings/hooks (`.claude/settings.json`),
+(omit `--root` to audit the current repo). The script reuses the Phase-1
+detection library under the false-positive containment convention
+([`security-lint-containment`](../../../docs/guidelines/agent-infra/security-lint-containment.md)),
+so doc/example files do not tank the score. It scans instruction files
+(`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.github/copilot-instructions.md`,
+`.clinerules`, `.windsurfrules`), MCP configs (`.mcp.json`, `.cursor/mcp.json`,
+`claude_desktop_config.json`), settings/hooks (`.claude/settings.json`), and
 installed skills.
 
 ### 2. Present the score
 
-Surface the overall grade + five category grades (Secrets · Permissions · Hooks
-· MCP · Agents/Rules), each with its OWASP-ASI tag, then the findings worth
-acting on (HIGH first). Lead with the worst category.
+Surface the overall grade + the five category grades (Secrets · Permissions ·
+Hooks · MCP · Agents/Rules), each with its OWASP-ASI tag, then list the
+findings worth acting on (HIGH first). Lead with the worst category.
 
 ### 3. Optional deep pass
 
-When asked for depth, or any category scores **D/F**, escalate:
+When the user asks for depth, or any category scores **D or F**, escalate:
 
 - Dispatch [`judge-security-auditor`](../skills/judge-security-auditor/SKILL.md)
   over the flagged files for a diff-level verdict.
-- For a red/blue/auditor review of the whole config, hand off to the
-  `agent-security-review` skill (`council_depth: deep`).
+- For a red-team / blue-team / auditor adversarial review of the whole config,
+  hand off to the `agent-security-review` skill (`council_depth: deep`).
 
 ### 4. Recommend, do not auto-fix
 
-Output is **decision support**, not a gate — detection is probabilistic.
-Recommend the fix per finding (secret → `${env:VAR}`, pin an MCP server, remove
-`bypassPermissions`, strip hidden Unicode), but never rewrite the consumer's
-config without confirmation (per [`scope-control`](../../../src/rules/scope-control.md)).
+Output is **decision support**, not a gate — detection is probabilistic
+(guardrails are evadable). Recommend the fix per finding (move a secret to
+`${env:VAR}`, pin an MCP server, remove a `bypassPermissions` flag, strip
+hidden Unicode), but never rewrite the consumer's config without confirmation
+(per [`scope-control`](../../../src/rules/scope-control.md)).
 
 ## Output format
 
@@ -80,5 +81,5 @@ Overall: B (84/100)
 ## See also
 
 - [`lint_agent_security`](../../../src/scripts/lint_agent_security.ts) — the self-audit (our own corpus) sibling.
-- [`untrusted-input-defense`](../../rules/untrusted-input-defense.md), [`lethal-trifecta-guard`](../../rules/lethal-trifecta-guard.md) — the always-on prevention rules.
+- [`untrusted-input-defense`](../../../src/rules/untrusted-input-defense.md), [`lethal-trifecta-guard`](../../../src/rules/lethal-trifecta-guard.md) — the always-on prevention rules.
 - [`/threat-model`](../threat-model/command.md), [`judge-security-auditor`](../skills/judge-security-auditor/SKILL.md) — deep-pass dispatch.

package/dist/agent-src/commands/{sync-agent-settings.md → sync/agent-settings.md}

@@ -4,6 +4,8 @@ name: sync-agent-settings
 pack: meta
 tier: 2
 visibility: internal
+sub: agent-settings
+cluster: sync
 skills: [sync-agent-settings]
 description: Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing
 suggestion:
@@ -23,7 +25,7 @@ Reconciles `.agent-settings.yml` with the shipped template
 (`config/agent-settings.template.yml`) and the selected cost-profile
 preset (`config/profiles/{profile}.ini`). Applies the section-aware
 merge rules documented in
-[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md):
+[`layered-settings`](../../../docs/guidelines/agent-infra/layered-settings.md):
 
 - Template section order wins — keys reorder to match.
 - Existing user scalar values are preserved.
@@ -61,7 +63,9 @@ The sync script ships in the installed package. Resolve in order:
 2. `vendor/event4u/agent-config/scripts/sync_agent_settings.ts` — Composer.
 3. `node_modules/@event4u/agent-config/scripts/sync_agent_settings.ts` — npm.
 
-Target is always `<project_root>/.agent-settings.yml`.
+Target is always the canonical `.agent-settings.yml` under `agents/settings/`; a legacy
+repo-root `.agent-settings.yml` is read as a fallback and migrated into the
+canonical location, never written afresh (ADR-038). Pass `--path` to override.
 
 ### 2. Dry-run — show the user what would change
 
@@ -134,9 +138,9 @@ is a local-agent concern.
 
 ## See also
 
-- [`scripts/sync_agent_settings.ts`](../../../scripts/sync_agent_settings.ts) — the helper
-- [`config/agent-settings.template.yml`](../../../config/agent-settings.template.yml) — canonical template
-- [`config/profiles/`](../../../config/profiles/) — profile presets
-- [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — the merge rules this command enforces
-- [`scripts/install.ts`](../../../scripts/install.ts) — first-install path; this command handles the update path
+- [`scripts/sync_agent_settings.ts`](../../../../scripts/sync_agent_settings.ts) — the helper
+- [`config/agent-settings.template.yml`](../../../../config/agent-settings.template.yml) — canonical template
+- [`config/profiles/`](../../../../config/profiles/) — profile presets
+- [`layered-settings`](../../../docs/guidelines/agent-infra/layered-settings.md) — the merge rules this command enforces
+- [`scripts/install.ts`](../../../../scripts/install.ts) — first-install path; this command handles the update path
 - [`/sync-gitignore`](sync-gitignore.md) — sibling command for the `.gitignore` block

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

@@ -1,11 +1,11 @@
 ---
 model_tier: medium
 name: sync-gitignore-fix
-pack: engineering-base
+pack: meta
 tier: 2
 visibility: internal
-cluster: sync-gitignore
-sub: fix
+cluster: sync
+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:
@@ -20,21 +20,21 @@ packs:
 
 # /sync-gitignore:fix
 
-Cleanup sibling of [`/sync-gitignore`](../sync-gitignore.md). Strips
+Cleanup sibling of [`/sync-gitignore`](../gitignore.md). Strips
 legacy patterns (pre-`/agents/` runtime artefacts —
 `.agent-chat-history`, `.agent-chat-history.bak`,
 `.agent-chat-history.*.bak`, `.agent-prices.md`, `.council-tmp/` —
 plus the 2.x intermediate `agents/runtime/.agent-prices.md`) from **anywhere**
 in the consumer's `.gitignore` — inside or outside the managed block —
 then re-runs the regular sync so the current canonical entries
-(`/agents/runtime/.agent-chat-history`, `/agents/runtime/.agent-prices.md`,
-`/agents/runtime/council/`) land in the block.
+(`/agents/runtime/` catch-all, plus the legacy back-compat lines
+`/agents/.agent-chat-history*`) land in the block.
 
 Use when:
 
 - An older installer (pre-May 2026) dropped root-level `.agent-chat-history`
   / `.agent-prices.md` lines that the current scripts no longer recognise.
-- A 2.x install left `/agents/.agent-prices.md` in the block before the
+- A 2.x install left `/agents/runtime/.agent-prices.md` in the block before the
   cache moved under `/agents/runtime/`.
 - A hand-edit added one of those legacy paths and it now conflicts with
   the managed `/agents/...` entry.
@@ -56,7 +56,7 @@ Use when:
 
 ### 1. Locate script and target
 
-Same resolution order as [`/sync-gitignore`](../sync-gitignore.md):
+Same resolution order as [`/sync-gitignore`](../gitignore.md):
 
 1. `./agent-config/scripts/sync_gitignore.ts`
 2. `vendor/event4u/agent-config/scripts/sync_gitignore.ts`
@@ -117,9 +117,9 @@ If the cleanup removed `.agent-chat-history` or any flavour of
 `.agent-prices.md`, mention that the **file** itself (if still present
 at its old location) may need to move. The installer does this
 automatically via
-[`migrate_legacy_root_infra`](../../../scripts/install.sh) (chat-history,
+[`migrate_legacy_root_infra`](../../../../scripts/install.sh) (chat-history,
 root → `agents/`) and
-[`migrate_legacy_prices_file`](../../../scripts/install.sh) (prices,
+[`migrate_legacy_prices_file`](../../../../scripts/install.sh) (prices,
 root or `agents/` → `agents/runtime/`); the agent does not run them
 from this command. One line of guidance is enough:
 
@@ -141,46 +141,55 @@ from this command. One line of guidance is enough:
 
 ### 5. Ignored-but-tracked detection pass
 
-After the legacy-cleanup sync, run the tracked-but-ignored check:
+After the legacy-cleanup sync, run the tracked-but-ignored check
+and surface any files that are now in the ignore list but still committed:
 
 ```bash
 npx tsx node_modules/@event4u/agent-config/src/scripts/check_tracked_but_ignored.ts
 ```
 
-Files reported →
+If files are reported:
 
 ```
-> ⚠️  Tracked but now ignored — will appear in every `git status` until untracked.
-> Fix (files stay on disk):
+> ⚠️  The following files are tracked by git but now covered by an ignore
+> pattern. They will appear in every `git status` until untracked.
+>
+> To remove them from the index (files stay on disk):
 >
 >   git rm --cached \
 >     <file1> \
 >     <file2>
 >
-> Then commit. One-time cleanup.
+> Then commit the result. This is a one-time cleanup.
 ```
 
-NEVER run `git rm --cached` automatically — git-ops are user-owned.
+Do NOT run `git rm --cached` automatically — git-ops are user-owned.
 
-### 6. Agent artefacts not covered
+### 6. Agent artefacts not covered by the managed block
 
-Manifest-vs-block coverage check (`agents-paths.yml` is the reference):
+Scan for known agent-artefact shapes that are neither ignored nor
+legitimately tracked. Use `agents-paths.yml` as the reference:
 
 ```bash
 npx tsx node_modules/@event4u/agent-config/src/scripts/check_gitignore_freshness.ts
 ```
 
-Fails → offer block re-sync (option 1 sync / 2 skip).
+If the check fails, offer to re-sync the block with the current template:
+
+```
+> ⚠️  gitignore-block.txt has entries not yet in your .gitignore.
+> Run option 1 to sync, or 2 to skip.
+```
 
 ## See also
 
-- [`/sync-gitignore`](../sync-gitignore.md) — append-only sync of the
+- [`/sync-gitignore`](../gitignore.md) — append-only sync of the
   managed block (no legacy cleanup)
-- [`scripts/sync_gitignore.ts`](../../../src/scripts/sync_gitignore.ts) —
+- [`scripts/sync_gitignore.ts`](../../../../src/scripts/sync_gitignore.ts) —
   the helper (`--cleanup-legacy` flag)
-- [`scripts/check_tracked_but_ignored.ts`](../../../src/scripts/check_tracked_but_ignored.ts) —
-  ignored-but-tracked detection
-- [`scripts/check_gitignore_freshness.ts`](../../../src/scripts/check_gitignore_freshness.ts) —
-  manifest vs block coverage
-- [`docs/contracts/agents-layout.md`](../../../docs/contracts/agents-layout.md) —
-  classification contract for `agents/` entries
+- [`scripts/check_tracked_but_ignored.ts`](../../../../src/scripts/check_tracked_but_ignored.ts) —
+  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) —
+  full classification contract for `agents/` entries

package/dist/agent-src/commands/{sync-gitignore.md → sync/gitignore.md}

@@ -1,10 +1,11 @@
 ---
 model_tier: medium
 name: sync-gitignore
-pack: engineering-base
+pack: meta
 tier: 2
 visibility: internal
-cluster: sync-gitignore
+sub: gitignore
+cluster: sync
 skills: [sync-gitignore]
 description: Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing
 suggestion:
@@ -16,25 +17,25 @@ packs:
   - meta
 ---
 
-# /sync-gitignore
+# /sync gitignore
 
-Top-level entry point for the `/sync-gitignore` family. Bare `/sync-gitignore`
-runs the interactive append-only sync described below. The `:fix`
-sub-command additionally scrubs legacy patterns (pre-`/agents/` layout)
-from anywhere in the consumer's `.gitignore` before re-syncing.
+`.gitignore` sub-family of the [`/sync`](../sync.md) cluster. Bare
+`/sync gitignore` runs the interactive append-only sync described below. The
+`gitignore-fix` sibling additionally scrubs legacy patterns (pre-`/agents/`
+layout) from anywhere in the consumer's `.gitignore` before re-syncing.
 
 ## Sub-commands
 
 | Sub-command | Routes to | Purpose |
 |---|---|---|
-| `/sync-gitignore` (bare) | this file (`## Default flow`) | Interactive — append-only sync of the managed block, dry-run preview, confirm before write |
-| `/sync-gitignore:fix` | `commands/sync-gitignore/fix.md` | Cleanup — strip legacy root-level patterns (pre-`/agents/` layout) wherever they appear, then sync |
+| `/sync gitignore` (bare) | this file (`## Default flow`) | Interactive — append-only sync of the managed block, dry-run preview, confirm before write |
+| `/sync gitignore-fix` | `commands/sync/gitignore/fix.md` | Cleanup — strip legacy root-level patterns (pre-`/agents/` layout) wherever they appear, then sync |
 
 ## Dispatch
 
-1. Parse the user's argument: `/sync-gitignore[:<sub>] [args]`.
-2. Bare `/sync-gitignore` → run the `## Default flow` below verbatim.
-3. `/sync-gitignore:fix` → load `commands/sync-gitignore/fix.md` and follow
+1. Parse the user's argument: `/sync gitignore[-fix] [args]`.
+2. Bare `/sync gitignore` → run the `## Default flow` below verbatim.
+3. `/sync gitignore-fix` → load `commands/sync/gitignore/fix.md` and follow
    its `## Steps` section verbatim.
 4. Unknown sub-command → print the table above and ask which one.
 
@@ -42,7 +43,7 @@ from anywhere in the consumer's `.gitignore` before re-syncing.
 
 Ensures the consumer project's `.gitignore` contains every entry the
 package expects to be ignored (symlinked `.augment/` subdirectories,
-`/agent-config` CLI wrapper, `.agent-settings*`, `agents/runtime/.agent-chat-history*`).
+`/agent-config` CLI wrapper, `.agent-settings*`, `/agents/runtime/` catch-all).
 Canonical list lives in `config/gitignore-block.txt`; the same file
 drives the installer, so the two cannot drift.
 
@@ -63,7 +64,7 @@ Use when:
 - To change what the block contains → edit
   `config/gitignore-block.txt` in the package repo and re-release.
 - To clean up legacy garbage from older installs → use
-  [`/sync-gitignore:fix`](sync-gitignore/fix.md) instead.
+  [`/sync gitignore-fix`](gitignore/fix.md) instead.
 
 ### 1. Locate script and target
 
@@ -78,7 +79,7 @@ Target is always `<project_root>/.gitignore`. If no `.gitignore` exists,
 stop and tell the user — the package does not create one unilaterally:
 
 ```
-> 📝 No .gitignore found at <project_root>. Create one first (e.g. `touch .gitignore`), then re-run /sync-gitignore.
+> 📝 No .gitignore found at <project_root>. Create one first (e.g. `touch .gitignore`), then re-run /sync gitignore.
 ```
 
 ### 2. Dry-run — show the user what would change
@@ -93,7 +94,7 @@ Run the script with `--dry-run` and capture stdout. Three outcomes:
 - **Additions only** (default append-only mode) → show the unified
   diff and ask:
   ```
-  > 📝 /sync-gitignore would add {N} entr{y|ies} to .gitignore:
+  > 📝 /sync gitignore would add {N} entr{y|ies} to .gitignore:
   >
   > {diff}
   >
@@ -121,7 +122,7 @@ full and drops user-added lines inside the block — destructive.
 Mention it only if the user explicitly asks to clean up or reset the
 block, and confirm once more before running it. For removing legacy
 root-level patterns (not user-added lines), prefer
-[`/sync-gitignore:fix`](sync-gitignore/fix.md).
+[`/sync gitignore-fix`](gitignore/fix.md).
 
 ## Rules
 
@@ -132,10 +133,10 @@ root-level patterns (not user-added lines), prefer
   They do not survive `--replace`.
 - Changes to `config/gitignore-block.txt` require a package update in
   the consumer project before this command can apply them.
-- **Do NOT chain sub-commands.** One `/sync-gitignore <sub>` per turn.
+- **Do NOT chain sub-commands.** One `/sync <sub>` per turn.
 
 ## See also
 
-- [`scripts/sync_gitignore.ts`](../../../scripts/sync_gitignore.ts) — the helper
-- [`config/gitignore-block.txt`](../../../config/gitignore-block.txt) — canonical block body
-- [`scripts/install.sh`](../../../scripts/install.sh) — installer integration (same source of truth, `--skip-gitignore` to opt out)
+- [`scripts/sync_gitignore.ts`](../../../../scripts/sync_gitignore.ts) — the helper
+- [`config/gitignore-block.txt`](../../../../config/gitignore-block.txt) — canonical block body
+- [`scripts/install.sh`](../../../../scripts/install.sh) — installer integration (same source of truth, `--skip-gitignore` to opt out)