@event4u/agent-config 5.10.1 → 6.1.0

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

@@ -1,136 +0,0 @@
----
-model_tier: medium
-name: agent-status
-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/.agent-src/commands/agents/audit.md

@@ -1,157 +0,0 @@
----
-model_tier: medium
-name: agents:audit
-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
-`.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 `.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/.agent-src/commands/agents/init.md

@@ -1,191 +0,0 @@
----
-model_tier: medium
-name: agents:init
-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/.agent-src/commands/agents/optimize.md

@@ -1,186 +0,0 @@
----
-model_tier: inherit
-name: agents:optimize
-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** `.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.