@event4u/agent-config 10.2.0 → 10.4.0

package/dist/agent-src/rules/design-fidelity.md

@@ -60,8 +60,28 @@ A PROVIDED PROTOTYPE / DESIGN SYSTEM IS THE SPEC, NOT A SUGGESTION.
 BUILD IT 1:1. NEVER SWAP FONTS, CONTROLS, COMPONENTS, LAYOUT, SPACING,
 OR COLOUR — AND NEVER OMIT OR ADD AN ELEMENT — WITHOUT EXPLICIT CONFIRMATION.
 A "BETTER IDEA" IS A PROPOSAL TO SURFACE, NEVER A CHANGE TO MAKE.
+WHENEVER THE SOURCE IS REACHABLE, THE SOURCE IS THE DATA BASIS.
+A SCREENSHOT IS VALIDATION, NEVER THE INPUT YOU BUILD FROM,
+WHILE ANY HIGHER RUNG IS REACHABLE. WHEN THE HANDOVER *IS* AN IMAGE,
+THE IMAGE IS THE SPEC AND THE 1:1 FLOOR ABOVE APPLIES TO IT UNCHANGED.
+WHERE THE ARTIFACT'S OWN MARKUP / CSS / JS IS STACK-COMPATIBLE, ADAPTING
+THAT CODE IS THE DEFAULT — A FROM-SCRATCH RE-DERIVATION IS A DEVIATION
+AND NEEDS THE SAME CONFIRMATION AS A SWAPPED CONTROL.
 ```
 
+The qualifier is load-bearing, not hedging. Unqualified, the screenshot line
+contradicts this rule's own opening sentence and its § What counts as the spec,
+both of which name a screenshot as a legitimate spec — and it would forbid the
+image-only handover class the rule exists to govern. What it forbids is
+narrower: reaching for pixels **while the code is sitting there**.
+
+The five new lines route to
+[`design-fidelity-mechanics`](../docs/guidelines/design-fidelity-mechanics.md)
+§ Data-basis ladder (the first three) and § Adopt the code (the last two) —
+including the scope line that keeps the adopt-the-code duty from colliding with
+[`code-provenance`](code-provenance.md). Read that scope line before acting on
+either rule; the boundary is stated from both sides.
+
 ## What counts as the spec
 
 A user-provided, finished design artifact the user points at and says "match
@@ -114,6 +134,21 @@ Two further handover shapes carry the artifact without any of the above:
   conventional location for a handed-over token/component set. The prefix is the
   vendor-scoped directory, never a bare `design-system/`, which is a normal
   source folder in a large fraction of frontend repos.
+- **A third-party builder's share link — UNCOVERED, deliberately.** A page built
+  in Lovable / v0 / bolt and handed over as a link is a finished spec, and this
+  rule does not route it. The obvious trigger was tried on this branch and
+  **withdrawn**: matching is plain substring containment, so `https://v0.dev/`
+  also fires on `https://v0.dev/docs`, a pricing page, or a changelog link — it
+  would treat every mention of the tool's own site as a spec handover. That is
+  the `claude.ai` failure the capability-URL entry above exists to avoid, and by
+  this rule's own standard it is worse than the gap it closes. The alternatives
+  are a bare-host keyword (broader still) or guessing each vendor's share-path
+  segment, and a trigger built on a guessed path is not evidence.
+  **What closes it:** a verified share-path segment per vendor, or a
+  handover-word co-occurrence the matcher cannot express today. Until then the
+  class needs one word in the prompt, like any other unlisted filename.
+  `near-bare-host-mention` in the matrix pins the bare-host direction silent so
+  a future attempt cannot reintroduce the broad form unnoticed.
 
 The trigger set is deliberately phrase-heavy on the German side and on
 `artifact`: a bare `artifact` keyword fires on "the CI build artifact is 40 MB".
@@ -121,9 +156,20 @@ The trigger set is deliberately phrase-heavy on the German side and on
 [`design_fidelity_routing.test.ts`](../../tests/scripts/design_fidelity_routing.test.ts)
 pins both halves — every class that must route, and the near-misses that must
 stay silent (fixture `daf-port-trigger-de`). Extending the set without adding a
-near-miss row there is how an over-broad trigger lands: each of the two triggers
-above ships with its own near-miss row (`near-claude-ai-chat-link`,
-`near-generic-design-system-dir`).
+near-miss row there is how an over-broad trigger lands: each of the two shipped
+trigger classes above carries its own near-miss row
+(`near-claude-ai-chat-link`, `near-generic-design-system-dir`), and the
+withdrawn builder-URL class left `near-bare-host-mention` behind so the broad
+form stays pinned silent.
+
+**The near-miss must test the direction the new trigger opens, not a direction
+that was already closed.** The withdrawn class is the worked example: its first
+near-miss row tested a protocol-less mention, which was silent *before* the
+change and therefore could not have caught the over-broadness the change
+introduced. The row that would have caught it is
+`near-builder-host-non-handover-url` — a documentation URL on the same host —
+and it exists only because a review asked for it after the trigger had already
+shipped. Write that row first next time; it is the cheap half.
 
 Body migrated to [`guideline:design-fidelity-mechanics`](../docs/guidelines/design-fidelity-mechanics.md) (per P4 of `road-to-kernel-and-router.md`) — surgical visual edits (targeted-edit vs redesign-trigger discipline, stable anchors), asset & imagery discipline (owned-asset path, third-party delivery is self-hosted by default, real-imagery-as-proof, iconography floor, no unrequested filler), deviation-surfacing shape, failure-mode catalog, `daf-*` fixtures.
 Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).

package/dist/agent-src/skills/design-review/references/verification-automation.md

@@ -29,7 +29,25 @@ Don't just screenshot the default state. Capture:
 
 ### Mockup-to-code verification
 
-When implementing from a design mockup or screenshot:
+**Branch on what the artifact actually is before you open anything.** The two
+kinds carry different workflows, and running the image workflow over a code
+artifact is the failure this branch exists to prevent — it rebuilds from pixels
+what was handed over as source.
+
+**Code artifact** — an HTML/JSX/Vue file, an archive, a repo, a live page whose
+DOM you can reach:
+
+1. **Read the code** — it is the data basis (`design-fidelity-mechanics`
+   § Data-basis ladder, rungs 1–2). Markup, styles, scripts.
+2. **Implement** — adapting the artifact's own code where it is
+   stack-compatible; a from-scratch re-derivation is a deviation, not a default.
+3. **Screenshot afterwards** — for an after-the-fact visual diff only, never as
+   the input you built from.
+4. **Flag deviations** — including behaviour: a handler or keyframe that did not
+   survive is a deviation, not an implementation detail.
+
+**Image artifact** — a PNG/JPG screenshot, a Figma export you cannot open as
+source, a photograph of a whiteboard:
 
 1. **Open the mockup** — use the provided image/screenshot.
 2. **Implement** — build the UI component.
@@ -38,6 +56,10 @@ When implementing from a design mockup or screenshot:
 
 This is especially useful when the user provides a screenshot or Figma export as a reference.
 
+> **Near-miss worth naming:** an HTML file *opened in a browser* is still a code
+> artifact. The browser makes it look like an image; the file on disk is rung 1.
+> Take the code path.
+
 ## Async-verifier pattern (keep the main context clean)
 
 For a review that needs browser probing, use an **async background verifier**

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/skills/fe-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: medium
 name: fe-design
-description: "Frontend design heuristics — and, outside the ticket engine, the loop that applies them: audit, brief, build, review. Use when building or changing any UI, not only when planning one."
+description: "Frontend design heuristics — and, outside the ticket engine, the loop that applies them: audit, brief, inventory, build, review. Use when building or changing any UI, not only when planning one."
 personas:
   - frontend-engineer
 domain: engineering
@@ -40,8 +40,32 @@ else runs the loop.
    `layout`, `components`, `states`, `microcopy`, `a11y`. `states` means all
    five of `empty`, `loading`, `error`, `success`, `disabled` — a brief missing
    one is unfinished, not concise.
-3. **Build** — against the audit's primitives, in the project's stack.
-4. **Review** — run [`design-review`](../design-review/SKILL.md) before calling
+3. **Inventory — only when an artifact was provided, and before you build.**
+   List the artifact's **interactions, keyframes, and script includes** from its
+   source (`design-fidelity-mechanics` § Data-basis ladder — read it, do not
+   look at a picture of it). Then place **every** listed item in exactly one
+   bucket, using the engine's own names (`apply.ts`, `COVERAGE_BUCKETS`) so the
+   two surfaces read the same. **Nothing enforces that they stay the same** —
+   this is a copied vocabulary, not a shared constant, and no test pins it;
+   renaming a bucket in the engine leaves this list stale and silent:
+
+   | Bucket | Meaning |
+   |---|---|
+   | `honoured` | carried over as-is |
+   | `translated` | carried over in a different shape (a handler became a framework binding) |
+   | `flagged` | **not** carried over — with the reason, in the output |
+
+   Dropping a handler stays allowed; hiding one does not. An item in no bucket
+   is the failure this step exists to catch — "missing JavaScript" is what it
+   looks like from the user's side. Inside the engine this is enforced
+   (`apply.ts`, `COVERAGE_BUCKETS`, an unaccounted item is a halt); out here it
+   is a duty you carry, and nothing checks it for you. (fixture:
+   `daf-adhoc-port-coverage`.)
+4. **Build** — against the audit's primitives, in the project's stack. Where the
+   artifact's own markup/CSS/JS is stack-compatible, adapt **that code**;
+   re-deriving it from scratch is a deviation needing confirmation
+   (`design-fidelity-mechanics` § Adopt the code).
+5. **Review** — run [`design-review`](../design-review/SKILL.md) before calling
    it done, and scope the verdict honestly: render-scoped when you can render
    it, otherwise explicitly static-scoped, naming which checks actually ran.
    "Looks good" with neither scope named is a verdict without evidence.

package/dist/agent-src/skills/judge-synthesis/SKILL.md

@@ -103,6 +103,36 @@ contested.
 Each entry carries **provenance**: which judge(s) raised it. Never merge two
 judges' findings into one unattributed line.
 
+### 4b. Mark an uncited assertion — never drop it
+
+A panelist assertion carrying neither fresh evidence produced this run (a
+`file:line`, a command's output, a diff hunk) nor a citation is **marked
+`uncited`** where it appears. It still ships.
+
+```
+FLAG THE UNCITED ASSERTION. NEVER DROP IT.
+A SUPPRESSED FINDING IS INDISTINGUISHABLE FROM A FINDING NOBODY MADE.
+```
+
+The distinction is load-bearing and it is the reason this is a marking rule
+rather than a filter: an unevidenced assertion may still be the most valuable
+line in the report — a judge noticing something it could not yet prove is
+exactly the signal a human wants. What the reader needs is to know which
+category they are reading, not to be protected from one of them.
+
+**Drop was considered and rejected against this file.** The formulation this
+was adapted from offers "drop or flag"; the drop half contradicts § 4's
+Advisory tier three paragraphs up — *"Emitted in full, never elided … a finding
+that reached a judge and not the reader was suppressed by the aggregator"*.
+Taking it would have put two rules in one skill in direct conflict, with the
+newer one silently winning. Marking satisfies the same goal (the reader can
+tell evidence from assertion) at zero information cost.
+
+Scope: this marks **panelist** assertions inside a synthesis. It does not reach
+the reviewed change, and it is not the `code-provenance` knowledge-layer
+obligation, which governs what a durable artefact asserts rather than what a
+transient review does.
+
 ### 5. Overall recommendation
 
 One sentence, not a number: `block` (any worst-tier verdict), `revise` (any

package/dist/agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -31,6 +31,17 @@ Use this skill when:
   a repeated phase pattern via
   [`extract_audit_patterns.ts`](../../../scripts/extract_audit_patterns.ts)
   — the pattern's `count` ≥ 2 already satisfies the repetition gate
+* A comparative analysis handed over a **`### SEED —` block** from its
+  `## Seeds` section ([`/analyze:reference-repo`](../../agent-src/commands/analyze/reference-repo.md)
+  § 6). This is an accepted intake shape: the block already carries the
+  proposed name, kind, target template, one-line description, and the
+  `Extends instead?` answer, so step 4's overlap search starts from a stated
+  candidate rather than a blank page — it does **not** skip that search, and a
+  seed whose `Extends instead?` line is missing is incomplete intake, not a
+  shortcut. The repetition gate is satisfied differently here: the evidence is
+  the anchored ADOPT/ADAPT verdict behind the seed rather than a recurrence
+  count — a mechanism confirmed once against a named own-repo defect is not the
+  one-off case the gate exists to filter.
 
 Do not use this skill when:
 

package/dist/agent-src/skills/roadmap-writing/SKILL.md

@@ -152,14 +152,14 @@ Sign-off" phases are authoring bugs; replace each with an
 agent-verifiable check (a command, a targeted test, a grep). Never
 restate run-time safety floors as steps.
 
-Gate-test before any checkpoint: *"Could the agent clear this with a
-tool or command during the run?"* Yes → step, not gate. No →
-structured `## Blockers` entry (§ 5b), distinguishing per rule 22:
-**human gate** (only a human can decide/authorize — Hard-Floor
-authorization, billable spend, contested decision) vs **external
-blocker** (agent cannot resolve but CAN probe status — CI run, package
-release, upstream PR; `Resolved when:` carries the probe, owner is
-not a human). Merge is never a completion requirement — it may appear
+Gate-test — three rungs in order (rule 22 owns the detail): **1.** agent-clearable
+by tool/command → step. **2.** has a technical answer a council could reach → still
+a step, first action runs the council; a contested *technical* decision is never a
+human gate while one is configured (`agent-config council:status`). **3.** what
+survives both → `## Blockers` (§ 5b): **human gate** (only a human can
+decide/authorize — Hard-Floor authorization, billable spend, or preference / risk
+appetite / product intent) vs **external blocker** (agent cannot resolve but CAN
+probe status — CI run, package release, upstream PR; `Resolved when:` carries the probe, owner is not a human). Merge is never a completion requirement — it may appear
 as a blocker only when later roadmap work depends on the merged state.
 `lint_roadmap_complexity` warns on human-gate patterns in every mode.
 

package/dist/agent-src/skills/skill-writing/SKILL.md

@@ -102,6 +102,10 @@ Do NOT create a skill or rule for:
 → See `docs/guidelines/agent-infra/size-and-scope.md` for full limits.
 
 * Target: 300–900 words. Review for split above 1200 words. Strongly consider split above 1500 words.
+* Over the 400-line K6 cap → the **router-head contract** in `templates/skill.md`
+  applies: entry head (when-to-use · mode table · routing) plus one `tasks/` or
+  `references/` file per mode, and the head never inlines more than one mode's
+  procedure. Gated by `lint_skill_router_head` with a shrink-only allowlist.
 * If multiple workflows exist → split into multiple skills
 * If two skills overlap heavily → merge
 * If a skill becomes "read the guideline" → it lost its purpose, restore the workflow

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.2.0"
+agent_config_version: "10.4.0"
 
 # --- Project identity ---
 project:

package/dist/agent-src/templates/persona.md

@@ -38,6 +38,32 @@ source: package
   - mode            optional — advisory link to a role-contracts workflow mode
   - version         required — semantic version; bump on breaking changes
   - source          required — "package" for personas shipped in dist/agent-src/
+  - sources         optional — harvest_id list this persona may cite as external
+                    doctrine (provenance/harvests.jsonl). OMIT IT unless you mean
+                    one of the two scoped states; absent is the normal case and
+                    the one every existing persona is in.
+-->
+
+<!-- SOURCES — an epistemic scope, not a bibliography.
+
+  A persona declares a voice. `sources:` optionally declares what that voice is
+  allowed to assert as *external doctrine* — as opposed to its own reasoning,
+  which needs no declaration and is never restricted.
+
+  | State | Meaning |
+  |---|---|
+  | field absent | Unscoped. Today's behaviour for every persona; nothing changes. |
+  | `sources: []` | Explicitly asserts nothing harvested — its positions are its own. |
+  | `sources: [id, …]` | May cite those harvest ids as doctrine. |
+
+  Every declared id must resolve to a row in `provenance/harvests.jsonl`;
+  `lint_harvest_provenance` fails an id that does not. Do NOT invent a row to
+  populate the field — an empty ledger and an absent field is the correct
+  resting state, and `[]` is for a persona where the distinction is worth
+  stating out loud.
+
+  This does not touch the Unique-Questions heuristic. A scoped persona still
+  earns its place by asking what nobody else asks.
 -->
 
 # {Role name}

package/dist/agent-src/templates/roadmaps.md

@@ -197,9 +197,22 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
       "user approves", "looks good", or "sign-off".
     - A **human gate** is allowed only when only a human can **decide or
       authorize**: a Hard-Floor action (deploy, prod data/infra),
-      billable spend, or a contested product / architecture decision.
-      Record it as a structured `## Blockers` entry (rule 20) — never as
-      an inline checkbox step scattered through phases.
+      billable spend, or a decision bound to the user's own preference,
+      risk appetite, or product intent.
+    - A **contested technical decision is not a human gate while a
+      council is configured.** Which design is sound, whether a contract
+      still holds, which of N implementations to pick — these have
+      technical answers, and `decision_resolution` already classes a
+      contract or architecture change as `medium_impact → council`
+      (`docs/contracts/ai-council-config.md`). Authoring them as human
+      gates contradicts that classification and spends the user's
+      attention on a question the council answers. Run it, record the
+      verdict in the phase, and the gate becomes a step.
+      `agent-config council:status` says whether one is configured —
+      never infer it from the project tree (`council-availability`).
+      Record a genuine gate as a structured `## Blockers` entry
+      (rule 20) — never as an inline checkbox step scattered through
+      phases.
     - An **external dependency is a blocker, not a human gate**, whenever
       the agent can probe its status (CI run finished, package version
       published, upstream PR merged, API reachable, DNS propagated):
@@ -216,10 +229,17 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
       `security-sensitive-stop`, and `commit-policy` fire at run time on
       their own; an authored "STOP: confirm with user before X" duplicates
       them and only adds interruptions.
-    Gate-test before writing any checkpoint: *"Could the agent clear this
-    with a tool or command during the run?"* Yes → it is a step, not a
-    gate. No → structured blocker with a decidable `Resolved when:`,
-    owned by a human only when the blocker is a genuine human gate.
+    Gate-test before writing any checkpoint, asked in this order:
+    1. *"Could the agent clear this with a tool or command during the
+       run?"* Yes → it is a step, not a gate.
+    2. *"Does it have a technical answer a council could reach?"* Yes →
+       it is a step whose first action runs the council.
+    3. Only what survives both — preference, risk appetite, product
+       intent, authorization, spend — becomes a structured blocker with
+       a decidable `Resolved when:`, owned by a human.
+    Stopping at question 1 is the authoring bug this ordering exists to
+    prevent: it sends every decision the agent cannot compute straight to
+    the user, including the ones the council exists to answer.
     `task lint-roadmap-complexity` warns on human-gate step patterns,
     human-gate phase headings, and human-approval exit criteria.
 

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/agent-src/templates/skill.md

@@ -207,8 +207,42 @@ Before considering a skill complete, verify it passes all 5 checks:
 - [ ] **K3: No obvious content** — doesn't teach the model what it already knows; only project-specific conventions and non-obvious patterns
 - [ ] **K4: Has Gotcha section** — documents real failure patterns, not theoretical advice; seeded with 2-3 entries
 - [ ] **K5: Has Output format** — numbered list with 2-4 deliverables describing what the skill produces
-- [ ] **K6: Under 400 lines** — if larger, extract reference tables or templates into separate files in the skill folder
+- [ ] **K6: Under 400 lines** — if larger, restructure as a router head per the contract below (gate: `lint_skill_router_head`)
 - [ ] **English only** — all content in English
 - [ ] **No duplication** — doesn't repeat rules or guidelines that are already enforced elsewhere
 - [ ] **No "Related skills" section for mid-tier / untiered skills** — the agent discovers them via `<available_skills>` descriptions; cross-links waste tokens. Senior-tier skills (`tier: senior`) MUST include the block per `skill-quality.md` § Senior-Tier Required Structure (linter-enforced).
 
+## The router-head contract (K6, over the cap)
+
+A `SKILL.md` over the 400-line cap restructures instead of growing. The shape:
+
+| Part | Holds | Budget |
+|---|---|---|
+| **Entry head** — `SKILL.md` | When-to-use · a mode table · the routing that picks a mode · anything true across *all* modes | the cap |
+| **Mode bodies** — `tasks/*.md` or `references/*.md` in the skill folder | One file per mode: the procedure, its examples, its tables | unbudgeted |
+
+One binding constraint on the head: **it never inlines the procedure body for
+more than one mode.** A head that carries mode A in full and points at modes
+B and C has not been restructured — it has been relabelled, and the next edit
+will grow it back.
+
+### What this contract does NOT claim
+
+It does not claim a token win. The host loads `SKILL.md` whole on trigger, and
+whether it then follows a pointer into `tasks/` is host behaviour **nothing in
+this tree observes**. Anyone proposing a retrofit of an existing oversized skill
+on activation grounds is asserting something currently unmeasurable, and
+ADR-202's lesson binds: an activation claim goes behind a measured instrument or
+it is not made.
+
+What the contract does is narrower and real: the 400-line cap was already this
+repo's published position, sitting in a checklist nothing enforced. The gate
+makes an existing contract true for **new** skills. Restructuring the current
+offenders is a separate decision with its own evidence bar.
+
+### Grandfathering
+
+`lint_skill_router_head` carries a shrink-only allowlist seeded with the skills
+that already exceed the cap. Entries may be removed, never added — a new
+oversized monolith fails the gate rather than joining the list.
+