@event4u/agent-config 16.1.0 → 16.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "16.1.0",
+    "version": "16.2.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including the counts in these badges.",
     "license": "MIT",
     "private": false,
@@ -80,7 +80,7 @@
     "scripts": {
         "build:cli": "tsc -p tsconfig.json && chmod +x dist/cli/agent-config.js",
         "build:install-bundle": "esbuild src/scripts/install.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/install/install.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);\"",
-        "build:hooks": "esbuild src/scripts/hooks/dispatch_entry.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/hooks/dispatch.js --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_HOOKS_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
+        "build:hooks": "esbuild src/scripts/hooks/dispatch_entry.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/hooks/dispatch.js --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_HOOKS_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\" && node src/scripts/write_bundle_digest.mjs",
         "build:mcp-bundle": "esbuild src/scripts/mcp_server/__main__.ts --bundle --platform=node --format=esm --target=node20 --define:__AGENT_CONFIG_BUNDLE__=true --outfile=dist/mcp/server.mjs --banner:js=\"import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url); const __acPath = require('node:path'); const __acFs = require('node:fs'); const __acUrl = require('node:url'); const __acReal = (p) => { try { return __acFs.realpathSync(p); } catch { return p; } }; const __acSelf = __acReal(__acUrl.fileURLToPath(import.meta.url)); if (process.argv[1] !== undefined && __acReal(__acPath.resolve(process.argv[1])) === __acSelf) { globalThis.__AC_MCP_BUNDLE_DIRECT = true; process.argv = [process.argv[0], __acSelf + '.__direct__', ...process.argv.slice(2)]; }\"",
         "clean:cli-delegate": "rm -rf dist/cli-delegate",
         "build:delegates": "npm run clean:cli-delegate && npm run build:cli-delegate && npm run build:agent-src-delegate && npm run build:delegate-aux",
@@ -122,8 +122,8 @@
         "tree-sitter-wasms": "0.1.13",
         "tsx": "^4.23.1",
         "typescript": "^5.9.3",
-        "vite": "^5.4.21",
-        "vitest": "^2.1.9"
+        "vite": "^8.3.1",
+        "vitest": "^5.0.2"
     },
     "dependencies": {
         "@fastify/static": "^10.1.2",

package/src/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)
     );
 }
 

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

@@ -10,6 +10,9 @@
  * rejection, or change recording. Apply validates the output against the
  * brief's microcopy lock so a mid-loop hallucination is caught at the boundary.
  */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
 import {
     type Any,
     type DeliveryState,
@@ -17,6 +20,11 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import {
+    type ComponentRequest,
+    conformance_lines,
+    plan_component_placement,
+} from '../../taxonomy/place.js';
 import { has_design_system, placeholder_paths, provided_artifact } from './design.js';
 import { _playbook_lines, _scaffold_playbooks } from './scaffold.js';
 import {
@@ -118,15 +126,27 @@ export function run(state: DeliveryState): StepResult {
     }
 
     const provided = provided_artifact(state.ui_design as Record<string, Any> | null);
+    const notes: string[] = [];
     if (provided !== null) {
-        const gaps = coverage_gaps(provided, envelope['coverage']);
-        if (gaps.length > 0) {
-            return _halt_coverage(state, provided, gaps);
+        const report = coverage_report(provided, envelope['coverage']);
+        if (report.gaps.length > 0) {
+            return _halt_coverage(state, provided, report.gaps);
+        }
+        notes.push(...report.fallbacks);
+        // 3.1 — reported in shadow: the outcome value is unchanged for one
+        // release, so a caller branching on it is found by the line rather
+        // than by the breakage.
+        const handed_back = _handed_back_line(report);
+        if (handed_back !== null) {
+            notes.push(handed_back);
         }
     }
 
     _record_changes(state, envelope);
-    return new StepResult({ outcome: Outcome.SUCCESS });
+    return new StepResult({
+        outcome: Outcome.SUCCESS,
+        message: notes.join('\n'),
+    });
 }
 
 /** Buckets the coverage report must sort every declared item into. */
@@ -139,8 +159,73 @@ export const COVERED_INVENTORIES: ReadonlyArray<string> = [
     'assets',
 ];
 
+/** What the coverage report said, split into what halts and what only warns. */
+export interface CoverageReport {
+    /** Reasons the report fails to account for the artifact. A halt. */
+    gaps: string[];
+    /** Items carried only by the deprecated containment fallback. A warning. */
+    fallbacks: string[];
+    /** Every declared item, in report order. */
+    declared: string[];
+    /** Declared items whose only account is in `flagged` — work handed back. */
+    handed_back: string[];
+}
+
 /**
- * Return every reason the coverage report fails to account for the artifact.
+ * Did the port hand back everything it was given?
+ *
+ * True only when there is a declared inventory and **every** item in it is
+ * accounted for solely by `flagged`. Deliberately narrow: flagging one dropped
+ * handler is the ledger working exactly as designed, and reporting that as a
+ * hand-back would make the signal worthless within a week. What this catches
+ * is the envelope that accounted for everything and carried none of it — which
+ * `coverage_gaps` cannot see, because a complete report and a complete
+ * surrender are the same empty gap list.
+ */
+export function carried_nothing(report: CoverageReport): boolean {
+    return report.declared.length > 0 && report.handed_back.length === report.declared.length;
+}
+
+/** The line that says a port handed its work back, or `null`. */
+function _handed_back_line(report: CoverageReport): string | null {
+    if (!carried_nothing(report)) return null;
+    return (
+        `the port carried nothing over — all ${report.declared.length} declared ` +
+        `item(s) are in \`flagged\`: ${report.handed_back.join(', ')}`
+    );
+}
+
+/** Characters that make a containment hit part of a longer word. */
+function _is_word_char(ch: string): boolean {
+    return (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9');
+}
+
+/**
+ * Does `entry` mention `needle` as its own token rather than by accident?
+ *
+ * The deprecated fallback's boundary. Both arguments are already lower-cased.
+ * `submit handler — translated` mentions `submit handler`; `table sort order`
+ * does not mention `tab`, even though it contains those three letters. The
+ * discriminator is whether the hit is delimited on both sides, which is
+ * exactly the difference between an entry carrying its own explanation — the
+ * one thing containment was documented as buying — and a short name colliding
+ * with the inside of a longer word.
+ */
+function _mentions(entry: string, needle: string): boolean {
+    let from = 0;
+    for (;;) {
+        const at = entry.indexOf(needle, from);
+        if (at < 0) return false;
+        const before = at === 0 ? '' : (entry[at - 1] as string);
+        const after_at = at + needle.length;
+        const after = after_at >= entry.length ? '' : (entry[after_at] as string);
+        if (!_is_word_char(before) && !_is_word_char(after)) return true;
+        from = at + 1;
+    }
+}
+
+/**
+ * Return what the coverage report fails to account for, and what it only warns on.
  *
  * The fidelity ledger the port case never had. `apply` used to validate its
  * output with a single placeholder substring scan and nothing else, so a
@@ -149,22 +234,45 @@ export const COVERED_INVENTORIES: ReadonlyArray<string> = [
  * appear in exactly one bucket turns that silence into a halt: a handler the
  * port could not carry has to be written down in `flagged`.
  *
- * Matching is substring containment against the bucket entries, so an entry
- * may carry its own explanation ("submit handler — translated to a form
- * action") and still count as accounting for `submit handler`.
+ * **Matching is equality, not containment.** Containment was chosen so an
+ * entry could carry its own explanation ("submit handler — translated to a
+ * form action") and still account for `submit handler`. It also accounted for
+ * a declared `tab` with an entry about `table sort order`, which is the same
+ * rule doing the opposite of its job: the shorter the declared name, the more
+ * likely some unrelated entry contains it, so the gate grew weakest exactly
+ * where the inventory was tersest.
+ *
+ * `allow_annotated_fallback` keeps the explanation case working for one
+ * release, as a **warning** rather than a silent pass, so an envelope written
+ * against the old rule does not halt without notice. It is narrower than the
+ * containment it replaces: the mention has to be delimited
+ * ({@link _mentions}), which is the property the explanation case always had
+ * and the collision case never did.
  */
-export function coverage_gaps(
+export function coverage_report(
     provided: Record<string, Any>,
     coverage: Any,
-): string[] {
+    allow_annotated_fallback = true,
+): CoverageReport {
     const gaps: string[] = [];
+    const fallbacks: string[] = [];
+    const declared_all: string[] = [];
+    const handed_back: string[] = [];
     if (!_isDict(coverage)) {
-        return [
-            'no `coverage` report in the apply envelope — a provided artifact ' +
-                'requires one',
-        ];
+        return {
+            gaps: [
+                'no `coverage` report in the apply envelope — a provided artifact ' +
+                    'requires one',
+            ],
+            fallbacks,
+            declared: declared_all,
+            handed_back,
+        };
     }
-    const entries: string[] = [];
+    // Kept per-bucket, not flattened: which bucket accounted for an item is
+    // what separates a port that translated its work from one that handed it
+    // back, and a flat list of entries cannot answer that.
+    const by_bucket = new Map<string, string[]>();
     for (const bucket of COVERAGE_BUCKETS) {
         const value = coverage[bucket];
         if (value === undefined) {
@@ -175,26 +283,75 @@ export function coverage_gaps(
             gaps.push(`\`coverage.${bucket}\` must be a list of strings`);
             continue;
         }
+        const kept: string[] = [];
         for (const item of value) {
             if (typeof item === 'string' && item !== '') {
-                entries.push(item.toLowerCase());
+                kept.push(item.toLowerCase());
             }
         }
+        by_bucket.set(bucket, kept);
+    }
+    /** The buckets that account for `needle`, by either rule. */
+    function _accounting_buckets(needle: string): string[] {
+        const hit: string[] = [];
+        for (const [bucket, entries] of by_bucket) {
+            if (entries.some((entry) => entry === needle)) {
+                hit.push(bucket);
+            } else if (
+                allow_annotated_fallback &&
+                entries.some((entry) => _mentions(entry, needle))
+            ) {
+                hit.push(bucket);
+            }
+        }
+        return hit;
     }
     for (const inventory of COVERED_INVENTORIES) {
         const declared = provided[inventory];
         if (!Array.isArray(declared)) continue;
         for (const item of declared) {
             if (typeof item !== 'string' || item === '') continue;
+            declared_all.push(item);
             const needle = item.toLowerCase();
-            if (!entries.some((entry) => entry.includes(needle))) {
+            const buckets = _accounting_buckets(needle);
+            if (buckets.length === 0) {
                 gaps.push(
                     `\`${inventory}\`: \`${item}\` appears in no coverage bucket`,
                 );
+                continue;
+            }
+            if (buckets.length === 1 && buckets[0] === 'flagged') {
+                handed_back.push(item);
+            }
+            const exact = [...by_bucket.values()].some((entries) =>
+                entries.some((entry) => entry === needle),
+            );
+            if (exact) continue;
+            const mention = [...by_bucket.values()]
+                .flat()
+                .find((entry) => _mentions(entry, needle));
+            if (mention !== undefined) {
+                fallbacks.push(
+                    `\`${inventory}\`: \`${item}\` matched only by containment ` +
+                        `against \`${mention}\``,
+                );
             }
         }
     }
-    return gaps;
+    return { gaps, fallbacks, declared: declared_all, handed_back };
+}
+
+/**
+ * Every reason the coverage report fails to account for the artifact.
+ *
+ * The halting half of {@link coverage_report}, kept as its own name because
+ * that is what callers and the port tests already ask for.
+ */
+export function coverage_gaps(
+    provided: Record<string, Any>,
+    coverage: Any,
+): string[] {
+    return coverage_report(provided, coverage).gaps;
 }
 
 /** BLOCKED halt — the port did not account for what the artifact declared. */
@@ -243,6 +400,40 @@ function _apply_envelope(state: DeliveryState): Record<string, Any> | null {
     return null;
 }
 
+/**
+ * Conformance lines for the taxonomy the audit detected, or nothing.
+ *
+ * Empty whenever `state.ui_audit.component_taxonomy` is absent or names no
+ * tiers — which is every project that has not chosen a granularity taxonomy,
+ * and is the case whose output must stay exactly as it was. Holding to the
+ * project's own structures is the standing rule; this step only ever conforms
+ * to a taxonomy the project itself evidences.
+ *
+ * The `'none'` case is NOT re-checked here. `conformance_lines` owns that
+ * invariant and says so in its own contract, and a second copy of the check
+ * here would mask a regression in the first: with both present, either one
+ * could be deleted and every AC-2 test would still pass. One owner, one test
+ * that fails when it breaks.
+ */
+export function taxonomy_lines(state: DeliveryState): string[] {
+    const audit = _isDict(state.ui_audit) ? (state.ui_audit as Record<string, Any>) : {};
+    const taxonomy = audit['component_taxonomy'];
+    if (typeof taxonomy !== 'string' || taxonomy === '') {
+        return [];
+    }
+    const root = typeof audit['component_root'] === 'string' ? audit['component_root'] : '';
+    const design = _isDict(state.ui_design) ? (state.ui_design as Record<string, Any>) : {};
+    const raw = design['components'];
+    const components: ComponentRequest[] = Array.isArray(raw)
+        ? raw.filter((c): c is Record<string, Any> => _isDict(c))
+        : [];
+    return conformance_lines(
+        taxonomy,
+        root,
+        plan_component_placement(taxonomy, root, components),
+    );
+}
+
 /** Pick the agent directive for the project's frontend stack. */
 function _resolve_directive(state: DeliveryState): string {
     const stack = _pyTruthy(state.stack) ? state.stack : {};
@@ -265,7 +456,53 @@ function _resolve_directive(state: DeliveryState): string {
  * exactly the same inputs.
  */
 function _placeholder_violations_in_output(envelope: Record<string, Any>): string[] {
-    return placeholder_paths(envelope['rendered']);
+    return [...placeholder_paths(envelope['rendered']), ...written_file_placeholders(envelope)];
+}
+
+/**
+ * Return the written files whose text carries a placeholder pattern.
+ *
+ * `rendered` is the porter's own report of what it wrote. The files are what
+ * it actually wrote, and nothing made the two agree — a placeholder that never
+ * entered the report was invisible to a gate that only read the report. This
+ * reads the other side of that pair.
+ *
+ * **Only `envelope['files']`** — the set the port declares it changed. Never a
+ * tree sweep: the directive has no business reading files this run did not
+ * touch, and a sweep would grow with the repository rather than with the port.
+ *
+ * A path that does not resolve to a readable file is **skipped, not reported**.
+ * `apply` runs at points where a declared file may not be on disk yet, and
+ * halting a correct port because a path failed to resolve would be a worse
+ * failure than the one this closes. The cost is real and worth naming: a
+ * placeholder inside a file the engine cannot read stays unseen.
+ *
+ * `root` defaults to the working directory, which is the consumer project root
+ * when the engine runs — the same convention as `scaffold`'s token lookup.
+ */
+export function written_file_placeholders(
+    envelope: Record<string, Any>,
+    root: string | null = null,
+): string[] {
+    const files = envelope['files'];
+    if (!Array.isArray(files)) return [];
+    const base = root !== null ? root : process.cwd();
+    const hits: string[] = [];
+    for (const rel of files as Any[]) {
+        if (typeof rel !== 'string' || rel === '') continue;
+        let text: string;
+        try {
+            const full = path.resolve(base, rel);
+            if (!fs.statSync(full).isFile()) continue;
+            text = fs.readFileSync(full, 'utf8');
+        } catch {
+            continue;
+        }
+        if (placeholder_paths(text, rel).length > 0) {
+            hits.push(rel);
+        }
+    }
+    return hits;
 }
 
 /** First-pass halt — emit the stack-specific apply directive. */
@@ -298,6 +535,7 @@ function _delegate_to_stack_skill(state: DeliveryState): StepResult {
         '> Microcopy is locked — every button label, empty-state ' +
             'message, and validation message must come verbatim from ' +
             '`state.ui_design.microcopy`.',
+        ...taxonomy_lines(state),
     ];
     if (provided !== null) {
         lines.push(
@@ -331,9 +569,10 @@ function _halt_placeholders(state: DeliveryState, violations: string[]): StepRes
     const directive = _resolve_directive(state);
     const lines: string[] = [
         agent_directive(directive),
-        '> Apply rejected: rendered output contains placeholder strings. ' +
+        '> Apply rejected: the port output contains placeholder strings. ' +
             'The design-brief microcopy lock failed mid-loop.',
-        '> Affected paths in `ui_apply.rendered`:',
+        '> Affected paths, in `ui_apply.rendered` and in the files the ' +
+            'envelope declares it wrote:',
     ];
     for (const p of violations) {
         lines.push(`> - \`${p}\``);

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

@@ -19,6 +19,20 @@ import {
     agent_directive,
 } from '../../delivery_state.js';
 
+/**
+ * The greenfield pick that adopts a component-granularity convention.
+ *
+ * Re-exported from the schema, which owns it beside `GREENFIELD_DECISIONS` —
+ * an option the user can pick that the schema then rejects is a halt with a
+ * dead exit, so the two cannot be allowed to drift.
+ *
+ * Offered only here, and only as an OFFER: a project that already exists is
+ * never asked, and a user who picks any other number has declined it for good
+ * — the halt is a no-op once a decision is recorded, so declining costs one
+ * number and is never raised again.
+ */
+export { GRANULARITY_CONVENTION } from '../../state.js';
+
 /** Similarity threshold for a "strong reusable match". */
 export const STRONG_SIMILARITY = 0.7;
 
@@ -42,8 +56,9 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
             'state.ui_audit.greenfield is True but greenfield_decision ' +
             'is unset — user has not picked a scaffolding direction',
         resolution:
-            'user picks scaffold / bare / external_reference; ' +
-            'agent records the choice in state.ui_audit.greenfield_decision',
+            'user picks scaffold / bare / external_reference / ' +
+            'granularity_convention; agent records the choice in ' +
+            'state.ui_audit.greenfield_decision',
     },
     {
         code: 'shadcn_version_mismatch',
@@ -198,6 +213,9 @@ function _halt_greenfield(state: DeliveryState, audit: Record<string, Any>): Ste
         '> 1. Scaffold — minimal token set + base component primitive folder',
         '> 2. Bare — proceed with Tailwind defaults, no scaffolding',
         '> 3. External reference — point me at a design-system 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 ' +
@@ -210,7 +228,8 @@ function _halt_greenfield(state: DeliveryState, audit: Record<string, Any>): Ste
         questions,
         message:
             'UI audit detected greenfield; halting for scaffolding ' +
-            'direction (scaffold / bare / external_reference).',
+            'direction (scaffold / bare / external_reference / ' +
+            'granularity_convention).',
     });
 }
 

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

@@ -42,6 +42,7 @@ import {
     StepResult,
     agent_directive,
 } from '../../delivery_state.js';
+import { GRANULARITY_CONVENTION } from '../../state.js';
 
 /**
  * Conventional locations for a project's DTCG `tokens.json`.
@@ -307,9 +308,13 @@ export function run(state: DeliveryState): StepResult {
 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. It has to reach the
+    // scaffold gate, or picking 4 would scaffold nothing at all.
     return (
         audit['greenfield'] === true &&
-        audit['greenfield_decision'] === 'scaffold'
+        (audit['greenfield_decision'] === 'scaffold' ||
+            audit['greenfield_decision'] === GRANULARITY_CONVENTION)
     );
 }
 

package/src/agent-src/templates/scripts/work_engine/state.ts

@@ -27,7 +27,10 @@
  *   `existing-ui-audit` skill (R3 Phase 2). `null` while the audit
  *   has not run; populated dict once the skill returns. `greenfield`
  *   flag plus `greenfield_decision` carry the user's scaffolding
- *   pick. The audit gate (`work_engine.directives.ui.audit`)
+ *   pick; `component_taxonomy` and `component_root` carry the
+ *   granularity taxonomy the project itself evidences, or `'none'`.
+ *   `'none'` is the value that leaves every downstream step behaving
+ *   exactly as it did before detection existed. The audit gate (`work_engine.directives.ui.audit`)
  *   refuses to advance to design/apply while the slot is empty or
  *   while `greenfield` is set without a recorded decision.
  * - `app_spec` — optional greenfield grounding artifact written by
@@ -40,7 +43,12 @@
  * - `ui_design` — optional design brief produced by
  *   `work_engine.directives.ui.design` (R3 Phase 3 Step 1). Locks
  *   layout / components / states / microcopy / a11y; `design_confirmed`
- *   carries the user's sign-off.
+ *   carries the user's sign-off. A `components[]` entry MAY carry a
+ *   `tier` naming one of `ui_audit.component_taxonomy`'s tiers; the
+ *   apply step reads it to name the target directory, and it is the
+ *   only producer of that field. Omit it and the component is
+ *   reported as a conformance gap rather than placed, which is the
+ *   honest answer when nothing said where it belongs.
  * - `ui_scaffold` — optional greenfield scaffold plan written by
  *   `work_engine.directives.ui.scaffold` (greenfield-scaffold
  *   Phase 3). Plan-only and stack-agnostic
@@ -172,6 +180,37 @@ export const KNOWN_DIRECTIVE_SETS: ReadonlySet<string> = new Set([
     'mixed',
 ]);
 
+/**
+ * Every value `state.ui_audit.greenfield_decision` may carry.
+ *
+ * One list, read by the schema here and by the halt that offers the options
+ * (`directives/ui/audit.ts`), so an option the user can pick and a value the
+ * schema accepts cannot drift apart.
+ *
+ * `granularity_convention` is option 4: scaffold, and organise what is
+ * scaffolded under a named granularity convention. It is a fourth value of the
+ * same single-number question rather than a second axis — one number still
+ * answers the block, which is what the reply-shape rule requires.
+ */
+export const GREENFIELD_DECISIONS: ReadonlyArray<string> = [
+    'scaffold',
+    'bare',
+    'external_reference',
+    'granularity_convention',
+];
+
+/**
+ * The greenfield pick that adopts a component-granularity convention.
+ *
+ * Exported HERE, beside the list it belongs to, and imported by every gate
+ * that tests for it — the audit halt that offers it, and the scaffold and
+ * app-spec gates that must let it through. It was a bare string literal in
+ * four places; a rename would have left those gates silently not matching,
+ * and an inert scaffold gate returns SUCCESS, so picking option 4 would have
+ * scaffolded nothing with no error anywhere.
+ */
+export const GRANULARITY_CONVENTION = 'granularity_convention';
+
 /** Raised when a state payload violates the v1 contract. */
 export class SchemaError extends Error {
     constructor(message: string) {
@@ -535,7 +574,7 @@ function _validate_stack(stack: JsonValue): void {
  * skill returns but before findings land; the gate treats it the
  * same as `null`. Once populated, `greenfield` (when present)
  * must be a bool, and `greenfield_decision` (when present) must
- * be one of the three documented choices. Other keys (`components`,
+ * be one of `GREENFIELD_DECISIONS`. Other keys (`components`,
  * `patterns`, ...) are validated by the audit handler against the
  * skill contract — the schema only enforces shape, not content.
  */
@@ -559,16 +598,27 @@ function _validate_ui_audit(ui_audit: JsonValue): void {
         : null;
     if (
         decision !== null &&
-        decision !== 'scaffold' &&
-        decision !== 'bare' &&
-        decision !== 'external_reference'
+        !(typeof decision === 'string' && GREENFIELD_DECISIONS.includes(decision))
     ) {
         throw new SchemaError(
             `state.ui_audit.greenfield_decision must be one of ` +
-                `'scaffold', 'bare', 'external_reference', or null; ` +
+                `${GREENFIELD_DECISIONS.map((d) => `'${d}'`).join(', ')}, or null; ` +
                 `got ${pyRepr(decision)}`,
         );
     }
+    const taxonomy = 'component_taxonomy' in ui_audit ? ui_audit['component_taxonomy'] : null;
+    if (taxonomy !== null && typeof taxonomy !== 'string') {
+        throw new SchemaError(
+            'state.ui_audit.component_taxonomy must be a string when present ' +
+                "— the project's own tiers joined with '/', or 'none'",
+        );
+    }
+    const root = 'component_root' in ui_audit ? ui_audit['component_root'] : null;
+    if (root !== null && typeof root !== 'string') {
+        throw new SchemaError(
+            'state.ui_audit.component_root must be a string when present',
+        );
+    }
     if (
         'a11y_baseline' in ui_audit &&
         !Array.isArray(ui_audit['a11y_baseline'])