aiki-cli 0.2.0

package/dist/orchestration/cluster.js

@@ -0,0 +1,83 @@
+// Deterministic restatement clustering for S2 (§9). Groups per-provider interpretations by
+// normalized token overlap; a threshold ≥ 0.6 puts two restatements in the same cluster. Pure
+// code (no model call) → directly unit-tested. This — not a model — decides whether the providers
+// agree on what the task is (§19 "deterministic validators decide what enters downstream").
+//
+// The overlap metric is the OVERLAP COEFFICIENT (|A∩B|/min), not Jaccard. §9 says "normalized token
+// overlap ≥ 0.6"; Jaccard was too strict on real prose — two same-meaning 1-sentence readings scored
+// right at ~0.60 and split, spuriously triggering the S2 clarification (observed live at T8). The
+// coefficient isn't penalized by length/filler differences: the two same-meaning readings score 0.76,
+// a genuine divergence scores ~0.50 — so real disagreement still clusters apart. (Fixed 2026-07-03.)
+export const SAME_CLUSTER_THRESHOLD = 0.6; // §9
+// Function words + restatement boilerplate ("the user is asking to…") carry no meaning about WHAT the
+// task is; keeping them dilutes the content-word overlap so two same-meaning readings that phrase the
+// framing differently split spuriously (V7). Dropping them makes the coefficient compare content only.
+// This does NOT loosen the 0.6 threshold — genuinely different readings still have disjoint content
+// words and split (see cluster.test). Deliberately conservative: no stemming (would risk false merges).
+const STOPWORDS = new Set([
+    'a', 'an', 'the', 'and', 'or', 'but', 'of', 'to', 'in', 'on', 'at', 'by', 'for', 'with', 'without',
+    'from', 'into', 'as', 'is', 'are', 'was', 'were', 'be', 'been', 'being', 'it', 'its', 'this', 'that',
+    'these', 'those', 'their', 'them', 'they', 'i', 'you', 'we', 'he', 'she', 'his', 'her', 'our', 'your',
+    'my', 'me', 'us', 'do', 'does', 'did', 'will', 'would', 'can', 'could', 'should', 'if', 'then', 'than',
+    'so', 'such', 'not', 'no', 'over', 'under', 'about', 'up', 'down', 'out', 'how', 'what', 'which',
+    // restatement framing verbs/nouns
+    'user', 'users', 'wants', 'want', 'wanting', 'asking', 'asks', 'ask', 'request', 'requesting', 'needs',
+    'need', 'wishes', 'wish', 'seeking', 'looking', 'like',
+]);
+/** Lowercase, split on non-alphanumerics, drop empties + stopwords. Overlap is on the resulting SET. */
+export function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 0 && !STOPWORDS.has(t)));
+}
+/** Jaccard overlap of two token sets: |A∩B| / |A∪B|. 0 when both empty. */
+export function overlap(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+/**
+ * Overlap coefficient of two token sets: |A∩B| / min(|A|,|B|). 0 when either is empty. Unlike
+ * Jaccard, it is not penalized when one text is much longer than the other — the right measure for
+ * "is this short restatement a subset of this longer text" (S5 drift: task_echo vs contract.task).
+ */
+export function overlapCoefficient(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    return inter / Math.min(a.size, b.size);
+}
+/**
+ * Single-link clustering: an item joins the first existing cluster whose representative it overlaps
+ * with ≥ threshold, else it starts a new cluster. Input order is preserved → deterministic output.
+ */
+export function clusterInterpretations(items, threshold = SAME_CLUSTER_THRESHOLD) {
+    const clusters = [];
+    for (const item of items) {
+        const tokens = tokenize(item.text);
+        const home = clusters.find((c) => overlapCoefficient(tokens, c.repTokens) >= threshold);
+        if (home)
+            home.members.push(item.key);
+        else
+            clusters.push({ members: [item.key], representative: item.text, repTokens: tokens });
+    }
+    return clusters.map((c) => ({ members: c.members, representative: c.representative }));
+}
+/** Index of the largest cluster (ties → earliest). Used by headless S2 to pick the majority. */
+export function majorityClusterIndex(clusters) {
+    let best = 0;
+    for (let i = 1; i < clusters.length; i++) {
+        if (clusters[i].members.length > clusters[best].members.length)
+            best = i;
+    }
+    return best;
+}

package/dist/orchestration/context.js

@@ -0,0 +1,277 @@
+// Run context + engine primitives (§6). A run is a single-threaded walk through typed stages;
+// `RunCtx` carries everything a stage needs and is the ONLY thing that spends the call budget.
+//
+// Invariants enforced here:
+// - Budget guard (§6, §19): a provider call that would exceed the budget throws `BudgetExceeded`
+//   BEFORE spawning anything; the run then fails gracefully with partial artifacts + meta.
+// - Wall-clock deadline (§19): checked before every call and between stages → `DeadlineExceeded`.
+//   A single in-flight call is separately bounded by the adapter's per-call timeout (process-tree
+//   kill), so the run cannot hang past deadline + one call timeout. (Mid-call abort is post-v1.)
+// - Full audit (§15): every call's exact prompt and raw output are written under `raw/`.
+import { randomBytes } from 'node:crypto';
+import { PROVIDER_IDS } from '../providers/types.js';
+import { ADAPTERS } from '../providers/adapters.js';
+import { extractJson } from '../providers/adapter-core.js';
+import { detect } from '../providers/detect.js';
+import { probeFlags } from '../providers/probe.js';
+import { replayKey } from '../storage/replay.js';
+/** Bracket a stage call with the TUI's start/end events (no-op headless). A thrown StageError marks
+ *  the row `failed` and re-propagates unchanged — the engine's failure handling is untouched. */
+export async function runStage(ctx, id, fn) {
+    ctx.events?.onStageStart?.(id);
+    try {
+        const result = await fn();
+        ctx.events?.onStageEnd?.(id, 'done');
+        return result;
+    }
+    catch (e) {
+        ctx.events?.onStageEnd?.(id, 'failed');
+        throw e;
+    }
+}
+export const DEFAULT_BUDGET = 18; // full idea pipeline min = S0(1)+S1(1)+S2(3)+S3(1)+S4(2)+S7-group(1)+
+// S8(1)+S9(1)+S9b(1) = 12. But S2 runs 3 providers that EACH can repair, plus S9 + S9b anchor repairs —
+// a live run spent 3 repairs and died at 13 before S9b. 18 = 12 + ~6 repair headroom so the validation
+// plan actually renders; a true repair-storm still fails gracefully. Overridable via `--budget`/config.
+// §19 was 10 min; raised to 20 (user-authorized 2026-07-06). Evidence: a real Opus judge (S9) on a
+// 9-dispute idea ran ~360s and the whole run was ~14 min → the 10-min wall-clock aborted a legitimate run.
+export const DEFAULT_DEADLINE_MS = 20 * 60 * 1000; // wall-clock cap
+// §7.1 was 180s; raised to 300 (user-authorized 2026-07-06). The adapter retries a TIMEOUT once, so 180s
+// gave a 360s ceiling and the deep-reasoning judge blew it (observed exactly 360.1s → TIMEOUT). 300s per
+// attempt covers the Opus judge; the wall-clock deadline above remains the outer bound.
+const DEFAULT_CALL_TIMEOUT_MS = 300_000;
+export class BudgetExceeded extends Error {
+    constructor(limit) {
+        super(`call budget exhausted (limit ${limit})`);
+        this.name = 'BudgetExceeded';
+    }
+}
+export class DeadlineExceeded extends Error {
+    constructor(deadlineMs) {
+        super(`run wall-clock deadline exceeded (${deadlineMs}ms)`);
+        this.name = 'DeadlineExceeded';
+    }
+}
+/** Raised by a stage when a provider call fails unrecoverably (post adapter retry) or output is
+ *  unusable after the §14 repair retry. Carries the provider taxonomy code for meta/reporting. */
+export class StageError extends Error {
+    stage;
+    code;
+    constructor(stage, code, // ProviderError | 'QUORUM' | 'ABORT'
+    message) {
+        super(`${stage}: ${message}`);
+        this.stage = stage;
+        this.code = code;
+        this.name = 'StageError';
+    }
+}
+export class RunCtx {
+    runId;
+    workflow;
+    roles;
+    writer;
+    cwd;
+    events;
+    budget;
+    calls = [];
+    /** §16 report-header flags accumulated by stages (S4 → low_diversity, S7 → low_diversity,
+     *  S9 → synthesis_suspect). Folded into meta.json at finalize by `buildMeta`. */
+    flags = new Set();
+    handles;
+    signal;
+    deadlineMs;
+    deadlineAt;
+    now;
+    replay; // resume replay cache (V6.3)
+    seq = 0; // monotonic per-call counter for raw/ filenames (== budget.used on a fresh run)
+    constructor(opts) {
+        this.runId = opts.runId;
+        this.workflow = opts.workflow;
+        this.roles = opts.roles;
+        this.writer = opts.writer;
+        this.cwd = opts.cwd;
+        this.events = opts.events;
+        this.budget = { limit: opts.budget ?? DEFAULT_BUDGET, used: 0 };
+        this.handles = new Map(opts.handles.map((h) => [h.id, h]));
+        this.signal = opts.signal;
+        this.deadlineMs = opts.deadlineMs ?? DEFAULT_DEADLINE_MS;
+        this.now = opts.now ?? Date.now;
+        this.deadlineAt = this.now() + this.deadlineMs;
+        this.replay = opts.replay;
+    }
+    /** Provider ids available this run (READY at setup). */
+    available() {
+        return [...this.handles.keys()];
+    }
+    /** True once the run's abort signal has fired (Ctrl+C). Lets the finalizer record `aborted:true`
+     *  even when the triggering error surfaced as something else (e.g. a killed in-flight call). */
+    get aborted() {
+        return this.signal?.aborted ?? false;
+    }
+    handle(id) {
+        const h = this.handles.get(id);
+        if (!h)
+            throw new StageError('setup', 'QUORUM', `provider ${id} not available`);
+        return h;
+    }
+    /** Raise a §16 report-header flag; deduped, folded into meta at finalize. */
+    addFlag(flag) {
+        this.flags.add(flag);
+    }
+    /** Guard: throw if aborted or past the wall-clock deadline. Called before every provider call. */
+    guard() {
+        if (this.signal?.aborted)
+            throw new StageError('run', 'ABORT', 'aborted');
+        if (this.now() > this.deadlineAt)
+            throw new DeadlineExceeded(this.deadlineMs);
+    }
+    /**
+     * Make one budgeted provider call. Decrements budget (throws `BudgetExceeded` if it would go
+     * over), records a `CallRecord`, and dumps the exact prompt + raw output under `raw/` (§15).
+     */
+    async call(handle, req, stage) {
+        this.guard();
+        const seq = ++this.seq;
+        await this.writer.writeRaw(`${stage}-${handle.id}-${seq}.prompt.txt`, req.prompt);
+        // Resume (V6.3): if this exact (provider, prompt) already succeeded in the run we're resuming,
+        // replay its output — no real call, no budget spend. Only never-completed calls hit the model.
+        const cachedOut = this.replay?.get(replayKey(handle.id, req.prompt));
+        let res;
+        if (cachedOut !== undefined) {
+            res = { ok: true, text: cachedOut, json: req.expectJson ? extractJson(cachedOut) : undefined, durationMs: 0 };
+        }
+        else {
+            if (this.budget.used + 1 > this.budget.limit)
+                throw new BudgetExceeded(this.budget.limit);
+            this.budget.used++;
+            res = await handle.adapter.run({
+                prompt: req.prompt,
+                cwd: req.cwd ?? this.cwd,
+                timeoutMs: req.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS,
+                expectJson: req.expectJson,
+                readOnly: true,
+                signal: this.signal, // Ctrl+C kills the in-flight child (T8); undefined headless
+            }, handle.flags);
+            // Only REAL calls count toward the ledger/budget; a replayed call is free and already recorded in
+            // the run it came from. raw/ below still logs the replayed prompt+output for a full audit.
+            this.calls.push({
+                provider: handle.id,
+                stage,
+                durationMs: res.durationMs,
+                ...(res.ok ? {} : { error: res.error }),
+            });
+        }
+        await this.writer.writeRaw(`${stage}-${handle.id}-${seq}.out`, res.ok ? res.text : `[${res.error}]\n${res.stderrTail}`);
+        return res;
+    }
+    /** Assemble the run's `meta.json` payload (§15) from the handles + call ledger accumulated so
+     *  far. Called at finalize (success) and in the failure path (partial artifacts stay valid). */
+    buildMeta(exitStatus, aborted, flags) {
+        const provider_versions = {};
+        const flag_profiles = {};
+        const read_only = {};
+        for (const h of this.handles.values()) {
+            if (h.version)
+                provider_versions[h.id] = h.version;
+            flag_profiles[h.id] = h.flags;
+            read_only[h.id] = h.readOnly;
+        }
+        // Roles record: the three singular roles plus one `s4_<n>` entry per fan-out seat (T6).
+        const roles = {
+            analyst: this.roles.analyst,
+            judge: this.roles.judge,
+            verifier: this.roles.verifier,
+        };
+        this.roles.s4.forEach((id, i) => (roles[`s4_${i + 1}`] = id));
+        // Fold stage-raised flags in with any explicitly passed by the caller; dedupe.
+        const allFlags = [...new Set([...(flags ?? []), ...this.flags])];
+        return {
+            run_id: this.runId,
+            workflow: this.workflow,
+            provider_versions,
+            flag_profiles,
+            roles,
+            read_only,
+            calls: this.calls,
+            call_count: this.calls.length,
+            budget: { limit: this.budget.limit, used: this.budget.used },
+            exit_status: exitStatus,
+            aborted,
+            ...(allFlags.length ? { flags: allFlags } : {}),
+        };
+    }
+}
+/** Run-fatal errors abort the whole run; everything else (e.g. a single provider failure in a
+ *  fan-out) is handled locally by the stage (drop provider, check quorum). */
+export function isFatal(e) {
+    return e instanceof BudgetExceeded || e instanceof DeadlineExceeded || (e instanceof StageError && e.code === 'ABORT');
+}
+// ── Provider setup + role assignment ────────────────────────────────────────
+const READONLY_FROM_FLAG = (f) => f.readOnlyFlag;
+/**
+ * Build handles for every provider that is READY (detect + flag probe; no model calls). Providers
+ * that aren't installed are simply omitted; quorum (§8) is checked by the caller.
+ */
+export async function setupProviders(models) {
+    const handles = [];
+    for (const id of PROVIDER_IDS) {
+        const det = await detect(id);
+        if (det.status !== 'READY')
+            continue;
+        const probed = await probeFlags(id);
+        const model = models?.[id]; // V8: user-chosen model → passed to the CLI as `--model <id>`
+        const flags = model ? { ...probed, model } : probed;
+        handles.push({ id, adapter: ADAPTERS[id], flags, readOnly: READONLY_FROM_FLAG(flags), version: det.version ?? null });
+    }
+    return handles;
+}
+/** Preference order used when a role's default provider is unavailable. */
+const ANALYST_PREF = ['agy', 'codex', 'claude'];
+const JUDGE_PREF = ['claude', 'agy', 'codex'];
+// code-review (§271): reviewers = claude + codex (strongest code-nav, they AUTHOR findings); judge =
+// agy (Gemini) so the judge never adjudicates its own finding. Verifier role is unused (S8 = mutual
+// cross-exam by the two reviewers).
+const CR_REVIEWERS = ['claude', 'codex'];
+const CR_JUDGE_PREF = ['agy', 'claude', 'codex'];
+/**
+ * Default role assignment (§10, decided at T5) with graceful degradation and an override seam.
+ * `overrides` is the config/flag hook (§10 "config can pin roles") — config loading itself is T9.
+ *
+ * idea-refinement default (3 providers): analyst=agy, judge=claude, verifier=codex, S4=[agy,codex].
+ * The one hard rule kept even under degradation: the judge must not be the sole S4 author it would
+ * adjudicate — with ≥2 S4 seats and judge picked outside them, that holds. Full §8/§10 fallbacks
+ * (2- and 1-provider self-consistency) are firmed at T6 when S4 lands.
+ */
+export function resolveRoles(workflow, available, overrides) {
+    const has = (id) => available.includes(id);
+    const pick = (pref, avoid = []) => {
+        const chosen = pref.find((id) => has(id) && !avoid.includes(id)) ?? pref.find((id) => has(id)) ?? available[0];
+        if (!chosen)
+            throw new StageError('setup', 'QUORUM', 'no providers available for role assignment');
+        return chosen;
+    };
+    // code-review (§271): reviewers author findings, judge must not be one of them. Verifier unused.
+    if (workflow === 'code-review') {
+        const reviewers = CR_REVIEWERS.filter(has);
+        const s4 = overrides?.s4 ?? (reviewers.length ? reviewers : available);
+        const judge = overrides?.judge ?? pick(CR_JUDGE_PREF, s4); // prefer agy, avoid the reviewers
+        return {
+            analyst: overrides?.analyst ?? s4[0] ?? judge, // unused in code-review (S1/S3 are deterministic)
+            judge,
+            verifier: overrides?.verifier ?? judge, // unused (S8 is mutual cross-exam) — kept type-valid
+            s4,
+        };
+    }
+    // idea-refinement: S4 seats = the two non-judge providers so the judge stays a non-author (§10).
+    const judge = overrides?.judge ?? pick(JUDGE_PREF);
+    const analyst = overrides?.analyst ?? pick(ANALYST_PREF);
+    const s4 = overrides?.s4 ?? available.filter((id) => id !== judge);
+    const verifier = overrides?.verifier ?? (has('codex') ? 'codex' : pick(ANALYST_PREF, [judge]));
+    return { analyst, judge, verifier, s4 };
+}
+/** Generate a run id: `<yyyymmdd>-<hhmm>-<workflow>-<rand4>` (§15). */
+export function makeRunId(workflow, at = new Date()) {
+    const p = (n, w = 2) => String(n).padStart(w, '0');
+    const stamp = `${at.getFullYear()}${p(at.getMonth() + 1)}${p(at.getDate())}-${p(at.getHours())}${p(at.getMinutes())}`;
+    return `${stamp}-${workflow}-${randomBytes(2).toString('hex')}`;
+}

package/dist/orchestration/engine.js

@@ -0,0 +1,92 @@
+// Engine run wrapper (§6). Sets up the run folder, walks a workflow's stage composition, and — no
+// matter how the run ends — finalizes a valid `meta.json` with the exit status. A fatal error
+// (budget/deadline/abort/bad-output/quorum) becomes a graceful failure: partial artifacts on disk
+// stay valid (RunWriter atomic writes) and meta records what happened (§6, §19).
+import { dirname, resolve } from 'node:path';
+import { BudgetExceeded, DeadlineExceeded, StageError, makeRunId, resolveRoles, setupProviders, RunCtx } from './context.js';
+import { RunWriter } from '../storage/runs.js';
+import { recordSession, updateSessionStatus } from '../storage/sessions.js';
+import { runIdeaRefinement } from '../workflows/idea-refinement.js';
+import { runCodeReview } from '../workflows/code-review.js';
+const WORKFLOWS = {
+    'idea-refinement': runIdeaRefinement,
+    'code-review': runCodeReview,
+};
+function classifyError(e) {
+    if (e instanceof BudgetExceeded)
+        return { code: 'BUDGET', aborted: false };
+    if (e instanceof DeadlineExceeded)
+        return { code: 'DEADLINE', aborted: false };
+    if (e instanceof StageError)
+        return { code: e.code, aborted: e.code === 'ABORT' };
+    return { code: 'CRASH', aborted: false };
+}
+/** Execute a workflow within an already-built RunCtx. Writes 00-original.md, runs the stages, and
+ *  finalizes meta.json in both the success and failure paths. */
+export async function executeRun(ctx, input, fn) {
+    await ctx.writer.init();
+    await ctx.writer.writeText('original', input);
+    ctx.events?.onStart?.(ctx.runId, ctx.writer.dir);
+    const base = { runId: ctx.runId, dir: ctx.writer.dir };
+    try {
+        await fn(ctx, input);
+        await ctx.writer.writeMeta(ctx.buildMeta('ok', false));
+        return { ok: true, ...base, callCount: ctx.calls.length };
+    }
+    catch (e) {
+        const classified = classifyError(e);
+        // A fired abort signal wins: record `aborted` even if the surfacing error was e.g. a killed
+        // in-flight call classified as CRASH/QUORUM (§472/§603 — Ctrl+C leaves aborted:true meta).
+        const aborted = ctx.aborted || classified.aborted;
+        // Best-effort finalize: never let a meta-write failure mask the original error.
+        await ctx.writer.writeMeta(ctx.buildMeta(aborted ? 'aborted' : 'failed', aborted)).catch(() => { });
+        return { ok: false, ...base, callCount: ctx.calls.length, error: { code: classified.code, message: e instanceof Error ? e.message : String(e) } };
+    }
+}
+/**
+ * Top-level headless entry (backs `aiki run`): detect+probe providers, check quorum (§8), assign
+ * roles (§10), build the RunCtx, and execute the workflow. No smoke test here — a dead provider
+ * surfaces as a call failure handled by the stage's quorum logic.
+ */
+export async function run(workflow, input, opts = {}) {
+    const handles = await setupProviders(opts.providerModels);
+    if (handles.length < 2) {
+        return {
+            ok: false,
+            runId: '(none)',
+            dir: '',
+            callCount: 0,
+            error: { code: 'QUORUM', message: `need ≥2 providers, found ${handles.length} — run \`aiki doctor\`` },
+        };
+    }
+    const runId = makeRunId(workflow);
+    const roles = resolveRoles(workflow, handles.map((h) => h.id), opts.roleOverrides);
+    const writer = new RunWriter(runId, opts.runsRoot);
+    const ctx = new RunCtx({
+        runId,
+        workflow,
+        handles,
+        roles,
+        writer,
+        cwd: opts.cwd ?? writer.dir, // code-review passes the repo root so reviewers can read the tree
+        budget: opts.budget,
+        deadlineMs: opts.deadlineMs,
+        signal: opts.signal,
+        events: opts.events,
+        replay: opts.replay,
+    });
+    // Register the session (V6.3) so `aiki sessions`/`resume` can find it from anywhere. run() is a
+    // real-CLI entry (setupProviders); tests use executeRun directly and never touch the global registry.
+    await recordSession({
+        id: runId,
+        workflow,
+        cwd: opts.cwd ?? writer.dir,
+        runsRoot: resolve(dirname(dirname(writer.dir))),
+        startedAt: new Date().toISOString(),
+        status: 'running',
+        ...(opts.resumedFrom ? { resumedFrom: opts.resumedFrom } : {}),
+    });
+    const outcome = await executeRun(ctx, input, WORKFLOWS[workflow]);
+    await updateSessionStatus(runId, outcome.ok ? 'ok' : 'failed');
+    return outcome;
+}

package/dist/orchestration/git.js

@@ -0,0 +1,133 @@
+// Git plumbing for the code-review workflow (§12.2, T10). This is aiki's OWN read-only git usage
+// (compute the diff to review) — not a provider spawn, so it doesn't go through the adapter machinery.
+//
+// Range semantics: THREE-DOT (`base...head`) = the merge-base diff, i.e. only what HEAD added since it
+// diverged from base. That's what "review this branch/PR" means and avoids noise when base moved ahead
+// (grilled 2026-07-04).
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+export class GitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitError';
+    }
+}
+/** Absolute path of the repo root containing `cwd`, or null if `cwd` isn't inside a git work tree. */
+export async function repoToplevel(cwd) {
+    try {
+        const { stdout } = await exec('git', ['rev-parse', '--show-toplevel'], { cwd });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function gitStdout(args, cwd) {
+    try {
+        const { stdout } = await exec('git', args, { cwd, maxBuffer: 32 * 1024 * 1024 });
+        return stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function chooseDefaultBranch(originHead, refs) {
+    const trimmed = originHead?.trim();
+    if (trimmed)
+        return trimmed;
+    for (const name of ['main', 'master']) {
+        if (refs.includes(name))
+            return name;
+        if (refs.includes(`origin/${name}`))
+            return `origin/${name}`;
+    }
+    return null;
+}
+export async function detectDefaultBranch(cwd) {
+    const originHead = await gitStdout(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], cwd);
+    const refsRaw = await gitStdout(['for-each-ref', '--format=%(refname:short)', 'refs/heads', 'refs/remotes'], cwd);
+    return chooseDefaultBranch(originHead, refsRaw ? refsRaw.split('\n').filter(Boolean) : []);
+}
+/** Compute the unified diff to review: `git diff --unified=3 <base>...<head>` (three-dot merge-base). */
+export async function computeDiff(base, head, cwd) {
+    try {
+        const { stdout } = await exec('git', ['diff', '--unified=3', `${base}...${head}`], { cwd, maxBuffer: 32 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (e) {
+        throw new GitError(`git diff ${base}...${head} failed: ${e.message.split('\n')[0]}`);
+    }
+}
+async function mergeBase(base, head, cwd) {
+    const mb = await gitStdout(['merge-base', base, head], cwd);
+    if (!mb)
+        throw new GitError(`git merge-base ${base} ${head} failed`);
+    return mb;
+}
+async function untrackedFiles(cwd) {
+    const raw = await gitStdout(['ls-files', '--others', '--exclude-standard'], cwd);
+    return raw ? raw.split('\n').filter(Boolean) : [];
+}
+async function diffUntrackedFile(file, cwd) {
+    try {
+        const { stdout } = await exec('git', ['diff', '--no-index', '--', '/dev/null', file], { cwd, maxBuffer: 32 * 1024 * 1024 });
+        return stdout;
+    }
+    catch (e) {
+        const err = e;
+        if (err.stdout)
+            return err.stdout;
+        throw e;
+    }
+}
+/** Diff from the merge-base to the current working tree, including staged, unstaged, and untracked files. */
+export async function computeWorkingTreeDiff(base, cwd) {
+    try {
+        const mb = await mergeBase(base, 'HEAD', cwd);
+        const { stdout } = await exec('git', ['diff', '--unified=3', mb], { cwd, maxBuffer: 32 * 1024 * 1024 });
+        const extra = await Promise.all((await untrackedFiles(cwd)).map((f) => diffUntrackedFile(f, cwd)));
+        return [stdout, ...extra].filter(Boolean).join('\n');
+    }
+    catch (e) {
+        if (e instanceof GitError)
+            throw e;
+        throw new GitError(`git diff working tree against ${base} failed: ${e.message.split('\n')[0]}`);
+    }
+}
+export async function changedFilesSinceDefault(base, cwd) {
+    try {
+        const mb = await mergeBase(base, 'HEAD', cwd);
+        const { stdout } = await exec('git', ['diff', '--name-only', mb], { cwd, maxBuffer: 32 * 1024 * 1024 });
+        const files = new Set([...stdout.split('\n').filter(Boolean), ...await untrackedFiles(cwd)]);
+        return files.size;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function detectRepoStatus(cwd) {
+    const root = await repoToplevel(cwd);
+    if (!root)
+        return null;
+    const defaultBranch = await detectDefaultBranch(root);
+    const changedFiles = defaultBranch ? await changedFilesSinceDefault(defaultBranch, root) : 0;
+    return { root, name: root.split('/').filter(Boolean).at(-1) ?? root, defaultBranch, changedFiles };
+}
+/**
+ * Pure: the set of files present at HEAD that the diff touches — parsed from `+++ b/<path>` lines
+ * (a `+++ /dev/null` marks a deletion, which has no HEAD file, so it is skipped). These are exactly
+ * the files a finding is allowed to reference (§12.2 "file appears in the diff").
+ */
+export function parseDiffFiles(diff) {
+    const files = new Set();
+    for (const line of diff.split('\n')) {
+        if (!line.startsWith('+++ '))
+            continue;
+        const path = line.slice(4).trim();
+        if (path === '/dev/null')
+            continue;
+        files.add(path.startsWith('b/') ? path.slice(2) : path);
+    }
+    return [...files];
+}

package/dist/orchestration/jsonStage.js

@@ -0,0 +1,32 @@
+// Shared helper for stages whose provider output is schema-validated JSON (§14).
+//
+// Flow: call provider (expectJson) → the adapter already did its ONE transient retry + §14
+// extraction → here we zod-validate the extracted JSON. On a *validation* failure we do the §14
+// repair retry: resend to the SAME provider with the zod error and a "corrected JSON only"
+// instruction, exactly once. A second failure → StageError('BAD_OUTPUT'), which the stage turns
+// into its §9 failure handling (S1/S3 abort the run).
+import { StageError } from './context.js';
+export async function jsonCall(ctx, handle, stage, prompt, schema, opts = {}) {
+    const first = await ctx.call(handle, { prompt, expectJson: true, cwd: opts.cwd }, stage);
+    if (!first.ok) {
+        // AUTH/QUOTA/NOT_FOUND fail fast; TIMEOUT/CRASH/BAD_OUTPUT were already retried once by the adapter.
+        throw new StageError(stage, first.error, `provider ${handle.id} call failed (${first.error})`);
+    }
+    const parsed = schema.safeParse(first.json);
+    if (parsed.success)
+        return parsed.data;
+    // §14 repair retry — one attempt, same provider.
+    const repairPrompt = `${prompt}\n\n---\nYour previous output failed validation:\n${zodMessage(parsed.error)}\n` +
+        `Output ONLY the corrected JSON, nothing else.`;
+    const second = await ctx.call(handle, { prompt: repairPrompt, expectJson: true, cwd: opts.cwd }, `${stage}-repair`);
+    if (!second.ok) {
+        throw new StageError(stage, second.error, `repair retry failed (${second.error})`);
+    }
+    const reparsed = schema.safeParse(second.json);
+    if (reparsed.success)
+        return reparsed.data;
+    throw new StageError(stage, 'BAD_OUTPUT', `output failed validation after repair: ${zodMessage(reparsed.error)}`);
+}
+function zodMessage(err) {
+    return err.issues.map((i) => `- ${i.path.join('.') || '(root)'}: ${i.message}`).join('\n');
+}

package/dist/orchestration/skills.js

@@ -0,0 +1,39 @@
+// Skills — per-role playbooks that sharpen a stage prompt without changing code. A "skill" is a
+// markdown file under src/skills/<workflow>/<role>.md (copied to dist/skills/ at build; the path
+// resolves the same in src and dist because the tree mirrors). A missing playbook returns '' so
+// callers stay backward-compatible: the stage prompt is byte-for-byte unchanged when no skill exists.
+//
+// §19 skill-injection boundary: playbooks load ONLY from the repo skills dir (never remote / user
+// paths), AND their text is scanned for exfiltration patterns. A playbook that trips the lint is
+// rejected (treated as absent) — fail-closed to the safe no-skill baseline; a bad skill file never
+// crashes the run, it just doesn't apply.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/** Exfiltration patterns a skill playbook must not contain (§19). Repo files are author-controlled;
+ *  this is defense-in-depth against a compromised playbook smuggling a "leak this" instruction. */
+const EXFIL_PATTERNS = [
+    { name: 'url', re: /\b(?:https?|ftp):\/\//i },
+    { name: 'upload', re: /\bupload\b/i },
+    { name: 'send-to', re: /\bsend\b[^\n]{0,30}\bto\b/i },
+    { name: 'base64-blob', re: /[A-Za-z0-9+/=]{50,}/ },
+];
+/** The name of the first exfiltration pattern `text` trips, or null if it is clean. */
+export function lintSkill(text) {
+    for (const { name, re } of EXFIL_PATTERNS)
+        if (re.test(text))
+            return name;
+    return null;
+}
+/** Load the playbook for a role in a workflow, or '' if none exists OR it fails the §19 lint.
+ *  Role-keyed, provider-agnostic. */
+export function loadSkill(workflow, role) {
+    const url = new URL(`../skills/${workflow}/${role}.md`, import.meta.url);
+    let text;
+    try {
+        text = readFileSync(fileURLToPath(url), 'utf8').trim();
+    }
+    catch {
+        return ''; // no playbook for this role → prompt unchanged
+    }
+    return lintSkill(text) ? '' : text; // §19: reject a playbook that trips the exfil lint
+}