astrocode-workflow 0.0.1

package/dist/workflow/baton.js

@@ -0,0 +1,101 @@
+import { clampLines, normalizeNewlines, stripCodeFences } from "../shared/text";
+import { z } from "zod";
+export const ASTRO_JSON_BEGIN = "<!-- ASTRO_JSON_BEGIN -->";
+export const ASTRO_JSON_END = "<!-- ASTRO_JSON_END -->";
+export const StageKeySchema = z.enum(["frame", "plan", "spec", "implement", "review", "verify", "close"]);
+export const AstroJsonSchema = z.object({
+    schema_version: z.number().int().default(1),
+    run_id: z.string().optional(),
+    story_key: z.string().optional(),
+    stage_key: StageKeySchema,
+    status: z.enum(["ok", "blocked", "failed"]).default("ok"),
+    summary: z.string().default(""),
+    decisions: z.array(z.string()).default([]),
+    next_actions: z.array(z.string()).default([]),
+    files: z.array(z.object({
+        path: z.string(),
+        kind: z.string().default("file"),
+        notes: z.string().optional(),
+    })).default([]),
+    evidence: z.array(z.object({
+        path: z.string(),
+        kind: z.string().default("evidence"),
+        notes: z.string().optional(),
+    })).default([]),
+    new_stories: z.array(z.object({
+        title: z.string(),
+        body_md: z.string().optional(),
+        priority: z.number().int().optional(),
+    })).default([]),
+    questions: z.array(z.string()).default([]),
+    metrics: z.record(z.string(), z.union([z.number(), z.string()])).default({}),
+});
+export function parseStageOutputText(text) {
+    const norm = normalizeNewlines(text ?? "").trim();
+    const beginIdx = norm.indexOf(ASTRO_JSON_BEGIN);
+    const endIdx = norm.indexOf(ASTRO_JSON_END);
+    if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
+        return {
+            baton_md: norm,
+            astro_json: null,
+            astro_json_raw: null,
+            error: `Missing ASTRO JSON markers. Expected markers ${ASTRO_JSON_BEGIN} ... ${ASTRO_JSON_END}`,
+        };
+    }
+    const before = norm.slice(0, beginIdx).trim();
+    const jsonRaw = norm.slice(beginIdx + ASTRO_JSON_BEGIN.length, endIdx).trim();
+    const after = norm.slice(endIdx + ASTRO_JSON_END.length).trim();
+    const baton = [before, after].filter(Boolean).join("\n\n").trim();
+    try {
+        const cleaned = stripCodeFences(jsonRaw).trim();
+        const parsed = JSON.parse(cleaned);
+        const astroJson = AstroJsonSchema.parse(parsed);
+        return { baton_md: baton, astro_json: astroJson, astro_json_raw: cleaned, error: null };
+    }
+    catch (e) {
+        return {
+            baton_md: baton,
+            astro_json: null,
+            astro_json_raw: jsonRaw,
+            error: `Failed to parse ASTRO JSON: ${String(e)}`,
+        };
+    }
+}
+export function buildBatonSummary(opts) {
+    const { config, stage_key, astro_json, baton_md } = opts;
+    const maxLines = config.context_compaction.baton_summary_max_lines;
+    const lines = [];
+    lines.push(`# ${stage_key} — Summary`);
+    if (astro_json?.summary) {
+        lines.push("", astro_json.summary.trim());
+    }
+    else {
+        // Fallback: first non-empty paragraph
+        const paras = baton_md.split(/\n\n+/).map((p) => p.trim()).filter(Boolean);
+        if (paras[0])
+            lines.push("", paras[0]);
+    }
+    const addList = (title, items) => {
+        if (!items.length)
+            return;
+        lines.push("", `## ${title}`);
+        for (const it of items.slice(0, 12))
+            lines.push(`- ${it}`);
+    };
+    addList("Decisions", astro_json?.decisions ?? []);
+    addList("Next actions", astro_json?.next_actions ?? []);
+    const files = astro_json?.files ?? [];
+    if (files.length) {
+        lines.push("", "## Files");
+        for (const f of files.slice(0, 15))
+            lines.push(`- \`${f.path}\` (${f.kind})${f.notes ? ` — ${f.notes}` : ""}`);
+    }
+    const evidence = astro_json?.evidence ?? [];
+    if (evidence.length) {
+        lines.push("", "## Evidence");
+        for (const ev of evidence.slice(0, 15))
+            lines.push(`- \`${ev.path}\` (${ev.kind})${ev.notes ? ` — ${ev.notes}` : ""}`);
+    }
+    const out = lines.join("\n").trim();
+    return clampLines(out, maxLines);
+}

package/dist/workflow/context.d.ts

@@ -0,0 +1,12 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import type { RunRow, StageRunRow, StoryRow } from "../state/types";
+export declare function getRun(db: SqliteDb, runId: string): RunRow | null;
+export declare function getStory(db: SqliteDb, storyKey: string): StoryRow | null;
+export declare function listStageRuns(db: SqliteDb, runId: string): StageRunRow[];
+export declare function buildContextSnapshot(opts: {
+    db: SqliteDb;
+    config: AstrocodeConfig;
+    run_id: string;
+    next_action?: string;
+}): string;

package/dist/workflow/context.js

@@ -0,0 +1,67 @@
+import { clampLines } from "../shared/text";
+export function getRun(db, runId) {
+    const row = db.prepare("SELECT * FROM runs WHERE run_id = ?").get(runId);
+    return row ?? null;
+}
+export function getStory(db, storyKey) {
+    const row = db.prepare("SELECT * FROM stories WHERE story_key = ?").get(storyKey);
+    return row ?? null;
+}
+export function listStageRuns(db, runId) {
+    return db
+        .prepare("SELECT * FROM stage_runs WHERE run_id = ? ORDER BY stage_index ASC")
+        .all(runId);
+}
+function statusIcon(status) {
+    switch (status) {
+        case "completed":
+            return "✅";
+        case "running":
+            return "🟦";
+        case "failed":
+            return "⛔";
+        case "skipped":
+            return "⏭️";
+        case "pending":
+        default:
+            return "⬜";
+    }
+}
+export function buildContextSnapshot(opts) {
+    const { db, config, run_id, next_action } = opts;
+    const run = getRun(db, run_id);
+    if (!run)
+        return `Run not found: ${run_id}`;
+    const story = getStory(db, run.story_key);
+    const stageRuns = listStageRuns(db, run_id);
+    const lines = [];
+    lines.push(`# Astrocode Context`);
+    lines.push(`- Run: \`${run.run_id}\`  Status: **${run.status}**`);
+    if (run.current_stage_key)
+        lines.push(`- Current stage: \`${run.current_stage_key}\``);
+    if (next_action)
+        lines.push(`- Next action: ${next_action}`);
+    if (story) {
+        lines.push(`- Story: \`${story.story_key}\` — ${story.title}`);
+        if (story.body_md?.trim()) {
+            const first = story.body_md.trim().split(/\n\n+/)[0]?.trim();
+            if (first)
+                lines.push(`- Story summary: ${first}`);
+        }
+    }
+    lines.push(``, `## Pipeline`);
+    for (const s of stageRuns) {
+        lines.push(`- ${statusIcon(s.status)} \`${s.stage_key}\` (${s.status})`);
+    }
+    const completed = stageRuns.filter((s) => s.status === "completed" && (s.summary_md ?? "").trim());
+    const lastSummaries = completed.slice(-config.context_compaction.snapshot_after_stage_count);
+    if (lastSummaries.length) {
+        lines.push(``, `## Recent stage summaries`);
+        for (const s of lastSummaries) {
+            lines.push(``, `### ${s.stage_key}`);
+            lines.push((s.summary_md ?? "").trim());
+        }
+    }
+    const out = lines.join("\n").trim();
+    return clampLines(out, config.context_compaction.snapshot_max_lines);
+}

package/dist/workflow/directives.d.ts

@@ -0,0 +1,37 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { StageKey } from "../state/types";
+export type DirectiveKind = "continue" | "stage" | "blocked" | "repair";
+export type BuiltDirective = {
+    kind: DirectiveKind;
+    title: string;
+    body: string;
+    hash: string;
+};
+export declare function directiveHash(body: string): string;
+export declare function buildContinueDirective(opts: {
+    config: AstrocodeConfig;
+    run_id: string;
+    stage_key: string | null;
+    next_action: string;
+    context_snapshot_md: string;
+}): BuiltDirective;
+export declare function buildBlockedDirective(opts: {
+    run_id: string;
+    stage_key: string;
+    question: string;
+    context_snapshot_md: string;
+}): BuiltDirective;
+export declare function buildRepairDirective(opts: {
+    report_md: string;
+}): BuiltDirective;
+export declare function buildStageDirective(opts: {
+    config: AstrocodeConfig;
+    stage_key: StageKey;
+    run_id: string;
+    story_key: string;
+    story_title: string;
+    stage_agent_name: string;
+    stage_goal: string;
+    stage_constraints: string[];
+    context_snapshot_md: string;
+}): BuiltDirective;

package/dist/workflow/directives.js

@@ -0,0 +1,111 @@
+import { sha256Hex } from "../shared/hash";
+import { clampChars, normalizeNewlines } from "../shared/text";
+export function directiveHash(body) {
+    // Stable hash to dedupe: normalize newlines + trim
+    const norm = normalizeNewlines(body).trim();
+    return sha256Hex(norm);
+}
+export function buildContinueDirective(opts) {
+    const { config, run_id, stage_key, next_action, context_snapshot_md } = opts;
+    const body = clampChars(normalizeNewlines([
+        `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`,
+        ``,
+        `Run: \`${run_id}\`${stage_key ? `  Stage: \`${stage_key}\`` : ""}`,
+        ``,
+        `Next action: ${next_action}`,
+        ``,
+        `Rules:`,
+        `- Do not stop early. Keep going until the run is completed, failed, or blocked.`,
+        `- Prefer tools over prose.`,
+        `- If blocked, ask exactly ONE question and stop.`,
+        ``,
+        `Context snapshot:`,
+        context_snapshot_md.trim(),
+    ].join("\n")), config.context_compaction.inject_max_chars);
+    return {
+        kind: "continue",
+        title: "ASTROCODE — CONTINUE",
+        body,
+        hash: directiveHash(body),
+    };
+}
+export function buildBlockedDirective(opts) {
+    const { run_id, stage_key, question, context_snapshot_md } = opts;
+    const body = normalizeNewlines([
+        `[SYSTEM DIRECTIVE: ASTROCODE — BLOCKED]`,
+        ``,
+        `Run: \`${run_id}\`  Stage: \`${stage_key}\``,
+        ``,
+        `You are blocked. Ask the user exactly ONE question (below), then stop.`,
+        ``,
+        `Question: ${question}`,
+        ``,
+        `Context snapshot:`,
+        context_snapshot_md.trim(),
+    ].join("\n")).trim();
+    return {
+        kind: "blocked",
+        title: "ASTROCODE — BLOCKED",
+        body,
+        hash: directiveHash(body),
+    };
+}
+export function buildRepairDirective(opts) {
+    const body = normalizeNewlines([
+        `[SYSTEM DIRECTIVE: ASTROCODE — REPAIR]`,
+        ``,
+        `Astrocode performed a repair pass. Summarize in <= 10 lines and continue.`,
+        ``,
+        `Repair report:`,
+        opts.report_md.trim(),
+    ].join("\n")).trim();
+    return {
+        kind: "repair",
+        title: "ASTROCODE — REPAIR",
+        body,
+        hash: directiveHash(body),
+    };
+}
+export function buildStageDirective(opts) {
+    const { config, stage_key, run_id, story_key, story_title, stage_agent_name, stage_goal, stage_constraints, context_snapshot_md } = opts;
+    const stageKeyUpper = stage_key.toUpperCase();
+    const constraintsBlock = stage_constraints.length
+        ? ["", "Constraints:", ...stage_constraints.map((c) => `- ${c}`)].join("\n")
+        : "";
+    const body = clampChars(normalizeNewlines([
+        `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_${stageKeyUpper}]`,
+        ``,
+        `You are: \`${stage_agent_name}\``,
+        `Run: \`${run_id}\``,
+        `Story: \`${story_key}\` — ${story_title}`,
+        ``,
+        `Stage goal: ${stage_goal}`,
+        constraintsBlock,
+        ``,
+        `Output contract (strict):`,
+        `1) Baton markdown (short, structured)`,
+        `2) ASTRO JSON between markers:`,
+        `   ${"```"}`,
+        `   ${"<!-- ASTRO_JSON_BEGIN -->"}`,
+        `   {...}`,
+        `   ${"<!-- ASTRO_JSON_END -->"}`,
+        `   ${"```"}`,
+        ``,
+        `ASTRO JSON requirements:`,
+        `- stage_key must be "${stage_key}"`,
+        `- status must be "ok" | "blocked" | "failed"`,
+        `- include summary + next_actions`,
+        `- include files/evidence paths when relevant`,
+        ``,
+        `If blocked: ask exactly ONE question and stop.`,
+        ``,
+        `Context snapshot:`,
+        context_snapshot_md.trim(),
+    ].join("\n")), config.context_compaction.inject_max_chars);
+    return {
+        kind: "stage",
+        title: `ASTROCODE — STAGE_${stageKeyUpper}`,
+        body,
+        hash: directiveHash(body),
+    };
+}

package/dist/workflow/repair.d.ts

@@ -0,0 +1,8 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+export type RepairReport = {
+    actions: string[];
+    warnings: string[];
+};
+export declare function repairState(db: SqliteDb, config: AstrocodeConfig): RepairReport;
+export declare function formatRepairReport(report: RepairReport): string;

package/dist/workflow/repair.js

@@ -0,0 +1,99 @@
+import { nowISO } from "../shared/time";
+import { newEventId, newStageRunId } from "../state/ids";
+function push(report, line) {
+    report.actions.push(line);
+}
+function warn(report, line) {
+    report.warnings.push(line);
+}
+export function repairState(db, config) {
+    const report = { actions: [], warnings: [] };
+    const now = nowISO();
+    // 1) Multiple running runs -> abort extras (keep most recent started_at)
+    const running = db
+        .prepare("SELECT * FROM runs WHERE status='running' ORDER BY started_at DESC, created_at DESC")
+        .all();
+    if (running.length > 1) {
+        const keep = running[0];
+        for (const r of running.slice(1)) {
+            db.prepare("UPDATE runs SET status='aborted', error_text=?, completed_at=?, updated_at=? WHERE run_id=?").run("repair: multiple running runs", now, now, r.run_id);
+            // unlock story
+            db.prepare("UPDATE stories SET state='approved', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?").run(now, r.story_key);
+            db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, 'run.aborted', ?, ?)").run(newEventId(), r.run_id, JSON.stringify({ reason: "repair: multiple running runs" }), now);
+            push(report, `Aborted extra running run ${r.run_id} (kept ${keep.run_id})`);
+        }
+    }
+    // 2) Fix story locks for the active run
+    const active = db.prepare("SELECT * FROM runs WHERE status='running' ORDER BY started_at DESC LIMIT 1").get();
+    if (active) {
+        const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(active.story_key);
+        if (!story) {
+            warn(report, `Active run ${active.run_id} references missing story ${active.story_key}`);
+        }
+        else {
+            if (story.locked_by_run_id !== active.run_id || story.in_progress !== 1 || story.state !== "in_progress") {
+                db.prepare("UPDATE stories SET state='in_progress', in_progress=1, locked_by_run_id=?, locked_at=COALESCE(locked_at, ?), updated_at=? WHERE story_key=?").run(active.run_id, now, now, story.story_key);
+                push(report, `Repaired story lock for ${story.story_key} to run ${active.run_id}`);
+            }
+        }
+        // 3) Ensure stage_runs exist for pipeline
+        const pipeline = JSON.parse(active.pipeline_stages_json ?? "[]");
+        const stageRuns = db
+            .prepare("SELECT * FROM stage_runs WHERE run_id=? ORDER BY stage_index ASC")
+            .all(active.run_id);
+        if (stageRuns.length < pipeline.length) {
+            const existingKeys = new Set(stageRuns.map((s) => s.stage_key));
+            const insert = db.prepare("INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, updated_at) VALUES (?, ?, ?, ?, 'pending', ?)");
+            pipeline.forEach((key, idx) => {
+                if (!existingKeys.has(key)) {
+                    insert.run(newStageRunId(), active.run_id, key, idx, now);
+                    push(report, `Inserted missing stage_run ${key} for run ${active.run_id}`);
+                }
+            });
+        }
+        // 4) If current_stage_key missing, set to first incomplete
+        const refreshed = db
+            .prepare("SELECT * FROM stage_runs WHERE run_id=? ORDER BY stage_index ASC")
+            .all(active.run_id);
+        const cur = refreshed.find((s) => s.status !== "completed" && s.status !== "skipped");
+        if (cur && active.current_stage_key !== cur.stage_key) {
+            db.prepare("UPDATE runs SET current_stage_key=?, updated_at=? WHERE run_id=?").run(cur.stage_key, now, active.run_id);
+            push(report, `Set run.current_stage_key to ${cur.stage_key} for ${active.run_id}`);
+        }
+    }
+    // 5) Orphaned story locks (in_progress=1 but no running run)
+    const lockedStories = db
+        .prepare("SELECT * FROM stories WHERE in_progress=1")
+        .all();
+    for (const s of lockedStories) {
+        const run = s.locked_by_run_id
+            ? db.prepare("SELECT * FROM runs WHERE run_id=?").get(s.locked_by_run_id)
+            : undefined;
+        if (!run || run.status !== "running") {
+            db.prepare("UPDATE stories SET in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?").run(now, s.story_key);
+            // Keep state conservative: if it was in_progress but no run, revert to approved.
+            db.prepare("UPDATE stories SET state='approved', updated_at=? WHERE story_key=? AND state='in_progress'").run(now, s.story_key);
+            push(report, `Cleared orphaned lock on story ${s.story_key}`);
+        }
+    }
+    if (!report.actions.length && !report.warnings.length) {
+        report.actions.push("No repairs needed.");
+    }
+    // Event marker
+    db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, NULL, NULL, 'repair.completed', ?, ?)").run(newEventId(), JSON.stringify({ actions: report.actions, warnings: report.warnings, schema: config.db.schema_version_required }), now);
+    return report;
+}
+export function formatRepairReport(report) {
+    const lines = [];
+    lines.push("# Astrocode repair report");
+    lines.push("");
+    lines.push("## Actions");
+    for (const a of report.actions)
+        lines.push(`- ${a}`);
+    if (report.warnings.length) {
+        lines.push("", "## Warnings");
+        for (const w of report.warnings)
+            lines.push(`- ${w}`);
+    }
+    return lines.join("\n").trim();
+}

package/dist/workflow/state-machine.d.ts

@@ -0,0 +1,43 @@
+import type { AstrocodeConfig } from "../config/schema";
+import type { SqliteDb } from "../state/db";
+import type { RunRow, StageKey, StageRunRow, StoryRow } from "../state/types";
+export type NextAction = {
+    kind: "idle";
+    reason: "no_approved_stories";
+} | {
+    kind: "start_run";
+    story_key: string;
+} | {
+    kind: "delegate_stage";
+    run_id: string;
+    stage_key: StageKey;
+    stage_run_id: string;
+} | {
+    kind: "await_stage_completion";
+    run_id: string;
+    stage_key: StageKey;
+    stage_run_id: string;
+} | {
+    kind: "complete_run";
+    run_id: string;
+} | {
+    kind: "failed";
+    run_id: string;
+    stage_key: StageKey;
+    error_text: string;
+};
+export declare function getActiveRun(db: SqliteDb): RunRow | null;
+export declare function getStory(db: SqliteDb, storyKey: string): StoryRow | null;
+export declare function getStageRuns(db: SqliteDb, runId: string): StageRunRow[];
+export declare function getCurrentStageRun(stageRuns: StageRunRow[]): StageRunRow | null;
+export declare function decideNextAction(db: SqliteDb, config: AstrocodeConfig): NextAction;
+export declare function createRunForStory(db: SqliteDb, config: AstrocodeConfig, storyKey: string): {
+    run_id: string;
+};
+export declare function startStage(db: SqliteDb, runId: string, stageKey: StageKey, meta?: {
+    subagent_type?: string;
+    subagent_session_id?: string;
+}): void;
+export declare function completeRun(db: SqliteDb, runId: string): void;
+export declare function failRun(db: SqliteDb, runId: string, stageKey: StageKey, errorText: string): void;
+export declare function abortRun(db: SqliteDb, runId: string, reason: string): void;

package/dist/workflow/state-machine.js

@@ -0,0 +1,127 @@
+import { nowISO } from "../shared/time";
+import { newEventId, newRunId, newStageRunId } from "../state/ids";
+import { warn } from "../shared/log";
+export function getActiveRun(db) {
+    const row = db
+        .prepare("SELECT * FROM runs WHERE status = 'running' ORDER BY started_at DESC, created_at DESC LIMIT 1")
+        .get();
+    return row ?? null;
+}
+export function getStory(db, storyKey) {
+    const row = db.prepare("SELECT * FROM stories WHERE story_key = ?").get(storyKey);
+    return row ?? null;
+}
+export function getStageRuns(db, runId) {
+    return db.prepare("SELECT * FROM stage_runs WHERE run_id = ? ORDER BY stage_index ASC").all(runId);
+}
+export function getCurrentStageRun(stageRuns) {
+    const cur = stageRuns.find((s) => s.status !== "completed" && s.status !== "skipped");
+    return cur ?? null;
+}
+export function decideNextAction(db, config) {
+    const activeRun = getActiveRun(db);
+    if (!activeRun) {
+        const story = db
+            .prepare("SELECT * FROM stories WHERE state = 'approved' AND (locked_by_run_id IS NULL) ORDER BY priority DESC, approved_at ASC, created_at ASC LIMIT 1")
+            .get();
+        if (!story)
+            return { kind: "idle", reason: "no_approved_stories" };
+        return { kind: "start_run", story_key: story.story_key };
+    }
+    const stageRuns = getStageRuns(db, activeRun.run_id);
+    const current = getCurrentStageRun(stageRuns);
+    if (!current) {
+        return { kind: "complete_run", run_id: activeRun.run_id };
+    }
+    if (current.status === "pending") {
+        return { kind: "delegate_stage", run_id: activeRun.run_id, stage_key: current.stage_key, stage_run_id: current.stage_run_id };
+    }
+    if (current.status === "running") {
+        return { kind: "await_stage_completion", run_id: activeRun.run_id, stage_key: current.stage_key, stage_run_id: current.stage_run_id };
+    }
+    if (current.status === "failed") {
+        return { kind: "failed", run_id: activeRun.run_id, stage_key: current.stage_key, error_text: current.error_text ?? "stage failed" };
+    }
+    // Should never happen: other statuses are handled above
+    warn("Unexpected stage status in decideNextAction", { status: current.status, stage_key: current.stage_key });
+    return { kind: "await_stage_completion", run_id: activeRun.run_id, stage_key: current.stage_key, stage_run_id: current.stage_run_id };
+}
+export function createRunForStory(db, config, storyKey) {
+    const story = getStory(db, storyKey);
+    if (!story)
+        throw new Error(`Story not found: ${storyKey}`);
+    if (story.state !== "approved")
+        throw new Error(`Story must be approved to run: ${storyKey} (state=${story.state})`);
+    const run_id = newRunId();
+    const now = nowISO();
+    const pipeline = config.workflow.pipeline;
+    // Lock story
+    db.prepare("UPDATE stories SET state='in_progress', in_progress=1, locked_by_run_id=?, locked_at=?, updated_at=? WHERE story_key=?").run(run_id, now, now, storyKey);
+    db.prepare("INSERT INTO runs (run_id, story_key, status, pipeline_stages_json, current_stage_key, created_at, started_at, updated_at) VALUES (?, ?, 'running', ?, ?, ?, ?, ?)").run(run_id, storyKey, JSON.stringify(pipeline), pipeline[0] ?? null, now, now, now);
+    // Stage runs
+    const insertStage = db.prepare("INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, updated_at) VALUES (?, ?, ?, ?, 'pending', ?)");
+    pipeline.forEach((stageKey, idx) => {
+        insertStage.run(newStageRunId(), run_id, stageKey, idx, now);
+    });
+    // Event
+    db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, 'run.started', ?, ?)").run(newEventId(), run_id, JSON.stringify({ story_key: storyKey, pipeline }), now);
+    db.prepare("UPDATE repo_state SET last_run_id=?, last_story_key=?, last_event_at=?, updated_at=? WHERE id=1").run(run_id, storyKey, now, now);
+    return { run_id };
+}
+export function startStage(db, runId, stageKey, meta) {
+    const now = nowISO();
+    // Ensure run is running
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
+    if (!run)
+        throw new Error(`Run not found: ${runId}`);
+    if (run.status !== "running")
+        throw new Error(`Run is not running: ${runId} (status=${run.status})`);
+    const stage = db
+        .prepare("SELECT * FROM stage_runs WHERE run_id=? AND stage_key=?")
+        .get(runId, stageKey);
+    if (!stage)
+        throw new Error(`Stage run not found: ${runId}/${stageKey}`);
+    if (stage.status !== "pending")
+        throw new Error(`Stage is not pending: ${stageKey} (status=${stage.status})`);
+    db.prepare("UPDATE stage_runs SET status='running', started_at=?, updated_at=?, subagent_type=COALESCE(?, subagent_type), subagent_session_id=COALESCE(?, subagent_session_id) WHERE stage_run_id=?").run(now, now, meta?.subagent_type ?? null, meta?.subagent_session_id ?? null, stage.stage_run_id);
+    db.prepare("UPDATE runs SET current_stage_key=?, updated_at=? WHERE run_id=?").run(stageKey, now, runId);
+    db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, 'stage.started', ?, ?)").run(newEventId(), runId, stageKey, JSON.stringify({ subagent_type: meta?.subagent_type ?? null }), now);
+}
+export function completeRun(db, runId) {
+    const now = nowISO();
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
+    if (!run)
+        throw new Error(`Run not found: ${runId}`);
+    if (run.status !== "running")
+        throw new Error(`Run not running: ${runId} (status=${run.status})`);
+    // Ensure all stages completed/skipped
+    const stageRuns = getStageRuns(db, runId);
+    const incomplete = stageRuns.find((s) => s.status !== "completed" && s.status !== "skipped");
+    if (incomplete)
+        throw new Error(`Cannot complete run: stage ${incomplete.stage_key} is ${incomplete.status}`);
+    db.prepare("UPDATE runs SET status='completed', completed_at=?, updated_at=?, current_stage_key=NULL WHERE run_id=?").run(now, now, runId);
+    db.prepare("UPDATE stories SET state='done', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?").run(now, run.story_key);
+    db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, 'run.completed', ?, ?)").run(newEventId(), runId, JSON.stringify({ story_key: run.story_key }), now);
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+}
+export function failRun(db, runId, stageKey, errorText) {
+    const now = nowISO();
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
+    if (!run)
+        throw new Error(`Run not found: ${runId}`);
+    db.prepare("UPDATE runs SET status='failed', error_text=?, updated_at=?, completed_at=? WHERE run_id=?").run(errorText, now, now, runId);
+    db.prepare("UPDATE stories SET state='blocked', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?").run(now, run.story_key);
+    db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, ?, 'run.failed', ?, ?)").run(newEventId(), runId, stageKey, JSON.stringify({ error_text: errorText }), now);
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+}
+export function abortRun(db, runId, reason) {
+    const now = nowISO();
+    const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(runId);
+    if (!run)
+        throw new Error(`Run not found: ${runId}`);
+    db.prepare("UPDATE runs SET status='aborted', error_text=?, updated_at=?, completed_at=? WHERE run_id=?").run(reason, now, now, runId);
+    // Unlock story back to approved so it can be re-run.
+    db.prepare("UPDATE stories SET state='approved', in_progress=0, locked_by_run_id=NULL, locked_at=NULL, updated_at=? WHERE story_key=?").run(now, run.story_key);
+    db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, 'run.aborted', ?, ?)").run(newEventId(), runId, JSON.stringify({ reason }), now);
+    db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+}

package/dist/workflow/story-helpers.d.ts

@@ -0,0 +1,9 @@
+import type { SqliteDb } from "../state/db";
+export declare function nextStoryKey(db: SqliteDb): string;
+export declare function insertStory(db: SqliteDb, opts: {
+    title: string;
+    body_md?: string;
+    priority?: number;
+    epic_key?: string | null;
+    state?: string;
+}): string;

package/dist/workflow/story-helpers.js

@@ -0,0 +1,13 @@
+import { nowISO } from "../shared/time";
+export function nextStoryKey(db) {
+    const row = db.prepare("SELECT next_story_num FROM story_keyseq WHERE id=1").get();
+    const n = row?.next_story_num ?? 1;
+    db.prepare("UPDATE story_keyseq SET next_story_num=? WHERE id=1").run(n + 1);
+    return `S-${String(n).padStart(4, "0")}`;
+}
+export function insertStory(db, opts) {
+    const now = nowISO();
+    const key = nextStoryKey(db);
+    db.prepare("INSERT INTO stories (story_key, epic_key, title, body_md, state, priority, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)").run(key, opts.epic_key ?? null, opts.title, opts.body_md ?? "", opts.state ?? "queued", opts.priority ?? 0, now, now);
+    return key;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "astrocode-workflow",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.1.19",
+    "@opencode-ai/sdk": "^1.1.19",
+    "jsonc-parser": "^3.2.0",
+    "zod": "4.1.8"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.6.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^20.12.12",
+    "typescript": "^5.6.3"
+  }
+}