@event4u/agent-config 8.8.0 → 8.10.0

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

@@ -37,53 +37,57 @@ A command is **user-invoked** and carries `disable-model-invocation: true`.
 A skill is model-invoked via description routing. If both audiences apply,
 author as a skill and add a thin command that delegates to it.
 
-**A command must EARN a top-level slot** — only three justifications:
-**flow-entry**, **state-query**, **product-surface**. Else it's a skill.
-Check first: [`command-clusters` § Command justification](../../../docs/contracts/command-clusters.md#command-justification--a-command-must-earn-a-top-level-slot)
+**A command must EARN a top-level slot.** Only three justifications qualify:
+**flow-entry**, **state-query**, or **product-surface** — everything else is a
+skill. Check before authoring: [`command-clusters` § Command justification](../../../docs/contracts/command-clusters.md#command-justification--a-command-must-earn-a-top-level-slot)
 ([ADR-048](../../../docs/decisions/ADR-048-command-justification-rule.md)).
 
-**Categorize at creation (checklist).** New top-level command → declare
-`category:` (schema enum `flow-entry | state-query | product-surface`):
+**Categorize at creation (checklist).** When you author a NEW top-level command,
+declare its justification as a `category:` in the frontmatter — the schema enum
+is `flow-entry | state-query | product-surface`:
 
-- [ ] **flow-entry** — daily work start (`work`, `git-commit`, `review-changes`).
-- [ ] **state-query** — read-only check (`agent-status`, `project-health`, `profile`).
-- [ ] **product-surface** — deliberately-started feature (`council`, `research`, `roadmap`).
-- [ ] **fits none → it's a skill.** Don't add the command.
-- [ ] **ambiguous?** Omit `category:` + note why — OPTIONAL (validate-when-present);
-  deferring is intentional.
+- [ ] **flow-entry** — a daily work starting point the user TYPES to begin
+  (`work`, `git-commit`, `review-changes`).
+- [ ] **state-query** — a read-only check (`agent-status`, `project-health`, `profile`).
+- [ ] **product-surface** — a feature started deliberately (`council`, `research`, `roadmap`).
+- [ ] **fits none → it is a skill.** Don't add the command; author a skill.
+- [ ] **genuinely ambiguous?** Omit `category:` and note why — `category:` is
+  OPTIONAL (validate-when-present); deferring is intentional, not forgotten.
 
-Sub-commands inherit the parent cluster's category — leave `category:` off them.
-Why optional + not yet blocking, + the upgrade trigger:
-[`command-category-governance`](../../../docs/contracts/command-category-governance.md).
+Sub-commands (`council:debate`) inherit the parent cluster's category — leave
+`category:` off them. Why optional + not yet a blocking lint, and what triggers
+the upgrade: [`command-category-governance`](../../../docs/contracts/command-category-governance.md).
 
 ## Commands ARE Claude skills (projection reality)
 
-Every `src/agent-src/commands/{name}.md` projects to
-`.claude/skills/{slug}/SKILL.md` via `scripts/condense.ts`
+Every command in `src/agent-src/commands/{name}.md` is projected
+into `.claude/skills/{slug}/SKILL.md` by `scripts/condense.ts`
 (`generate_claude_commands`). Nested commands flatten with `-`
-(`council/default.md` → `council-default`). Skills + commands share the
+(`council/default.md` → `council-default`). Skills and commands share the
 **same `.claude/skills/` namespace** — Claude does not distinguish them.
 
-Authoring consequences:
-
-* Frontmatter `description` is Claude's **routing surface**. Generic
-  phrasing → undertriggering even with `disable-model-invocation: true`,
-  because the in-host suggester, fuzzy search, and any tooling that
-  scans `.claude/skills/` ranks by description match.
-* `disable-model-invocation: true` blocks **automatic** invocation only.
-  It does NOT remove the command from discovery surfaces. Weak
-  description = invisible to the suggester even when intent matches.
-* Trigger phrasing follows the same Iron Law as skill descriptions:
+Consequences for authoring:
+
+* The frontmatter `description` is the **routing surface** Claude reads.
+  Polite or generic phrasing causes undertriggering even with
+  `disable-model-invocation: true` set, because the in-host command
+  suggester, fuzzy search, and any tooling that scans `.claude/skills/`
+  rank by description match.
+* `disable-model-invocation: true` blocks **automatic** invocation. It
+  does NOT remove the command from discovery surfaces. A weak description
+  means the command is invisible to the suggester even when the user's
+  intent matches.
+* Trigger phrasing must follow the same Iron Law as skill descriptions:
   name 2+ trigger classes (domains, symptoms, user phrasing), end with
   the `... even when the user just says ...` tail, ≤ 200 chars. See
   `skill-writing` § 1b for the canonical before/after.
-* `suggestion.trigger_description` / `suggestion.trigger_context` are
-  **separate** from frontmatter `description` — they drive the in-host
-  suggester (`command-suggestion-policy`), not Claude's skill router.
-  Both matter, both must be precise.
+* The `suggestion.trigger_description` and `suggestion.trigger_context`
+  blocks are **separate** from the frontmatter `description` — they
+  drive the in-host suggester (`command-suggestion-policy`), not Claude's
+  skill router. Both matter, both must be precise.
 
-Bottom line: write the command's `description` as if a skill router
-will read it — because one will.
+Bottom line: write the command's `description` as if a skill router will
+read it — because one will.
 
 ## Procedure
 
@@ -205,9 +209,9 @@ multi-paragraph explanation, extract it into a skill and call it.
 ### 6. Governance baseline (when introducing a new linter check)
 
 **Advisory, reviewer-checked — no CI gate.** When the same PR adds a
-new check to `scripts/skill_linter.ts` (or strengthens an existing one)
-such that previously-clean commands now warn, the PR body MUST record
-the pre-existing violations on `main` in a Markdown table:
+new check to `scripts/skill_linter.ts` (or strengthens an existing
+one) such that previously-clean commands now warn, the PR body MUST
+record the pre-existing violations on `main` in a Markdown table:
 
 ```markdown
 ### Pre-existing baseline (informational)
@@ -217,10 +221,11 @@ the pre-existing violations on `main` in a Markdown table:
 | {new_code} | N | (a) genuine fix · (b) accept · (c) check too aggressive |
 ```
 
-Forward-only: the new check applies to **the file under review** and to
-**future** edits. The baseline table is informational so reviewers can
-spot intent (fix-now vs. backlog) without diffing the full lint output.
-See `agents/evidence/analysis/lint-warning-triage.md` for the 3-bucket reference.
+Forward-only: the new check applies to **the file under review** and
+to **future** edits. The baseline table is informational so reviewers
+can spot intent (fix-now vs. backlog) without diffing the full lint
+output. See `agents/evidence/analysis/lint-warning-triage.md` for the
+3-bucket reference.
 
 ## Output format
 
@@ -299,3 +304,11 @@ Good description (trigger-shaped, outcome-focused):
 Bad description (vague, no outcome):
 
 > "PR command"
+
+## Encode usage policy in the description
+
+Workflow sequencing, preconditions, ID/output provenance ("copy ids verbatim,
+never from memory"), a mandatory "why" intent field, and turn-end contracts
+belong INSIDE this artifact's description/frontmatter — where they fire at the
+decision point — not in always-on prose. See
+[`tool-description-as-policy`](../../../docs/guidelines/agent-infra/tool-description-as-policy.md).

package/dist/agent-src/skills/dashboard-design/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill": "dashboard-design",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "design-metrics-dashboard",
+      "prompt": "Design a metrics dashboard for our SaaS ops team.",
+      "assertions": [
+        {
+          "kind": "rubric",
+          "criterion": "Leads with the decisions the viewer must make, groups metrics by that, uses the right chart per data shape, and avoids vanity metrics."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/dcf-modeling/evals/domain-truth.json

@@ -0,0 +1,29 @@
+{
+  "skill": "dcf-modeling",
+  "domain": "finance",
+  "_note": "Deterministic domain-truth keys computed independently from cited standard DCF formulas (NOT the skill's own output). Authored as maintainer-ratification candidates per road-to-domain-soundness Phase 2 (blocker: domain-competence-for-answer-keys); the Phase-3 run + --write-floor ratchet-pin remain the maintainer's gate.",
+  "cases": [
+    {
+      "id": "gordon-terminal-value",
+      "scenario": "Year-6 free cash flow to the firm (FCFF) = $108M, WACC = 10%, terminal growth g = 2%. Compute the terminal value at the end of year 5 using the Gordon-growth model TV = FCFF_6 / (WACC - g). State the single figure in $M.",
+      "source": "Gordon-growth terminal value: TV = FCFF_{n+1} / (WACC - g) (standard DCF; e.g. Damodaran, 'Investment Valuation').",
+      "check": {
+        "kind": "deterministic",
+        "expected": 1350,
+        "tolerance": 0.5,
+        "rationale": "108 / (0.10 - 0.02) = 108 / 0.08 = 1,350 ($M). Step 1/Step 2 Gordon-growth terminal value."
+      }
+    },
+    {
+      "id": "pv-discount-factor",
+      "scenario": "An FCFF of $200M is received in year 3. WACC = 12%. Compute its present value = 200 / (1.12)^3. State the single figure in $M to two decimals.",
+      "source": "DCF discounting: PV = CF_t / (1 + WACC)^t (standard DCF; Damodaran, 'Investment Valuation').",
+      "check": {
+        "kind": "deterministic",
+        "expected": 142.36,
+        "tolerance": 0.1,
+        "rationale": "1.12^3 = 1.404928; 200 / 1.404928 = 142.36 ($M). Step 2 discounts each FCFF year by 1 / (1 + WACC)^t."
+      }
+    }
+  ]
+}

package/dist/agent-src/skills/dcf-modeling/evals/evals.json

@@ -0,0 +1,20 @@
+{
+  "skill": "dcf-modeling",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "dcf-terminal-value-and-sensitivity",
+      "prompt": "DCF this target: year-6 FCFF $108M, WACC 10%, terminal growth 2%, net debt $200M. Give enterprise + equity value and the discount-rate sensitivity.",
+      "assertions": [
+        {
+          "kind": "contains",
+          "value": "WACC"
+        },
+        {
+          "kind": "rubric",
+          "criterion": "Computes Gordon terminal value = FCFF_{n+1}/(WACC−g) = 108/0.08 = 1350, bridges EV→equity via net debt, and includes a WACC/terminal-growth sensitivity grid — never a single point estimate."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/decision-record/evals/evals.json

@@ -0,0 +1,20 @@
+{
+  "skill": "decision-record",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "record-adr",
+      "prompt": "Record our decision to adopt Postgres over MySQL as an ADR.",
+      "assertions": [
+        {
+          "kind": "contains",
+          "value": "Consequences"
+        },
+        {
+          "kind": "rubric",
+          "criterion": "Uses the ADR shape — Status / Context / Decision / Consequences / Alternatives — and states the trade-off given up, not only the choice."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/deep-reading-analyst/SKILL.md

@@ -114,6 +114,7 @@ Load only the frameworks the user's depth bought. Each framework follows the sam
 **L4 addition:**
 
 - **Cross-source comparison** ([`comparison-matrix`](../../../docs/guidelines/agent-infra/comparison-matrix.md)) — web-search 2–3 related sources, compare SCQA across sources, identify consensus vs divergence, synthesize integrated perspective.
+- **Disconfirmation + per-part grounding (pre-synthesis gate)** — run at least one search that tries to *falsify* the leading takeaway (rule alternatives in/out, not only confirm), and ground each part of the reading goal in a retrieved source before writing it. Distinct from [`verify-before-complete`](../../../src/rules/verify-before-complete.md) (completion evidence).
 
 ### Step 4: Synthesize by Goal
 

package/dist/agent-src/skills/design-intelligence/SKILL.md

@@ -81,6 +81,14 @@ and accessibility. The register changes which corpus selections are appropriate
 (distinctive palette/typography in brand mode; predictable, semantic in product
 mode). State the register in the Design Read line below.
 
+**Embedded vs standalone (a third discriminator).** UI **embedded inside a host
+surface** — a widget in a slide, a card in a chat, a panel in someone else's
+app — follows a **flatter charter** than a greenfield standalone page:
+restrained weights, hairline borders, no atmospherics/gradients/shadows that
+would fight the host. Select the register per surface (embedded → flat;
+standalone → the brand/product register above) — it is a selector, not a fixed
+token set (no values vendored; the host's tokens win).
+
 ## Design Read — articulate intent before generating
 
 Before producing any design brief or making any style selection, emit one
@@ -103,7 +111,8 @@ If `DESIGN.md` declares `## Taste Dials`, use those values. Otherwise infer
 three 1–10 dials from the brief and append them to the Design Read line
 (`… · dials V/M/D = 6/3/4`) so the user can correct them; on confirmation,
 suggest persisting to `DESIGN.md` (via `design-system-capture`). Dials are a
-config, not a vibe — never re-infer when `DESIGN.md` already sets them.
+config, not a vibe — never re-infer when `DESIGN.md` already sets them
+(no drift across sessions).
 
 **Dial Inference Table** (brief signal → Variance / Motion / Density, 1–10):
 
@@ -115,15 +124,15 @@ config, not a vibe — never re-infer when `DESIGN.md` already sets them.
 | data-dense / dashboard / admin / cockpit | 4–6 | 2–3 | 7–9 |
 | bold / playful / expressive / awards / Dribbble | 8–10 | 7–10 | 3–5 |
 
-**Dial → downstream levers:**
+**Dial → downstream levers** (how a dial value changes generation):
 
 | Dial | Low (1–3) | High (8–10) |
 |---|---|---|
 | Variance | symmetric grids, one layout family | asymmetry, varied layout families, off-grid accents |
-| Motion | static / reduced-motion-first, opacity-only | choreographed scroll/stagger (GPU-only, reduced-motion alt) |
-| Density | generous whitespace, large spacing scale | tight spacing scale, more info per viewport |
+| Motion | static / `prefers-reduced-motion`-first, opacity-only | choreographed scroll/stagger (still GPU-only, still reduced-motion alt) |
+| Density | generous whitespace, large spacing scale, few items/viewport | tight spacing scale, more information per viewport |
 
-Dials persist in `DESIGN.md`; stack executors (`tailwind-engineer`,
+Dials persist in `DESIGN.md`; the stack executors (`tailwind-engineer`,
 `react-shadcn-ui`, `blade-ui`, `flux`) read `DESIGN.md` and honour them.
 
 **Anti-Default Discipline — first-impulse check:** Before committing to any design direction, verify you are NOT defaulting to:
@@ -140,12 +149,13 @@ If any of these was the first impulse, name a different direction or explicitly
 When the brief maps to an official design system (Material Design, Fluent,
 Carbon, Polaris, GOV.UK, shadcn, Tailwind UI, Radix, etc.):
 
-0. **Canon grounding first.** Brief names a system OR `components.json`/deps
-   signal one (`@mui/material`, `antd`, `@fluentui/*`, `@carbon/*`,
-   `@atlaskit/*`) → pull
+0. **Canon grounding first.** If the brief names a system OR
+   `components.json`/deps signal one (`@mui/material`, `antd`, `@fluentui/*`,
+   `@carbon/*`, `@atlaskit/*`), pull
    [`docs/guidelines/design-canon.md`](../../../docs/guidelines/design-canon.md),
-   surface the matching one-liner, **offer to fetch the live spec** before
-   committing to the system's conventions. Thin + lazy: skip for a generic brief.
+   surface the matching one-line summary, and **offer to fetch the live spec**
+   before committing to the system's conventions — rather than improvising.
+   The canon index is thin + lazy: do not load it for a generic, unnamed brief.
 1. **Install the real package** — do not hand-recreate its CSS or components.
    Surface the install command for the project's package manager (the
    system's official package, e.g. the shadcn CLI or the `@mui/material`
@@ -158,8 +168,8 @@ Carbon, Polaris, GOV.UK, shadcn, Tailwind UI, Radix, etc.):
    (see Design Read above); never fall back to an unnamed generic aesthetic
    (per `source-discovery-gate`: real source before guessing).
 
-**Grounding precedence** (per `brand-source-of-truth`): consumer brand tokens >
-confirmed session decisions > named canon
+**Grounding precedence** (consistent with `brand-source-of-truth`): consumer
+brand tokens > confirmed session decisions > named canon
 ([`design-canon.md`](../../../docs/guidelines/design-canon.md)) > generated
 corpus. Canon is a gap-filler, never an override of a registered brand value.
 
@@ -267,6 +277,33 @@ guidance + docs URLs from here instead of memory.
   already covers — audit findings outrank corpus suggestions.
 - Do NOT hide low confidence — the user signs off on the gaps too.
 
+## Diagram-type routing — route on the verb
+
+Choose a visualization by the *intent verb*, not the noun. Count the nouns
+before you draw (input-complexity triage): 1–2 → inline prose or a single
+shape; 3–7 → one diagram; 8+ → split or summarize, never one dense picture.
+
+| The user asks… | Intent | Draw |
+|---|---|---|
+| "how does X **work** / flow" | illustrative (intuition) | flowchart / sequence — illustrative default |
+| "what is X's **architecture** / structure" | reference (structural) | structural diagram (boxes + typed edges) |
+| a **cycle** / loop / lifecycle | — | a **stepper widget**, never a hand-drawn ring |
+| a **DB schema / ERD** / entity relations | — | **mermaid**, never hand-placed SVG |
+
+### Geometric pre-checks (run BEFORE finalizing an SVG/diagram)
+
+Ranked by failure rate — procedures, not constants:
+
+1. **viewBox safety** — compute the lowest + rightmost element (plus a buffer)
+   and set the viewBox from that; never assume the default fits.
+2. **arrow-through-box trace** — trace every arrow's path and confirm it does
+   not cross through an unrelated box before drawing it.
+3. **box-width-from-longest-label** — size each box from its longest label
+   before placing it, so text never overflows.
+
+(Reference-only: any color/easing/frame values come from the consumer's tokens
+or a maintained upstream — this skill vendors no drawn-asset corpus.)
+
 ## Interplay (who owns what)
 
 | Concern | Owner |

package/dist/agent-src/skills/design-intelligence/evals/evals.json

@@ -0,0 +1,14 @@
+{
+  "skill": "design-intelligence",
+  "_calibration": "Behavioural fixtures (road-to-skill-eval-coverage Phase 2, rich set). Deterministic `contains` asserts the WCAG-checked-token property the skill promises; the rubric (pinned-judge known-limit) checks the corpus-grounding — a grounded brief names a concrete style/palette/type decision, not arbitrary taste.",
+  "scenarios": [
+    {
+      "id": "grounded-brief-fintech-dashboard",
+      "prompt": "Give me a grounded design brief (style, color tokens, typography, layout pattern) for a serious fintech analytics dashboard. Justify the palette's contrast.",
+      "assertions": [
+        { "kind": "contains", "value": "WCAG" },
+        { "kind": "rubric", "criterion": "Selects a concrete named style/archetype + a specific palette and type pairing grounded in the design corpus (not arbitrary), and states at least one anti-pattern to avoid." }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/design-review/SKILL.md

@@ -13,6 +13,12 @@ packs:
 
 ## When to use
 
+> **Render-verification gate.** A UI verdict is gated on the
+> [design-artifact verification checklist](../../../docs/contracts/design-artifact-verification.md#verification-checklist):
+> where render capability exists, do not pass a design task without render
+> evidence (checklist steps 1–5); where it is absent, scope the verdict to what
+> was statically checked and say so — never "looks good" without evidence.
+
 Use this skill when:
 - Reviewing pull requests with UI changes
 - Auditing frontend components for design quality
@@ -279,6 +285,18 @@ This is especially useful when the user provides a screenshot or Figma export as
 - WCAG
 - responsive
 
+## Async-verifier pattern (keep the main context clean)
+
+For a review that needs browser probing, use an **async background verifier**
+rather than self-screenshotting inline: fork a verifier subagent with its own
+view — it takes the screenshots, probes viewports, and checks states, then
+**stays silent on pass and surfaces only real, actionable problems** (never
+nitpicks). The main agent does not self-screenshot, so its context stays clean
+for the actual review reasoning. This is an orchestration pattern —
+dispatch it via [`subagent-orchestration`](../subagent-orchestration/SKILL.md)
+and position it against [`verify-repair-loop`](../verify-repair-loop/SKILL.md)
+(the existing verify skill); it complements them, it does not duplicate them.
+
 ## Gotcha
 
 - Don't review design without understanding the user's constraints (time, resources, scope).
@@ -289,27 +307,29 @@ This is especially useful when the user provides a screenshot or Figma export as
 
 Hybrid: a deterministic detector does the mechanical pattern-matching (zero
 token cost, no catalog reload); you do the judgment it cannot. After the
-structured phases, add an **Anti-Slop Check** section:
+structured review phases, add an explicit **Anti-Slop Check** section:
 
-1. **Run the detector first** — catches pattern-detectable tells so you don't
-   eyeball or re-derive:
+1. **Run the deterministic detector first** — it catches the pattern-detectable
+   tells so you don't eyeball or re-derive them:
    ```
    npx tsx src/scripts/lint_design_slop.ts --dir <consumer-ui-path> --json
    ```
-   Each finding: `rule` (`slop-v1-side-stripe`), `catalogId` (`V1`), `severity`
-   (`P0`–`P3`), `file:line`, `message`. **Cite verbatim** — don't re-describe
-   from the catalog. Findings are *rebuttable presumptions*: a `DESIGN.md`-gated
-   finding is already filtered; a remaining one means intent not declared.
-   `lint_design_slop` is **flags, never a block** (default exit 0; CI opts in via
-   `--fail-on`).
+   Each finding carries `rule` (e.g. `slop-v1-side-stripe`), `catalogId`
+   (`V1`), `severity` (`P0`–`P3`), `file:line`, and a `message`. **Cite these
+   verbatim** (rule-id + catalogId + file:line) — do not re-describe them from
+   the prose catalog. Findings are *rebuttable presumptions*: a finding the
+   consumer's `DESIGN.md` gate suppresses is already filtered out; a remaining
+   finding means the project has not declared the pattern as intentional.
+   `lint_design_slop` is **flags, never a block** (default exit 0; CI opts into
+   failure via `--fail-on`).
 2. **Judge what the detector cannot** — load
    [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
-   for tells needing structural/aesthetic judgment (T3 icon-tile stack, L2
-   three-identical-card grid, V2 glassmorphism intent). List any, cite by entry
-   ID, check the override.
-3. Run the AI-slop originality self-test on the overall direction. Report
-   pass / flag / fail + one sentence of evidence — the judgment the detector
-   does not make.
+   for the tells that need structural/aesthetic judgment (e.g. T3 icon-tile
+   stack, L2 three-identical-card grid, V2 glassmorphism intent). List any that
+   appear, cite by entry ID, and check the override condition.
+3. Run the AI-slop originality self-test on the overall aesthetic direction.
+   Report the result (pass / flag / fail) with one sentence of evidence — this
+   is the human judgment the detector deliberately does not make.
 
 For the **objective quality floors** (WCAG contrast, font-size, line-length,
 reduced-motion, heading hierarchy, focus indicator), do NOT eyeball them —

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

@@ -194,30 +194,37 @@ Example: "Dashboard = control panel for power users, not an exploration space."
 
 ## Importing an extracted design system
 
-A consumer reverse-engineers an existing site/repo with any external static tool
-and hands the result here as a `design-system.json`. We own the **import
-contract**, not the crawler — the package never ships the Playwright runtime, a
-font-bundler, or a `.skill` auto-installer (out of scope). Full schema lazy from
-[`reference/design-system-json.md`](reference/design-system-json.md); read only
-on import.
-
-Import procedure:
-
-1. Read `design-system.json`; reject if `source` (kind + ref + captured_at) is
-   missing — no provenance, no import.
-2. Diff every field vs the current `DESIGN.md`.
-3. **Per-field confirm/merge proposal** — observed, not authoritative (mirrors
-   `source-discovery`); never write silently.
-4. Conflict with a registered brand value (confirmed `.tokens.json` / brand
-   token) → **flag, never auto-apply** (`brand-source-of-truth`). Precedence:
-   brand tokens > confirmed `DESIGN.md` > imported observation.
-5. On accept, persist chosen fields; hand mapped DTCG fields to
-   [`brand-to-tokens`](../brand-to-tokens/SKILL.md) / `design-tokens` for
-   `.tokens.json` — no parallel token format.
-
-Two sources, one shape: external target → external tool emits the artifact;
-current repo → prefer [`existing-ui-audit`](../existing-ui-audit/SKILL.md), which
-emits the same shape.
+A consumer can reverse-engineer an existing site/repo's look-and-feel with any
+external static-extraction tool and hand the result to this skill as a
+`design-system.json` artifact. We own the **import contract**, not the crawler:
+the package never ships the Playwright runtime, a font-bundler, or a `.skill`
+auto-installer (out of scope). Full schema is lazy-loaded from
+[`reference/design-system-json.md`](reference/design-system-json.md) — read it
+only when an import is requested.
+
+**Import procedure:**
+
+1. Read `design-system.json`; reject it if `source` (kind + ref + captured_at)
+   is missing — no provenance, no import.
+2. Diff every field against the current `DESIGN.md`.
+3. Surface a **per-field confirm/merge proposal** — the artifact is *observed,
+   not authoritative* (mirrors `source-discovery`). Never write silently.
+4. **Conflict with a registered brand value** (a confirmed `.tokens.json` /
+   brand token) → **flag, never auto-apply** (`brand-source-of-truth`:
+   consumer brand wins). Precedence: brand tokens > confirmed `DESIGN.md` >
+   imported observation.
+5. On the human's accept, persist the chosen fields into `DESIGN.md`. Where the
+   consumer wants a token source of truth, hand the mapped DTCG fields to
+   [`brand-to-tokens`](../brand-to-tokens/SKILL.md) / `design-tokens` to
+   materialise `.tokens.json` — do not invent a parallel token format.
+
+**Two sources, one shape:**
+
+- **External target** (a site/repo you don't own) → an external tool emits the
+  artifact; import it here.
+- **Current repo** → prefer [`existing-ui-audit`](../existing-ui-audit/SKILL.md);
+  it already inventories the codebase and can emit the same `design-system.json`
+  shape, so the import path is identical either way.
 
 ## How the design skills consume these documents
 
@@ -237,6 +244,59 @@ The boundary from `brand-to-tokens`:
   not 4px or 12px)
 Both are consumed together; DESIGN.md takes precedence for usage questions.
 
+## Design→dev handoff README (template)
+
+When handing a design to implementation, emit a README a developer can build
+from **without the mockup open**. Template only — no vendored values (tokens
+come from the consumer's `.tokens.json` / DESIGN.md):
+
+```markdown
+# <Feature> — implementation handoff
+
+Fidelity: <hi-fi = pixel-recreate the mockup | lo-fi = apply the codebase's
+          existing design system, mockup is directional only>
+
+## Screens
+- <screen>: components used + each component's states (default/hover/active/
+  disabled/empty/error/loading)
+
+## Interactions
+- <interaction>: trigger → result, duration + easing (name the token, not a ms
+  literal)
+
+## Tokens
+- Color / type / spacing / radius: reference DESIGN.md / .tokens.json — do not
+  inline hex or px
+
+## Done means
+- Implementable from this README alone; every state and interaction named.
+```
+
+Fidelity declaration is load-bearing: hi-fi vs lo-fi tells the dev whether to
+recreate the mockup pixel-for-pixel or apply the existing system — the single
+most common handoff ambiguity.
+
+## Design-system extraction floor
+
+When the goal is to extract this repo's design system as a **reusable package
+artifact** (not just DESIGN.md prose), the extraction meets this floor — the
+handoff shape emitted alongside `design-system.json`
+([import contract](reference/design-system-json.md)).
+
+- **Contract contents.** A complete extraction carries: a root guide / manifest;
+  token CSS (or the stack's equivalent); the typography / colour / spacing /
+  iconography foundations; component specimens; an asset inventory (logos, icons,
+  fonts); UI-kit screens; and starting-point templates where appropriate.
+- **Specimen granularity.** Many small foundation cards beat one dense dump —
+  each specimen demonstrates ONE reusable sub-concept (a single button state,
+  one spacing step, one elevation level), so a consumer lifts concepts
+  individually rather than parsing a monolith.
+- **Developer handoff bundle** (extends § Design→dev handoff README): a
+  high-fidelity reference, behaviour notes, the assets list, the component
+  mapping (design name → code component), responsive states, known caveats, and
+  — when the artifact is a mock — an explicit "prototype, not production code"
+  warning so a consumer never ships the reference verbatim.
+
 ## Gotcha
 
 - **Over-writing instead of diff-updating** — the most common failure.

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

@@ -0,0 +1,15 @@
+{
+  "skill": "design-system-capture",
+  "_calibration": "Behavioural fixtures (road-to-skill-eval-coverage Phase 2, rich set). Deterministic `contains` asserts the two artifacts the skill's contract maintains (DESIGN.md + PRODUCT.md); the rubric checks it captures decisions rather than re-describing generic guidance.",
+  "scenarios": [
+    {
+      "id": "capture-from-repo",
+      "prompt": "Capture this project's design system so future sessions stay consistent: it uses a 4px spacing grid, 8px radius, a spring motion strategy, and a blue primary. Where do these decisions go?",
+      "assertions": [
+        { "kind": "contains", "value": "DESIGN.md" },
+        { "kind": "contains", "value": "PRODUCT.md" },
+        { "kind": "rubric", "criterion": "Routes the visual decisions (spacing/radius/motion/color) into DESIGN.md and interaction patterns into PRODUCT.md, and flags any TBD rather than inventing values." }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/developer-like-execution/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill": "developer-like-execution",
+  "_calibration": "Behavioural fixture (road-to-skill-eval-coverage Phase 2, default-surface). Deterministic assertions on a real output property where reliable; rubric pins the qualitative core as a known-limit (pass ratified in PR review, not a hidden judge). finding_floor n is a conservative floor, not a calibrated per-host number.",
+  "scenarios": [
+    {
+      "id": "execute-like-dev",
+      "prompt": "Implement this small change end-to-end the way a senior would.",
+      "assertions": [
+        {
+          "kind": "rubric",
+          "criterion": "Reads before editing, keeps the diff minimal + scoped, updates downstream callers/tests, and verifies with a real run before claiming done."
+        }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/doc-coauthoring/SKILL.md

@@ -13,6 +13,12 @@ packs:
 
 ## When to use
 
+> **Cross-surface handoff.** When this document consumes upstream work (research
+> → document, spreadsheet → report), read the handoff envelope from
+> [`surface-agent-contracts`](../../../docs/contracts/surface-agent-contracts.md#cross-surface-handoff-envelope):
+> trust `verification_already_done`, honour source restrictions, and don't
+> re-fetch what the source already grounded.
+
 Use this skill when:
 
 * User starts a substantial writing task — PRD, RFC, design doc, decision doc, technical spec, proposal
@@ -40,6 +46,27 @@ Move from a fuzzy ask to a complete document the user owns, by:
 * `save-file` and `str-replace-editor` available
 * Target path and filename agreed up front
 
+## Document format & export floor
+
+The document surface's floor (per
+[`surface-agent-contracts`](../../../docs/contracts/surface-agent-contracts.md)):
+
+- **Choose the format by intent.** Markdown vs `.docx` vs PDF follows what the
+  user will DO with it — when a named format is requested, produce THAT format
+  via the document tooling; never silently substitute markdown for a `.docx`
+  request. (fixture: `ssac-docx-requested-markdown-only`.)
+- **Preserve edit scope.** On an edit, change only what was asked and preserve
+  the rest of the document (mirrors
+  [`minimal-safe-diff`](../../rules/minimal-safe-diff.md)).
+- **Print/PDF preserves selectable text.** Never rasterize a text-heavy document
+  to an image-only PDF when browser print or native export keeps the text
+  selectable. (fixture: `ssac-pdf-screenshot-rasterized`.)
+- **Verify the output opens/exports.** Confirm the generated file opens /
+  round-trips
+  ([`design-artifact-verification`](../../../docs/contracts/design-artifact-verification.md));
+  where the format's tooling is absent, ship the source + say what could not be
+  verified rather than claiming a produced file.
+
 ## Procedure
 
 ### 0. Inspect existing material