@event4u/agent-config 1.23.0 → 1.25.0

package/.agent-src/rules/no-roadmap-references.md

@@ -1,31 +1,49 @@
 ---
 type: "auto"
 tier: "mechanical-already"
-description: "Adding a link to a specific file in agents/roadmaps/ from any stable artifact (rule, skill, command, context, guideline) — roadmaps are transient; promote durable findings to agents/contexts/ instead"
+description: "Linking transient files (agents/roadmaps/, agents/council-{questions,responses,sessions}/) from a stable artifact — both layers expire; promote findings"
 alwaysApply: false
 source: package
 triggers:
   - path_prefix: "agents/roadmaps/"
+  - path_prefix: "agents/council-questions/"
+  - path_prefix: "agents/council-responses/"
+  - path_prefix: "agents/council-sessions/"
   - intent: "link from stable artifact"
+  - intent: "link to council artefact"
+routes_to:
+  - "skill:ai-council"
 validator_ignore:
   - type: "substring"
     pattern: ".agent-src.uncompressed/"
-    reason: "Rule contrasts the authoring tree with transient roadmap files."
+    reason: "Rule contrasts the authoring tree with transient layers."
 ---
 
-# No Roadmap References from Stable Artifacts
+# No Transient References from Stable Artifacts
 
-Roadmaps in `agents/roadmaps/` are **transient** — archived, skipped,
-or deleted as work completes. Stable artifacts (rules, skills,
-commands, contexts, guidelines, AGENTS.md, README) outlive them. A
-stable artifact citing a specific roadmap file becomes a broken
-reference the moment that roadmap is deleted.
+Two transient layers under `agents/` outlive nothing: roadmaps in
+`agents/roadmaps/` are archived, skipped, or deleted as work
+completes; council artefacts in `agents/council-{questions,responses,
+sessions}/` are **gitignored, local-only, and auto-pruned** after
+`ai_council.session_retention_days` (default 7). Stable artifacts
+(rules, skills, commands, contexts, guidelines, AGENTS.md, README,
+copilot-instructions) outlive both. A stable artifact citing a
+specific transient file becomes a broken reference the moment that
+file is deleted or pruned.
+
+Council links rot three ways: gitignored (not in cloned repo),
+pruned after retention window (gone even locally), and the installed
+`.augment/` projection cannot follow a path that does not exist in
+the consumer.
 
 ## The Iron Law
 
 ```
-NEVER LINK TO A SPECIFIC FILE IN agents/roadmaps/ FROM A STABLE ARTIFACT.
+NEVER LINK TO A SPECIFIC FILE IN agents/roadmaps/
+OR IN agents/council-{questions,responses,sessions}/
+FROM A STABLE ARTIFACT.
 PROMOTE DURABLE CONCLUSIONS TO agents/contexts/ AND CITE THAT INSTEAD.
+INLINE COUNCIL CONVERGENCE WITH DATE + MEMBERS, NEVER THE PATH.
 ```
 
 Stable artifact = anything that is **not** a roadmap, council
@@ -37,6 +55,9 @@ These paths must not appear inside a stable artifact:
 
 - `agents/roadmaps/<file>.md`, `agents/roadmaps/archive/<file>.md`,
   `agents/roadmaps/skipped/<file>.md`
+- `agents/council-questions/<file>.md`,
+  `agents/council-responses/<file>.json`,
+  `agents/council-sessions/<file>.json` or `<timestamp>/...`
 
 Stable artifact = any file under `.agent-src.uncompressed/{rules,
 skills,commands,contexts,templates,personas}/`, `agents/contexts/`,
@@ -44,38 +65,53 @@ skills,commands,contexts,templates,personas}/`, `agents/contexts/`,
 `docs/customization.md`, `docs/getting-started.md`, `docs/catalog.md`,
 `AGENTS.md`, `README.md`, `copilot-instructions.md`.
 
-CI enforcement: `scripts/check_no_roadmap_refs.py` (companion linter
-— fails the build on any new violation).
+CI enforcement: `scripts/check_no_roadmap_refs.py` (roadmap layer)
+and `scripts/check_council_references.py` (council layer) — both
+fail the build on any new violation.
 
 ## Allowed patterns
 
-- `agents/roadmaps/` and its subdirectories as directory mentions
+- `agents/roadmaps/` and `agents/council-*/` as **directory** mentions
   (talking about the layer, not a specific file)
 - Roadmap → roadmap references (siblings within the transient layer)
+- The `ai-council` skill and `/council:*` commands documenting the
+  output path schema
+- Inline council convergence summary — e.g. *"Council
+  (claude-sonnet-4-5 + gpt-4o, 2026-05-06) converged on …"* with
+  date + members, no filepath
 - Council sessions, `agents/.agent-chat-history`, commit messages, PR
   descriptions — transient by construction, not part of the package
   surface
 
 ## What to do instead
 
-When a stable artifact needs to cite a roadmap finding:
+When a stable artifact needs to cite a transient finding:
 
 1. Identify the durable conclusion — decision, contract, lesson,
    mechanic.
 2. Promote it to a context file under `agents/contexts/` (ADR,
-   mechanics doc, locked decision). The roadmap can then point at
-   the context, not the other way around.
+   mechanics doc, locked decision). The roadmap or council session
+   can then point at the context, not the other way around.
 3. Reference the context from the stable artifact.
+4. For council convergences specifically: inline a convergence-summary
+   block (members, date, cost if relevant — see `ai-council`
+   § Output format) instead of linking the session JSON.
+
+Failure modes:
 
-Failure mode: *"I'll just link to the roadmap, it's evidence."* The
-roadmap gets archived, then deleted, then the link rots. **Promote
-first, link second.**
+- *"I'll just link to the roadmap, it's evidence."* The roadmap
+  gets archived, then deleted, then the link rots. **Promote first,
+  link second.**
+- *"I'll just link to the session JSON, it's evidence."* The session
+  is gone in 7 days. **Inline first, link never.**
 
 ## See also
 
 - [`docs-sync`](docs-sync.md) — cross-reference sync after rename / delete
 - [`agent-docs`](agent-docs.md) — roadmap layer conventions
-- [`roadmap-progress-sync`](roadmap-progress-sync.md) — sync dashboard on
-  roadmap touch
+- [`roadmap-progress-sync`](roadmap-progress-sync.md) — sync dashboard
+  on roadmap touch
 - [`augment-source-of-truth`](augment-source-of-truth.md) — edit
   `.agent-src.uncompressed/`
+- [`ai-council`](../skills/ai-council/SKILL.md) — output path
+  convention and convergence-summary format

package/.agent-src/rules/onboarding-gate.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "1"
-description: "First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt the user to run /onboard before executing any other request"
+description: "First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt to run /onboard before any request"
 source: package
 triggers:
   - phrase: "first turn"

package/.agent-src/rules/package-ci-checks.md

@@ -1,5 +1,5 @@
 ---
-type: "auto"
+type: "manual"
 tier: "mechanical-already"
 description: "Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first"
 source: package

package/.agent-src/rules/reviewer-awareness.md

@@ -1,18 +1,25 @@
 ---
 type: "auto"
 tier: "2a"
-description: "When suggesting reviewers for a change — anchor the choice in paths and risk, never prestige or seniority; require primary + secondary role for medium/high risk"
+description: "When suggesting reviewers or flagging risk hotspots — anchor in paths/risk + ownership-map + bug-patterns; medium/high needs primary + secondary"
 source: package
 triggers:
   - keyword: "reviewer"
   - phrase: "suggest reviewers"
+  - phrase: "risk hotspot"
+  - phrase: "ownership map"
 routes_to:
   - "skill:review-routing"
 ---
 
 # Reviewer Awareness
 
-**Iron Law.** Anchor reviewer choice in paths and risk, never seniority; medium / high risk requires primary + secondary role.
+**Iron Law (reviewer choice).** Anchor reviewer choice in paths and risk, never seniority; medium / high risk requires primary + secondary role.
+
+**Iron Law (routing / risk).** Consult ownership-map and historical-bug-patterns before suggesting reviewers or claiming a change is safe.
 
 Body migrated to `skill:review-routing` (per P4 of `road-to-kernel-and-router.md`).
 Trigger-set above activates this routing under the `balanced` and `full` profiles.
+
+Consolidates the former review-routing-awareness rule per the
+package's adr-auto-rule-consolidation decision.

package/.agent-src/rules/roadmap-progress-sync.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "1"
-description: "Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response"
+description: "Any roadmap touch (file move, checkbox flip, phase change) regens dashboard same response; archive at 0 open. Autonomous runs flip checkboxes inline"
 source: package
 triggers:
   - path_prefix: "agents/roadmaps/"
@@ -11,7 +11,41 @@ routes_to:
 
 # Roadmap Progress Sync
 
-**Iron Law.** Any touch to `agents/roadmaps/` regenerates the dashboard in the same response; archive the roadmap when 0 open items remain.
+## Iron Law 1 — dashboard sync, same response
 
-Body migrated to `guideline:agent-infra/roadmap-progress-mechanics` (per P4 of `road-to-kernel-and-router.md`).
+```
+ANY ROADMAP TOUCH → REGENERATE THE DASHBOARD, SAME RESPONSE.
+NO EXCEPTIONS. NO "I'LL DO IT AT THE END". NO BATCHING ACROSS TURNS.
+```
+
+Roadmap touch = create / rename / delete / move file, add/rename/remove a phase, OR flip any checkbox (`[ ]` ↔ `[x]` ↔ `[~]` ↔ `[-]`). Regen command: `./agent-config roadmap:progress`. Archive (`git mv` → `archive/`) the moment `count_open == 0` — same response.
+
+## Iron Law 2 — real-time checkbox cadence (autonomous execution)
+
+```
+EVERY DONE STEP FLIPS [ ] → [x] IN THE SAME REPLY THAT LANDS THE WORK.
+NO "I UPDATE THE ROADMAP AT THE END OF THE PHASE."
+NO "FOUR STEPS DONE, ONE COMMIT, ONE REGEN."
+A REPLY THAT LANDS A VERIFIED STEP WITHOUT FLIPPING ITS CHECKBOX
+IS A RULE VIOLATION, NOT AN OVERSIGHT.
+```
+
+`/roadmap:process-step`, `/roadmap:process-phase`, `/roadmap:process-full`, and any other multi-step autonomous run flip the box for step N **before** moving on to step N+1. The dashboard is a real-time monitor, not a post-hoc summary. Batched flips at the archive commit defeat the dashboard's purpose.
+
+**Step counts as done** when its code/doc change is written and saved AND the verification cited in the step has passed (fresh output in this reply or an earlier one).
+
+**In-progress marker.** When a step takes more than one reply, mark it `[~]` the moment work starts and regen — the user sees one row move `[ ] → [~] → [x]` instead of silent rows. `[~]` stays open for `count_open` but advances the phase percentage.
+
+## Pre-send self-check — MANDATORY
+
+Before sending any reply that landed roadmap work:
+
+1. Did this reply land a step (code/doc saved + verification passed)?
+2. Is its checkbox flipped to `[x]` / `[~]` / `[-]` in `agents/roadmaps/<file>.md`? If no → flip, then continue.
+3. Did `./agent-config roadmap:progress` run after the flip? If no → run, then continue.
+4. Did `count_open` reach 0? If yes → `git mv` to `archive/` and regen again — same reply.
+
+Any "no" at step 2 or 3 → reply is incomplete. Do not send.
+
+Long-form mechanics (failure-mode catalog, Copilot fallback, `[~]` vs `[ ]` semantics, hook + CI defence-in-depth) live in `guideline:agent-infra/roadmap-progress-mechanics`.
 Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/scope-control.md

@@ -6,6 +6,7 @@ alwaysApply: true
 source: package
 load_context:
   - ../contexts/authority/scope-mechanics.md
+  - ../contexts/authority/kernel-rule-edits.md
 ---
 
 # Scope Control
@@ -29,6 +30,7 @@ The user decides the git shape. Never improvise. Commit specifics: canonical [`c
 - NEVER push a tag or create a release without permission.
 - NEVER include version numbers, target releases, deprecation dates, release-tied milestones, or git tags in roadmaps, plans, tickets, or any planning artifact. Roadmaps plan **work**; releases / tags are a separate decision outside the roadmap. Never surface "which release should this ship in?" as a numbered choice. User pins by saying so explicitly.
 - Task seems to need a separate branch / PR → STOP and **brief before asking** ([`scope-mechanics § Brief-before-asking`](../contexts/authority/scope-mechanics.md)).
+- BEFORE the first commit on related work, **inventory** existing branches and open PRs (`git branch --show-current`, `gh pr list --state open`). If a plausible base beyond the current branch exists, STOP and ask with numbered options — never improvise the base. Inventory + 4-option template + diverging-stack failure mode: [`scope-mechanics § Branch-base inventory`](../contexts/authority/scope-mechanics.md).
 
 "Explicit permission" = user said so **this turn or in a standing instruction not yet revoked**. Earlier permission for a different operation does not carry over.
 
@@ -36,6 +38,10 @@ The user decides the git shape. Never improvise. Commit specifics: canonical [`c
 
 A subset is **never** autonomous and never auto-permitted by a standing autonomy directive. Canonical: [`non-destructive-by-default`](non-destructive-by-default.md). Trigger list (prod-branch merges, deploys / releases, prod data / infra, bulk-destructive ops) and the "authorization is this turn, not earlier" clarification: [`scope-mechanics § Production, infrastructure, bulk-destructive`](../contexts/authority/scope-mechanics.md).
 
+## Kernel-rule edits — slow-rollout guarantee
+
+Each kernel-rule edit ships in **its own PR**, ≥ 24 h between merges. Autonomous mandate does NOT lift this — soak guarantee, not preference. CI fails > 1 kernel rule per PR unless labeled `bundled-always-rules-acknowledged`. Trigger / scope: [`kernel-rule-edits`](../contexts/authority/kernel-rule-edits.md).
+
 ## Decline = silence — no re-asking on the same task
 
 After the user **declines** a proposal (branch switch, PR creation, tag/release entry, separate worktree, version pinning), do **not** raise it again on the same task. Decline stands until the user reopens the topic. Timing / "is this worth asking?": [`scope-mechanics § Decline = silence`](../contexts/authority/scope-mechanics.md).

package/.agent-src/rules/security-sensitive-stop.md

@@ -2,7 +2,7 @@
 type: "auto"
 tier: "2a"
 alwaysApply: false
-description: "Security-sensitive paths — auth, billing, tenant boundaries, secrets, file uploads, external integrations, webhooks, public endpoints — stop and run threat analysis BEFORE editing"
+description: "Security-sensitive paths — auth, billing, tenant boundaries, secrets, uploads, integrations, webhooks, public endpoints — threat-model BEFORE editing"
 source: package
 triggers:
   - keyword: "auth"

package/.agent-src/rules/size-enforcement.md

@@ -1,5 +1,5 @@
 ---
-type: "auto"
+type: "manual"
 tier: "mechanical-already"
 description: "Creating or editing rules, skills, commands, guidelines, AGENTS.md, or copilot-instructions.md — enforce size and scope limits"
 alwaysApply: false

package/.agent-src/rules/token-optimizer-maintenance.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "2a"
-description: "Editing a token-optimizer-cited asset (cli-output-handling, rtk-output-filtering, token-efficiency, agent-handoff, direct-answers, markitdown) — keep the catalog row in sync in the same commit."
+description: "Editing a token-optimizer-cited asset (cli-output-handling, rtk-output-filtering, token-efficiency, markitdown) — sync catalog same commit"
 source: package
 triggers:
   - keyword: "cli-output-handling"

package/.agent-src/rules/ui-audit-gate.md

@@ -2,7 +2,7 @@
 type: "auto"
 tier: "2b"
 alwaysApply: false
-description: "Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings in state.ui_audit before non-trivial UI change; gate, not suggestion"
+description: "Writing or editing UI — components, screens, partials, layouts, design tokens — require existing-ui-audit findings before non-trivial UI change"
 source: package
 triggers:
   - path_prefix: "resources/views/"

package/.agent-src/skills/adr-create/SKILL.md

@@ -194,4 +194,5 @@ to every ADR you author.
 - Reuse an existing ADR number — the index regenerator hard-fails.
 - Author ADRs for reversible refactors or minor cleanups.
 - Cite a council session id without ensuring the file is committed
-  or otherwise reachable from the repo (per `no-council-references`).
+  or otherwise reachable from the repo (per `no-roadmap-references`,
+  council clause).

package/.agent-src/skills/agents-md-thin-root/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: agents-md-thin-root
+description: "Use when editing AGENTS.md (package root) or templates/AGENTS.md (consumer) — enforces Thin-Root contract: hard char ceilings, ≥40% pointer ratio, mandatory emergency-triage block."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# agents-md-thin-root
+
+## When to use
+
+Use when:
+- Editing `AGENTS.md` at the package root.
+- Editing `.agent-src.uncompressed/templates/AGENTS.md` (consumer-shipped template).
+- Reviewing a PR that changes either file.
+- Running `/optimize/agents`.
+- A budget meter (`scripts/measure_augment_budget.py`) flags the package-root AGENTS.md as the dominant cost.
+
+## Do NOT
+
+- Edit `.github/copilot-instructions.md` with this skill (use `copilot-agents-optimization` instead).
+- Edit other `.md` files under `.augment/`, `.agent-src.uncompressed/`, or `agents/` with this skill.
+- Add a section to AGENTS.md without first checking whether an outboard target already exists in `agents/contexts/` or `docs/contracts/`.
+- Replace prose with a bare link `[label](path)` — every pointer needs a *why*-clause ≥ 60 chars or it does not count toward the 40 % ratio.
+- Reuse the package-root anatomy in the consumer template — caps and target paths differ.
+
+## Why Thin-Root
+
+Augment Code injects `AGENTS.md` verbatim into every workspace prompt. Each kilobyte spent here permanently consumes the 49,512-char workspace-guidelines budget shared with always-rules and auto-rule registry stubs. The Thin-Root pattern keeps the entry point a navigation surface (pointers + intent) and pushes deep detail into files Augment loads on demand via `load_context` or that other tools fetch only when their search retrieves them. Strategic council R2 (2026-05-08, Sonnet 4.5 / Opus 4.1 / gpt-4o / o1) converged on the contract codified below as the minimum guard against AGENTS.md re-bloat.
+
+## The contract — hard caps
+
+| File | FAIL above | WARN above | Target |
+|---|---|---|---|
+| `AGENTS.md` (package root) | 3,000 chars | 2,800 chars | ≤ 2,800 |
+| `.agent-src.uncompressed/templates/AGENTS.md` (consumer) | 2,500 chars | 2,300 chars | ≤ 2,300 |
+
+Char-count is raw file size (`wc -c`), frontmatter included. Enforcement: `scripts/lint_agents_md.py` (Phase 7), wired into the package's CI pipeline via the `lint-agents-md` task. WARN is a soft signal in CI; FAIL blocks merge.
+
+The R2 council originally proposed 2,500 / 2,000 caps. Phase 6.4 empirical refactor demonstrated that the mandatory emergency-triage block (≈ 700 chars) plus operational must-haves (source-of-truth disclaimer, `task` quickstart, six substantive pointers) raise the achievable floor by ≈ 500 chars. The caps above are the post-refactor baseline; the previous numbers stayed unattainable without dropping mandatory content.
+
+## The contract — pointer ratio
+
+≥ 40 % of non-blank lines must be **substantive pointers**. A substantive pointer is a Markdown link `[label](path[#anchor])` whose surrounding sentence carries a *why* clause ≥ 60 chars explaining what the reader will learn there. Decorative links (table-of-contents, badges, repeated cross-refs) do not count. Lint formula:
+
+```
+pointer_ratio = (substantive_pointer_lines / non_blank_lines) >= 0.40
+```
+
+## The contract — pointer anatomy
+
+Every substantive pointer specifies, on the same line or the immediately following line:
+
+1. **Target file path** — repo-relative, no leading `./`.
+2. **Optional anchor** — `#section-slug` when the linked file's content is large enough that landing in the middle saves the reader. Skip only when the linked file is itself short.
+3. ***Why* clause** — ≥ 60 chars, present-tense, names the concrete decision the pointer unblocks. Not "see also", not "more info", not the file's title repeated.
+
+### Wrong vs. right
+
+❌ **Wrong** — bare link, no *why*, no anchor:
+> See [`commit-policy`](.agent-src/rules/commit-policy.md).
+
+❌ **Wrong** — *why* present but < 60 chars:
+> Commit rules: [`commit-policy`](.agent-src/rules/commit-policy.md).
+
+✅ **Right** — full anatomy, anchor, *why* ≥ 60 chars:
+> Commit policy — never auto-commit, four named exceptions, Hard Floor list of bulk-deletion / infra triggers: [`commit-policy § Iron Law`](.agent-src/rules/commit-policy.md#the-iron-law).
+
+✅ **Right** — anchor optional when target is short:
+> Mirror the user's language every reply, single Iron Law that overrides any momentum: [`language-and-tone`](.agent-src/rules/language-and-tone.md).
+
+## The contract — emergency-triage block
+
+Every Thin-Root AGENTS.md MUST contain an **Emergency Triage** section verbatim from `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` (Phase 6.4 will create that file as the canonical source). The block lists the five questions a host agent answers from the root file alone when network / tool access is degraded:
+
+1. What is this repository?
+2. What language(s) does this repository accept?
+3. Where do I edit (source-of-truth path)?
+4. What is the lint / test / sync entry point?
+5. Where do the always-active behavior rules live?
+
+Each answer must fit on one line. The block exists so the root never silently degrades to "useful only when every linked file is reachable".
+
+## Procedure — apply Thin-Root to AGENTS.md
+
+1. **Measure baseline.** `wc -c AGENTS.md` and `python3 scripts/measure_augment_budget.py`. Record current char-count and the gap to 2,200 / 2,500.
+2. **Inventory sections.** List every `## ` heading and its char-count. Mark each as `keep-inline` (Iron-Law-adjacent, ≤ 200 chars, no good outboard target) or `outboard-candidate` (longer-form prose, table-only sections, narrative).
+3. **Identify outboard targets.** For each `outboard-candidate`, name the destination — `.agent-src.uncompressed/contexts/`, `docs/contracts/`, an existing rule body, an existing skill body. Never invent a new top-level directory.
+4. **Move content; insert pointer.** Cut the section into the target file. Replace it in AGENTS.md with a single substantive pointer per anatomy above. Verify the *why*-clause length.
+5. **Re-measure.** `wc -c AGENTS.md` again. If above 2,200, repeat steps 2–4 on the next-largest section. Above 2,500 = must outboard further before commit.
+6. **Validate pointer ratio.** Count non-blank lines and substantive-pointer lines. Ratio < 0.40 = collapse decorative or boilerplate lines into a single pointer or remove.
+7. **Verify emergency-triage block.** Diff the in-file block against `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md`. Drift = revert to canonical.
+8. **Run lints.** `task lint-agents-md && task check-refs && task lint-skills`. All green before commit.
+
+## Procedure — apply Thin-Root to consumer template
+
+Same procedure, applied to `.agent-src.uncompressed/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/contexts/`, ...), not this package's authoring tree.
+
+## Gotchas
+
+- **Outboarding to a new top-level dir.** Inventing `agents/explainers/` or `docs/notes/` for the moved content silently widens the contract surface. Outboard only into `.agent-src.uncompressed/contexts/`, `docs/contracts/`, an existing rule body, or an existing skill body.
+- **Pointer-ratio inflation by decoration.** Adding boilerplate "Browse all skills" / "See also" links to lift the ratio above 40 % defeats the purpose. The lint counts only substantive pointers (with a *why*-clause ≥ 60 chars); decorative links get filtered out and the ratio drops back below threshold.
+- **Emergency-triage drift.** Editing the in-file emergency-triage block instead of the canonical `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` causes the package-root and consumer-template versions to diverge silently. Always edit the canonical file and let the lint diff pull both back in sync.
+- **Cap inversion under WARN.** A 2,250-char AGENTS.md (above 2,200 WARN, below 2,500 FAIL) is a yellow signal not a green one — every additional sentence raises the probability of the next FAIL. Treat WARN as the spend boundary, not a buffer.
+- **Char-count includes frontmatter.** `wc -c` counts every byte including the YAML preamble, blank lines, and the trailing newline. Stripping a section to "look smaller" without re-running `wc -c` understates the true budget impact.
+
+## Output format
+
+When invoked as a planning step, produce:
+
+1. Current size + gap to target (one line per file).
+2. Inventory table (section, chars, keep-inline / outboard-candidate, target).
+3. Pointer ratio before / after (predicted).
+4. Specific outboarding edits as a numbered diff plan.
+5. The four lint commands the agent must run before claiming completion.
+
+## See also
+
+- [`copilot-agents-optimization`](../copilot-agents-optimization/SKILL.md) — sibling skill for `.github/copilot-instructions.md`; runs alongside Thin-Root in `/optimize/agents`.
+- [`agent-docs-writing`](../agent-docs-writing/SKILL.md) — broader documentation-structure context for navigating outboard targets.
+- [`size-enforcement`](../../rules/size-enforcement.md) — covers per-skill / per-rule / per-command size budgets; AGENTS.md caps live in this skill instead.
+- [`ADR-004-rule-governance-pruning`](../../../docs/decisions/ADR-004-rule-governance-pruning.md) — captures the rule-governance pruning that freed the workspace-guidelines budget; the Thin-Root caps build on that headroom.

package/.agent-src/skills/ai-council/SKILL.md

@@ -235,9 +235,10 @@ durable contract lives in the roadmap / ADR / skill body that cites
 the council's convergence inline.
 
 **Linking to a specific council file is forbidden by
-[`no-council-references`](../../rules/no-council-references.md)** —
-gitignored, not in the cloned repo, gone after the retention window.
-Inline the convergence with date + members instead.
+[`no-roadmap-references`](../../rules/no-roadmap-references.md)
+(council clause)** — gitignored, not in the cloned repo, gone after
+the retention window. Inline the convergence with date + members
+instead.
 
 Three directories, three modes:
 
@@ -258,10 +259,11 @@ matching `road-to-<topic-slug>` roadmap under `agents/roadmaps/`).
 - Any other directory below `agents/` (e.g. `agents/scratch/`,
   `agents/tmp/`).
 - Cross-references from any artefact to specific council files —
-  see [`no-council-references`](../../rules/no-council-references.md).
-  Inline the convergence summary instead, with date and member list
-  for traceability (`Council (claude-sonnet-4-5 + gpt-4o, YYYY-MM-DD)
-  reviewed N candidate strategies; converged on …`).
+  see [`no-roadmap-references`](../../rules/no-roadmap-references.md)
+  (council clause). Inline the convergence summary instead, with
+  date and member list for traceability (`Council (claude-sonnet-4-5
+  + gpt-4o, YYYY-MM-DD) reviewed N candidate strategies; converged
+  on …`).
 
 `scripts/check_council_layout.py` is the mechanical check for the
 output path convention — wire it into the package's CI pipeline so

package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -285,6 +285,15 @@ Decision: Create focused skill for Laravel route inspection via JSON and jq.
 Learning: "I forgot to run PHPStan once."
 Decision: No action — one-off, already covered by verify-before-complete rule.
 
+Learning: "We re-invented a per-format PDF extractor in three different
+analysis skills."
+Decision: Update the affected skills to dispatch to
+[`markitdown`](../markitdown/SKILL.md) instead of writing new
+extractors. Non-text ingestion (PDF / DOCX / XLSX / PPTX / image /
+audio) goes through the upstream `markitdown-mcp` server first; only
+write a custom extractor if `markitdown` cannot handle the format and
+the gap is documented in its skill body.
+
 ## Environment notes
 
 Prefer updating existing rule/skill when possible.