@event4u/agent-config 8.4.0 → 8.4.1

package/src/agent-src/templates/scripts/work_engine/directives/mixed/stitch.ts

@@ -0,0 +1,259 @@
+/**
+ * `stitch` step — integration verification across the contract / UI seam.
+ *
+ * TypeScript twin of `directives/mixed/stitch.py` (ADR-200 py2ts). Public API
+ * names stay snake_case to mirror the Python module 1:1.
+ *
+ * In the `mixed` directive set the `test` slot is the integration boundary.
+ * The dispatcher does not run integration scenarios itself — the agent invokes
+ * the `integration-test` skill which drives end-to-end smokes and writes the
+ * verdict back to `state.stitch`.
+ */
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+} from '../../delivery_state.js';
+
+/** Agent directive that drives end-to-end smoke scenarios. */
+export const INTEGRATION_TEST_DIRECTIVE = 'integration-test';
+
+const _ALLOWED_VERDICTS: ReadonlyArray<string> = ['success', 'blocked', 'partial'];
+
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'upstream_ui_failed',
+        trigger: '`implement` (mixed.ui) outcome is not `success`',
+        resolution: 're-run the mixed flow; UI track must finish before stitch',
+    },
+    {
+        code: 'empty_stitch_delegate',
+        trigger: '`state.stitch` empty — integration-test skill has not run yet',
+        resolution: 'agent directive `integration-test` → end-to-end smokes',
+    },
+    {
+        code: 'malformed_stitch',
+        trigger:
+            '`state.stitch` is not a dict or `verdict` is not one of ' +
+            'success / blocked / partial',
+        resolution: 're-run `integration-test` and record a clean verdict',
+    },
+    {
+        code: 'bad_stitch_verdict',
+        trigger:
+            "`state.stitch['verdict']` is `blocked` or `partial` " +
+            'and `integration_confirmed` is not True',
+        resolution:
+            'address findings and re-run `integration-test`, or set ' +
+            '`integration_confirmed=True` to override (rare)',
+    },
+];
+
+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 _pyTypeName(value: Any): string {
+    if (value === null || value === undefined) return 'NoneType';
+    if (typeof value === 'boolean') return 'bool';
+    if (typeof value === 'number') return Number.isInteger(value) ? 'int' : 'float';
+    if (typeof value === 'string') return 'str';
+    if (Array.isArray(value)) return 'list';
+    return 'dict';
+}
+
+function pyRepr(value: Any): string {
+    if (value === null || value === undefined) return 'None';
+    if (value === true) return 'True';
+    if (value === false) return 'False';
+    if (typeof value === 'string') return pyStrRepr(value);
+    return String(value);
+}
+
+function pyStrRepr(s: string): string {
+    const hasSingle = s.includes("'");
+    const hasDouble = s.includes('"');
+    const quote = hasSingle && !hasDouble ? '"' : "'";
+    let body = '';
+    for (const ch of s) {
+        if (ch === '\\') body += '\\\\';
+        else if (ch === quote) body += `\\${ch}`;
+        else if (ch === '\n') body += '\\n';
+        else if (ch === '\r') body += '\\r';
+        else if (ch === '\t') body += '\\t';
+        else body += ch;
+    }
+    return `${quote}${body}${quote}`;
+}
+
+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, '');
+}
+
+/** Gate on `implement`, then validate `state.stitch`. */
+export function run(state: DeliveryState): StepResult {
+    if (state.outcomes['implement'] !== Outcome.SUCCESS) {
+        return _blocked_on_precondition(state);
+    }
+
+    const stitch = state.stitch;
+    if (!_pyTruthy(stitch)) {
+        return _delegate_to_integration_test(state);
+    }
+
+    const shape_issues = _diagnose_stitch(stitch);
+    if (shape_issues.length > 0) {
+        return _blocked_on_shape(state, shape_issues);
+    }
+
+    const s = stitch as Record<string, Any>;
+    const verdict = s['verdict'];
+    if (verdict === 'success') {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    if (s['integration_confirmed'] === true) {
+        return new StepResult({
+            outcome: Outcome.SUCCESS,
+            message: `stitch verdict \`${pyStr(verdict)}\` overridden by integration_confirmed=True.`,
+        });
+    }
+
+    return _blocked_on_bad_verdict(state, verdict, s);
+}
+
+/** Return shape errors; empty list when `stitch` is well-formed. */
+function _diagnose_stitch(stitch: Any): string[] {
+    if (!_isDict(stitch)) {
+        return [`state.stitch must be a dict, got ${_pyTypeName(stitch)}`];
+    }
+    const verdict = stitch['verdict'];
+    if (typeof verdict !== 'string' || !_ALLOWED_VERDICTS.includes(verdict)) {
+        return [
+            `state.stitch['verdict'] must be one of ` +
+                `${_ALLOWED_VERDICTS.join(', ')}; got ${pyRepr(verdict)}`,
+        ];
+    }
+    return [];
+}
+
+/** One-line preview of the original input for halt bodies. */
+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('')) + '…';
+}
+
+/** BLOCKED halt — upstream UI step did not succeed. */
+function _blocked_on_precondition(state: DeliveryState): StepResult {
+    void state;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            '> Mixed `stitch` step gated on the UI step; ' +
+                'the implement outcome is not success.',
+            '> 1. Re-run — restart the mixed flow from the start',
+            '> 2. Abort — drop this request',
+        ],
+        message: 'stitch step gated on implement; upstream UI outcome is not success.',
+    });
+}
+
+/** Halt with an agent directive so the orchestrator runs smokes. */
+function _delegate_to_integration_test(state: DeliveryState): StepResult {
+    const preview = _preview_input(state);
+    const contract = _isDict(state.contract) ? state.contract : {};
+    const api_surface = _pyTruthy(contract['api_surface']) ? contract['api_surface'] : [];
+    const endpoint_count = Array.isArray(api_surface) ? api_surface.length : 0;
+
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive(INTEGRATION_TEST_DIRECTIVE),
+            `> Input: ${preview}`,
+            '> UI track finished; the contract / UI seam needs end-to-end ' +
+                'verification before the delivery report:',
+            `> - Endpoints / actions to smoke: ${endpoint_count}`,
+            '> Scenarios cover the full round-trip — fill form → ' +
+                'server validation → response → UI update. Unit-level ' +
+                'passes from the UI review do **not** substitute for this gate.',
+            '> 1. Continue — run `integration-test` now',
+            '> 2. Abort — skip integration verification (NOT recommended)',
+        ],
+        message: 'Mixed UI complete; delegating to integration-test for stitch.',
+    });
+}
+
+/** BLOCKED halt — recorded stitch verdict is malformed. */
+function _blocked_on_shape(state: DeliveryState, issues: string[]): StepResult {
+    void state;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            '> Recorded stitch output is malformed: ' + issues.join('; ') + '.',
+            '> 1. Re-run `integration-test` and resume',
+            '> 2. Abort — stitch verdict cannot be trusted',
+        ],
+        message: `Mixed stitch shape invalid: ${issues.join('; ')}.`,
+    });
+}
+
+/** BLOCKED halt — verdict is blocked / partial and not user-confirmed. */
+function _blocked_on_bad_verdict(
+    state: DeliveryState,
+    verdict: Any,
+    stitch: Record<string, Any>,
+): StepResult {
+    void state;
+    const scenarios = _pyTruthy(stitch['scenarios']) ? stitch['scenarios'] : [];
+    const scenario_count = Array.isArray(scenarios) ? scenarios.length : 0;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            `> \`integration-test\` reported \`${pyStr(verdict)}\` after running ` +
+                `${scenario_count} scenario(s). The delivery report cannot ` +
+                'claim completion on a non-success integration verdict.',
+            '> 1. Address the findings and re-run `integration-test`',
+            '> 2. Override — set `state.stitch.integration_confirmed=true` ' +
+                'and resume (rare; document why)',
+            '> 3. Abort',
+        ],
+        message:
+            `Mixed stitch verdict was \`${pyStr(verdict)}\`, not success; ` +
+            'user override required to continue.',
+    });
+}

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

@@ -0,0 +1,216 @@
+/**
+ * `ui` step — delegates to the UI track once the contract is locked.
+ *
+ * TypeScript twin of `directives/mixed/ui.py` (ADR-200 py2ts). Public API
+ * names stay snake_case to mirror the Python module 1:1.
+ *
+ * In the `mixed` directive set the `implement` slot is the UI handoff. It
+ * gates on the upstream contract sentinel
+ * (`state.contract.contract_confirmed is True`) and then delegates the full
+ * audit → design → apply → review → polish sub-flow to the UI track via an
+ * `@agent-directive: ui-track` halt.
+ */
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+} from '../../delivery_state.js';
+
+/** Agent directive that triggers the full UI sub-flow. */
+export const UI_TRACK_DIRECTIVE = 'ui-track';
+
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'upstream_contract_failed',
+        trigger: '`plan` (contract) outcome is not `success`',
+        resolution: 're-run the mixed flow from the start',
+    },
+    {
+        code: 'contract_sentinel_missing',
+        trigger:
+            'state.contract.contract_confirmed is missing or False — ' +
+            'defense-in-depth check refuses to start the UI track',
+        resolution:
+            'loop back to the contract step; user must confirm ' +
+            'the data_model + api_surface lock before UI work begins',
+    },
+    {
+        code: 'ui_track_not_started',
+        trigger:
+            'state.ui_review is empty or missing `review_clean` — ' +
+            'the UI sub-flow has not run yet',
+        resolution:
+            'agent directive `ui-track` → orchestrator runs ' +
+            'audit → design → apply → review → polish with the contract as ' +
+            'immutable input',
+    },
+    {
+        code: 'ui_track_review_unclean',
+        trigger:
+            'UI sub-flow finished but `review_clean` is False — ' +
+            'polish ceiling reached or findings remain',
+        resolution:
+            'user picks re-run / hand off / abort; polish-ceiling ' +
+            'semantics already fired inside the UI track',
+    },
+];
+
+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, '');
+}
+
+/** Delegate the UI sub-flow once the contract is locked. */
+export function run(state: DeliveryState): StepResult {
+    if (state.outcomes['plan'] !== Outcome.SUCCESS) {
+        return _blocked_on_precondition(state);
+    }
+
+    if (!_contract_confirmed(state)) {
+        return _blocked_on_contract_sentinel(state);
+    }
+
+    const review = _isDict(state.ui_review) ? state.ui_review : null;
+    if (review === null || !('review_clean' in review)) {
+        return _delegate_to_ui_track(state);
+    }
+
+    if (review['review_clean'] === true) {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    return _halt_review_unclean(state, review);
+}
+
+/** True when the contract sentinel is explicitly `True`. */
+function _contract_confirmed(state: DeliveryState): boolean {
+    const contract = state.contract;
+    if (!_isDict(contract)) return false;
+    return contract['contract_confirmed'] === true;
+}
+
+/** One-line preview of the original input for halt bodies. */
+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('')) + '…';
+}
+
+/** BLOCKED halt — upstream contract step did not succeed. */
+function _blocked_on_precondition(state: DeliveryState): StepResult {
+    void state;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            '> Mixed `ui` step gated on the contract step; the contract ' +
+                'outcome is not success.',
+            '> 1. Re-run — restart the mixed flow from the start',
+            '> 2. Abort — drop this request',
+        ],
+        message: 'ui step gated on plan; upstream contract outcome is not success.',
+    });
+}
+
+/** BLOCKED halt — contract sentinel missing despite plan success. */
+function _blocked_on_contract_sentinel(state: DeliveryState): StepResult {
+    void state;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            '> Contract sentinel missing — `state.contract.contract_confirmed` ' +
+                'is not `True`. The UI track will not start until the data ' +
+                'model and API surface are locked and confirmed.',
+            '> 1. Loop back — re-enter the contract step and confirm',
+            '> 2. Abort — drop this mixed request',
+        ],
+        message:
+            'ui step refused; contract_confirmed sentinel missing despite plan success.',
+    });
+}
+
+/** Halt with an agent directive so the orchestrator runs the UI track. */
+function _delegate_to_ui_track(state: DeliveryState): StepResult {
+    const preview = _preview_input(state);
+    const contract = _isDict(state.contract) ? state.contract : {};
+    const data_model = _pyTruthy(contract['data_model']) ? contract['data_model'] : [];
+    const api_surface = _pyTruthy(contract['api_surface']) ? contract['api_surface'] : [];
+    const entity_count = Array.isArray(data_model) ? data_model.length : 0;
+    const endpoint_count = Array.isArray(api_surface) ? api_surface.length : 0;
+
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive(UI_TRACK_DIRECTIVE),
+            `> Input: ${preview}`,
+            '> Contract is locked. Handing off to the UI track:',
+            `> - Entities: ${entity_count}`,
+            `> - Endpoints / actions: ${endpoint_count}`,
+            '> The UI track runs audit → design → apply → ' +
+                'review → polish with the contract as immutable input. ' +
+                'No new entities or endpoints — the contract drives the UI shape.',
+            '> 1. Continue — run the UI track',
+            '> 2. Abort — drop this mixed request',
+        ],
+        message: 'Mixed contract locked; delegating UI sub-flow to ui-track.',
+    });
+}
+
+/** BLOCKED halt — UI sub-flow finished but review is not clean. */
+function _halt_review_unclean(state: DeliveryState, review: Record<string, Any>): StepResult {
+    void state;
+    const findings = _pyTruthy(review['findings']) ? review['findings'] : [];
+    const finding_count = Array.isArray(findings) ? findings.length : 0;
+    const lines: string[] = [
+        `> UI track finished but review is not clean. Findings remaining: ${finding_count}.`,
+        '> Polish ceiling already fired inside the UI track — the ' +
+            'engine cannot resolve the remaining findings without a user ' +
+            'decision.',
+        '> 1. Re-run UI track — hand back to `ui-track` for another ' +
+            'audit → design pass (rare; usually means the contract changed)',
+        '> 2. Hand off — ship as-is and let a human resolve the ' +
+            'remaining findings outside the engine',
+        '> 3. Abort — drop this mixed request',
+    ];
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message: `Mixed ui step halted; UI track review unclean (${finding_count} findings).`,
+    });
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Pass-through handler for UI directive slots that have no work.
+ *
+ * TypeScript twin of `directives/ui/_passthrough.py` (ADR-200 py2ts). Public
+ * API names stay snake_case to mirror the Python module 1:1 (Python style is
+ * part of the contract). The handler is intentionally pure and
+ * side-effect-free: it neither reads nor writes `state`.
+ *
+ * Phase 6 of the UI track retired the Phase 3 deferral stub once design /
+ * apply / review / polish landed. Two slots remain semantically empty for the
+ * UI track:
+ *
+ * - `memory` — the UI track does not consult the memory types the
+ *   backend retrieves over. UI work pivots on the audit findings in
+ *   `state.ui_audit` instead.
+ * - `plan` — `.design` produces the locked design brief that `.apply`
+ *   follows verbatim. The brief IS the plan.
+ *
+ * Both slots return `Outcome.SUCCESS` without writing to state.
+ */
+import {
+    type DeliveryState,
+    Outcome,
+    StepResult,
+} from '../../delivery_state.js';
+
+/** Pass-through never blocks — empty surface, declared intent. */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [];
+
+/**
+ * Return `SUCCESS` without mutating state.
+ *
+ * The handler neither reads nor writes `state`. The dispatcher records the
+ * step as successful in `state.outcomes` (its own bookkeeping) and advances to
+ * the next slot.
+ */
+export function run(state: DeliveryState): StepResult {
+    void state; // explicitly unused — the slot is a no-op by design
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}