@event4u/agent-config 14.9.0 → 14.11.0

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

@@ -18,6 +18,7 @@ import {
 import {
     is_ambiguous_stack,
     bundle_line,
+    scope_lines,
     unsupported_stack_questions,
 } from './stack_bundles.js';
 
@@ -266,6 +267,7 @@ function _delegate_to_polish_skill(
             agent_directive(directive),
             `> Stack: \`${stack_label}\`. Polish round ${next_round} of ${ceiling}.`,
             bundle_line(state.stack, 'build', stack_label),
+            ...scope_lines(state.stack),
             findings_line,
             '> Fix chart-type / contrast findings against the adopted ' +
                 "corpus rows (design-intelligence § 'Grounding the " +

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

@@ -19,6 +19,7 @@ import {
 import {
     is_ambiguous_stack,
     bundle_line,
+    scope_lines,
     unsupported_stack_questions,
 } from './stack_bundles.js';
 
@@ -50,6 +51,29 @@ export const SEVERITY_ORDER: Record<string, number> = {
 /** R4 a11y default severity floor. */
 export const DEFAULT_SEVERITY_FLOOR = 'moderate';
 
+/**
+ * Marker on a review finding that flags a hardcoded design value.
+ *
+ * Deliberately re-declared rather than imported from `polish.ts`: the two
+ * directives are siblings with no dependency edge between them, and
+ * `token_violation_kinds_agree` in the Phase 3 test pins the two literals
+ * equal so the duplication cannot drift silently.
+ */
+export const TOKEN_VIOLATION_KIND = 'token_violation';
+
+/** A finding produced by a deterministic check, not by an agent's judgement. */
+export const DETECTOR_CHANNEL = 'detector';
+
+/**
+ * A finding produced by an agent reading the surface.
+ *
+ * Named here only so the two channels are readable side by side. The prose
+ * channel (`tailwind-engineer` § arbitrary values) is unchanged by the
+ * detector — the detector is additive, and a finding that carries no
+ * `channel` at all predates the split and is treated as judgement.
+ */
+export const JUDGEMENT_CHANNEL = 'judgement';
+
 export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
     {
         code: 'review_envelope_missing',
@@ -151,11 +175,15 @@ export function run(state: DeliveryState): StepResult {
         return a11y_halt;
     }
 
+    _apply_token_detector(state, r);
+
     const preview_halt = _apply_preview_gate(state, r);
     if (preview_halt !== null) {
         return preview_halt;
     }
 
+    _stamp_verdict_scope(r);
+
     return new StepResult({ outcome: Outcome.SUCCESS });
 }
 
@@ -210,6 +238,7 @@ function _delegate_to_review_skill(state: DeliveryState): StepResult {
             `> Stack: \`${stack_label}\`. Reviewing rendered components ` +
                 'against the locked design brief.',
             bundle_line(state.stack, 'review', stack_label),
+            ...scope_lines(state.stack),
             '> The review pass compares `state.ticket.ui_apply.rendered` ' +
                 'against `state.ui_design` (microcopy, states, a11y, layout) ' +
                 'and produces a structured `findings` list.',
@@ -372,6 +401,193 @@ function _synthesize_a11y_findings(findings: Any[], actionable: Any[]): void {
     }
 }
 
+/**
+ * Return the audit token category whose bucket holds `value`, or null.
+ *
+ * This predicate IS the pre-registered scope of the measured dimension: "a raw
+ * literal where the audit found a token". A value the audit holds no token for
+ * is outside it and is never emitted — the `F4-unscoped` falsifier
+ * (`agents/evidence/analysis/frontend-fidelity-preregistered-falsifiers.md`)
+ * fires on a detector that flags every literal instead.
+ *
+ * Membership is tested with `Object.values(bucket).includes(value)`, the exact
+ * predicate `polish._classify_token_violations` uses. Sharing the predicate is
+ * what makes every detector-produced finding classify as `matched` downstream,
+ * so the detector channel can never trip the token-extraction halt.
+ */
+function _audit_token_category(tokens: Record<string, Any>, value: string): string | null {
+    for (const category of Object.keys(tokens)) {
+        const bucket = tokens[category];
+        if (_isDict(bucket) && Object.values(bucket).includes(value)) {
+            return category;
+        }
+    }
+    return null;
+}
+
+/** Return `state.ui_audit.design_tokens` as a dict, or `{}`. */
+function _audit_design_tokens(state: DeliveryState): Record<string, Any> {
+    const audit = _pyTruthy(state.ui_audit) ? state.ui_audit : {};
+    if (!_isDict(audit)) {
+        return {};
+    }
+    const tokens = _pyTruthy(audit['design_tokens']) ? audit['design_tokens'] : {};
+    return _isDict(tokens) ? tokens : {};
+}
+
+/** Dedup key for a detector finding — one per measured site and value. */
+function _tokenKeyOf(file: Any, line: Any, value: Any): string {
+    return `${String(file)}\u0000${String(line)}\u0000${String(value)}`;
+}
+
+/**
+ * Append `token_violation` findings from the detector envelope.
+ *
+ * Mirrors `_synthesize_a11y_findings`: the review skill writes the raw scan
+ * into `state.ui_review.tokens.violations`, and this turns the in-scope subset
+ * into findings the polish gate already knows how to act on. Deduped by
+ * `(file, line, value)`, so re-running the step is idempotent.
+ *
+ * Returns the number of findings appended.
+ */
+function _synthesize_token_findings(
+    findings: Any[],
+    violations: Any[],
+    tokens: Record<string, Any>,
+): number {
+    const existing = new Set<string>();
+    for (const f of findings) {
+        if (_isDict(f) && f['kind'] === TOKEN_VIOLATION_KIND) {
+            existing.add(_tokenKeyOf(f['file'], f['line'], f['value']));
+        }
+    }
+    let added = 0;
+    for (const v of violations) {
+        if (!_isDict(v)) {
+            continue;
+        }
+        const value = v['value'];
+        if (typeof value !== 'string') {
+            continue;
+        }
+        const category = _audit_token_category(tokens, value);
+        if (category === null) {
+            continue;
+        }
+        const key = _tokenKeyOf(v['file'], v['line'], value);
+        if (existing.has(key)) {
+            continue;
+        }
+        findings.push({
+            kind: TOKEN_VIOLATION_KIND,
+            channel: DETECTOR_CHANNEL,
+            category,
+            value,
+            file: v['file'] ?? null,
+            line: v['line'] ?? null,
+            detector_type: v['type'] ?? null,
+        });
+        existing.add(key);
+        added += 1;
+    }
+    return added;
+}
+
+/**
+ * Turn the detector envelope into findings, and take the review off clean.
+ *
+ * Never halts. An absent envelope is not an error: the detector is one channel
+ * of two, and a run that did not scan is a run with nothing measured — which is
+ * exactly what the `render_ok` gate below refuses to let pass silently for the
+ * render channel, and what a null record covers for a blocked dimension.
+ */
+function _apply_token_detector(state: DeliveryState, review: Record<string, Any>): void {
+    const raw = review['tokens'];
+    if (!_isDict(raw)) {
+        return;
+    }
+    const violations = raw['violations'];
+    if (!Array.isArray(violations) || violations.length === 0) {
+        return;
+    }
+    const findings = review['findings'];
+    if (!Array.isArray(findings)) {
+        return;
+    }
+    const added = _synthesize_token_findings(
+        findings as Any[],
+        violations as Any[],
+        _audit_design_tokens(state),
+    );
+    if (added > 0) {
+        review['review_clean'] = false;
+    }
+}
+
+/**
+ * Render-dependent checks, and the blocker that gates each of them.
+ *
+ * Named here so a static-scoped verdict can enumerate what it did NOT do.
+ * "Scope the verdict to what was statically checked and say so" is only
+ * readable if the unrun half is written down too — an enumerated `checks_run`
+ * with no `checks_not_run` beside it reads as a complete review.
+ */
+export const RENDER_DEPENDENT_CHECKS: ReadonlyArray<string> = [
+    'viewport-sweep',
+    'touch-target-size',
+    'rendered-contrast',
+    'screenshot-diff',
+];
+
+/** The blocker slug every render-dependent check is gated behind. */
+export const RENDER_BLOCKER = 'b-page-capture-primitive';
+
+/**
+ * Stamp the verdict scope onto the review envelope.
+ *
+ * W6: `design-review` makes browser automation a hard prerequisite and, below
+ * it, describes a static path in prose with no artefact recording which checks
+ * actually ran. This writes that artefact.
+ *
+ * Every field is DERIVED from the envelope — nothing is invented. A check is
+ * listed as run because the envelope carries its evidence, never because a
+ * skill said it ran. `scope` is always stamped, so an unscoped verdict is not a
+ * shape this step can leave behind.
+ */
+function _stamp_verdict_scope(review: Record<string, Any>): void {
+    const raw_preview = review['preview'];
+    const preview: Record<string, Any> = _isDict(raw_preview) ? raw_preview : {};
+    const rendered = preview['render_ok'] === true;
+
+    const checks_run: string[] = ['findings-review'];
+    const a11y = review['a11y'];
+    if (_isDict(a11y) && Array.isArray(a11y['violations'])) {
+        checks_run.push('a11y-axe');
+    }
+    const tokens = review['tokens'];
+    if (_isDict(tokens) && Array.isArray(tokens['violations'])) {
+        checks_run.push('token-detector');
+    }
+    if (rendered) {
+        checks_run.push(...RENDER_DEPENDENT_CHECKS);
+    }
+
+    const scope: Record<string, Any> = {
+        scope: rendered ? 'render' : 'static',
+        render_available: rendered,
+        checks_run,
+    };
+    if (!rendered) {
+        scope['checks_not_run'] = [...RENDER_DEPENDENT_CHECKS];
+        scope['blocker'] = RENDER_BLOCKER;
+        const reason = preview['skip_reason'];
+        scope['skip_reason'] = typeof reason === 'string' && reason.length > 0
+            ? reason
+            : RENDER_BLOCKER;
+    }
+    review['verdict_scope'] = scope;
+}
+
 /** BLOCKED halt — audit declared a baseline but review has no a11y. */
 function _halt_a11y_pending(state: DeliveryState): StepResult {
     const directive = _resolve_directive(state);

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

@@ -59,6 +59,146 @@ export const BRAND_TOKEN_PATHS: ReadonlyArray<string> = [
     'agents/settings/brand/tokens.json',
 ];
 
+/**
+ * Conventional location of the project's `Playbook` contexts (ADR-244).
+ *
+ * A playbook is this repository's OWN procedure for a task, and it outranks a shipped
+ * skill: the generic skill answers a generic question, while the playbook carries decisions
+ * the repository already made (file layout, barrel exports, naming) that no shipped skill
+ * can know. Mirrors {@link BRAND_TOKEN_PATHS} deliberately — same acyclic,
+ * degrades-gracefully shape: present → the repository's command is proposed first, absent →
+ * nothing is emitted and the lane is byte-identical.
+ */
+export const PLAYBOOK_HOME = path.join('agents', 'settings', 'contexts');
+
+/** A playbook the lane may act on: `configured` grade, matching scope, non-empty `invokes`. */
+export interface ScaffoldPlaybook {
+    readonly file: string;
+    readonly task: string;
+    readonly invokes: readonly string[];
+}
+
+/**
+ * Read a playbook's head. Only `configured` playbooks with a `scope` that covers
+ * `scope_root` are returned — an `observed` playbook is advisory (per the
+ * `playbook-precedence` rule) and MUST NOT be dispatched ahead of a shipped skill, because
+ * at least one of its ids was never resolved in the tree.
+ */
+export function _read_playbook(file: string, scope_root: string): ScaffoldPlaybook | null {
+    let text = '';
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    } catch {
+        return null;
+    }
+    if (!text.startsWith('---')) return null;
+    const end = text.indexOf('\n---', 3);
+    if (end < 0) return null;
+    const head = text.slice(3, end);
+
+    const grade = /^grade:\s*["']?([A-Za-z]+)["']?\s*$/m.exec(head);
+    if (grade === null || grade[1] !== 'configured') return null;
+
+    const scope = /^scope:\s*["']?(.+?)["']?\s*$/m.exec(head);
+    const scope_value = scope?.[1] ?? '';
+    // `repo` covers everything; otherwise the playbook's scope must be a prefix of the
+    // project's scope_root (or equal to it). A partial match is NOT a match — a playbook
+    // for `packages/ui` says nothing about `packages/api`.
+    const in_scope =
+        scope_value === 'repo' ||
+        (scope_value !== '' && (scope_root === scope_value || scope_root.startsWith(`${scope_value}/`)));
+    if (!in_scope) return null;
+
+    const task = /^task:\s*["']?(.+?)["']?\s*$/m.exec(head);
+    const invokes: string[] = [];
+    let in_list = false;
+    for (const line of head.split('\n')) {
+        if (/^invokes:\s*$/.test(line)) {
+            in_list = true;
+            continue;
+        }
+        if (in_list) {
+            const item = /^\s+-\s*["']?(.+?)["']?\s*$/.exec(line);
+            if (item?.[1] !== undefined) {
+                invokes.push(item[1]);
+                continue;
+            }
+            in_list = false;
+        }
+        const inline = /^invokes:\s*\[(.*)\]\s*$/.exec(line);
+        if (inline?.[1] !== undefined) {
+            for (const part of inline[1].split(',')) {
+                const v = part.trim().replace(/^["']|["']$/g, '');
+                if (v.length > 0) invokes.push(v);
+            }
+        }
+    }
+    // A `configured` playbook with no ids cannot be dispatched: there is nothing to propose,
+    // and proposing the empty set as "the repository's procedure" would be worse than silence.
+    if (invokes.length === 0) return null;
+    return { file, task: task?.[1] ?? '(untitled)', invokes };
+}
+
+/**
+ * The `configured` playbooks whose scope covers this project, for the given verb.
+ *
+ * `verb` is matched against the playbook's `task` as a plain lower-cased substring. That is
+ * deliberately loose: a playbook titled "Add a new component to this repository" must match
+ * the `scaffold` lane's component work, and a stricter match would make the whole mechanism
+ * unreachable for the phrasing `playbook-authoring` actually generates.
+ */
+export function _scaffold_playbooks(
+    state: DeliveryState,
+    verb_terms: ReadonlyArray<string>,
+    root: string | null = null,
+): ScaffoldPlaybook[] {
+    const base = root !== null ? root : process.cwd();
+    const home = path.join(base, PLAYBOOK_HOME);
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(home).filter((n) => n.endsWith('.md')).sort();
+    } catch {
+        return [];
+    }
+    const stack = _pyTruthy(state.stack) ? state.stack : {};
+    const scope_root_raw = _isDict(stack) ? stack['scope_root'] : undefined;
+    const scope_root = typeof scope_root_raw === 'string' ? scope_root_raw : '';
+
+    const out: ScaffoldPlaybook[] = [];
+    for (const name of names) {
+        const pb = _read_playbook(path.join(home, name), scope_root);
+        if (pb === null) continue;
+        const task_lower = pb.task.toLowerCase();
+        if (!verb_terms.some((t) => task_lower.includes(t))) continue;
+        out.push(pb);
+    }
+    return out;
+}
+
+/**
+ * The lines that put the repository's own procedure ahead of the stack skill.
+ *
+ * Empty array when no playbook matches — that is what keeps a project with no playbook home
+ * byte-identical to before this existed. The commands are PROPOSED, never run: the
+ * engine-never-writes contract is unchanged, and a playbook is authoritative about *what*,
+ * never about who runs it.
+ */
+export function _playbook_lines(playbooks: ReadonlyArray<ScaffoldPlaybook>): string[] {
+    if (playbooks.length === 0) return [];
+    const lines: string[] = [
+        '> **This repository has its own procedure for this, and it goes FIRST.** A shipped ' +
+            'skill is a generic answer; the playbook below carries decisions this repository ' +
+            'already made. Use the stack skill only for what the playbook does not cover.',
+    ];
+    for (const pb of playbooks) {
+        lines.push(
+            `> \`${pb.file}\` — ${pb.task}: propose \`${pb.invokes.join('`, `')}\` ` +
+                'before any stack-skill step. Propose, never run — the human runs it.',
+        );
+    }
+    return lines;
+}
+
 /**
  * Stack-agnostic directive that derives the scaffold plan.
  *
@@ -67,6 +207,23 @@ export const BRAND_TOKEN_PATHS: ReadonlyArray<string> = [
  */
 export const PLAN_DIRECTIVE = 'ui-scaffold-plan';
 
+/**
+ * Task words that make a playbook relevant to the `scaffold` verb.
+ *
+ * Kept small and concrete rather than clever: these are the nouns
+ * `playbook-authoring` derives from a repository's own creation scripts
+ * (`new:component`, `new:package`, `generate:page`), so the terms and the generator are
+ * two halves of one contract.
+ */
+export const SCAFFOLD_VERB_TERMS: ReadonlyArray<string> = [
+    'component',
+    'page',
+    'package',
+    'workspace',
+    'route',
+    'screen',
+];
+
 /**
  * Map `state.stack.frontend` → build-stage agent-directive skill name.
  *
@@ -324,10 +481,12 @@ function _delegate_build(state: DeliveryState, scaffold: Record<string, Any>): S
     const page_count = Array.isArray(pages) ? pages.length : 0;
     const routes = scaffold['routes'];
     const route_count = Array.isArray(routes) ? routes.length : 0;
+    const playbook_lines = _playbook_lines(_scaffold_playbooks(state, SCAFFOLD_VERB_TERMS));
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
+            ...playbook_lines,
             `> Stack: \`${stack_label}\`. Scaffold plan is ready ` +
                 `(${page_count} page(s), ${route_count} route(s)). Create the ` +
                 'skeleton from `state.ui_scaffold` — routes, layout shell, and ' +

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

@@ -212,17 +212,86 @@ export function unsupported_stack_questions(
     for (const c of conflicts) {
         lines.push(`> - \`${c}\``);
     }
+    // A scope conflict has a *closed* option set — the detector already named
+    // every candidate — so enumerate them instead of asking the open question.
+    // "Which workspace?" answered from a list is a pick; answered as free text
+    // it is a guess the agent has to validate, which is the same silent-pick
+    // failure one layer up.
+    const roots = workspace_roots_from_conflicts(conflicts);
+    let n = 1;
+    for (const root of roots) {
+        lines.push(
+            `> ${n}. Build for \`${root}\` — write it to \`state.stack.scope_root\` ` +
+                'and re-run detection against that workspace.',
+        );
+        n += 1;
+    }
+    if (roots.length === 0) {
+        lines.push(
+            `> ${n}. Name the project to build for — the workspace path, or which ` +
+                'framework owns this surface. Detection re-runs against that scope.',
+        );
+        n += 1;
+    }
     lines.push(
-        '> 1. Name the project to build for — the workspace path, or which ' +
-            'framework owns this surface. Detection re-runs against that scope.',
-        '> 2. Continue on the stack-neutral floor anyway — `ui-apply-generic` ' +
+        `> ${n}. Continue on the stack-neutral floor anyway — \`ui-apply-generic\` ` +
             'plus its companions. Output will not be idiomatic for either ' +
             'framework; say so in the result.',
-        '> 3. Abort — drop this UI request.',
+        `> ${n + 1}. Abort — drop this UI request.`,
     );
     return lines;
 }
 
+/** Prefix of the ambiguity string the detector emits for a scope conflict. */
+const _WORKSPACE_CONFLICT_PREFIX = 'workspace roots: ';
+
+/**
+ * The workspace names carried by a `workspace roots: a + b` conflict.
+ *
+ * Parsed back out of the ambiguity string rather than passed alongside it,
+ * because `StackResult.ambiguity` is the serialized contract the halt already
+ * echoes — adding a parallel field would give the same fact two representations
+ * that can disagree after a round-trip through `state.stack`.
+ */
+export function workspace_roots_from_conflicts(
+    conflicts: ReadonlyArray<string>,
+): string[] {
+    for (const c of conflicts) {
+        if (c.startsWith(_WORKSPACE_CONFLICT_PREFIX)) {
+            return c
+                .slice(_WORKSPACE_CONFLICT_PREFIX.length)
+                .split('+')
+                .map((name) => name.trim())
+                .filter((name) => name !== '');
+        }
+    }
+    return [];
+}
+
+/**
+ * Name the workspace a dispatch is scoped to, when it is not the project root.
+ *
+ * Returns an empty array for every non-monorepo project, so those halts stay
+ * byte-identical. The line exists because the skills downstream read
+ * `components.json`, `components/ui/*` and the styling config by path, and in a
+ * monorepo none of those live at the repository root — which is the M5 prose
+ * defect, restated where the agent actually acts on it.
+ */
+export function scope_lines(stack_state: unknown): string[] {
+    if (typeof stack_state !== 'object' || stack_state === null) {
+        return [];
+    }
+    const raw = (stack_state as Record<string, unknown>)['scope_root'];
+    if (typeof raw !== 'string' || raw === '') {
+        return [];
+    }
+    return [
+        `> Scope: \`${raw}\` — the workspace this stack was detected in. Read ` +
+            'and write component files, `components.json`, and the styling ' +
+            'config under that path. The repository root carries none of them.',
+    ];
+}
+
 /**
  * Render the "load these skills" line for a dispatch halt.
  *