@event4u/agent-config 14.10.0 → 14.12.0

package/src/agent-src/templates/scripts/check_playbook_invokes.ts

@@ -0,0 +1,231 @@
+/**
+ * check_playbook_invokes — a `configured` playbook may not name a procedure the tree no
+ * longer has.
+ *
+ * Ships in the consumer `scripts/` template so it runs in the CONSUMER's CI, over the
+ * consumer's own playbooks and the consumer's own configuration. That placement is the
+ * whole design: staleness is a fact about their repository, and a gate in this package
+ * could only ever check this package.
+ *
+ * The grade is the contract (ADR-244). `configured` asserts every step invokes something
+ * present in the tree; when a generator is renamed, that assertion becomes false silently —
+ * the playbook still reads like a procedure and the command no longer exists. This check is
+ * what turns that into a failure instead of a surprise at the next `turbo gen`.
+ *
+ * Three resolvable kinds, and no more: a script name in the package manifest, a declared
+ * task in the task file, and a registered generator template. An Nx or Plop id is reported
+ * `unsupported` — NEVER as resolved and never as missing, because discovering those needs a
+ * binary this check deliberately does not run. Reporting a real id as missing would be the
+ * worse error: it would push a correct playbook to `observed`.
+ *
+ * Usage:
+ *   check_playbook_invokes [--root <dir>] [--home <dir>] [--quiet]
+ *
+ * Exit 0 = every `configured` playbook resolves (or there are none).
+ * Exit 1 = at least one `configured` step names an id the tree does not have.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Playbooks are a context type (ADR-244), so the home is the contexts home. */
+const DEFAULT_HOME = path.join('agents', 'settings', 'contexts');
+
+export interface PlaybookHead {
+    readonly file: string;
+    readonly grade: string;
+    readonly invokes: readonly string[];
+}
+
+export type Verdict = 'resolved' | 'missing' | 'unsupported';
+
+export interface Check {
+    readonly file: string;
+    readonly id: string;
+    readonly verdict: Verdict;
+    /** Where it resolved, for a `resolved` verdict. */
+    readonly where: string | null;
+}
+
+/** Ids this check cannot resolve without running a consumer binary. */
+const UNSUPPORTED_PREFIXES = ['nx ', 'nx:', 'plop ', 'plop:'] as const;
+
+const readJson = (p: string): Record<string, unknown> | null => {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return null;
+    }
+};
+
+const asRecord = (v: unknown): Record<string, unknown> =>
+    v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+
+/**
+ * Minimal frontmatter read — `grade` and the `invokes` list only.
+ *
+ * Deliberately not a YAML dependency: this file ships into a consumer repository, where
+ * adding a parser dependency to run one gate is a cost the consumer did not ask for.
+ */
+export const parseHead = (file: string, text: string): PlaybookHead | null => {
+    if (!text.startsWith('---')) return null;
+    const end = text.indexOf('\n---', 3);
+    if (end < 0) return null;
+    const head = text.slice(3, end);
+    const gradeMatch = /^grade:\s*["']?([A-Za-z]+)["']?\s*$/m.exec(head);
+    if (!gradeMatch) return null;
+
+    const invokes: string[] = [];
+    const lines = head.split('\n');
+    let inList = false;
+    for (const line of lines) {
+        if (/^invokes:\s*$/.test(line)) {
+            inList = true;
+            continue;
+        }
+        if (inList) {
+            const item = /^\s+-\s*["']?(.+?)["']?\s*$/.exec(line);
+            if (item?.[1] !== undefined) {
+                invokes.push(item[1]);
+                continue;
+            }
+            inList = false;
+        }
+        // An inline list is the other legal shape and a reader that only handled the block
+        // form would report a correct playbook as having no ids at all.
+        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);
+            }
+        }
+    }
+    return { file, grade: gradeMatch[1] as string, invokes };
+};
+
+/** Generator templates registered in the tree, as `<runner> gen <name>` ids. */
+export const registeredGenerators = (root: string): Map<string, string> => {
+    const out = new Map<string, string>();
+    const dir = path.join(root, 'turbo', 'generators');
+    if (!fs.existsSync(dir)) return out;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.set(entry.name, path.relative(root, full));
+            continue;
+        }
+        const text = fs.readFileSync(full, 'utf8');
+        for (const m of text.matchAll(/\.(?:set|add)Generator\(\s*['"]([A-Za-z0-9_-]+)['"]/g)) {
+            out.set(m[1] as string, path.relative(root, full));
+        }
+    }
+    return out;
+};
+
+export const resolveId = (
+    root: string,
+    id: string,
+    gens: Map<string, string>,
+): { verdict: Verdict; where: string | null } => {
+    const lower = id.toLowerCase();
+    if (UNSUPPORTED_PREFIXES.some((p) => lower.startsWith(p))) {
+        return { verdict: 'unsupported', where: null };
+    }
+
+    const gen = /^\S+\s+gen\s+([A-Za-z0-9_-]+)/.exec(id);
+    if (gen) {
+        const name = gen[1] as string;
+        return gens.has(name)
+            ? { verdict: 'resolved', where: gens.get(name) ?? null }
+            : { verdict: 'missing', where: null };
+    }
+
+    const tasks = asRecord(readJson(path.join(root, 'turbo.json'))?.tasks);
+    if (Object.prototype.hasOwnProperty.call(tasks, id)) {
+        return { verdict: 'resolved', where: 'turbo.json#tasks' };
+    }
+    const scripts = asRecord(readJson(path.join(root, 'package.json'))?.scripts);
+    if (Object.prototype.hasOwnProperty.call(scripts, id)) {
+        return { verdict: 'resolved', where: 'package.json#scripts' };
+    }
+    return { verdict: 'missing', where: null };
+};
+
+export const checkAll = (root: string, home: string): Check[] => {
+    if (!fs.existsSync(home)) return [];
+    const gens = registeredGenerators(root);
+    const out: Check[] = [];
+    for (const name of fs.readdirSync(home).sort()) {
+        if (!name.endsWith('.md')) continue;
+        const file = path.join(home, name);
+        const head = parseHead(file, fs.readFileSync(file, 'utf8'));
+        // Only `configured` is a claim about the tree. An `observed` playbook already says
+        // its steps are unverified, so failing it here would punish the honest grade.
+        if (head === null || head.grade !== 'configured') continue;
+        for (const id of head.invokes) {
+            const { verdict, where } = resolveId(root, id, gens);
+            out.push({ file, id, verdict, where });
+        }
+    }
+    return out;
+};
+
+/**
+ * The remediation. BOTH options are printed verbatim on every failure, and neither is
+ * "delete the line": a playbook that loses its evidence line stops being checkable, which
+ * turns a caught drift into an uncatchable one.
+ */
+export const REMEDIATION = [
+    'Two ways to fix this, and only two:',
+    '  1. Fix the `invokes` id — the procedure moved, so point the playbook at where it moved to.',
+    '  2. Downgrade the step to `observed` and cite the commit it was last seen working in.',
+    'Do NOT delete the evidence line. A playbook without it is not a weaker claim, it is an',
+    'unverifiable one — and the next drift goes unnoticed.',
+].join('\n');
+
+const main = (): number => {
+    const argv = process.argv.slice(2);
+    const arg = (flag: string): string | null => {
+        const i = argv.indexOf(flag);
+        return i >= 0 && i + 1 < argv.length ? String(argv[i + 1]) : null;
+    };
+    const quiet = argv.includes('--quiet');
+    const root = arg('--root') ?? '.';
+    const home = arg('--home') ?? path.join(root, DEFAULT_HOME);
+
+    const checks = checkAll(root, home);
+    const missing = checks.filter((c) => c.verdict === 'missing');
+    const unsupported = checks.filter((c) => c.verdict === 'unsupported');
+
+    if (!quiet) {
+        for (const u of unsupported) {
+            process.stdout.write(
+                `ℹ️  ${u.file}: \`${u.id}\` is unsupported by this check (its discovery needs a ` +
+                    `consumer binary) — reported, not treated as missing\n`,
+            );
+        }
+        process.stdout.write(
+            `scanned: ${String(checks.length)} configured step(s) across ${String(new Set(checks.map((c) => c.file)).size)} playbook(s)\n`,
+        );
+    }
+
+    if (missing.length === 0) {
+        if (!quiet) {
+            process.stdout.write('✅  check_playbook_invokes: every configured step resolves in the tree.\n');
+        }
+        return 0;
+    }
+
+    for (const m of missing) {
+        process.stderr.write(
+            `❌  ${m.file}: step invoking \`${m.id}\` does not resolve — no such script, task, or generator in the tree\n`,
+        );
+    }
+    process.stderr.write(`\n${REMEDIATION}\n`);
+    return 1;
+};
+
+if (process.argv[1] !== undefined && process.argv[1].includes('check_playbook_invokes')) {
+    process.exit(main());
+}

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

@@ -18,13 +18,30 @@ import {
     agent_directive,
 } from '../../delivery_state.js';
 import { has_design_system, placeholder_paths, provided_artifact } from './design.js';
+import { _playbook_lines, _scaffold_playbooks } from './scaffold.js';
 import {
     is_ambiguous_stack,
     bundle_line,
+    scope_lines,
     unsupported_stack_questions,
 } from './stack_bundles.js';
 
 /** Map `state.stack.frontend` → agent-directive skill name. */
+/**
+ * Task words that make a playbook relevant to the `apply` verb.
+ *
+ * Same shape as `scaffold`'s list and deliberately a SEPARATE constant: `apply` implements
+ * into an existing surface, so a repository may reasonably carry a playbook for one verb and
+ * not the other. One shared list would silently dispatch a scaffold-only procedure here.
+ */
+export const APPLY_VERB_TERMS: ReadonlyArray<string> = [
+    'component',
+    'page',
+    'route',
+    'screen',
+    'view',
+];
+
 export const STACK_DIRECTIVES: Record<string, string> = {
     'blade-livewire-flux': 'ui-apply-blade-livewire-flux',
     'blade-livewire': 'ui-apply-blade-livewire',
@@ -267,10 +284,17 @@ function _delegate_to_stack_skill(state: DeliveryState): StepResult {
         });
     }
     const provided = provided_artifact(state.ui_design as Record<string, Any> | null);
+    // The repository's own procedure goes ahead of the stack skill when it has one. Empty
+    // when it does not, which is what keeps a project with no playbook home byte-identical.
+    // Imported from `scaffold` rather than duplicated: two copies of a scope-match rule
+    // drift, and the drift would be invisible — both lanes would still emit *something*.
+    const playbook_lines = _playbook_lines(_scaffold_playbooks(state, APPLY_VERB_TERMS));
     const lines: string[] = [
         agent_directive(directive),
+        ...playbook_lines,
         `> Stack: \`${stack_label}\`. Implementing the locked design brief.`,
         bundle_line(state.stack, 'build', stack_label),
+        ...scope_lines(state.stack),
         '> Microcopy is locked — every button label, empty-state ' +
             'message, and validation message must come verbatim from ' +
             '`state.ui_design.microcopy`.',

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);