astrocode-workflow 0.3.0 → 0.3.2

package/dist/src/workflow/artifacts.d.ts

@@ -0,0 +1,24 @@
+import type { SqliteDb } from "../state/db";
+export type ArtifactType = "baton" | "summary" | "evidence" | "diff" | "log" | "commit" | "tool_output" | "snapshot" | "spec";
+export type PutArtifactOpts = {
+    repoRoot: string;
+    db: SqliteDb;
+    run_id?: string | null;
+    stage_key?: string | null;
+    type: ArtifactType | string;
+    rel_path: string;
+    content: string | Buffer;
+    meta?: Record<string, unknown>;
+};
+export declare function writeFileSafe(repoRoot: string, relPath: string, content: string | Buffer): void;
+export declare function putArtifact(opts: PutArtifactOpts): {
+    artifact_id: string;
+    sha256: string;
+    abs_path: string;
+};
+export declare function listArtifacts(db: SqliteDb, filters?: {
+    run_id?: string;
+    stage_key?: string;
+    type?: string;
+}): any[];
+export declare function getArtifact(db: SqliteDb, artifact_id: string): any | null;

package/dist/src/workflow/artifacts.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+import { newArtifactId } from "../state/ids";
+import { nowISO } from "../shared/time";
+import { sha256Hex } from "../shared/hash";
+import { assertInsideAstro, ensureDir, toPosix } from "../shared/paths";
+export function writeFileSafe(repoRoot, relPath, content) {
+    const abs = path.join(repoRoot, relPath);
+    assertInsideAstro(repoRoot, abs);
+    ensureDir(path.dirname(abs));
+    fs.writeFileSync(abs, content);
+}
+export function putArtifact(opts) {
+    const { repoRoot, db, run_id = null, stage_key = null, type, rel_path, content } = opts;
+    const artifact_id = newArtifactId();
+    const abs_path = path.join(repoRoot, rel_path);
+    writeFileSafe(repoRoot, rel_path, content);
+    const sha256 = sha256Hex(content instanceof Buffer ? content : Buffer.from(content, "utf-8"));
+    const created_at = nowISO();
+    const meta_json = JSON.stringify(opts.meta ?? {});
+    db.prepare("INSERT INTO artifacts (artifact_id, run_id, stage_key, type, path, sha256, meta_json, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)").run(artifact_id, run_id, stage_key, type, toPosix(rel_path), sha256, meta_json, created_at);
+    return { artifact_id, sha256, abs_path };
+}
+export function listArtifacts(db, filters) {
+    const where = [];
+    const params = [];
+    if (filters?.run_id) {
+        where.push("run_id = ?");
+        params.push(filters.run_id);
+    }
+    if (filters?.stage_key) {
+        where.push("stage_key = ?");
+        params.push(filters.stage_key);
+    }
+    if (filters?.type) {
+        where.push("type = ?");
+        params.push(filters.type);
+    }
+    const sql = `SELECT * FROM artifacts ${where.length ? "WHERE " + where.join(" AND ") : ""} ORDER BY created_at DESC LIMIT 200`;
+    return db.prepare(sql).all(...params);
+}
+export function getArtifact(db, artifact_id) {
+    const row = db.prepare("SELECT * FROM artifacts WHERE artifact_id = ?").get(artifact_id);
+    return row ?? null;
+}

package/dist/src/workflow/baton.d.ts

@@ -0,0 +1,72 @@
+import type { AstrocodeConfig } from "../config/schema";
+import { z } from "zod";
+export declare const ASTRO_JSON_BEGIN = "<!-- ASTRO_JSON_BEGIN -->";
+export declare const ASTRO_JSON_END = "<!-- ASTRO_JSON_END -->";
+export declare const StageKeySchema: z.ZodEnum<{
+    frame: "frame";
+    plan: "plan";
+    spec: "spec";
+    implement: "implement";
+    review: "review";
+    verify: "verify";
+    close: "close";
+}>;
+export declare const AstroJsonSchema: z.ZodObject<{
+    schema_version: z.ZodDefault<z.ZodNumber>;
+    run_id: z.ZodOptional<z.ZodString>;
+    story_key: z.ZodOptional<z.ZodString>;
+    stage_key: z.ZodEnum<{
+        frame: "frame";
+        plan: "plan";
+        spec: "spec";
+        implement: "implement";
+        review: "review";
+        verify: "verify";
+        close: "close";
+    }>;
+    status: z.ZodDefault<z.ZodEnum<{
+        blocked: "blocked";
+        failed: "failed";
+        ok: "ok";
+    }>>;
+    summary: z.ZodDefault<z.ZodString>;
+    decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    next_actions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tasks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        complexity: z.ZodOptional<z.ZodNumber>;
+        subtasks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodDefault<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodDefault<z.ZodString>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    new_stories: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        body_md: z.ZodOptional<z.ZodString>;
+        priority: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    questions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    metrics: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
+}, z.core.$strip>;
+export type AstroJson = z.infer<typeof AstroJsonSchema>;
+export type ParsedStageOutput = {
+    baton_md: string;
+    astro_json: AstroJson | null;
+    astro_json_raw: string | null;
+    error: string | null;
+};
+export declare function parseStageOutputText(text: string): ParsedStageOutput;
+export declare function buildBatonSummary(opts: {
+    config: AstrocodeConfig;
+    stage_key: string;
+    astro_json: AstroJson | null;
+    baton_md: string;
+}): string;

package/dist/src/workflow/baton.js

@@ -0,0 +1,166 @@
+import { clampLines, normalizeNewlines, stripCodeFences } from "../shared/text";
+import { z, ZodError } 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([]),
+    tasks: z.array(z.object({
+        title: z.string(),
+        description: z.string().optional(),
+        complexity: z.number().int().min(1).max(10).optional(),
+        subtasks: z.array(z.string()).optional(),
+    })).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);
+    let baton_md = "";
+    let jsonRaw = "";
+    let fallbackUsed = false;
+    if (beginIdx === -1 || endIdx === -1 || endIdx <= beginIdx) {
+        // Enhanced fallback: scan for any JSON object in the text
+        const jsonMatch = norm.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            try {
+                const parsed = JSON.parse(jsonMatch[0]);
+                const astroJson = AstroJsonSchema.parse(parsed);
+                return {
+                    baton_md: norm.replace(jsonMatch[0], "").trim(),
+                    astro_json: astroJson,
+                    astro_json_raw: jsonMatch[0],
+                    error: null
+                };
+            }
+            catch (e) {
+                // JSON found but invalid, continue to marker error
+            }
+        }
+        // Fallback: if no markers, check if the entire text is JSON
+        try {
+            const parsed = JSON.parse(norm);
+            const astroJson = AstroJsonSchema.parse(parsed);
+            return {
+                baton_md: "",
+                astro_json: astroJson,
+                astro_json_raw: norm,
+                error: null
+            };
+        }
+        catch (e) {
+            // Not JSON, proceed with marker error
+        }
+        // If no JSON found, create a default structure from the text
+        const defaultJson = {
+            schema_version: 1,
+            stage_key: "frame", // Default, will be overridden by actual stage_key
+            status: "ok",
+            summary: norm.trim() || "Stage completed without structured output",
+            decisions: [],
+            next_actions: [],
+            tasks: [],
+            files: [],
+            evidence: [],
+            new_stories: [],
+            questions: [],
+            metrics: {}
+        };
+        return {
+            baton_md: "",
+            astro_json: defaultJson,
+            astro_json_raw: JSON.stringify(defaultJson, null, 2),
+            error: null
+        };
+    }
+    const before = norm.slice(0, beginIdx).trim();
+    jsonRaw = norm.slice(beginIdx + ASTRO_JSON_BEGIN.length, endIdx).trim();
+    const after = norm.slice(endIdx + ASTRO_JSON_END.length).trim();
+    baton_md = [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, astro_json: astroJson, astro_json_raw: cleaned, error: null };
+    }
+    catch (e) {
+        if (e instanceof ZodError) {
+            return {
+                baton_md,
+                astro_json: null,
+                astro_json_raw: jsonRaw,
+                error: `Schema validation failed: ${e.message}. Ensure JSON conforms to ASTRO schema with required fields like stage_key, status, etc.`,
+            };
+        }
+        else {
+            return {
+                baton_md: norm,
+                astro_json: null,
+                astro_json_raw: null,
+                error: `JSON parsing failed: ${String(e)}. Ensure valid JSON syntax between ${ASTRO_JSON_BEGIN} and ${ASTRO_JSON_END} markers.`,
+            };
+        }
+    }
+}
+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/src/workflow/context.d.ts

@@ -0,0 +1,20 @@
+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[];
+/**
+ * Check if a context snapshot is stale by comparing DB timestamps
+ */
+export declare function isContextSnapshotStale(snapshotText: string, db: SqliteDb, maxAgeSeconds?: number): boolean;
+/**
+ * Add staleness indicator to context snapshot if needed
+ */
+export declare function addStalenessIndicator(snapshotText: string, db: SqliteDb, maxAgeSeconds?: number): string;
+export declare function buildContextSnapshot(opts: {
+    db: SqliteDb;
+    config: AstrocodeConfig;
+    run_id: string;
+    next_action?: string;
+}): string;

package/dist/src/workflow/context.js

@@ -0,0 +1,113 @@
+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 "⬜";
+    }
+}
+/**
+ * Check if a context snapshot is stale by comparing DB timestamps
+ */
+export function isContextSnapshotStale(snapshotText, db, maxAgeSeconds = 300) {
+    // Extract run_id from snapshot
+    const runIdMatch = snapshotText.match(/Run: `([^`]+)`/);
+    if (!runIdMatch)
+        return true; // Can't validate without run_id
+    const runId = runIdMatch[1];
+    // Extract snapshot's claimed updated_at
+    const snapshotUpdatedMatch = snapshotText.match(/updated: ([^\)]+)\)/);
+    if (!snapshotUpdatedMatch)
+        return true; // Fallback to age-based check
+    try {
+        const snapshotUpdatedAt = snapshotUpdatedMatch[1];
+        const currentRun = db.prepare("SELECT updated_at FROM runs WHERE run_id = ?").get(runId);
+        if (!currentRun?.updated_at)
+            return true; // Run doesn't exist
+        // Compare timestamps - if DB is newer than snapshot claims, snapshot is stale
+        const snapshotTime = new Date(snapshotUpdatedAt).getTime();
+        const currentTime = new Date(currentRun.updated_at).getTime();
+        return currentTime > snapshotTime;
+    }
+    catch (error) {
+        // Fallback to age-based staleness if parsing fails
+        const timestampMatch = snapshotText.match(/generated: (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)/);
+        if (!timestampMatch)
+            return false;
+        const generatedAt = new Date(timestampMatch[1]);
+        const now = new Date();
+        const ageSeconds = (now.getTime() - generatedAt.getTime()) / 1000;
+        return ageSeconds > maxAgeSeconds;
+    }
+}
+/**
+ * Add staleness indicator to context snapshot if needed
+ */
+export function addStalenessIndicator(snapshotText, db, maxAgeSeconds = 300) {
+    if (isContextSnapshotStale(snapshotText, db, maxAgeSeconds)) {
+        return snapshotText.replace(/# Astrocode Context \(generated: ([^\)]+)\)/, "# Astrocode Context (generated: $1) ⚠️ STALE - DB state has changed");
+    }
+    return snapshotText;
+}
+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 = [];
+    // Add timestamps for staleness checking
+    const now = new Date();
+    const timestamp = now.toISOString();
+    lines.push(`# Astrocode Context (generated: ${timestamp})`);
+    lines.push(`- Run: \`${run.run_id}\`  Status: **${run.status}** (updated: ${run.updated_at})`);
+    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/src/workflow/directives.d.ts

@@ -0,0 +1,39 @@
+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: {
+    config?: AstrocodeConfig;
+    run_id: string;
+    stage_key: string;
+    question: string;
+    context_snapshot_md: string;
+}): BuiltDirective;
+export declare function buildRepairDirective(opts: {
+    config?: AstrocodeConfig;
+    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/src/workflow/directives.js

@@ -0,0 +1,137 @@
+import { sha256Hex } from "../shared/hash";
+import { clampChars, normalizeNewlines } from "../shared/text";
+function getInjectMaxChars(config) {
+    // Deterministic fallback for older configs.
+    const v = config?.context_compaction?.inject_max_chars;
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 12000;
+}
+export function directiveHash(body) {
+    // Stable hash to dedupe: normalize newlines + trim
+    const norm = normalizeNewlines(body).trim();
+    return sha256Hex(norm);
+}
+function finalizeBody(body, maxChars) {
+    // Normalize first, clamp second, trim last => hash/body match exactly.
+    const norm = normalizeNewlines(body);
+    const clamped = clampChars(norm, maxChars);
+    return clamped.trim();
+}
+export function buildContinueDirective(opts) {
+    const { config, run_id, stage_key, next_action, context_snapshot_md } = opts;
+    const maxChars = getInjectMaxChars(config);
+    const body = finalizeBody([
+        `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`,
+        ``,
+        `This directive is injected by the Astro agent to continue the workflow.`,
+        ``,
+        `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"), maxChars);
+    return {
+        kind: "continue",
+        title: "ASTROCODE — CONTINUE",
+        body,
+        hash: directiveHash(body),
+    };
+}
+export function buildBlockedDirective(opts) {
+    const { config, run_id, stage_key, question, context_snapshot_md } = opts;
+    const maxChars = getInjectMaxChars(config);
+    const body = finalizeBody([
+        `[SYSTEM DIRECTIVE: ASTROCODE — BLOCKED]`,
+        ``,
+        `This directive is injected by the Astro agent indicating the workflow is 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"), maxChars);
+    return {
+        kind: "blocked",
+        title: "ASTROCODE — BLOCKED",
+        body,
+        hash: directiveHash(body),
+    };
+}
+export function buildRepairDirective(opts) {
+    const maxChars = getInjectMaxChars(opts.config);
+    const body = finalizeBody([
+        `[SYSTEM DIRECTIVE: ASTROCODE — REPAIR]`,
+        ``,
+        `This directive is injected by the Astro agent after performing a repair pass.`,
+        ``,
+        `Astrocode performed a repair pass. Summarize in <= 10 lines and continue.`,
+        ``,
+        `Repair report:`,
+        (opts.report_md ?? "").trim(),
+    ].join("\n"), maxChars);
+    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 maxChars = getInjectMaxChars(config);
+    const stageKeyUpper = String(stage_key).toUpperCase();
+    const constraintsBlock = Array.isArray(stage_constraints) && stage_constraints.length
+        ? ["", "Constraints:", ...stage_constraints.map((c) => `- ${c}`)].join("\n")
+        : "";
+    const body = finalizeBody([
+        `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_${stageKeyUpper}]`,
+        ``,
+        `This directive is injected by the Astro agent to delegate the stage task.`,
+        ``,
+        `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 -->`,
+        `   {`,
+        `     "schema_version": 1,`,
+        `     "stage_key": "${stage_key}",`,
+        `     "status": "ok",`,
+        `     "...": "..."`,
+        `   }`,
+        `   <!-- 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"), maxChars);
+    return {
+        kind: "stage",
+        title: `ASTROCODE — STAGE_${stageKeyUpper}`,
+        body,
+        hash: directiveHash(body),
+    };
+}

package/dist/src/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;