@event4u/agent-config 1.29.0 → 1.31.0

package/.agent-src/commands/agents/audit.md

@@ -2,247 +2,151 @@
 name: agents:audit
 cluster: agents
 sub: audit
-description: Audits agents/ and module agents/ directories — finds outdated docs, structural issues, duplicates, orphaned overrides, and creates an improvement roadmap.
-skills: [agents-audit, agent-docs-writing, override-management, module-management]
+description: Audit agent infrastructure — token overhead, rule triggers, AGENTS.md health, Capability-over-Structure adherence, stale references. Read-only, suggest-only, never auto-apply.
+skills: [copilot-agents-optimization, agents-audit, agent-docs-writing, agents-md-thin-root, quality-tools]
 disable-model-invocation: true
 suggestion:
   eligible: true
-  trigger_description: "audit my agent docs, check the state of the agents/ directory"
-  trigger_context: "stale files under agents/ or recent edits to .augment/ without doc updates"
+  trigger_description: "audit agent infrastructure, check rule triggers, verify AGENTS.md health, agent-layer health-check"
+  trigger_context: "maintainer working on .augment/ files, AGENTS.md, or planning a refactor"
 ---
 
 # /agents audit
-Audits all agent documentation across the project — root `agents/`, module `app/Modules/*/agents/`,
-and `agents/overrides/`.
 
-## Steps
-
-### 1. Inventory all agent docs
-
-Scan all directories:
-
-```bash
-# Root-level docs
-find agents/ -maxdepth 1 -name '*.md' | sort
-
-# Subdirectories
-find agents/features/ agents/contexts/ -name '*.md' 2>/dev/null | sort
-
-# Overrides
-find agents/overrides/ -name '*.md' -not -name '.gitkeep' 2>/dev/null | sort
+Read-only health check of the **agent layer** — `AGENTS.md` (and tool stubs),
+rules, skills, and pointer/anchor integrity. Measures token overhead, surfaces
+duplicate triggers, verifies the Thin-Root contract, and flags stale references.
+**Suggest only — never auto-apply.** Fixes happen via `/agents optimize` (file
+refactor) or rule-/skill-level commands.
 
-# Guidelines
-find .augment/guidelines/ -name '*.md' | sort
+**Source of truth:** `.agent-src.uncompressed/` — never read or edit
+`.agent-src/` or `.augment/` directly.
 
-# Module-level docs (excluding roadmaps)
-find app/Modules/*/agents/ -name '*.md' -not -path '*/roadmaps/*' 2>/dev/null | sort
-```
-
-For each file, extract:
-- Filename and path
-- First heading (title)
-- File size and last git modification date (`git log -1 --format='%ai' -- {file}`)
+## Steps
 
-### 2. Scan module agents coverage
+### 1. Measure baseline
 
-Check every module for agent docs:
+Count lines affecting token consumption:
 
 ```bash
-for dir in app/Modules/*/; do
-  name=$(basename "$dir")
-  if [ -d "$dir/agents" ]; then
-    count=$(find "$dir/agents" -name '*.md' | wc -l | tr -d ' ')
-    echo "✅  $name — $count docs"
-  else
-    echo "❌  $name — no agents/ dir"
-  fi
-done
+# Always-loaded (per chat)
+for f in .agent-src.uncompressed/rules/*.md; do
+  type=$(head -5 "$f" | grep 'type:' | sed 's/.*"\(.*\)"/\1/')
+  [ "$type" = "auto" ] && continue
+  lines=$(wc -l < "$f"); echo "always | $lines | $(basename "$f")"
+done | sort -t'|' -k2 -rn
+agents=$(wc -l < AGENTS.md); echo "always | $agents | AGENTS.md"
+
+# Auto-loaded rules
+for f in .agent-src.uncompressed/rules/*.md; do
+  type=$(head -5 "$f" | grep 'type:' | sed 's/.*"\(.*\)"/\1/')
+  [ "$type" != "auto" ] && continue
+  lines=$(wc -l < "$f"); echo "auto | $lines | $(basename "$f")"
+done | sort -t'|' -k2 -rn
+
+# Skills (top 20 by size)
+for f in .agent-src.uncompressed/skills/*/SKILL.md; do
+  name=$(echo "$f" | sed 's|.agent-src.uncompressed/skills/||;s|/SKILL.md||')
+  lines=$(wc -l < "$f"); echo "$lines | $name"
+done | sort -rn | head -20
 ```
 
-For each module WITH agents, check structure:
-
-| Check | Expected | Severity |
-|---|---|---|
-| Module description file exists | `agents/{name}.md` or `agents/README.md` | 🟡 Warning |
+Report totals (always + auto + skills + AGENTS.md).
 
-| Features dir (if planned work) | `agents/features/` | 🔵 Info |
-| Contexts dir (if complex domain) | `agents/contexts/` | 🔵 Info |
-| Consistent format across modules | Same heading structure, same sections | 🔵 Info |
+### 2. Check rules
 
-### 3. Scan overrides
-
-For each override in `agents/overrides/`:
+- **Frontmatter**: every rule has `type: "always"` or `type: "auto"` with `description`.
+- **Duplicate triggers**: same `description` → both rules load simultaneously (waste).
+- **Redundancy**: a rule's content duplicated in AGENTS.md or a skill.
+- **Merge candidates**: rules under 15 lines that belong inside a sibling rule.
 
 ```bash
-find agents/overrides/ -name '*.md' -not -name '.gitkeep' | while read f; do
-  # Extract Mode and Original path from header
-  mode=$(grep -m1 'Mode:' "$f" | sed 's/.*`\(.*\)`.*/\1/')
-  original=$(grep -m1 'Original:' "$f" | sed 's/.*`\(.*\)`.*/\1/')
-  # Check if original exists
-  if [ -f "$original" ]; then
-    echo "✅  $f → $original ($mode)"
-  else
-    echo "❌  $f → $original (ORPHANED — original missing)"
-  fi
-done
+for f in .agent-src.uncompressed/rules/*.md; do
+  desc=$(head -5 "$f" | grep 'description:' | sed 's/.*"\(.*\)"/\1/')
+  [ -n "$desc" ] && echo "$desc | $(basename "$f")"
+done | sort | awk -F' \\| ' '{descs[$1]=descs[$1] " " $2} END {for (d in descs) {n=split(descs[d], a, " "); if (n>1) print "⚠️  " d " →" descs[d]}}'
 ```
 
-| Check | Severity |
-|---|---|
-| Override has valid `Mode` header (`extend` or `replace`) | 🔴 Critical if missing |
-| Override has valid `Original` path | 🔴 Critical if missing |
-| Original file exists | 🟡 Warning if orphaned |
-| Override content is not empty (beyond template) | 🟡 Warning if empty |
-
-### 4. Classify each document
-
-For each doc, determine its category:
-
-- **Architecture** — project-level architecture docs (DB, auth, tenancy)
-- **Convention** — coding guidelines and standards
-- **Pattern** — design pattern documentation
-- **Feature plan** — planned features
-- **Context** — codebase area snapshots
-- **Module doc** — module-specific documentation
-- **Override** — project-level override of shared resource
-- **Unclear** — doesn't fit a clear category
-
-### 5. Check for issues
-
-**Structural issues:**
-- Files in wrong directories (e.g., a guideline in `agents/` root)
-- Missing expected directories
-- Naming inconsistencies (not kebab-case)
-- Module docs that should be root-level (cross-module concern)
-- Root docs that should be module-level (single-module concern)
-
-**Content issues (for each doc):**
-- Read the file and extract referenced file paths, class names, method names
-- Use `codebase-retrieval` or file checks to verify references still exist
-- Flag references to deleted/renamed code
-
-**Duplication:**
-- Compare doc topics — are two docs covering the same thing?
-- Check overlap between `agents/` docs and `.augment/skills/` content
-- Check overlap between root docs and `.augment/guidelines/` docs
-- Check overlap between module docs and root docs
-
-**Coverage gaps:**
-- Active modules without any agent docs
-- Complex areas (many files, many services) without documentation
-- Overrides that reference sections no longer in the original
-
-### 6. Display audit report
+### 3. Check `always` → `auto` candidates
 
-```
-═══════════════════════════════════════════════
-  🔍  AGENTS AUDIT
-═══════════════════════════════════════════════
+Apply `rule-type-governance`:
 
-📁  Scanned: {total} files in {dirs} directories
+1. Applies to EVERY conversation? → keep `always`.
+2. Triggered by a specific topic? → candidate for `auto`.
+3. Core behavior constraint (`scope-control`, `verify-before-complete`, `token-efficiency`, `commit-policy`, `non-destructive-by-default`)? → **NEVER change to auto**.
 
-───────────────────────────────────────────────
-INVENTAR
-───────────────────────────────────────────────
+Surface candidates with explicit justification. Never auto-apply.
 
-  Category         Count   Files
-  ───────────────  ──────  ────────────────────────────
-  Architecture     {n}     database-setup.md, ...
-  Convention       {n}     guidelines/controllers.md, ...
-  Pattern          {n}     guidelines/patterns/service-layer.md, ...
-  Feature          {n}     {or "keine"}
-  Context          {n}     {or "keine"}
-  Module Doc       {n}     Import/agents/import.md, ...
-  Override         {n}     overrides/skills/eloquent.md, ...
-  Unklar           {n}     {files that don't fit}
+### 4. Check AGENTS.md — Thin-Root + Capability-over-Structure
 
-───────────────────────────────────────────────
-MODULE AGENTS
-───────────────────────────────────────────────
+Run the linter and inspect output:
 
-  Module             Status  Docs  Description   Features  Contexts
-  ─────────────────  ──────  ────  ────────────  ────────  ────────
-  Import             ✅      3     ✅            ✅        ❌
-  Backoff            ✅      1     ✅            ❌        ❌
-  Grafana            ✅      2     ✅            ❌        ❌
-  ClientSoftware     ❌      0     ❌            ❌        ❌
-  ...
+```bash
+python3 scripts/lint_agents_md.py
+wc -c AGENTS.md
+```
 
-───────────────────────────────────────────────
-OVERRIDES
-───────────────────────────────────────────────
+Then audit against the **Capability-over-Structure heuristic** (canonical:
+[`agents-md-anatomy § Iron Law`](../../contexts/contracts/agents-md-anatomy.md#iron-law--capability-over-structure)):
 
-  Override                          Mode     Original  Status
-  ────────────────────────────────  ───────  ────────  ──────
-  {or "No overrides found"}
+- Every section answers a *what-the-agent-does* question, not *what-files-exist*.
+- Path bullets without why-clauses ≥ 60 chars → flag for rewrite as capability bullets.
+- Pointer ratio ≥ 0.40; emergency-triage block present and matches the canonical variant.
 
-───────────────────────────────────────────────
-ISSUES
-───────────────────────────────────────────────
+Failures route to `/agents optimize` — this command does **not** edit.
 
-🔴  Kritisch ({count}):
-  •  {file} — {issue description}
+### 5. Check docs sync + stale references
 
-🟡  Warnung ({count}):
-  •  {file} — {issue description}
+```bash
+python3 scripts/check_references.py
+```
 
-🔵  Info ({count}):
-  •  {file} — {improvement suggestion}
+Confirm counts/lists in `.augment/contexts/augment-infrastructure.md` and
+`docs/architecture.md` match the actual `.agent-src.uncompressed/` tree.
 
-⚪  Clean ({count} files without issues)
+### 6. Run skill linter
 
-───────────────────────────────────────────────
-DUPLICATES / OVERLAPS
-───────────────────────────────────────────────
+```bash
+python3 scripts/skill_linter.py --all --pairs --duplicates 2>&1 | grep "Summary:"
+```
 
-  •  {file1} ↔ {file2} — {what overlaps}
+Report FAIL/WARN counts. Don't fix here — delegate to `skill-reviewer` or
+`/optimize skills`.
 
-───────────────────────────────────────────────
-GAPS
-───────────────────────────────────────────────
+### 7. Present findings
 
-  ⚠️  Modules without docs: {list}
-  ⚠️  Missing contexts: {list}
-  ⚠️  Orphaned overrides: {list}
+Single table, no auto-edits:
 
-═══════════════════════════════════════════════
-```
+| # | Category | Finding | Impact | Suggested fix |
+|---|---|---|---|---|
+| 1 | Rule | `{name}` duplicate trigger | Both load simultaneously | Tighten `description` |
+| 2 | Rule | `{name}` is `always` but topic-specific | ~{n} lines saved/chat | Switch to `auto` (with safety gate) |
+| 3 | AGENTS.md | Path enumeration without why-clauses | Capability-over-Structure violation | Run `/agents optimize` |
+| ... | | | | |
 
-### 7. Create improvement roadmap
+Then ask:
 
 ```
-Create an improvement roadmap?
-
-1. ✅  Yes — create roadmap in agents/roadmaps/agents-cleanup.md
-2. 📋  Show recommendations only (no file creation)
-3. ❌  No — the audit was all that was needed
+> 1. Walk through suggestions one at a time
+> 2. Apply only high-impact changes (saves > 50 lines or fixes a FAIL)
+> 3. Report only — no edits
 ```
 
-**Option 1:** Create a roadmap using `.augment/templates/roadmaps.md` with phases:
+## What this command does NOT do
 
-- **Phase 1: Critical fixes** — orphaned overrides, broken references, broken structure
-- **Phase 2: Structural cleanup** — move misplaced files, merge duplicates
-- **Phase 3: Module docs** — create missing module descriptions and contexts
-- **Phase 4: Cleanup** — delete obsolete docs, clean up naming, align formats
-
-**Option 2:** Show recommendations inline without creating a file.
-
-### 8. Offer next steps
-
-```
-What next?
-
-1. 🧹  Start cleanup → /agents-cleanup
-2. 📄  Update a specific doc → /context-refactor
-3. ✅  Done
-```
+- **No edits** — read-only audit. Fixes route to `/agents optimize`,
+  `skill-reviewer`, or `/optimize skills`.
+- **No edits to `.agent-src/` or `.augment/`** — those regenerate from
+  `.agent-src.uncompressed/`. Edit the source.
+- **No `agents/` folder ops** — scaffolding, folder-audit, folder-cleanup
+  live in `/optimize agents-dir`.
+- **No commits, no push, no PR** — finishing the audit is a user decision
+  per [`commit-policy`](../../rules/commit-policy.md).
 
-## Rules
+## See also
 
-- **Do NOT modify or delete any files** — this command is analysis only.
-- **Do NOT commit or push.**
-- **Do NOT audit `agents/roadmaps/` or `app/Modules/*/agents/roadmaps/`** — roadmaps have their own lifecycle.
-- **Do NOT audit `.augment/`** — skills and rules are managed separately.
-- **Verify references against the actual codebase** — don't guess.
-- **Be specific about issues** — name the file, the reference, and what's wrong.
-- **Don't flag missing module docs for tiny/inactive modules** — only for active modules with significant code.
+- [`agents-md-thin-root`](../../skills/agents-md-thin-root/SKILL.md) — caps, pointer-ratio, anatomy.
+- [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md) — Iron Law, Capability-over-Structure heuristic.
+- [`rule-type-governance`](../../rules/rule-type-governance.md) — `always` vs `auto` decision rules.
+- [`/agents optimize`](optimize.md) — apply Thin-Root contract fixes.
+- [`/optimize agents-dir`](../optimize/agents-dir.md) — `agents/` folder operations (Phase 3).

package/.agent-src/commands/{copilot-agents → agents}/init.md

@@ -1,24 +1,32 @@
 ---
-name: copilot-agents:init
-cluster: copilot-agents
+name: agents:init
+cluster: agents
 sub: init
-description: Create AGENTS.md and .github/copilot-instructions.md from scratch in the consumer project — interactive, auto-detects stack, never leaks other projects' identifiers.
-skills: [copilot-config, copilot-agents-optimization, agent-docs-writing]
+description: Initialize the agent layer for a consumer project — creates AGENTS.md and .github/copilot-instructions.md from package templates, auto-detects stack, never leaks other projects' identifiers.
+skills: [copilot-config, copilot-agents-optimization, agent-docs-writing, agents-md-thin-root]
 disable-model-invocation: true
 suggestion:
   eligible: false
   rationale: "Project init — only deliberately during onboarding."
 ---
 
-# /copilot-agents init
+# /agents init
+
 Interactive initializer that **creates** `AGENTS.md` and
 `.github/copilot-instructions.md` in the consumer project from the
 package-shipped templates (`.augment/templates/AGENTS.md` and
 `.augment/templates/copilot-instructions.md`), filling in placeholders
 based on auto-detected stack + user answers.
 
+Tool-agnostic by design — AGENTS.md is the universal entry point
+honoured by Claude Code, Cursor, Codex, Copilot, Augment and Gemini.
+The `.github/copilot-instructions.md` companion is generated alongside
+because GitHub Copilot reads its own file path. Other tool stubs
+(`CLAUDE.md`, `GEMINI.md`, `.cursorrules`) follow the symlink-or-stub
+strategy in [`agents-md-anatomy § Multi-tool symlink strategy`](../../contexts/contracts/agents-md-anatomy.md#multi-tool-symlink-strategy).
+
 Use when either file is missing, or the user wants to start over with a
-clean scaffold. For tuning an existing file, use `/copilot-agents-optimize`.
+clean scaffold. For tuning an existing file, use `/agents optimize`.
 
 ## Steps
 
@@ -35,7 +43,7 @@ Outcomes:
 |---|---|
 | Both targets missing | Proceed |
 | One exists, other missing | Ask whether to fill only the missing one |
-| Both exist | Ask confirmation — offer `/copilot-agents-optimize` instead |
+| Both exist | Ask confirmation — offer `/agents optimize` instead |
 | Template missing | Abort with "package not installed" hint |
 
 ### 2. Auto-detect stack
@@ -75,7 +83,7 @@ always with numbered options where applicable:
    directory name.
 2. **One-line description** — used in copilot-instructions.md.
 3. **Architecture style** — e.g. "Controllers thin, logic in services,
-   validation via FormRequests". Offer `/optimize-agents` style presets
+   validation via FormRequests". Offer `/agents optimize` style presets
    based on detected framework.
 4. **User-facing strings strategy** — translation files? hardcoded?
    default per framework.
@@ -132,12 +140,12 @@ Write to `AGENTS.md` and `.github/copilot-instructions.md` (create
 Next steps:
   1. Review both files and refine sections that say "document your …"
   2. Commit them as part of the project's initial agent setup
-  3. Run `/copilot-agents-optimize` periodically to deduplicate against .augment/
+  3. Run `/agents optimize` periodically to deduplicate against .augment/
 ```
 
 ### 7. Follow-ups
 
-If `agents/` directory does not exist, suggest running `/agents-prepare`.
+If `agents/` directory does not exist, suggest running `/optimize agents-dir --scaffold`.
 If `.agent-settings.yml` does not exist, suggest running `scripts/install` (then `/onboard` for first-run setup).
 
 ## Rules

package/.agent-src/commands/agents/optimize.md

@@ -0,0 +1,181 @@
+---
+name: agents:optimize
+cluster: agents
+sub: optimize
+description: Refactor AGENTS.md to the Thin-Root contract (caps, pointer ratio, capability bullets, emergency-triage) and propagate to tool stubs. Suggest only, never auto-apply.
+skills: [agents-md-thin-root, copilot-agents-optimization, copilot-config, agent-docs-writing]
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "refactor AGENTS.md, shrink AGENTS.md, capability bullets, thin-root, optimize agent layer"
+  trigger_context: "maintainer working on AGENTS.md (root or consumer template) or its tool stubs"
+---
+
+# /agents optimize
+
+Refactor of a single `AGENTS.md` file (project root, package root, or
+consumer template) into the Thin-Root contract: hard char caps, ≥ 40 %
+substantive-pointer ratio, Capabilities-over-Structure Iron Law,
+mandatory emergency-triage block. Propagates the result to the
+multi-tool stubs the consumer ships (`copilot-instructions.md`,
+`CLAUDE.md`, `GEMINI.md`, `.cursorrules`) per the symlink-or-stub
+strategy. **Suggest only — never auto-apply.**
+
+**Source of truth:** the canonical contract lives in
+[`agents-md-thin-root`](../../skills/agents-md-thin-root/SKILL.md);
+the long-form anatomy lives in
+[`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md).
+This command orchestrates the diagnose-and-propose flow, it does not
+restate the contract.
+
+## When to invoke
+
+- Lint emits FAIL or WARN on `AGENTS.md` size, pointer-ratio, or
+  path-enumeration.
+- A new section feels like it belongs at the root and you want a
+  pre-flight check before adding it.
+- A monorepo grew a 6 KB root `AGENTS.md` because every package
+  appended its own section.
+- Migrating from a hand-grown `AGENTS.md` (path enumerations, no
+  emergency triage) to the package's contract.
+
+## Steps
+
+### 1. Identify the target file
+
+Default: the AGENTS.md the user is editing right now. If unclear,
+ask:
+
+> 1. project root — `AGENTS.md`
+> 2. consumer template — `.agent-src.uncompressed/templates/AGENTS.md`
+> 3. package root — `AGENTS.md` of `event4u/agent-config` itself
+> 4. monorepo package — `<path>/AGENTS.md` (specify path)
+
+### 2. Measure baseline
+
+```bash
+target="<path-to-AGENTS.md>"
+wc -c "$target"
+python3 scripts/lint_agents_md.py 2>&1 | grep -A1 "$target" || \
+  python3 scripts/lint_agents_md.py
+```
+
+Record: total chars, gap to FAIL/WARN cap, pointer-ratio output,
+path-enumeration warning count.
+
+### 3. Section inventory
+
+```bash
+awk '/^## / {if (h) print h, n; h=$0; n=0; next} {n+=length($0)+1} END {if (h) print h, n}' "$target"
+```
+
+For each section: classify as `keep-inline` (Iron-Law-adjacent,
+≤ 200 chars, no good outboard target) or `outboard-candidate`
+(longer-form prose, table-only sections, narrative). Reference the
+anatomy refactor recipe.
+
+### 4. Path-enumeration sweep
+
+```bash
+grep -nE "^[[:space:]]*[-*+][[:space:]]+\`[^\`]*/[^\`]*\`" "$target" | \
+  grep -v "\[.*\](.*)" || echo "(none)"
+```
+
+Three or more bare path bullets without why-clauses → propose a
+capability-style rewrite using the anatomy table.
+
+### 5. Pointer audit
+
+For every link in the file, verify:
+
+- *Why*-clause ≥ 60 chars on the same line.
+- Target file resolves on disk (the lint already checks this; flag
+  failures here only for human readability).
+- Anchor used when the linked file is large.
+
+### 6. Emergency-triage diff
+
+```bash
+diff <(awk '/^## Emergency triage/,/^## [^E]/' "$target") \
+     .agent-src.uncompressed/contexts/contracts/emergency-triage-block.md
+```
+
+Drift = revert in-file block to the canonical variant (package-root
+or consumer-template).
+
+### 7. Propose findings — numbered options
+
+Present the user with a single numbered-options block:
+
+```
+> 1. apply suggested edits (I show the diff first, you approve)
+> 2. apply only the highest-impact edit (the one that frees the
+>    most chars or fixes a FAIL)
+> 3. report only — no edits
+```
+
+Never auto-apply. Edits land only after explicit user approval per
+[`scope-control`](../../rules/scope-control.md) and
+[`commit-policy`](../../rules/commit-policy.md).
+
+### 8. Multi-tool propagation
+
+After AGENTS.md is updated, check for the four common tool stubs and
+keep them in sync:
+
+```bash
+ls .github/copilot-instructions.md CLAUDE.md GEMINI.md .cursorrules 2>/dev/null
+```
+
+For each present file, decide per
+[`agents-md-anatomy § Multi-tool symlink strategy`](../../contexts/contracts/agents-md-anatomy.md#multi-tool-symlink-strategy):
+
+- **Symlink target** (`CLAUDE.md`, `GEMINI.md`, `.cursorrules` → `AGENTS.md`)
+  → no edit needed; the link already resolves to the new content.
+- **Stub** (one-line "see AGENTS.md" pointer) → no edit needed.
+- **Independent file** (`.github/copilot-instructions.md` is the
+  canonical one — Copilot reads its own path) → present a side-by-side
+  diff against AGENTS.md and let the user choose what to copy across.
+  Never auto-overwrite.
+
+If a tool stub has drifted into a long independent file, surface that
+as a finding in the step-7 numbered options instead of editing here.
+
+### 9. Verify before claiming done
+
+```bash
+python3 scripts/lint_agents_md.py
+python3 scripts/check_references.py
+```
+
+Both green = the refactor is finished. Surface fresh output in the
+final reply per
+[`verify-before-complete`](../../rules/verify-before-complete.md).
+
+## Preservation gate — MANDATORY before any edit
+
+- [ ] Emergency-triage block keeps all five canonical questions.
+- [ ] No substantive pointer dropped without an outboard target.
+- [ ] No new top-level directory invented for outboarded prose.
+- [ ] Pointer ratio stays ≥ 0.40 after the edit.
+- [ ] Char-count under FAIL cap; under WARN preferred.
+
+## What this command does NOT do
+
+- **No edits to** `.augment/` **or** `.agent-src/` — those regenerate
+  from `.agent-src.uncompressed/`. Edit the source.
+- **No commits, no push, no PR** — finishing the refactor is a user
+  decision; cite [`commit-policy`](../../rules/commit-policy.md).
+- **No broader agent-infra audit** — for token overhead, rule
+  triggers, and skill-level findings, route to `/agents audit`.
+- **No `agents/` folder ops** — scaffolding, folder-audit, and folder
+  cleanup live in `/optimize agents-dir`.
+
+## See also
+
+- [`agents-md-thin-root`](../../skills/agents-md-thin-root/SKILL.md)
+  — caps, pointer-ratio, anatomy, gotchas.
+- [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md)
+  — Iron Law, refactor recipe, monorepo and symlink strategy.
+- [`emergency-triage-block`](../../contexts/contracts/emergency-triage-block.md)
+  — canonical block both AGENTS.md variants embed.