@event4u/agent-config 2.20.0 → 2.21.0

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

@@ -57,6 +57,22 @@ Extract from latest record:
 Pricing source: [`bench/pricing.yaml`](../../bench/pricing.yaml). Reader
 implementation: [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs).
 
+### 3b. Read caveman delta + per-conversation cost lens
+
+Run two read-only Python helpers (stdlib-only, no-op safe if JSONL missing):
+
+- `python3 scripts/caveman_stats.py --format json` — per-session +
+  per-conversation + lifetime caveman delta. Honors suspended
+  multiplier (see [`docs/contracts/caveman-telemetry.md`](../docs/contracts/caveman-telemetry.md)) — delta reads `0` while suspended; display version + ACTIVE/SUSPENDED state regardless.
+- `python3 scripts/cost_by_conversation.py --format json` — per-conversation
+  total cost + model breakdown for current conversation, sourced
+  from same `agents/cost-tracking/sessions.jsonl` ledger.
+
+Surface in dashboard as one line:
+`[caveman: {lifetime.delta_tokens:+,} tok lifetime · {current_conv.delta_tokens:+,} this conv · multiplier v{multiplier_version} {ACTIVE|SUSPENDED}] · [conv cost: ${current_conv.total_cost_usd:.4f}]`.
+
+If both JSONLs missing or empty, omit line silently.
+
 ### 4. Calculate freshness thresholds
 
 - **Message threshold**: Next multiple of 25 ≥ current count

package/.agent-src/rules/caveman-speak.md

@@ -56,6 +56,8 @@ Post-rewrite validator runs on every reply when `speak_scope != off`:
 The rule documents the algorithm; agents apply it inline before
 sending. The mechanism is the rule, not a hidden script.
 
+Optional CI-side regression lock: [`scripts/validate_caveman_carveouts.py`](../../scripts/validate_caveman_carveouts.py) takes pre/post reply pair and asserts byte-identical preservation across all seven carve-out categories — runtime mechanism stays algorithmic; script is offline check.
+
 ## Caveman grammar
 
 - Drop articles (`the`, `a`, `an`).

package/.agent-src/skills/compress-memory/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: compress-memory
+description: "Use when shrinking always-loaded memory files (AGENTS.md, CLAUDE.md, .cursorrules) via caveman grammar — refuses sensitive paths, round-trips via .original.md backup."
+source: package
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: [Bash]
+---
+
+# compress-memory
+
+> **Experimental.** Output-side caveman dialect did not meet kill-criterion in [`bench/reports/caveman-v1.md`](../../../bench/reports/caveman-v1.md) (`vs_terse` median −9.27 %). Input-side memory compression is orthogonal use case: savings target always-loaded memory budget, not reply stream. Treat ship-criterion as **per-target measurement**, not v1 verdict.
+
+## When to use
+
+Use when:
+
+- Always-loaded memory file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`) close to or above host tool's char budget and maintainer wants to recover input-token headroom.
+- Consumer-shipped `templates/AGENTS.md` failing `agents-md-thin-root` cap and pointer-extraction options exhausted.
+- Maintainer asks to "compress this memory file" or "shrink AGENTS.md" or names input-side caveman.
+
+## Do NOT
+
+- Compress reply, commit message, PR body, ticket summary, or any deliverable written *for* human reader — those are carve-outs in [`caveman-speak § Carve-outs`](../../rules/caveman-speak.md) and stay verbatim.
+- Compress path matching sensitive-file denylist (`.env*`, `.netrc`, `credentials*`, `secrets*`, `id_rsa*`, `*.pem|key|p12|pfx|crt|cer|jks`, `.ssh/*`) — script refuses with `SensitivePathError` and so should you.
+- Compress generated file (`.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`) — edit source in `.agent-src.uncompressed/` and regenerate via package's sync + generate-tools scripts (`scripts/compress.sh --sync` + `scripts/compress.py --generate-tools`).
+- Hand-edit compressed memory file in place — run `--decompress` first; next compress pass refuses on body-hash drift (`CompressionRefused`).
+- Commit compressed file without committing matching `.original.md` backup — round-trip breaks otherwise.
+
+## Procedure
+
+1. **Analyse target first.** Before any write, **inspect** target with `view` or `wc -l` to confirm it is always-loaded memory file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`), not generated, and has prose paragraphs to compress (pointer-only Thin-Root file may net near-zero). Skip rest of procedure if any check fails.
+2. **Check denylist gate.** Run `python3 scripts/compress_memory.py <path> --check` — exit 0 = safe; exit 2 = denylist hit, stop and surface refusal.
+3. **Record baseline.** `wc -c <path>` — capture pre-compression char count for commit message.
+4. **Compress.** `python3 scripts/compress_memory.py <path>`. Script writes `<path>.original.md` (verbatim backup) and rewrites `<path>` with `original_sha256:` + `compressed_at:` frontmatter.
+5. **Inspect diff.** Eyeball every Iron-Law fence, numbered-options block, code fence, backtick span, `❌`/`⚠️`/`✅` line, and frontmatter pair — all must be byte-identical. Body prose may have lost articles (`the`/`a`/`an`) and auxiliaries (`is`/`are`/`was`/`be`/`that`/`which`).
+6. **Validate idempotency.** Re-run `python3 scripts/compress_memory.py <path>` — clean re-run is no-op (body hash matches). Non-zero exit = stop, escalate.
+7. **Commit both files together.** `<path>` and `<path>.original.md` ship as pair. Backup is rollback path; never commit one without other.
+8. **Rollback path.** If readability fails review at step 5: `python3 scripts/compress_memory.py <path> --decompress` restores backup and deletes `.original.md`.
+
+## Output format
+
+Maintainer-facing report after invoking script MUST contain, in this order:
+
+1. **Diff line** — pre/post `wc -c` as single line (`AGENTS.md: 2,891 → 2,453 chars (−15.1 %)`).
+2. **Backup path** — full path of `.original.md` backup so maintainer can verify it landed on disk.
+3. **Carve-out check** — one line confirming seven carve-out classes round-tripped (`carve-outs: 7 classes preserved · idempotent re-run: clean`).
+4. **Exit-code surface** — on failure, surface verbatim exit code and exception name (`SensitivePathError → exit 2`, `CompressionRefused → exit 3`, `FileNotFoundError → exit 4`); do not paraphrase.
+
+Do **not** narrate algorithm, grammar rules, or carve-out theory — rule and this skill document contract; output reports result.
+
+## Carve-outs — byte-for-byte preserved
+
+Mirrors seven carve-out classes in [`caveman-speak`](../../rules/caveman-speak.md). Compression engine in [`scripts/compress_memory.py`](../../../scripts/compress_memory.py) preserves:
+
+1. **Triple-backtick fences** — any language, any depth.
+2. **Numbered-options lines** — `^>?\s*\d+\.\s` plus `**Recommendation:**` / `**Empfehlung:**` label.
+3. **Backtick spans** — file paths, command names, identifiers inside body prose.
+4. **Status / error markers** — lines starting with `❌`, `⚠️`, `✅`.
+5. **Iron-Law ALL-CAPS lines** — `^[A-Z][A-Z0-9 ,.\-_/']{3,}$`.
+6. **Frontmatter blocks** — `---` fence pairs at head of file.
+7. **Mode markers** per [`role-mode-adherence`](../../rules/role-mode-adherence.md).
+
+Mangling any of these breaks Iron-Law surface host tool reads. Unit tests in `tests/test_compress_memory.py` lock each carve-out class as regression case.
+
+## Idempotency contract — Step 9 guard
+
+Script is **idempotent on clean re-runs**: running it twice on same target is no-op because body hash matches recompressed hash. Script **refuses** on **body drift**:
+
+| State | Outcome |
+|---|---|
+| No frontmatter SHA marker | Compress + write backup + inject SHA. |
+| SHA marker present, body re-compresses to same hash | No-op (return target unchanged). |
+| SHA marker present, body hash diverged | **Refuse** with `CompressionRefused` exit 3. |
+
+If you need to edit compressed memory file, run `--decompress` first, edit restored `.original.md` content, then re-run compressor. Never hand-edit compressed body — next CI run will either silently corrupt your edit (if it happens to re-compress to same shape) or hard-fail next compress pass.
+
+## Sensitive-path gate
+
+Every read path passes through [`scripts/validate_safe_paths.py`](../../../scripts/validate_safe_paths.py) `assert_safe()` before bytes leave disk. Gate is security floor for Phase 2 (input-side compression) per `step-16-caveman-substance.md` Phase 0; rollback of gate is rollback of this skill.
+
+CLI exit codes:
+
+- `0` — compress / decompress / check succeeded.
+- `2` — `SensitivePathError` (path matched denylist).
+- `3` — `CompressionRefused` (body hash diverged from frontmatter SHA).
+- `4` — `FileNotFoundError` (no `.original.md` backup to restore).
+
+## Gotchas
+
+- **Body-hash drift after manual edit** — hand-editing compressed body breaks `original_sha256:` invariant. Next compress pass refuses with `CompressionRefused` (exit 3). Recovery: `--decompress`, edit restored body, re-compress.
+- **`.original.md` backup missing on `--decompress`** — exit 4 (`FileNotFoundError`). Either someone deleted backup or `--decompress` already ran. Restore from git history; never regenerate backup by hand (regenerated content would not be byte-identical).
+- **Denylist false positive** — sensitive-looking filename outside denylist surface (project-specific naming) will still pass `assert_safe()`. Denylist necessary but not sufficient; maintainer responsible for never feeding secrets to compressor.
+- **Frontmatter ordering with existing keys** — if target already has frontmatter, compressor preserves existing keys, drops any prior `original_sha256:` / `compressed_at:` entries, and appends new pair. Other agents reading file should treat SHA + timestamp pair as canonical compression marker, not file size.
+- **Negative savings on pointer-heavy files** — `templates/AGENTS.md` already following Thin-Root (≥ 40 % pointers, ≥ 60-char *why*-clauses) has little prose left to drop; compression may net near-zero or even add bytes via frontmatter. Run [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) first to maximise pointer share, then measure whether this skill still pays.
+- **Generated-tree drift** — compressing `.agent-src.uncompressed/templates/AGENTS.md` does NOT propagate to `.augment/`, `.claude/`, etc. until package's sync + generate-tools scripts run (`scripts/compress.sh --sync` + `scripts/compress.py --generate-tools`). Always regenerate after compressing templated file.
+
+## Measurement — when to compress
+
+No published `caveman-v2` baseline for input-side savings yet (Step 11 of `step-16-caveman-substance.md` ships that). Until then, maintainer judges per-target whether compression pays its readability cost. Suggested workflow:
+
+1. `wc -c <path>` before — record baseline char count.
+2. `python3 scripts/compress_memory.py <path>` — compress + back up.
+3. `wc -c <path>` after — record post-compression char count.
+4. Eyeball diff: does prose stay legible? Are all Iron-Law fences intact?
+5. If yes → commit both `<path>` and `<path>.original.md`. If no → `--decompress`.
+
+Future `caveman-v2.md` will tabulate realised input-token saving against `agents-md-thin-root` 40 % pointer-ratio constraint so maintainer has numerical floor.
+
+## Cross-references
+
+- [`caveman-speak`](../../rules/caveman-speak.md) — runtime rule script mirrors for input-side targets; `caveman.speak_scope` does **not** gate this script (input-side runs regardless).
+- [`scripts/validate_safe_paths.py`](../../../scripts/validate_safe_paths.py) — Phase 0 gate; ported from upstream Caveman `63a91ec`.
+- [`scripts/compress_memory.py`](../../../scripts/compress_memory.py) — implementation.
+- [`tests/test_compress_memory.py`](../../../tests/test_compress_memory.py) — regression locks for each carve-out + idempotency + denylist.
+- [`docs/contracts/compression-default-kill-criterion.md`](../../../docs/contracts/compression-default-kill-criterion.md) — v1 verdict (output-side; informs but does not gate this skill).
+- [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) — caps consumer-shipped `templates/AGENTS.md`; this skill is one tool to land under cap.

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.py (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "2.19.0"
+agent_config_version: "2.20.1"
 
 # --- Project identity ---
 project:

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": "2.20.0",
+    "version": "2.21.0",
     "keywords": [
       "agent-config",
       "skills",
@@ -99,6 +99,7 @@
         "./.claude/skills/competitive-positioning",
         "./.claude/skills/composer-packages",
         "./.claude/skills/compress",
+        "./.claude/skills/compress-memory",
         "./.claude/skills/content-funnel-design",
         "./.claude/skills/context",
         "./.claude/skills/context-authoring",

package/CHANGELOG.md

@@ -695,13 +695,62 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
-# Era: 2.16.x — current
+# Era: 2.17.x — current
 
-> Started at `2.16.0` (2026-05-15). Full entries live inline below.
+> Started at `2.17.0` (2026-05-15). Full entries live inline below.
 > The drift test caps this era at 200 lines of entry body; growth past
-> that forces a new era split (`# Era: 2.17.x`, etc.) — see
+> that forces a new era split (`# Era: 2.18.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.21.0](https://github.com/event4u-app/agent-config/compare/2.20.1...2.21.0) (2026-05-17)
+
+### Features
+
+* **telemetry:** caveman stats + per-conversation cost lens ([13300cc](https://github.com/event4u-app/agent-config/commit/13300cc2d709ec2cce58520621cf560fbd6414c3))
+* **memory:** input-side compression for always-loaded files ([abfd5b1](https://github.com/event4u-app/agent-config/commit/abfd5b120f2effd2abd68adea45c8b15f315dfec))
+* **bench:** add caveman v1 benchmark with terse-control arm ([1e37062](https://github.com/event4u-app/agent-config/commit/1e37062cada6f9be5bfa0dfe4083753ade87f2f2))
+* **security:** add safe-paths denylist and caveman carve-outs validators ([249114d](https://github.com/event4u-app/agent-config/commit/249114d900a9d6960aee7bbeda5c28f85be718ad))
+
+### Bug Fixes
+
+* **caveman-speak:** bullet-format prose lines to satisfy structural-density lock ([5c8006d](https://github.com/event4u-app/agent-config/commit/5c8006d8bd70fea93671361160e6b7c4399302c6))
+* **refs:** inline roadmap council citations + mark contract council-refs as ADR trace ([5a11951](https://github.com/event4u-app/agent-config/commit/5a11951ebff87ba95465c0a6b9b59fd9a4d4cee2))
+* **contracts:** drop roadmap reference from compression-default-kill-criterion ([f2b2124](https://github.com/event4u-app/agent-config/commit/f2b212495744dae1904b256aa11d47e230e7b534))
+* **contracts:** add stability frontmatter to caveman-telemetry + cost-summary-schema ([c7efa54](https://github.com/event4u-app/agent-config/commit/c7efa54cc3587f42f3a21ca18b783b5504c56e04))
+* **portability:** apply task-invocation fix in .agent-src/ projection ([be87c2b](https://github.com/event4u-app/agent-config/commit/be87c2be1637570a61b7a8863216288f3828609c))
+* **portability:** swap task invocations for script paths in compress-memory skill ([886f9f4](https://github.com/event4u-app/agent-config/commit/886f9f4a615fa2351b9261a62fd49173f8e87c2f))
+* **roadmap:** clarify agent-status is a command not a skill in step-16 ([96df39d](https://github.com/event4u-app/agent-config/commit/96df39de7a7562df946c37fea8bc42927851071f))
+* **template:** bump agent_config_version pin to 2.20.1 ([c275864](https://github.com/event4u-app/agent-config/commit/c2758641718077baaaaefea1191760d397f6b47e))
+
+### Documentation
+
+* **readme:** compact banner and badge row to stay under 750-line lint budget ([2f411a7](https://github.com/event4u-app/agent-config/commit/2f411a78993260d3bd1f5fb819779cad2b19ed07))
+* **readme:** add hero banner and migrate count display to shields.io badges ([980fe1a](https://github.com/event4u-app/agent-config/commit/980fe1ac1c529e3c57c967db148f2b162240ff27))
+* **caveman:** v1 kill-criterion verdict + Suspended state ([ca1751e](https://github.com/event4u-app/agent-config/commit/ca1751e8957783fa4e40ddfb89172702619f12bc))
+
+### Chores
+
+* **ownership:** regenerate ownership matrix ([1331bce](https://github.com/event4u-app/agent-config/commit/1331bce63d223adb971a931babe5e163b5a8aa12))
+* **index:** regenerate agents/index.md + docs/catalog.md for compress-memory ([6d16e7f](https://github.com/event4u-app/agent-config/commit/6d16e7fb3ca0a2fbe76a18337a94e98607262d06))
+* **sync:** bump skill count 210 -> 211 (compress-memory) ([bb361ed](https://github.com/event4u-app/agent-config/commit/bb361edb4e5e65cbc4e7eb41382f88f1909e5583))
+* **roadmaps:** close step-16 caveman-substance + archive-phantom-scan ([9388f9b](https://github.com/event4u-app/agent-config/commit/9388f9be662da17b98eb4000f16ff8fcf376e626))
+
+Tests: 4559 (+24 since 2.20.1)
+
+## [2.20.1](https://github.com/event4u-app/agent-config/compare/2.20.0...2.20.1) (2026-05-16)
+
+### Bug Fixes
+
+* **lint:** treat zero active roadmaps as pass in lint-roadmap-complexity ([ff814e2](https://github.com/event4u-app/agent-config/commit/ff814e262a25b9269ae5d1b66495602b5d8f457b))
+* **template:** bump agent_config_version pin to 2.20.0 ([ab3acfc](https://github.com/event4u-app/agent-config/commit/ab3acfc3eebd39e5fb7df919bd5b7a455e2f58ea))
+
+### Chores
+
+* **changelog:** split era 2.16.x → pre-2.17.0 ([67b668e](https://github.com/event4u-app/agent-config/commit/67b668ee2298cc56478a808a716e965482bf199d))
+* **roadmaps:** close and archive all 8 open roadmaps (Total Dominance) ([c13359f](https://github.com/event4u-app/agent-config/commit/c13359f0b676f251a9b6c6b7ed11804fdeb84257))
+
+Tests: 4535 (+0 since 2.20.0)
+
 ## [2.20.0](https://github.com/event4u-app/agent-config/compare/2.19.0...2.20.0) (2026-05-16)
 
 ### Features
@@ -881,47 +930,14 @@ Tests: 4476 (+17 since 2.17.0)
 
 Tests: 4459 (+54 since 2.16.0)
 
-## [2.16.0](https://github.com/event4u-app/agent-config/compare/2.15.0...2.16.0) (2026-05-15)
-
-### Features
-
-* **install:** install-mode marker + minimal-init upgrade hint (Step 8 P3) ([e028468](https://github.com/event4u-app/agent-config/commit/e028468ed2b58428b99bea5a2e6c2a25e12fc113))
-* **cli:** doctor --trace-root + --context diagnostic surface (Step 8 P2) ([387a626](https://github.com/event4u-app/agent-config/commit/387a626b7795fc40e6e2442c1dde272dfc98f9d7))
-* **cli:** --root override flag + fail-loud root validation (Step 8 P1) ([0c8356e](https://github.com/event4u-app/agent-config/commit/0c8356e9034ca474827de89db5386a04c61f560c))
-* **wrapper:** export AGENT_CONFIG_PROJECT_ROOT pin so subdir invocations skip the walk ([e866cef](https://github.com/event4u-app/agent-config/commit/e866cef14d40269786fb0a88b69d9aafcfab1c88))
-* **agent-settings:** add resolve_project_root helper for Phase 3 subdir hardening ([95bac18](https://github.com/event4u-app/agent-config/commit/95bac187132d35d476716cd38d8c619bccaca6e5))
-* **install:** add --minimal / --settings-only init mode ([4c02743](https://github.com/event4u-app/agent-config/commit/4c02743cd7df6d89f7b7fa6188d654ca1eec983c))
-* **agent_settings:** extend find_project_root with agents/ + .agent-settings.yml anchors ([60dcd11](https://github.com/event4u-app/agent-config/commit/60dcd11c498f25f92bb01482943bfb95d4efef37))
-
-### Documentation
-
-* **changelog:** Step 8 discovery polish entry under Unreleased ([eecaf6a](https://github.com/event4u-app/agent-config/commit/eecaf6a9a2248a877d71dbd33e7db096f94dab3b))
-* **installation:** root override + monorepo semantics + diagnostics (Step 8) ([de3081f](https://github.com/event4u-app/agent-config/commit/de3081fe828cb43c628d922c50d25177d43f267e))
-* **roadmap:** archive step-7 (all phases complete) + sync dashboard ([8f2953e](https://github.com/event4u-app/agent-config/commit/8f2953ee5c867ada29c9f32cf45bd2380504bc12))
-* **step-7:** add minimal-init flow, anchor migration guide, changelog entry ([9ace019](https://github.com/event4u-app/agent-config/commit/9ace01945967e67e98e8855a940801db09de8d17))
-* **roadmap:** mark Step 7 Phase 3 complete (subdir invocation hardening) ([518f9dc](https://github.com/event4u-app/agent-config/commit/518f9dcaf6d71a34cf1700bceb1487f1e8e33175))
-* **roadmap:** mark Step 7 Phase 2 + test items complete ([1bb9b71](https://github.com/event4u-app/agent-config/commit/1bb9b712d866dd509124f7d8502f52957e972b20))
-* **roadmap:** mark Step 7 Phase 1 complete; refresh progress dashboard ([2ba8d5b](https://github.com/event4u-app/agent-config/commit/2ba8d5be1b94bbab87da4270d833697c895cc9c6))
-
-### Refactoring
-
-* **cli:** route all cmd_*.py entry points through resolve_project_root ([aa7a01a](https://github.com/event4u-app/agent-config/commit/aa7a01a7f27205919193d54339298c0dbd30c43e))
+# Era: pre-2.17.0 — archived
 
-### Tests
-
-* **cli:** coverage for --root override + doctor trace/context (Step 8) ([9b943aa](https://github.com/event4u-app/agent-config/commit/9b943aa9f002750499738fd36f8a203525fb84da))
-* **subdir:** cover resolve_project_root precedence + wrapper-pinned root ([0693714](https://github.com/event4u-app/agent-config/commit/06937145ac8f4e1160ec9279d3832e4f5397bb1e))
-* **install:** cover --minimal payload + nested-install guard ([5623521](https://github.com/event4u-app/agent-config/commit/56235218624792b487a92f444ff8ee114a5651a3))
-* **agent_settings:** cover anchor extension, kill-switch, perf budget ([37a080c](https://github.com/event4u-app/agent-config/commit/37a080c07ee9238fda45bbda1829764a4232f062))
-
-### Chores
-
-* **template:** bump agent_config_version pin to 2.15.0 ([093367d](https://github.com/event4u-app/agent-config/commit/093367d3e417a11a28295f2efa574e8c3fef6524))
-* **sync:** propagate Step 8 agent_settings.py to .agent-src/ projection ([7ce92e5](https://github.com/event4u-app/agent-config/commit/7ce92e514a8edbd970a4118b91d2f651bf730070))
-* **roadmap:** archive Step 8 discovery polish ([1c21982](https://github.com/event4u-app/agent-config/commit/1c219825dc413cfe45aefc3b12c08d2720583880))
-* **changelog:** split era 2.11.x → pre-2.15.0 ([c79363c](https://github.com/event4u-app/agent-config/commit/c79363c05d775ecfa95ab6fff5b3bbe706f797c9))
-
-Tests: 4405 (+53 since 2.15.0)
+> All `2.16.0` entries live in
+> [`docs/archive/CHANGELOG-pre-2.17.0.md`](docs/archive/CHANGELOG-pre-2.17.0.md).
+> The archive is read-only; git tag `2.16.0` remains the canonical
+> source for what shipped. Splitting these out of the main file keeps
+> the active era under the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
 
 # Era: pre-2.16.0 — archived
 

package/README.md

@@ -1,5 +1,9 @@
+<p align="center"><a href="https://event4u.app"><img alt="event4u Agent Config" src=".github/assets/banner.png"></a></p>
+
 # Agent Config — Universal AI Agent OS
 
+[![Skills](https://img.shields.io/badge/Skills-211-1f6feb?style=flat-square)](.augment/skills/) [![Rules](https://img.shields.io/badge/Rules-79-d73a49?style=flat-square)](.augment/rules/) [![Commands](https://img.shields.io/badge/Commands-124-2da44e?style=flat-square)](.augment/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-72-8957e5?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-22-bf8700?style=flat-square)](docs/personas.md) [![Advisors](https://img.shields.io/badge/Advisors-5-fb8500?style=flat-square)](docs/profiles.md) [![AI Tools](https://img.shields.io/badge/AI%20Tools-8-1abc9c?style=flat-square)](docs/architecture.md) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+
 > **A deterministic orchestration contract for AI agents — audited skills, governance rules, replayable state — usable by developers, founders, and creators alike.**
 
 Give your AI agents an audit-disciplined execution layer: **210 skills**, **79 governance rules**, **124 commands**, and a replayable state machine that turns any host agent (Claude Code, Augment, Cursor, Copilot, Windsurf) into a reliable team member.
@@ -27,10 +31,6 @@ schema: [`docs/contracts/profile-system.md`](docs/contracts/profile-system.md).
 Beyond software: [`user-types/`](.agent-src.uncompressed/user-types/)
 (galabau · metalworking · truck — see [Who this is for](#who-this-is-for)).
 
-<p align="center">
-  <strong>210 Skills</strong> · <strong>79 Rules</strong> · <strong>124 Commands</strong> · <strong>72 Guidelines</strong> · <strong>22 Personas</strong> · <strong>5 Advisors</strong> · <strong>8 AI Tools</strong>
-</p>
-
 <p align="center">
   <a href="CHANGELOG.md">CHANGELOG</a> ·
   <a href="https://github.com/event4u-app/agent-config/releases/latest">Latest release</a> ·
@@ -577,7 +577,7 @@ slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
 or manual wiring required)
 
 > **What this means in practice:** Claude Code gets the full project-scoped
-> package (rules + 210 skills + 124 native commands); Augment Code gets the
+> package (rules + 211 skills + 124 native commands); Augment Code gets the
 > same content but only from a single global install at `~/.augment/`.
 > Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot, Roo Code, Codex CLI,
 > and Continue.dev only get the **rules** natively; skills and commands are

package/docs/architecture.md

@@ -141,7 +141,7 @@ note, package-internal path-swap, description budget, and the
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 210 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Skills** | 211 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 79 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 124 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 72 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |

package/docs/archive/CHANGELOG-pre-2.17.0.md

@@ -0,0 +1,63 @@
+# Changelog Archive — pre-2.17.0
+
+> Frozen snapshot of `event4u/agent-config` changelog entries from
+> `2.16.0`, split out of the main
+> [`CHANGELOG.md`](../../CHANGELOG.md) on 2026-05-16 once the active
+> era's body crossed the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
+>
+> **Read-only.** New entries land in `CHANGELOG.md` § "Era: 2.17.x".
+> Entries here are not amended — git tag `2.16.0` remains the
+> canonical source for what shipped.
+>
+> Entry shape follows the conventions documented in
+> [`docs/contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md).
+> Earlier eras live in
+> [`CHANGELOG-pre-2.16.0.md`](CHANGELOG-pre-2.16.0.md),
+> [`CHANGELOG-pre-2.15.0.md`](CHANGELOG-pre-2.15.0.md),
+> [`CHANGELOG-pre-2.11.0.md`](CHANGELOG-pre-2.11.0.md),
+> [`CHANGELOG-pre-2.7.0.md`](CHANGELOG-pre-2.7.0.md), and
+> [`CHANGELOG-pre-2.2.0.md`](CHANGELOG-pre-2.2.0.md).
+
+
+## [2.16.0](https://github.com/event4u-app/agent-config/compare/2.15.0...2.16.0) (2026-05-15)
+
+### Features
+
+* **install:** install-mode marker + minimal-init upgrade hint (Step 8 P3) ([e028468](https://github.com/event4u-app/agent-config/commit/e028468ed2b58428b99bea5a2e6c2a25e12fc113))
+* **cli:** doctor --trace-root + --context diagnostic surface (Step 8 P2) ([387a626](https://github.com/event4u-app/agent-config/commit/387a626b7795fc40e6e2442c1dde272dfc98f9d7))
+* **cli:** --root override flag + fail-loud root validation (Step 8 P1) ([0c8356e](https://github.com/event4u-app/agent-config/commit/0c8356e9034ca474827de89db5386a04c61f560c))
+* **wrapper:** export AGENT_CONFIG_PROJECT_ROOT pin so subdir invocations skip the walk ([e866cef](https://github.com/event4u-app/agent-config/commit/e866cef14d40269786fb0a88b69d9aafcfab1c88))
+* **agent-settings:** add resolve_project_root helper for Phase 3 subdir hardening ([95bac18](https://github.com/event4u-app/agent-config/commit/95bac187132d35d476716cd38d8c619bccaca6e5))
+* **install:** add --minimal / --settings-only init mode ([4c02743](https://github.com/event4u-app/agent-config/commit/4c02743cd7df6d89f7b7fa6188d654ca1eec983c))
+* **agent_settings:** extend find_project_root with agents/ + .agent-settings.yml anchors ([60dcd11](https://github.com/event4u-app/agent-config/commit/60dcd11c498f25f92bb01482943bfb95d4efef37))
+
+### Documentation
+
+* **changelog:** Step 8 discovery polish entry under Unreleased ([eecaf6a](https://github.com/event4u-app/agent-config/commit/eecaf6a9a2248a877d71dbd33e7db096f94dab3b))
+* **installation:** root override + monorepo semantics + diagnostics (Step 8) ([de3081f](https://github.com/event4u-app/agent-config/commit/de3081fe828cb43c628d922c50d25177d43f267e))
+* **roadmap:** archive step-7 (all phases complete) + sync dashboard ([8f2953e](https://github.com/event4u-app/agent-config/commit/8f2953ee5c867ada29c9f32cf45bd2380504bc12))
+* **step-7:** add minimal-init flow, anchor migration guide, changelog entry ([9ace019](https://github.com/event4u-app/agent-config/commit/9ace01945967e67e98e8855a940801db09de8d17))
+* **roadmap:** mark Step 7 Phase 3 complete (subdir invocation hardening) ([518f9dc](https://github.com/event4u-app/agent-config/commit/518f9dcaf6d71a34cf1700bceb1487f1e8e33175))
+* **roadmap:** mark Step 7 Phase 2 + test items complete ([1bb9b71](https://github.com/event4u-app/agent-config/commit/1bb9b712d866dd509124f7d8502f52957e972b20))
+* **roadmap:** mark Step 7 Phase 1 complete; refresh progress dashboard ([2ba8d5b](https://github.com/event4u-app/agent-config/commit/2ba8d5be1b94bbab87da4270d833697c895cc9c6))
+
+### Refactoring
+
+* **cli:** route all cmd_*.py entry points through resolve_project_root ([aa7a01a](https://github.com/event4u-app/agent-config/commit/aa7a01a7f27205919193d54339298c0dbd30c43e))
+
+### Tests
+
+* **cli:** coverage for --root override + doctor trace/context (Step 8) ([9b943aa](https://github.com/event4u-app/agent-config/commit/9b943aa9f002750499738fd36f8a203525fb84da))
+* **subdir:** cover resolve_project_root precedence + wrapper-pinned root ([0693714](https://github.com/event4u-app/agent-config/commit/06937145ac8f4e1160ec9279d3832e4f5397bb1e))
+* **install:** cover --minimal payload + nested-install guard ([5623521](https://github.com/event4u-app/agent-config/commit/56235218624792b487a92f444ff8ee114a5651a3))
+* **agent_settings:** cover anchor extension, kill-switch, perf budget ([37a080c](https://github.com/event4u-app/agent-config/commit/37a080c07ee9238fda45bbda1829764a4232f062))
+
+### Chores
+
+* **template:** bump agent_config_version pin to 2.15.0 ([093367d](https://github.com/event4u-app/agent-config/commit/093367d3e417a11a28295f2efa574e8c3fef6524))
+* **sync:** propagate Step 8 agent_settings.py to .agent-src/ projection ([7ce92e5](https://github.com/event4u-app/agent-config/commit/7ce92e514a8edbd970a4118b91d2f651bf730070))
+* **roadmap:** archive Step 8 discovery polish ([1c21982](https://github.com/event4u-app/agent-config/commit/1c219825dc413cfe45aefc3b12c08d2720583880))
+* **changelog:** split era 2.11.x → pre-2.15.0 ([c79363c](https://github.com/event4u-app/agent-config/commit/c79363c05d775ecfa95ab6fff5b3bbe706f797c9))
+
+Tests: 4405 (+53 since 2.15.0)

package/docs/benchmarks.md

@@ -0,0 +1,74 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# Benchmark cadence
+
+> **Status:** active · **Owner:** `step-16-caveman-substance.md` Phase 1 ·
+> **Sources:** [`benchmark-corpus-spec.md`](contracts/benchmark-corpus-spec.md) ·
+> [`benchmark-report-schema.md`](contracts/benchmark-report-schema.md)
+
+Where the package's benchmark runs live, when they run, and what counts as
+a publishable report. Mirrors the Ruflo `docs/benchmarks/runs/<ISO>.json`
+discipline (upstream `5b71c7a`).
+
+## Corpora
+
+| Corpus | Path | Purpose |
+|---|---|---|
+| `dev` | `tests/eval/corpus-dev.yaml` | router / engine selection |
+| `caveman` | `bench/corpora/caveman/prompts.yaml` | compression dialect (`vs_raw` + `vs_terse`) |
+
+## Reports — naming and trail
+
+- **Canonical pointer:** `bench/reports/<corpus>-v<N>.{json,md}` — always
+  reflects the latest published run for that corpus version.
+- **Timestamped trail:** `bench/reports/<ISO-Zulu>-<corpus>-v<N>.{json,md}`
+  — every committed run keeps an immutable history copy alongside.
+
+Both are produced in one `scripts/bench_run.py` invocation; do not commit
+one without the other.
+
+## Cadence
+
+| Trigger | Required corpus | Required artefact |
+|---|---|---|
+| Pre-release bake (any `vX.Y.0`) | `dev` + `caveman` | both reports refreshed |
+| Edit to `.agent-src.uncompressed/rules/caveman-speak.md` | `caveman` | report refreshed in same PR |
+| Edit to `scripts/bench_run.py` `--caveman` arm | `caveman` | report refreshed in same PR |
+| Edit to `bench/corpora/caveman/prompts.yaml` | `caveman` | report refreshed, version bumped (`caveman-vN+1`) |
+| Edit to `scripts/_lib/bench_caveman*.py` | `caveman` | report refreshed in same PR |
+
+A PR that touches any of the cadence triggers without refreshing the
+corresponding report is rejected by reviewer convention (no CI gate yet
+— the trigger surface is too small to warrant one).
+
+## Cost envelope (`caveman` corpus)
+
+10 prompts × 3 arms (`compressed` · `terse-control` · `uncompressed`) = 30
+Anthropic calls per run. Observed envelope on `claude-sonnet-4-5` (v1,
+2026-05-16): **$0.0805 actual** · 0 errors · realised carve-out share
+30.67 %.
+
+## Commands
+
+```bash
+task bench -- --caveman                                  # full run
+task bench -- --caveman --caveman-max-prompts 1          # 1-prompt smoke
+task bench -- --caveman --caveman-dry-run --no-write     # offline shape
+```
+
+Cost-touched runs require an `ANTHROPIC_API_KEY` at
+`~/.event4u/agent-config/anthropic.key` (mode 600).
+
+## Cross-references
+
+- [`benchmark-corpus-spec.md`](contracts/benchmark-corpus-spec.md) —
+  per-prompt schema.
+- [`benchmark-report-schema.md`](contracts/benchmark-report-schema.md) —
+  per-report JSON / Markdown contract.
+- [`compression-default-kill-criterion.md`](contracts/compression-default-kill-criterion.md)
+  — how a published `caveman-v<N>` report is read against the kill table.
+- `agents/roadmaps/step-16-caveman-substance.md` Phase 1 — where the
+  caveman corpus was authored.

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **482 public artefacts** shipped by
+Consumer-facing catalog of all **483 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 (210)
+## Skills (211)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -43,6 +43,7 @@ are excluded.
 | skill | [`competitive-moat-analysis`](../.agent-src/skills/competitive-moat-analysis/SKILL.md) |  | Use when mapping competitors, naming defensibility, and finding white-space — moat reasoning, where-to-play, where-not-to-play. Triggers on 'who are we competing with', 'what's our moat'. |
 | skill | [`competitive-positioning`](../.agent-src/skills/competitive-positioning/SKILL.md) |  | Use when comparing this package to a peer / competitor — ours-vs-theirs verdict table, axis selection, adoption queue. Triggers on 'how do we compare to X', 'should we adopt their pattern'. |
 | skill | [`composer-packages`](../.agent-src/skills/composer-packages/SKILL.md) |  | Use when building or maintaining a Composer library — versioning, Laravel integration, autoloading, publishing to private registries — even when the user says 'release a new version'. |
+| skill | [`compress-memory`](../.agent-src/skills/compress-memory/SKILL.md) |  | Use when shrinking always-loaded memory files (AGENTS.md, CLAUDE.md, .cursorrules) via caveman grammar — refuses sensitive paths, round-trips via .original.md backup. |
 | skill | [`content-funnel-design`](../.agent-src/skills/content-funnel-design/SKILL.md) |  | Use when mapping funnel-stage to content shape — conversion-pathway, content-as-system, leverage-point selection. Triggers on 'design our content funnel', 'why does mid-funnel leak'. |
 | skill | [`context-authoring`](../.agent-src/skills/context-authoring/SKILL.md) |  | Use when filling in knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive walkthrough that turns templates into reviewer fuel. |
 | skill | [`context-document`](../.agent-src/skills/context-document/SKILL.md) |  | Use when the user says "create context", "document this area", or wants a structured snapshot of a codebase area for agent orientation. |

package/docs/contracts/caveman-telemetry.md

@@ -0,0 +1,83 @@
+---
+stability: beta
+keep-beta-until: 2026-08-15
+---
+
+# caveman telemetry — multiplier contract
+
+> **Status:** suspended (kill-criterion not met in `caveman-v1`).
+> Telemetry surface records `caveman_delta_tokens = 0` until a v2 bench
+> proves a positive multiplier on the load-bearing `vs_terse` arm.
+
+## Constant
+
+| Key | Value | Provenance |
+|---|---|---|
+| `caveman_multiplier_version` | `v1` | Tied to `bench/reports/caveman-v1.{json,md}` |
+| `caveman_multiplier_value` | `0.9155` | `median(terse_control_tokens / compressed_tokens)` over the 10-prompt v1 corpus |
+| `caveman_multiplier_p10` | `0.4506` | 10th percentile (worst-case carve-out-tax prompts) |
+| `caveman_multiplier_p90` | `2.3664` | 90th percentile (pure-prose prompts where caveman wins) |
+| `caveman_multiplier_active` | `false` | **Suspended** — kill-criterion not met (`vs_terse` median −9.27 %) |
+
+The **active** flag gates whether the multiplier is applied to runtime
+telemetry. While `false`, `scripts/caveman_stats.py` reports
+`caveman_delta_tokens = 0` regardless of `speak_scope` setting.
+
+## How the multiplier is interpreted
+
+`caveman_estimated_uncompressed_tokens = caveman_compressed_tokens × M`,
+where `M = caveman_multiplier_value`.
+
+`caveman_delta_tokens = caveman_estimated_uncompressed_tokens − caveman_compressed_tokens`.
+
+- `M > 1.0` → caveman compresses; `delta` is **positive** (saving).
+- `M = 1.0` → break-even; no delta surfaced.
+- `M < 1.0` → caveman costs more than the terse baseline; `delta` is
+  **negative**. Surfacing a negative saving is misleading for the
+  user (looks like a bug), so the contract is to **suspend the
+  multiplier** and record `delta = 0` until a v2 bench lifts `M`
+  above `1.0` on the load-bearing arm.
+
+## Why suspended after v1
+
+The `caveman-v1` bench (`bench/reports/caveman-v1.md`, 30 calls,
+2026-05-16) found:
+
+- Median savings vs raw uncompressed: **+23.51 %** (inflated by the
+  carve-out-tax-free pure-prose prompts).
+- Median savings vs terse-control: **−9.27 %** (load-bearing).
+- Carve-out-heavy prompts (path-list −108 %, mode-marker −123 %)
+  drag the median negative.
+
+The terse-control arm is the kill-criterion baseline per
+[`compression-default-kill-criterion.md`](compression-default-kill-criterion.md).
+Until a v2 bench (broader corpus or a re-tuned dialect) lifts the
+`vs_terse` median to ≥ 0 %, the multiplier stays suspended.
+
+## How to lift the suspension
+
+1. Run an extended bench against a broader corpus (Phase 3+ work).
+2. If `median(savings_vs_terse) ≥ 0` (and ideally ≥ 30 % to flip the
+   rule default), recompute `caveman_multiplier_value`.
+3. Update this contract: bump `caveman_multiplier_version` to `v2`,
+   set `caveman_multiplier_active = true`, cite the new bench file.
+4. The change is reversible — drop back to `v1` if a regression
+   appears.
+
+## Consumers
+
+- [`scripts/caveman_stats.py`](../../scripts/caveman_stats.py) — reads
+  this constant, computes per-session / per-conversation / lifetime
+  deltas from `agents/cost-tracking/sessions.jsonl`.
+- [`scripts/cost_summary.py`](../../scripts/cost_summary.py) — emits
+  the stable JSON contract for inter-tool consumption per
+  [`cost-summary-schema.md`](cost-summary-schema.md).
+- `agent-status` skill — surfaces the per-session delta in the
+  status report under the `[caveman: …]` widget.
+
+## See also
+
+- [`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) — the rule-default-flip gate; this multiplier is gated on the same `vs_terse` arm.
+- [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) — provenance for the `v1` value.
+- [`bench/reports/caveman-v2.md`](../../bench/reports/caveman-v2.md) — input-side (orthogonal); does NOT feed this multiplier (this multiplier is output-side).
+- [`caveman-speak`](../../.agent-src.uncompressed/rules/caveman-speak.md) — runtime rule the multiplier measures.