@yagni-app/code-staging 0.0.0 → 0.1.0-staging.998.1

package/dist/extension/pipeline/types.d.ts

@@ -0,0 +1,436 @@
+/**
+ * Single source of truth for the /go pipeline's data shapes + tuning constants.
+ *
+ * Pure types and constants only — no logic. Every other pipeline module imports
+ * from here so the orchestrator's correctness lives in typed data rather than in
+ * scattered string literals. The stage list is a declarative contract (spec
+ * §7.2) so future complexity-lanes select a subset, never a rewrite.
+ */
+import type { RunUsage } from "./budget.js";
+/**
+ * Opaque per-stage model tier. These map to models server-side under the `yagni`
+ * provider — never a model id in the pipeline config. The pipeline uses `peak`
+ * for judgment (plan/review), `standard` for execution (map/implement/fix), and
+ * `efficient` for the format-recovery re-ask; `advanced` is not wired into a
+ * stage but is the Balanced session's driver tier, so it stays valid here.
+ *
+ * `balanced` is deliberately NOT a member: it is a session strategy the picker
+ * offers, not something a pipeline stage can request. A stage names the tier it
+ * actually runs on.
+ */
+export type ModelTier = "peak" | "advanced" | "standard" | "efficient";
+/** The fixed v1 pipeline stages, in order. */
+export type StageId = "map" | "plan" | "implement" | "review" | "fix";
+/**
+ * The stage vocabulary of the live feed + progress signals: the LLM pipeline
+ * stages plus the deterministic post-loop FINISH stage (spec §3c — commit /
+ * push / PR). FINISH is deliberately NOT a {@link StageId}: it is never run
+ * through the stage runner or `selectStages` — the /go handler drives it
+ * directly after a `clean` stop — but the feed still paints it as a stage row.
+ */
+export type FeedStageId = StageId | "finish";
+/** The three adversarial review angles (spec §3). */
+export type ReviewLens = "correctness" | "business_fit" | "does_it_hold";
+/** Finding severities; only `critical` + `high` block the review→fix loop. */
+export type Severity = "critical" | "high" | "medium" | "low";
+/**
+ * One declarative stage. `model` + `tools` are the tuning surface; `taskTemplate`
+ * carries `{ticket}` / `{previous}` placeholders the invocation builder fills.
+ */
+export interface PipelineStage {
+    id: StageId;
+    agent: string;
+    model: ModelTier;
+    tools: string[];
+    taskTemplate: string;
+    /** Only set when the stage is fanned out per review lens. */
+    lens?: ReviewLens;
+}
+/** A single structured review finding parsed from a reviewer's output. */
+export interface Finding {
+    severity: Severity;
+    lens: ReviewLens;
+    message: string;
+    file?: string;
+    line?: number;
+}
+/** Token/cost accounting aggregated across a stage's assistant turns. */
+export interface StageUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    turns: number;
+}
+/** The outcome of running one grounded child stage. */
+export interface StageResult {
+    stageId: StageId;
+    agent: string;
+    exitCode: number;
+    finalOutput: string;
+    usage: StageUsage;
+    stopReason?: string;
+    errorMessage?: string;
+    stderr: string;
+    /**
+     * Tool-call health for this stage (R3-a). `toolCalls` is how many tools the
+     * child actually executed (`tool_execution_end` events); `toolErrors` is how
+     * many of those returned an error. The orchestrator folds the ratio into the
+     * write-stage health check so an implement / fix stage that exits 0 with a
+     * clean-looking summary while most of its edits failed is caught rather than
+     * trusted. Both default to 0 (no tools observed), which is below
+     * MIN_TOOL_CALLS_FOR_HEALTH and so never trips the guard.
+     */
+    toolCalls: number;
+    toolErrors: number;
+    /**
+     * How many stdout lines this stage discarded for exceeding the max line size
+     * (`RunStageDeps.maxLineBytes`). A pathologically long single NDJSON line (a
+     * runaway assistant turn or an enormous tool payload) is dropped rather than
+     * accumulated — the reader stays O(n) and bounded instead of OOM-crashing the
+     * whole pipeline. Absent/undefined when nothing was dropped (the normal case).
+     */
+    overlongLinesDropped?: number;
+}
+/** One round of the bounded review→fix loop. */
+export interface ReviewRound {
+    round: number;
+    lensResults: StageResult[];
+    findings: Finding[];
+    /**
+     * Review lenses that could not fully carry this round, surfaced in the /go
+     * handoff so a narrowed review is never silent. Two flavors (hence string,
+     * not ReviewLens — spec §3e): a bare lens name means its child FAILED and was
+     * skipped (R2 partial-failure tolerance; a failed REQUIRED lens fails the
+     * round instead); `<lens> (unparseable)` means the child was healthy but its
+     * non-empty output never yielded a findings block, even after the one §3e
+     * re-ask, so the round proceeded treating it as zero findings. Absent when
+     * every lens was healthy and parseable.
+     */
+    degradedLenses?: string[];
+}
+/**
+ * Why the pipeline ended. `clean` / `round_cap` are the two healthy review
+ * outcomes; `aborted` (a user/signal cancel) and `failed` (a crashed review or
+ * fix child) are surfaced honestly rather than mis-reported as `clean` (spec
+ * §7.3 — no silent truncation). `no_changes` is the same honesty applied one
+ * stage earlier: the build half produced no diff, so there was nothing to
+ * review — reporting that as `clean` would be a false "reviewed and clean".
+ * `partial` is the same honesty applied to a WRITE stage (implement/fix) that
+ * fails AFTER it has begun editing (a timeout or transient blip the R1 wrapper
+ * cannot retry without risking a double-apply): the diff it produced is real and
+ * sits in the working tree, so the run is reported as a preserved partial rather
+ * than a bare `failed` that discards the work.
+ */
+export type StopReason = "clean" | "round_cap" | "aborted" | "failed" | "no_changes" | "budget_exceeded" | "partial";
+/**
+ * A point-in-time signature of the repo working tree, used to detect whether the
+ * build half actually produced a change. `tracked` is false when the cwd is not
+ * a git work tree (or git is unavailable) — the no-op guard fails OPEN in that
+ * case (assumes a change) rather than mis-firing `no_changes`. `head` is the
+ * current commit (so a stage that COMMITS its work still counts as a change) and
+ * `status` is the porcelain working-tree state (so an uncommitted edit counts).
+ */
+export interface WorkspaceSnapshot {
+    tracked: boolean;
+    head: string;
+    status: string;
+}
+/**
+ * What the FINISH stage (spec §3c) actually landed: the commit on the run
+ * branch (and the optional pushed PR). Present ONLY when a commit really
+ * happened — a FINISH that skipped or failed leaves this absent and carries an
+ * honest note instead (§0.1: never fake a commit that didn't happen).
+ */
+export interface FinishInfo {
+    branch?: string;
+    commitSha: string;
+    prUrl?: string;
+    prNumber?: number;
+}
+/** The full pipeline outcome handed back to the /go command. */
+export interface PipelineResult {
+    stages: StageResult[];
+    rounds: ReviewRound[];
+    stopReason: StopReason;
+    findings: Finding[];
+    /**
+     * P4 honest note when the deterministic verify gate did NOT produce a verdict
+     * (no command detected, unrunnable, or timed out, so the loop fell open to the
+     * LLM-only review). Absent when verify ran and gave a clean/blocking verdict, so
+     * a /go that silently skipped the build check is never reported as fully gated.
+     */
+    verifyNote?: string;
+    /**
+     * The FINAL round's verify command label(s) when the gate actually RAN (e.g.
+     * "typecheck" or "typecheck, lint"). Feeds the commit trailer's
+     * `YAGNI-Verify: passed (<cmds>)` honestly; absent whenever the final verify
+     * was skipped (see {@link PipelineResult.verifyNote}).
+     */
+    verifyCommand?: string;
+    /**
+     * How many `record_decision` tool calls completed WITHOUT error during this
+     * run, counted off the NDJSON `tool_execution_end` tap (spec §3c). COUNT only:
+     * decision ids are not observable without widening {@link JsonEvent}. Feeds
+     * the commit trailer's `YAGNI-Decisions` line.
+     */
+    decisionsRecorded?: number;
+    /**
+     * FINISH-stage outcome, attached by the /go handler after a `clean` stop (the
+     * orchestrator never sets it — commit/push live outside the LLM pipeline).
+     */
+    finish?: FinishInfo;
+}
+/**
+ * The append-only resilience journal (spec: 2026-06-29-yagni-code-go-resilience).
+ * One record per completed pipeline boundary, written through the fail-soft
+ * {@link CheckpointStore} seam so a /go interrupted mid-run can be resumed (or
+ * honestly reported) by a LATER session instead of rediscovering everything.
+ *
+ *  - `run_start`  : opened the run; `snapshot` = the pre-build baseline.
+ *  - `build_done` : map→plan→implement all finished; `snapshot` = post-build tree,
+ *                   `reviewInput` = implement output (the round-1 review handoff).
+ *  - `round_done` : a full review→fix round completed AND the loop will continue;
+ *                   `round` = that round, `reviewInput` = fix output (next round's
+ *                   handoff), `findings` = that round's union, `snapshot` = post-fix.
+ *  - `finish_done`: the FINISH stage (spec §3c) completed after a clean stop;
+ *                   carries `commitSha`/`prUrl` when a commit/PR actually landed.
+ *                   Purely informational for later sessions — planResume ignores it.
+ *  - `run_finish` : the run reached a terminal stopReason — makes the key NOT
+ *                   resumable (a completed run, even `round_cap`, is not "interrupted").
+ */
+export type CheckpointKind = "run_start" | "build_done" | "round_done" | "finish_done" | "run_finish";
+/** One append-only journal record. Latest-applicable record wins on resume. */
+export interface CheckpointRecord {
+    v: 1;
+    kind: CheckpointKind;
+    /** Identifies a resumable run: sanitized ticket + cwd + repo + branch. */
+    sessionKey: string;
+    ts: number;
+    ticket: string;
+    /** Backend run handle, present once the run was tracked (for session.bind on resume). */
+    runId?: string;
+    workItemId?: string;
+    repo?: string;
+    branch?: string;
+    /**
+     * The git working-tree signature at this boundary (the resume consistency key).
+     * Always set on run_start/build_done/round_done; omitted on run_finish (which is
+     * a terminal marker — planResume reads it before ever inspecting a snapshot).
+     */
+    snapshot?: WorkspaceSnapshot;
+    /** build_done: implement output. round_done: fix output. (The next review handoff.) */
+    reviewInput?: string;
+    /** round_done: the round that just fully completed (review + fix). */
+    round?: number;
+    /** round_done: the findings union for that round (for an honest final count). */
+    findings?: Finding[];
+    /** run_finish: the terminal stop reason. */
+    stopReason?: StopReason;
+    /** finish_done: the FINISH commit that landed (absent when the commit was skipped). */
+    commitSha?: string;
+    /** finish_done: the PR opened by --pr (absent when none was). */
+    prUrl?: string;
+    /** Cumulative run usage through this completed boundary. */
+    usage?: RunUsage;
+}
+/**
+ * The injectable, fail-soft journal seam (mirrors the optional `onStage` seam).
+ * Every method swallows its own errors — a checkpoint failure must NEVER break
+ * /go. `load` returns `[]` on any error (absent/corrupt file → fresh run).
+ */
+export interface CheckpointStore {
+    /** Append one record. Never throws. */
+    record(rec: CheckpointRecord): void;
+    /** All records for this run's key, in write order. Never throws (→ []). */
+    load(): CheckpointRecord[];
+    /** Best-effort close/delete for this key (called on every terminal outcome). */
+    clear(): void;
+}
+/**
+ * The PURE resume decision (the analogue of {@link shouldStop}). Folds the
+ * journal + a live workspace snapshot into one verdict:
+ *  - `fresh`        : nothing to resume (no journal, completed run, or unknowable tree).
+ *  - `resume_loop`  : the build half completed and the live tree still matches the
+ *                     checkpoint — re-enter the review→fix loop at `round`.
+ *  - `warn_partial` : the run was interrupted mid-build, or the tree diverged —
+ *                     auto-replay would risk double-applying edits, so warn + run fresh.
+ */
+export type ResumePlan = {
+    mode: "fresh";
+} | {
+    mode: "warn_partial";
+    reason: "build_interrupted" | "tree_diverged";
+    ticket: string;
+} | {
+    mode: "resume_loop";
+    /** The round to (re)enter the while-loop at (continues counting toward the cap). */
+    round: number;
+    /** The diff handoff text for that round (post-cap, byte-identical to the live run). */
+    reviewInput: string;
+    /** Prior rounds reconstructed from the journal (round# + findings) for an honest result. */
+    priorRounds: ReviewRound[];
+    /** Cumulative usage reconstructed from the last completed checkpoint. */
+    priorUsage?: RunUsage;
+    runId?: string;
+    workItemId?: string;
+    ticket: string;
+};
+/** Usage block as it appears on a pi `message_end` assistant message. */
+export interface JsonEventUsage {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    cost?: {
+        total?: number;
+    };
+    totalTokens?: number;
+}
+/** A content part of a pi message (text or tool call). */
+export interface JsonEventMessagePart {
+    type: string;
+    text?: string;
+    name?: string;
+    arguments?: Record<string, unknown>;
+}
+/** A pi message carried on a `message_end` event. */
+export interface JsonEventMessage {
+    role: string;
+    content: JsonEventMessagePart[];
+    usage?: JsonEventUsage;
+    model?: string;
+    stopReason?: string;
+    errorMessage?: string;
+}
+/**
+ * Minimal structural shape of an event off the `--mode json` NDJSON stream.
+ * Covers `message_end` (assistant text + usage), `tool_execution_end` (the real
+ * tool-result event; the example's `tool_result_end` is dead/never-emitted),
+ * `agent_end`, and the leading session header line. The runner only line-buffers
+ * + `JSON.parse`s; the events reducers narrow on `type`.
+ */
+export interface JsonEvent {
+    type: string;
+    message?: JsonEventMessage;
+    toolName?: string;
+    isError?: boolean;
+    /** Correlates a `tool_execution_start` with its `tool_execution_end`. */
+    toolCallId?: string;
+    /** Tool arguments carried on a `tool_execution_start` (label-only; never executed). */
+    args?: Record<string, unknown>;
+}
+/**
+ * One line surfaced into the live `/go` activity feed (spec §2). Produced PURELY
+ * by `activity.ts#eventToLine` from a single NDJSON event; the stateful
+ * `ActivityFeed` then folds these into the rendered panel.
+ */
+export interface ActivityLine {
+    kind: "narration" | "action";
+    /** For actions: stable id to resolve a running start against its done/error end. */
+    toolCallId?: string;
+    /** Display text, already trimmed/labelled (empty for a resolving end event). */
+    text: string;
+    /** Action lifecycle; narration is always "done". */
+    state: "running" | "done" | "error";
+}
+/** Which stage (and review lens / round) a tapped event belongs to (spec §5). */
+export interface StageTag {
+    stageId: StageId;
+    lens?: ReviewLens;
+    round?: number;
+}
+/**
+ * Structured progress signal (replaces the bare `onProgress(string)`); the feed
+ * folds these into stage glyph transitions, the round/findings header, and the
+ * final outcome (spec §2 + §5). Stage transitions speak {@link FeedStageId} so
+ * the /go handler can drive the post-loop FINISH row through the same channel
+ * (the orchestrator itself only ever emits real {@link StageId}s).
+ */
+export type PipelineProgress = {
+    kind: "stage_start";
+    stageId: FeedStageId;
+    lens?: ReviewLens;
+    round?: number;
+} | {
+    kind: "stage_done";
+    stageId: FeedStageId;
+    lens?: ReviewLens;
+    round?: number;
+    /**
+     * Per-lens finding counts. Attached only on the SECOND `stage_done` a lens
+     * receives: the first fires when its child process returns, the second when
+     * the round's parse loop resolves its output. A count is never reported
+     * before it exists.
+     */
+    findings?: number;
+    blocking?: number;
+    /**
+     * Why this lens could not fully carry the round (spec §3e): `failed` = the
+     * child failed and was skipped; `unparseable` = healthy but its output never
+     * yielded a findings block, even after the one re-ask.
+     */
+    degraded?: "failed" | "unparseable";
+} | {
+    kind: "findings";
+    round: number;
+    total: number;
+    blocking: number;
+} | {
+    kind: "done";
+    stopReason: StopReason;
+};
+/** Stop the review→fix loop after at most this many rounds (spec §7.3). */
+export declare const MAX_REVIEW_ROUNDS = 3;
+/**
+ * R1 in-loop resilience policy: the tuning surface for {@link withResilience},
+ * the HOF that wraps every per-stage child spawn with idle + wall-clock timeouts
+ * and bounded, transient-only retry. Pure data so a lane (or a dev composing the
+ * `runStage` seam) can swap the policy without touching the wrapper logic.
+ */
+export interface ResiliencePolicy {
+    /** Abort a stage that emits no NDJSON event for this many ms (a stalled child). */
+    idleTimeoutMs: number;
+    /** Abort a stage whose total wall-clock run exceeds this many ms. */
+    wallTimeoutMs: number;
+    /** Total attempts INCLUDING the first (so 1 = no retry). */
+    maxAttempts: number;
+    /** Exponential backoff base: delay = backoffBaseMs * 2^(attempt-1), capped. */
+    backoffBaseMs: number;
+    /** Upper bound on a single backoff delay before jitter. */
+    backoffMaxMs: number;
+    /** Jitter as a fraction of the computed delay, applied as +/- (0 = none). */
+    jitterRatio: number;
+}
+/**
+ * Default resilience policy. Generous timeouts so a legitimately long but live
+ * stage is never killed (the idle window sits well under the 5-min run heartbeat,
+ * and the wall window bounds a truly wedged child); three attempts with short,
+ * jittered backoff so a single transient blip across the up-to-8 child spawns no
+ * longer terminates the whole run.
+ */
+export declare const DEFAULT_RESILIENCE_POLICY: ResiliencePolicy;
+/**
+ * R3-a tool-failure health gate. A WRITE stage (implement / fix) that exits 0 is
+ * still a failure when most of its tool calls errored: the prose summary reads
+ * fine while the edits never landed (the recorded silent-partial-implement
+ * landmine). Conservative by design — BOTH guards must hold before a stage is
+ * failed for tool errors, so a couple of expected misses never trip it:
+ *  - `TOOL_ERROR_FAIL_RATE`: the error rate must EXCEED this clear majority, so a
+ *    grep that finds nothing or one transient error among many calls is fine.
+ *  - `MIN_TOOL_CALLS_FOR_HEALTH`: require a meaningful sample first, so a stage
+ *    that made only one or two tool calls is never failed on a tiny ratio.
+ * Tunable per lane if a future stage needs a stricter or looser bar.
+ */
+export declare const TOOL_ERROR_FAIL_RATE = 0.6;
+export declare const MIN_TOOL_CALLS_FOR_HEALTH = 4;
+/** Bound on parallel review-lens children per round (mirrors the subagent example). */
+export declare const MAX_CONCURRENCY = 4;
+/** Per-stage final-output byte cap when handed forward as `{previous}`. */
+export declare const PER_TASK_OUTPUT_CAP: number;
+/** Max length of a narration headline surfaced into the feed (spec §3). */
+export declare const NARRATION_MAX = 80;
+/** Bound on the active stage's rolling action ring buffer (spec §4). */
+export declare const FEED_WINDOW = 8;
+//# sourceMappingURL=types.d.ts.map

package/dist/extension/pipeline/types.js

@@ -0,0 +1,48 @@
+/**
+ * Single source of truth for the /go pipeline's data shapes + tuning constants.
+ *
+ * Pure types and constants only — no logic. Every other pipeline module imports
+ * from here so the orchestrator's correctness lives in typed data rather than in
+ * scattered string literals. The stage list is a declarative contract (spec
+ * §7.2) so future complexity-lanes select a subset, never a rewrite.
+ */
+/** Stop the review→fix loop after at most this many rounds (spec §7.3). */
+export const MAX_REVIEW_ROUNDS = 3;
+/**
+ * Default resilience policy. Generous timeouts so a legitimately long but live
+ * stage is never killed (the idle window sits well under the 5-min run heartbeat,
+ * and the wall window bounds a truly wedged child); three attempts with short,
+ * jittered backoff so a single transient blip across the up-to-8 child spawns no
+ * longer terminates the whole run.
+ */
+export const DEFAULT_RESILIENCE_POLICY = {
+    idleTimeoutMs: 4 * 60_000,
+    wallTimeoutMs: 20 * 60_000,
+    maxAttempts: 3,
+    backoffBaseMs: 1_000,
+    backoffMaxMs: 30_000,
+    jitterRatio: 0.25,
+};
+/**
+ * R3-a tool-failure health gate. A WRITE stage (implement / fix) that exits 0 is
+ * still a failure when most of its tool calls errored: the prose summary reads
+ * fine while the edits never landed (the recorded silent-partial-implement
+ * landmine). Conservative by design — BOTH guards must hold before a stage is
+ * failed for tool errors, so a couple of expected misses never trip it:
+ *  - `TOOL_ERROR_FAIL_RATE`: the error rate must EXCEED this clear majority, so a
+ *    grep that finds nothing or one transient error among many calls is fine.
+ *  - `MIN_TOOL_CALLS_FOR_HEALTH`: require a meaningful sample first, so a stage
+ *    that made only one or two tool calls is never failed on a tiny ratio.
+ * Tunable per lane if a future stage needs a stricter or looser bar.
+ */
+export const TOOL_ERROR_FAIL_RATE = 0.6;
+export const MIN_TOOL_CALLS_FOR_HEALTH = 4;
+/** Bound on parallel review-lens children per round (mirrors the subagent example). */
+export const MAX_CONCURRENCY = 4;
+/** Per-stage final-output byte cap when handed forward as `{previous}`. */
+export const PER_TASK_OUTPUT_CAP = 50 * 1024;
+/** Max length of a narration headline surfaced into the feed (spec §3). */
+export const NARRATION_MAX = 80;
+/** Bound on the active stage's rolling action ring buffer (spec §4). */
+export const FEED_WINDOW = 8;
+//# sourceMappingURL=types.js.map