@event4u/agent-config 8.13.0 → 9.0.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": "8.13.0",
+    "version": "9.0.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -48,6 +48,26 @@ 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
@@ -1024,6 +1044,122 @@ our recommendation order, not its support status.
 > 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))
+
+### 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

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-271-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-91-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-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/)
 
 > **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.
 

package/dist/agent-src/commands/agent-handoff.md

@@ -9,6 +9,7 @@ tier: 0
 visibility: visible
 skills: [agent-docs-writing]
 description: Generate a context summary for continuing work in a fresh chat. Replaces the session system.
+argument-hint: "[with tasks]"
 suggestion:
   eligible: true
   trigger_description: "user asks for an agent handoff, fresh-chat summary, or context-summary to paste into a new chat"
@@ -84,6 +85,40 @@ Roadmap: {roadmap file if active, or "none"}
 lossy re-summarization of the user's own constraints is the exact failure this
 template prevents. Everything else (Done / Key decisions) stays concise.
 
+### 2b. File-artifact mode — `HANDOFF.md` (optional, host-neutral)
+
+On `/agent-handoff --file` (or when a workflow skill's phase boundary asks
+for a standing handoff), ALSO write the contract to
+`agents/runtime/state/HANDOFF.md` (gitignored runtime state — plain
+Markdown, no host API). Required fields, in order:
+
+```
+# HANDOFF
+## Mode
+{current workflow mode/phase, e.g. Implement (TDD)}
+## Contract received
+{what the previous phase handed over}
+## Contract owed
+{what the current phase must produce before yielding}
+## Decisions
+- {decisions taken, with one-line rationale}
+## Open questions
+- {unresolved items the next session must not silently drop}
+## Next command
+{the single command or step to run first on resume}
+```
+
+**Resume rule:** a workflow skill's step 0 checks for this file and resumes
+from its contract (mode-inference table) instead of re-deriving state; a
+long phase refreshes the file before yielding. Validated by
+`lint_handoffs.ts` when present — a missing required field is red.
+
+**Critical-planning-file safety protocol** (applies to HANDOFF.md and agent
+roadmap edits): read the current file FIRST; take a timestamped backup copy
+next to it (`HANDOFF.md.<ts>.bak`) before overwrite; duplicate-check before
+appending (never double-append a section); preserve the section structure;
+post-verify the write by re-reading the required fields.
+
 ### 3. Present to user
 
 Show the handoff prompt in a fenced code block and say:

package/dist/agent-src/commands/agents/init.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: agents
 sub: init
 description: Initialize the agent layer for a consumer project — creates AGENTS.md and .github/copilot-instructions.md from package templates, auto-detects stack, never leaks other projects' identifiers.
+argument-hint: "[--force]"
 skills: [copilot-config, copilot-agents-optimization, agent-docs-writing, agents-md-thin-root]
 suggestion:
   eligible: false

package/dist/agent-src/commands/agents/optimize.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: agents
 sub: optimize
 description: Refactor AGENTS.md to the Thin-Root contract (caps, pointer ratio, capability bullets, emergency-triage) and propagate to tool stubs. Suggest only, never auto-apply.
+argument-hint: "[path-to-AGENTS.md]"
 skills: [agents-md-thin-root, copilot-agents-optimization, copilot-config, agent-docs-writing]
 suggestion:
   eligible: true

package/dist/agent-src/commands/agents/user/accept.md

@@ -8,6 +8,7 @@ cluster: agents
 sub: user
 skills: [agents]
 description: Apply a buffered observation to .agent-user.md after explicit user confirmation; bumps last_updated and drops the applied observations from the buffer.
+argument-hint: "[field]"
 suggestion:
   eligible: false
   rationale: "Mutates .agent-user.md — only run from /agents user review or explicit user invocation."
@@ -20,7 +21,7 @@ packs:
 # /agents user accept
 
 Apply a buffered observation from
-[`.agent-user.observations.jsonl`](../../../../../../../docs/contracts/agent-user-schema.md#observation-buffer)
+[`.agent-user.observations.jsonl`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer)
 to `.agent-user.md` after explicit confirmation.
 
 Use when:
@@ -119,6 +120,6 @@ Do NOT commit. Do NOT auto-chain to a second field.
 
 ## See also
 
-- Schema + buffer contract: [`agent-user-schema § Observation buffer`](../../../../../../../docs/contracts/agent-user-schema.md#observation-buffer).
+- Schema + buffer contract: [`agent-user-schema § Observation buffer`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer).
 - Parent: [`/agents user`](../user.md).
 - Sibling: [`/agents user review`](review.md), [`/agents user update`](update.md).

package/dist/agent-src/commands/agents/user/init.md

@@ -8,6 +8,7 @@ cluster: agents
 sub: user
 skills: [agents]
 description: Interactive interview that creates the project-root .agent-user.md from the locked v1 schema (name, language, role, style, voice_sample).
+argument-hint: "[--force]"
 suggestion:
   eligible: false
   rationale: "User-persona bootstrap — only deliberately, never auto-suggested."
@@ -21,7 +22,7 @@ packs:
 
 Short interactive interview that creates **`.agent-user.md`** at the
 project root from the locked v1 schema in
-[`docs/contracts/agent-user-schema.md`](../../../../../../../../../../docs/contracts/agent-user-schema.md).
+[`docs/contracts/agent-user-schema.md`](../../../../../docs/contracts/agent-user-schema.md).
 
 Use when:
 
@@ -85,7 +86,7 @@ Ask in this order. Each answer drives one frontmatter field.
    ```
 
 6. **Voice sample** — required.
-   `Paste eine typische Nachricht von dir (1–3 Sätze, im normalen Schreibstil)` /
+   `Paste eine typische Nachricht von dir (1-3 Sätze, im normalen Schreibstil)` /
    `Paste one typical message of yours (1–3 sentences, your normal style)`
 
 ### 4. Privacy-floor sanity check
@@ -98,7 +99,7 @@ Before writing, scan the collected `voice_sample` and `role` for:
 - Health/legal status keywords.
 
 Hit → surface the line and ask the user to redact before proceeding.
-Per [`agent-user-schema § Explicit exclusions`](../../../../../../../../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
+Per [`agent-user-schema § Explicit exclusions`](../../../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
 
 ### 5. Render and write
 
@@ -160,5 +161,5 @@ Do NOT commit. Do NOT run any other `/agents user` sub-sub-command.
 
 ## See also
 
-- Schema: [`agent-user-schema`](../../../../../../../../../../docs/contracts/agent-user-schema.md).
+- Schema: [`agent-user-schema`](../../../../../docs/contracts/agent-user-schema.md).
 - Parent: [`/agents user`](../user.md).

package/dist/agent-src/commands/agents/user/update.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: agents
 sub: user
 description: Open .agent-user.md in the user's IDE for manual edit; validates schema and 100-line cap on save.
+argument-hint: "[--validate]"
 suggestion:
   eligible: true
   trigger_description: "edit user persona, update .agent-user.md, change nickname, change language, refresh voice sample"
@@ -61,7 +62,7 @@ When called with `--validate` (or after the user confirms "done"):
 
 1. Read `.agent-user.md`.
 2. Parse frontmatter; check every required field per
-   [`agent-user-schema § Field reference`](../../../../../../../docs/contracts/agent-user-schema.md#field-reference).
+   [`agent-user-schema § Field reference`](../../../../../docs/contracts/agent-user-schema.md#field-reference).
 3. Check file size ≤100 lines.
 4. Run the privacy-floor scan (same as `init` step 4): credentials,
    third-party PII, financial figures, health/legal status.
@@ -99,6 +100,6 @@ Do NOT commit. Do NOT chain to another `/agents user *` command.
 
 ## See also
 
-- Schema: [`agent-user-schema`](../../../../../../../docs/contracts/agent-user-schema.md).
+- Schema: [`agent-user-schema`](../../../../../docs/contracts/agent-user-schema.md).
 - Parent: [`/agents user`](../user.md).
 - Sibling: [`/agents user init`](init.md), [`/agents user show`](show.md), [`/agents user review`](review.md).

package/dist/agent-src/commands/agents/user.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: agents
 sub: user
 description: User-persona file (.agent-user.md) — interview, render, and maintain who the user is and how they want to be addressed.
+argument-hint: "[init|show|review|accept|update] [args]"
 type: orchestrator
 suggestion:
   eligible: true

package/dist/agent-src/commands/agents.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: agents
 disable-model-invocation: true
+argument-hint: "[init|optimize|audit|user] [args]"
 pack: meta
 intent: "Manage the AGENTS.md file family — init, optimize, audit, user persona"
 routes_to: [agents-init, agents-optimize, agents-audit, agents-user]

package/dist/agent-src/commands/analytics/show.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: analytics
 sub: show
 description: Render top prompts, launcher → completion rate per role, average session length, and knowledge-source usage from the local analytics log.
+argument-hint: "[--window 24h|7d|30d] [--event <name>] [--role <slug>] [--format markdown|csv|json]"
 skills: [file-editor]
 suggestion:
   eligible: true

package/dist/agent-src/commands/analytics.md

@@ -5,6 +5,7 @@ pack: analytics
 tier: 2
 visibility: internal
 description: Analytics orchestrator — routes to show, prune. Local-only workspace event log under `~/.event4u/agent-config/workspace/analytics/`.
+argument-hint: "[show|prune] [args]"
 cluster: analytics
 type: orchestrator
 auto_detect: true

package/dist/agent-src/commands/analyze/decision.md

@@ -8,6 +8,7 @@ cluster: analyze
 sub: decision
 skills: [decision-review]
 description: Audit a past architectural decision — restate what was chosen and why, compare original assumptions against reality now, produce a verdict (still valid / needs amendment / superseded).
+argument-hint: "[adr-id | path | decision-name]"
 suggestion:
   eligible: true
   trigger_description: "decision review, ADR review, did this hold up, rückblick Architektur, past decision"

package/dist/agent-src/commands/analyze/incident.md

@@ -8,6 +8,7 @@ cluster: analyze
 sub: incident
 skills: [incident-commander, root-cause-frameworks, blameless-post-mortem]
 description: Full incident flow — incident-commander coordination, then RCA via root-cause-frameworks, then a blame-free write-up via blameless-post-mortem, ending with an incident-learnings candidate.
+argument-hint: "[incident-description]"
 suggestion:
   eligible: true
   trigger_description: "production is down, active incident, Vorfall, Prod ist down, full incident analysis"

package/dist/agent-src/commands/analyze/near-miss.md

@@ -8,6 +8,7 @@ cluster: analyze
 sub: near-miss
 skills: [blameless-post-mortem]
 description: Blame-free near-miss analysis — same post-mortem flow as analyze:postmortem but framed around a close call that did not result in a production incident.
+argument-hint: "[event-description]"
 suggestion:
   eligible: true
   trigger_description: "near-miss, almost failed, beinahe-Vorfall, close call, we almost had an outage"

package/dist/agent-src/commands/analyze/postmortem.md

@@ -8,6 +8,7 @@ cluster: analyze
 sub: postmortem
 skills: [blameless-post-mortem, root-cause-frameworks]
 description: Blame-free post-mortem after a resolved incident — consume the incident-commander skeleton, derive root cause, write corrective actions, draft an incident-learnings memory candidate.
+argument-hint: "[incident-description]"
 suggestion:
   eligible: true
   trigger_description: "post-mortem, Nachbesprechung, incident review, was ist schiefgelaufen"

package/dist/agent-src/commands/analyze/premortem.md

@@ -8,6 +8,7 @@ cluster: analyze
 sub: premortem
 skills: [premortem]
 description: Forward-looking imagined-failure analysis before committing to a heavy or irreversible plan — enumerate failure stories, score each mode, derive early-warning signals and guardrails.
+argument-hint: "[plan-summary]"
 suggestion:
   eligible: true
   trigger_description: "premortem, what if this fails, imagine failure, stress-test this plan, what could go wrong"

package/dist/agent-src/commands/analyze/reference-repo.md

@@ -8,6 +8,7 @@ sub: reference-repo
 cluster: analyze
 skills: [project-analyzer, learning-to-rule-or-skill]
 description: Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project.
+argument-hint: "<repo-url | owner/repo | archive-url> [--focus=<area>] [--no-roadmap]"
 suggestion:
   eligible: true
   trigger_description: "look at how X does this, compare with that other repo, study this competitor's approach"

package/dist/agent-src/commands/analyze.md

@@ -2,6 +2,7 @@
 model_tier: medium
 name: analyze
 disable-model-invocation: true
+argument-hint: "[postmortem|premortem|decision|near-miss|incident|reference-repo] [subject]"
 pack: analysis-workbench
 intent: "Analysis dispatcher — classify input by keywords, propose a weighted framework path, let the user pick"
 routes_to: [analyze-postmortem, analyze-premortem, analyze-decision, analyze-near-miss, analyze-incident, analyze-reference-repo]
@@ -115,11 +116,11 @@ and ask which one was intended. One question, no guessing.
 - **Memory loop applies** — every sub-command that produces an
   analysis output MUST draft a memory candidate via
   `/memory propose` per
-  [`docs/contracts/analysis-memory-loop.md`](../../../docs/contracts/analysis-memory-loop.md).
+  [`docs/contracts/analysis-memory-loop.md`](../../docs/contracts/analysis-memory-loop.md).
 
 ## See also
 
-- [`docs/contracts/analysis-memory-loop.md`](../../../docs/contracts/analysis-memory-loop.md) — produce → propose → promote → retrieve contract
+- [`docs/contracts/analysis-memory-loop.md`](../../docs/contracts/analysis-memory-loop.md) — produce → propose → promote → retrieve contract
 - [`blameless-post-mortem`](../../../skills/blameless-post-mortem/SKILL.md) — post-mortem + near-miss skill
 - [`root-cause-frameworks`](../../../skills/root-cause-frameworks/SKILL.md) — RCA engine
 - [`premortem`](../../../skills/premortem/SKILL.md) — forward-looking imagined-failure skill

package/dist/agent-src/commands/brand/identity.md

@@ -8,6 +8,7 @@ cluster: brand
 sub: identity
 skills: [brand-identity]
 description: Define the brand identity — logo direction, colour story, type story, imagery direction — and the token constraints downstream generation consumes.
+argument-hint: "<strategy-ref | brief>"
 suggestion:
   eligible: true
   trigger_description: "define our brand identity, logo and colour direction, type story, visual identity system"
@@ -20,8 +21,8 @@ packs:
 
 # /brand:identity
 
-Run the [`brand-identity`](../../skills/brand-identity/SKILL.md) skill — logo
-direction, colour story, type story, imagery direction. brand-identity
-**defines** the tokens/constraints; pack-ai-image's brand-asset generation
-**generates** the marks from them (B → A). Args: `"<strategy ref or brief>"`.
-Run `/brand:strategy` first when no positioning exists.
+Run the [`brand-identity`](../../skills/brand-identity/SKILL.md) skill —
+logo direction, colour story, type story, imagery direction. brand-identity
+**defines** the tokens/constraints; `pack-ai-image`'s brand-asset generation
+**generates** the marks from them (B → A dependency). Args: `"<strategy ref or
+brief>"`. Run `/brand:strategy` first when no positioning exists.

package/dist/agent-src/commands/brand/review.md

@@ -8,6 +8,7 @@ cluster: brand
 sub: review
 skills: [brand-audit]
 description: Audit emitted UI, copy, and assets against the active brand tokens and voice profile — flag any value not traceable to a brand token or voice rule.
+argument-hint: "<artifact-path | description>"
 suggestion:
   eligible: true
   trigger_description: "audit our brand consistency, is this on-brand, check this UI/copy against the brand, brand review"
@@ -20,8 +21,8 @@ packs:
 
 # /brand:review
 
-Run the [`brand-audit`](../../skills/brand-audit/SKILL.md) skill — audit emitted
-UI / copy / assets against the active brand tokens (from `state.ui_design` / the
-consumer's `.tokens.json`) and the voice profile, per the `brand-consistency`
-gate. A value not traceable to a brand token or voice rule is flagged off-brand.
-Args: `"<artifact path or description>"`.
+Run the [`brand-audit`](../../skills/brand-audit/SKILL.md) skill — audit
+emitted UI / copy / assets against the active brand tokens (from
+`state.ui_design` / the consumer's `.tokens.json`) and the voice profile, per
+the `brand-consistency` gate. A value not traceable to a brand token or voice
+rule is flagged off-brand. Args: `"<artifact path or description>"`.

package/dist/agent-src/commands/brand/strategy.md

@@ -8,6 +8,7 @@ cluster: brand
 sub: strategy
 skills: [brand-strategy]
 description: Define brand positioning, archetype, voice, tone, and messaging over the brand-grounding corpus — the strategy that bounds identity and UI.
+argument-hint: "<brief>"
 suggestion:
   eligible: true
   trigger_description: "define our brand strategy, what's our brand archetype, positioning and messaging, brand voice direction"
@@ -21,7 +22,8 @@ packs:
 # /brand:strategy
 
 Run the [`brand-strategy`](../../skills/brand-strategy/SKILL.md) skill —
-positioning, archetype (the 12), voice, tone, messaging frameworks grounded in
-the brand corpus. Output: the strategic frame identity/tokens/voice build on.
-Args: `"<brief>"` (company / product + market). Consumer brand tokens, if
-present, are the source of truth; the corpus fills gaps.
+positioning, archetype (the 12), voice, tone, and messaging frameworks grounded
+in the brand corpus. Output is the strategic frame the rest of the brand layer
+(identity, tokens, voice) builds on. Args: `"<brief>"` (the company / product +
+market). Consumer brand tokens, if present, are the source of truth; the corpus
+fills gaps.

package/dist/agent-src/commands/brand/tokens.md

@@ -8,6 +8,7 @@ cluster: brand
 sub: tokens
 skills: [brand-to-tokens]
 description: Derive a DTCG .tokens.json source of truth from brand decisions, then emit CSS vars + Tailwind via the no-Node token generator.
+argument-hint: "<identity-ref>"
 suggestion:
   eligible: true
   trigger_description: "derive brand tokens, turn our brand into design tokens, generate a .tokens.json from the brand"
@@ -20,9 +21,9 @@ packs:
 
 # /brand:tokens
 
-Run the [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) skill — brand
-decisions → a DTCG `.tokens.json` source of truth → `design-tokens` emits CSS
-vars + Tailwind (no Node). The same `.tokens.json` is the export pack-ai-image's
-brand-asset generation and the greenfield scaffold seed consume; stays on
-`$value`/`$type` so Tokens Studio / Style Dictionary round-trip. Args:
-`"<identity ref>"`.
+Run the [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) skill —
+brand decisions → a DTCG `.tokens.json` source of truth → `design-tokens`
+emits CSS vars + Tailwind (no Node). The same `.tokens.json` is the export that
+`pack-ai-image`'s brand-asset generation and the greenfield scaffold seed
+consume; stays on `$value`/`$type` so Tokens Studio / Style Dictionary
+round-trip. Args: `"<identity ref>"`.

package/dist/agent-src/commands/brand/voice.md

@@ -8,6 +8,7 @@ cluster: brand
 sub: voice
 skills: [voice-and-tone-design]
 description: Define the brand voice-and-tone profile — register, do/don't lexicon, and tone shifts by context — the profile the brand-consistency gate checks copy against.
+argument-hint: "<brand-ref | strategy-ref>"
 suggestion:
   eligible: true
   trigger_description: "define our brand voice, voice and tone guide, how should our copy sound, tone of voice profile"
@@ -21,7 +22,7 @@ packs:
 # /brand:voice
 
 Run the [`voice-and-tone-design`](../../skills/voice-and-tone-design/SKILL.md)
-skill — register, do/don't lexicon, per-context tone shifts. The voice profile
-is what `/brand:review` and the `brand-consistency` gate check emitted copy
-against. Args: `"<brand/strategy ref>"`. Run `/brand:strategy` first when the
-archetype/positioning is not yet set.
+skill — register, do/don't lexicon, and per-context tone shifts. The resulting
+voice profile is what `/brand:review` and the `brand-consistency` gate check
+emitted copy against. Args: `"<brand/strategy ref>"`. Run `/brand:strategy`
+first when the archetype/positioning is not yet set.

package/dist/agent-src/commands/brand.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: brand
 type: orchestrator
 description: Brand-as-UX orchestrator — strategy, identity, tokens, review, voice. Routes to the brand-grounding skills that constrain the design layer.
+argument-hint: "[strategy|identity|tokens|review|voice] [args]"
 suggestion:
   eligible: true
   trigger_description: "work on our brand, define brand strategy/identity/voice, derive brand tokens, audit brand consistency"
@@ -20,11 +21,12 @@ packs:
 # /brand
 
 Top-level orchestrator for the `/brand:*` family — brand as a first-class UX
-layer that **constrains** the UI. Consulted **before**
+layer that **constrains** the UI. The brand layer is consulted **before**
 [`design-intelligence`](../../skills/design-intelligence/SKILL.md) so brand
-bounds style selection. Designer flow: discover → strategy → identity → tokens →
-application → governance. Derived brand tokens are the export pack-ai-image's
-brand-asset generation and the greenfield scaffold seed consume (B → A).
+decisions bound style selection. Walk the designer flow: discover → strategy →
+identity → tokens → application → governance. Brand tokens, once derived, are
+the export that pack-ai-image's brand-asset generation and the greenfield
+scaffold seed consume (B → A dependency).
 
 ## Sub-commands
 
@@ -47,9 +49,9 @@ brand-asset generation and the greenfield scaffold seed consume (B → A).
 
 - **Do NOT commit, push, or open a PR** — subcommands never do this.
 - **Do NOT chain subcommands.** One `/brand <sub>` per turn.
-- **Consumer brand tokens are the source of truth.** Corpus only fills gaps; a
-  value not traceable to a brand token or voice rule is off-brand (per
-  [`brand-consistency`](../rules/brand-consistency.md)).
+- **Consumer brand tokens are the source of truth.** The brand corpus only
+  fills gaps; a value not traceable to a brand token or voice rule is off-brand
+  (per [`brand-consistency`](../rules/brand-consistency.md)).
 - **Edit `src/` only.** Generated mirrors regenerate.
 
 ## See also