@event4u/agent-config 16.1.0 → 16.2.0

package/dist/agent-src/commands/roadmap/process-full.md

@@ -165,7 +165,7 @@ command is a claim; a layer with one is a check.
 | 1 | A targeted local RED, then GREEN | the test runner filtered to the failing name — `npm run test:ts -- <file>`, never the suite |
 | 2 | Quality scoped to the changed surface | the type-checker and linter over the diff — `npm run typecheck`, the linter on changed files |
 | 3 | Per-phase fast CI | `roadmap.quality_cadence: per_phase` (Phase 0.2) at each phase boundary |
-| 4 | The final full required CI | `./scripts-run src/scripts/ci_settle <PR> --timeout 1700` — its LAST OUTPUT LINE is the verdict |
+| 4 | The final full required CI | `./scripts-run src/scripts/ci_settle <PR> --timeout-min 28`, run as a BACKGROUND job — its LAST OUTPUT LINE is the verdict |
 | 5 | Forge branch protection | `agent-config doctor --json` → `forge_protection` (Phase 3.2), read from the forge |
 | 6 | Final-head verification | `ci_settle`'s verdict line names the head; it must be the head that was pushed last |
 

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

@@ -9,6 +9,10 @@ visibility: visible
 skills: [refine-prompt, command-routing]
 description: Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over `work_engine`, confidence-band gated, no auto-git, test-first.
 argument-hint: "[prompt]"
+inputs:
+  - name: prompt
+    type: string
+    description: What to work on. Absent means resume the current task.
 suggestion:
   eligible: true
   trigger_description: "build this, implement this, drive this end-to-end"

package/dist/agent-src/contexts/execution/autonomy-mechanics.md

@@ -62,14 +62,10 @@ Ask.
 
 Committing is governed by the canonical
 [`commit-policy`](../../rules/commit-policy.md) rule, which applies
-regardless of `personal.autonomy`:
-
-- NEVER commit unless user said so this turn, a commit command was
-  invoked, a standing instruction is active, or the roadmap
-  authorizes it.
-- NEVER ask about committing. The user invokes a command or says so.
-- In autonomous mode, the **only** permitted commit-related question
-  is the one-shot pre-scan ask at the start of roadmap execution.
+regardless of `personal.autonomy`. Its Iron Law, its four exceptions
+and the never-ask clause live there; the mechanics — the Hard-Floor
+diff triggers and the one-shot roadmap pre-scan ask — live in
+[`commit-mechanics`](../authority/commit-mechanics.md).
 
 Push, merge, rebase, branch creation, PR operations, and tags
 remain permission-gated by

package/dist/agent-src/rules/ui-audit-gate.md

@@ -71,8 +71,7 @@ EXISTING-UI-AUDIT RUNS FIRST. ALWAYS.
 `state.ui_audit` is a non-empty dict carrying at least one of:
 
 - `components_found` — inventory entries from `existing-ui-audit`.
-- `greenfield: true` plus `greenfield_decision` ∈
-  `{scaffold, bare, external_reference}`.
+- `greenfield: true` plus a `greenfield_decision` ∈ `GREENFIELD_DECISIONS`.
 - Legacy `components` alias — back-compat.
 
 `null` or `{}` is **not** findings; empty dict is rejected on purpose.

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/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/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.
@@ -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,6 +358,7 @@ 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

package/dist/agent-src/skills/existing-ui-audit/references/component-taxonomy-detection.md

@@ -0,0 +1,56 @@
+# existing-ui-audit — component-taxonomy detection
+
+> Section-level entry point of the `existing-ui-audit` skill (progressive
+> disclosure). Load this file when § 1b of SKILL.md routes here — it carries
+> the detection rules and the boundary the step must not cross.
+
+## What the detector answers
+
+The question is *"has this project already chosen a way to organize its
+components by granularity, and if so what does it call the tiers?"* — never
+*"which taxonomy should this project use?"*. The recorded value is the
+project's **own** tier directory names, in the project's own order, joined
+with `/`, or `none`. Nothing canonical is ever written: a project with three
+tiers records three, and a project whose tiers are called
+`primitives / patterns / features` records exactly that.
+
+## Three properties, each pinned by a test
+
+- **Declared outranks inferred.** A `## Component taxonomy` section in the
+  consumer project's own `DESIGN.md`, at its root or under `docs/`, listing
+  backticked directory names as list items wins, provided at least two of
+  those directories exist
+  under the component root. The name may be bolded — `- **\`atoms\`** — ...`
+  is read exactly like `` - `atoms` — ... ``. Grounding the declaration against
+  the tree keeps a stale doc from declaring a taxonomy the tree does not have,
+  and a backticked name in prose rather than in a list item is a mention, not a
+  declaration. This is how a project whose tiers appear in no vocabulary the
+  detector knows still gets conformance. The first doc that *qualifies* wins:
+  one with no section, or one naming fewer than two tiers that exist on disk,
+  falls through to the next.
+
+- **A folder that merely sounds like a tier is a collision, not a convention.**
+  `components/{checkout,billing,molecules}` records `none`, and so does the
+  ordinary kind split `components/{layout,pages,forms}` — `layout`, `page`,
+  `block`, `element`, `part` and `cell` are all everyday folder names as well
+  as granularity words. Inference needs at least two tier-shaped buckets **and**
+  more than two thirds of the weighed ones; support folders (`hooks`, `utils`,
+  `types`, `lib`, `styles`, …) are left out of the denominator, so three
+  ordinary siblings cannot hide a taxonomy that is really there. Each floor has
+  its own fixture, because at one hit in three buckets either floor alone would
+  still refuse and neither would be tested.
+
+- **`none` is a real answer, not a failure.** A flat tree, an unreadable tree,
+  a missing component folder, a permission error: all record `none`, and every
+  downstream step then behaves exactly as it did before this detection
+  existed. Detection never throws — degrading to `none` is the safe direction,
+  because `none` is precisely the value that leaves the project's own
+  structures untouched.
+
+## The boundary
+
+Never write a taxonomy the project does not evidence, and never "tidy" an
+existing layout into one. Holding to the project's own structures is the
+standing rule; this step exists to *find* that structure, not to supply one.
+The single place a taxonomy is ever *offered* is the greenfield halt in § 7,
+and a decline there is terminal.

package/dist/agent-src/skills/markitdown/SKILL.md

@@ -1,6 +1,10 @@
 ---
 model_tier: medium
 name: markitdown
+inputs:
+  - name: source
+    type: string
+    description: "URI of the document to convert — file:, https: or data: (http: is refused). Absent means the skill is being read for its scheme discipline rather than invoked."
 description: "Convert PDF, DOCX, XLSX, PPTX, EPUB, images, or audio to Markdown via the markitdown-mcp server — 'extract this PDF', 'OCR this image', 'transcribe this audio'."
 status: active
 tier: senior

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

@@ -144,22 +144,46 @@ test('homepage visual regression', async ({ page }) => {
 
 ## Viewport testing
 
+A viewport loop whose only assertion is an image proves that the page rendered,
+not that the breakpoint did anything: the same picture comes back whether the
+media query fired or silently did not. Assert the layout property the breakpoint
+is supposed to change, then keep the capture and name it for the one thing it
+proves.
+
 ```ts
 test.describe('Responsive design', () => {
   for (const viewport of [
-    { width: 1440, height: 900, name: 'desktop' },
-    { width: 768, height: 1024, name: 'tablet' },
-    { width: 375, height: 812, name: 'mobile' },
+    { width: 1440, height: 900, name: 'desktop', columns: '1fr 1fr 1fr' },
+    { width: 768, height: 1024, name: 'tablet', columns: '1fr 1fr' },
+    { width: 375, height: 812, name: 'mobile', columns: '1fr' },
   ]) {
-    test(`renders correctly on ${viewport.name}`, async ({ page }) => {
-      await page.setViewportSize(viewport)
+    test(`lays out correctly on ${viewport.name}`, async ({ page }) => {
+      await page.setViewportSize({ width: viewport.width, height: viewport.height })
       await page.goto('/')
-      await expect(page).toHaveScreenshot(`home-${viewport.name}.png`)
+      // Behaviour: the declared breakpoint actually changed the layout.
+      await expect(page.locator('#grid')).toHaveCSS('grid-template-columns', viewport.columns)
+      // Appearance only: presence + sanity that nothing renders broken.
+      await expect(page).toHaveScreenshot(`appearance-${viewport.name}.png`)
     })
   }
 })
 ```
 
+**Read the probe artifact rather than re-deriving the matrix by hand.**
+`agents/runtime/state/ui-conformance.json` — produced by
+`ui_conformance_probe --target <file> --reference <file>` — carries a
+`viewport_matrix` row per declared width, plus a not-applicable row with its
+reason wherever the host could not cross the breakpoint. A width with no row is
+missing evidence, not a pass, and no dimension reads zero findings because it did
+not run.
+
+**The capture above is appearance-only, and it stays mandatory.** It proves
+presence and sanity — the surface rendered and nothing renders obviously broken —
+and proves nothing about hover, focus, keyboard or a media-preference branch.
+Demoting it from behavioral evidence does not narrow when it runs: it still runs
+at every width in the matrix. Floor and division of labour:
+[`design-review`](../design-review/SKILL.md) § Appearance verification.
+
 ## Debugging
 
 ```bash

package/dist/agent-src/skills/ui-component-architect/SKILL.md

@@ -69,6 +69,29 @@ still exists in the tree. Absent or empty → fall through to
 Then review existing components in the codebase for the same
 responsibility — extend rather than rebuild when a match is found.
 
+**Read `state.ui_audit.component_taxonomy` before you decide where the
+component goes.** The audit (§ 1b of
+[`existing-ui-audit`](../existing-ui-audit/SKILL.md)) records the project's
+**own** granularity tiers, joined with `/`, or `none`:
+
+- **It names tiers** → record the chosen tier on the component's
+  `state.ui_design.components[]` entry as `tier` (the apply step reads that
+  field and nothing else writes it), then place the component inside it and say
+  which:
+  *"conforming to the project's `primitives/patterns/features` taxonomy —
+  `Checkout` goes under `src/components/features/`"*. Match the tier by name;
+  there is no rule here that computes a tier, and there must not be one.
+- **A component fits no tier** → report it as a named conformance gap with the
+  reason, and leave it unplaced. Do not put it somewhere else quietly, and do
+  not invent a tier for it — picking one would need exactly the per-tier rule
+  the measurement below shows is not derivable.
+- **`none`** → behave exactly as you would without this paragraph. A project
+  that organizes its components some other way must not be able to tell that
+  this step exists. Never propose a taxonomy to a project that has one you did
+  not recognise, and never propose one mid-task to a project that has none —
+  the single offer is made once, at the greenfield halt, and a decline there is
+  terminal.
+
 **A new component's workshop is part of its design where the project has one —
 size-conditional, never a generic mandate.** The boundary is
 [`component-oriented-and-oop-development`](../../guidelines/component-oriented-and-oop-development.md)

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: "16.1.0"
+agent_config_version: "16.2.0"
 
 # --- Project identity ---
 project:

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

@@ -575,6 +575,36 @@ that was never a judgement call.
     full CI pipeline — per `roadmap-ci-steps-policy` a `verify:` must not
     be a full-suite gate.
 
+    **The expectation half — say what the command must produce.** A command
+    alone names no oracle. `` verify: `cat notes.md` `` is a conforming step
+    field that cannot say no, so the box gets flipped on a command that was
+    never able to fail. In practice the great majority of clauses in a
+    roadmap tree state no oracle at all — run the share command below on
+    your own tree rather than trusting a number written here. A clause
+    MAY therefore state what the command must produce, using the arrow
+    `exec:` evidence already carries — not a new symbol:
+
+    - `` verify: `<cmd>` -> 0 `` — the command must exit with that code.
+    - `` verify: `<cmd>` -> /regex/ `` — its output must match.
+
+    Prose after `verify:` stays legal and reads as MANUAL. Forbidding it
+    would invalidate most clauses already in the tree at a stroke, and a
+    grammar that reds every producer gets weakened until it finds nothing.
+    One parser reads the arrow (`src/scripts/_lib/verify_clause.ts`) and
+    nothing parses it a second time. `closure_scan`'s `unfalsifiable-verify`
+    family reports the clauses whose oracle cannot say no, and exits 0
+    unconditionally — it is a listing, never a gate. The share per roadmap
+    is `./scripts-run src/scripts/roadmap_verify_share`.
+
+    **An absence check names its positive control.** A `verify:` asserting
+    that something is *absent* — no match, no occurrence, an empty diff —
+    passes identically when the property holds, when the check itself is
+    broken, when the path moved, and when the corpus is empty. Such a clause
+    MUST name the input on which it does fire: the positive control. A
+    fixture that plants the thing, a prior commit that carried it, or a
+    sabotage the step records. Without one it is a check nobody has seen
+    working, and its green means only that nothing ran.
+
 24. **Ready roadmaps carry a `## Risk Register` (Gate R1).** Every
     ready (non-draft) roadmap ends with a schema-valid Risk Register —
     marker line (`<!-- risk-review: v1 | reviewed: YYYY-MM-DD |

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

@@ -11,8 +11,9 @@
  *
  * The gate is **scoped to the greenfield-scaffold path only**. It acts only
  * when `state.ui_audit` records `greenfield == True` and
- * `greenfield_decision == "scaffold"`. Every other UI flow sees this slot as a
- * clean `SUCCESS` no-op, so those flows stay byte-identical.
+ * `greenfield_decision` ∈ `{scaffold, granularity_convention}`. Every other
+ * UI flow sees this slot as a clean `SUCCESS` no-op, so those flows stay
+ * byte-identical.
  */
 import {
     type Any,
@@ -21,6 +22,7 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import { GRANULARITY_CONVENTION } from '../../state.js';
 
 /** Declared ambiguity surfaces for this step. */
 export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
@@ -112,14 +114,18 @@ export function run(state: DeliveryState): StepResult {
  * The gate is inert for every other flow: improve-existing, the `bare` /
  * `external_reference` greenfield picks, and the `diff` / `file` envelopes all
  * leave `ui_audit` without the `greenfield == True` +
- * `greenfield_decision == "scaffold"` pair.
+ * `greenfield_decision` ∈ `{scaffold, granularity_convention}` pair.
  */
 function _is_greenfield_scaffold(state: DeliveryState): boolean {
     const audit = state.ui_audit;
     if (!_isDict(audit)) return false;
+    // `granularity_convention` is option 4 — a scaffold that additionally
+    // organises what it creates under a named convention, so it takes the same
+    // grounding pass. Kept in step with the identical guard in `scaffold`.
     return (
         audit['greenfield'] === true &&
-        audit['greenfield_decision'] === 'scaffold'
+        (audit['greenfield_decision'] === 'scaffold' ||
+            audit['greenfield_decision'] === GRANULARITY_CONVENTION)
     );
 }