@event4u/agent-config 8.4.0 → 8.4.1

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

@@ -0,0 +1,241 @@
+/**
+ * `app_spec` step — greenfield grounding gate (the `memory` slot).
+ *
+ * TypeScript twin of `directives/ui/app_spec.py` (ADR-200 py2ts). Public API
+ * names stay snake_case to mirror the Python module 1:1.
+ *
+ * greenfield-scaffold Phase 2: before any scaffolding, derive the app shape and
+ * confirm it fast (disambiguation, not BDUF). The step occupies the UI set's
+ * `memory` slot, which runs **before** `analyze` (design); it replaces the
+ * former no-op pass-through there.
+ *
+ * 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.
+ */
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+} from '../../delivery_state.js';
+
+/** Declared ambiguity surfaces for this step. */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'app_spec_missing',
+        trigger:
+            'greenfield scaffold path and state.app_spec is None / ' +
+            'empty / carries no `pages` — the app-spec skill has not derived ' +
+            'the page-set yet',
+        resolution:
+            'agent directive `app-spec` → skill derives ' +
+            '{pages, entity_model, flow_map} and writes them into ' +
+            'state.app_spec (or the user bypasses with \'just scaffold\')',
+    },
+    {
+        code: 'app_spec_unconfirmed',
+        trigger:
+            'greenfield scaffold path and state.app_spec carries a ' +
+            'derived page-set but `confirmed` is not True and `bypassed` is ' +
+            'not set — the user has not signed off on the derived shape',
+        resolution:
+            'user confirms the derived page-set + entity model ' +
+            '(agent sets state.app_spec.confirmed = True), edits and re-runs, ' +
+            'or bypasses (\'just scaffold\' → state.app_spec.bypassed = True)',
+    },
+];
+
+function _isDict(value: Any): value is Record<string, Any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+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, '');
+}
+
+/**
+ * Apply the greenfield app-spec grounding gate.
+ *
+ * No-op `SUCCESS` for every non-greenfield-scaffold flow; the confirm/bypass
+ * gate 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 spec = state.app_spec;
+
+    // Explicit bypass — "just scaffold" / fenced step. Honoured before any
+    // populated-check so the user can skip derivation entirely.
+    if (_isDict(spec) && _pyTruthy(spec['bypassed'])) {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    if (!_is_populated(spec)) {
+        return _delegate_to_app_spec_skill(state);
+    }
+
+    const specDict = spec as Record<string, Any>;
+    // Idempotent: a confirmed spec round-trips through SUCCESS without
+    // re-emitting the halt the user already answered.
+    if (specDict['confirmed'] === true) {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    return _halt_unconfirmed(state, specDict);
+}
+
+/**
+ * True when the audit recorded a `scaffold` greenfield decision.
+ *
+ * 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.
+ */
+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 `spec` carries a derived page-set.
+ *
+ * Non-dict and empty-dict shapes are treated as "skill has not run". The
+ * skill's first deliverable is the `pages` list, so its presence is the
+ * populated signal.
+ */
+function _is_populated(spec: Any): boolean {
+    return _isDict(spec) && Array.isArray(spec['pages']);
+}
+
+/** Render a one-line preview of the input being grounded. */
+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('')) + '…';
+}
+
+/** First-pass halt — emit the `app-spec` derivation directive. */
+function _delegate_to_app_spec_skill(state: DeliveryState): StepResult {
+    const preview = _preview_input(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('app-spec'),
+            `> Input: ${preview}`,
+            '> Greenfield scaffold — grounding the app shape before any ' +
+                'skeleton is planned. Derive the page-set, entity model, and ' +
+                'flow-map from the prompt.',
+            '> 1. Continue — derive {pages, entity_model, flow_map} ' +
+                'into `state.app_spec`',
+            '> 2. Just scaffold — skip the app spec (set ' +
+                '`state.app_spec.bypassed = true` and go straight to scaffold)',
+            '> 3. Abort — drop this UI request',
+            '',
+            '**Recommendation: 1 — derive the spec** — a ' +
+                'confirmed page-set keeps the multi-page scaffold coherent ' +
+                'and is seconds of work. Caveat: flip to 2 if the prompt ' +
+                'already pins an exact, single-screen shape.',
+        ],
+        message:
+            'Greenfield app-spec missing; delegating to `app-spec` ' +
+            'skill to derive the page-set before scaffold.',
+    });
+}
+
+/** BLOCKED halt — derived spec needs the lightweight confirm or bypass. */
+function _halt_unconfirmed(state: DeliveryState, spec: Record<string, Any>): StepResult {
+    const rawPages = Array.isArray(spec['pages']) ? (spec['pages'] as Any[]) : [];
+    const pages = rawPages.filter((p) => typeof p === 'string' || _isDict(p));
+    const rawEntities = Array.isArray(spec['entity_model']) ? (spec['entity_model'] as Any[]) : [];
+    const entities = rawEntities.filter((e) => typeof e === 'string' || _isDict(e));
+    const lines: string[] = [
+        `> Input: ${_preview_input(state)}`,
+        '> Derived app spec — confirm the shape before scaffold:',
+        `> Pages (${pages.length}): ${_summarize(pages)}`,
+        `> Entities (${entities.length}): ${_summarize(entities)}`,
+        '> 1. Confirm — the derived page-set + entity model look right ' +
+            '(set `state.app_spec.confirmed = true`)',
+        '> 2. Edit — adjust the derived spec, then re-run the app-spec ' +
+            'skill',
+        '> 3. Just scaffold — skip confirmation (set ' +
+            '`state.app_spec.bypassed = true`)',
+        '',
+        '**Recommendation: 1 — Confirm** — the derived shape is ' +
+            'the cheapest point to catch a wrong page-set, before the scaffold ' +
+            'plan locks routes and layout. Caveat: flip to 2 if a page or ' +
+            'entity is missing / wrong.',
+    ];
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message:
+            'Greenfield app-spec derived; halting for lightweight confirm ' +
+            '(confirm / edit / bypass).',
+    });
+}
+
+/** Render up to three item names as a compact inline preview. */
+function _summarize(items: Any[]): string {
+    const names: string[] = [];
+    for (const item of items.slice(0, 3)) {
+        if (typeof item === 'string') {
+            names.push(item);
+        } else if (_isDict(item)) {
+            // Python `item.get("name") or item.get("title") or item.get("path")`:
+            // first truthy by Python rules ([] / {} are falsy, unlike JS `||`).
+            const name = _pyTruthy(item['name'])
+                ? item['name']
+                : _pyTruthy(item['title'])
+                  ? item['title']
+                  : item['path'];
+            names.push(_pyTruthy(name) ? pyStr(name) : '(unnamed)');
+        }
+    }
+    if (names.length === 0) {
+        return '(none)';
+    }
+    const suffix = items.length > 3 ? ', …' : '';
+    return names.join(', ') + suffix;
+}

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

@@ -0,0 +1,216 @@
+/**
+ * `apply` step — stack-dispatched UI implementation.
+ *
+ * TypeScript twin of `directives/ui/apply.py` (ADR-200 py2ts). Public API
+ * names stay snake_case to mirror the Python module 1:1.
+ *
+ * The apply step turns the locked design brief into actual files. Routes on
+ * `state.stack.frontend` to the appropriate implementation skill bundle, and
+ * on `state.ticket["ui_apply"]` shape: first-pass delegation, placeholder
+ * 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 {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+} from '../../delivery_state.js';
+import { PLACEHOLDER_PATTERNS } from './design.js';
+
+/** Map `state.stack.frontend` → agent-directive skill name. */
+export const STACK_DIRECTIVES: Record<string, string> = {
+    'blade-livewire-flux': 'ui-apply-blade-livewire-flux',
+    'react-shadcn': 'ui-apply-react-shadcn',
+    vue: 'ui-apply-vue',
+    plain: 'ui-apply-plain',
+};
+
+/** Fallback directive when `state.stack` is missing or malformed. */
+export const DEFAULT_DIRECTIVE = 'ui-apply-plain';
+
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'apply_envelope_missing',
+        trigger:
+            "state.ticket['ui_apply'] unset — first pass, " +
+            'stack-specific skill has not run yet',
+        resolution:
+            'agent directive `ui-apply-<stack>` → skill ' +
+            'bundle implements the brief and writes the envelope back',
+    },
+    {
+        code: 'apply_placeholders_in_output',
+        trigger:
+            'rendered text in apply envelope contains ' +
+            'placeholder patterns (<placeholder>, Lorem, TODO:, TBD, XXX) ' +
+            '— design-brief lock failed mid-loop',
+        resolution:
+            'agent re-renders the components with the locked ' +
+            'microcopy verbatim from state.ui_design.microcopy',
+    },
+];
+
+function _isDict(value: Any): value is Record<string, Any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+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;
+}
+
+/** Apply the stack-dispatched implementation gate. */
+export function run(state: DeliveryState): StepResult {
+    const envelope = _apply_envelope(state);
+    if (envelope === null) {
+        return _delegate_to_stack_skill(state);
+    }
+
+    const violations = _placeholder_violations_in_output(envelope);
+    if (violations.length > 0) {
+        return _halt_placeholders(state, violations);
+    }
+
+    _record_changes(state, envelope);
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}
+
+/** 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 : {};
+    const envelope = (data as Record<string, Any>)['ui_apply'];
+    if (_isDict(envelope) && _pyTruthy(envelope)) {
+        return envelope;
+    }
+    return null;
+}
+
+/** Pick the agent directive for the project's frontend stack. */
+function _resolve_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 paths into `envelope['rendered']` whose text matches a pattern. */
+function _placeholder_violations_in_output(envelope: Record<string, Any>): string[] {
+    const rendered = envelope['rendered'];
+    if (!_isDict(rendered)) {
+        return [];
+    }
+    const violations: string[] = [];
+    _walk_rendered(rendered, '', violations);
+    return violations;
+}
+
+function _walk_rendered(node: Record<string, Any>, prefix: string, violations: string[]): void {
+    for (const key of Object.keys(node)) {
+        const value = node[key];
+        const path = prefix ? `${prefix}.${key}` : String(key);
+        if (_isDict(value)) {
+            _walk_rendered(value, path, violations);
+            continue;
+        }
+        if (typeof value !== 'string') {
+            continue;
+        }
+        const lowered = value.toLowerCase();
+        for (const pattern of PLACEHOLDER_PATTERNS) {
+            if (lowered.includes(pattern)) {
+                violations.push(path);
+                break;
+            }
+        }
+    }
+}
+
+/** First-pass halt — emit the stack-specific apply directive. */
+function _delegate_to_stack_skill(state: DeliveryState): StepResult {
+    const directive = _resolve_directive(state);
+    const stack_label = _stack_label(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive(directive),
+            `> Stack: \`${stack_label}\`. Implementing the locked design brief.`,
+            '> Microcopy is locked — every button label, empty-state ' +
+                'message, and validation message must come verbatim from ' +
+                '`state.ui_design.microcopy`.',
+            '> 1. Continue — implement the brief and write a ' +
+                '`ui_apply` envelope back into state.ticket ' +
+                '(rendered: {path: text}, files: [...])',
+            '> 2. Abort — drop this UI request',
+        ],
+        message: `UI apply pending; delegating to \`${directive}\` for stack \`${stack_label}\`.`,
+    });
+}
+
+/** BLOCKED halt — rendered output still carries placeholder patterns. */
+function _halt_placeholders(state: DeliveryState, violations: string[]): StepResult {
+    const directive = _resolve_directive(state);
+    const lines: string[] = [
+        agent_directive(directive),
+        '> Apply rejected: rendered output contains placeholder strings. ' +
+            'The design-brief microcopy lock failed mid-loop.',
+        '> Affected paths in `ui_apply.rendered`:',
+    ];
+    for (const p of violations) {
+        lines.push(`> - \`${p}\``);
+    }
+    lines.push(
+        '> Re-render with the locked microcopy verbatim from ' +
+            '`state.ui_design.microcopy`; apply will not write placeholder text.',
+    );
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message:
+            `UI apply rejected: ${violations.length} placeholder ` +
+            'violation(s) in rendered output.',
+    });
+}
+
+/** Append one `state.changes` entry per file in the apply envelope. */
+function _record_changes(state: DeliveryState, envelope: Record<string, Any>): void {
+    let files = envelope['files'];
+    if (!Array.isArray(files)) {
+        files = [];
+    }
+    const summary = _pyTruthy(envelope['summary']) ? envelope['summary'] : 'ui apply';
+    const stack_label = _stack_label(state);
+    for (const p of files as Any[]) {
+        if (typeof p !== 'string' || p === '') {
+            continue;
+        }
+        state.changes.push({
+            kind: 'ui',
+            stack: stack_label,
+            file: p,
+            summary: summary,
+        });
+    }
+}
+
+/** 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';
+}