@event4u/agent-config 8.4.0 → 8.4.1

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

@@ -0,0 +1,111 @@
+/**
+ * UI-trivial directive set — single-file ≤5-line micro-edit path.
+ *
+ * TypeScript twin of `work_engine/directives/ui_trivial/__init__.py` (ADR-200
+ * py2ts Phase 1 — work_engine TOP/integration layer). The `__init__.py` →
+ * `index.ts` mapping mirrors the hooks subpackage convention. Public API names
+ * stay snake_case to mirror the Python module 1:1 (per ADR-200).
+ *
+ * The eight-step shape mirrors `work_engine.directives.backend` /
+ * `work_engine.directives.ui` — eight slots, fixed order, no branching:
+ *
+ * - `refine`    → `refine`   — confirm intent gate.
+ * - `memory`    → `_skipped` — bypassed.
+ * - `analyze`   → `_skipped` — bypassed.
+ * - `plan`      → `_skipped` — bypassed.
+ * - `implement` → `apply`    — hard preconditions; reclassify to `ui-improve`
+ *   (full audit gate) when violated.
+ * - `test`      → `test`     — smoke-test delegate.
+ * - `verify`    → `_skipped` — bypassed.
+ * - `report`    → `report`   — one-line delivery summary.
+ *
+ * The directory uses an underscore (`ui_trivial`) because Python packages
+ * cannot contain hyphens. The schema carries the external hyphenated name
+ * `"ui-trivial"`; the dispatcher's loader is the single place that translates
+ * between them.
+ */
+
+import type { Step } from '../../delivery_state.js';
+
+import * as _skipped from './_skipped.js';
+import * as apply from './apply.js';
+import * as refine from './refine.js';
+import * as report from './report.js';
+import * as test from './test.js';
+
+/**
+ * External name carried in `state.directive_set` for this set.
+ *
+ * Note the hyphen — this is the schema/wire form, not the module name. The
+ * module name (`ui_trivial`) is an implementation detail of the loader.
+ */
+export const DIRECTIVE_SET_NAME = 'ui-trivial';
+
+/** Roadmap that defines this directive bundle (Phase 2 Step 6). */
+export const ROADMAP = 'agents/roadmaps/road-to-product-ui-track.md';
+
+/**
+ * Input kinds this directive set knows how to handle.
+ *
+ * The intent classifier reaches `ui-trivial` from any of the four input
+ * kinds; the trivial set keeps the same tuple so input routing stays
+ * unchanged once the intent label has landed.
+ */
+export const SUPPORTED_KINDS: ReadonlyArray<string> = ['ticket', 'prompt', 'diff', 'file'];
+
+/**
+ * Wire the eight-step dispatcher slots for the trivial set.
+ *
+ * `refine` validates the intent gate; `implement`, `test`, and `report` carry
+ * the trivial-path behavior; the four bypassed slots share `_skipped` so the
+ * dispatcher's completeness check is satisfied without inventing per-slot
+ * stubs. The mapping is rebuilt per call (cheap; the dispatcher invokes
+ * `get_steps` once per run).
+ */
+function _build_step_map(): Map<string, Step> {
+    const skipped = _skipped.run;
+    return new Map<string, Step>([
+        ['refine', refine.run],
+        ['memory', skipped],
+        ['analyze', skipped],
+        ['plan', skipped],
+        ['implement', apply.run],
+        ['test', test.run],
+        ['verify', skipped],
+        ['report', report.run],
+    ]);
+}
+
+/**
+ * Return the `{step_name: handler}` mapping the dispatcher walks.
+ *
+ * Mirrors `work_engine.directives.backend.get_steps`. `refine`, `implement`,
+ * `test`, and `report` carry trivial-path behavior; the four bypassed slots
+ * delegate to `_skipped`.
+ */
+export function get_steps(): Map<string, Step> {
+    return _build_step_map();
+}
+
+/**
+ * Per-step ambiguity declarations.
+ *
+ * Mirrors `work_engine.directives.backend.all_ambiguities`. The four bypassed
+ * slots re-export `_skipped.AMBIGUITIES` (empty) so doc generators see a
+ * uniform shape across all eight steps.
+ */
+export function all_ambiguities(): Record<string, ReadonlyArray<Record<string, string>>> {
+    const skipped = _skipped.AMBIGUITIES;
+    return {
+        refine: refine.AMBIGUITIES,
+        memory: skipped,
+        analyze: skipped,
+        plan: skipped,
+        implement: apply.AMBIGUITIES,
+        test: test.AMBIGUITIES,
+        verify: skipped,
+        report: report.AMBIGUITIES,
+    };
+}
+
+export { apply, refine, report, test };

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

@@ -0,0 +1,126 @@
+/**
+ * `refine` step — intent gate for the `ui-trivial` directive set.
+ *
+ * TypeScript twin of `directives/ui_trivial/refine.py` (ADR-200 py2ts).
+ * Public API names stay snake_case to mirror the Python module 1:1.
+ *
+ * `ui-trivial` is reachable only when the intent classifier (or an explicit
+ * user override) labelled the work as `ui-trivial`. Reaching this slot through
+ * any other route is a routing error, not a user-facing ambiguity.
+ *
+ * The handler is deterministic and tiny: confirm the ticket carries the
+ * expected intent label (or accept the default when `directive_set` is already
+ * pinned), and return `SUCCESS`.
+ */
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+} from '../../delivery_state.js';
+
+/** Intent label that gates entry into this directive set. */
+export const EXPECTED_INTENT = 'ui-trivial';
+
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'wrong_intent_for_trivial',
+        trigger:
+            "state.ticket['intent'] is set and not equal to 'ui-trivial' " +
+            '— routing landed on this set by mistake',
+        resolution:
+            'abort and re-run with the correct directive_set ' +
+            "(populate_routing should select 'ui' or 'backend' instead)",
+    },
+];
+
+/**
+ * Python `repr()` for the scalar/JSON value kinds that reach the `{intent!r}`
+ * interpolation. Mirrors CPython: `None`, `True`/`False`, single-quoted
+ * strings (double-quoted only when the string contains a single quote and no
+ * double quote), numbers and everything else via `str`.
+ */
+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);
+}
+
+/** Python `str(value)` for the scalar kinds reaching the `{intent}` slot. */
+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 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}`;
+}
+
+/**
+ * Confirm the ticket's intent matches the trivial path.
+ *
+ * The ticket's `intent` is optional on v0 callers; absence is treated as a
+ * silent pass since the v0 path predates intent classification. v1 callers
+ * always carry an intent — a mismatch means the dispatcher routed incorrectly
+ * and we halt loudly so the wiring bug surfaces before any edit happens.
+ */
+export function run(state: DeliveryState): StepResult {
+    const ticket = state.ticket ?? {};
+    const intent = ticket['intent'];
+    if (intent === undefined || intent === null || intent === EXPECTED_INTENT) {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            '> Routing error — the ``ui-trivial`` directive set was ' +
+                "selected but the ticket's intent is `" +
+                pyStr(intent) +
+                '`.',
+            '> 1. Reclassify — set `state.directive_set` from the ' +
+                'intent label and re-invoke the engine',
+            '> 2. Abort — drop this run',
+        ],
+        message:
+            `intent=${pyRepr(intent)} but directive_set='ui-trivial'; ` +
+            'routing must be reclassified before any edit',
+    });
+}

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

@@ -0,0 +1,112 @@
+/**
+ * `report` step — one-line delivery summary for the trivial path.
+ *
+ * TypeScript twin of `directives/ui_trivial/report.py` (ADR-200 py2ts).
+ * Public API names stay snake_case to mirror the Python module 1:1.
+ *
+ * The trivial summary captures what the operator needs: which file, how many
+ * lines, what the edit did, and the smoke verdict. The step is pure and
+ * deterministic: reads `DeliveryState`, writes `state.report`, always returns
+ * `SUCCESS`.
+ */
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+} from '../../delivery_state.js';
+
+/** Pure render — no blocked paths. */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [];
+
+/**
+ * Python truthiness for the values reached here: empty string / empty array /
+ * empty object / 0 / false / null / undefined are falsy.
+ */
+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 `str(value)` for the `{lines}` interpolation. */
+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 _isDict(value: Any): value is Record<string, Any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Render the one-line trivial summary into `state.report`. */
+export function run(state: DeliveryState): StepResult {
+    state.report = _render(state);
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}
+
+function _render(state: DeliveryState): string {
+    const change = _last_trivial_change(state);
+    if (change === null) {
+        return '_(trivial UI edit — no change recorded)_';
+    }
+
+    const filesRaw = change['files'];
+    const files = _pyTruthy(filesRaw) ? filesRaw : [];
+    const lines = 'lines_changed' in change ? change['lines_changed'] : 0;
+    const summaryRaw = change['summary'];
+    const summary = (_pyTruthy(summaryRaw) ? String(summaryRaw) : 'trivial UI edit').trim();
+    const file_str =
+        Array.isArray(files) && files.length === 1
+            ? pyStr((files as Any[])[0])
+            : `${Array.isArray(files) ? files.length : 0} files`;
+    const verdict = _smoke_verdict(state);
+    const verdict_str = verdict ? ` — smoke: **${verdict}**` : '';
+    return `**Trivial edit:** ${summary} (\`${file_str}\`, ${pyStr(lines)} lines)${verdict_str}`;
+}
+
+function _last_trivial_change(state: DeliveryState): Record<string, Any> | null {
+    const changes = _pyTruthy(state.changes) ? state.changes : [];
+    for (let i = changes.length - 1; i >= 0; i -= 1) {
+        const change = changes[i];
+        if (_isDict(change) && change['kind'] === 'ui-trivial') {
+            return change;
+        }
+    }
+    return null;
+}
+
+function _smoke_verdict(state: DeliveryState): string {
+    const tests = state.tests;
+    if (_isDict(tests)) {
+        const verdict = tests['verdict'];
+        if (typeof verdict === 'string') {
+            return verdict;
+        }
+    }
+    return '';
+}

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

@@ -0,0 +1,164 @@
+/**
+ * `test` step — smoke-test delegate for the `ui-trivial` set.
+ *
+ * TypeScript twin of `directives/ui_trivial/test.py` (ADR-200 py2ts). Public
+ * API names stay snake_case to mirror the Python module 1:1.
+ *
+ * The trivial path runs "apply + smoke-test only". The handler is the smaller
+ * cousin of `backend.test`: same verdict contract on `state.tests`, narrower
+ * scope on the agent directive. `failed` / `mixed` verdicts halt with the
+ * verdict echoed back; `success` flows through.
+ */
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+} from '../../delivery_state.js';
+
+const _ALLOWED_VERDICTS: ReadonlyArray<string> = ['success', 'failed', 'mixed'];
+
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'empty_tests_delegate',
+        trigger: '`state.tests` empty — smoke runner not invoked yet',
+        resolution:
+            'agent directive `run-tests scope=smoke` → ' +
+            '`/tests-execute` (narrowest layer covering the touched file)',
+    },
+    {
+        code: 'malformed_tests',
+        trigger:
+            '`state.tests` is not a dict or `verdict` is not one of ' +
+            'success / failed / mixed',
+        resolution: 're-run smoke and record a clean verdict',
+    },
+    {
+        code: 'bad_test_verdict',
+        trigger: "`state.tests['verdict']` is `failed` or `mixed`",
+        resolution: 'fix the regression and re-run, or abort',
+    },
+];
+
+function _isDict(value: Any): value is Record<string, Any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Python truthiness for `if not tests`. */
+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 `type(x).__name__` for the dict/non-dict diagnostic. */
+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';
+}
+
+/** Python `repr()` for the verdict value (`{verdict!r}`). */
+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}`;
+}
+
+/** Python `repr()` of the `_ALLOWED_VERDICTS` tuple, for `{_ALLOWED_VERDICTS}`. */
+function _allowedVerdictsRepr(): string {
+    return `(${_ALLOWED_VERDICTS.map((v) => pyStrRepr(v)).join(', ')})`;
+}
+
+/** Gate the smoke verdict; delegate when `state.tests` is empty. */
+export function run(state: DeliveryState): StepResult {
+    const tests = state.tests;
+    if (!_pyTruthy(tests)) {
+        return _delegate();
+    }
+
+    if (!_isDict(tests)) {
+        return _malformed(`state.tests is ${_pyTypeName(tests)}, expected dict`);
+    }
+
+    const verdict = tests['verdict'];
+    if (typeof verdict !== 'string' || !_ALLOWED_VERDICTS.includes(verdict)) {
+        return _malformed(
+            `state.tests['verdict']=${pyRepr(verdict)} not in ${_allowedVerdictsRepr()}`,
+        );
+    }
+
+    if (verdict === 'success') {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            `> Smoke test verdict: **${verdict}** — trivial edit may ` +
+                'have regressed the touched surface.',
+            '> 1. Investigate — read failures, fix, re-run smoke',
+            '> 2. Reclassify — promote to `ui-improve` if the regression ' +
+                'indicates the edit was less trivial than assumed',
+            '> 3. Abort — revert the edit',
+        ],
+        message: `smoke verdict=${verdict} on trivial edit`,
+    });
+}
+
+function _delegate(): StepResult {
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('run-tests', { scope: 'smoke' }),
+            '> Trivial edit applied; run the smoke test layer covering ' +
+                'the touched file.',
+            '> 1. Continue — invoke `/tests-execute` with smoke scope, ' +
+                'then write the verdict back to `state.tests`',
+            '> 2. Skip — record `state.tests = {"verdict": "success", ' +
+                '"scope": "none"}` (logged as a deferred verification)',
+            '> 3. Abort — drop this run',
+        ],
+        message: 'smoke run not yet invoked',
+    });
+}
+
+function _malformed(detail: string): StepResult {
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            `> Malformed test envelope: ${detail}.`,
+            '> 1. Re-run smoke — produce a clean verdict',
+            '> 2. Abort — drop this run',
+        ],
+        message: detail,
+    });
+}