@event4u/agent-config 8.4.0 → 8.5.0

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

@@ -0,0 +1,189 @@
+/**
+ * `implement` step — gate + Option-A delegation for applying the plan.
+ *
+ * TypeScript twin of `work_engine/directives/backend/implement.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 step never edits files. Editing is delegated to the agent via
+ * `@agent-directive: apply-plan`; the agent runs the `minimal-safe-
+ * diff` and `scope-control` rules while it applies the plan, then
+ * writes the resulting file-level changes onto `state.changes` and
+ * marks `outcomes['implement'] = 'success'` before re-invoking the
+ * dispatcher.
+ *
+ * Flow:
+ *
+ * - `plan` outcome is not `success` → BLOCKED on precondition.
+ * - `state.changes` empty → BLOCKED with `@agent-directive:
+ *   apply-plan` so the agent applies the plan.
+ * - `state.changes` populated but malformed (entries missing
+ *   `path`, or non-dict entries) → BLOCKED with shape complaint.
+ * - Otherwise → SUCCESS.
+ *
+ * `changes` entries use the loose shape described in
+ * `docs/contracts/implement-ticket-flow.md#deliverystate-the-only-shared-object`
+ * — each entry is a dict with at least a `path`; optional
+ * `lines` / `purpose` 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';
+
+/** Declared ambiguity surfaces. Advisory personas skip this step entirely. */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'upstream_plan_failed',
+        trigger: '`plan` outcome is not `success`',
+        resolution: 're-run `/implement-ticket` from the start',
+    },
+    {
+        code: 'empty_changes_delegate',
+        trigger: '`state.changes` empty — plan not applied yet',
+        resolution: 'agent directive `apply-plan` → edit under `minimal-safe-diff` ' + '+ `scope-control`',
+    },
+    {
+        code: 'malformed_changes',
+        trigger: 'any change entry is not a dict or has no non-empty `path`',
+        resolution: 're-run `apply-plan` and resume',
+    },
+];
+
+/** Gate on `plan`, then either delegate or validate `state.changes`. */
+export function run(state: DeliveryState): StepResult {
+    const policy = resolve_policy(state.persona);
+    if (!policy.allows_implement) {
+        // Advisory personas produce a plan only; `state.changes` stays
+        // empty and the delivery report renders a "no file changes
+        // recorded" placeholder. See `persona_policy` for contract.
+        return new StepResult({
+            outcome: Outcome.SUCCESS,
+            message: `implement skipped: persona \`${policy.name}\` is plan-only.`,
+        });
+    }
+
+    if (state.outcomes.plan !== Outcome.SUCCESS) {
+        return _blocked_on_precondition(state);
+    }
+
+    if (!_pyTruthy(state.changes)) {
+        return _delegate_to_apply_plan(state);
+    }
+
+    const shapeIssues = _diagnose_changes(state.changes);
+    if (shapeIssues.length > 0) {
+        return _blocked_on_shape(state, shapeIssues);
+    }
+
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}
+
+/** Every entry must be a dict carrying at least a non-empty `path`. */
+function _diagnose_changes(changes: Any[]): string[] {
+    const issues: string[] = [];
+    changes.forEach((change, i) => {
+        const idx = i + 1;
+        if (!_isPlainObject(change)) {
+            issues.push(`change #${idx} is not a dict`);
+            return;
+        }
+        const d = change as Record<string, unknown>;
+        const path = _pyTruthy(d.path) ? d.path : d.file;
+        if (typeof path !== 'string' || _pyStrip(path).length === 0) {
+            issues.push(`change #${idx} has no path`);
+        }
+    });
+    return issues;
+}
+
+function _delegate_to_apply_plan(state: DeliveryState): StepResult {
+    const ticketId = _ticketId(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('apply-plan', { ticket: ticketId }),
+            `> Ticket ${ticketId} — applying the recorded plan under ` +
+                '`minimal-safe-diff` + `scope-control`.',
+            '> 1. Continue — apply the plan as recorded',
+            '> 2. Abort — stop before any edits are made',
+        ],
+        message: `Ticket ${ticketId} needs its plan applied before testing.`,
+    });
+}
+
+function _blocked_on_precondition(state: DeliveryState): StepResult {
+    const ticketId = _ticketId(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            `> Ticket ${ticketId} — implement gate refused: ` +
+                '`plan` step did not complete successfully.',
+            '> 1. Re-run `/implement-ticket` from the start',
+            '> 2. Abort',
+        ],
+        message: `Ticket ${ticketId} cannot implement: plan 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 changes are malformed: ` + issues.join('; ') + '.',
+            '> 1. Re-run `apply-plan` and resume',
+            '> 2. Abort — changes cannot be trusted',
+        ],
+        message: `Ticket ${ticketId} changes shape invalid: ${issues.join('; ')}.`,
+    });
+}
+
+/** `(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)';
+}
+
+/** 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;
+}
+
+/** Python `str.strip()` — strip leading/trailing whitespace. */
+function _pyStrip(s: string): string {
+    return s.trim();
+}
+
+/** 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)
+    );
+}

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

@@ -0,0 +1,94 @@
+/**
+ * Backend directive set — step handlers for the backend-coding flow.
+ *
+ * TypeScript twin of `work_engine/directives/backend/__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).
+ *
+ * Each module exposes a single `run` callable that matches the `Step`
+ * protocol defined in `../../delivery_state`. The dispatcher wires them into
+ * the `STEP_ORDER` mapping at call time.
+ *
+ * The deterministic gates (`refine`, `memory`, `analyze`) validate upstream
+ * state; the delegation gates (`plan`, `implement`, `test`, `verify`) halt
+ * with `@agent-directive:` markers so the orchestrator can invoke the matching
+ * skill and resume. `report` renders the delivery Markdown once everything
+ * else has succeeded.
+ */
+
+import type { Step } from '../../delivery_state.js';
+
+import * as analyze from './analyze.js';
+import * as implement from './implement.js';
+import * as memory from './memory.js';
+import * as plan from './plan.js';
+import * as refine from './refine.js';
+import * as report from './report.js';
+import * as test from './test.js';
+import * as verify from './verify.js';
+
+/** External name carried in `state.directive_set` for this set. */
+export const DIRECTIVE_SET_NAME = 'backend';
+
+/**
+ * Input kinds this directive set knows how to handle.
+ *
+ * Read by `work_engine.dispatcher.assert_kind_supported` before the loop
+ * starts. The schema's `work_engine.state.KNOWN_INPUT_KINDS` is the *envelope*
+ * whitelist (what is accepted on disk); `SUPPORTED_KINDS` is the *capability*
+ * whitelist (what this set can actually drive end to end).
+ */
+export const SUPPORTED_KINDS: ReadonlyArray<string> = ['ticket', 'prompt'];
+
+// Mirror the Python `_STEPS` tuple: (refine, memory, analyze, plan, implement,
+// test, verify, report). The leaf name is the dispatcher slot key; in Python
+// it is derived via `step.__name__.rsplit(".", 1)[-1]` — hardcoded here since
+// the modules are imported statically.
+const _STEPS: ReadonlyArray<[string, { run: Step; AMBIGUITIES: ReadonlyArray<Record<string, string>> }]> = [
+    ['refine', refine],
+    ['memory', memory],
+    ['analyze', analyze],
+    ['plan', plan],
+    ['implement', implement],
+    ['test', test],
+    ['verify', verify],
+    ['report', report],
+];
+
+/**
+ * Return `{step_name: AMBIGUITIES}` for every step in flow order.
+ *
+ * Used by documentation generators and the `test_ambiguity_coverage` suite to
+ * prove every step explicitly declares what can surface a `BLOCKED` outcome.
+ * Steps that always succeed (`memory`, `report`) return an empty tuple —
+ * declared intent, not an omission.
+ */
+export function all_ambiguities(): Record<string, ReadonlyArray<Record<string, string>>> {
+    const out: Record<string, ReadonlyArray<Record<string, string>>> = {};
+    for (const [name, step] of _STEPS) {
+        out[name] = step.AMBIGUITIES;
+    }
+    return out;
+}
+
+/**
+ * Return the `{step_name: handler}` mapping the dispatcher walks.
+ *
+ * Each value is the module-level `run` callable matching the
+ * `work_engine.delivery_state.Step` protocol — exactly what
+ * `work_engine.dispatcher.dispatch` calls. Order of insertion matches the
+ * canonical backend flow (refine → memory → analyze → plan → implement →
+ * test → verify → report).
+ */
+export function get_steps(): Map<string, Step> {
+    const out = new Map<string, Step>();
+    for (const [name, step] of _STEPS) {
+        out.set(name, step.run);
+    }
+    return out;
+}
+
+// Re-export the step modules as namespaces (Python `__all__` lists them as
+// importable members of the package).
+export { analyze, implement, memory, plan, refine, report, test, verify };

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

@@ -0,0 +1,193 @@
+/**
+ * `memory` step — bounded retrieval over the three allowed types.
+ *
+ * TypeScript twin of `work_engine/directives/backend/memory.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).
+ *
+ * Contract (see
+ * `docs/contracts/implement-ticket-flow.md#memory-retrieval-contract`):
+ *
+ * - Three allowed types: `domain-invariants`, `incident-learnings`,
+ *   `historical-patterns`. (Architectural rationale lives in ADRs —
+ *   `docs/decisions/` — not in curated memory.)
+ * - Hard cap of **12** hits total across the three types.
+ * - Keys derive from the ticket — title tokens plus acceptance-criterion
+ *   tokens plus any already-known `files` hint. Tokenisation is
+ *   deliberately naive (whitespace split, lower-cased) so the retrieval
+ *   shape stays reproducible in tests.
+ * - Step always returns `SUCCESS`. Zero hits is a valid outcome
+ *   ("nothing in memory touches this ticket") — the `report` step
+ *   drops the memory section when that happens rather than padding.
+ *
+ * The step stores each hit as a plain dict on `state.memory` so
+ * consumers outside Python (the delivery report, JSON log lines) can
+ * round-trip the structure without pickling dataclasses.
+ */
+
+import type { DeliveryState} from '../../delivery_state.js';
+import { type Any, Outcome, StepResult } from '../../delivery_state.js';
+import { retrieve as _real_retrieve } from '../../../memory_lookup.js';
+
+/** The three types allowed by the flow contract. No aliases, no extras. */
+export const MEMORY_TYPES: ReadonlyArray<string> = [
+    'domain-invariants',
+    'incident-learnings',
+    'historical-patterns',
+];
+
+/** Hard cap per the roadmap — never raise without amending the contract. */
+export const MAX_HITS = 12;
+
+/**
+ * Declared ambiguity surfaces — memory retrieval always succeeds.
+ *
+ * Declared empty so the aggregate registry in `steps/__init__.py`
+ * can round-trip every step's surfaces without a special case.
+ */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [];
+
+/** Signature of the `memory_lookup.retrieve` callable this step drives. */
+type RetrieveFn = (types: string[], keys: string[], limit: number) => unknown;
+
+/**
+ * Test seam mirroring Python's late `import memory_lookup` monkeypatch
+ * point. Default is the real `memory_lookup.retrieve`; tests swap it via
+ * `_setRetrieve` exactly as the Python suite patches `memory_lookup.retrieve`.
+ */
+let _retrieve_override: RetrieveFn | null = null;
+
+/** Swap the `retrieve` callable (test hook for the lazy-import seam). */
+export function _setRetrieve(fn: RetrieveFn | null): void {
+    _retrieve_override = fn;
+}
+
+const _WORD = /[A-Za-z][A-Za-z0-9_-]{2,}/g;
+const _STOPWORDS: ReadonlySet<string> = new Set([
+    'the', 'and', 'for', 'with', 'from', 'into', 'that', 'this',
+    'should', 'must', 'when', 'then', 'will', 'have', 'has',
+    'are', 'was', 'were', 'can', 'could', 'would', 'shall',
+    'also', 'which', 'where', 'while', 'make', 'made', 'use',
+    'used', 'using', 'user', 'users', 'test', 'tests',
+]);
+
+/** Populate `state.memory` with up to `MAX_HITS` hits. */
+export function run(state: DeliveryState): StepResult {
+    const retrieve = _resolve_retrieve();
+    const keys = _keys_from_ticket(state.ticket);
+    const hits = retrieve([...MEMORY_TYPES], keys, MAX_HITS);
+
+    // `retrieve` returns `Hit` dataclasses; coerce to dicts so the
+    // state is serialisation-ready for the report step and metrics log.
+    const hitList = Array.isArray(hits) ? hits : [];
+    state.memory = hitList.slice(0, MAX_HITS).map((h) => _as_dict(h));
+    return new StepResult({ outcome: Outcome.SUCCESS });
+}
+
+/**
+ * Resolve `memory_lookup.retrieve` lazily so tests can monkeypatch it.
+ *
+ * Importing at module load time would freeze the reference before
+ * tests can swap in a fake, which is the standard gotcha with the
+ * `from X import Y` form. Deferring the resolution keeps the step
+ * patchable from a single attribute (`memory_lookup.retrieve`).
+ */
+function _resolve_retrieve(): RetrieveFn {
+    return _retrieve_override ?? (_real_retrieve as RetrieveFn);
+}
+
+/**
+ * Derive retrieval keys from the ticket.
+ *
+ * Three sources, in priority order so callers reading the log can
+ * reconstruct why a hit scored: explicit `files` hints first,
+ * then title tokens, then acceptance-criterion tokens. Duplicates
+ * are removed while preserving first-seen order.
+ */
+function _keys_from_ticket(ticket: Record<string, Any>): string[] {
+    const keys: string[] = [];
+    _extend_unique(keys, _as_str_list((ticket || {}).files));
+    _extend_unique(keys, _tokenise((ticket || {}).title));
+    for (const ac of _as_str_list((ticket || {}).acceptance_criteria)) {
+        _extend_unique(keys, _tokenise(ac));
+    }
+    return keys;
+}
+
+/** Return lower-cased content words from `value` (empty when absent). */
+function _tokenise(value: Any): string[] {
+    if (typeof value !== 'string') {
+        return [];
+    }
+    const out: string[] = [];
+    for (const match of value.matchAll(_WORD)) {
+        const word = match[0].toLowerCase();
+        if (!_STOPWORDS.has(word)) {
+            out.push(word);
+        }
+    }
+    return out;
+}
+
+/** Coerce `value` to a list of non-empty strings. */
+function _as_str_list(value: Any): string[] {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item): item is string => typeof item === 'string' && item.trim().length !== 0);
+}
+
+/** Append items from `source` to `target` skipping duplicates. */
+function _extend_unique(target: string[], source: Iterable<string>): void {
+    const seen = new Set(target);
+    for (const item of source) {
+        if (seen.has(item)) {
+            continue;
+        }
+        target.push(item);
+        seen.add(item);
+    }
+}
+
+/** Coerce a `Hit` (or pre-dict test fake) into a plain dict. */
+function _as_dict(hit: Any): Record<string, Any> {
+    const asDict = (hit as { as_dict?: unknown })?.as_dict;
+    if (typeof asDict === 'function') {
+        return (asDict as () => Record<string, Any>).call(hit);
+    }
+    if (_isPlainObject(hit)) {
+        return { ...(hit as Record<string, Any>) };
+    }
+    // Fallback path — should not happen in production, but keeps the
+    // step from crashing if a fixture returns a raw namespace object.
+    return { entry: _pyRepr(hit) };
+}
+
+/** 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)
+    );
+}
+
+/** Minimal Python `repr()` for the fallback path's scalar inputs. */
+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);
+}