@event4u/agent-config 1.23.0 → 1.25.0

package/AGENTS.md

@@ -1,221 +1,34 @@
 # event4u/agent-config
 
-> **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
-
-**Shared agent configuration** — skills, rules, commands, guidelines, and templates
-for AI coding tools (Augment Code, Claude Code, Cursor, Cline, Windsurf, Gemini CLI,
-GitHub Copilot).
-
-This file is the AGENTS.md **of the package itself**. It gives an agent that is
-working **on this repository** (adding skills, fixing the installer, improving
-the linter) the context it needs. Consumer projects get their own AGENTS.md
-generated from [`.augment/templates/AGENTS.md`](.agent-src/templates/AGENTS.md)
-when they install the package.
-
-## What this repo is
-
-`event4u/agent-config` is a **governed skill suite** for two cognition
-clusters: engineering depth (Wing 1) and senior cross-department
-cognition (Wings 2–4: Product + Foundation, GTM + Growth, Money +
-Strategy + Ops). The differentiator is **depth over breadth, decisions
-over boilerplate, under a shared Iron-Law floor** (`commit-policy`,
-`non-destructive-by-default`, `language-and-tone`, `skill-quality`,
-`direct-answers`). The same agent that ships a refactor commit also
-runs DCF sensitivity, OKR-tree decomposition, and launch-funnel
-diagnosis — under the same governance.
-
-Mechanically the package is:
-
-- A distribution package, not an application of any framework.
-- `type: library` in `composer.json`; no `app/` directory, no application
-  runtime (no Laravel, Symfony, Next.js, or other framework app code).
-- Published to Composer and npm as `event4u/agent-config` / `@event4u/agent-config`.
-- Installed into consumer projects via `scripts/install.sh` (Bash) and
-  `scripts/install.py` (Python bridge).
-
-## The four wings
-
-The skill suite is organized as four wings under one Iron-Law floor.
-Each wing has its own roadmap, its own personas, and its own plate;
-they compose via the cross-wing handoff contract
-([`docs/contracts/cross-wing-handoff.md`](docs/contracts/cross-wing-handoff.md) (beta),
-landing in `road-to-suite-closure.md` Phase 3).
-
-| Wing | Cognition cluster |
-|---|---|
-| **1 — Engineering** | Code craft, debugging, refactoring, release discipline; depth-first |
-| **2 — Product + Foundation** | Roles cluster (PM, designer, QA, EM); product discovery, prioritization, delivery shape |
-| **3 — GTM + Growth** | CMO + marketing + sales + lifecycle; channel-agnostic positioning + funnel cognition |
-| **4 — Money + Strategy + Ops** | CFO + COO + board-level strategy, valuation, org-design; stage-agnostic financial + operational cognition |
-
-Per-wing plates (roadmaps, persona maps, decision logs) live under
-`agents/roadmaps/` and `agents/contexts/`. Roadmaps are transient
-working layers — agents that need a wing's plate look it up by wing
-number rather than by file path (per `no-roadmap-references`).
+> Shared skill / rule / command suite for AI coding tools. No application runtime. AGENTS.md of the **package itself**.
 
 ## Source of truth
 
-| Directory | Purpose | Editable? |
-|---|---|---|
-| `.agent-src.uncompressed/` | Authoring layer — full verbose content | ✅ Yes — edit here |
-| `.agent-src/` | Compressed output — shipped in the package, consumed by agents | ❌ No — regenerated |
-| `.augment/` | Local projection of `.agent-src/` for Augment Code (gitignored) | ❌ No — regenerated |
-| `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` | Tool-specific projections | ❌ No — regenerated |
-| `agents/` | Package's own roadmaps, contexts, sessions | ✅ Yes |
-
-**Never edit `.agent-src/` or `.augment/` directly.** Edit `.agent-src.uncompressed/`
-and run `task sync` (or `task ci`) to compress + regenerate the tool directories.
-
-## Tech stack of this package
-
-- **Bash** — install scripts, compression driver
-- **Python 3.10+** — linters (`scripts/skill_linter.py`, `scripts/check_portability.py`,
-  `scripts/check_references.py`, `scripts/readme_linter.py`), compression tooling,
-  test suite (pytest)
-- **Markdown** — all content (skills, rules, commands, guidelines, templates)
-- **Taskfile** — developer entrypoints (`task ci`, `task sync`, `task test`)
-- **GitHub Actions** — CI workflow under `.github/workflows/`
-
-No application code or framework runtime (no Laravel / Symfony / Next.js /
-Express). The `composer.json` / `package.json` are thin distribution
-manifests.
-
-**Cognition-only floor for Wings 2–4.** Wings 2, 3, and 4 enforce a
-no-SaaS-auth, no-vendor-SDK, no-stage-prescription floor: cognition
-artifacts (markdown tables, scoring rubrics, walkthroughs) must work
-in any host without external dependencies. The structural-malice
-check in `skill_linter.py` enforces this boundary mechanically (no
-credential exfiltration, no remote execution, no shell injection in
-subprocess calls — see `.agent-src.uncompressed/rules/skill-quality.md`
-§ Structural Malice Floor).
+Edit `.agent-src.uncompressed/` only. Generated trees (`.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`) regenerate from `task sync` + `task generate-tools`; never hand-edit.
 
 ## Working on this repo
 
 ```bash
-task sync                  # .agent-src.uncompressed/ → .agent-src/, then project → .augment/
-task generate-tools        # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
-task test                  # pytest tests/ + tests/test_install.sh
-task lint-skills           # python3 scripts/skill_linter.py --all
-task build-cloud-bundles-all  # ZIP every eligible skill → dist/cloud/ (Claude.ai Web / Skills API)
-task ci                    # Full pipeline — must be green before PR
-```
-
-All checks must pass before a PR: sync-check, consistency, check-compression,
-check-refs, check-portability, lint-skills, test, lint-readme.
-
-## Maintainer telemetry (opt-in)
-
-The artefact-engagement telemetry pipeline (`./agent-config telemetry:record`
-and `./agent-config telemetry:report`) is **default-off**. Maintainers who
-want to measure which skills/rules/commands the agent actually applies set
-`telemetry.artifact_engagement.enabled: true` in `.agent-settings.yml`. The
-log is local-only JSONL (no upload, no cross-project share) and is bound
-by the redaction floor described in
-[`contexts/contracts/artifact-engagement-flow.md`](.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md) (beta).
-The recording rule lives at
-[`.agent-src/rules/artifact-engagement-recording.md`](.agent-src/rules/artifact-engagement-recording.md).
-
-## Context-aware command suggestion
-
-When a user's free-form prompt matches a command's purpose, the agent
-surfaces matches as a numbered-options block with an always-present
-"run the prompt as-is" escape. **Nothing auto-executes** — the user
-picks every time. Engine: `scripts/command_suggester/`. Rule:
-[`.agent-src/rules/command-suggestion-policy.md`](.agent-src/rules/command-suggestion-policy.md).
-Locked eligibility table, scoring contract, and hardening list:
-[`docs/contracts/adr-command-suggestion.md`](docs/contracts/adr-command-suggestion.md)
-and
-[`contexts/contracts/command-suggestion-flow.md`](.agent-src.uncompressed/contexts/contracts/command-suggestion-flow.md) (beta).
-
-## Key rules for agents editing this repo
-
-| Rule | File |
-|---|---|
-| `.agent-src/` must stay project-agnostic — no project names, domains, stacks | [`augment-portability`](.agent-src/rules/augment-portability.md) |
-| Root AGENTS.md + copilot-instructions.md must stay project-agnostic too | [`augment-portability`](.agent-src/rules/augment-portability.md) |
-| Edit `.agent-src.uncompressed/`, never `.agent-src/` or `.augment/` | [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md) |
-| Skills must declare frontmatter, be self-contained, pass the linter | [`skill-quality`](.agent-src/rules/skill-quality.md) |
-| Size budgets for skills, rules, commands | [`size-enforcement`](.agent-src/rules/size-enforcement.md) |
-| Keep `.agent-src/` / `agents/` cross-refs in sync on add/rename/delete | [`docs-sync`](.agent-src/rules/docs-sync.md) |
-| Creating a new skill/rule/command/guideline runs Understand → Research → Draft | [`artifact-drafting-protocol`](.agent-src/rules/artifact-drafting-protocol.md) |
-
-## Kernel + Router
-
-The rule set runs on a **Kernel + Router** model (locked 2026-05-06,
-see [`docs/decisions/ADR-rule-kernel-and-router.md`](docs/decisions/ADR-rule-kernel-and-router.md)):
-
-- **Kernel** = 9 always-loaded Iron-Law rules, ≤ 26k chars
-  (`agent-authority`, `ask-when-uncertain`, `commit-policy`,
-  `direct-answers`, `language-and-tone`, `no-cheap-questions`,
-  `non-destructive-by-default`, `scope-control`, `verify-before-complete`).
-  Locked set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-membership.md) (beta).
-- **Router** = frontmatter `tier:` + `triggers:` + `routes_to:` keys
-  on every rule. `scripts/compile_router.py` builds `router.json`
-  deterministically. Contract: [`docs/contracts/rule-router.md`](docs/contracts/rule-router.md) (beta).
-- **Cost profiles** gate which tiers load:
-  `minimal` = kernel only · `balanced` = kernel + tier-1 (default) ·
-  `full` = kernel + tier-1 + tier-2.
-
-Hard caps enforced by `task lint-rule-budget`: kernel-bucket ≤ 26k chars,
-per-rule ≤ 2.5k chars (Iron-Law overrides up to 4.0k via ADR in
-[`docs/decisions/`](docs/decisions/) and
-[`docs/contracts/iron-law-overrides.txt`](docs/contracts/iron-law-overrides.txt)).
-Daily snapshots: `python3 scripts/measure_rule_budget.py --trend-append`
-appends to `agents/.rule-budget-history.jsonl`.
-
-## Repository layout
-
-```
-.agent-src.uncompressed/      ← edit here
-  skills/       (140 skills)
-  rules/        (60 rules)
-  commands/     (103 commands)
-  personas/     (7 personas)
-  templates/    (AGENTS.md, copilot-instructions.md, skill.md, …)
-  contexts/
-
-docs/guidelines/            (47 guidelines — reference material, not packaged)
-docs/contracts/             (kernel-membership, rule-router, rule-classification, …)
-docs/decisions/             (ADRs — kernel overrides, scope decisions)
-.agent-src/                 ← compressed output shipped in the package
-.agent-src/router.json      ← compiled router manifest (consumed at runtime)
-.augment/                   ← local projection for Augment Code (gitignored)
-scripts/                    ← install.sh, install.py, compress.py, linters
-tests/                      ← pytest (324 tests) + test_install.sh
-agents/                     ← this package's own roadmaps / sessions / contexts
-.github/workflows/          ← CI
+task sync              # regenerate .agent-src/, .augment/
+task generate-tools    # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
+task ci                # full pipeline — green before PR
 ```
 
-## Multi-agent tool support
-
-`task generate-tools` builds:
-
-| Tool | Output | Strategy |
-|---|---|---|
-| Augment Code | `.augment/` | 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 |
-| Claude.ai Web / Skills API | `dist/cloud/<skill>.zip` | `task build-cloud-bundles-all` (T3-H gated) |
-
-Skills follow the [Agent Skills open standard](https://agentskills.io). Commands
-are converted to Claude Code Skills with `disable-model-invocation: true`.
-Cloud bundles enforce description budgets and prepend a sandbox note for
-T2/T3-S skills — see [`docs/architecture.md`](docs/architecture.md#cloud-bundle-pipeline).
+## Pointers
 
-## Contributing
+- **Package self-orientation** — identity, four-wing cognition map, repo layout, tech stack, key-rules table, telemetry, command-suggester: [`docs/contracts/package-self-orientation.md`](docs/contracts/package-self-orientation.md).
+- **Kernel + Router** — 9 always-loaded Iron-Law rules, tier-1 / tier-2 routing, cost profiles, per-rule char caps enforced by `task lint-rule-budget`: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
+- **Multi-tool projection** — Augment, Claude Code, Cursor, Cline, Windsurf, Gemini CLI, Claude.ai bundle pipeline that ships from `.agent-src/` to consumer surfaces: [`docs/architecture.md`](docs/architecture.md#cloud-bundle-pipeline).
+- **Iron-Law rules when editing this repo** — portability, source-of-truth, skill-quality: [`augment-portability`](.agent-src/rules/augment-portability.md), [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md), [`skill-quality`](.agent-src/rules/skill-quality.md).
+- **Thin-Root contract** governing **this** file (cap, pointer ratio, emergency-triage block) — read before editing AGENTS.md: [`agents-md-thin-root`](.agent-src/skills/agents-md-thin-root/SKILL.md).
+- **Consumer story + architecture deep-dive** — what the package does for installers and how it ships: [`README.md`](README.md), [`docs/architecture.md`](docs/architecture.md).
 
-1. Edit inside `.agent-src.uncompressed/` or `scripts/` or `tests/` — never in
-   `.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, etc.
-2. Run `task ci` locally. It must exit 0.
-3. Commit in logical chunks with Conventional Commits.
-4. Open a PR against `main`.
+## Emergency triage — read this when nothing else is reachable
 
-See [`README.md`](README.md) for the user-facing story, and
-[`docs/architecture.md`](docs/architecture.md) for the package architecture.
+1. **What is this repo?** — `event4u/agent-config`, a governed skill / rule / command suite for AI coding tools (no application runtime).
+2. **What language?** — All `.md` content is English; agents mirror the user's language at runtime.
+3. **Where do I edit?** — `.agent-src.uncompressed/` only. Never `.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`.
+4. **Lint / test / sync entry point?** — `task ci` (full pipeline). Subsets: `task sync`, `task generate-tools`, `task lint-skills`, `task test`.
+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`).
 
-## License
 
-[MIT](LICENSE).

package/CHANGELOG.md

@@ -318,6 +318,76 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.25.0](https://github.com/event4u-app/agent-config/compare/1.24.0...1.25.0) (2026-05-08)
+
+### Features
+
+* **scope-control:** mandate branch-base inventory before first commit ([b038c26](https://github.com/event4u-app/agent-config/commit/b038c2660f8e317f09156ff00120bcdf31d7db92))
+* **ci:** agents-md linter + CI integration (Phase 7) ([dd86beb](https://github.com/event4u-app/agent-config/commit/dd86bebd929bb3dde96e4100e96645a674f137fa))
+* **agents-md:** Thin-Root refactor — agents-md-thin-root skill + content (Phase 6) ([7d31204](https://github.com/event4u-app/agent-config/commit/7d31204659a0ce085bb8a8f45b16de34cae06a78))
+* **rules:** rule-governance audit — demote 4 auto-rules to manual (Phase 5) ([5071ff5](https://github.com/event4u-app/agent-config/commit/5071ff5855cf67c61303bb4cb07c4229fbbb4dd4))
+* **rules:** consolidate auto-rules — merge council into no-roadmap-references and review-routing-awareness into reviewer-awareness (Lever D) ([18c42a3](https://github.com/event4u-app/agent-config/commit/18c42a33af0d950e07c50615615d4deb076071ff))
+* **docs:** outboard AGENTS.md tech-stack details to context (Lever B) ([9b7bcfd](https://github.com/event4u-app/agent-config/commit/9b7bcfd374ce3325dd7013e530ce71f4b92df4eb))
+* **budget:** augment workspace-guidelines budget meter + description cap (Lever A) ([da75061](https://github.com/event4u-app/agent-config/commit/da750615acbf9a687b81b1ecaff6d517a11203fb))
+* **ci:** enforce one kernel-rule edit per PR ([a91ce92](https://github.com/event4u-app/agent-config/commit/a91ce927dc2a98129a7b685f803f7650863b31fa))
+
+### Bug Fixes
+
+* **roadmap:** repoint sibling-roadmap reference to archived path ([f7ee632](https://github.com/event4u-app/agent-config/commit/f7ee632800290d3cd90f2dd1274e47e8127f1f63))
+* **tests:** align update_counts + linter + hero-counts tests with Thin-Root ([5556c8c](https://github.com/event4u-app/agent-config/commit/5556c8ce1a8cf4df7a7b4a957030d5b5d2d0fd7e))
+* **skills:** mark agents-md-thin-root cloud_safe noop ([17a3824](https://github.com/event4u-app/agent-config/commit/17a3824ddd1ea567fca8b699113b2c62050c5507))
+* **docs:** move agents-md-tech-stack from agents/contexts/ to docs/contracts/ ([77eef8c](https://github.com/event4u-app/agent-config/commit/77eef8c61d2561ef5a563518f2bdb1dff80541c7))
+* **rules:** drop forbidden agents/ link from reviewer-awareness body ([8a573a4](https://github.com/event4u-app/agent-config/commit/8a573a48bc959f0c16ea8b56fc0e6bd0d3139238))
+* **refs:** point to archived roadmap, inline council convergence ([bf56b70](https://github.com/event4u-app/agent-config/commit/bf56b7084dae68fe2a21e52d7cb644ed6b3bb670))
+
+### Documentation
+
+* **roadmap:** archive road-to-augment-limit-fit and repoint references ([58e101c](https://github.com/event4u-app/agent-config/commit/58e101c8a3421004929f47f4c760e44b97c124bc))
+* **roadmap:** flip 8.3 + 8.4 — strategic phases committed and CI green ([712c414](https://github.com/event4u-app/agent-config/commit/712c4141103dbdc6db7fa6d1fa94d31943bd40e1))
+* **roadmap:** drop gitignored council-response link ([74206a5](https://github.com/event4u-app/agent-config/commit/74206a592f47b9254c788b162ea3d99c54057506))
+* **roadmap:** close road-to-augment-limit-fit (Phase 8) ([ac062ad](https://github.com/event4u-app/agent-config/commit/ac062ad184764f04f639eb52d59b1d63419b4b9b))
+* **index:** regenerate agents/index.md + docs/catalog.md after rule consolidation ([3aa347c](https://github.com/event4u-app/agent-config/commit/3aa347c1e814a9c289891c350d69f8b9fda6783f))
+* **roadmap:** land road-to-augment-limit-fit + ADR + regen derived artefacts ([5e54d22](https://github.com/event4u-app/agent-config/commit/5e54d220579658c4fc2310f123908b8cba97683e))
+* **adr:** park always-budget relief strategy with reactivation triggers ([487e736](https://github.com/event4u-app/agent-config/commit/487e7366de6e99db60906906d61033486a0a6aa3))
+* **rules:** add kernel-rule slow-rollout guarantee to scope-control ([26c43a2](https://github.com/event4u-app/agent-config/commit/26c43a2c96ede95319990b4ba578a986e46768a2))
+
+### Refactoring
+
+* **copilot:** collapse copilot-review-instructions.md into copilot-instructions.md ([6c6ac25](https://github.com/event4u-app/agent-config/commit/6c6ac25a5958c3bbc0ffc7bb38422a6b9d855b50))
+
+### Chores
+
+* **tools:** regen .windsurfrules for branch-base inventory ([a87641c](https://github.com/event4u-app/agent-config/commit/a87641cc0db84e705a9afe7aa36afbd451fb1467))
+* **rebase:** restore compression hashes for files inherited from PR #55 ([863ba1c](https://github.com/event4u-app/agent-config/commit/863ba1cd71dc00559db905eb0d11b96951a9c5bd))
+* regenerate .windsurfrules ([822b95e](https://github.com/event4u-app/agent-config/commit/822b95e1dcf48b05ec4e9bec0a4f481583ae6de7))
+* **roadmap:** close + archive road-to-always-budget-relief, regen index ([350bfb1](https://github.com/event4u-app/agent-config/commit/350bfb1e75602769f6a1cfa535ed5d30adcd5eba))
+
+## [1.24.0](https://github.com/event4u-app/agent-config/compare/1.23.0...1.24.0) (2026-05-08)
+
+### Features
+
+* **rules:** harden roadmap-progress-sync — real-time checkbox cadence ([bdaaf0c](https://github.com/event4u-app/agent-config/commit/bdaaf0caff6d312ab87aabc8d170793cbbc6513a))
+* **measurement:** markitdown lift benchmark + corpus ([e606c7a](https://github.com/event4u-app/agent-config/commit/e606c7afae9977ab3c19f2a7f99a6ec18b31b483))
+* **skill:** add markitdown skill with four-layer defense ([21514f4](https://github.com/event4u-app/agent-config/commit/21514f4bf8b77d00480fc5dfab54a1a04e34f4f1))
+
+### Bug Fixes
+
+* drop markitdown roadmap link + trim README to 500 lines ([da8240d](https://github.com/event4u-app/agent-config/commit/da8240d6fce74555d08a8bfb4f4d15379d10de54))
+* **refs:** update markitdown roadmap path to archive/ after archival ([f7679de](https://github.com/event4u-app/agent-config/commit/f7679debb851bd721f671e26fe962186e56a1e86))
+
+### Documentation
+
+* feature markitdown in README, AGENTS, architecture ([fa1babc](https://github.com/event4u-app/agent-config/commit/fa1babcb344c5f090aa4cea0eafb58e5732cf872))
+* cross-link markitdown from analysis and learning skills ([14f9d72](https://github.com/event4u-app/agent-config/commit/14f9d7290dbcb341d2ff97280dbfb54b32e39057))
+
+### Chores
+
+* **generate-tools:** refresh .windsurfrules after roadmap-progress-sync body expansion ([3fdba11](https://github.com/event4u-app/agent-config/commit/3fdba11cd4e91425a05ef9ad82b0e7c611180668))
+* **compress:** sync .agent-src/ with hardened roadmap-progress-sync rule ([30e7d1a](https://github.com/event4u-app/agent-config/commit/30e7d1ab455da823afbe7602f01d543d3fe91c5d))
+* **roadmap:** archive markitdown-adoption + refresh progress dashboard ([5481d90](https://github.com/event4u-app/agent-config/commit/5481d9025f4c85f33e11533099cf725eeb306455))
+* add skills-provenance registry for upstream attribution ([65c2eeb](https://github.com/event4u-app/agent-config/commit/65c2eeb3d1c9d0f86957757ce22221ed0e255292))
+* **roadmap:** harden process-full to ignore horizon markers ([36d0fa6](https://github.com/event4u-app/agent-config/commit/36d0fa6c263721618999b7fa27ddb9cb336dd6c2))
+
 ## [1.23.0](https://github.com/event4u-app/agent-config/compare/1.22.0...1.23.0) (2026-05-08)
 
 ### Features

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>140 Skills</strong> · <strong>60 Rules</strong> · <strong>103 Commands</strong> · <strong>58 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>142 Skills</strong> · <strong>58 Rules</strong> · <strong>103 Commands</strong> · <strong>58 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -368,7 +368,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 140 skills + 103 native commands). Cursor, Cline, Windsurf,
+> package (rules + 142 skills + 103 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.

package/docs/architecture.md

@@ -96,8 +96,8 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 140 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
+| **Skills** | 142 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Rules** | 58 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 103 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 58 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
@@ -258,15 +258,21 @@ created by `scripts/install.sh`, not via raw git checkout. This means
 GitHub Copilot's static checker — which walks the git tree — will see
 broken paths where there are none. **The gap is intentional, not a bug.**
 
-The package ships two complementary suppression artefacts:
+The package ships **one** Copilot instruction artefact:
 
 | File | Read by | Purpose |
 |---|---|---|
-| `.github/copilot-instructions.md` | Copilot Chat + PR review | Repo-wide coding standards, self-contained behavior |
-| `.github/copilot-review-instructions.md` | Copilot PR review | Path-resolution suppression floor (this section's mate) |
+| `.github/copilot-instructions.md` | Copilot Chat + PR review | Repo-wide coding standards plus the path-resolution suppression floor (Known False Positives) |
 
-Both are installed (copy-if-missing) by `scripts/install.sh` from
-`.agent-src.uncompressed/templates/`. Consumers can edit them freely;
+Per [GitHub's documented convention](https://docs.github.com/en/copilot/reference/custom-instructions-support),
+Copilot Code Review reads `.github/copilot-instructions.md`
+repository-wide and `.github/instructions/**/*.instructions.md` for
+path-specific rules — there is no separate "review-only" instruction
+file. The first 4000 characters are the budget; keep
+high-priority rules (Scope Control, Known False Positives) up top.
+
+Installed (copy-if-missing) by `scripts/install.sh` from
+`.agent-src.uncompressed/templates/`. Consumers can edit it freely;
 the installer never overwrites.
 
 The mechanical floor is `scripts/check_compressed_paths.py`, wired into