@event4u/agent-config 8.4.0 → 8.4.1

package/src/agent-src/templates/scripts/work_engine/cli_args.ts

@@ -0,0 +1,249 @@
+/**
+ * Argument parser and state-file constants for the CLI entry point.
+ *
+ * TypeScript twin of `work_engine/cli_args.py` (ADR-200 py2ts Phase 1 —
+ * work_engine foundation). Public API names stay snake_case to mirror the
+ * Python module 1:1 (per ADR-200 — Python style is part of the contract).
+ *
+ * Extracted from `cli.py` in P2.3 of `road-to-post-pr29-optimize.md`.
+ * Behaviour-preserving: the parser shape, default values, and exit-code
+ * semantics are identical to the pre-split version. The constants moved here
+ * so the parser default and the legacy-file detector both reference a single
+ * source of truth.
+ *
+ * The Python source returns an `argparse.ArgumentParser`; this twin exposes
+ * {@link parse_args} instead, mirroring argparse's runtime behaviour for the
+ * declared flags: long-option prefix abbreviation, `--flag=value` /
+ * `--flag value` forms, `store_true` flags, `-h`/`--help` exit-0, and exit-2
+ * on every error path (unknown flag, ambiguous abbreviation, missing value,
+ * explicit value on a store_true flag). `--help` prose is intentionally NOT
+ * a parity surface (ADR-200 — argparse help text is not byte-compared).
+ */
+
+// Paths are kept as plain strings here (the Python source wraps them in
+// `pathlib.Path` via `type=Path`; the consuming modules — state_io,
+// input_builders — land in a later py2ts phase and own the Path semantics).
+export const DEFAULT_STATE_FILE = '.work-state.json';
+/**
+ * State file used when `--state-file` is not passed.
+ *
+ * Renamed from `.implement-ticket-state.json` in 1.15.0 alongside the
+ * `implement_ticket → work_engine` package move. The legacy filename is
+ * still recognised on load (see {@link LEGACY_STATE_FILE} below) so that
+ * existing checkouts surface a clear migration message instead of a
+ * silent "no state file" error.
+ */
+
+export const LEGACY_STATE_FILE = '.implement-ticket-state.json';
+/**
+ * Pre-1.15.0 default state file. Detected only as a migration hint;
+ * never written to. See `docs/MIGRATION.md`.
+ */
+
+export const _FMT_V0 = 'v0';
+export const _FMT_V1 = 'v1';
+/**
+ * Wire-format markers carried alongside the loaded `WorkState`.
+ *
+ * Format-preserving roundtrip: `_load` records which shape it parsed,
+ * `_save` rewrites in that same shape. v0 in → v0 out (Goldens stay
+ * byte-equal); v1 in → v1 out (future flows produced by the migration
+ * tool or a fresh v1 init keep their envelope fields).
+ */
+
+/** Parsed namespace — mirrors the argparse `Namespace` attribute names. */
+export interface ParsedArgs {
+    state_file: string;
+    ticket_file: string | null;
+    prompt_file: string | null;
+    diff_file: string | null;
+    file_file: string | null;
+    persona: string | null;
+    no_hooks: boolean;
+    hooks_config: string | null;
+}
+
+/** Thrown internally to mirror argparse's exit-2 error path. */
+class ArgparseExit extends Error {
+    readonly code: number;
+    constructor(code: number) {
+        super(`argparse exit ${code}`);
+        Object.setPrototypeOf(this, ArgparseExit.prototype);
+        this.name = 'ArgparseExit';
+        this.code = code;
+    }
+}
+
+const PROG = 'implement-ticket';
+
+// Declared optionals, in declaration order (drives prefix-abbreviation
+// candidate ordering and the usage line, exactly as argparse builds it).
+interface OptionSpec {
+    flag: string; // canonical long option, e.g. "--state-file"
+    dest: keyof ParsedArgs; // namespace attribute
+    takesValue: boolean; // false for store_true
+}
+
+const OPTIONS: OptionSpec[] = [
+    { flag: '--state-file', dest: 'state_file', takesValue: true },
+    { flag: '--ticket-file', dest: 'ticket_file', takesValue: true },
+    { flag: '--prompt-file', dest: 'prompt_file', takesValue: true },
+    { flag: '--diff-file', dest: 'diff_file', takesValue: true },
+    { flag: '--file-file', dest: 'file_file', takesValue: true },
+    { flag: '--persona', dest: 'persona', takesValue: true },
+    { flag: '--no-hooks', dest: 'no_hooks', takesValue: false },
+    { flag: '--hooks-config', dest: 'hooks_config', takesValue: true },
+];
+
+// `-h` / `--help` is an implicit argparse optional; included as a prefix
+// abbreviation candidate so e.g. `--he` resolves to `--help`.
+const HELP_FLAGS = ['--help'];
+
+function usage(): string {
+    // Compact one-line usage marker; the exact wrapping/prose is not a parity
+    // surface (ADR-200 — argparse usage/help text is not byte-compared).
+    return `usage: ${PROG} [-h] [options]`;
+}
+
+function err(message: string): never {
+    process.stderr.write(`${usage()}\n`);
+    process.stderr.write(`${PROG}: error: ${message}\n`);
+    throw new ArgparseExit(2);
+}
+
+/**
+ * Resolve a long option token to its canonical flag, applying argparse's
+ * unambiguous-prefix-abbreviation rule. Returns the matched spec, the
+ * sentinel `'help'`, or throws exit-2 on an ambiguous / unknown option.
+ */
+function resolveLong(name: string): OptionSpec | 'help' {
+    // Exact match first (argparse short-circuits exact hits before abbrev).
+    const exact = OPTIONS.find((o) => o.flag === name);
+    if (exact) {
+        return exact;
+    }
+    if (HELP_FLAGS.includes(name)) {
+        return 'help';
+    }
+    // Prefix abbreviation across both the declared options and --help.
+    const candidates: Array<OptionSpec | 'help'> = [];
+    for (const o of OPTIONS) {
+        if (o.flag.startsWith(name)) {
+            candidates.push(o);
+        }
+    }
+    for (const h of HELP_FLAGS) {
+        if (h.startsWith(name)) {
+            candidates.push('help');
+        }
+    }
+    if (candidates.length === 1) {
+        return candidates[0] as OptionSpec | 'help';
+    }
+    if (candidates.length === 0) {
+        // argparse reports unknown options via "unrecognized arguments".
+        err(`unrecognized arguments: ${name}`);
+    }
+    const names = candidates.map((c) => (c === 'help' ? '--help' : c.flag)).join(', ');
+    err(`ambiguous option: ${name} could match ${names}`);
+}
+
+/**
+ * Parse `argv` (the slice after the program name) into a namespace.
+ *
+ * Mirrors `argparse.ArgumentParser.parse_args`: on `-h`/`--help` it prints
+ * a help marker to stdout and exits 0; on any error it prints to stderr and
+ * exits 2 (via `process.exitCode`, never `process.exit`, per ADR-200).
+ * Returns the parsed namespace on success.
+ */
+export function parse_args(argv: string[]): ParsedArgs {
+    const ns: ParsedArgs = {
+        state_file: DEFAULT_STATE_FILE,
+        ticket_file: null,
+        prompt_file: null,
+        diff_file: null,
+        file_file: null,
+        persona: null,
+        no_hooks: false,
+        hooks_config: null,
+    };
+    const extras: string[] = [];
+
+    try {
+        let i = 0;
+        while (i < argv.length) {
+            const tok = argv[i] as string;
+            if (tok === '-h' || tok === '--help') {
+                process.stdout.write(`${usage()}\n`);
+                throw new ArgparseExit(0);
+            }
+            if (tok.startsWith('--')) {
+                let name = tok;
+                let inlineValue: string | null = null;
+                const eq = tok.indexOf('=');
+                if (eq !== -1) {
+                    name = tok.slice(0, eq);
+                    inlineValue = tok.slice(eq + 1);
+                }
+                if (name === '-h' || name === '--help') {
+                    process.stdout.write(`${usage()}\n`);
+                    throw new ArgparseExit(0);
+                }
+                const resolved = resolveLong(name);
+                if (resolved === 'help') {
+                    process.stdout.write(`${usage()}\n`);
+                    throw new ArgparseExit(0);
+                }
+                if (resolved.takesValue) {
+                    if (inlineValue !== null) {
+                        assignValue(ns, resolved, inlineValue);
+                    } else {
+                        const next = argv[i + 1];
+                        // argparse: a value beginning with `-` is still consumed
+                        // only when it does not look like a known option; the
+                        // simpler "expected one argument" path covers the
+                        // missing-trailing-value case the contract exercises.
+                        if (next === undefined) {
+                            err(`argument ${resolved.flag}: expected one argument`);
+                        }
+                        assignValue(ns, resolved, next);
+                        i += 1;
+                    }
+                } else {
+                    // store_true: an explicit `=value` is an error in argparse.
+                    if (inlineValue !== null) {
+                        err(`argument ${resolved.flag}: ignored explicit argument '${inlineValue}'`);
+                    }
+                    (ns[resolved.dest] as boolean) = true;
+                }
+            } else if (tok.startsWith('-') && tok !== '-') {
+                // Single-dash unknown short option → unrecognized.
+                extras.push(tok);
+            } else {
+                // Positional — this parser declares none, so it is an extra.
+                extras.push(tok);
+            }
+            i += 1;
+        }
+        if (extras.length > 0) {
+            err(`unrecognized arguments: ${extras.join(' ')}`);
+        }
+    } catch (e) {
+        if (e instanceof ArgparseExit) {
+            process.exitCode = e.code;
+            // Surface as a thrown sentinel so a CLI caller can stop; the test
+            // harness inspects process.exitCode (mirrors argparse SystemExit).
+            throw e;
+        }
+        throw e;
+    }
+    return ns;
+}
+
+function assignValue(ns: ParsedArgs, spec: OptionSpec, value: string): void {
+    // All value-taking flags here are string/Path; store the raw string.
+    (ns[spec.dest] as string) = value;
+}
+
+/** Re-exported sentinel so a CLI entry point can recognise the exit path. */
+export { ArgparseExit };

package/src/agent-src/templates/scripts/work_engine/delivery_state.ts

@@ -0,0 +1,225 @@
+/**
+ * `DeliveryState` — the only object shared between orchestrator steps.
+ *
+ * TypeScript twin of `work_engine/delivery_state.py` (ADR-200 py2ts Phase 1 —
+ * work_engine foundation). Public API names stay snake_case to mirror the
+ * Python module 1:1 (per ADR-200 — Python style is part of the contract).
+ *
+ * The shape mirrors `docs/contracts/implement-ticket-flow.md`. No step
+ * may invent fields not declared here; extensions require a roadmap
+ * amendment plus a flow-contract update.
+ *
+ * Steps return a `StepResult` with one of three `Outcome` values:
+ *
+ * - `SUCCESS`  — step populated its slice of `DeliveryState` and the
+ *   dispatcher continues to the next step.
+ * - `BLOCKED`  — step hit an ambiguity it cannot resolve on its own.
+ *   `questions` carries pre-formatted numbered options per the
+ *   `user-interaction` rule. The dispatcher halts.
+ * - `PARTIAL`  — step populated its slice *and* produced open
+ *   questions. The dispatcher halts with the same surface as BLOCKED;
+ *   the calling orchestrator (Phase 3) decides whether to prompt the
+ *   user to continue or stop.
+ *
+ * `DeliveryState` is a plain dataclass rather than a typed dict so
+ * step handlers can rely on attribute access, defaults, and mutation
+ * semantics without resorting to dictionary indirection.
+ */
+
+/** Arbitrary JSON-ish value, mirroring the Python `Any` fields. */
+export type Any = unknown;
+
+/**
+ * Terminal outcome of a single step.
+ *
+ * The Python source subclasses `str` + `Enum`, so each member serialises as
+ * its string form. We mirror that with a string-valued const object: the
+ * values are exactly the strings the Python enum members carry.
+ */
+export const Outcome = {
+    SUCCESS: 'success',
+    BLOCKED: 'blocked',
+    PARTIAL: 'partial',
+} as const;
+
+export type Outcome = (typeof Outcome)[keyof typeof Outcome];
+
+/**
+ * Return value of a single `Step` invocation.
+ *
+ * `questions` is only populated for `BLOCKED` / `PARTIAL` outcomes. Each
+ * entry is a fully-formatted numbered line so the dispatcher can surface
+ * them verbatim without reformatting.
+ *
+ * Field order (outcome, questions, message) mirrors the Python dataclass so
+ * an `asdict`-style projection stays key-order identical.
+ */
+export class StepResult {
+    outcome: Outcome;
+    questions: string[];
+    message: string;
+
+    constructor(args: { outcome: Outcome; questions?: string[]; message?: string }) {
+        this.outcome = args.outcome;
+        // `field(default_factory=list)` → every instance owns its own array.
+        this.questions = args.questions ?? [];
+        this.message = args.message ?? '';
+    }
+}
+
+/**
+ * Canonical state passed between orchestrator steps.
+ *
+ * Field order matches the table in `docs/contracts/implement-ticket-flow.md`.
+ * Mutable defaults are created per-instance (the Python
+ * `field(default_factory=...)` contract) so every instance owns its own
+ * containers — a single shared array across runs would be a cross-run
+ * contamination hazard for the metrics pipeline.
+ */
+export class DeliveryState {
+    ticket: Record<string, Any>;
+    persona: string;
+    memory: Array<Record<string, Any>>;
+    plan: Any;
+    changes: Array<Record<string, Any>>;
+    tests: Any;
+    verify: Any;
+    outcomes: Record<string, string>;
+    questions: string[];
+    report: string;
+    ui_audit: Record<string, Any> | null;
+    app_spec: Record<string, Any> | null;
+    ui_design: Record<string, Any> | null;
+    ui_scaffold: Record<string, Any> | null;
+    ui_review: Record<string, Any> | null;
+    ui_polish: Record<string, Any> | null;
+    contract: Record<string, Any> | null;
+    stitch: Record<string, Any> | null;
+    stack: Record<string, Any> | null;
+
+    constructor(args: {
+        ticket: Record<string, Any>;
+        persona?: string;
+        memory?: Array<Record<string, Any>>;
+        plan?: Any;
+        changes?: Array<Record<string, Any>>;
+        tests?: Any;
+        verify?: Any;
+        outcomes?: Record<string, string>;
+        questions?: string[];
+        report?: string;
+        ui_audit?: Record<string, Any> | null;
+        app_spec?: Record<string, Any> | null;
+        ui_design?: Record<string, Any> | null;
+        ui_scaffold?: Record<string, Any> | null;
+        ui_review?: Record<string, Any> | null;
+        ui_polish?: Record<string, Any> | null;
+        contract?: Record<string, Any> | null;
+        stitch?: Record<string, Any> | null;
+        stack?: Record<string, Any> | null;
+    }) {
+        this.ticket = args.ticket;
+        this.persona = args.persona ?? 'senior-engineer';
+        this.memory = args.memory ?? [];
+        this.plan = args.plan ?? null;
+        this.changes = args.changes ?? [];
+        this.tests = args.tests ?? null;
+        this.verify = args.verify ?? null;
+        this.outcomes = args.outcomes ?? {};
+        this.questions = args.questions ?? [];
+        this.report = args.report ?? '';
+        this.ui_audit = args.ui_audit ?? null;
+        this.app_spec = args.app_spec ?? null;
+        this.ui_design = args.ui_design ?? null;
+        this.ui_scaffold = args.ui_scaffold ?? null;
+        this.ui_review = args.ui_review ?? null;
+        this.ui_polish = args.ui_polish ?? null;
+        this.contract = args.contract ?? null;
+        this.stitch = args.stitch ?? null;
+        this.stack = args.stack ?? null;
+    }
+}
+
+/**
+ * Protocol every step handler must satisfy.
+ *
+ * A step reads and writes `DeliveryState` in place; its return value
+ * carries only the terminal `Outcome` and any surfaced questions.
+ */
+export type Step = (state: DeliveryState) => StepResult;
+
+/**
+ * Marker that flags a `questions[0]` entry as agent-addressed, not
+ * user-addressed.
+ *
+ * When a step cannot run deterministically from pure Python (edits,
+ * subprocess calls, anything that needs tools the dispatcher doesn't
+ * own), it returns `BLOCKED` with this prefix as the first entry of
+ * `questions`. The orchestrator reads it and drives the matching
+ * skill; the user-facing numbered options follow on subsequent lines.
+ *
+ * The prefix is public contract: changing it breaks every agent that
+ * has learned to recognise it. See
+ * `docs/contracts/implement-ticket-flow.md#agent-directives`.
+ */
+export const AGENT_DIRECTIVE_PREFIX = '@agent-directive:';
+
+/**
+ * Python `str(value)` for the scalar value kinds an agent-directive payload
+ * carries. The Python source coerces every payload value with `str(...)`, so
+ * `True` → `"True"`, `False` → `"False"`, `None` → `"None"`; numbers and
+ * strings render as-is.
+ */
+function pyStr(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'None';
+    }
+    if (value === true) {
+        return 'True';
+    }
+    if (value === false) {
+        return 'False';
+    }
+    return String(value);
+}
+
+/**
+ * Format a canonical `@agent-directive:` line.
+ *
+ * `name` is the directive verb the agent dispatches on (for example
+ * `"implement-plan"` or `"run-tests"`). `payload` entries are rendered as
+ * `key=value` pairs on the same line, so the whole directive stays a single
+ * greppable string. Values are coerced with Python `str()` semantics — richer
+ * payloads belong on the `DeliveryState` itself, not in the directive line.
+ *
+ * Insertion order of `payload` keys is preserved, matching Python's `**kwargs`
+ * ordering.
+ */
+export function agent_directive(name: string, payload: Record<string, unknown> = {}): string {
+    const suffix = Object.entries(payload)
+        .map(([key, value]) => `${key}=${pyStr(value)}`)
+        .join(' ');
+    return suffix
+        ? `${AGENT_DIRECTIVE_PREFIX} ${name} ${suffix}`.trim()
+        : `${AGENT_DIRECTIVE_PREFIX} ${name}`;
+}
+
+/**
+ * True when `question` is an agent-addressed directive line.
+ *
+ * Used by the orchestrator to split `state.questions` into the
+ * agent-facing directive (at most one, always at index 0) and the
+ * user-facing numbered options (everything else).
+ */
+export function is_agent_directive(question: unknown): boolean {
+    return typeof question === 'string' && pyLstrip(question).startsWith(AGENT_DIRECTIVE_PREFIX);
+}
+
+/**
+ * Python `str.lstrip()` with no argument — strips leading whitespace as
+ * Python defines it (the `str.isspace` set). JS `String.prototype.trimStart`
+ * covers the same Unicode whitespace set for the inputs this module sees.
+ */
+function pyLstrip(s: string): string {
+    return s.trimStart();
+}

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

@@ -0,0 +1,125 @@
+/**
+ * `analyze` step — deterministic precondition gate.
+ *
+ * TypeScript twin of `work_engine/directives/backend/analyze.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 runs no analysis of its own: the real impact analysis is
+ * owned by the agent between the `memory` and `plan` steps. The
+ * gate's job is to confirm the upstream slices are populated enough
+ * for planning to be meaningful.
+ *
+ * Checks, in order:
+ *
+ * 1. `refine` outcome must be `success` — the ticket is refined.
+ * 2. `memory` outcome must be `success` — priors were queried
+ *    (an empty result set is still a successful query, per the
+ *    `memory` step's own contract).
+ * 3. The ticket must still carry acceptance criteria — guards against
+ *    a resuming caller overwriting `state.ticket` between runs.
+ *
+ * On any missing precondition the step returns `BLOCKED` with the
+ * reason spelled out and numbered options per the `user-interaction`
+ * rule. Otherwise it returns `SUCCESS` without mutating state.
+ */
+
+import type { DeliveryState} from '../../delivery_state.js';
+import { Outcome, StepResult } from '../../delivery_state.js';
+
+/** Declared ambiguity surfaces. Every BLOCKED return maps to one code. */
+export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
+    {
+        code: 'upstream_refine_failed',
+        trigger: '`refine` outcome is not `success`',
+        resolution: 're-run `/implement-ticket` from the start',
+    },
+    {
+        code: 'upstream_memory_failed',
+        trigger: '`memory` outcome is not `success`',
+        resolution: 're-run `/implement-ticket` from the start',
+    },
+    {
+        code: 'lost_ac',
+        trigger: 'ticket lost its `acceptance_criteria` between runs',
+        resolution: 'restart with the full ticket payload',
+    },
+];
+
+/** Return SUCCESS when upstream is coherent, BLOCKED otherwise. */
+export function run(state: DeliveryState): StepResult {
+    const missing = _diagnose(state);
+    if (missing.length === 0) {
+        return new StepResult({ outcome: Outcome.SUCCESS });
+    }
+
+    const ticketId = _pyTruthy((state.ticket ?? {}).id) ? String((state.ticket ?? {}).id) : '(no id)';
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: _format_questions(ticketId, missing),
+        message: `Ticket ${ticketId} cannot enter the plan step: ` + missing.join('; '),
+    });
+}
+
+/** List the precondition failures in the order a reader needs them. */
+function _diagnose(state: DeliveryState): string[] {
+    const issues: string[] = [];
+
+    if (state.outcomes.refine !== Outcome.SUCCESS) {
+        issues.push('refine step did not complete successfully');
+    }
+
+    if (state.outcomes.memory !== Outcome.SUCCESS) {
+        issues.push('memory step did not complete successfully');
+    }
+
+    const ac = (state.ticket ?? {}).acceptance_criteria;
+    if (!Array.isArray(ac) || ac.length === 0) {
+        issues.push('ticket lost its acceptance criteria');
+    }
+
+    return issues;
+}
+
+/**
+ * Render the numbered options shown to the user when BLOCKED.
+ *
+ * Two options: retry from the first failing step, or abort. The
+ * headnote names the ticket and every failure so the user can
+ * decide without re-reading the earlier output.
+ */
+function _format_questions(ticketId: string, missing: string[]): string[] {
+    const headnote = `> Ticket ${ticketId} — analyze gate failed: ` + missing.join('; ') + '.';
+    return [
+        headnote,
+        '> 1. Re-run `/implement-ticket` from the start — rebuild upstream state',
+        '> 2. Abort — the flow cannot continue',
+    ];
+}
+
+/** 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;
+}