@event4u/agent-config 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -318,6 +318,72 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.21.0](https://github.com/event4u-app/agent-config/compare/1.20.0...1.21.0) (2026-05-06)
+
+### Features
+
+* **linter:** add council-reference guard with pragma suppressions ([734b7ae](https://github.com/event4u-app/agent-config/commit/734b7ae61d53c17fadb78f6f68bb54e3fe7cdde8))
+* **linter:** density-gated size warnings (council Option 2) ([281b9aa](https://github.com/event4u-app/agent-config/commit/281b9aa6f52640a93cf55c7b13678fbd2ea85077))
+* **skills:** add prompt-optimizer skill and /optimize-prompt command ([4f99e50](https://github.com/event4u-app/agent-config/commit/4f99e50ae46b19eab3eed2629bb94ac5d017151e))
+* **path-fixes:** finalize Phase 5-7 — checker, smoke, copilot review, contracts move ([3c5fc5d](https://github.com/event4u-app/agent-config/commit/3c5fc5d100ea7c542a48778e4e0669f551fad946))
+* **install:** rules_use_symlinks toggle for both compress.py and install.sh ([927adc3](https://github.com/event4u-app/agent-config/commit/927adc35002588eef4d24825c313e6a9511d6ca1))
+* **ai-council:** default rounds via ai_council.min_rounds (default 2) ([26da301](https://github.com/event4u-app/agent-config/commit/26da30125a0b5a2c74c9c48cf6a2f8e2e5d021dd))
+* **ai-council:** isolate council artefacts as gitignored, auto-pruned scratch ([ab0e245](https://github.com/event4u-app/agent-config/commit/ab0e245734c8560f6d93df927b8af6d105c1d8dc))
+* **rules:** enforce logical-name path conventions for load_context ([fd12ff6](https://github.com/event4u-app/agent-config/commit/fd12ff6b37cec7d2be8ea88d3ec055333fea13e2))
+* **rules:** land kernel + router architecture ([d4fe80e](https://github.com/event4u-app/agent-config/commit/d4fe80e1ce2a956eb86df328de32e3252515553f))
+* **linter:** validate router frontmatter schema (P3.3) ([124e4d7](https://github.com/event4u-app/agent-config/commit/124e4d7387c4f6b90dba5a60179580af5ba5ed45))
+* **router:** compile router.json + wire into CI (P3.2) ([a050a5c](https://github.com/event4u-app/agent-config/commit/a050a5c7b1ba4900be8d7439eadf5cd2953f15d1))
+* **router:** add rule-router schema contract (P3.1) ([e7b1088](https://github.com/event4u-app/agent-config/commit/e7b108809d2fc1f26b4f8f4254044c6019b75a90))
+* **kernel:** add Iron-Law SHA tooling + raise bucket cap to 26k (ADR-002) ([2f8b867](https://github.com/event4u-app/agent-config/commit/2f8b867bb1c306d8c03a754f68f8c82a53013689))
+* **kernel:** land P2.1 — kernel-budget enforcement + ADR-001 ([dd7d50a](https://github.com/event4u-app/agent-config/commit/dd7d50aeb81ca53c430d84d1c0ba36a93008c7f8))
+* **scripts:** add rule-budget measurement + Phase-1 pilot tooling ([396a85f](https://github.com/event4u-app/agent-config/commit/396a85fef25578871566c6c463f57e23b7f95ef2))
+
+### Bug Fixes
+
+* **commands:** add cluster: optimize to optimize-prompt frontmatter ([bdc3907](https://github.com/event4u-app/agent-config/commit/bdc390772086fa4c13dba1142eb2b82ab133f5a7))
+* **compress:** protect rule examples with inline-code backticks ([c5ea62b](https://github.com/event4u-app/agent-config/commit/c5ea62ba8937d52651544b8509b955498e109579))
+* **schema:** accept rewritten ../contexts/ paths in load_context ([8101320](https://github.com/event4u-app/agent-config/commit/8101320c9a014e02bddfa60fb433b09bd3646b0a))
+* **linter:** support validator_ignore frontmatter + dual-location contracts ([031bd7d](https://github.com/event4u-app/agent-config/commit/031bd7df79deb35a53b8f1d49384056cfcea7711))
+* **templates:** compressed mirror of templates/rule.md + placeholder fix for check-refs ([c182723](https://github.com/event4u-app/agent-config/commit/c18272386d1c5f31efdd14f6d2cca8b8d8b876c8))
+* **skills:** portability — script paths in rule-writing, lower-case agent-config in copilot-agents-optimization ([7e5a86f](https://github.com/event4u-app/agent-config/commit/7e5a86f5dda9a095e3d887c19df718555f7f347c))
+* **tests:** align load_context tests with logical-name path format ([924e52e](https://github.com/event4u-app/agent-config/commit/924e52ed4005d2fb8d22167899058ed9eeb61449))
+* **commit-mechanics:** trim four-exceptions block to fit 6k extended-size cap ([0b6391f](https://github.com/event4u-app/agent-config/commit/0b6391f08d23af71f8945a7e685c7a979e229d61))
+* **contexts:** restore obligation-keyword baseline after P2.2 rule compression ([8996bcd](https://github.com/event4u-app/agent-config/commit/8996bcd83621670f175f93d73ee1c577695d3b34))
+* **linear-digest:** update language-and-tone strip-section title after P2.2 rename ([9643a82](https://github.com/event4u-app/agent-config/commit/9643a82c15a9904ceefcc6a9f1b90a4ef2225b47))
+
+### Documentation
+
+* **roadmap:** add road-to-structural-linter-reform (council Option 3) ([ac62e56](https://github.com/event4u-app/agent-config/commit/ac62e563f17f697401c8d9045847b3c12ec1c927))
+* update package docs for kernel + router model ([8fef804](https://github.com/event4u-app/agent-config/commit/8fef804aa00ce578ee2b1a96c7002081f07bc538))
+* **kernel:** land Phase 1 classification + kernel set + Council R2 amendments ([a179487](https://github.com/event4u-app/agent-config/commit/a179487dd6fef2b548cd1b886a1e7d54a4c00a39))
+
+### Refactoring
+
+* compression logic ([6701f9f](https://github.com/event4u-app/agent-config/commit/6701f9f12568ddc409ccad62a7690d64ba885122))
+* **chat-history:** import emits summary + resume offer instead of verbatim entries ([dfafd9c](https://github.com/event4u-app/agent-config/commit/dfafd9cd62d740a7137f6a6e648acfb377f46b1b))
+* **kernel:** compress 8 kernel rules per P2.2 playbook + lock kernel (P2.3) ([4e771da](https://github.com/event4u-app/agent-config/commit/4e771da5c4ceea2e6d2e8935098f1cd231c80c30))
+
+### Chores
+
+* **router:** add routes_to to no-council-references rule ([fb50540](https://github.com/event4u-app/agent-config/commit/fb505404c9b03cb9fa597ac36793eb3f552585f7))
+* **roadmaps:** archive completed agent-memory roadmaps ([a35b680](https://github.com/event4u-app/agent-config/commit/a35b6803ff545ce2e9098a55cfa8ecb1fbcf624d))
+* **ownership:** regenerate matrix after road-to-structural-linter-reform ([174dd24](https://github.com/event4u-app/agent-config/commit/174dd24989f112eab89c628807acbbb0e10b6aae))
+* **ci:** regenerate index, catalog, roadmap complexity fix ([d61dc9c](https://github.com/event4u-app/agent-config/commit/d61dc9ce96f2ccdab8efd11281bf00d80ed755ef))
+* **docs:** bump getting-started command count from 94 to 95 ([6751897](https://github.com/event4u-app/agent-config/commit/6751897cdf2744683731fc9230183a38834e9b9c))
+* **sync:** regenerate agents/index.md + docs/catalog.md after prompt-optimizer ([cfe2367](https://github.com/event4u-app/agent-config/commit/cfe236759671792a9b49ff10f664fbed10edc4c4))
+* **readme:** bump command count from 94 to 95 after prompt-optimizer addition ([62a59a4](https://github.com/event4u-app/agent-config/commit/62a59a427986ff428d1c1e729d311914ce3be0e5))
+* **sync:** regenerate .windsurfrules after caveman arrow update ([509ba00](https://github.com/event4u-app/agent-config/commit/509ba0061500a47129c77da5bae1f8384636a09c))
+* **compression:** apply caveman abbreviation and arrow rules to mirror ([34e5b1f](https://github.com/event4u-app/agent-config/commit/34e5b1f85da99de94ea8b5f932011583c844a0c8))
+* **sync:** regenerate compressed mirror + ownership matrix after Phase 5-7 ([b421e8e](https://github.com/event4u-app/agent-config/commit/b421e8e3aae6c1ee739bbdd35ed4f44cd78eed85))
+* **roadmap:** archive road-to-path-fixes after Phase 7 closure ([651fd3e](https://github.com/event4u-app/agent-config/commit/651fd3e6586e552dab6368be1853141b2b2fb0ff))
+* **portability:** replace 'Galawork'/'galawork' with 'Consumer'/'consumer' ([bac0433](https://github.com/event4u-app/agent-config/commit/bac0433c13e007910564e6b21b82ca6e6dcccdf9))
+* regenerate router, index, catalog, windsurf rules, tool symlinks ([93685bb](https://github.com/event4u-app/agent-config/commit/93685bb0fbe7c9f671f3a49672e693a8e4a44b85))
+* **commands:** sync compressed mirror of chat-history/import.md to summary+resume ([0063941](https://github.com/event4u-app/agent-config/commit/0063941c69d011a8935ddbcc7ea1266cd4d2c692))
+* **roadmaps:** add road-to-path-fixes and refresh progress ([34f9c23](https://github.com/event4u-app/agent-config/commit/34f9c23ccf67f79758e7dd293c66bc4c443ccc29))
+* **roadmaps:** close kernel-router, package-opt, token-opt plates ([445ef25](https://github.com/event4u-app/agent-config/commit/445ef2574772358ca278ce2d334a08431e82ed68))
+* **roadmap:** close Phase 3 (Router contract) in kernel-and-router ([30b834f](https://github.com/event4u-app/agent-config/commit/30b834fceb9c1198ffae5f0d35d1c84e5bd44c24))
+* **ownership:** regenerate file-ownership matrix after P2.2 kernel compression ([0e82da1](https://github.com/event4u-app/agent-config/commit/0e82da18399cd1e9ecff57769116d7a3317c2949))
+
 ## [1.20.0](https://github.com/event4u-app/agent-config/compare/1.19.0...1.20.0) (2026-05-06)
 
 ### Features
@@ -1298,7 +1364,7 @@ our recommendation order, not its support status.
 
 * add iron rule for skill independence ([b060730](https://github.com/event4u-app/agent-config/commit/b060730e98b15b6bc498ad68a111035fab72907f))
 * address Copilot PR review feedback ([11b4d20](https://github.com/event4u-app/agent-config/commit/11b4d2060084d1739bfc9e6550fc78c4a4a0bcb7))
-* address galawork-api PR [#1466](https://github.com/event4u-app/agent-config/issues/1466) bot feedback ([c5f8e18](https://github.com/event4u-app/agent-config/commit/c5f8e18a6c429e2f8f0224e1d9130233107ce65e))
+* address consumer-api PR [#1466](https://github.com/event4u-app/agent-config/issues/1466) bot feedback ([c5f8e18](https://github.com/event4u-app/agent-config/commit/c5f8e18a6c429e2f8f0224e1d9130233107ce65e))
 * **check-refs:** resolve .augment/X as alias for .agent-src/X ([ff3b094](https://github.com/event4u-app/agent-config/commit/ff3b09479a7fa266606467d862f8de9277ef1fc4))
 * **check-refs:** skip forward refs in unchecked TODO items ([1458a18](https://github.com/event4u-app/agent-config/commit/1458a181eb5bbe3189777b87bd9ad210b8cc00c5))
 * **check-refs:** validate paths inside memory YAML + exempt consumer dirs ([ec4e8aa](https://github.com/event4u-app/agent-config/commit/ec4e8aae2a0f8e7c489442441b8cfa7f9242be2f))
@@ -1474,8 +1540,8 @@ our recommendation order, not its support status.
   for scope questions; Issues remain for bugs and feature requests.
 
 ### Removed
-- Hardcoded `galawork` references removed from installer and portability
-  checker. No public release ever shipped the legacy `# galawork/agent-config`
+- Hardcoded `consumer` references removed from installer and portability
+  checker. No public release ever shipped the legacy `# consumer/agent-config`
   gitignore marker, so the in-place migration path was also removed.
 
 ## [1.3.3] — 2026-04-17

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>134 Skills</strong> · <strong>56 Rules</strong> · <strong>94 Commands</strong> · <strong>51 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>136 Skills</strong> · <strong>58 Rules</strong> · <strong>95 Commands</strong> · <strong>56 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -55,15 +55,11 @@ bash vendor/event4u/agent-config/scripts/install
 bash node_modules/@event4u/agent-config/scripts/install --profile=balanced
 ```
 
-**To install the package:** no Task, no Make, no build tools required.
-`scripts/install` orchestrates two stages: a bash payload sync and a
-Python bridge generator. **Python 3** (stdlib only, pre-installed on
-macOS 12.3+ and all major Linux distros) is required for the bridge
-stage; without it the orchestrator warns, runs the payload sync, and
-continues. The package makes rules, skills, and commands available
-project-locally for all supported AI tools. Task is required for
-*contributors* who want to rebuild the compressed content locally — see
-[CONTRIBUTING.md](CONTRIBUTING.md).
+**To install:** no Task / Make / build tools — `scripts/install` runs a
+bash payload sync plus a Python 3 bridge generator (stdlib only, default
+on macOS 12.3+ / major Linux distros). Python missing → orchestrator
+warns and continues payload-only. Task is needed only for *contributors*
+rebuilding compressed content — see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 **Verify hook coverage** after installing — every supported platform
 (Augment, Claude Code, Cowork, Cursor, Cline, Windsurf, Gemini CLI,
@@ -270,15 +266,20 @@ session is explicitly not.
 
 ## You don't need everything
 
-Start with **Rules + Skills**. Everything else is optional.
+`cost_profile` is the master switch for **rule-tier loading**. The kernel
+(always-loaded Iron-Law floor, ≤ 26k chars across 9 rules) ships in every
+profile; tier-1 and tier-2 rules are gated by profile and resolved at
+session start from `router.json`.
 
-| Mode | What's active | Runtime process overhead |
-|---|---|---|
-| **Minimal** (default) | Rules, Skills, Commands | None |
-| **Balanced** | + Runtime Dispatcher for skills that declare a shell command | Low |
-| **Full** | + Tool Adapters (GitHub / Jira read-only, opt-in) | Moderate |
+| Profile | Rule tiers loaded | Token footprint | Best for |
+|---|---|---|---|
+| **`minimal`** | kernel only (no router, no auto-rules) | lowest | Cost-sensitive sessions; trivial Q&A; CI runs |
+| **`balanced`** (default) | kernel + tier-1 auto-rules | medium | Day-to-day work — current behaviour superset |
+| **`full`** | kernel + tier-1 + tier-2 (everything) | highest | Agent-config development; full rule fidelity |
 
-Nothing runs automatically without your control. [Configure modes →](docs/customization.md)
+Architecture: [`docs/contracts/rule-router.md`](docs/contracts/rule-router.md) (beta) ·
+kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-membership.md) (beta) ·
+[Configure profiles →](docs/customization.md)
 
 > **Stability tiers** — [`STABILITY.md`](docs/contracts/STABILITY.md) for
 > the full matrix. Runtime Dispatcher: **stable** (`php` / `node` handlers
@@ -342,7 +343,7 @@ Nothing runs automatically without your control. [Configure modes →](docs/cust
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 94 active commands](.agent-src/commands/)
+→ [Browse all 95 active commands](.agent-src/commands/)
 
 ---
 
@@ -367,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 + 134 skills + 94 native commands). Cursor, Cline, Windsurf,
+> package (rules + 136 skills + 95 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.
@@ -449,7 +450,7 @@ telemetry:
 
 Reports: `./agent-config telemetry:report`. Full contract,
 privacy/redaction floor, and quartile semantics:
-[`docs/contracts/artifact-engagement-flow.md`](docs/contracts/artifact-engagement-flow.md) (beta).
+[`contexts/contracts/artifact-engagement-flow.md`](.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md) (beta).
 
 ### Context-aware command suggestion
 
@@ -470,7 +471,7 @@ commands:
 Per-conversation: `/command-suggestion-off` disables the layer until
 re-enabled or the chat ends. Full scoring contract and hardening:
 [`adr-command-suggestion`](docs/contracts/adr-command-suggestion.md),
-[`command-suggestion-flow`](docs/contracts/command-suggestion-flow.md) (beta).
+[`command-suggestion-flow`](.agent-src.uncompressed/contexts/contracts/command-suggestion-flow.md) (beta).
 
 ---
 

package/config/agent-settings.template.yml

@@ -7,13 +7,15 @@
 
 # --- Cost profile ---
 #
-# Selects which agent surfaces are active. See docs/customization.md for
-# the authoritative description.
+# Master switch that controls which rule tiers load each session.
+# See docs/customization.md for the authoritative description and
+# docs/contracts/rule-router.md for the kernel + router architecture.
 #
-# minimal  = rules, skills, and commands only (zero extra surface, default)
-# balanced = + runtime dispatcher for skills that declare a shell command
-# full     = + tool adapters (GitHub / Jira, read-only, opt-in)
-# custom   = ignore profile — every matrix value must be set explicitly
+# minimal  = kernel only (always-loaded Iron-Law floor, ≤ 26k chars).
+#            No router, no auto-rules. Lowest token footprint.
+# balanced = kernel + tier-1 auto-rules (default — current behaviour superset).
+# full     = kernel + tier-1 + tier-2 (everything, highest token cost).
+# custom   = ignore profile — every matrix value must be set explicitly.
 cost_profile: __COST_PROFILE__
 
 # --- Personal preferences ---
@@ -74,6 +76,22 @@ github:
   # auto                  = detect on first use and update this setting
   pr_reply_method: create_review_comment
 
+# --- Augment Code projection (.augment/) ---
+#
+# Controls how rule files are written into .augment/rules/ during
+# install (scripts/install.sh) and the package's own projection
+# (scripts/compress.py --project-augment).
+#
+# Augment Code historically does not load symlinked rule files, so the
+# default is to write each rule as a real copy. Flip the toggle to true
+# once Augment Code supports symlinked rules — symlinks keep the files
+# in sync without re-running install/sync, and remove a class of stale-
+# copy path bugs.
+augment:
+  # When true, .augment/rules/*.md are symlinked into .agent-src/rules/.
+  # When false (default) or missing, they are copied as real files.
+  rules_use_symlinks: false
+
 # --- Eloquent (Laravel) ---
 eloquent:
   # Model property access style
@@ -205,10 +223,25 @@ ai_council:
       model: "gpt-4o"
       # mode: "manual"   # uncomment to override ai_council.mode
 
+  # Default number of debate rounds per /council invocation.
+  #
+  # Round 1 sees the artefact alone. Round 2+ sees the artefact plus
+  # anonymised critiques from the previous round (provider/model
+  # identity stripped per the neutrality Iron Law). Applies identically
+  # to api and manual transports — manual mode runs round 1 across all
+  # members, the host agent consolidates, then round 2 starts with the
+  # anonymised round-1 critiques folded in.
+  #
+  # Default is 2 so council members critique each other at least once
+  # before convergence. The agent does NOT ask "how many rounds?" when
+  # the requested rounds <= min_rounds; pass `rounds:N` on the
+  # invocation (or `--rounds N` to the CLI) to override.
+  min_rounds: 2
+
   # Hard cost ceiling per /council invocation. The orchestrator pauses
   # before any member whose projected spend would breach a cap and asks
   # the user to continue. `max_total_usd: 0` disables the USD ceiling
-  # (token caps still apply).
+  # (token caps still apply). Total spend = rounds * single-round cost.
   #
   # Prices come from `agents/.agent-prices.md` (gitignored, refreshed weekly
   # by `python3 scripts/update_prices.py`; bootstrapped from
@@ -219,10 +252,11 @@ ai_council:
     max_calls: 10
     max_total_usd: 0.50
 
-  # Retention for `agents/council-sessions/` audit folders. Sessions
-  # older than this are pruned automatically on the next `save()`.
+  # Retention for council artefacts. Files older than this in
+  # `agents/council-{questions,responses,sessions}/` are pruned
+  # automatically on the next `save()` and on `task council-prune`.
   # `0` disables pruning (keep forever — disk grows unbounded).
-  session_retention_days: 14
+  session_retention_days: 7
 
 # --- Onboarding ---
 #

package/config/gitignore-block.txt

@@ -29,3 +29,10 @@
 
 # Agent config — AI Council price table (refreshed weekly, never commit)
 /agents/.agent-prices.md
+
+# Agent config — AI Council artefacts (questions, responses, sessions).
+# Dev-time scratch — informs decisions, never the durable contract.
+# See ai-council § Output path convention.
+/agents/council-questions/
+/agents/council-responses/
+/agents/council-sessions/

package/docs/architecture.md

@@ -27,7 +27,8 @@ Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 .agent-src.uncompressed/          ← Source of truth (verbose, human-readable)
     ↓ /compress command
 .agent-src/                     ← Compressed output (token-efficient, shipped in the package)
-    ↓ project_to_augment() — copies rules, symlinks rest
+    ↓ project_to_augment() — copies rules by default, symlinks rest
+                              (toggle: augment.rules_use_symlinks)
 .augment/                       ← Local projection for Augment Code (gitignored)
     ↓ install.sh (Cursor, Cline, Windsurf, Augment VSCode) / plugin system
 .claude/ .cursor/ .clinerules/  ← Tool-specific symlinks/copies (auto-generated)
@@ -36,6 +37,39 @@ Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 dist/cloud/<skill>.zip          ← Anthropic Skills bundles (Claude.ai Web / Skills API)
 ```
 
+### Installer layout
+
+In a consumer project, the installer (`scripts/install.sh`) and the
+package's own `project_to_augment()` projection produce a `.augment/`
+tree where:
+
+- `.augment/rules/` — **copies** of compressed rule files by default.
+  Augment Code historically does not load symlinked rules, so each
+  rule is a real file. Set `augment.rules_use_symlinks: true` in
+  `.agent-settings.yml` to switch them to symlinks once Augment Code
+  supports it (the toggle is honored by both `scripts/install.sh` on
+  the consumer side and `project_to_augment()` in the package).
+- `.augment/skills/`, `.augment/commands/`, `.augment/personas/`,
+  `.augment/contexts/`, `.augment/templates/` — **symlinks** into
+  `.agent-src/<subdir>/`. Reading a context follows the symlink to
+  the package payload.
+- `.augment/docs/guidelines/` — **symlink** into the package's
+  `docs/guidelines/` (consumer side: `vendor/event4u/agent-config/docs/guidelines/`;
+  package self-projection: `../docs/guidelines/`). This is the only
+  `docs/` subdirectory exposed in `.augment/`; `docs/contracts/` and
+  `docs/decisions/` are package-internal — rules that reference
+  contracts inline a 2–3 line excerpt instead of linking out.
+
+Cross-references inside `.agent-src/rules/*.md` are written
+**relative to `.agent-src/rules/`** (e.g. `../contexts/execution/foo.md`,
+`../docs/guidelines/agent-infra/foo.md`). Source files under
+`.agent-src.uncompressed/rules/` use **logical names** without a
+directory prefix (e.g. `contexts/execution/foo.md`); the
+compress-time path rewriter in `scripts/compress.py` translates
+them to the relative form when writing into `.agent-src/`. Hardcoding
+`.agent-src.uncompressed/` in source frontmatter or body links is
+forbidden and caught by `scripts/check_compressed_paths.py`.
+
 ### Cloud-bundle pipeline
 
 `task build-cloud-bundles-all` produces one ZIP per skill at
@@ -62,10 +96,10 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 134 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
-| **Rules** | 56 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 94 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 51 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Skills** | 136 | 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** | 95 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Guidelines** | 56 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 
@@ -215,4 +249,51 @@ adjustments (description budget, sandbox note, package-internal path-swap).
 
 ---
 
+## Path resolution and Copilot integration
+
+Cross-references inside `.augment/rules/`, `.augment/skills/`, and the
+mirrored `.claude/`, `.cursor/`, `.clinerules/` trees use **relative
+paths from the delivered location**. They resolve through the symlinks
+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:
+
+| 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) |
+
+Both are installed (copy-if-missing) by `scripts/install.sh` from
+`.agent-src.uncompressed/templates/`. Consumers can edit them freely;
+the installer never overwrites.
+
+The mechanical floor is `scripts/check_compressed_paths.py`, wired into
+`task ci` as `check-compressed-paths`. It validates `.agent-src/rules/*.md`:
+
+- `load_context:` entries must resolve to existing files.
+- Forbidden substrings (`.agent-src.uncompressed/`, `../../docs/`,
+  `../../agents/`) must not survive compression — unless declared
+  per-rule via the `validator_ignore:` frontmatter primitive (audited).
+- Body links to `../docs/guidelines/...` are intentionally **not**
+  checked (they are package-internal reference material, silenced by
+  the Copilot suppression floor above).
+
+### Verifying path fixes in a consumer
+
+If a regression is suspected, replay the smoke test against the
+package's own `.augment/` projection:
+
+```bash
+task sync                              # regenerate .agent-src/ → .augment/
+python3 scripts/smoke_path_resolution.py
+```
+
+The script walks `.augment/rules/*.md` and resolves every
+`load_context:` entry to a file under `.augment/`. A non-zero exit
+means a consumer would also see the same broken reference.
+
+---
+
 ← [Back to README](../README.md)

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **332 public artefacts** shipped by
+Consumer-facing catalog of all **342 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `python3 scripts/generate_index.py`
 > Auto-generated — do not edit manually.
 
-## Skills (134)
+## Skills (136)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -106,6 +106,7 @@ are excluded.
 | skill | [`project-analysis-zend-laminas`](../.agent-src/skills/project-analysis-zend-laminas/SKILL.md) |  | Use for deep Zend Framework or Laminas project analysis: bootstrap, config merge order, service manager, MVC flow, data layer, and migration-specific risks. |
 | skill | [`project-analyzer`](../.agent-src/skills/project-analyzer/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work. |
 | skill | [`project-docs`](../.agent-src/skills/project-docs/SKILL.md) |  | Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs. |
+| skill | [`prompt-optimizer`](../.agent-src/skills/prompt-optimizer/SKILL.md) |  | Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'. |
 | skill | [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) |  | Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned. |
 | skill | [`react-shadcn-ui`](../.agent-src/skills/react-shadcn-ui/SKILL.md) |  | Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack. |
 | skill | [`readme-reviewer`](../.agent-src/skills/readme-reviewer/SKILL.md) |  | Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues. |
@@ -137,6 +138,7 @@ are excluded.
 | skill | [`test-driven-development`](../.agent-src/skills/test-driven-development/SKILL.md) |  | Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'. |
 | skill | [`test-performance`](../.agent-src/skills/test-performance/SKILL.md) |  | Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives. |
 | skill | [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) |  | Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation. |
+| skill | [`token-optimizer`](../.agent-src/skills/token-optimizer/SKILL.md) |  | Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action. |
 | skill | [`traefik`](../.agent-src/skills/traefik/SKILL.md) |  | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
 | skill | [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) |  | Use when modeling CAC, LTV, gross-margin payback, or contribution margin per customer — for SaaS, marketplace, or transactional businesses. |
 | skill | [`universal-project-analysis`](../.agent-src/skills/universal-project-analysis/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills. |
@@ -146,7 +148,7 @@ are excluded.
 | skill | [`verify-completion-evidence`](../.agent-src/skills/verify-completion-evidence/SKILL.md) |  | Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (53)
+## Rules (55)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -178,6 +180,7 @@ are excluded.
 | rule | [`model-recommendation`](../.agent-src/rules/model-recommendation.md) | auto | Starting a new task, switching task type, or invoking a command — detect task complexity and recommend the optimal model (Opus/Sonnet/GPT) before any work |
 | rule | [`no-attribution-footers`](../.agent-src/rules/no-attribution-footers.md) | auto | Generating PR/issue/comment/commit-message bodies — forbids unsolicited 'Generated with', 'Co-authored by', or 'Pull Request opened by' attribution footers in any user-owned artifact |
 | rule | [`no-cheap-questions`](../.agent-src/rules/no-cheap-questions.md) | always | No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on) |
+| rule | [`no-council-references`](../.agent-src/rules/no-council-references.md) | auto | Linking a specific file in agents/council-{questions,responses,sessions}/ from any artifact — council files are gitignored, local-only, auto-pruned; inline the convergence instead |
 | rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | 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 |
 | rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass |
 | rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | 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 |
@@ -198,13 +201,14 @@ are excluded.
 | rule | [`slash-command-routing-policy`](../.agent-src/rules/slash-command-routing-policy.md) | auto | When user types a slash command like /create-pr, /commit, or pastes command file content |
 | rule | [`think-before-action`](../.agent-src/rules/think-before-action.md) | auto | Before coding, modifying, or debugging — analyze first, verify with real tools, never guess or trial-and-error |
 | rule | [`token-efficiency`](../.agent-src/rules/token-efficiency.md) | auto | When running CLI tools, fetching logs, or producing replies — redirect verbose output, minimize tool calls, keep replies concise |
+| rule | [`token-optimizer-maintenance`](../.agent-src/rules/token-optimizer-maintenance.md) | auto | 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. |
 | rule | [`tool-safety`](../.agent-src/rules/tool-safety.md) | auto | When a skill uses external tools — enforce allowlist, deny-by-default, and no hidden credential patterns |
 | rule | [`ui-audit-gate`](../.agent-src/rules/ui-audit-gate.md) | auto | 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 |
 | rule | [`upstream-proposal`](../.agent-src/rules/upstream-proposal.md) | auto | After creating or significantly improving a skill, rule, guideline, or command — ask if it should be contributed upstream to the shared package |
 | rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (94)
+## Commands (95)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -217,7 +221,7 @@ are excluded.
 | command | [`analyze-reference-repo`](../.agent-src/commands/analyze-reference-repo.md) |  | Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project. |
 | command | [`bug-fix`](../.agent-src/commands/bug-fix.md) |  | Plan and implement a bug fix — based on investigation, with quality checks and test verification |
 | command | [`bug-investigate`](../.agent-src/commands/bug-investigate.md) |  | Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause |
-| command | [`chat-history:import`](../.agent-src/commands/chat-history/import.md) | cluster: chat-history | Surface prior chat-history sessions as numbered options, let the user pick exactly one, then render its entries verbatim into the current chat — selective, user-driven cross-session import |
+| command | [`chat-history:import`](../.agent-src/commands/chat-history/import.md) | cluster: chat-history | Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit a short summary plus a resume offer — selective, user-driven cross-session import |
 | command | [`chat-history:learn`](../.agent-src/commands/chat-history/learn.md) | cluster: chat-history | Pick a prior chat-history session and mine it for project-improving learnings — runs learning-to-rule-or-skill on the picked session, drafts proposal(s) under agents/proposals/ |
 | command | [`chat-history:show`](../.agent-src/commands/chat-history/show.md) | cluster: chat-history | Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and the last few entries |
 | command | [`chat-history`](../.agent-src/commands/chat-history.md) | cluster: chat-history | Chat-history orchestrator — routes to show, import, learn |
@@ -275,6 +279,7 @@ are excluded.
 | command | [`optimize:augmentignore`](../.agent-src/commands/optimize/augmentignore.md) | cluster: optimize | Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifacts, and irrelevant agent skills/rules. |
 | command | [`optimize:rtk`](../.agent-src/commands/optimize/rtk.md) | cluster: optimize | Create or optimize project-local rtk filters based on the actual toolchain |
 | command | [`optimize:skills`](../.agent-src/commands/optimize/skills.md) | cluster: optimize | Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto-apply. |
+| command | [`optimize-prompt`](../.agent-src/commands/optimize-prompt.md) | cluster: optimize | Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL auto-detect, one clarifying question per turn, returns the polished prompt. |
 | command | [`optimize`](../.agent-src/commands/optimize.md) | cluster: optimize | Optimize orchestrator — routes to skills, agents, augmentignore, rtk-filters |
 | command | [`override:create`](../.agent-src/commands/override/create.md) | cluster: override | Creates a project-level override for a shared skill, rule, or command. |
 | command | [`override:manage`](../.agent-src/commands/override/manage.md) | cluster: override | Reviews, updates, and refactors existing project-level overrides. |
@@ -303,7 +308,7 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (51)
+## Guidelines (56)
 
 | kind | name | category | description |
 |---|---|---|---|
@@ -320,13 +325,17 @@ are excluded.
 | guideline | [`naming`](../docs/guidelines/agent-infra/naming.md) | agent-infra |  |
 | guideline | [`output-patterns`](../docs/guidelines/agent-infra/output-patterns.md) | agent-infra |  |
 | guideline | [`review-routing-data-format`](../docs/guidelines/agent-infra/review-routing-data-format.md) | agent-infra |  |
+| guideline | [`roadmap-progress-mechanics`](../docs/guidelines/agent-infra/roadmap-progress-mechanics.md) | agent-infra |  |
 | guideline | [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md) | agent-infra |  |
 | guideline | [`role-mode-router`](../docs/guidelines/agent-infra/role-mode-router.md) | agent-infra |  |
+| guideline | [`rule-type-governance`](../docs/guidelines/agent-infra/rule-type-governance.md) | agent-infra |  |
 | guideline | [`runtime-layer`](../docs/guidelines/agent-infra/runtime-layer.md) | agent-infra |  |
 | guideline | [`self-improvement-pipeline`](../docs/guidelines/agent-infra/self-improvement-pipeline.md) | agent-infra |  |
 | guideline | [`size-and-scope`](../docs/guidelines/agent-infra/size-and-scope.md) | agent-infra |  |
+| guideline | [`skill-quality-checklist`](../docs/guidelines/agent-infra/skill-quality-checklist.md) | agent-infra |  |
 | guideline | [`tool-integration`](../docs/guidelines/agent-infra/tool-integration.md) | agent-infra |  |
 | guideline | [`verify-before-complete-demos`](../docs/guidelines/agent-infra/verify-before-complete-demos.md) | agent-infra |  |
+| guideline | [`augment-portability-patterns`](../docs/guidelines/augment-portability-patterns.md) | (root) |  |
 | guideline | [`readme-size-and-splitting`](../docs/guidelines/docs/readme-size-and-splitting.md) | docs |  |
 | guideline | [`playwright`](../docs/guidelines/e2e/playwright.md) | e2e |  |
 | guideline | [`api-design`](../docs/guidelines/php/api-design.md) | php |  |
@@ -353,6 +362,7 @@ are excluded.
 | guideline | [`strategy`](../docs/guidelines/php/patterns/strategy.md) | patterns |  |
 | guideline | [`patterns`](../docs/guidelines/php/patterns.md) | php |  |
 | guideline | [`performance`](../docs/guidelines/php/performance.md) | php |  |
+| guideline | [`php-coding-patterns`](../docs/guidelines/php/php-coding-patterns.md) | php |  |
 | guideline | [`resources`](../docs/guidelines/php/resources.md) | php |  |
 | guideline | [`security`](../docs/guidelines/php/security.md) | php |  |
 | guideline | [`sql`](../docs/guidelines/php/sql.md) | php |  |

package/docs/contracts/agent-memory-contract.md

@@ -13,7 +13,7 @@ helpers.
 **Ownership.** `agent-memory` is ours; we decide release timing. This
 doc is internal, not a spec handed to an external team. The
 authoritative spec-side documents live under
-[`agents/roadmaps/agent-memory/`](../../agents/roadmaps/agent-memory/); this context
+[`agents/roadmaps/agent-memory/`](../../agents/roadmaps/archive/agent-memory/); this context
 is the **consumer-side snapshot** — what our wired code assumes today.
 
 Last refreshed: 2026-04-22.

package/docs/contracts/context-paths.md

@@ -34,6 +34,7 @@ a roadmap revision (per `road-to-structural-optimization.md` § Definitions).
 | `contexts/chat-history/` | Phase 6 | `cadence.md`, `ownership.md`, `visibility.md` |
 | `contexts/execution/` | PR #34 (existing) | `<topic>-mechanics.md`, `<topic>-detection.md`, `<topic>-examples.md` |
 | `contexts/authority/` | PR #34 (existing) | `<topic>-mechanics.md` |
+| `contexts/contracts/` | road-to-path-fixes Phase 4 | `<topic>-flow.md` (load-bearing flow contracts cited via `load_context:`) |
 
 ## Grandfathered files
 
@@ -54,7 +55,7 @@ contexts/subagent-configuration.md
 
 1. **Sub-tree allow-list.** Every `*.md` under
    `.agent-src.uncompressed/contexts/` must be either (a) in one of the
-   eight locked sub-trees above, or (b) one of the six grandfathered
+   nine locked sub-trees above, or (b) one of the six grandfathered
    root-level files. Anything else fails CI.
 2. **No collisions.** No two context files may share the same basename
    across sub-trees. `judges/persona-voice-rubric.md` and