@event4u/agent-config 16.1.0 → 16.3.0

package/dist/agent-src/scripts/deferral_carry.ts

@@ -0,0 +1,339 @@
+/**
+ * Auto-carry for the archival sweep: a finished roadmap whose only obstacle is
+ * bare `[~]` steps hands them to a follow-up roadmap and then archives.
+ *
+ * WHY. The dashboard renders a roadmap with zero open steps as 100 %, deferred
+ * steps included, while the sweep refused every bare `[~]` and waited for a
+ * human to write the `carried-to` annotation by hand. Nobody did: measured
+ * 2026-10-02, five roadmaps sat at 100 % in the active tree with fourteen
+ * unannotated deferrals between them, and `/roadmap:process-full` — which ends
+ * non-interactively — had no step that could resolve one. "Finished" and
+ * "archived" had silently come apart.
+ *
+ * The disposition this module executes is the one `roadmap-progress-sync`
+ * Iron Law 3 already routes to the council without the owner: carry the item
+ * AND its blocker into a named follow-up created in the SAME change. It keeps
+ * every criterion alive in the active estate, so it is the preserving branch of
+ * the preservation test, never a drop. The owner decided on 2026-10-02 that the
+ * sweep performs it automatically instead of waiting for a menu.
+ *
+ * What the carry does, so the archived parent and the live child agree:
+ *
+ *   - every bare `[~]` block is copied verbatim into the child as an OPEN `[ ]`
+ *     step — open, not `[~]`, because a child at 100 % on arrival would be
+ *     carried again by the next sweep, forever;
+ *   - the parent's step gets `<!-- deferred-resolution: carried-to=<child> -->`,
+ *     and the child gets `parent_roadmap: <parent>`, which is the pair
+ *     `deferralProblems` and `lint_deferral_integrity` validate from both ends;
+ *   - every OPEN blocker a carried step names via `blocked-by: <id>` moves with
+ *     it: copied verbatim into the child's `## Blockers`, and closed in the
+ *     parent with a status line naming where it went. The open-blocker count is
+ *     unchanged, it only changes file.
+ *
+ * NOT automatic when a moved blocker waits on the OWNER (owner decision
+ * 2026-10-02): the sweep then writes nothing and asks — archive with the steps
+ * parked in `later/` (`--owner-decision later`), or work them step by step with
+ * the first one on screen. The procedure lives in `roadmap-process-loop` § 6a.
+ *
+ * Refused, so nothing is written, when the parent would still not archive
+ * afterwards: an open blocker no carried step names is a decision the parent
+ * itself raised, and carrying around it would strand the child with steps that
+ * have no reason to exist apart from the parent. A human-written annotation
+ * that fails validation is also left alone — fixing someone's wrong carry is
+ * not this module's call.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * `<!-- deferred-resolution: carried-to=<slug> -->` — the resolved-deferral
+ * annotation. `merged-into=<slug>` is the second accepted form.
+ */
+export const DEFERRED_RESOLUTION_RE =
+    /<!--\s*deferred-resolution:\s*(carried-to|merged-into)\s*=\s*([A-Za-z0-9._-]+)\s*-->/;
+
+/** `- [~] …` — a deferred step, at any indent, with `-` or `*`. */
+export const DEFERRED_STEP_RE = /^[ \t]*[-*][ \t]+\[~\][ \t]*(.*)$/;
+
+/** Any other checkbox, or a heading — where a step's block ends. */
+export const BLOCK_END_RE = /^[ \t]*[-*][ \t]+\[[ xX~-]\]|^#{1,6}[ \t]/;
+
+const BLOCKED_BY_RE = /blocked-by:\s*([A-Za-z0-9._-]+)/g;
+const BLOCKER_HEAD_RE = /^###[ \t]+blocker:[ \t]*(.+?)[ \t]*$/i;
+const STATUS_LINE_RE = /^([ \t]*-[ \t]+\*\*Status:\*\*[ \t]*)(.*)$/;
+const AC_HEADING_RE = /^##[ \t]+acceptance/i;
+const OWNER_LINE_RE = /^[ \t]*-[ \t]+\*\*Owner:\*\*[ \t]*`?([A-Za-z]+)/;
+
+/**
+ * Blocker owners that are NOT the human owner. Everything else — `maintainer`,
+ * `user`, `owner`, and any value this list does not name — is owner-dependent:
+ * in doubt it is the owner's decision, so an unrecognised owner fails closed.
+ */
+const AGENT_SIDE_OWNERS: ReadonlySet<string> = new Set(['implementer', 'council', 'agent', 'ai']);
+
+/**
+ * What happens to deferrals whose blockers wait on the owner.
+ *
+ * `ask` (default): nothing is written; the sweep reports the decision instead —
+ * archive with the steps parked in `later/`, or work them step by step.
+ * `later`: the owner chose to archive; the carry lands in `later/`.
+ */
+export type OwnerDecision = 'ask' | 'later';
+
+/** The lightweight cap `lint_roadmap_complexity` enforces, with margin. */
+const LIGHTWEIGHT_LINE_BUDGET = 500;
+
+const DISPOSITION_DIRS: readonly string[] = ['', 'later', 'archive', 'skipped'];
+
+interface BareStep {
+    /** Line index of the `[~]` line in the parent. */
+    line: number;
+    /** The step line plus its continuation block, dedented to the step. */
+    block: string[];
+    isAcceptance: boolean;
+    blockerIds: string[];
+}
+
+interface BlockerSpan {
+    id: string;
+    start: number;
+    end: number;
+    open: boolean;
+    ownerDependent: boolean;
+}
+
+export interface CarryPlan {
+    destSlug: string;
+    destRel: string;
+    destText: string;
+    sourceText: string;
+    carried: number;
+    movedBlockers: string[];
+    /** Moved blockers only the owner can resolve. Non-empty ⇒ the owner decides. */
+    ownerBlockers: string[];
+    /** The first carried step, verbatim, for the step-by-step offer. */
+    firstStep: string;
+    /** True when the carry targets `later/` (owner chose to archive). */
+    parked: boolean;
+}
+
+export type CarryOutcome = { plan: CarryPlan } | { refused: string };
+
+function _bareSteps(lines: readonly string[]): BareStep[] {
+    const out: BareStep[] = [];
+    let inAcceptance = false;
+    // No fence skipping, on purpose: `parseDeferredItems` does not skip fences
+    // either, and a step this module did not see but the sweep's validation does
+    // would be written, then refused.
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] as string;
+        if (/^##[ \t]/.test(line)) inAcceptance = AC_HEADING_RE.test(line);
+        const m = DEFERRED_STEP_RE.exec(line);
+        if (m === null) continue;
+        let end = i + 1;
+        while (end < lines.length && !BLOCK_END_RE.test(lines[end] as string)) end++;
+        const raw = lines.slice(i, end);
+        if (DEFERRED_RESOLUTION_RE.test(raw.join('\n'))) continue;
+        while (raw.length > 1 && (raw[raw.length - 1] as string).trim() === '') raw.pop();
+        const indent = (/^[ \t]*/.exec(line) as RegExpExecArray)[0].length;
+        const block = raw.map((l) => (l.slice(0, indent).trim() === '' ? l.slice(indent) : l));
+        const ids = new Set<string>();
+        for (const b of raw) for (const hit of b.matchAll(BLOCKED_BY_RE)) ids.add(hit[1] as string);
+        out.push({ line: i, block, isAcceptance: inAcceptance, blockerIds: [...ids] });
+    }
+    return out;
+}
+
+function _blockerSpans(lines: readonly string[]): BlockerSpan[] {
+    const start = lines.findIndex((l) => /^##[ \t]+Blockers[ \t]*$/i.test(l));
+    if (start === -1) return [];
+    let sectionEnd = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^##[ \t]+\S/.test(lines[i] as string)) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    const spans: BlockerSpan[] = [];
+    for (let i = start + 1; i < sectionEnd; i++) {
+        const m = BLOCKER_HEAD_RE.exec(lines[i] as string);
+        if (m === null) continue;
+        let end = i + 1;
+        while (end < sectionEnd && !/^###?[ \t]/.test(lines[end] as string)) end++;
+        const status = lines
+            .slice(i, end)
+            .map((l) => STATUS_LINE_RE.exec(l))
+            .find((s) => s !== null);
+        const value = (status?.[2] ?? 'open').trim().toLowerCase();
+        const owner = lines
+            .slice(i, end)
+            .map((l) => OWNER_LINE_RE.exec(l))
+            .find((o) => o !== null);
+        spans.push({
+            id: (m[1] as string).trim(),
+            start: i,
+            end,
+            open: !/^resolved\b/.test(value),
+            ownerDependent: !AGENT_SIDE_OWNERS.has((owner?.[1] ?? '').toLowerCase()),
+        });
+    }
+    return spans;
+}
+
+function _plusDays(date: string, days: number): string {
+    const d = new Date(`${date}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + days);
+    return d.toISOString().slice(0, 10);
+}
+
+/** The first `<base>-carried[-N]` slug no roadmap directory already holds. */
+export function nextCarrySlug(root: string, sourceSlug: string): string {
+    const base = sourceSlug.replace(/-carried(-\d+)?$/, '');
+    for (let n = 1; ; n++) {
+        const slug = n === 1 ? `${base}-carried` : `${base}-carried-${n}`;
+        const taken = DISPOSITION_DIRS.some((d) =>
+            fs.existsSync(path.join(root, 'agents', 'roadmaps', d, `${slug}.md`)),
+        );
+        if (!taken) return slug;
+    }
+}
+
+function _title(sourceText: string, sourceSlug: string): string {
+    const h1 = /^#[ \t]+(.+?)[ \t]*$/m.exec(sourceText.replace(/^---\n[\s\S]*?\n---\n/, ''));
+    return h1 !== null ? (h1[1] as string) : sourceSlug.replace(/-/g, ' ');
+}
+
+/**
+ * Plan the carry for one roadmap. Pure apart from reading which slugs exist, so
+ * the sweep can decide before it writes anything.
+ *
+ * @param openBlockerIds every OPEN blocker the parent carries, as `collect()`
+ *   counts them — the source of truth for "would it archive afterwards".
+ */
+export function planCarry(
+    root: string,
+    rel: string,
+    text: string,
+    openBlockerIds: readonly string[],
+    date: string,
+    ownerDecision: OwnerDecision = 'ask',
+): CarryOutcome {
+    const sourceSlug = rel.replace(/\.md$/, '');
+    const lines = text.split('\n');
+    const steps = _bareSteps(lines);
+    if (steps.length === 0) return { refused: 'no bare `[~]` step to carry' };
+
+    const named = new Set(steps.flatMap((s) => s.blockerIds));
+    const stranded = openBlockerIds.filter((id) => !named.has(id));
+    if (stranded.length > 0) {
+        return {
+            refused:
+                `open blocker(s) no deferred step names (${stranded.join(', ')}) — ` +
+                'carrying around them would not let this roadmap archive',
+        };
+    }
+    const moved = _blockerSpans(lines).filter((b) => b.open && named.has(b.id));
+    const ownerBlockers = moved.filter((b) => b.ownerDependent).map((b) => b.id);
+    const parked = ownerBlockers.length > 0 && ownerDecision === 'later';
+
+    const destSlug = nextCarrySlug(root, sourceSlug);
+    const annotation = `<!-- deferred-resolution: carried-to=${destSlug} -->`;
+
+    const out = [...lines];
+    for (const b of moved) {
+        for (let i = b.start; i < b.end; i++) {
+            const s = STATUS_LINE_RE.exec(out[i] as string);
+            if (s === null) continue;
+            out[i] =
+                `${s[1] as string}resolved — carried, still open, to \`${destSlug}\` ` +
+                `with the steps it blocks (was: ${(s[2] as string).trim()})`;
+            break;
+        }
+    }
+    for (const s of steps) out[s.line] = `${out[s.line] as string} ${annotation}`;
+
+    const toOpen = (block: readonly string[]): string =>
+        block.map((l, i) => (i === 0 ? l.replace(/\[~\]/, '[ ]') : l)).join('\n');
+    const phaseSteps = steps.filter((s) => !s.isAcceptance).map((s) => toOpen(s.block));
+    const acSteps = steps.filter((s) => s.isAcceptance).map((s) => toOpen(s.block));
+    const phaseName = `Deferred steps carried from ${sourceSlug}`;
+    const blockerText = moved.map((b) => lines.slice(b.start, b.end).join('\n').trimEnd());
+
+    const body = [
+        `# ${_title(text, sourceSlug)} — carried`,
+        '',
+        `> **Source:** carried by the archival sweep on ${date} from`,
+        `> [\`${sourceSlug}\`](${parked ? '../' : ''}archive/${sourceSlug}.md), which closed every other step.`,
+        '> Each step below was `[~]` there and is restated verbatim as open work, so',
+        '> archiving the parent buried nothing. Blockers the steps name moved with them.',
+        '',
+        '## Goal',
+        '',
+        `Every step ${sourceSlug} deferred is either done here or explicitly disposed`,
+        'of — a step that still cannot run is re-deferred with its reason, never',
+        'left to read as finished.',
+        '',
+        `## Phase 1 — ${phaseName}`,
+        '',
+        phaseSteps.length > 0
+            ? phaseSteps.join('\n')
+            : '- [ ] **1.1 Close the carried acceptance criteria below.** The parent deferred\n' +
+              '      only acceptance criteria; this step is done when each is checked or disposed of.\n' +
+              '      verify: every criterion under `## Acceptance Criteria` is `[x]` or `[-]`',
+        '',
+        ...(blockerText.length > 0 ? ['## Blockers', '', blockerText.join('\n\n'), ''] : []),
+        '## Risk Register',
+        `<!-- risk-review: v1 | reviewed: ${date} | reviewer: archive-sweep/auto-carry -->`,
+        '',
+        '| Rank | Item | Risk type | Description | Mitigation | Anchored under |',
+        '|------|------|-----------|-------------|------------|----------------|',
+        '| 1 | Carried steps stay blocked indefinitely | implementation | A step deferred ' +
+            'once for elapsed time or a decision can sit here as long as it sat in the parent | ' +
+            'It now counts as open work in the dashboard instead of as 100 %, and its blocker ' +
+            `is listed where the estate gates count it | Phase 1 — ${phaseName} |`,
+        '',
+        '## Acceptance Criteria',
+        '',
+        acSteps.length > 0
+            ? acSteps.join('\n')
+            : `- [ ] AC-1 — No step carried from \`${sourceSlug}\` is still \`[ ]\` without a recorded disposition.`,
+        '',
+    ].join('\n');
+    const complexity = body.split('\n').length > LIGHTWEIGHT_LINE_BUDGET ? 'structural' : 'lightweight';
+    // Parked: `status: later` plus the three-part `entry_condition:` mapping
+    // `lint_roadmap_later_disposition` requires, and the growth claim the
+    // `later_roadmaps` count needs — a new file in `later/` is not a parking
+    // move, so no allowance covers it otherwise.
+    const ids = ownerBlockers.join(', ');
+    const parkedKeys = parked
+        ? 'entry_condition:\n' +
+          `  what: the owner resolves blocker(s) ${ids}\n` +
+          '  when: whenever the owner takes the next step\n' +
+          '  who: owner\n' +
+          // `lint_roadmap_later_disposition` rule C: a park with no review date
+          // reads exactly like an abandonment.
+          `review_by: ${_plusDays(date, 90)}\n` +
+          `estate_growth_exempt: >-\n  Owner-chosen archive of ${sourceSlug}: its deferred steps wait on owner\n` +
+          `  blocker(s) ${ids} and are parked here instead of left active. The parent\n` +
+          '  is archived in the same change, so the active count drops by one.\n'
+        : '';
+    const destText =
+        `---\ncomplexity: ${complexity}\nstatus: ${parked ? 'later' : 'ready'}\nexecution:\n  mode: phase-checkpoints\n` +
+        `parent_roadmap: ${sourceSlug}\n${parkedKeys}---\n${body}`;
+    const destRel = parked ? `agents/roadmaps/later/${destSlug}.md` : `agents/roadmaps/${destSlug}.md`;
+
+    return {
+        plan: {
+            destSlug,
+            destRel,
+            destText,
+            sourceText: out.join('\n'),
+            carried: steps.length,
+            movedBlockers: moved.map((b) => b.id),
+            ownerBlockers,
+            firstStep: (steps[0] as BareStep).block.join('\n'),
+            parked,
+        },
+    };
+}

package/dist/agent-src/scripts/update_roadmap_progress.ts

@@ -1351,7 +1351,10 @@ function main(argv?: readonly string[]): number {
     // leaves behind rather than the one it found. `--check` never archives: a
     // gate that mutates the tree it is checking cannot be trusted by CI.
     let sweep_out = '';
-    if (!args.check && args.archive && unarchived_complete(collect(roadmap_root)).length > 0) {
+    // `pending_iron_law_3` too: a 100 % roadmap with bare `[~]` steps is what the
+    // sweep's carry exists for, and gating on `deferred === 0` never spawned it.
+    const before = collect(roadmap_root);
+    if (!args.check && args.archive && unarchived_complete(before).length + pending_iron_law_3(before).length > 0) {
         const swept = run_archival_sweep(repo_root);
         sweep_out = swept.stdout;
         if (swept.stderr) {

package/dist/agent-src/skills/accessibility-auditor/data/aria-patterns.csv

@@ -3,7 +3,7 @@ Modal dialog,modal dialog overlay popup confirm,dialog role + aria-modal,"role=d
 Combobox / autocomplete,combobox autocomplete select search suggest dropdown,combobox + listbox popup,"role=combobox aria-expanded aria-controls aria-activedescendant; Down opens list, Enter selects, Esc closes; results announced via live region count","WCAG 4.1.2, 1.3.1",Re-implementing as div+onclick without keyboard model,https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
 Tabs,tabs tabpanel tablist switch view,tablist/tab/tabpanel triad,"role=tablist/tab/tabpanel, aria-selected, tab order: one tabstop into list then Arrow keys; panel labelled by its tab","WCAG 2.1.1, 4.1.2",Each tab a separate Tab stop; panels not labelled,https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
 Accordion / disclosure,accordion disclosure expand collapse faq section,button + aria-expanded,Header is a real button with aria-expanded + aria-controls; content region labelled; Enter/Space toggle,"WCAG 4.1.2, 1.3.1",Heading-with-onclick; hiding content with display:none while aria-expanded=true,https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
-Menu / dropdown actions,menu dropdown actions kebab context,menu button + menu/menuitem,"menubutton with aria-haspopup=menu aria-expanded; Arrow navigation, Esc closes and returns focus; menuitem (not links styled as menu)",WCAG 2.1.1,Using role=menu for site navigation (use nav+links),https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/
+Menu / dropdown actions,menu dropdown actions kebab context menubutton menu-button,menu button + menu/menuitem,"menu button with aria-haspopup=menu aria-expanded; Arrow navigation, Esc closes and returns focus; menuitem (not links styled as menu)",WCAG 2.1.1,Using role=menu for site navigation (use nav+links),https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
 Toast / status message,toast notification snackbar status alert,status / alert live regions,"role=status (polite) for confirmations, role=alert (assertive) sparingly for errors; never move focus to a toast; pause on hover/focus; allow dismissal","WCAG 4.1.3, 2.2.1",Focus-stealing toasts; auto-dismiss with no persistence option for critical info,https://www.w3.org/WAI/ARIA/apg/patterns/alert/
 Data table,table grid sortable data rows columns,table semantics + aria-sort,Native table elements with th scope; sortable headers are buttons inside th with aria-sort on the th; caption or aria-label names the table,WCAG 1.3.1,Div-grid for tabular data; sort state only as an icon,https://www.w3.org/WAI/ARIA/apg/patterns/table/
 Form validation feedback,form error validation invalid message field,described-by + alert summary,aria-invalid + aria-describedby on the field; on submit failure move focus to first invalid field or an error-summary with anchor links; errors persist until fixed,"WCAG 3.3.1, 3.3.3, 2.4.3",Placeholder-only labels; toast-only errors,https://www.w3.org/WAI/tutorials/forms/notifications/

package/dist/agent-src/skills/accessibility-auditor/data/manifest.json

@@ -28,7 +28,7 @@
   "refresh_cadence": "quarterly",
   "upstream": {
     "repo": "derived: W3C ARIA Authoring Practices Guide + WCAG 2.2",
-    "sha": "APG 2026 / WCAG 2.2 (W3C Recommendation 12 Dec 2024) \u2014 verified not superseded 2026-09-18",
-    "last_checked": "2026-09-18"
+    "sha": "WCAG 2.2 W3C-REC-2024-12-12; APG continuously-published, menu-button canonical slug",
+    "last_checked": "2026-10-01"
   }
 }

package/dist/agent-src/skills/api-design/data/manifest.json

@@ -28,7 +28,7 @@
   "refresh_cadence": "quarterly",
   "upstream": {
     "repo": "derived: RFC 9110/9457/7396/8288 + httpapi WG drafts",
-    "sha": "RFC 9110 (STD 97) / 9457 / 7396 / 8288 \u2014 verified 2026-09-18: 9110 neither obsoleted nor updated; 9457 current and obsoletes 7807",
-    "last_checked": "2026-09-18"
+    "sha": "RFC 9110 (STD 97, 2022-06) / 9457 (2023-07, obsoletes 7807) / 7396 (2014-10) / 8288 (2017-10) \u2014 all Standards Track",
+    "last_checked": "2026-10-04"
   }
 }

package/dist/agent-src/skills/api-testing/SKILL.md

@@ -234,3 +234,20 @@ When a test fails, do not retry blindly with tweaked assertions until something
 ## Clarification guard — ambiguous contract → ask
 
 If the endpoint contract is ambiguous (unclear status code, optional fields, error envelope shape), do not assume. Ask the user or check the OpenAPI spec / route definition before writing assertions — never guess the response shape from the route name.
+
+## The HTTP-assertion idiom, per ecosystem
+
+The examples above are Laravel's. The *shape* they teach — assert the status,
+then the body contract, then the side effect, and keep one behavior per test —
+transfers unchanged; the API does not. Resolve the runner with
+`resolve_toolchain` and read its `ecosystems`:
+
+| `ecosystems` | Request + assertion surface |
+|---|---|
+| `php` | `$this->getJson(...)` / `assertStatus` / `assertJsonPath` |
+| `js` | `supertest` or the framework's own test client, with `expect(res.status)` |
+| `python` | `httpx.AsyncClient` / framework `TestClient`; `assert res.status_code` |
+| `go` | `httptest.NewServer` + `net/http`, or the router's own `ServeHTTP` |
+
+Whatever the surface, the negative tests are not optional: unauthenticated,
+not-owner and cross-tenant each get their own case, per `broken-access-control`.

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

@@ -245,14 +245,26 @@ paragraph claiming "the same five answers" directly after a list of four:
 | `graph_dead` | `dead` |
 | `graph_query` | `query` |
 | `graph_path` | `path` |
+| `graph_node` | no CLI verb — one symbol's location, in-edges, out-edges and degree |
 
 `untested` has no tool of its own; it is a flag on `graph_impact`, because the
-two answer the same question over the same diff and a sixth tool would have cost
-standing context for a boolean. `graph_impact` is the only one that is not
+two answer the same question over the same diff and a separate tool would have
+cost standing context for a boolean. `graph_impact` is the only one that is not
 read-only — it runs `git diff --name-only` to resolve its rev — and
 `graph_dead`'s refusal arrives as `status: "refused"`, never as `status: "ok"`
 with an empty list.
 
+`graph_node` is the one entry with no CLI verb behind it, and the one that
+REFUSES a seed it cannot resolve exactly. Every other reader answers about a
+neighbourhood or a set, where a best-guess seed costs the caller one wrong line
+among several; a node view's every field — the location, the degree, both edge
+lists — is a statement about ONE node, so a guess is wrong in all of them at
+once. It resolves on the exact tiers of the same seed ladder (node id, then
+label) and returns `status: "refused"` naming the candidates when a label is
+ambiguous, rather than scoring free text — which is the retrieval class the
+measured null covers (`docs/CLAIMS.md`, `code-graph-retrieval-null`). Use
+`graph_query` when a best-guess match is what you want.
+
 **No ordering claim is added here, and no measurement claim either.** These
 verbs are cheaper than reconstructing the same relationship by hand — that is a
 claim about the ALTERNATIVE being a manual reconstruction, not about grep.

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

@@ -44,7 +44,7 @@ A **live preview URL** is required for testing.
 
 ## Procedure: Design review
 
-1. **Inspect the PR and preview** — Read the PR description, diff, and identify changed components/pages; capture a baseline screenshot of the preview URL.
+1. **Inspect the PR and preview** — Read the PR description, diff, and identify changed components/pages; read the probe artifact and run the appearance floor over the preview URL (Phase 0).
 2. **Walk the interactions** — Run Phase 1; cover hover/focus/active/disabled, keyboard, loading, and form error states.
 3. **Cover responsiveness, polish, a11y, robustness** — Run Phases 2–5 in order; record findings per phase.
 4. **Audit code-health and content** — Run Phases 6–7; check tokens, dead styles, copy, console warnings.
@@ -55,7 +55,11 @@ A **live preview URL** is required for testing.
 - Read PR description and git diff.
 - Identify changed components and affected pages.
 - Navigate to preview URL.
-- Take baseline screenshot.
+- **Read the probe artifact** `agents/runtime/state/ui-conformance.json`
+  (`ui_conformance_probe --target <file> --reference <file>`) — its per-dimension counters are the
+  behavioral evidence Phases 1–2 report against. Absent is absent, never clean; a dimension the host
+  could not exercise carries a not-applicable row with its reason rather than a zero.
+- **Run the appearance floor** (§ Appearance verification) — mandatory on every review.
 
 ### Phase 1: Interaction
 
@@ -102,7 +106,9 @@ asserted floor outside the measured set is an assertion nobody checks; 375px
 passing says nothing about 320px, which is where a two-column grid or a fixed
 `min-width` actually breaks.
 
-- Take screenshots at each viewport.
+- **Read the probe artifact's `viewport_matrix` rows** — one per declared width, recording whether the
+  layout property that should change at that breakpoint did. A not-applicable row is missing evidence, not a pass.
+- **Run the appearance floor** (§ Appearance verification) at every one of the four widths.
 - **Scroll-driven surface** — read the `scroll_evidence` artefact
   ([`references/verification-automation.md`](references/verification-automation.md)
   § Scroll evidence) and report every sample whose asserted `state` and
@@ -156,6 +162,26 @@ passing says nothing about 320px, which is where a two-column grid or a fixed
 - No placeholder text left in production.
 - Check browser console for JavaScript errors or warnings.
 
+## Appearance verification — mandatory, and explicitly appearance-only
+
+```
+APPEARANCE VERIFICATION IS MANDATORY WHEREVER APPEARANCE CAN BE AFFECTED.
+THE PROBE DEMOTES THE IMAGE FROM PRIMARY EVIDENCE — IT DOES NOT MOVE THE FLOOR.
+AN IMAGE IS NEVER EVIDENCE FOR HOVER, FOCUS, KEYBOARD, BREAKPOINT OR JS BEHAVIOR.
+AN UNRUN APPEARANCE CHECK IS REPORTED AS UNRUN, NEVER AS PASSED.
+```
+
+**Trigger — identical to the two capture steps it replaces**, not merely as broad: Phase 0
+unconditionally, Phase 2 once per width. Only what the image is evidence *for* narrowed.
+**Two jobs, and the older one comes first:** (1) presence and sanity — *"presence + sanity
+check that nothing renders broken. Not pixel-perfect regression"* — no blank frame, no
+collapsed or overlapping layout, no missing region, no unstyled flash; **no probe dimension
+covers it**, because a computed style can be correct on a node nobody can see; (2) pixel
+comparison against a baseline where one exists, element-scoped, dynamic content masked. No
+render capability → scope the verdict and say so per the gate at the top of this skill;
+degrading is reported, never a pass. What a clean render does *not* answer:
+[`references/verification-automation.md`](references/verification-automation.md) § Appearance verification.
+
 ## Reviewer posture
 
 **Approval is earned, not assumed. Default to flagging.**
@@ -187,7 +213,7 @@ excessive copy, and redundant UI chrome.
 Load the reference file whose sections the review needs — never all of them by default:
 
 - [`references/review-communication.md`](references/review-communication.md) — Before / After / Why output format · Communication principles · Report structure · Design Review Summary
-- [`references/verification-automation.md`](references/verification-automation.md) — Visual QA with browser automation · Async-verifier pattern (keep the main context clean)
+- [`references/verification-automation.md`](references/verification-automation.md) — Visual QA with browser automation · Async-verifier pattern (keep the main context clean) · Appearance verification (what a clean render does not answer)
 
 ## Output format
 

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

@@ -122,3 +122,35 @@ the async verifier above, which captures the fan-out's main win without spinning
 up four separate views. Reconsider only when `design-review` runs as a standalone
 heavy batch over many *independent* surfaces, where per-surface
 `do-in-parallel` genuinely pays.
+
+## Appearance verification — what a clean render does not answer
+
+The skill body carries the floor: appearance verification is mandatory wherever
+appearance can be affected, its trigger is identical to the two capture steps it
+replaces, and presence-and-sanity comes before pixel comparison. This section is
+the part a reviewer looks up rather than obeys — the division of labour between a
+render and the probe's four dimensions.
+
+A render is a resting frame. It can only show what the surface looks like with
+nothing driving it, which is why a clean one says nothing about:
+
+| The question | Why the render cannot answer it | What does |
+|---|---|---|
+| Does hover / focus / active feedback exist? | the state is never entered | `interaction` |
+| Does the keyboard reach it, and does the handler fire? | no input is delivered | `interaction` |
+| Did the breakpoint change the layout, or did the media query silently not fire? | the same picture comes back either way | `viewport_matrix` |
+| Is the resolved value the token intended, after cascade and fallback? | a wrong value can look plausible | `computed_style` |
+| Is `prefers-reduced-motion` honoured, and with *what* instead? | the preference is never emulated | `media_emulation` |
+
+Reading a clean render as though it covered a row of this table is the
+substitution the appearance-only marking exists to prevent, and it is the reason
+the floor lists its two jobs separately rather than as one "visual check": the
+first job is the one no probe dimension replaces, and the second is the one the
+probe supersedes for behavior.
+
+**The converse holds and is the less obvious half.** No probe dimension covers
+presence and sanity. A `computed_style` row can be green on a node that is
+off-screen, transparent, zero-height or painted under an overlay — correct
+resolved values on something nobody can see. That asymmetry is why demoting the
+image from *primary evidence* is not the same as removing it, and why an unrun
+appearance check is reported as unrun rather than folded into a probe verdict.

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

@@ -38,7 +38,7 @@ what this skill owns.
    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
+   `brand-to-tokens` / `design-tokens` to
    materialise `.tokens.json` — do not invent a parallel token format.
 
 **Two sources, one shape:**

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -97,6 +97,14 @@ nobody can test is how the previous mismatch happened.
 It reads zero in a JavaScript tree by construction, which is not the same as
 unused.
 
+### 1b. Detect the component-granularity taxonomy the project already chose
+
+```bash
+npx tsx scripts/work_engine/taxonomy/detect.ts   # or import detect_component_taxonomy(root)
+```
+
+Returns the project's **own** tier names joined with `/` — `atoms/molecules/organisms`, `primitives/patterns/features`, whatever it actually uses — or `none`. Record it as `state.ui_audit.component_taxonomy`, with `state.ui_audit.component_root` for where the components live. `none` is a real answer, and leaves every downstream step behaving exactly as it did before this detection existed. Never write a taxonomy the project does not evidence, and never "tidy" a layout into one — this step *finds* the project's structure, it never supplies one. Detection rules, the declared-beats-inferred precedence and the two collision floors: [`references/component-taxonomy-detection.md`](references/component-taxonomy-detection.md).
+
 ### 2. Identify the design system
 
 Detect markers, in order. **Stop at the first match** — projects rarely run more than one design system.
@@ -220,7 +228,7 @@ this component satisfy the artifact"* — which is a different question with a
 different answer, because a candidate can be an excellent name-and-props match
 and still use the wrong type scale, the wrong control, or a colour the artifact
 never states. Until this step existed nothing anywhere asked the second
-question, while [`ui-audit-gate`](../../rules/ui-audit-gate.md) carried *"reuse
+question, while `ui-audit-gate` carried *"reuse
 beats duplication"* as unqualified prose. Reused on an artifact port, an
 unconforming candidate is a fidelity deviation dressed as good hygiene.
 
@@ -271,6 +279,9 @@ then set `state.ui_audit.greenfield = true` and emit a halt:
 >    before building (recommended for projects with >1 planned screen)
 > 2. Proceed bare with Tailwind defaults (recommended for one-off prototypes)
 > 3. Point me at an external design-system reference (URL or file)
+> 4. Scaffold + a granularity convention — as 1, and new components go into
+>    named granularity folders you pick the names for; rename or drop it later
+>    and nothing here objects
 
 **Recommendation: 1 — Scaffold tokens + primitives** — even one extra screen
 benefits from a shared base; the scaffold cost is ~10 min and saves
@@ -278,7 +289,9 @@ re-doing every primitive on screen 2. Caveat: flip to 2 if this is a
 demo or single-page prototype that will not grow.
 ```
 
-Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `bare` | `external_reference`). Re-running the skill on the same state-file with `greenfield_decision` set is a no-op for the halt (audit findings stay).
+Option 4 is an **offer**, and the only one made anywhere: a project that already exists is never asked (§ 1b reads what it chose), and a greenfield project picking any other number has declined terminally, because the halt is a no-op once any decision is recorded. It stays one more number in the same block rather than a second question — a single number still answers it, which is what the reply-shape rule requires.
+
+Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `bare` | `external_reference` | `granularity_convention`). Re-running the skill on the same state-file with `greenfield_decision` set is a no-op for the halt (audit findings stay). `granularity_convention` takes the same scaffold path as `scaffold` — it adds the convention, it does not replace the scaffolding.
 
 ### 8. (Optional) Capture an a11y baseline
 
@@ -332,6 +345,7 @@ violations will surface as new findings on every run.
 Load on demand once the audit needs the pitfall catalog:
 
 - [`references/anti-slop-cross-reference.md`](references/anti-slop-cross-reference.md) — Anti-slop cross-reference
+- [`references/component-taxonomy-detection.md`](references/component-taxonomy-detection.md) — Component-taxonomy detection rules
 
 - [`references/output-and-pitfalls.md`](references/output-and-pitfalls.md) — Output format · Gotcha · Anti-slop cross-reference
 
@@ -344,12 +358,13 @@ Load on demand once the audit needs the pitfall catalog:
 5. **`state.ui_audit.patterns`** — object with forms, tables, modals, empty_states, navigation, data_display arrays
 6. **`state.ui_audit.candidates`** — top-5 similarity matches for the current input (may be empty)
 7. **`state.ui_audit.greenfield`** — boolean; when true, `greenfield_decision` MUST also be set before the dispatcher advances
+7b. **`state.ui_audit.component_taxonomy`** / **`component_root`** — the project's own granularity tiers joined with `/` (or `none`), and where the components live relative to the project root. Never a canonical tier list — a project with three tiers records three; `none` is the value that leaves every downstream step unchanged.
 8. **`state.ui_audit.a11y_baseline`** *(optional)* — array of `{rule, selector, severity?}` entries documenting pre-existing a11y violations the review gate should treat as informational. Omit the key entirely when no baseline applies; do not write `[]` for "I checked and there are none" — that disables the gate's filter for every future run.
 
 **Design-system export (current-repo source):** when the goal is to seed
 `DESIGN.md` from *this* repo, emit the inventory as a `design-system.json`
 artifact (the import contract in
-[`design-system-capture`](../design-system-capture/references/design-system-json.md))
+`design-system-capture`)
 and hand it to `design-system-capture` — the same shape an external extraction
 tool produces, so the import path is uniform.