@event4u/agent-config 6.1.0 → 7.0.1

package/dist/agent-src/templates/scripts/work_engine/directives/backend/verify.ts

@@ -0,0 +1,258 @@
+/**
+ * `verify` step — gate + Option-A delegation to `review-changes`.
+ *
+ * TypeScript twin of `work_engine/directives/backend/verify.py` (ADR-200
+ * py2ts Phase 1 — work_engine directive sets). Public API names stay
+ * snake_case to mirror the Python module 1:1 (per ADR-200 — Python style is
+ * part of the contract).
+ *
+ * The dispatcher does not run the review-changes judges itself; the
+ * agent invokes the composite review (bug-hunter + security +
+ * test-coverage + code-quality) and captures the consolidated
+ * verdict onto `state.verify`.
+ *
+ * `state.verify` contract when populated:
+ *
+ * - Must be a dict.
+ * - Must carry a `verdict` key — one of `success`, `blocked`,
+ *   `partial`. Matches the `Outcome` vocabulary used everywhere
+ *   else in the flow.
+ * - A `success` verdict advances the flow to `report`.
+ * - A `blocked` or `partial` verdict halts with numbered options
+ *   so the user decides whether to address the findings, override
+ *   (rarely appropriate), or abort.
+ * - Optional keys (`confidence`, `findings`, `followups`) feed
+ *   the delivery report.
+ */
+
+import type { DeliveryState} from '../../delivery_state.js';
+import { type Any, Outcome, StepResult, agent_directive } from '../../delivery_state.js';
+import { resolve_policy } from '../../persona_policy.js';
+
+const _ALLOWED_VERDICTS = ['success', 'blocked', 'partial'] as const;
+
+/** Declared ambiguity surfaces. Advisory personas skip this step entirely. */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'upstream_test_failed',
+        trigger: '`test` outcome is not `success`',
+        resolution: 're-run `/implement-ticket` from the start',
+    },
+    {
+        code: 'empty_verify_delegate',
+        trigger: '`state.verify` empty — four-judge review not run yet',
+        resolution: 'agent directive `review-changes` → `/review-changes`',
+    },
+    {
+        code: 'malformed_verify',
+        trigger: '`state.verify` is not a dict or `verdict` is not one of ' + 'success / blocked / partial',
+        resolution: 're-run `/review-changes` and record a clean verdict',
+    },
+    {
+        code: 'bad_verify_verdict',
+        trigger: '`state.verify[\'verdict\']` is `blocked` or `partial`',
+        resolution:
+            'address findings and re-run `/review-changes` — never bypass ' + '(see `verify-before-complete`)',
+    },
+];
+
+/** Gate on `test`, then either delegate or validate `state.verify`. */
+export function run(state: DeliveryState): StepResult {
+    const policy = resolve_policy(state.persona);
+    if (!policy.allows_verify) {
+        return new StepResult({
+            outcome: Outcome.SUCCESS,
+            message: `verify skipped: persona \`${policy.name}\` is plan-only.`,
+        });
+    }
+
+    if (state.outcomes.test !== Outcome.SUCCESS) {
+        return _blocked_on_precondition(state);
+    }
+
+    const verify = state.verify;
+    if (!_pyTruthy(verify)) {
+        return _delegate_to_review_changes(state);
+    }
+
+    const shapeIssues = _diagnose_verify(verify);
+    if (shapeIssues.length > 0) {
+        return _blocked_on_shape(state, shapeIssues);
+    }
+
+    const verdict = (verify as Record<string, unknown>).verdict;
+    if (verdict !== 'success') {
+        return _blocked_on_bad_verdict(state, verdict);
+    }
+
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}
+
+function _diagnose_verify(verify: Any): string[] {
+    if (!_isPlainObject(verify)) {
+        return [`state.verify must be a dict, got ${_pyTypeName(verify)}`];
+    }
+    const verdict = (verify as Record<string, unknown>).verdict;
+    if (!_inAllowedVerdicts(verdict)) {
+        return [
+            `state.verify['verdict'] must be one of ` +
+                `${_ALLOWED_VERDICTS.join(', ')}; got ${_pyRepr(verdict)}`,
+        ];
+    }
+    return [];
+}
+
+function _delegate_to_review_changes(state: DeliveryState): StepResult {
+    const ticketId = _ticketId(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('review-changes', { ticket: ticketId }),
+            `> Ticket ${ticketId} — running the four-judge review ` +
+                '(bugs, security, tests, code quality) before the delivery ' +
+                'report is written.',
+            '> 1. Continue — run `review-changes` now',
+            '> 2. Abort — skip review (NOT recommended)',
+        ],
+        message: `Ticket ${ticketId} needs \`review-changes\` before the report.`,
+    });
+}
+
+function _blocked_on_precondition(state: DeliveryState): StepResult {
+    const ticketId = _ticketId(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            `> Ticket ${ticketId} — verify gate refused: ` +
+                '`test` step did not complete successfully.',
+            '> 1. Re-run `/implement-ticket` from the start',
+            '> 2. Abort',
+        ],
+        message: `Ticket ${ticketId} cannot verify: test gate did not pass.`,
+    });
+}
+
+function _blocked_on_shape(state: DeliveryState, issues: string[]): StepResult {
+    const ticketId = _ticketId(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            `> Ticket ${ticketId} — recorded verify output is malformed: ` + issues.join('; ') + '.',
+            '> 1. Re-run `review-changes` and resume',
+            '> 2. Abort — verify verdict cannot be trusted',
+        ],
+        message: `Ticket ${ticketId} verify shape invalid: ${issues.join('; ')}.`,
+    });
+}
+
+function _blocked_on_bad_verdict(state: DeliveryState, verdict: Any): StepResult {
+    const ticketId = _ticketId(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            `> Ticket ${ticketId} — \`review-changes\` reported ` +
+                `\`${String(verdict)}\`. The delivery report cannot claim completion on a ` +
+                'non-success verdict (see `verify-before-complete`).',
+            '> 1. Address the findings and re-run `review-changes`',
+            '> 2. Continue anyway — override (NOT recommended)',
+            '> 3. Abort',
+        ],
+        message: `Ticket ${ticketId} verify verdict was \`${String(verdict)}\`, not success.`,
+    });
+}
+
+/** `(state.ticket or {}).get("id") or "(no id)"`. */
+function _ticketId(state: DeliveryState): string {
+    const id = (state.ticket ?? {}).id;
+    return _pyTruthy(id) ? String(id) : '(no id)';
+}
+
+function _inAllowedVerdicts(value: unknown): boolean {
+    return (_ALLOWED_VERDICTS as ReadonlyArray<unknown>).includes(value);
+}
+
+/** Python truthiness for the scalar/container kinds these slices carry. */
+function _pyTruthy(value: unknown): boolean {
+    if (value === null || value === undefined || value === false) {
+        return false;
+    }
+    if (value === true) {
+        return true;
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    if (typeof value === 'string') {
+        return value.length !== 0;
+    }
+    if (Array.isArray(value)) {
+        return value.length !== 0;
+    }
+    if (value instanceof Set || value instanceof Map) {
+        return value.size !== 0;
+    }
+    if (typeof value === 'object') {
+        return Object.keys(value as Record<string, unknown>).length !== 0;
+    }
+    return true;
+}
+
+/** True for a dict-like value (mirrors Python `isinstance(x, dict)`). */
+function _isPlainObject(value: unknown): value is Record<string, unknown> {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Set) &&
+        !(value instanceof Map)
+    );
+}
+
+/** Python `type(x).__name__` for the value kinds the diagnose paths see. */
+function _pyTypeName(value: unknown): 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';
+    }
+    if (value instanceof Set) {
+        return 'set';
+    }
+    if (value instanceof Map || _isPlainObject(value)) {
+        return 'dict';
+    }
+    return typeof value;
+}
+
+/**
+ * Python `repr()` for the verdict value kinds (`{verdict!r}`).
+ *
+ * Strings render single-quoted; `None` → `None`; booleans → `True` / `False`;
+ * numbers as-is. Only the kinds an invalid `verdict` slot can carry are
+ * covered.
+ */
+function _pyRepr(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'None';
+    }
+    if (value === true) {
+        return 'True';
+    }
+    if (value === false) {
+        return 'False';
+    }
+    if (typeof value === 'string') {
+        return `'${value}'`;
+    }
+    return String(value);
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Directive-set bundles consumed by the dispatcher.
+ *
+ * TypeScript twin of `work_engine/directives/__init__.py` (ADR-200 py2ts
+ * Phase 1 — work_engine TOP/integration layer). The `__init__.py` → `index.ts`
+ * mapping mirrors the hooks subpackage convention.
+ *
+ * A *directive set* is a coherent group of step handlers (refine,
+ * memory, analyze, plan, implement, test, verify, report) tuned for a
+ * particular kind of work — backend coding, UI work, mixed front+back
+ * work, and so on. The dispatcher selects exactly one set per cycle
+ * (see `dispatcher.select_directive_set`) and walks its eight steps
+ * in the canonical order.
+ *
+ * Each set is a sub-package exposing a single function:
+ *
+ *     function get_steps(): Mapping<string, Step>
+ *
+ * The mapping must cover every entry in `dispatcher.STEP_ORDER`;
+ * incomplete bundles raise at dispatch time.
+ *
+ * The schema (`state.KNOWN_DIRECTIVE_SETS`) carries the *external*
+ * names `ui`, `ui-trivial`, `mixed`; the directory layout uses
+ * underscores (`ui_trivial`) because Python packages cannot contain
+ * hyphens. The dispatcher's loader is the single place that translates
+ * between the two.
+ */
+
+// The Python `__init__` declares `__all__: list[str] = []` — no re-exports.
+// This twin is the package marker module; consumers import the per-set
+// `index.ts` directly (e.g. `./backend/index.js`).
+export {};

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

@@ -0,0 +1,243 @@
+/**
+ * `contract` step — locks data_model + api_surface before any UI work.
+ *
+ * TypeScript twin of `directives/mixed/contract.py` (ADR-200 py2ts). Public
+ * API names stay snake_case to mirror the Python module 1:1.
+ *
+ * In the `mixed` directive set the `plan` slot is the contract step. It
+ * resolves the backend contract the UI will consume — entity shape, endpoint
+ * signatures, validation surface — before the UI track runs. The mixed `ui`
+ * step gates on `state.contract.contract_confirmed is True`.
+ */
+import {
+    type Any,
+    type DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+} from '../../delivery_state.js';
+
+/** Top-level keys every well-formed contract must carry. */
+export const REQUIRED_CONTRACT_KEYS: ReadonlyArray<string> = ['data_model', 'api_surface'];
+
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'upstream_analyze_failed',
+        trigger: '`analyze` outcome is not `success`',
+        resolution: 're-run the mixed flow from the start',
+    },
+    {
+        code: 'contract_missing',
+        trigger: 'state.contract is None or empty — contract has not been produced',
+        resolution:
+            'agent directive `contract-plan` → `feature-plan` skill ' +
+            'writes the contract into state.contract',
+    },
+    {
+        code: 'contract_incomplete',
+        trigger:
+            'contract is populated but missing required keys ' +
+            '(`data_model`, `api_surface`) or one of them is empty',
+        resolution:
+            'agent re-runs `feature-plan` with contract-only scope; ' +
+            'halt lists the missing slots',
+    },
+    {
+        code: 'contract_unconfirmed',
+        trigger: 'contract is well-formed but contract_confirmed is unset/False',
+        resolution:
+            'user reviews the contract summary and sets ' +
+            'state.contract.contract_confirmed = True (or asks for ' +
+            'revisions, which loops back to contract-plan)',
+    },
+];
+
+function _isDict(value: Any): value is Record<string, Any> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Python `value is None or value == [] or value == {}` — the contract step's
+ * emptiness check. NOTE: unlike `directives/ui/design`, contract does NOT treat
+ * an empty string `""` as missing; only None / empty list / empty dict count.
+ */
+function _isEmptyOrNone(value: Any): boolean {
+    if (value === null || value === undefined) return true;
+    if (Array.isArray(value)) return value.length === 0;
+    if (_isDict(value)) return Object.keys(value).length === 0;
+    return false;
+}
+
+/** Apply the contract-first lock to `state.contract`. */
+export function run(state: DeliveryState): StepResult {
+    if (state.outcomes['analyze'] !== Outcome.SUCCESS) {
+        return _blocked_on_precondition(state);
+    }
+
+    const contract = state.contract;
+    if (!_is_populated(contract)) {
+        return _delegate_to_feature_plan(state);
+    }
+
+    const missing = _missing_required_keys(contract as Record<string, Any>);
+    if (missing.length > 0) {
+        return _halt_incomplete_contract(state, missing);
+    }
+
+    if ((contract as Record<string, Any>)['contract_confirmed'] === true) {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    return _halt_unconfirmed(state, contract as Record<string, Any>);
+}
+
+/** True when `contract` carries an actionable backend lock. */
+function _is_populated(contract: Any): boolean {
+    if (!_isDict(contract)) return false;
+    if (Object.keys(contract).length === 0) return false;
+    return REQUIRED_CONTRACT_KEYS.some((key) => key in contract);
+}
+
+/** Return required top-level keys that are missing or empty. */
+function _missing_required_keys(contract: Record<string, Any>): string[] {
+    const missing: string[] = [];
+    for (const key of REQUIRED_CONTRACT_KEYS) {
+        const value = contract[key];
+        if (_isEmptyOrNone(value)) {
+            missing.push(key);
+        }
+    }
+    return missing;
+}
+
+/** Render a one-line preview of the input being contracted. */
+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((s) => s.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('')) + '…';
+}
+
+/** Python `str.rstrip()` (no arg) — strip trailing whitespace. */
+function _pyRStrip(s: string): string {
+    return s.replace(/\s+$/u, '');
+}
+
+/** Python truthiness (used for the `data.get("id") or "(no title)"` chain). */
+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)`. */
+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);
+}
+
+/** BLOCKED halt — upstream `analyze` did not succeed. */
+function _blocked_on_precondition(state: DeliveryState): StepResult {
+    void state;
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            '> `analyze` did not succeed; cannot lock the contract until ' +
+                'the upstream investigation lands.',
+            '> 1. Re-run — restart the mixed flow from the start',
+            '> 2. Abort — drop this request',
+        ],
+        message: 'contract step gated on analyze; upstream outcome is not success.',
+    });
+}
+
+/** Halt with an agent directive so the orchestrator runs `feature-plan`. */
+function _delegate_to_feature_plan(state: DeliveryState): StepResult {
+    const preview = _preview_input(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('contract-plan'),
+            `> Input: ${preview}`,
+            '> No backend contract yet — producing one now. The contract ' +
+                'locks the data model and API surface the UI will consume; ' +
+                'the mixed `ui` step refuses to start without it.',
+            '> Scope: contract-only (no UI plan, no implementation).',
+            '> 1. Continue — produce the contract via `feature-plan`',
+            '> 2. Abort — drop this mixed request',
+        ],
+        message: 'Mixed contract missing; delegating to feature-plan (contract-only).',
+    });
+}
+
+/** BLOCKED halt — contract is missing required keys. */
+function _halt_incomplete_contract(state: DeliveryState, missing: string[]): StepResult {
+    const preview = _preview_input(state);
+    const lines: string[] = [
+        agent_directive('contract-plan'),
+        `> Input: ${preview}`,
+        '> Backend contract is incomplete. Missing required slots:',
+    ];
+    for (const p of missing) {
+        lines.push(`> - \`${p}\``);
+    }
+    lines.push(
+        '> Re-run `feature-plan` (contract-only) so every required slot ' +
+            'has a final value before the UI track starts.',
+    );
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message: `Mixed contract incomplete; ${missing.length} required slot(s) missing.`,
+    });
+}
+
+/** BLOCKED halt — contract is well-formed; user must sign off. */
+function _halt_unconfirmed(state: DeliveryState, contract: Record<string, Any>): StepResult {
+    const preview = _preview_input(state);
+    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;
+
+    const lines: string[] = [
+        `> Input: ${preview}`,
+        '> Backend contract is ready. Summary:',
+        `> - Entities (data model): ${entity_count}`,
+        `> - Endpoints / actions (api surface): ${endpoint_count}`,
+        '> 1. Confirm — lock this contract and advance to the UI track',
+        '> 2. Revise — send feedback; loops back to `contract-plan`',
+        '> 3. Abort — drop this mixed request',
+        '',
+        '**Recommendation: 1 — Confirm** — the contract covers both ' +
+            'required slots. Caveat: flip to 2 only if an entity field or ' +
+            'endpoint signature is wrong; the UI track will treat this ' +
+            'contract as immutable input.',
+    ];
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: lines,
+        message: 'Mixed contract ready; halting for user confirmation before UI track.',
+    });
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Mixed (backend + UI) directive set.
+ *
+ * TypeScript twin of `work_engine/directives/mixed/__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).
+ *
+ * `mixed` is the directive set for tickets that touch both layers. Its plan
+ * slot locks the backend contract (data shape + API surface) before any UI
+ * work begins; its implement slot delegates the full UI sub-flow once the
+ * contract is confirmed; its test slot stitches the seam with end-to-end smoke
+ * scenarios.
+ *
+ * Slot mapping (mirrors `work_engine.directives.backend.get_steps`):
+ *
+ * - `refine`    → backend.refine  — intent classification + ticket / prompt gate.
+ * - `memory`    → backend.memory  — engineering-memory pull.
+ * - `analyze`   → backend.analyze — backend analysis precondition.
+ * - `plan`      → `contract`      — backend contract lock.
+ * - `implement` → `ui`            — delegate to UI sub-flow.
+ * - `test`      → `stitch`        — integration verification.
+ * - `verify`    → backend.verify  — four-judge review on the merged diff.
+ * - `report`    → backend.report  — delivery markdown.
+ *
+ * The shared steps are reused by reference, not by duplication.
+ */
+
+import type { Step } from '../../delivery_state.js';
+import {
+    analyze as backend_analyze,
+    memory as backend_memory,
+    refine as backend_refine,
+    report as backend_report,
+    verify as backend_verify,
+} from '../backend/index.js';
+
+import * as contract from './contract.js';
+import * as stitch from './stitch.js';
+import * as ui from './ui.js';
+
+/** External name carried in `state.directive_set` for this set. */
+export const DIRECTIVE_SET_NAME = 'mixed';
+
+/** Roadmap that promotes the Phase 4 stub to working handlers. */
+export const ROADMAP = 'agents/roadmaps/road-to-product-ui-track.md';
+
+/**
+ * Input kinds this directive set accepts.
+ *
+ * `mixed` accepts the same envelope shapes as `backend`: ticket payloads
+ * (refined by the ticket flow) and free-form prompts (refined by
+ * `refine-prompt`). The `diff` / `file` envelopes stay UI-only since they
+ * describe an existing screen, not a backend contract surface.
+ */
+export const SUPPORTED_KINDS: ReadonlyArray<string> = ['ticket', 'prompt'];
+
+/**
+ * Wire the eight-step dispatcher slots for the mixed set.
+ *
+ * `refine` / `memory` / `analyze` / `verify` / `report` reuse the backend
+ * handlers verbatim; `plan` / `implement` / `test` are the mixed-specific
+ * contract → ui → stitch chain.
+ */
+function _build_step_map(): Map<string, Step> {
+    return new Map<string, Step>([
+        ['refine', backend_refine.run],
+        ['memory', backend_memory.run],
+        ['analyze', backend_analyze.run],
+        ['plan', contract.run],
+        ['implement', ui.run],
+        ['test', stitch.run],
+        ['verify', backend_verify.run],
+        ['report', backend_report.run],
+    ]);
+}
+
+/**
+ * Return the `{step_name: handler}` mapping the dispatcher walks.
+ *
+ * Mirrors `work_engine.directives.backend.get_steps` and
+ * `work_engine.directives.ui.get_steps`.
+ */
+export function get_steps(): Map<string, Step> {
+    return _build_step_map();
+}
+
+/**
+ * Per-step ambiguity declarations.
+ *
+ * Each handler re-exports its own `AMBIGUITIES`. The mapping is rebuilt per
+ * call (cheap; documentation generators and the `test_ambiguity_coverage`
+ * suite invoke this once per run).
+ */
+export function all_ambiguities(): Record<string, ReadonlyArray<Record<string, string>>> {
+    return {
+        refine: backend_refine.AMBIGUITIES,
+        memory: backend_memory.AMBIGUITIES,
+        analyze: backend_analyze.AMBIGUITIES,
+        plan: contract.AMBIGUITIES,
+        implement: ui.AMBIGUITIES,
+        test: stitch.AMBIGUITIES,
+        verify: backend_verify.AMBIGUITIES,
+        report: backend_report.AMBIGUITIES,
+    };
+}
+
+export { contract, stitch, ui };