@event4u/agent-config 9.0.0 → 9.2.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Bootstrap shim for the event4u agent-config suite. This plugin ships ONLY the dispatcher hooks plus one install-pointer skill — ALL content (skills, rules, commands) is installed via `npx -y @event4u/agent-config init`, which writes the file projection AND registers the same hooks in ~/.claude/settings.json. DEPRECATED as a content channel; kept so the marketplace listing stays discoverable and existing installs keep working hooks.",
-    "version": "9.0.0",
+    "version": "9.2.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -48,26 +48,6 @@ foundation also land — both non-breaking by default.
 
 ### Breaking changes (6.0.0)
 
-**0. Consumer rule projection is scoped by default** (`road-to-request-scoped-rule-load` Phase 1 human gate, 2026-07-13)
-
-- **Who is affected:** fresh consumer installs — the settings template now
-  ships `projection.rule_workspaces` filled with every consumer workspace, so
-  the 16 exclusively-maintainer specification rules (plus the recorded
-  `source-of-truth.md` compat exclusion) no longer arrive: 103 → 88 rules,
-  −9,880 cl100k tokens (−13.1%) per install. All domain safety floors and
-  domain rules keep shipping; kernel rules always ship.
-- **Existing installs:** unchanged until you run `agent-config sync` /
-  re-install (settings sync preserves your current value; fill the list to
-  opt in). The first session after opting in rebuilds the KV-cache prefix
-  once (1.25–2× write cost, one session only).
-- **Quality evidence:** deterministic set-inclusion verification
-  (`src/scripts/check_consumer_scope_flip.ts` →
-  `internal/bench/reports/2026-07-13-consumer-scoped-default-flip.json`):
-  only exclusively-maintainer rules drop; zero golden-set-exercised consumer
-  rules affected (90/90 labelled tasks, coverage 86/86).
-- **Rollback:** set `projection.rule_workspaces: []` (= legacy-all).
-
-
 **1. Condensed output moved: root `.agent-src/` → `dist/agent-src/`** ([ADR-058])
 
 - **Who is affected:** consumers whose scripts or tool configs hard-code
@@ -1037,207 +1017,45 @@ our recommendation order, not its support status.
 > keeps the active era under the 250-line drift cap enforced by
 > `tests/test_changelog_eras.py`.
 
-# Era: 8.12.x — current
-
-> Started at `8.12.0`. Full entries live inline below.
-> The drift test caps this era at 250 lines of entry body; growth past
-> that forces a new era split (`# Era: 8.13.x`, etc.) — see
-> [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
-
-## [9.0.0](https://github.com/event4u-app/agent-config/compare/8.13.0...9.0.0) (2026-07-13)
-
-### BREAKING CHANGES
-
-* **scoping:** flip consumer rule projection default to scoped (Phase-1 human gate, approved) ([565c91a](https://github.com/event4u-app/agent-config/commit/565c91aa25e4c970d5b37258f497366f33e7a7a9))
-
-### Features
-
-* **product:** pre-build demand gate folded into improve-before-implement — plate complete, archived ([d6b0fcb](https://github.com/event4u-app/agent-config/commit/d6b0fcb9d020f983a98f8cd0c744d758bb758f9a))
-* **skills:** Known-pitfalls sections for docker, terraform, laravel ([4427224](https://github.com/event4u-app/agent-config/commit/442722417f319b7b704c2d0bdc711c38e870f796))
-* **skill-writing,size-enforcement:** Known-pitfalls section standard + sprawl guard ([6276c9f](https://github.com/event4u-app/agent-config/commit/6276c9f24b3166c1ae4360151cf05f2cd29f9b31))
-* **skill:** spreadsheet-authoring — recalc-verification loop + zero-formula-error contract ([fcaf93e](https://github.com/event4u-app/agent-config/commit/fcaf93e8beb36c944b356df04b1203941f8a3271))
-* **skill:** pdf-tools — library-per-task PDF create/transform/fill routing ([11af714](https://github.com/event4u-app/agent-config/commit/11af7140fa999dea0f514ddb32f5a1d6d6e8934b))
-* **skill:** docx-authoring — skeleton-create + unpack/edit/pack-with-validate toolkit ([218f711](https://github.com/event4u-app/agent-config/commit/218f7115359f10c630c239ec02302f6a2eb21a63))
-* **humanizer:** severity-tiered AI-ism taxonomy, stance-preservation, voice-match ([00077d2](https://github.com/event4u-app/agent-config/commit/00077d2488246766317f86110a65e65cab7080b9))
-* **skills:** docx-authoring + pdf-tools — completes the document read→write cycle ([c0688c1](https://github.com/event4u-app/agent-config/commit/c0688c11badc38bd060de89f0585b351ea2d265d))
-* **skill:** launch-readiness epistemics block + fix-loop (contract-backed) ([591c386](https://github.com/event4u-app/agent-config/commit/591c386ae6be8d06b68997a41198166334e7249c))
-* **prelaunch:** finding-ID contract, epistemics, regression gate + suppression ([0f4bff6](https://github.com/event4u-app/agent-config/commit/0f4bff64e12f5a73525ea2272df479672ce7f9aa))
-* **workflow:** Phase 3 merge-conflicts plan-first — plate complete, archived ([3f51f4e](https://github.com/event4u-app/agent-config/commit/3f51f4ed1fa6ed4253788432db468c35678f1c81))
-* **workflow:** Phase 2 — HANDOFF.md convention, resume rule, artifact validation ([5092d5e](https://github.com/event4u-app/agent-config/commit/5092d5ef44ea154817eda4640a526fa0909ed9a9))
-* **workflow:** Phase 1 — TDD mode contracts with diff-checkable Forbidden blocks ([a6c4d70](https://github.com/event4u-app/agent-config/commit/a6c4d7048e24505db80dc04c6e03d8a63bfce3d1))
-* **ci:** bridge-derivation, tools-matrix + host-loadability gates (Phase 4.3/4.4) ([9168bbd](https://github.com/event4u-app/agent-config/commit/9168bbdb455412261bf593dd89f5111085d24fe9))
-* **schema:** optional effort: reasoning-effort pin (Phase 4.2) ([9248f36](https://github.com/event4u-app/agent-config/commit/9248f366d13e79d195bfcd50985fc48313e1b51f))
-* **commands:** argument-hint frontmatter across the command surface (Phase 4.1) ([333a1b3](https://github.com/event4u-app/agent-config/commit/333a1b37bd15ff394c9c82ba4a7a961ce3aaf1c2))
-* **authoring:** U1 description-optimizer loop (held-out split) — plate complete, archived ([a2d7f55](https://github.com/event4u-app/agent-config/commit/a2d7f552a6d28657714914d0a0efa81decb2b57e))
-* **authoring:** U5 self-QA fresh-eyes pattern for output-producing skills ([6295bd7](https://github.com/event4u-app/agent-config/commit/6295bd744dc6dbd96face318956e3925a0b80ca6))
-* **authoring:** U3 tool-grant uplift — scoped grants, disallowed_tools deny-list, numeric thresholds ([7089ac8](https://github.com/event4u-app/agent-config/commit/7089ac8d6ac5121f391650987b5b2c8fb227f6fb))
-* **authoring:** U4 register note + U2 Agent-Skills spec alignment ([6ce3a13](https://github.com/event4u-app/agent-config/commit/6ce3a13b1243fdfb63a184c758a4764ab1dc67d8))
-* **telemetry:** U5 agent-combo facet on the orchestration record ([1aacb46](https://github.com/event4u-app/agent-config/commit/1aacb46458c42f3857b5107d714ca25386133e97))
-* **measurement:** U4 host-loadability smoke — generated trees must actually load ([0d0b014](https://github.com/event4u-app/agent-config/commit/0d0b0141f160f5722d4bba71ba8e017d0445a98a))
-* **evals:** U2 golden-adversarial review pair + not_contains assertion kind ([b5f040a](https://github.com/event4u-app/agent-config/commit/b5f040a8fd90b6012106760c06a67981a2a437a9))
-* **measurement:** U1 loaded-vs-fired utilization report + census-honesty note ([545c2ce](https://github.com/event4u-app/agent-config/commit/545c2ce3f1c0d3894bb9eebd5c87bb8e110ddb2b))
-* **telemetry:** U1a loaded denominator — engagement schema, record CLI, aggregator, renderer ([a549788](https://github.com/event4u-app/agent-config/commit/a5497881cc67475a6cddfc3fb857f675fcb032be))
-* **skill-quality:** add read-only-by-default script-convention lint ([401828d](https://github.com/event4u-app/agent-config/commit/401828df53069331007fe0e28edab8811fa46fa4))
-* **skill-quality:** add eval schema v2 — tool-choice + trajectory_budget ([63a5cdf](https://github.com/event4u-app/agent-config/commit/63a5cdfd433374099ea70e8e10a5b8350ccebb52))
-* **skill-quality:** add description-quality lint gate ([e7acc5e](https://github.com/event4u-app/agent-config/commit/e7acc5ec8744b1e00d2fe9ad89727731d3500147))
-* **scoping:** deterministic held-quality verifier for the consumer scoped-projection flip ([9375e6e](https://github.com/event4u-app/agent-config/commit/9375e6e6f4788f644c031a62c36e956bd49c0ec7))
-* **review:** tally-vs-reasoned boundary + fix-pr-comments dedup ([564efa8](https://github.com/event4u-app/agent-config/commit/564efa8300b07c345c9c618b8d5790f20fde9089))
-* **review:** change-type routing, two-tier output, de-biasing in code-review ([ffad758](https://github.com/event4u-app/agent-config/commit/ffad75807e3ae6dae58087280d47865286d9d437))
-* **team-gate:** managed Review-Gate circuit breaker — never an infinite Claude/Codex loop ([0356b30](https://github.com/event4u-app/agent-config/commit/0356b30f60a00b9fe7b13cdd7dde05ddda3684db))
-* **team-fallback:** read-only multi-host review via team_dispatch + team-review envelope ([ba6ea00](https://github.com/event4u-app/agent-config/commit/ba6ea0062b34cad03dc296a887a7d8edba559d09))
-* **security:** STRIDE table, CI-agent + insecure-defaults coverage, active-probe design note ([260fd2f](https://github.com/event4u-app/agent-config/commit/260fd2fe667e0c605cd042935327b316fa4a9641))
-* **security:** add security-maturity-assessment skill ([657b68f](https://github.com/event4u-app/agent-config/commit/657b68f550bdeff356cfa3e1654a98f69835ec26))
-* **security:** add false-positive gate to bug + security review skills ([4309cb3](https://github.com/event4u-app/agent-config/commit/4309cb35f93eb68deeed523369417ad90c13d86c))
-* **evals:** calibrate finding_floor from the cross-host lower envelope — gate armed ([c19aecf](https://github.com/event4u-app/agent-config/commit/c19aecfb440e3d748935a494400319ff8bd0617a))
-* **bench:** cross-model parity count-pass runner (council-transport re-scope) ([5cef323](https://github.com/event4u-app/agent-config/commit/5cef32329263f1169ed7875cf4cfad0ab982a10c))
-
-### Bug Fixes
-
-* **humanizer:** reword 'drift' → 'slippage' to clear wing3_vendor_independence false-positive ([66f9179](https://github.com/event4u-app/agent-config/commit/66f91797a0f3cff9c414cb0edfe64b89c916d1a8))
-* **ai-council:** enforce config is user-global only, never project-local ([09b16bb](https://github.com/event4u-app/agent-config/commit/09b16bb559f548baf2760a255e1ab20b48a3ccdd))
-* **merge:** resolve index-roadmap conflict — both quality-gates and workflow-contracts shipped ([c42dce4](https://github.com/event4u-app/agent-config/commit/c42dce428f0c35f01cf2e58046f62be28dc05504))
-* **ci:** use .js import extensions in the new matrix-lint modules (typecheck) ([bf79fe0](https://github.com/event4u-app/agent-config/commit/bf79fe0fd32975b2b1e7d1639bf382874f9b0c18))
-* **schema:** surgical skill-schema edits — restore original formatting ([01243ad](https://github.com/event4u-app/agent-config/commit/01243ad12cf5381a010f1e822b6f0e3bb8a32268))
-* **rules:** P4 Batch B stub consistency — routes_to + fire-time fix-now boundary ([97bed1c](https://github.com/event4u-app/agent-config/commit/97bed1c1dedc0687a9349381949094f850da8e1f))
-* **linear-digest:** drop stale strip_sections for context-hygiene after Batch B migration ([0e705c1](https://github.com/event4u-app/agent-config/commit/0e705c1316a5cfb2e76ca5e0cd958fa95757463c))
-* **tests:** run bench_parity_count tests under vitest (CI runner), not node:test ([5076a68](https://github.com/event4u-app/agent-config/commit/5076a68353f789d35dc2f236090056aa1a958017))
-* **ci:** team status description under the 200-char linter cap ([800d2f4](https://github.com/event4u-app/agent-config/commit/800d2f49fdbd980bf58333f3a80bebe0760768bb))
-* **team-doctor:** expiry-aware auth signal + namespace-resistant plugin identity + gate WARN ([7698386](https://github.com/event4u-app/agent-config/commit/76983863d0a164e20ad2a588fb2e6b8517f00622))
-
-### Documentation
-
-* **roadmap:** mark skill-quality-gates Phases 1-3 done ([b0c2d43](https://github.com/event4u-app/agent-config/commit/b0c2d43b5a409c69a991191b478c8af28e58a463))
-* **changelog:** breaking-change entry for the scoped consumer default (sync/re-install + one-time KV-prefix rebuild) ([2520859](https://github.com/event4u-app/agent-config/commit/2520859aa3e1842658392596e892b82b16f2b6eb))
-* **roadmaps:** add and archive road-to-batch-b-stub-consistency ([60bf22c](https://github.com/event4u-app/agent-config/commit/60bf22cbbfffdf60e431c147bb5ec2367d2b1fa1))
-* **team:** quota clarity, honest wording, pack move to meta, envelope contract ([6be986e](https://github.com/event4u-app/agent-config/commit/6be986e3ed500d3165a7adec3525203a0fd5b76e))
-* **bench:** cross-model-parity-count claim + benchmark section ([5ff1a4c](https://github.com/event4u-app/agent-config/commit/5ff1a4c9f90344523e8977639296e18128674abc))
-
-### Refactoring
-
-* **rules:** P4 Batch B part 2 — domain-adoption-policy, minimal-safe-diff, context-hygiene thinned; backlink report + grandfather shrink ([c6eb79c](https://github.com/event4u-app/agent-config/commit/c6eb79cb7383a78e3b48bc46bef4ade01b7d9106))
-* **rules:** P4 Batch B part 1 — active-remediation, artifact-drafting-protocol, framework-neutrality, design-fidelity thinned to stubs ([e382bec](https://github.com/event4u-app/agent-config/commit/e382bec6cc04470e19534c7521a8271c52e0f79e))
-
-### Tests
-
-* **workspace_inbox:** refresh skill-hint snapshot for docker Known-pitfalls section ([7003101](https://github.com/event4u-app/agent-config/commit/70031011264cc6bcafc8b68a33f8b6cfafa1c7e2))
-* **review:** review-mechanics eval fixtures ([3a74f94](https://github.com/event4u-app/agent-config/commit/3a74f94e729fe6c5f0476be303e11b1d91a80027))
+# Era: pre-9.2.0 — archived
 
-### Build
-
-* **skill-quality:** wire the two new lints into ci-fast ([c9e85d8](https://github.com/event4u-app/agent-config/commit/c9e85d80f31266f901189f2ee3bdc337ce030551))
-
-### Chores
-
-* **roadmap:** tool-pitfalls plate complete — archived, index updated ([b93774c](https://github.com/event4u-app/agent-config/commit/b93774c8d130a2e0f6663b0aba24d88e679924a1))
-* refresh condensation hashes ([8a0d974](https://github.com/event4u-app/agent-config/commit/8a0d97437f6257399da5f79cb218671154aa97b4))
-* **roadmap:** document-skills plate complete — archived, index updated ([d96a11e](https://github.com/event4u-app/agent-config/commit/d96a11e5d69bf21c7d6d6d2148b231fb56449a7e))
-* **docs:** skill counts 272 → 274, meta pack regen, condensation hashes ([4115d3a](https://github.com/event4u-app/agent-config/commit/4115d3a08041086251926303ee9e3d6c39437cd8))
-* **generated:** regenerate proof.md + CAPABILITIES.yaml after +2 skills (272→274) ([51eac3e](https://github.com/event4u-app/agent-config/commit/51eac3eb885956ac4ded6f874d4a27645b1c6dc9))
-* **roadmap:** prose-authenticity U1-U5 complete; U6 blocked on decision-revisit-gate ([ebff2d8](https://github.com/event4u-app/agent-config/commit/ebff2d815630ea92a69bd341a21f73aa39fc66ac))
-* **roadmap:** prelaunch-diagnostics plate complete — archived, index updated ([6ca449d](https://github.com/event4u-app/agent-config/commit/6ca449de2e3b4c8c73ef36ca509a9956d57ac087))
-* **roadmap:** skill-quality-gates plate complete — Phase 4 flipped, archived, index updated ([2d89dd3](https://github.com/event4u-app/agent-config/commit/2d89dd3e2c514f3add37176ee86e84e2b218fbb4))
-* **sync:** regenerate meta domain README after condense-memory description update ([d6f8557](https://github.com/event4u-app/agent-config/commit/d6f85574627e124b6b9af8e2b2e3cc2b2731a122))
-* **condense:** re-mark upstream-contribute after skill-writing dep-fold ([6e71ef9](https://github.com/event4u-app/agent-config/commit/6e71ef95daf695b23de2da3fd30c4f840ca1a2b7))
-* **roadmap:** authoring-rigor U2+U4 closed ([b744092](https://github.com/event4u-app/agent-config/commit/b74409267a40e458805a701cc44678bf679041df))
-* **sync:** dist twin of code-review evals after U2 golden pair ([10d67ba](https://github.com/event4u-app/agent-config/commit/10d67ba755ef75ecc2520e2ff242d00a9c8e10fa))
-* **roadmap:** reliability-measurement plate complete — archived, index updated ([5662e80](https://github.com/event4u-app/agent-config/commit/5662e80753a620be34c95680e1d7e4cec56dd0d4))
-* **roadmap:** reliability-measurement U1/U1a/U3 closed ([dc16eaa](https://github.com/event4u-app/agent-config/commit/dc16eaa6e1d19c105b36001f09979e8a08cb8466))
-* **roadmap:** request-scoped-rule-load Phase-1 human gate closed - only trigger-gated Phase-4 park remains ([0f46997](https://github.com/event4u-app/agent-config/commit/0f46997c9829a6d9c3f265ed4d744c3588e7f7be))
-* **counts:** guideline badge + table 91 -> 98 after Batch B guideline homes ([ecad776](https://github.com/event4u-app/agent-config/commit/ecad7764848d8a0309bae2a56c11b3aafd048efc))
-* **roadmap:** complete + archive review-mechanics; refresh hashes ([9ede176](https://github.com/event4u-app/agent-config/commit/9ede1767c451446ec485198da25247821d56b032))
-* **roadmap:** request-scoped-rule-load Phase 5 closed — Batch B done, Batch C skipped-by-tradeoff, backlink report current ([37e73f8](https://github.com/event4u-app/agent-config/commit/37e73f89cd30dc7127293de51cc583ed0118d7b1))
-* **roadmap:** truth-sync the inherited golden-set blocker in request-scoped-rule-load ([2e13966](https://github.com/event4u-app/agent-config/commit/2e1396657d2e9570bb6eebbb02f51413f1b5fad2))
-* **roadmap:** park road-to-token-saving in later/ — all open work operator-gated, judge blocker resolved negative ([51a56bd](https://github.com/event4u-app/agent-config/commit/51a56bdd0fe6b6203bde83792892a88f25a5c8c4))
-* **proof:** regenerate docs/proof.md after claims-ledger update ([63421da](https://github.com/event4u-app/agent-config/commit/63421da76566e2ca38e1f72025c68e49646ec404))
-* **bench:** codex-host lift replication HONEST NULL — discipline_profile default stays; measurement-unblock roadmap complete + archived ([5e11ce0](https://github.com/event4u-app/agent-config/commit/5e11ce09f7846f4875e032db1c6dc236f9a229cb))
-* **pack:** register security-maturity-assessment in engineering-base manifest ([ee89252](https://github.com/event4u-app/agent-config/commit/ee89252794e4979a002de7e2dd682ee90c75d533))
-* sync generated count surfaces + dependent command hashes ([44e064a](https://github.com/event4u-app/agent-config/commit/44e064abecd90d924432fcef958477964ed13fa7))
-* **sync:** meta pack manifest + index + envelope dist projection ([5473ca0](https://github.com/event4u-app/agent-config/commit/5473ca0e9e6446bfff475db8668ff334b9f2295d))
-* **roadmaps:** feedback-8.11-5 executed and archived; team-mode Phases 3+4 complete ([487cbe6](https://github.com/event4u-app/agent-config/commit/487cbe61a2fa52e20c21db66aa9b6a4650aac60b))
-* **roadmap:** regenerate progress dashboard ([d085f71](https://github.com/event4u-app/agent-config/commit/d085f716c25c06fa2edf6561c0c66ba9204acdc9))
-* **roadmap:** archive completed ecosystem-harvest bug-security-rigor ([25982c5](https://github.com/event4u-app/agent-config/commit/25982c55aefd3a8c2b8715f2ac05112e52849bb4))
-* **roadmap:** measurement-unblock Phase 3 complete (build decision + parity pass + armed gate) ([9c0f051](https://github.com/event4u-app/agent-config/commit/9c0f051c91b6a712884fb1408e41c339fc42462f))
-
-Tests: 7716 (+158 since 8.13.0)
-
-## [8.13.0](https://github.com/event4u-app/agent-config/compare/8.12.0...8.13.0) (2026-07-12)
-
-### Features
-
-* **backlinks:** orphan-stub correctness check + fan-out info + gated hard-gate list ([fe88ff5](https://github.com/event4u-app/agent-config/commit/fe88ff5c42bd08338c0ab9c83f3e1fdf0f6f7d1c))
-* **team-doctor:** 'team' health check + suppressible setup hint ([22a5c14](https://github.com/event4u-app/agent-config/commit/22a5c141ddaa47994f7d9c150dafa36b0fcb38a8))
-* **team-commands:** /team family — thin fail-closed delegations under ai_team governance ([958c491](https://github.com/event4u-app/agent-config/commit/958c4910bf2276449a99ef2462e78caa718148a5))
-* **team-config:** ai_team contract — default-off block, fail-closed loader, shared quota ([f45c988](https://github.com/event4u-app/agent-config/commit/f45c98860a63d2c8c572a9e121ecaf05d4c34aa9))
-* **pr-create:** harden the freshness gate — regenerate-on-conflict + update freshness ([83104e0](https://github.com/event4u-app/agent-config/commit/83104e0a3a8666d8eb47044c9b9e028a1e60c913))
-
-### Bug Fixes
-
-* **rules:** restore the concrete verification-tool mapping in the improve-before-implement stub ([a54d89f](https://github.com/event4u-app/agent-config/commit/a54d89f852120e639f25aa059e33baf672255f66))
-
-### Documentation
-
-* **round4:** strict:false operating conditions + Batch B/C stub-necessity pre-questions ([7961ba4](https://github.com/event4u-app/agent-config/commit/7961ba4dda15d33fe4a8be6a92d4e71b7a4bedb6))
-* **team:** getting-started section — depth complement to the council, no value claims ([6c64fc3](https://github.com/event4u-app/agent-config/commit/6c64fc3acade96c3d1eff3c610677be5a852f18e))
-* **roadmap:** measurement-unblock Phase 2 — codex auth+smoke verified, paired run in flight ([489bdc1](https://github.com/event4u-app/agent-config/commit/489bdc168565c6b27eceeaca8384751e089378ef))
-
-### Chores
+> All entries before `9.2.0` live in
+> [`docs/archive/CHANGELOG-pre-9.2.0.md`](docs/archive/CHANGELOG-pre-9.2.0.md).
+> The archive is read-only; git tags remain the canonical
+> source for what shipped. Splitting them out of the main file
+> keeps the active era under the 250-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
 
-* **counts:** hero badge + browse line 178 -> 183 after the 8.12.0 release merge ([ef396f5](https://github.com/event4u-app/agent-config/commit/ef396f55476ccfed53387a6fbe49201be8e312c0))
-* **counts:** featured-skills command count 178 -> 183 (update_counts anchor) ([13cb8de](https://github.com/event4u-app/agent-config/commit/13cb8de13373e66c26a21689b2a86427ee9ac043))
-* **roadmaps:** feedback-8.11-4 executed and archived; team-mode P1+P2 complete ([dd44aa6](https://github.com/event4u-app/agent-config/commit/dd44aa69fea35d95fadc00936c3ec23caaeb2c1b))
+# Era: 9.2.x — current
 
-Tests: 7558 (+49 since 8.12.0)
+> Started at `9.2.0`. Full entries live inline below.
+> The drift test caps this era at 250 lines of entry body; growth past
+> that forces a new era split (`# Era: 9.3.x`, etc.) — see
+> [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
-## [8.12.0](https://github.com/event4u-app/agent-config/compare/8.11.0...8.12.0) (2026-07-12)
+## [9.2.0](https://github.com/event4u-app/agent-config/compare/9.1.0...9.2.0) (2026-07-14)
 
 ### Features
 
-* **rules:** P4 migration Batch A — 9 rule bodies to their existing homes (−51.7% stub bytes) ([94dc19c](https://github.com/event4u-app/agent-config/commit/94dc19cac62ff21449afd5a373c1363ee3d6215c))
-* **explain-run:** plain-language Summary section ([257d8fc](https://github.com/event4u-app/agent-config/commit/257d8fc4d2ef69e9696f9a143d653a1a0a771e2c))
-* **complexity:** report v2 — proxy honesty, coupling metric, soft-ratchet baseline ([8328bae](https://github.com/event4u-app/agent-config/commit/8328bae0b791da4215fd704a90734123df0f6b13))
-* **bench:** live retrieval benchmark executed — decisive PASS ([25d9f03](https://github.com/event4u-app/agent-config/commit/25d9f03756e33870fbc507bc1bc964c5b6c83403))
-* **bench:** persona-placebo benchmark — executed, HONEST NULL (identity adds nothing) ([000c3e7](https://github.com/event4u-app/agent-config/commit/000c3e77081d7aa39e3d617f98ba67ef27121218))
-* **reports:** complexity report, explain-run v0, rule-backlinks — all report-only with kill criteria ([e718f13](https://github.com/event4u-app/agent-config/commit/e718f1396562e0cb94fab344b75332a73a34ac35))
-* **knowledge:** per-card sensitivity classes, promotion gate, revocation trail (ADR-121) ([a14b1ad](https://github.com/event4u-app/agent-config/commit/a14b1ad54b750d86ff288cd96ad9e76fe58fcdc5))
-* **consumer-matrix:** live hook-lifecycle leg + dist import-graph completeness ([1f1d9e1](https://github.com/event4u-app/agent-config/commit/1f1d9e1f8f8186de51071f47ca20ed649fad01f3))
-* **bench:** length-neutral judge rerun — executed, SECOND INCONCLUSIVE (gate closed-by-diagnosis) ([66ba0a3](https://github.com/event4u-app/agent-config/commit/66ba0a3e7a995fb8f7db1b795d33682328dc8596))
-* **council:** restate pass — the last wiring item (pre-round-1, transport-safe) ([4df6069](https://github.com/event4u-app/agent-config/commit/4df6069e127a0467f5a86aea57ea4c90929746a1))
-* **council:** stance-line repair call in consult (bounded, transport-gated) ([91fd10e](https://github.com/event4u-app/agent-config/commit/91fd10e25429d7d35f460ba8560c76565007b0c6))
-* **council:** debate-gate repair dispatch in run_debate (bounded, policy-gated) ([e7f6380](https://github.com/event4u-app/agent-config/commit/e7f6380639835d61c72b4b89cb79d77a5c90cb9c))
+* **rules:** cross-source-consistency — detect discrepancies, ask before guessing ([63b8049](https://github.com/event4u-app/agent-config/commit/63b804981e70045f138af4bd4a5546b62b135d24))
+* **settings:** add consistency.cross_source toggle (default on) ([2f41bbb](https://github.com/event4u-app/agent-config/commit/2f41bbbf52737f12401eb7ccfed104d3b4a9b4a6))
+* **settings:** opt-in subagents.adversarial_council + verify-budget escalation ([fa68dbc](https://github.com/event4u-app/agent-config/commit/fa68dbc514a6cc2def90f7f4b8b031e5c872747f))
+* **subagent:** Mode 9 adversarial-verification-council + skeptic prompt ([26501a1](https://github.com/event4u-app/agent-config/commit/26501a18a1ab53d3eb54a06230086e0c4508bfee))
+* **subagent:** adversarial-findings schema + deterministic reconciliation core ([12c64f2](https://github.com/event4u-app/agent-config/commit/12c64f26bcc92d4472935badc41b64fe563f98b2))
 
 ### Bug Fixes
 
-* **ci:** roadmap-ci-steps-mechanics joins the task-invocation skip class ([659d775](https://github.com/event4u-app/agent-config/commit/659d775099bd67168beac8a5742a4efbe773b690))
-* **ci:** skill description under the 200-char linter cap + modernize a migrated legacy path ([893ce69](https://github.com/event4u-app/agent-config/commit/893ce6922df759ac2432b221e28951a292233a47))
-* **proof:** move the honest-null entry into the build_proof generator ([5c1a12c](https://github.com/event4u-app/agent-config/commit/5c1a12c152d35fd320e40f0173b27f842fb39903))
-* **ci:** regenerate proof.md post-merge + de-literalize example imports ([6ff330d](https://github.com/event4u-app/agent-config/commit/6ff330d5a84c4682fae63eb2331ec3f645473cb4))
-* **claims:** thin-projection honesty + pre-register the council-vs-solo baseline ([6aee669](https://github.com/event4u-app/agent-config/commit/6aee669e311261121f582793e47698e029b0c8ae))
-* **identity:** resolve the placeholder git identity and guard against recurrence ([b17a801](https://github.com/event4u-app/agent-config/commit/b17a801dd16ddda9c3bcfd6b269dc65aff5a5e41))
-* **counts:** regenerate CAPABILITIES.yaml and close the structured-surface drift gap ([55aafb5](https://github.com/event4u-app/agent-config/commit/55aafb58b7f0e775b73a100d0b83f55b13defea0))
+* **proof:** regenerate docs/proof.md after the pre-registered claim ([a24fb54](https://github.com/event4u-app/agent-config/commit/a24fb54574379aaf90061beee2df4d21e3d55a9a))
 
 ### Documentation
 
-* **posture:** knowledge scaling reality + local_auto_run as deliberate design ([ad9f43b](https://github.com/event4u-app/agent-config/commit/ad9f43baaa52cea533f6e1fd91ca012d95d35e9e))
-* **maintainers:** one-page system map + prepared branch protection ([efe63d0](https://github.com/event4u-app/agent-config/commit/efe63d006ff7ef97b1f4e201c29e53824ef3af95))
-* **claims:** pre-register the utilization-window decision criteria ([4667adf](https://github.com/event4u-app/agent-config/commit/4667adf085af9d2e178932b0a3fc9e2d674d6d2c))
-* **roadmap:** complete + archive road-to-opt-retrieval-and-memory ([cfc8657](https://github.com/event4u-app/agent-config/commit/cfc86578b7033945d227db80d98821aef33b8917))
-* **roadmap:** complete + archive road-to-opt-council-deliberation ([8777a8e](https://github.com/event4u-app/agent-config/commit/8777a8ebf90c2fc32362cfcbe1e58f8bee8f56d7))
-* **proof:** persona-identity-placebo-null — backed claim + honest-null story ([0d0de13](https://github.com/event4u-app/agent-config/commit/0d0de1387b6cd61a0165ec26a1db695172dcc2bd))
-* **rules:** rule-body migration inventory + P4 batches into request-scoped-rule-load ([c5abc40](https://github.com/event4u-app/agent-config/commit/c5abc40e4edc09d92681afbeae5f837f63784e29))
-* **bench:** record the closed-by-diagnosis disposition ([e02f7d7](https://github.com/event4u-app/agent-config/commit/e02f7d765d1aa2d61ae7bd1e879b27a1711fe595))
-* **roadmap:** flip the restate step + the confirmed harness prerequisite ([6415b3e](https://github.com/event4u-app/agent-config/commit/6415b3e672a659e8453159ca7e421d2ce7fdb9da))
-* **roadmap:** flip the stance-repair + chairman-ADR steps ([c1278a0](https://github.com/event4u-app/agent-config/commit/c1278a092027bb1659ba37d3281b9692a2c4066e))
-* **adr:** ADR-120 — council chairman mode supersedes always-host synthesis ([9e593f4](https://github.com/event4u-app/agent-config/commit/9e593f42bcd5ff844332eb7eca4fbb545be7d8fd))
-* **roadmap:** flip the debate-gate repair-dispatch step ([d4bba6b](https://github.com/event4u-app/agent-config/commit/d4bba6b31c1ceca01480f66ea80174a27887ab88))
+* **adr:** ADR-122 + pre-registered finding-coverage claim + eval design ([0123cd2](https://github.com/event4u-app/agent-config/commit/0123cd298d0587fd1eb98f82c7e40f41e912ee05))
 
 ### Chores
 
-* **sync:** propagate the shortened skill description into the generated domain README ([ec2a931](https://github.com/event4u-app/agent-config/commit/ec2a931e76b148c0c653dad3353f6f11590edf33))
-* **roadmaps:** feedback-8.11-2 disposition executed and archived ([0037d52](https://github.com/event4u-app/agent-config/commit/0037d521c62699d3757b5e975dafbec54beab1b4))
-* **condense:** record knowledge-card template condensation hash ([7ce68cc](https://github.com/event4u-app/agent-config/commit/7ce68cc38d976a4e10666bdf006db4059d788305))
-* **roadmaps:** feedback-8.11 disposition executed and archived ([960179f](https://github.com/event4u-app/agent-config/commit/960179fa08e343a8e1bb1856bce76e2025abe8d3))
+* regenerate derived artefacts for the new rule ([5268766](https://github.com/event4u-app/agent-config/commit/5268766dd6aca34efbac77660ecf3fa9d1553814))
 
-Tests: 7509 (+130 since 8.11.0)
+Tests: 7764 (+27 since 9.1.0)
 
 # Era: pre-4.0.0 — archived
 

package/MIGRATION.md

@@ -16,6 +16,20 @@ firing (now from `settings.json`), skills/commands stop listing twice, and
 `claude-plugin` no longer reporting a duplicate surface). Augment CLI and
 Copilot CLI plugins are unaffected.
 
+# Migrating to 9.0
+
+> Consumer rule projection is **scoped by default** in 9.0. Full
+> breaking-change detail: [`CHANGELOG.md` § 9.0.0](CHANGELOG.md).
+
+Fresh installs now ship `projection.rule_workspaces` pre-filled with every
+consumer workspace, so the 16 exclusively-maintainer specification rules no
+longer arrive: **103 → 88 rules** per install. All domain safety floors,
+domain rules, and kernel rules keep shipping.
+
+Existing installs are unchanged until you run `agent-config sync` /
+re-install (settings sync preserves your current value). To stay on the
+legacy every-rule behaviour, set `projection.rule_workspaces: []`.
+
 # Migrating to 6.0
 
 > Upgrading an existing install to the **6.0 experience-first** layout.

package/README.md

@@ -4,7 +4,7 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-274-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-104-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-183-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-98-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-275-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-105-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-184-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-100-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 > **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
 
@@ -178,7 +178,7 @@ npx -y @event4u/agent-config init
 
 **Verify hook coverage:** `npx @event4u/agent-config hooks:status` prints the per-platform matrix (`--strict` for CI, `--format json` for tooling).
 
-> **Scope (v2.5+):** `init` writes **global** only — `~/.event4u/agent-config/`, `~/.claude/`, `~/.cursor/`, …. The project tree gets `agents/overrides/` + `agents/.event4u-bridge.yml`. `--project` is maintainer-only behind `AGENT_CONFIG_DEV_MODE=1` ([ADR-020](docs/decisions/ADR-020-global-only-consumer-scope.md), [dev-mode](docs/maintainers/dev-mode.md)).
+> **Scope (v2.5+):** `init` writes **global** only — `~/.event4u/agent-config/`, `~/.claude/`, `~/.cursor/`, …. The project tree gets `agents/overrides/` only (the bridge marker was retired — ADR-020 amendment 2026-07-13; the global root resolves from `~/.event4u/agent-config`). `--project` is maintainer-only behind `AGENT_CONFIG_DEV_MODE=1` ([ADR-020](docs/decisions/ADR-020-global-only-consumer-scope.md), [dev-mode](docs/maintainers/dev-mode.md)).
 
 Migrating from a v1.x install? `npx @event4u/agent-config migrate` — full notes in [`docs/migration/v1-to-v2.md`](docs/migration/v1-to-v2.md).
 

package/dist/agent-src/commands/explain-run.md

@@ -0,0 +1,88 @@
+---
+model_tier: inherit
+name: explain-run
+pack: meta
+tier: 2
+visibility: internal
+description: "Read-only 'why did that happen' run report — resolved rule set, rules fired, artefact engagement, subagent dispatches, hook/loop/freshness state — even when the user just says 'explain the last run'."
+argument-hint: "[--task <id>] [--since <ref>]"
+skills: [agent-docs-writing]
+suggestion:
+  eligible: false
+  rationale: "Package-internal maintainer diagnostic — only the event4u/agent-config repo runs this."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# explain-run
+
+Thin runner for the read-only explainability engine `explain_run`
+(`src/scripts/explain_run.ts`). Renders one Markdown
+report answering **"why did the agent do that this run?"** entirely from
+artefacts other parts of the suite already write — no new state, no capture,
+no daemon.
+
+The report covers: the resolved rule set (kernel vs trigger-routed, from
+`dist/router.json`), rules the audit log actually observed firing, artefact
+engagement (consulted vs applied), subagent dispatches (mode / tiers / token
+deltas), a hook / loop / freshness state snapshot, and a parked list of
+"why" questions this v0 cannot answer yet (surfaced, never silently omitted).
+
+## Instructions
+
+### 1. Resolve the window
+
+Both arguments are optional and narrow the report:
+
+- `--task <id>` — restrict to one task id seen in the audit log.
+- `--since <ref>` — an ISO-8601 timestamp / date cutoff (e.g. `2026-07-01`).
+
+With neither, the engine reports over all available artefacts. Pass through
+exactly what the user gave — do not invent a task id or a date.
+
+### 2. Run the engine
+
+```bash
+./scripts-run src/scripts/explain_run [--task <id>] [--since <ISO-8601>]
+```
+
+Exit codes:
+
+- `0` → report rendered to stdout; continue to step 3.
+- `2` → bad argument (unknown flag or unparsable `--since`); surface stderr
+  and stop.
+
+The engine prints an honest `no data — <source> absent or empty` for any
+section whose source file is missing — that is expected output, not an error.
+
+### 3. Surface the report
+
+Show the engine's Markdown output. Do not re-summarize or re-order it — the
+report already opens with a plain-language `## Summary`. If the user wants the
+report written to a file, add `--output <path>` and confirm the write.
+
+## Rules
+
+- **Read-only** — this command only reads on-disk artefacts. It never edits,
+  captures, or writes state (aside from an explicit `--output` file).
+- **Do NOT commit or push** — the working tree is left to the user.
+- **Never edit generated trees** — per [`source-of-truth`](../rules/source-of-truth.md),
+  the engine lives in `src/scripts/`; never hand-edit `dist/agent-src/` or any
+  tool projection.
+- **Honest nulls, not invented rows** — the engine's `no data` lines are
+  correct output; do not fabricate rule firings or dispatches to fill them.
+
+## When NOT to use
+
+- To *change* behaviour — this only explains it. Rule / routing edits go
+  through the normal source-of-truth flow.
+- Kill criterion: the engine self-documents a delete-if-unused-after-3-releases
+  criterion; if this command sees zero use, retire it with the engine.
+
+## See also
+
+- `explain_run` (`src/scripts/explain_run.ts`) — the read-only engine this wraps.
+- `/agent-status` — live session snapshot (this is the retrospective, artefact-sourced view).
+- [`source-of-truth`](../rules/source-of-truth.md) — edit `src/`, never generated trees.

package/dist/agent-src/commands/implement-ticket.md

@@ -131,6 +131,8 @@ On exit `1`, look at the first line after `[halt] outcome=… step=…`:
   options verbatim, wait for the user, write their answer back onto the
   matching state slice, then re-run the engine. Never guess.
 
+A **cross-source discrepancy** discovered while planning or applying — ticket text contradicting an attached mockup, a spec silent on a clearly-needed behavior, or a spec-vs-codebase conflict (per [`cross-source-consistency`](../rules/cross-source-consistency.md), gated by `consistency.cross_source`) — is a blocking user question, not a silent resolution: surface it as the `questions[0]` halt and wait, never expand scope on a plausible inference.
+
 ### 4. Directive mapping
 
 When `questions[0]` is `@agent-directive: <verb> [key=value …]`, dispatch:

package/dist/agent-src/commands/pr/create/description-only.md

@@ -95,34 +95,164 @@ That's 6 round-trips for what should be 2.
 
 ### 4. Build the PR body
 
+#### 4.0 Resolve the detail level
+
+Read `commands.create_pr.detail_level` from `.agent-settings.yml` (default
+`min` when unset). This tier governs **only the explanatory depth of the
+Description section** — never which template sections exist, and never
+whether a critical callout appears (see 4.1 critical-info-always).
+
+| Tier | Description section content |
+|---|---|
+| `min` (default) | Title-level summary in 2-3 sentences: *what* changed, *why*, and the user/system impact. No per-file walk, no restating commit subjects, no "how to test". |
+| `med` | `min` + grouped logical changes as 3-5 bullets (by concern, not by file) + a one-line tests note (added / none / coverage). |
+| `max` | `med` + how-to-test steps + edge cases / trade-offs + one "reviewer guidance" line (what to focus on). ≈ the legacy output. |
+
+`min` is the default because this is a token-cost optimization: a shorter
+description costs fewer output tokens on every PR. Keep `min` genuinely
+minimal — but never at the expense of the critical-info block below.
+
+#### 4.1 Critical-info-always — tier-independent MUST
+
+```
+CRITICAL INFORMATION APPEARS AT EVERY TIER, INCLUDING min.
+THE TIER GOVERNS EXPLANATORY DEPTH, NEVER WHETHER A CRITICAL CALLOUT APPEARS.
+DROPPING A BREAKING-CHANGE / MIGRATION / SECURITY / ROLLBACK CALLOUT AT min
+IS A P0 DEFECT, NOT A TOKEN SAVING.
+```
+
+If the diff shows any of the following, a one-line callout for it is included
+in the Description **regardless of `detail_level`** (grounded in the diff, not
+guessed):
+
+- **Breaking change** — API contract change (new/removed/renamed field, changed
+  endpoint or response shape), CLI-arg change, changed env var, or a renamed
+  route the frontend depends on. Prefix `⚠️ Breaking:`.
+- **Migration required** — DB migration, config migration, or a deployment step.
+  Prefix `Migration:`.
+- **Security implication** — new permission/scope, auth change, or data-exposure
+  surface. Prefix `🔒 Security:`.
+- **Non-trivial rollback** — when reverting is not a plain `git revert`. Prefix
+  `Rollback:`.
+
+None present → omit the block entirely (do not emit empty "No breaking
+changes" filler at `min`).
+
+#### 4.2 Fill the template sections
+
 **ALWAYS** use the PR template (`.github/pull_request_template.md`). Fill in its sections:
 
 - **Jira badge**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
-- **Description**: Summarize the changes in 2-5 sentences. Explain *what* changed and *why*.
-  Use the Jira ticket description and commit messages as input.
+- **Description**: Write it to the resolved tier (4.0) with the critical-info
+  block (4.1) always present. Use the Jira ticket description + commit messages
+  as input.
 - **Type of change**: Check the appropriate checkbox(es) based on the changes.
 - **Checklist**: Leave as-is (the developer fills this in).
 - **Links**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
-- **Screenshots**: Leave as `...` unless the user provides screenshots.
+- **Screenshots**: Handled by Step 4.4 (default: leave the placeholder / `...`).
 
-If no PR template exists, use this structure:
+If no PR template exists, use this structure — including only the sections the
+tier calls for (at `min`, the `## Changes` bullets collapse to the 2-3 sentence
+summary and `## How to test` is omitted):
 
 ```markdown
 ## Jira
 [{TICKET-ID}]({JIRA_BASE_URL}/browse/{TICKET-ID})
 
-## Changes
-- Bullet list of what was changed and why
+## Description
+- 2-3 sentence what/why/impact (min) — grouped bullets (med/max)
+- Critical-info callouts (any tier, only if present)
 
 ### Migrations
 - List new/changed migrations (if any)
 
 ### Tests
-- List new/changed tests (if any)
+- List new/changed tests (med/max)
 
 ## How to test
-- Steps to verify the changes
+- Steps to verify the changes (max)
+```
+
+#### 4.3 API response examples (evidence-grounded)
+
+Read `commands.create_pr.api_examples` (default `true`). When `true` **and**
+the diff touches an API endpoint, add a fenced request/response example under
+the Description.
+
+**Detect an API-endpoint change** (fail-open — no false enrichment when
+ambiguous): a changed file matches `commands.create_pr.api_paths` (if set), or
+the light heuristic — a route file (`routes/`, `**/api/**`, `*Controller*`,
+resource/serializer classes) whose diff adds or changes an endpoint or its
+request/response shape. No confident match → skip silently.
+
+**Ground the example in a real source — never invent one:**
+
+```
+NEVER FABRICATE A JSON EXAMPLE. AN INVENTED CONTRACT MISLEADS REVIEWERS
+AND IS WORSE THAN NONE. EMIT A JSON BLOCK ONLY FROM A REAL SOURCE.
+```
+
+Grounding sources, in priority order: the response DTO / API-resource /
+serializer class in the diff · an OpenAPI/JSON-schema in the repo · a test
+fixture or assertion exercising the endpoint · the actual output of a probe you
+ran this session (`curl` / test client). If **none** exists, emit a one-line
+pointer instead — `API contract changed — see \`<file>\`` — never a guessed
+example. This is [`senior-engineering-discipline`](../rules/senior-engineering-discipline.md)
+(never invent an API) applied to the description surface.
+
+Format when grounded:
+
+~~~markdown
+### API example (`POST /api/...`)
+Request:
+```json
+{ ...grounded... }
+```
+Response `201`:
+```json
+{ ...grounded... }
 ```
+~~~
+
+`api_examples: false` → skip this step entirely.
+
+#### 4.4 Screenshots for frontend changes (capability-gated)
+
+Read `commands.create_pr.screenshots` (default `false`). `false` → skip this
+step entirely; leave the template Screenshots placeholder as-is.
+
+When `true`, this is a **capability-gated contract, never a runtime
+orchestrator** — the package ships instructions, the host provides the tools:
+
+1. **Frontend-change gate.** Only proceed if the diff touches a frontend
+   surface — a changed file matches `commands.create_pr.ui_paths` (if set), or
+   the light heuristic (`.vue` / `.tsx` / `.jsx` / `.blade.php` / `.svelte`,
+   component/view/page/template dirs, CSS/Tailwind). No match → skip silently.
+2. **Capability gate — explicit, never silent.** Screenshots need host
+   browser/preview tooling (a Playwright/browser MCP **and** a reachable dev-server
+   or preview URL). There is no capability flag to read, so probe cheaply. If the
+   tooling or a running preview is **absent**:
+   - Leave the template Screenshots placeholder untouched, **and**
+   - Emit ONE line in the chat reply: `Screenshots requested (screenshots: true)
+     but no browser/preview tooling was reachable — skipped.`
+   - **Never** fail, block, or delay PR creation over this.
+3. **Capture (when capable).** Capture the current (head) state of each changed
+   surface. Before/after (base vs head) with changed-region highlighting is
+   **best-effort only** — a base checkout mid-PR is fragile and expensive;
+   attempt it only if cheap and safe, otherwise after-only. One screenshot per
+   changed surface, each with a one-line caption.
+4. **Embedding — honest limits.** The `github-api pulls` write path cannot
+   upload image bytes and GitHub markdown does not render `data:` URIs, so an
+   agent cannot inline captured bytes into the body via the API. Use, in order:
+   (a) a host image-upload capability if one exists (embed the returned URL);
+   (b) otherwise save the screenshots to a local path, reference them in the
+   Screenshots section, and tell the user to drag them into the PR in the
+   GitHub UI. **Never claim an embed that did not happen**
+   ([`direct-answers`](../rules/direct-answers.md) Iron Law 2).
+
+Limitations (state them so expectations are set): default off; depends on host
+browser tooling + a running preview; before/after + highlighting is best-effort;
+byte-embedding into the PR body is not possible via the API.
 
 ### 5. Present as copyable block