@event4u/agent-config 8.4.0 → 8.4.1

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

@@ -0,0 +1,352 @@
+/**
+ * `scaffold` step — greenfield Zero-to-One skeleton gate (the `plan` slot).
+ *
+ * TypeScript twin of `directives/ui/scaffold.py` (ADR-200 py2ts). Public API
+ * names stay snake_case to mirror the Python module 1:1.
+ *
+ * greenfield-scaffold Phase 3: raise a real multi-page skeleton from a
+ * confirmed app-spec, under gates, without the engine ever writing app files.
+ * The step occupies the UI set's `plan` slot, which runs **after** `analyze`
+ * (design) and before `implement` (apply); it replaces the former no-op
+ * pass-through there.
+ *
+ * Order: audit → app-spec → design → scaffold → apply. `design` fixes the
+ * abstract visual language; `scaffold` maps that language onto concrete
+ * structure. The recoverable state is "designed but not scaffolded" — the plan
+ * is stack-agnostic and the engine writes zero files, so a failed scaffold
+ * re-runs from this step alone.
+ *
+ * The gate is **scoped to the greenfield-scaffold path only** (the same guard
+ * as `app_spec`). Every other UI flow sees this slot as a clean `SUCCESS`
+ * no-op, so those flows stay byte-identical.
+ *
+ * Two stages, both honouring the engine-never-renders contract:
+ *
+ * 1. **Plan** — `state.ui_scaffold` carries no structural plan yet. Emit
+ *    `@agent-directive: ui-scaffold-plan`: the agent/skill derives a
+ *    stack-agnostic `{pages, routes, layout_strategy, component_manifest,
+ *    token_seed}` and writes it into `state.ui_scaffold`.
+ * 2. **Build** — the plan exists but `scaffolded` is not `True`. Emit the
+ *    stack-specific `@agent-directive: ui-scaffold-<stack>`: the stack skill
+ *    consumes the plan, creates the skeleton files, and writes
+ *    `state.ui_scaffold.scaffolded = true` + `artifacts`.
+ *
+ * Idempotent: a fully-scaffolded plan round-trips through `SUCCESS`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+} from '../../delivery_state.js';
+
+/**
+ * Conventional locations for a project's DTCG `tokens.json`.
+ *
+ * When one is present (authored by the `design-tokens` skill, or shipped by
+ * `pack-brand`), the scaffold plan's `token_seed` is seeded from it — the
+ * anti-generic moat that makes a generated multi-page app coherent rather than
+ * default-shadcn. Absent → sane defaults. The dependency is acyclic and
+ * degrades gracefully: scaffold never *requires* `pack-brand`.
+ */
+export const BRAND_TOKEN_PATHS: ReadonlyArray<string> = [
+    'tokens.json',
+    'assets/tokens.json',
+    'resources/tokens.json',
+    'agents/settings/brand/tokens.json',
+];
+
+/**
+ * Stack-agnostic directive that derives the scaffold plan.
+ *
+ * The plan IS stack-agnostic, so plan derivation is a single directive
+ * regardless of frontend; only the build stage dispatches per stack.
+ */
+export const PLAN_DIRECTIVE = 'ui-scaffold-plan';
+
+/**
+ * Map `state.stack.frontend` → build-stage agent-directive skill name.
+ *
+ * Mirrors `directives/ui/apply.STACK_DIRECTIVES`. An unknown / missing stack
+ * falls through to `ui-scaffold-plain` rather than raising — a wrong skill
+ * pick is recoverable, a crash is not.
+ */
+export const STACK_DIRECTIVES: Record<string, string> = {
+    'blade-livewire-flux': 'ui-scaffold-blade-livewire-flux',
+    'react-shadcn': 'ui-scaffold-react-shadcn',
+    vue: 'ui-scaffold-vue',
+    plain: 'ui-scaffold-plain',
+};
+
+/** Fallback build directive when `state.stack` is missing or malformed. */
+export const DEFAULT_DIRECTIVE = 'ui-scaffold-plain';
+
+/** Declared ambiguity surfaces for this step. */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'scaffold_plan_missing',
+        trigger:
+            'greenfield scaffold path and state.ui_scaffold carries no ' +
+            'structural plan (no routes / layout_strategy / component_manifest) — ' +
+            'the scaffold plan has not been derived yet',
+        resolution:
+            'agent directive `ui-scaffold-plan` → derive a ' +
+            'stack-agnostic {pages, routes, layout_strategy, component_manifest, ' +
+            'token_seed} from the confirmed app_spec + locked design brief into ' +
+            'state.ui_scaffold',
+    },
+    {
+        code: 'scaffold_build_pending',
+        trigger:
+            'greenfield scaffold path and state.ui_scaffold carries a ' +
+            'plan but `scaffolded` is not True — the stack skill has not created ' +
+            'the skeleton files yet',
+        resolution:
+            'agent directive `ui-scaffold-<stack>` → stack skill ' +
+            'consumes the plan, creates the skeleton, and writes ' +
+            'state.ui_scaffold.scaffolded = true + artifacts',
+    },
+];
+
+function _isDict(value: Any): value is Record<string, Any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Apply the greenfield scaffold gate.
+ *
+ * No-op `SUCCESS` for every non-greenfield-scaffold flow; the plan → build loop
+ * only engages when the audit recorded a `scaffold` greenfield decision.
+ */
+export function run(state: DeliveryState): StepResult {
+    if (!_is_greenfield_scaffold(state)) {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    const scaffold = state.ui_scaffold;
+
+    if (!_is_planned(scaffold)) {
+        return _delegate_plan(state);
+    }
+
+    const scaffoldDict = scaffold as Record<string, Any>;
+    if (scaffoldDict['scaffolded'] !== true) {
+        return _delegate_build(state, scaffoldDict);
+    }
+
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}
+
+/**
+ * True when the audit recorded a `scaffold` greenfield decision.
+ *
+ * Identical guard to `app_spec._is_greenfield_scaffold`: the gate is inert for
+ * improve-existing, the `bare` / `external_reference` greenfield picks, and the
+ * `diff` / `file` envelopes.
+ */
+function _is_greenfield_scaffold(state: DeliveryState): boolean {
+    const audit = state.ui_audit;
+    if (!_isDict(audit)) return false;
+    return (
+        audit['greenfield'] === true &&
+        audit['greenfield_decision'] === 'scaffold'
+    );
+}
+
+/**
+ * True when `scaffold` carries a structural plan.
+ *
+ * The defining content of the scaffold plan is the structure the app-spec did
+ * not produce — routes, a layout strategy, or a component manifest. Their
+ * presence (any one) is the "plan derived" signal; an empty dict or a bare
+ * `None` is treated as "skill has not run". `pages` alone is *not* sufficient,
+ * since the app-spec slice also carries a page-set.
+ */
+function _is_planned(scaffold: Any): boolean {
+    if (!_isDict(scaffold)) {
+        return false;
+    }
+    return ['routes', 'layout_strategy', 'component_manifest'].some(
+        (key) => key in scaffold,
+    );
+}
+
+/** Render a one-line preview of the input being scaffolded. */
+function _preview_input(state: DeliveryState): string {
+    const data = (_isDict(state.ticket) ? state.ticket : {}) as Record<string, Any>;
+    const raw = data['raw'];
+    let text: string;
+    if (typeof raw === 'string' && raw.trim() !== '') {
+        text = raw.split(/\s+/u).filter((x) => x.length > 0).join(' ');
+    } else {
+        const title = data['title'];
+        if (typeof title === 'string') {
+            text = title;
+        } else {
+            const id = data['id'];
+            text = _pyTruthy(id) ? pyStr(id) : '(no title)';
+        }
+    }
+    if ([...text].length <= 80) {
+        return text;
+    }
+    return _pyRStrip([...text].slice(0, 79).join('')) + '…';
+}
+
+function _pyTruthy(value: Any): boolean {
+    if (value === null || value === undefined) return false;
+    if (typeof value === 'string') return value.length > 0;
+    if (typeof value === 'number') return value !== 0;
+    if (typeof value === 'boolean') return value;
+    if (Array.isArray(value)) return value.length > 0;
+    if (typeof value === 'object') return Object.keys(value).length > 0;
+    return true;
+}
+
+function pyStr(value: Any): string {
+    if (value === null || value === undefined) return 'None';
+    if (value === true) return 'True';
+    if (value === false) return 'False';
+    return String(value);
+}
+
+function _pyRStrip(s: string): string {
+    return s.replace(/\s+$/u, '');
+}
+
+/** Return the frontend stack label, defaulting to `plain`. */
+function _stack_label(state: DeliveryState): string {
+    const stack = _pyTruthy(state.stack) ? state.stack : {};
+    if (_isDict(stack)) {
+        const frontend = stack['frontend'];
+        if (typeof frontend === 'string' && frontend !== '') {
+            return frontend;
+        }
+    }
+    return 'plain';
+}
+
+/** Pick the build-stage directive for the project's frontend stack. */
+function _resolve_build_directive(state: DeliveryState): string {
+    const stack = _pyTruthy(state.stack) ? state.stack : {};
+    if (_isDict(stack)) {
+        const frontend = stack['frontend'];
+        if (typeof frontend === 'string' && frontend in STACK_DIRECTIVES) {
+            return STACK_DIRECTIVES[frontend] as string;
+        }
+    }
+    return DEFAULT_DIRECTIVE;
+}
+
+/**
+ * Return the relative path to a present `tokens.json`, or `null`.
+ *
+ * Checks {@link BRAND_TOKEN_PATHS} under `root` (default: the current working
+ * directory, which is the consumer project root when the engine runs). The
+ * first existing file wins. Absent → `null` so the caller degrades to default
+ * tokens — the acyclic, graceful-degradation contract.
+ */
+function _brand_token_source(root: string | null = null): string | null {
+    const base = root !== null ? root : process.cwd();
+    for (const rel of BRAND_TOKEN_PATHS) {
+        try {
+            if (fs.statSync(path.join(base, rel)).isFile()) {
+                return rel;
+            }
+        } catch {
+            continue;
+        }
+    }
+    return null;
+}
+
+/**
+ * Describe the token-seed source for the plan directive.
+ *
+ * Brand-seeds from a present DTCG `tokens.json` when one exists; otherwise
+ * instructs the skill to derive from the locked design brief + sane defaults.
+ * Graceful degradation: no token source → defaults, never a hard failure.
+ */
+function _token_seed_line(_state: DeliveryState): string {
+    const source = _brand_token_source();
+    if (source !== null) {
+        return (
+            `> \`token_seed\`: seed from the project's brand/design tokens ` +
+            `at \`${source}\` (DTCG \`tokens.json\`) — the anti-generic moat. ` +
+            `Do NOT fall back to default shadcn tokens when this source is ` +
+            `present; carry its primitives + semantic layers into the plan.`
+        );
+    }
+    return (
+        '> `token_seed`: derive from the locked design brief\'s tokens; ' +
+        'fall back to sane defaults (neutral scale, system font) when the ' +
+        'brief leaves a slot open (no `tokens.json` brand source detected).'
+    );
+}
+
+/** Stage 1 — emit the stack-agnostic plan-derivation directive. */
+function _delegate_plan(state: DeliveryState): StepResult {
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive(PLAN_DIRECTIVE),
+            `> Input: ${_preview_input(state)}`,
+            '> Greenfield scaffold — derive a stack-agnostic skeleton plan ' +
+                'from the confirmed `state.app_spec` (page-set + entity model) ' +
+                'and the locked `state.ui_design` brief. The engine writes no ' +
+                'files; this stage only produces the plan.',
+            '> Write `state.ui_scaffold` = ' +
+                '{pages, routes, layout_strategy, component_manifest, token_seed}.',
+            _token_seed_line(state),
+            '> 1. Continue — derive the scaffold plan into ' +
+                '`state.ui_scaffold`',
+            '> 2. Abort — drop this UI request',
+            '',
+            '**Recommendation: 1 — derive the plan** — the ' +
+                'stack-agnostic plan is the recoverable checkpoint: if the build ' +
+                'stage fails, scaffold re-runs from here without touching design ' +
+                'or apply.',
+        ],
+        message:
+            'Greenfield scaffold plan missing; delegating to ' +
+            '`ui-scaffold-plan` to derive the stack-agnostic skeleton plan.',
+    });
+}
+
+/** Stage 2 — emit the stack-specific skeleton-build directive. */
+function _delegate_build(state: DeliveryState, scaffold: Record<string, Any>): StepResult {
+    const directive = _resolve_build_directive(state);
+    const stack_label = _stack_label(state);
+    const pages = scaffold['pages'];
+    const page_count = Array.isArray(pages) ? pages.length : 0;
+    const routes = scaffold['routes'];
+    const route_count = Array.isArray(routes) ? routes.length : 0;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive(directive),
+            `> 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 ' +
+                'the component-manifest stubs.',
+            '> The engine writes no files: the stack skill creates the ' +
+                'skeleton and writes `state.ui_scaffold.scaffolded = true` plus ' +
+                '`state.ui_scaffold.artifacts` (the created paths).',
+            '> Recoverable: a failed build re-runs from this scaffold step ' +
+                'alone — design and app-spec stay locked.',
+            '> 1. Continue — create the skeleton and mark ' +
+                '`scaffolded = true`',
+            '> 2. Abort — drop this UI request',
+            '',
+            `**Recommendation: 1 — build the skeleton** — the ` +
+                `\`${stack_label}\` scaffold skill materialises the confirmed plan; ` +
+                `the rendered output is verified downstream by the review gate.`,
+        ],
+        message:
+            `Greenfield scaffold plan ready; delegating to \`${directive}\` to ` +
+            `create the skeleton for stack \`${stack_label}\`.`,
+    });
+}

package/src/agent-src/templates/scripts/work_engine/directives/ui_trivial/_skipped.ts

@@ -0,0 +1,33 @@
+/**
+ * Pass-through handler for slots the trivial path skips.
+ *
+ * TypeScript twin of `directives/ui_trivial/_skipped.py` (ADR-200 py2ts).
+ * Public API names stay snake_case to mirror the Python module 1:1.
+ *
+ * The `ui-trivial` directive set short-circuits the audit / design / review /
+ * polish loop. The dispatcher's `STEP_ORDER` is fixed (eight slots, no
+ * branching), so the trivial set fills the unused slots — `memory`,
+ * `analyze`, `plan`, `verify` — with this no-op handler. It returns `SUCCESS`
+ * without touching state, mutates nothing, and declares zero ambiguities.
+ */
+import {
+    type DeliveryState,
+    Outcome,
+    StepResult,
+} from '../../delivery_state.js';
+
+/** No ambiguities — the slot is unconditionally skipped on the trivial path. */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [];
+
+/**
+ * Return `SUCCESS` without touching `state`.
+ *
+ * Shared handler for the slots the trivial path intentionally bypasses.
+ * Keeping the slot wired (rather than raising) preserves the dispatcher's
+ * completeness-check invariant: every slot in `STEP_ORDER` has a callable
+ * handler, every directive set has a uniform shape.
+ */
+export function run(state: DeliveryState): StepResult {
+    void state;
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}

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

@@ -0,0 +1,213 @@
+/**
+ * `apply` step — single-file edit path for the `ui-trivial` set.
+ *
+ * TypeScript twin of `directives/ui_trivial/apply.py` (ADR-200 py2ts).
+ * Public API names stay snake_case to mirror the Python module 1:1.
+ *
+ * The short-circuit path for micro UI edits that provably cannot warrant the
+ * full audit / design / review / polish loop. Hard preconditions enforced on
+ * every rebound: ≤ 1 file, ≤ 5 changed lines, no new component, no new state,
+ * no new dependency. Any precondition violation BLOCKS with a
+ * `reclassify-to-ui-improve` halt; the orchestrator promotes
+ * `state.directive_set` to `"ui-improve"` and re-invokes the engine.
+ */
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+} from '../../delivery_state.js';
+
+/** Edit-surface ceiling — single-file edits only. */
+export const MAX_FILES = 1;
+
+/** Changed-line ceiling — anything larger is structural, not trivial. */
+export const MAX_LINES_CHANGED = 5;
+
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'trivial_envelope_missing',
+        trigger: "state.ticket['trivial_edit'] unset — first pass",
+        resolution:
+            'agent directive `trivial-apply` → agent performs ' +
+            'the single-file edit and writes the envelope back',
+    },
+    {
+        code: 'trivial_preconditions_violated',
+        trigger: 'edit touches >1 file, >5 lines, adds component/state/dependency',
+        resolution:
+            'agent directive `reclassify-to-ui-improve` → ' +
+            "orchestrator promotes directive_set='ui-improve' and re-runs " +
+            'through the full audit gate',
+    },
+];
+
+function _isDict(value: Any): value is Record<string, Any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Python truthiness for the values reached here. */
+function _pyTruthy(value: Any): boolean {
+    if (value === null || value === undefined) return false;
+    if (typeof value === 'string') return value.length > 0;
+    if (typeof value === 'number') return value !== 0;
+    if (typeof value === 'boolean') return value;
+    if (Array.isArray(value)) return value.length > 0;
+    if (typeof value === 'object') return Object.keys(value).length > 0;
+    return true;
+}
+
+/**
+ * Python `int(x)` for the values that reach the precondition check. Mirrors
+ * CPython semantics for the shapes JSON produces:
+ *
+ * - `bool` → 0 / 1.
+ * - integer-valued / fractional `float` → truncate toward zero.
+ * - `str` → parse a base-10 integer literal (optional sign, surrounding
+ *   whitespace allowed); a non-integer string raises `ValueError`.
+ * - `None` / arrays / objects → `TypeError`.
+ *
+ * Returns the int on success, or the sentinel `null` to mirror the
+ * `except (TypeError, ValueError)` branch in the source.
+ */
+function _pyInt(value: Any): number | null {
+    if (typeof value === 'boolean') {
+        return value ? 1 : 0;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            return null; // int(inf)/int(nan) → ValueError/OverflowError
+        }
+        return Math.trunc(value);
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        // Python int() accepts an optional sign + digits + optional `_`
+        // separators between digits. The inputs here are plain integers; match
+        // the common case and reject anything else.
+        if (/^[+-]?[0-9]+$/.test(trimmed)) {
+            return Number(trimmed);
+        }
+        return null;
+    }
+    return null;
+}
+
+/** Apply the trivial-edit gate. */
+export function run(state: DeliveryState): StepResult {
+    const envelope = _trivial_envelope(state);
+    if (envelope === null) {
+        return _delegate_to_agent(state);
+    }
+
+    const violations = _check_preconditions(envelope);
+    if (violations.length > 0) {
+        return _halt_reclassify(state, violations);
+    }
+
+    _record_change(state, envelope);
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}
+
+/** Return the agent-written `trivial_edit` envelope, or `null`. */
+function _trivial_envelope(state: DeliveryState): Record<string, Any> | null {
+    const data = _pyTruthy(state.ticket) ? state.ticket : {};
+    const envelope = (data as Record<string, Any>)['trivial_edit'];
+    if (_isDict(envelope) && _pyTruthy(envelope)) {
+        return envelope;
+    }
+    return null;
+}
+
+/** Return a list of violation codes; empty when all preconditions pass. */
+function _check_preconditions(envelope: Record<string, Any>): string[] {
+    const violations: string[] = [];
+
+    const files = envelope['files'];
+    if (!Array.isArray(files) || files.length === 0) {
+        violations.push('files_missing');
+    } else if (files.length > MAX_FILES) {
+        violations.push(`files_exceeded:${files.length}>${MAX_FILES}`);
+    }
+
+    const lines = envelope['lines_changed'];
+    const lines_int = _pyInt(lines);
+    if (lines_int === null) {
+        violations.push('lines_changed_missing');
+    } else {
+        if (lines_int > MAX_LINES_CHANGED) {
+            violations.push(`lines_exceeded:${lines_int}>${MAX_LINES_CHANGED}`);
+        }
+        if (lines_int < 0) {
+            violations.push('lines_changed_negative');
+        }
+    }
+
+    if (_pyTruthy(envelope['new_component'])) {
+        violations.push('new_component');
+    }
+    if (_pyTruthy(envelope['new_state'])) {
+        violations.push('new_state');
+    }
+    if (_pyTruthy(envelope['new_dependency'])) {
+        violations.push('new_dependency');
+    }
+
+    return violations;
+}
+
+/** First-pass halt — delegate to the agent for the single-file edit. */
+function _delegate_to_agent(state: DeliveryState): StepResult {
+    void state;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('trivial-apply'),
+            '> Trivial UI edit path — audit / design / review skipped.',
+            '> 1. Continue — perform the single-file edit, then ' +
+                'write a `trivial_edit` envelope back into state.ticket ' +
+                '(files, lines_changed, new_component, new_state, new_dependency)',
+            '> 2. Abort — drop this trivial edit',
+        ],
+        message: 'Trivial UI edit pending; delegating to agent for single-file edit.',
+    });
+}
+
+/** BLOCKED halt — orchestrator must reclassify to `ui-improve`. */
+function _halt_reclassify(state: DeliveryState, violations: string[]): StepResult {
+    state.ticket['__reclassify_to__'] = 'ui-improve';
+    delete state.ticket['trivial_edit'];
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('reclassify-to-ui-improve'),
+            '> Trivial-edit preconditions violated; this work needs the ' +
+                'full audit gate.',
+            `> Violations: ${violations.join(', ')}.`,
+            '> 1. Reclassify — orchestrator sets ' +
+                '`state.directive_set = "ui-improve"` and re-runs the engine',
+            '> 2. Abort — drop this UI request',
+        ],
+        message:
+            'Trivial-edit preconditions failed ' +
+            `(${violations.join(', ')}); reclassification required.`,
+    });
+}
+
+/** Write a single `state.changes` entry summarising the trivial edit. */
+function _record_change(state: DeliveryState, envelope: Record<string, Any>): void {
+    const filesRaw = envelope['files'];
+    const files = _pyTruthy(filesRaw) ? filesRaw : [];
+    const lines = 'lines_changed' in envelope ? envelope['lines_changed'] : 0;
+    const summaryRaw = envelope['summary'];
+    const summary = _pyTruthy(summaryRaw) ? summaryRaw : 'trivial UI edit';
+    // `_record_change` only runs after preconditions pass, so `files` is a
+    // non-empty list here; mirror Python `list(files)` with a shallow copy.
+    state.changes.push({
+        kind: 'ui-trivial',
+        files: [...(files as Any[])],
+        lines_changed: lines,
+        summary: summary,
+    });
+}