@event4u/agent-config 10.3.0 → 10.4.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": "10.3.0",
+    "version": "10.4.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -348,6 +348,84 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 > that forces a new era split (`# Era: 10.4.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [10.4.0](https://github.com/event4u-app/agent-config/compare/10.3.0...10.4.0) (2026-08-13)
+
+### Release highlights
+
+<!-- Curated head: fill before merge, keep it under 10 lines, and leave `_none_` where it is genuinely the answer. The generated log below is unchanged. -->
+- **Behaviour changes:** _none_
+- **Default changes + migration:** _none_
+- **Security and correctness:** _none_
+- **Honest nulls:** _auto-derived, rewrite before merge:_ commits carrying an honest-null marker in 5a9f530.
+- **Known limitations:** _none_
+
+### Features
+
+* **commands:** /design-system cluster — three doors onto machinery that already ships ([e56eaf4](https://github.com/event4u-app/agent-config/commit/e56eaf4a5496bed575e421df997ad60bd2cfac08))
+* **scripts:** three-lane adapter into the design-system.json contract ([d1dd006](https://github.com/event4u-app/agent-config/commit/d1dd00610d4c2c97aa5adf0fa7baa120167b6aa2))
+* **hooks:** an open subagent dispatch is an explicit turn-end allow ([39daf4e](https://github.com/event4u-app/agent-config/commit/39daf4e2c3ba70fa4e43b57fc82bc1bf9eb5b613))
+* **hooks:** ship Phase 3 runaway containment in shadow posture ([b9efa4e](https://github.com/event4u-app/agent-config/commit/b9efa4ec618b3f26c1c07a8eb335866545c4274c))
+* **hooks:** register subagent lifecycle events and bind the ledger ([a6a4023](https://github.com/event4u-app/agent-config/commit/a6a4023529074069f03f8542d0513ee77f3adfde))
+* **hooks:** add the capture-only subagent-ledger concern ([f393ec4](https://github.com/event4u-app/agent-config/commit/f393ec4686422d247bc5862cf13e04459d64ace5))
+* **gates:** adopt the self-test harness in lint_rule_skill_pack_reach ([a758153](https://github.com/event4u-app/agent-config/commit/a7581533b8d5ed8672f985337dc87d21508fa451))
+
+### Bug Fixes
+
+* **design-system:** drop maintainer-only invocations from shipped surfaces ([122760a](https://github.com/event4u-app/agent-config/commit/122760aad5f2a6f4a19c7571da5fcfb732e5e1a8))
+* **scripts:** close nine silent-loss paths in the design-system import adapter ([ed4c7e3](https://github.com/event4u-app/agent-config/commit/ed4c7e39ad3bd732b034c24952460332bb7cb503))
+* **docs:** regenerate proof.md after the command-count change ([c5cb075](https://github.com/event4u-app/agent-config/commit/c5cb07529d8e1903ad15bbf300ce4156fb5a11b2))
+* **ci:** wire check_gate_coverage locally too, and correct three numbers ([a62745c](https://github.com/event4u-app/agent-config/commit/a62745cea249ace8e89a453e9f5950e7179721ce))
+* **ci:** wire the two meta-gates, re-anchor the parity floor ([ea13fc7](https://github.com/event4u-app/agent-config/commit/ea13fc77f2cceecc127933b7f56a5fbcc5a07709))
+* **commands:** register analyze:conformance in the table it already belonged in ([2c307f3](https://github.com/event4u-app/agent-config/commit/2c307f392061eb4ff24a15b1c29b7ddc5c162b71))
+* **hooks:** close the round-2 completion-review findings ([a3de33b](https://github.com/event4u-app/agent-config/commit/a3de33beacff72725b48e4ebdd0bb58b4258bee1))
+* **contracts:** drop the roadmap link from the activation policy ([4d49029](https://github.com/event4u-app/agent-config/commit/4d49029266a04d8d025e110be0a574553634acea))
+* **roadmap:** sync the Phase 2 record with the shipped floors, and own the red ([f98d9d5](https://github.com/event4u-app/agent-config/commit/f98d9d52998c016ad865334ffdf3964b4e01a8e3))
+* **hooks:** close the twelve R2 completion-review findings in the subagent ledger ([4415ff5](https://github.com/event4u-app/agent-config/commit/4415ff54c2e8f47375aeeada5e5d9776eccefa86))
+* **gates:** emit a parseable scan line, and refuse a valueless --root ([8ec2334](https://github.com/event4u-app/agent-config/commit/8ec2334a526572dd549b571f40bf9a24928dbd35))
+* **refs:** re-point the archived roadmap and record a two-gate contradiction ([9671002](https://github.com/event4u-app/agent-config/commit/9671002114d27fcbd112d3f77d79dfaacc94c821))
+* **roadmap:** tag the corpus-scoping roadmap lightweight, not standard ([b6676b0](https://github.com/event4u-app/agent-config/commit/b6676b09f87c48aa083feb98f2ff7343c837bd18))
+
+### Documentation
+
+* **review:** re-bind the findings artefact after the consumer-path fix ([fcb8ab4](https://github.com/event4u-app/agent-config/commit/fcb8ab408c9b2fbfd51d98e261ead5c572e5cf7a))
+* **review:** re-bind the findings artefact after the second main merge ([cfd2695](https://github.com/event4u-app/agent-config/commit/cfd2695162708c3db80b699667dbc7108c9e057c))
+* **review:** re-bind the findings artefact to the post-fix scope ([2674827](https://github.com/event4u-app/agent-config/commit/267482700c5d00db465722005888f823d50acc4c))
+* **review:** re-bind the skip declaration to the merged scope ([6518a6a](https://github.com/event4u-app/agent-config/commit/6518a6a12a69bc640c70febcf36d176ae05b8992))
+* **design-system:** correct two claims the review showed were too broad ([49b6e47](https://github.com/event4u-app/agent-config/commit/49b6e4741aa21a18c72c3f51f9775981f980bb1f))
+* **review:** bind the R2 completion-review findings for feat-design-system-onramp ([3be0b77](https://github.com/event4u-app/agent-config/commit/3be0b771bf99816ab4b0a7d9d69c51ea8e41a848))
+* **roadmap:** close road-to-local-only-gate-reds and archive it ([cfeeacc](https://github.com/event4u-app/agent-config/commit/cfeeacc81c2b09f18d7e5fcfd7a312b05dd0b209))
+* **roadmap:** archive road-to-august-program on its own falsifier ([3fd5a77](https://github.com/event4u-app/agent-config/commit/3fd5a776750447e6967137be31ee76a6e1c7b4b4))
+* **roadmap:** resolve the three release-integrity blockers and archive it ([9d66d73](https://github.com/event4u-app/agent-config/commit/9d66d73f45b28ed8c17b842ca0f730cf11ca614d))
+* **contract:** publish the curated-head recurrence rate, (b) stands ([310b49b](https://github.com/event4u-app/agent-config/commit/310b49b1d4b5f8fe7a12d6199c84429257cc4e0c))
+* **adr:** ADR-228 — the global install does not emit paths: ([d9bcbf5](https://github.com/event4u-app/agent-config/commit/d9bcbf5c46e7d4c100f1bceabe429c0df6b42990))
+* **adr:** accept ADR-221, the host-native-first ladder ([a55a37f](https://github.com/event4u-app/agent-config/commit/a55a37f6f88eb08326d56a0562c22324fa1746dc))
+* **review:** re-bind the round-2 findings after the fix pass ([f1403f1](https://github.com/event4u-app/agent-config/commit/f1403f1896b4570b6eb83c9ac0f1c28b1d504914))
+* **review:** bind round 2 of the completion review, and keep round 1 ([7914694](https://github.com/event4u-app/agent-config/commit/7914694b9055c4b47caf5c01c49699cb1aa77f01))
+* **design-system:** name the supply path where the contract is refused ([0bef92d](https://github.com/event4u-app/agent-config/commit/0bef92d6314c82978bce578effaff7e43e24ea6c))
+* **roadmap:** record the Phase 3 council pass and flip its three steps ([e1c99ad](https://github.com/event4u-app/agent-config/commit/e1c99ad25ece149cd80c0879957b01702148cc00))
+* **contracts:** write the concern activation policy three roadmaps cited and none wrote ([130a9d9](https://github.com/event4u-app/agent-config/commit/130a9d98ad691888a3d41bec71f170e8e6d853c3))
+* **review:** re-bind the round-2 artefact to the fixed scope ([1cba2b1](https://github.com/event4u-app/agent-config/commit/1cba2b111a3759d565ec0071ee1607c7c0d6bbec))
+* **review:** round 2 of the completion review, over the merged scope ([57e4fc5](https://github.com/event4u-app/agent-config/commit/57e4fc58491b80ce70f994963fbcaa6fbe972be4))
+* **review:** re-bind the findings artefact after the fix pass ([b58fcd5](https://github.com/event4u-app/agent-config/commit/b58fcd59ea10b899d6feaa1b7afa632c437f3d77))
+* **review:** bind the R2 completion-review findings for feat-subagent-lifecycle-integrity ([79b7c8e](https://github.com/event4u-app/agent-config/commit/79b7c8eb27f114ae6d40d6c168fa5c992be1b650))
+* **review:** re-bind the completion-review artefact to the fixed scope ([c714668](https://github.com/event4u-app/agent-config/commit/c71466897e1053bc28387d3da1240a3773534a0b))
+* **review:** R2 completion review for feat-local-only-gate-reds ([3c87378](https://github.com/event4u-app/agent-config/commit/3c87378c83b36da10a82af729ffa224d506716a8))
+* **roadmap:** record the Phase 0/1/5 findings and the Phase 3 stop ([3fc4332](https://github.com/event4u-app/agent-config/commit/3fc433269cc36520bb10e5f08f302cdfdffc5d5a))
+* **review:** declare the completion-review skip for a zero-code-path branch ([ac92f16](https://github.com/event4u-app/agent-config/commit/ac92f1686a44ca8d52cf652fb3c35ec71224d800))
+* **adr:** record that paths scoping is saturated, not a corpus lever ([6c062d9](https://github.com/event4u-app/agent-config/commit/6c062d9d57e290a50b0eb544448e83b8ec03c396))
+* **roadmap:** record the four closed steps, and a fifth red the repair left ([637c009](https://github.com/event4u-app/agent-config/commit/637c00913b9936d5ceb8fe5cdffa8eddd610ef47))
+
+### Chores
+
+* **dist:** re-project the design-system doc and halt-text changes ([070f4ce](https://github.com/event4u-app/agent-config/commit/070f4ce7b48ca0f206b6fae413a8f529d3f5bf0b))
+* **roadmap:** regenerate the dashboard after the main merge ([54250e3](https://github.com/event4u-app/agent-config/commit/54250e3f6de110ba8881386e6e8c95be38b9b8d4))
+* **roadmap:** close design-system-onramp Phases 1, 2 and 4; file two blockers ([80573dd](https://github.com/event4u-app/agent-config/commit/80573dd7d75ab27d026138e54ef06119daec59e8))
+* **roadmaps:** regenerate the dashboard after the main merge ([d54aba9](https://github.com/event4u-app/agent-config/commit/d54aba956229302c3bc7323ddf8cafd7bd4ccb3c))
+* **roadmap:** regenerate the dashboard after the second main merge ([b1a283b](https://github.com/event4u-app/agent-config/commit/b1a283bb04d9a881aa13495c28f0779557792670))
+* **roadmap:** close always-loaded-corpus-scoping on its honest null ([5a9f530](https://github.com/event4u-app/agent-config/commit/5a9f53009a920ff16b9cc92e39167497a51d92ab))
+
+Tests: 13768 (+89 since 10.3.0)
+
 ## [10.3.0](https://github.com/event4u-app/agent-config/compare/10.2.0...10.3.0) (2026-08-13)
 
 ### Release highlights

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) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-289-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-116-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-196-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-105-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-289-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-116-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-200-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-105-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/)
 
 **Try it in 30 seconds** — drop one read-only subagent into any repo and watch it gate "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
 

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 argument-hint: "[postmortem|premortem|decision|near-miss|incident|reference-repo|inbox] [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, analyze-inbox]
+routes_to: [analyze-postmortem, analyze-premortem, analyze-decision, analyze-near-miss, analyze-incident, analyze-reference-repo, analyze-inbox, analyze-conformance]
 replaces: []
 tier: 1
 visibility: advanced
@@ -40,6 +40,7 @@ to the chosen sub-command. Never auto-selects silently.
 | `/analyze:incident` | `analyze/incident/command.md` | Full incident flow: commander → RCA → post-mortem → memory candidate |
 | `/analyze:reference-repo` | `analyze/reference-repo/command.md` | Deep-dive an external reference repo (competitor, inspiration, peer) → structured comparison + adoption plan |
 | `/analyze:inbox` | `analyze/inbox/command.md` | Deep-dive a LOCAL artifact dropped in `agents/tmp/` (review, prompt, spec, transcript) → claim verification against the current tree + artefact mapping + roadmap |
+| `/analyze:conformance` | `analyze/conformance/command.md` | Audit recent local sessions for rule violations → deterministic scan + subagent passes, root-caused per class, and a roadmap for what is mechanisable |
 
 ## Dispatch
 

package/dist/agent-src/commands/design-system/capture.md

@@ -0,0 +1,44 @@
+---
+model_tier: medium
+name: design-system-capture
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: design-system
+sub: capture
+skills: [existing-ui-audit, design-system-capture]
+description: Inventory this repo's own components and tokens and emit them in the design-system.json shape, so the import path is identical to an external extraction.
+argument-hint: "[path]"
+suggestion:
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+---
+
+# /design-system:capture
+
+Run [`existing-ui-audit`](../../skills/existing-ui-audit/SKILL.md) over the
+current repo and emit its inventory as a `design-system.json` artifact — the
+same shape an external extraction tool produces, so the import path is identical
+either way. Args: optional `[path]` to narrow the scan.
+
+Two sources, one shape: use this for **this** repo, and
+[`/design-system:import`](../import/command.md) for a site or repo you do not
+own.
+
+## Then hand it over
+
+Pass the emitted artifact to [`design-system-capture`](../../skills/design-system-capture/SKILL.md)'s
+import step, which confirms it per field into `DESIGN.md`.
+
+## Rules
+
+- **Set `source` honestly** — `kind: dir`, `ref` = the scanned path,
+  `captured_at` = now. An artifact with no provenance is rejected downstream.
+- **Observation is not a token.** Anything the audit *noticed* rather than
+  *decided* belongs under `_meta`, per the contract's field rules.
+- **The audit's own grouping is not the contract's shape.** Map it deliberately;
+  do not rename the audit's output keys and call it done.

package/dist/agent-src/commands/design-system/generate.md

@@ -0,0 +1,53 @@
+---
+model_tier: high
+name: design-system-generate
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: design-system
+sub: generate
+skills: [corpus-grounding, design-intelligence, design-system-capture]
+description: Ground a design system in the curated design corpus from a product or industry brief, then optionally persist it as MASTER.md or seed DESIGN.md.
+argument-hint: "<product / industry / keywords>"
+suggestion:
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+---
+
+# /design-system:generate
+
+Run the grounded one-shot over the curated corpus and print the full
+recommendation. Args: `"<product / industry / keywords>"`.
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/skills/corpus-grounding/scripts/ground.ts \
+    ground "<query>" \
+    --manifest node_modules/@event4u/agent-config/src/skills/design-intelligence/data/manifest.json
+```
+
+Add `--persist <dir> --project-name <name>` to write
+`design-system/<slug>/MASTER.md`, and `--page <name>` for a page-override stub
+alongside it. The engine is read-only without `--persist`.
+
+## After the recommendation
+
+Offer both destinations, and let the human pick — they are different artifacts,
+not two spellings of one:
+
+- **`MASTER.md` + page overrides** (`--persist`) — the interchange format, good
+  for handing a system to another tool or to a designer.
+- **`DESIGN.md`** via [`design-system-capture`](../../skills/design-system-capture/SKILL.md)
+  — this package's canonical design memory, the file every later design task
+  reads. Seed it when the system is for *this* repo's own work.
+
+## Rules
+
+- **Generated output is a proposal.** A provided artifact, registered brand
+  tokens, and a confirmed `DESIGN.md` outrank it — never overwrite a confirmed
+  decision with a generated default.
+- **Never persist silently.** `--persist` is the human's choice, and `DESIGN.md`
+  is seeded per field, not written wholesale.

package/dist/agent-src/commands/design-system/import.md

@@ -0,0 +1,63 @@
+---
+model_tier: medium
+name: design-system-import
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: design-system
+sub: import
+skills: [design-system-capture]
+description: Run an extraction tool's output through the three-lane adapter into the design-system.json contract, then hand it to the per-field confirmation import.
+argument-hint: "<file>"
+suggestion:
+  eligible: false
+  rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+---
+
+# /design-system:import
+
+Transform an extracted design system into the `design-system.json` contract,
+then import it per field. Args: `<file>`.
+
+```bash
+npx tsx node_modules/@event4u/agent-config/src/scripts/design_system_import.ts <file> \
+    [--lane native|dtcg|dembrandt] \
+    [--source-kind url|repo|dir --source-ref <ref>] [--captured-at <ISO>] \
+    [--format json|summary]
+```
+
+The lane is detected from the file's own shape; `--lane` only forces which
+mapper runs and never reshapes the input. Lane behaviour, the documented
+producers, and the never-force-a-lane degradation are specified in
+[`design-system-json.md`](../../skills/design-system-capture/references/design-system-json.md)
+§ Extractor compatibility.
+
+## The easy path, in two lines
+
+1. Connect an extractor once — e.g.
+   `claude mcp add --transport stdio dembrandt -- npx -y --package dembrandt dembrandt-mcp`.
+2. Run `/design-system:import` over its output.
+
+No extractor available? Skip step 1 and use
+[`/design-system:generate`](../generate/command.md) from the corpus instead, or
+[`/design-system:capture`](../capture/command.md) for this repo.
+
+## Then hand it over
+
+Pass the result to [`design-system-capture`](../../skills/design-system-capture/SKILL.md)'s
+import step. Do not write `DESIGN.md` from here.
+
+## Rules
+
+- **Provenance is mandatory.** A file with no `source` and no `--source-ref` is
+  rejected — you cannot confirm what you cannot trace. Supplying it by flag is
+  recorded as caller-asserted, not extracted.
+- **The artifact is observed, not authoritative.** Every field is confirmed by
+  the human; a value conflicting with a registered brand token is flagged, never
+  auto-applied.
+- **The adapter is offline.** It reads a file and writes the contract shape — it
+  never fetches, crawls, or launches a browser.

package/dist/agent-src/commands/design-system.md

@@ -0,0 +1,66 @@
+---
+model_tier: inherit
+name: design-system
+pack: engineering-base
+tier: 2
+visibility: internal
+cluster: design-system
+type: orchestrator
+description: Design-system onramp — generate one from the corpus, import an extractor's output, or capture the current repo's. Three doors onto machinery that already ships.
+argument-hint: "[generate|import|capture] [args]"
+suggestion:
+  eligible: true
+  trigger_description: "generate a design system, import extracted design tokens, capture this repo's design system, seed DESIGN.md from a site"
+  trigger_context: "user explicitly wants a design system produced, imported, or captured — never suggested for ordinary UI work"
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+---
+
+# /design-system
+
+Three doors onto machinery this package already ships and nothing could reach.
+The grounded generator, its `MASTER.md` persistence, the `design-system.json`
+import contract, and the current-repo inventory all existed before this cluster;
+what was missing was a way in. So every sub-command below is an entry point, not
+a new subsystem.
+
+**Optional means invoked or not invoked.** This cluster adds no settings key, no
+always-on rule, and no auto-trigger. It is suggestion-eligible only when a
+design-system question is explicit, and otherwise silent.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/design-system:generate "<product / industry / keywords>"` | `commands/design-system/generate.md` | Ground a design system in the curated corpus; optionally persist `MASTER.md` + page overrides, or seed `DESIGN.md` |
+| `/design-system:import <file>` | `commands/design-system/import.md` | Run an extractor's output through the three-lane adapter, then the per-field confirmation import |
+| `/design-system:capture` | `commands/design-system/capture.md` | Inventory *this* repo's components and tokens and emit the same `design-system.json` shape |
+
+## Dispatch
+
+1. Parse `/design-system <sub-command> [args]`. Sub-command = first token; match
+   against the table's exact names only.
+2. Look up the sub-command and execute its file verbatim with the remaining args.
+3. Unknown / missing sub-command → print the table and ask which door to take.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** — subcommands never do this.
+- **Do NOT chain subcommands.** One `/design-system <sub>` per turn.
+- **Generated and imported output is a proposal.** A provided artifact,
+  registered brand tokens, and a confirmed `DESIGN.md` all outrank it; a value
+  that conflicts with a registered brand token is flagged, never auto-applied
+  (per [`brand-source-of-truth`](../rules/brand-source-of-truth.md)).
+- **No crawler, browser runtime, or font-bundler is shipped.** Extraction tools
+  are user-installed and user-connected; this package's share is the adapter,
+  the instructions, and the validation.
+- **Edit `src/` only.** Generated mirrors regenerate.
+
+## See also
+
+- [`design-system-capture`](../../skills/design-system-capture/SKILL.md) — owns `DESIGN.md` and the per-field-confirmation import.
+- [`corpus-grounding`](../../skills/corpus-grounding/SKILL.md) · [`design-intelligence`](../../skills/design-intelligence/SKILL.md) — the grounded generator behind `:generate`.
+- [`existing-ui-audit`](../../skills/existing-ui-audit/SKILL.md) — the current-repo inventory behind `:capture`.
+- [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md) — `design-system` cluster registration.

package/dist/agent-src/skills/design-system-capture/SKILL.md

@@ -202,6 +202,15 @@ auto-installer (out of scope). Full schema is lazy-loaded from
 [`references/design-system-json.md`](references/design-system-json.md) — read it
 only when an import is requested.
 
+**The supply path is real, and it is one command.** Where an extractor's output
+is not already in this shape, run it through the three-lane adapter first —
+`/design-system:import <file>`, which accepts a native artifact, a DTCG token
+file, or an extraction tool's raw JSON and emits the contract. Lanes and
+documented producers:
+[`references/design-system-json.md`](references/design-system-json.md)
+§ Extractor compatibility. The adapter is offline and pure — it does not change
+what this skill owns.
+
 **Import procedure:**
 
 1. Read `design-system.json`; reject it if `source` (kind + ref + captured_at)

package/dist/agent-src/skills/design-system-capture/references/design-system-json.md

@@ -71,3 +71,73 @@ brand wins). Precedence on import: registered brand tokens > confirmed
 
 The package **owns this contract**; it does **not** ship the crawler, the
 Playwright runtime, or a font-bundler.
+
+## Extractor compatibility — which crawler, and how its output gets here
+
+The contract above says what this skill reads. This section says how a real
+tool's output becomes that shape, so the answer to *"which crawler?"* lives in
+the contract rather than in somebody's memory.
+
+`src/scripts/design_system_import.ts` is a **pure, offline file transform** with
+three input lanes. It reads a file and writes the contract shape to stdout — no
+network, no browser, no crawl. That is the lock restated as code: a transform
+that fetched would quietly become the crawler this package does not ship.
+
+| Lane | Input | What it does |
+|---|---|---|
+| `native` | an existing `design-system.json` | Validates `source`, carries every other key verbatim. Past provenance the validation is **report-only** — a key whose shape contradicts the contract is flagged and kept, never dropped, because the import is a proposal a human reads. |
+| `dtcg` | a W3C DTCG token file (`{$value, $type}` leaves) | Buckets by `$type`, so it works on any authoring tool's layering — **with two stated path exceptions**: `dimension` / `number` is genuinely ambiguous in DTCG (spacing, radius and font size share it), so the path breaks that tie, and a path segment named `dark` files a colour under the dark theme. Both are inferences and both are reported in the notes. Resolves `{alias.references}` to their values. Tokens with no contract bucket land in `_meta.unmapped` — which is why `component.button.paddingX` lands there rather than under spacing. |
+| `dembrandt` | an extraction tool's raw JSON | Matches the documented top-level key names and accepts a small set of shapes per bucket. Motion durations/easings become the `motion` block; per-context profiles, hover deltas, WCAG results and breakpoints are **observation** and land in `_meta`. |
+
+```bash
+# The command is the supported entry point:
+/design-system:import <file>
+
+# Or call the transform directly, from an installed package:
+npx tsx node_modules/@event4u/agent-config/src/scripts/design_system_import.ts <file> \
+    [--lane native|dtcg|dembrandt] \
+    [--source-kind url|repo|dir --source-ref <ref>] [--captured-at <ISO>] \
+    [--format json|summary]
+```
+
+**Documented producers.** Two extraction tools are known to emit input this
+adapter consumes, and both are **user-installed and user-connected** — the
+package ships the adapter, the instructions, and the validation, never the tool:
+
+- **dembrandt** (MIT, npm) — the richest single source: computed-DOM tokens,
+  automatic motion extraction (duration scale, easing curves), component
+  observations, WCAG pairs, and a stdio MCP server. Feeds the `dembrandt` lane
+  directly, or the `dtcg` lane via its `--dtcg` export.
+- **designlang** (MIT) — DTCG in primitive/semantic/composite layers plus
+  interaction states. Feeds the `dtcg` lane. Its own repo-writing feature is not
+  invoked; this package owns its projection.
+
+A third, **extract-design-system**, emits plain W3C `tokens.json` and feeds the
+same `dtcg` lane. Any other tool that can export DTCG works without a new lane.
+
+**Provenance is mandatory on every lane, and its origin is recorded.** DTCG
+carries no `source` block by construction, so the caller supplies one; the
+result then carries `source._meta.provenance_origin: "caller"` rather than
+`"input"`, so a reader can always tell an extracted provenance from an asserted
+one. Neither one present is a rejection, not a default — you cannot confirm what
+you cannot trace.
+
+**A lane is never forced.** Where a real sample cannot be mapped without
+inventing values, the adapter emits it as `_meta` observation and says so in a
+note. An import that lands mostly under `_meta` is the designed degradation, not
+a failure — it means the tool's shape moved, and the values are still in front
+of the human instead of silently coerced into tokens.
+
+**Parked, not adopted — runtime drift detection.** One documented producer also
+ships a drift gate: `--compare <baseline>` against a captured baseline, with
+distinct exit codes (0 clean · 1 drift · 2 usage · 67 threshold) and a
+machine-readable `drift` key carrying per-token `changes[]`. That is a
+*design-quality CI* capability, not an import one, and nothing in this package
+asks for it today — recorded here as a candidate so the next reader finds it
+already assessed, and taken up only if a design-quality roadmap asks for runtime
+drift detection.
+
+The compatibility matrix is committed as tests, not prose:
+`tests/scripts/fixtures/design-system-import/` holds one input/expected pair per
+lane, and that directory's README states which sample is a real capture and
+which is derived from a tool's published output surface.

package/dist/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.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "10.3.0"
+agent_config_version: "10.4.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/scripts/work_engine/directives/ui/design.ts

@@ -345,7 +345,10 @@ function _halt_provided_without_contract(
         '> 1. Proceed — port it with those five losses on the record; `apply` ' +
             'still has to report what it honoured, translated, and flagged',
         '> 2. Supply a `design-system.json` — its token values are then ' +
-            'honoured verbatim instead of re-derived',
+            'honoured verbatim instead of re-derived. Already have an ' +
+            "extractor's output in another shape? `/design-system:import " +
+            '<file>` maps a DTCG token file or an extraction tool\'s raw JSON ' +
+            'into this contract offline.',
         '> 3. Abort — drop this UI request',
         '',
         '**Recommendation: 2 — Supply the contract** — it is the only option ' +

package/dist/cli-delegate/chunk-RLN73PR5.js

@@ -0,0 +1,157 @@
+import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+import {
+  git_common_dir
+} from "./chunk-PZWRPRWP.js";
+
+// src/scripts/_lib/envelope_grounding.ts
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// src/scripts/_lib/git_env.ts
+var GIT_DISCOVERY_VARS = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  "GIT_COMMON_DIR",
+  "GIT_NAMESPACE",
+  "GIT_PREFIX"
+];
+function gitEnv(base = process.env) {
+  const env = { ...base };
+  for (const key of GIT_DISCOVERY_VARS) {
+    delete env[key];
+  }
+  return env;
+}
+
+// src/scripts/_lib/envelope_grounding.ts
+var MAX_FIELD_CHARS = 200;
+var MAX_PATHS = 40;
+function git(root, args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: root,
+      env: gitEnv(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function canonicalizeRepoIdentity(raw) {
+  let s = raw.trim();
+  s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+  s = s.replace(/^[^/@]+@/, "");
+  s = s.replace(/^([^/:]+):(?!\/)/, "$1/");
+  s = s.replace(/\/+$/, "");
+  s = s.replace(/\.git$/i, "");
+  const slash = s.indexOf("/");
+  if (slash > 0) {
+    s = s.slice(0, slash).toLowerCase() + s.slice(slash);
+  } else {
+    s = s.toLowerCase();
+  }
+  return s;
+}
+function collectRepoAnchor(root) {
+  const remote = git(root, ["config", "--get", "remote.origin.url"]);
+  let identity = null;
+  if (remote) {
+    identity = canonicalizeRepoIdentity(remote);
+  } else {
+    const common = git_common_dir(root);
+    if (common !== null) {
+      try {
+        identity = fs.realpathSync(common);
+      } catch {
+        identity = common;
+      }
+    }
+  }
+  return {
+    repo_identity: identity ? identity.slice(0, MAX_FIELD_CHARS) : null,
+    branch: git(root, ["rev-parse", "--abbrev-ref", "HEAD"]),
+    head: git(root, ["rev-parse", "HEAD"])
+  };
+}
+var VERIFY_STATE_REL = path.join("agents", "runtime", "state", "verify-before-complete.json");
+function readLastVerify(root) {
+  try {
+    const raw = fs.readFileSync(path.join(root, VERIFY_STATE_REL), "utf-8");
+    const state = JSON.parse(raw);
+    const lv = state["last_verification"];
+    if (typeof lv !== "object" || lv === null || Array.isArray(lv)) return null;
+    const rec = lv;
+    const command = typeof rec["command"] === "string" ? rec["command"] : null;
+    if (!command) return null;
+    const at = typeof rec["at"] === "string" ? rec["at"] : "unknown time";
+    return `${command} @ ${at} (no exit status is recorded anywhere)`.slice(0, MAX_FIELD_CHARS);
+  } catch {
+    return null;
+  }
+}
+function collectGrounding(root) {
+  const anchor = collectRepoAnchor(root);
+  const porcelain = git(root, ["status", "--porcelain"]);
+  if (porcelain === null) {
+    return { ...anchor, uncommitted_paths: [], status_summary: null, last_verify: readLastVerify(root) };
+  }
+  const lines = porcelain.split("\n").filter((l) => l.trim().length > 0);
+  const paths = lines.map((l) => l.slice(3).trim()).filter((p) => p.length > 0 && p.length <= MAX_FIELD_CHARS).slice(0, MAX_PATHS);
+  return {
+    ...anchor,
+    uncommitted_paths: paths,
+    status_summary: lines.length === 0 ? "clean working tree" : `${lines.length} uncommitted path(s)${lines.length > MAX_PATHS ? `, first ${MAX_PATHS} listed` : ""}`,
+    last_verify: readLastVerify(root)
+  };
+}
+function describeDrift(envelope, actual) {
+  if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) return [];
+  const e = envelope;
+  const drift = [];
+  const recordedIdentity = typeof e["repo_identity"] === "string" ? e["repo_identity"] : null;
+  if (recordedIdentity && actual.repo_identity && recordedIdentity !== actual.repo_identity) {
+    drift.push(
+      `IDENTITY DRIFT: this envelope was written in "${recordedIdentity}", you are in "${actual.repo_identity}". Re-verify every path before acting \u2014 same branch name does not mean same working tree.`
+    );
+  }
+  const recordedBranch = typeof e["branch"] === "string" ? e["branch"] : null;
+  if (recordedBranch && actual.branch && recordedBranch !== actual.branch) {
+    drift.push(
+      `BRANCH DRIFT: envelope written on "${recordedBranch}", checkout is on "${actual.branch}".`
+    );
+  }
+  const recordedHead = typeof e["head"] === "string" ? e["head"] : null;
+  if (recordedHead && actual.head && recordedHead !== actual.head) {
+    drift.push(
+      `COMMIT DRIFT: envelope written at ${recordedHead.slice(0, 12)}, HEAD is now ${actual.head.slice(0, 12)} \u2014 re-read anything the envelope quotes.`
+    );
+  }
+  return drift;
+}
+
+// src/scripts/_lib/recycle_envelope_paths.ts
+import * as path2 from "node:path";
+var RECYCLE_ENVELOPE_REL = path2.join("agents", "runtime", "state", "recycle-envelope.json");
+var RECYCLE_CONSUMED_REL = path2.join(
+  "agents",
+  "runtime",
+  "state",
+  "recycle-envelope.consumed.json"
+);
+var RECYCLE_MAX_AGE_HOURS = 48;
+var RECYCLE_ENVELOPE_MAX_BYTES = 6144;
+
+export {
+  collectRepoAnchor,
+  collectGrounding,
+  describeDrift,
+  RECYCLE_ENVELOPE_REL,
+  RECYCLE_CONSUMED_REL,
+  RECYCLE_MAX_AGE_HOURS,
+  RECYCLE_ENVELOPE_MAX_BYTES
+};