@event4u/agent-config 1.24.0 → 1.25.0

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/review-routing/SKILL.md

@@ -26,7 +26,7 @@ Do NOT use when:
 - The diff is low-risk and no ownership map exists — fall back to
   [`reviewer-awareness`](../../rules/reviewer-awareness.md) defaults.
 - A full PR description is requested — route to
-  [`create-pr-description`](../create-pr-description/SKILL.md) and let
+  [`create-pr-description`](../create-pr:description-only/SKILL.md) and let
   it call this skill for the routing block.
 - A threat model is wanted — route to
   [`threat-modeling`](../threat-modeling/SKILL.md).
@@ -187,9 +187,8 @@ Data source: <"ownership-map.yml + historical-bug-patterns.yml"
 
 ## See also
 
-- [`reviewer-awareness`](../../rules/reviewer-awareness.md)
-- [`review-routing-awareness`](../../rules/review-routing-awareness.md)
+- [`reviewer-awareness`](../../rules/reviewer-awareness.md) — role vocabulary + data-source rules
 - [`review-routing-data-format`](../../../docs/guidelines/agent-infra/review-routing-data-format.md)
-- [`create-pr-description`](../create-pr-description/SKILL.md)
+- [`create-pr-description`](../create-pr:description-only/SKILL.md)
 - [`judge-test-coverage`](../judge-test-coverage/SKILL.md) — consumes
   the `required_test` entries from matched patterns.

package/.agent-src/templates/AGENTS.md

@@ -1,164 +1,34 @@
 # {{project_name}}
 
 <!--
-  AGENTS.md — entry point for AI coding agents working on this project.
-
-  This file was installed by `event4u/agent-config` as a starting template.
-  Fill in the placeholders below (or run `/copilot-agents-init` to do it
-  interactively) and then delete this HTML comment.
-
-  Keep it short. Detailed conventions belong in `.augment/` (read-only from
-  the shared package) or in `agents/overrides/` (project-specific).
+  AGENTS.md entry point for AI coding agents. Installed by
+  `event4u/agent-config`. Fill placeholders (or run `/copilot-agents-init`)
+  and delete this comment. Keep thin; bulk prose belongs in the linked guide.
 -->
 
 {{project_description}}
 
-## Agent Infrastructure
+## Layers
 
 | Layer | Location | Purpose |
 |---|---|---|
-| **Shared package** | `.augment/` | Skills, rules, commands, guidelines, templates — read-only |
+| **Shared package** | `.augment/`, `.agent-src/` | Installed skills / rules / commands — do not hand-edit |
 | **Project overrides** | `agents/overrides/` | Customizations of shared resources |
 | **Project docs** | `agents/` | Architecture, features, roadmaps, sessions, contexts |
-| **Agent settings** | `.agent-settings.yml` | Project-specific config consumed by skills (YAML) |
-
-### Key References
-
-| What | Where |
-|---|---|
-| Behavior rules (always active) | `.augment/rules/` |
-| Coding guidelines | `.augment/guidelines/` |
-| Skills (on-demand expertise) | `.augment/skills/` |
-| Commands (workflows) | `.augment/commands/` |
-| Copilot instructions | `.github/copilot-instructions.md` |
-
-### Recommended entry flow
-
-Two entrypoints share the same engine and Option-A loop; pick by input shape:
-
-| You have | Command | Envelope |
-|---|---|---|
-| Ticket id, URL, or pasted ticket payload | [`/implement-ticket`](.augment/commands/implement-ticket.md) | `input.kind="ticket"` |
-| Free-form goal, no ticket | [`/work`](.augment/commands/work.md) | `input.kind="prompt"` |
-
-Both drive the linear flow `refine → memory → analyze → plan → implement →
-test → verify → report` with block-on-ambiguity semantics and no auto-git.
-
-`/work` adds a confidence-band gate at `refine`: the
-[`refine-prompt`](.augment/skills/refine-prompt/SKILL.md) skill scores the
-prompt on five dimensions and the engine proceeds **silently** on `high`,
-halts with an **assumptions report** on `medium`, or halts with **one
-clarifying question** on `low` (per the `ask-when-uncertain` Iron Law).
-UI-shaped prompts route through the product UI track (`directive_set`
-`ui` / `ui-trivial` / `mixed`) — `audit → design → apply → review →
-polish` with a hard audit gate before any `apply`.
-
-Persona comes from `.agent-settings.yml` (`roles.active_role`). Use
-`/commit` and `/create-pr` explicitly after the delivery report. The two
-flows are mutually exclusive at the state-file level: one
-`.work-state.json` carries one envelope at a time; the engine refuses to
-switch mid-flight.
-
-### Multi-Agent Support
-
-| Tool | Rules | Skills | How |
-|---|---|---|---|
-| **Augment Code** | `.augment/rules/` | `.augment/skills/` | Native (source) |
-| **Claude Code** | `.claude/rules/` | `.claude/skills/` | Symlinks + Agent Skills standard |
-| **Cursor** | `.cursor/rules/` | — | Symlinks |
-| **Cline** | `.clinerules/` | — | Symlinks |
-| **Windsurf** | `.windsurfrules` | — | Concatenated file |
-| **Gemini CLI** | `GEMINI.md` | — | Symlink → AGENTS.md |
-
-Regenerate: `task generate-tools` · Clean: `task clean-tools`
-(Requires the `task` binary; see https://taskfile.dev if missing.)
-
----
-
-## Tech Stack
-
-<!-- Replace with your actual stack. Examples:
-  - Framework: Laravel 11 (PHP ^8.2) / Next.js 15 / Rails 7 / Django 5
-  - Database: PostgreSQL / MySQL / MariaDB / SQLite
-  - Queue: Redis / RabbitMQ / SQS
-  - Testing: Pest / PHPUnit / Jest / Vitest / pytest
-  - Code style / linters: ECS / PHPStan / Ruff / ESLint
--->
-
-- **Language:** {{primary_language}}
-- **Framework:** {{framework}}
-- **Database:** {{database}}
-- **Testing:** {{test_framework}}
-- **Code style:** {{code_style_tool}}
-
----
-
-## Development Setup
-
-<!-- Replace with your project's actual setup commands. Examples:
-  - `make start` / `make console` / `make test`
-  - `docker compose up` / `docker compose exec app bash`
-  - `npm run dev` / `npm test`
-  - `php artisan serve` / `php artisan test`
--->
-
-```bash
-{{dev_start_command}}
-{{dev_test_command}}
-```
-
-### Environment files
-
-| File | Purpose |
-|---|---|
-| `.env` | Main environment |
-| `.env.local` | Local overrides |
-| `.env.testing` | Testing env |
-
----
-
-## Project Structure
-
-<!-- Document your directory conventions:
-  - Where new features go
-  - Module/component boundaries
-  - Namespace conventions
--->
-
-{{project_structure_notes}}
-
----
-
-## Testing
-
-<!-- Document:
-  - Test framework and its quirks
-  - How to run all tests / targeted tests
-  - Test data strategy (seeders, factories, fixtures)
-  - Performance-critical tests or suites
--->
-
-{{testing_notes}}
-
----
-
-## Quality Tools
-
-<!-- Document:
-  - Which linters/formatters run
-  - Whether they auto-fix or report only
-  - CI enforcement level
--->
+| **Agent settings** | `.agent-settings.yml` | Project-specific config consumed by skills |
 
-{{quality_tools_notes}}
+## Pointers
 
----
+- **Filling out this AGENTS.md** — tech-stack / dev-setup / testing / quality / project-structure templates plus `/work` + `/implement-ticket` entry flow and multi-agent matrix: [`.augment/contexts/contracts/consumer-agents-md-guide.md`](.augment/contexts/contracts/consumer-agents-md-guide.md).
+- **Behavior rules (always active)** — Iron Laws and routed rules that fire automatically while you work in this project: [`.augment/rules/`](.augment/rules/).
+- **Skills (on-demand expertise)** — domain skills surfaced by description; invoked when their trigger fires: [`.augment/skills/`](.augment/skills/).
+- **Commands (workflows)** — slash-commands the agent runs end-to-end (`/work`, `/implement-ticket`, `/commit`, `/create-pr`, …): [`.augment/commands/`](.augment/commands/).
+- **Project-specific docs** — your own architecture notes, roadmaps, sessions, contexts: [`agents/`](agents/).
 
-## Additional Documentation
+## Emergency triage — read this when nothing else is reachable
 
-| Document | Topic |
-|---|---|
-| `.github/copilot-instructions.md` | Coding standards for GitHub Copilot (self-contained) |
-| `agents/` | Project-specific architecture docs and roadmaps |
-| `.augment/contexts/` | Shared cross-cutting concepts from the package |
-| `.agent-settings.yml` | Project-specific agent configuration (YAML) |
+1. **What is this repo?** — Consumer project; agent-config is installed as a shared skill / rule / command suite at `.augment/` and `.agent-src/`.
+2. **What language?** — Project-specific; agents mirror the user's language at runtime.
+3. **Where do I edit agent-config?** — Do not edit `.augment/` or `.agent-src/` here; they are installed artifacts. Project edits live in `agents/` and project source.
+4. **Lint / test / sync entry point?** — Project-specific (see project README); agent-config reinstalls via `composer update event4u/agent-config` or `npm update @event4u/agent-config`.
+5. **Where do the always-active rules live?** — `.agent-src/rules/` (kernel = 9 Iron-Law rules; tier-1 / tier-2 routed via `.agent-src/router.json`).

package/.agent-src/templates/copilot-instructions.md

@@ -1,16 +1,22 @@
 # Copilot Repository Instructions
 
 <!--
-  copilot-instructions.md — read by GitHub Copilot Code Review (PR bot) and
-  Copilot Chat when reviewing or editing this repo.
+  copilot-instructions.md — the ONE file GitHub Copilot Code Review (PR bot)
+  loads from `.github/`. Also read by Copilot Chat when editing this repo.
 
   This file was installed by `event4u/agent-config` as a starting template.
   Fill in the placeholders below and remove this HTML comment.
 
   Keep this file **self-contained**. Copilot Code Review CANNOT follow links
   to `.augment/` — so every rule Copilot must enforce lives here in full.
+  Copilot Code Review only reads the **first 4000 characters**; keep the
+  highest-priority rules (Scope Control, Known False Positives) up top.
   Copilot Chat (in the IDE) can read other files, but still benefits from
   this overview.
+
+  For path-specific rules, use `.github/instructions/<NAME>.instructions.md`
+  with an `applyTo:` frontmatter glob — that is GitHub's documented
+  convention for narrowing instructions to a subtree.
 -->
 
 This repository contains {{project_description_oneline}}.
@@ -89,23 +95,41 @@ This repository contains {{project_description_oneline}}.
 ## ✅ Known False Positives — Do NOT Flag
 
 The repo ships agent-config rules and skills under `.augment/`,
-`.agent-src/`, and `.agent-src.uncompressed/`. These trees use a
-deliberate path convention; the following patterns are **correct by
-design** — do not flag them as broken:
-
-- **Relative cross-references inside markdown rules / skills** like
-  `[x](../docs/guidelines/foo.md)` or `[y](../contexts/bar.md)`. The
-  base resolves from the file's delivered location (e.g.
-  `.augment/rules/<rule>.md`) — these paths are valid via the
-  `.augment/` tree, even when the file is symlinked into
-  `.claude/rules/`, `.cursor/rules/`, or `.clinerules/`.
+`.agent-src/`, and (during authoring) `.agent-src.uncompressed/`.
+Cross-references inside those trees resolve via the **delivered**
+`.augment/` layout — not via raw git checkout. Copilot's static
+checker walks the git tree, so it sees broken paths where there are
+none. **Intentional, not a bug.** The installer projects
+`.agent-src/` → `.augment/` and creates the symlinks that make paths
+resolve at agent runtime. The patterns below are correct by design:
+
+- **Relative cross-references inside markdown rules / skills /
+  commands** like `[x](../docs/guidelines/foo.md)` or
+  `[y](../contexts/bar.md)`. The base resolves from the file's
+  delivered location (e.g. `.augment/rules/<rule>.md`) — these paths
+  are valid via the `.augment/` tree, even when the file is symlinked
+  into `.claude/rules/`, `.cursor/rules/`, or `.clinerules/`.
 - **`path_prefix:` triggers containing `.agent-src.uncompressed/`**
   in YAML frontmatter. This is a literal match pattern for the
-  host's router, **not** a file reference — keeping the verbatim
-  source path is required for the rule to fire on the right edits.
-- **Symlinked rule files** under `.claude/rules/`, `.cursor/rules/`,
-  `.clinerules/`. Targets resolve into `.augment/rules/`; missing-file
-  reports here are renderer artifacts, not real bugs.
+  host's router, **not** a file reference — source-of-truth meta-rules
+  (`augment-source-of-truth`, `augment-portability`, `skill-quality`,
+  `docs-sync`, `rule-type-governance`) legitimately match against the
+  authoring tree.
+- **Symlinked rule / skill / command files** under `.claude/`,
+  `.cursor/`, `.clinerules/`. Targets resolve into `.augment/rules/`,
+  `.augment/skills/`, `.augment/commands/` via installer-managed
+  symlinks. Missing-file reports here are renderer artifacts.
+- **Body-link forms `../docs/guidelines/...`** (single-up). This is
+  the post-rewrite shape produced by `scripts/compress.py`. The
+  compressed `.agent-src/rules/` tree is one level deeper than the
+  source `.agent-src.uncompressed/rules/`, so the rewriter collapses
+  `../../docs/...` to `../docs/...`. Both forms are expected — one in
+  source, one in compressed output.
+
+**What TO flag:** code defects, security issues, broken tests, type
+errors, and any new `.agent-src.uncompressed/` substring introduced
+into `.agent-src/rules/` body content (the `check-compressed-paths`
+task gates this — flag it as a regression if it slips through).
 
 ## ✅ Code Review Comment Behavior
 

package/.agent-src/templates/github-workflows/pr-risk-review.yml

@@ -106,7 +106,7 @@ jobs:
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
         # The script auto-discovers ownership-map.yml and
         # historical-bug-patterns.yml under .github/ first and falls
-        # back to agents/ — matching the review-routing-awareness rule.
+        # back to agents/ — matching the reviewer-awareness rule.
         # Missing data files emit a generic fallback, not an error.
         run: |
           python3 scripts/pr_review_routing.py \

package/.agent-src/templates/scripts/pr_review_routing.py

@@ -22,7 +22,7 @@ Usage:
 
 If --ownership-map / --patterns are omitted, the script searches
 `.github/` first and falls back to `agents/` — matching what the
-review-routing-awareness rule and review-routing skill document.
+reviewer-awareness rule and review-routing skill document.
 Missing data files are not an error; the script emits a generic
 fallback block.
 

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.24.0"
+    "version": "1.25.0"
   },
   "plugins": [
     {
@@ -23,6 +23,7 @@
         "./.claude/skills/agents",
         "./.claude/skills/agents-audit",
         "./.claude/skills/agents-cleanup",
+        "./.claude/skills/agents-md-thin-root",
         "./.claude/skills/agents-prepare",
         "./.claude/skills/ai-council",
         "./.claude/skills/analysis-autonomous-mode",