@event4u/agent-config 16.1.0 → 16.3.0

package/dist/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,26 @@ 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.2 — the shadow is now the outcome. 3.1 shipped the line one
+        // release ahead (16.2.0 carries it) so a caller branching on
+        // `SUCCESS` was found by the words before it is found by the value.
+        if (carried_nothing(report)) {
+            return _halt_carried_nothing(state, report, notes);
         }
     }
 
     _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 +158,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[];
+}
+
+/**
+ * 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 every reason the coverage report fails to account for the artifact.
+ * 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 +233,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 +282,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. */
@@ -233,6 +389,49 @@ function _halt_coverage(
     });
 }
 
+/**
+ * BLOCKED halt — the port accounted for everything and carried none of it.
+ *
+ * The gap list is empty here by construction: a complete report and a complete
+ * surrender look identical to `coverage_gaps`, which is why this is its own
+ * halt rather than a gap. `questions` is non-empty because the dispatcher
+ * rejects a `BLOCKED` result that surfaces nothing to answer — handing the
+ * work back has to come with a way forward, not just a refusal.
+ */
+function _halt_carried_nothing(
+    state: DeliveryState,
+    report: CoverageReport,
+    fallbacks: ReadonlyArray<string>,
+): StepResult {
+    const directive = _resolve_directive(state);
+    const lines: string[] = [
+        agent_directive(directive),
+        '> Apply rejected: the coverage report accounts for every declared ' +
+            'item and the port carried none of them over.',
+        `> All ${report.declared.length} declared item(s) are in \`flagged\`:`,
+    ];
+    for (const item of report.handed_back) {
+        lines.push(`> - \`${item}\``);
+    }
+    lines.push(
+        '> A complete report and a complete hand-back are the same empty gap ' +
+            'list, so this is checked separately — flagging one handler the ' +
+            'port could not carry is the ledger working; flagging all of them ' +
+            'is the port not having run.',
+        '> 1. Continue — implement the items above and re-write ' +
+            '`ui_apply.coverage` with each one in `honoured` or `translated`, ' +
+            'leaving in `flagged` only what genuinely could not be carried',
+        '> 2. Flag deliberately — say here which of the items above are out of ' +
+            'scope for this port and why, and the operator decides',
+        '> 3. Abort — drop this UI request',
+    );
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message: [...fallbacks, `UI apply rejected: ${_handed_back_line(report)}`].join('\n'),
+    });
+}
+
 /** Return the agent-written `ui_apply` envelope, or `null`. */
 function _apply_envelope(state: DeliveryState): Record<string, Any> | null {
     const data = _pyTruthy(state.ticket) ? state.ticket : {};
@@ -243,6 +442,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 +498,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 +577,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 +611,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/dist/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/dist/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)
     );
 }