@event4u/agent-config 5.10.1 → 6.0.0

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

@@ -0,0 +1,140 @@
+---
+model_tier: medium
+name: agent-status
+pack: meta
+intent: "Report the current agent session state, mode, and progress at a glance"
+routes_to: [agent-docs-writing]
+replaces: []
+tier: 0
+skills: [agent-docs-writing]
+description: Show current conversation stats — message count, token costs, task progress, next freshness check.
+suggestion:
+  eligible: false
+  rationale: "Pure status display; no natural-language trigger distinct from idle small-talk."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /agent-status
+
+Displays a dashboard of the current conversation's health and token costs.
+
+## Steps
+
+### 1. Count messages
+
+Count your own responses in this conversation (each response ≈ 1 user message).
+This is an estimate — you cannot access exact counts.
+
+### 2. Count tasks
+
+Run `view_tasklist` and count:
+- Total tasks
+- Completed tasks
+- In-progress tasks
+- Not started tasks
+
+### 3. Estimate token costs
+
+Calculate based on these estimates:
+
+| Component | How to estimate | Tokens |
+|---|---|---|
+| **Conversation history** | responses × ~1,500 | variable |
+| **AGENTS.md** | always loaded | ~1,800 |
+| **Skill descriptions** | always loaded | ~4,100 |
+| **Matched rules** | count rules triggered this request × ~800 avg | variable |
+| **Matched skills** | count skills triggered this request × ~1,500 avg | variable |
+| **Platform overhead** | system prompt, tool schemas | ~15,000 |
+
+### 3a. Read session cost ledger (measured, not estimated)
+
+Run `node scripts/cost/track.mjs` (silent — `TRACK_QUIET=1`) and parse
+the last record from `agents/cost-tracking/sessions.jsonl`. If the file
+does not exist (tracker never run for this project), skip this step and
+note `cost ledger: not initialised` in the dashboard.
+
+Extract from latest record:
+
+- `total_usd` — dollars spent in current session
+- `by_model[]` — per-tier (haiku / sonnet / opus) input / output / cache split
+- `budget.tier` — `under` / `50` / `75` / `90` / `100` (from `node scripts/cost/budget.mjs check`)
+
+Pricing source: [`internal/bench/pricing.yaml`](../../bench/pricing.yaml). Reader
+implementation: [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs).
+
+### 3b. Read telegraph delta + per-conversation cost lens
+
+Run two read-only Python helpers (stdlib-only, no-op safe if JSONL missing):
+
+- `python3 scripts/telegraph_stats.py --format json` — per-session +
+  per-conversation + lifetime telegraph delta. Honors suspended
+  multiplier (see [`docs/contracts/telegraph-telemetry.md`](../docs/contracts/telegraph-telemetry.md)) — delta reads `0` while suspended; display version + ACTIVE/SUSPENDED state regardless.
+- `python3 scripts/cost_by_conversation.py --format json` — per-conversation
+  total cost + model breakdown for current conversation, sourced
+  from same `agents/cost-tracking/sessions.jsonl` ledger.
+
+Surface in dashboard as one line:
+`[telegraph: {lifetime.delta_tokens:+,} tok lifetime · {current_conv.delta_tokens:+,} this conv · multiplier v{multiplier_version} {ACTIVE|SUSPENDED}] · [conv cost: ${current_conv.total_cost_usd:.4f}]`.
+
+If both JSONLs missing or empty, omit line silently.
+
+### 4. Calculate freshness thresholds
+
+- **Message threshold**: Next multiple of 25 ≥ current count
+- **Task threshold**: Next multiple of 15 ≥ completed count
+- **Which comes first?**
+
+### 5. Display dashboard
+
+Use Markdown tables and headings — NOT ASCII box art (breaks in non-monospace chat UIs).
+
+**📊 Agent Status**
+
+| | |
+|---|---|
+| 💬 Messages | ~{N} responses |
+| 📋 Tasks | {done}/{total} done ({in_progress} in progress, {not_started} open) |
+| 🌿 Branch | `{branch}` |
+
+**💰 Estimated tokens PER REQUEST**
+
+| Component | Tokens |
+|---|---|
+| Platform overhead | ~15,000 |
+| AGENTS.md + Skills | ~5,900 |
+| **Conversation history** | **~{N×1500}** ← biggest cost |
+| Matched rules (~{n}) | ~{n×800} |
+| Matched skills (~{n}) | ~{n×1500} |
+| **Total input** | **~{sum}** |
+
+**💵 Session cost (measured)**
+
+If ledger exists, render:
+
+| | |
+|---|---|
+| 💵 Session total | ${total_usd} |
+| Haiku / Sonnet / Opus | ${haiku} / ${sonnet} / ${opus} |
+| 🎯 Budget tier | {emoji} {tier} ({utilization_pct}% of cap) |
+
+Tier-emoji map: `under` / `50` → ✅ · `75` → ⚠️ · `90` → ⚠️⚠️ · `100` → ❌.
+If ledger does not exist, render `Session cost: not initialised — run \`task cost:track\` to start measuring`.
+
+**⚡ Freshness**
+
+| | |
+|---|---|
+| Next check at | {next_msg} messages or {next_task} completed tasks |
+| Fresh chat saves | ~{N×1500} tokens/request |
+
+If history cost exceeds ~50,000: add a ⚠️ recommendation to start a fresh chat.
+
+## Rules
+
+- **Estimates only** — no access to real token counts, make that clear.
+- **Markdown tables** — never use ASCII box art, it breaks in chat UIs.
+- **History cost is the key insight** — bold it as the biggest variable cost.
+- **Always show the savings** — "Fresh chat saves X tokens/request" drives the point home.

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

@@ -0,0 +1,158 @@
+---
+model_tier: medium
+name: agents-audit
+pack: meta
+tier: 2
+cluster: agents
+sub: audit
+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]
+suggestion:
+  eligible: true
+  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"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /agents audit
+
+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.
+
+**Source of truth:** `.agent-src.uncondensed/` — never read or edit
+`dist/agent-src/` or `.augment/` directly.
+
+## Steps
+
+### 1. Measure baseline
+
+Count lines affecting token consumption:
+
+```bash
+# Always-loaded (per chat)
+for f in .agent-src.uncondensed/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.uncondensed/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.uncondensed/skills/*/SKILL.md; do
+  name=$(echo "$f" | sed 's|.agent-src.uncondensed/skills/||;s|/SKILL.md||')
+  lines=$(wc -l < "$f"); echo "$lines | $name"
+done | sort -rn | head -20
+```
+
+Report totals (always + auto + skills + AGENTS.md).
+
+### 2. Check rules
+
+- **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
+for f in .agent-src.uncondensed/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]}}'
+```
+
+### 3. Check `always` → `auto` candidates
+
+Apply `rule-type-governance`:
+
+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**.
+
+Surface candidates with explicit justification. Never auto-apply.
+
+### 4. Check AGENTS.md — Thin-Root + Capability-over-Structure
+
+Run the linter and inspect output:
+
+```bash
+python3 scripts/lint_agents_md.py
+wc -c AGENTS.md
+```
+
+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)):
+
+- 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.
+
+Failures route to `/agents optimize` — this command does **not** edit.
+
+### 5. Check docs sync + stale references
+
+```bash
+python3 scripts/check_references.py
+```
+
+Confirm counts/lists in `.augment/contexts/augment-infrastructure.md` and
+`docs/architecture.md` match the actual `.agent-src.uncondensed/` tree.
+
+### 6. Run skill linter
+
+```bash
+python3 scripts/skill_linter.py --all --pairs --duplicates 2>&1 | grep "Summary:"
+```
+
+Report FAIL/WARN counts. Don't fix here — delegate to `skill-reviewer` or
+`/optimize skills`.
+
+### 7. Present findings
+
+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` |
+| ... | | | | |
+
+Then ask:
+
+```
+> 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
+```
+
+## What this command does NOT do
+
+- **No edits** — read-only audit. Fixes route to `/agents optimize`,
+  `skill-reviewer`, or `/optimize skills`.
+- **No edits to `dist/agent-src/` or `.augment/`** — those regenerate from
+  `.agent-src.uncondensed/`. 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).
+
+## See also
+
+- [`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/dist/agent-src/commands/agents/init.md

@@ -0,0 +1,192 @@
+---
+model_tier: medium
+name: agents-init
+pack: meta
+tier: 2
+cluster: agents
+sub: init
+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]
+suggestion:
+  eligible: false
+  rationale: "Project init — only deliberately during onboarding."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /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 `/agents optimize`.
+
+## Steps
+
+### 1. Precondition checks
+
+```bash
+ls AGENTS.md .github/copilot-instructions.md 2>/dev/null
+ls .augment/templates/AGENTS.md .augment/templates/copilot-instructions.md
+```
+
+Outcomes:
+
+| State | Action |
+|---|---|
+| Both targets missing | Proceed |
+| One exists, other missing | Ask whether to fill only the missing one |
+| Both exist | Ask confirmation — offer `/agents optimize` instead |
+| Template missing | Abort with "package not installed" hint |
+
+### 2. Auto-detect stack
+
+Read (in this order) and record what is found:
+
+- `composer.json` → framework (Laravel / Symfony), PHP version, package name
+- `package.json` → framework (Next.js / React / Vue / Node), engines
+- `pyproject.toml` / `requirements.txt` → Python framework + version
+- `Gemfile` → Rails
+- `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle` → language/framework
+
+Secondary signals:
+
+- `Dockerfile`, `docker-compose.yml` → containerized setup
+- `Makefile`, `Taskfile.yml`, `package.json` scripts → dev commands
+- `phpunit.xml` / `pest.config` / `jest.config` / `vitest.config` / `pytest.ini` → test framework
+- `phpstan.neon`, `rector.php`, `eslint.config.js`, `ruff.toml` → quality tools
+
+Present a numbered table so the user can confirm or correct:
+
+```
+Detected:
+> 1. Language: {lang}            — correct? yes / edit
+> 2. Framework: {framework}      — correct? yes / edit
+> 3. Database: {db}              — correct? yes / skip / edit
+> 4. Test framework: {tests}     — correct? yes / edit
+> 5. Dev commands: {commands}    — correct? yes / edit
+```
+
+### 3. Gather remaining answers
+
+Ask for values that cannot be auto-detected — one question at a time,
+always with numbered options where applicable:
+
+1. **Project name** — default = `{{repo_name}}` from git remote or
+   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 `/agents optimize` style presets
+   based on detected framework.
+4. **User-facing strings strategy** — translation files? hardcoded?
+   default per framework.
+5. **Additional conventions** — free text, optional.
+
+### 4. Generate files
+
+Read the templates, substitute placeholders:
+
+| Placeholder | Source |
+|---|---|
+| `{{project_name}}` | Step 3.1 |
+| `{{project_description}}` | Step 3.2 |
+| `{{project_description_oneline}}` | Short version of 3.2 |
+| `{{primary_language}}`, `{{framework}}`, `{{database}}`, `{{test_framework}}`, `{{code_style_tool}}` | Step 2 |
+| `{{dev_start_command}}`, `{{dev_test_command}}` | Step 2 Makefile / scripts |
+| `{{project_structure_notes}}`, `{{testing_notes}}`, `{{quality_tools_notes}}` | Offer framework-specific defaults, let user edit |
+| `{{architecture_notes}}`, `{{coding_standards}}`, `{{framework_conventions}}` | Offer defaults + user edits |
+| `{{test_all_command}}`, `{{test_targeted_command}}`, `{{testing_extra_notes}}` | From detected test framework |
+| `{{user_facing_strings_strategy}}` | Step 3.4 |
+| `{{target_language_level}}` | e.g. "PHP 8.2 / Laravel 11" |
+
+Remove the HTML comments starting with `<!-- AGENTS.md — entry point …`
+and `<!-- copilot-instructions.md — read by GitHub Copilot …` — they are
+instructions for the human user and no longer needed once filled.
+
+Keep the **example** HTML comments (those starting with `<!-- Replace with
+your actual stack. Examples:`) — they help future maintenance.
+
+### 5. Portability verification
+
+Before writing, scan the generated content for forbidden identifiers:
+
+- Any project name from `agents/` module docs except the one chosen in 3.1
+- Any reference to vendor-specific internal tools not in the user's stack
+- Any identifier listed in `FORBIDDEN_IDENTIFIERS` in
+  `scripts/check_portability.py` (the package ships a blocklist of
+  legacy/adjacent project names that must never leak into consumer files)
+- The package's own name (e.g. the shared-config package itself), unless
+  the consumer project explicitly depends on it
+
+If any hit is found, flag it and ask for a replacement. This mirrors what
+`scripts/check_portability.py` enforces for package files.
+
+### 6. Write files
+
+Write to `AGENTS.md` and `.github/copilot-instructions.md` (create
+`.github/` if missing). Report:
+
+```
+✅  AGENTS.md written (X lines)
+✅  .github/copilot-instructions.md written (Y lines)
+
+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 `/agents optimize` periodically to deduplicate against .augment/
+```
+
+### 7. Module-root proposal (optional)
+
+Surface configurable-module candidates so the team file can opt in to
+module-aware skills (road-to-configurable-modules Phase B). Skips
+silently when the helper finds no candidates.
+
+```bash
+python3 scripts/propose_modules_config.py --json
+```
+
+If the JSON `candidates` array is non-empty, render the proposed
+`modules:` block as numbered options:
+
+```
+> 1. Accept all candidates — patch .agent-project-settings.yml
+> 2. Pick a subset — choose root paths interactively
+> 3. Skip — leave modules.enabled: false (default)
+```
+
+On accept, append the `modules:` block to the team file
+`.agent-project-settings.yml` (preserve comments + ordering per the
+[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md)
+contract). On skip, do nothing — the block stays opt-in.
+
+### 8. Follow-ups
+
+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
+
+- **Never copy from the package's own root `AGENTS.md` or
+  `.github/copilot-instructions.md`.** Those are meta docs about the
+  package, not templates.
+- **Always start from `.augment/templates/`** — that is the only portable
+  source.
+- **Refuse to overwrite** existing files without explicit `--force` or
+  interactive confirmation.
+- **Never embed identifiers from other projects** — if the consumer's repo
+  is `acme/widget`, the generated file must say `acme/widget`, not any
+  name encountered while scaffolding the shared package.

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

@@ -0,0 +1,187 @@
+---
+model_tier: inherit
+name: agents-optimize
+pack: meta
+tier: 2
+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]
+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"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /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.uncondensed/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.uncondensed/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** `dist/agent-src/` — those regenerate
+  from `.agent-src.uncondensed/`. 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.