astrocode-workflow 0.1.57 → 0.1.59

package/dist/workflow/directives.js

@@ -1,13 +1,25 @@
 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 body = clampChars(normalizeNewlines([
+    const maxChars = getInjectMaxChars(config);
+    const body = finalizeBody([
         `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`,
         ``,
         `This directive is injected by the Astro agent to continue the workflow.`,
@@ -22,8 +34,8 @@ export function buildContinueDirective(opts) {
         `- If blocked, ask exactly ONE question and stop.`,
         ``,
         `Context snapshot:`,
-        context_snapshot_md.trim(),
-    ].join("\n")), config.context_compaction.inject_max_chars);
+        (context_snapshot_md ?? "").trim(),
+    ].join("\n"), maxChars);
     return {
         kind: "continue",
         title: "ASTROCODE — CONTINUE",
@@ -32,8 +44,9 @@ export function buildContinueDirective(opts) {
     };
 }
 export function buildBlockedDirective(opts) {
-    const { run_id, stage_key, question, context_snapshot_md } = opts;
-    const body = normalizeNewlines([
+    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.`,
@@ -45,8 +58,8 @@ export function buildBlockedDirective(opts) {
         `Question: ${question}`,
         ``,
         `Context snapshot:`,
-        context_snapshot_md.trim(),
-    ].join("\n")).trim();
+        (context_snapshot_md ?? "").trim(),
+    ].join("\n"), maxChars);
     return {
         kind: "blocked",
         title: "ASTROCODE — BLOCKED",
@@ -55,7 +68,8 @@ export function buildBlockedDirective(opts) {
     };
 }
 export function buildRepairDirective(opts) {
-    const body = normalizeNewlines([
+    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.`,
@@ -63,8 +77,8 @@ export function buildRepairDirective(opts) {
         `Astrocode performed a repair pass. Summarize in <= 10 lines and continue.`,
         ``,
         `Repair report:`,
-        opts.report_md.trim(),
-    ].join("\n")).trim();
+        (opts.report_md ?? "").trim(),
+    ].join("\n"), maxChars);
     return {
         kind: "repair",
         title: "ASTROCODE — REPAIR",
@@ -73,12 +87,13 @@ export function buildRepairDirective(opts) {
     };
 }
 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
+    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 = clampChars(normalizeNewlines([
+    const body = finalizeBody([
         `[SYSTEM DIRECTIVE: ASTROCODE — STAGE_${stageKeyUpper}]`,
         ``,
         `This directive is injected by the Astro agent to delegate the stage task.`,
@@ -93,14 +108,14 @@ export function buildStageDirective(opts) {
         `Output contract (strict):`,
         `1) Baton markdown (short, structured)`,
         `2) ASTRO JSON between markers:`,
-        `   ${"<!-- ASTRO_JSON_BEGIN -->"}`,
+        `   <!-- ASTRO_JSON_BEGIN -->`,
         `   {`,
         `     "schema_version": 1,`,
         `     "stage_key": "${stage_key}",`,
         `     "status": "ok",`,
-        `     ...`,
+        `     "...": "..."`,
         `   }`,
-        `   ${"<!-- ASTRO_JSON_END -->"}`,
+        `   <!-- ASTRO_JSON_END -->`,
         ``,
         `ASTRO JSON requirements:`,
         `- stage_key must be "${stage_key}"`,
@@ -111,8 +126,8 @@ export function buildStageDirective(opts) {
         `If blocked: ask exactly ONE question and stop.`,
         ``,
         `Context snapshot:`,
-        context_snapshot_md.trim(),
-    ].join("\n")), config.context_compaction.inject_max_chars);
+        (context_snapshot_md ?? "").trim(),
+    ].join("\n"), maxChars);
     return {
         kind: "stage",
         title: `ASTROCODE — STAGE_${stageKeyUpper}`,

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

@@ -1,6 +1,33 @@
 import type { AstrocodeConfig } from "../config/schema";
 import type { SqliteDb } from "../state/db";
 import type { RunRow, StageKey, StageRunRow, StoryRow } from "../state/types";
+export declare const EVENT_TYPES: {
+    readonly RUN_STARTED: "run.started";
+    readonly RUN_COMPLETED: "run.completed";
+    readonly RUN_FAILED: "run.failed";
+    readonly RUN_ABORTED: "run.aborted";
+    readonly RUN_GENESIS_PLANNING_ATTACHED: "run.genesis_planning_attached";
+    readonly STAGE_STARTED: "stage.started";
+    readonly WORKFLOW_PROCEED: "workflow.proceed";
+};
+/**
+ * PLANNING-FIRST REDESIGN
+ * ----------------------
+ * Old behavior: mutate an approved story into a planning/decomposition instruction.
+ * New behavior: NEVER mutate story title/body.
+ *
+ * Planning-first is a run-scoped directive stored in `injects` (scope = run:<run_id>).
+ *
+ * Deterministic trigger (config-driven):
+ * - config.workflow.genesis_planning:
+ *    - "off"             => never attach directive
+ *    - "first_story_only"=> attach only when story_key === "S-0001"
+ *    - "always"          => attach for every run
+ *
+ * Contract: DB is already initialized before workflow is used:
+ * - schema tables exist
+ * - repo_state singleton row (id=1) exists
+ */
 export type NextAction = {
     kind: "idle";
     reason: "no_approved_stories";

package/dist/workflow/state-machine.js

@@ -1,6 +1,17 @@
+import { withTx } from "../state/db";
 import { nowISO } from "../shared/time";
 import { newEventId, newRunId, newStageRunId } from "../state/ids";
 import { warn } from "../shared/log";
+import { sha256Hex } from "../shared/hash";
+export const EVENT_TYPES = {
+    RUN_STARTED: "run.started",
+    RUN_COMPLETED: "run.completed",
+    RUN_FAILED: "run.failed",
+    RUN_ABORTED: "run.aborted",
+    RUN_GENESIS_PLANNING_ATTACHED: "run.genesis_planning_attached",
+    STAGE_STARTED: "stage.started",
+    WORKFLOW_PROCEED: "workflow.proceed",
+};
 export function getActiveRun(db) {
     const row = db
         .prepare("SELECT * FROM runs WHERE status = 'running' ORDER BY started_at DESC, created_at DESC LIMIT 1")
@@ -30,9 +41,8 @@ export function decideNextAction(db, config) {
     }
     const stageRuns = getStageRuns(db, activeRun.run_id);
     const current = getCurrentStageRun(stageRuns);
-    if (!current) {
+    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 };
     }
@@ -42,103 +52,174 @@ export function decideNextAction(db, config) {
     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 };
 }
-function isInitialStory(db, storyKey) {
-    // Check if this story has no parent relations (is top-level)
-    const relations = db.prepare("SELECT COUNT(*) as count FROM story_relations WHERE child_story_key=?").get(storyKey);
-    return relations.count === 0;
+function getPipelineFromConfig(config) {
+    const pipeline = config?.workflow?.pipeline;
+    if (!Array.isArray(pipeline) || pipeline.length === 0) {
+        throw new Error("Invalid config: workflow.pipeline must be a non-empty array of stage keys.");
+    }
+    return pipeline;
 }
-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();
+function getGenesisPlanningMode(config) {
+    const raw = config?.workflow?.genesis_planning;
+    if (raw === "off" || raw === "first_story_only" || raw === "always")
+        return raw;
+    if (raw != null)
+        warn(`Invalid workflow.genesis_planning config: ${String(raw)}. Using default "first_story_only".`);
+    return "first_story_only";
+}
+function shouldAttachPlanningDirective(config, story) {
+    const mode = getGenesisPlanningMode(config);
+    if (mode === "off")
+        return false;
+    if (mode === "always")
+        return true;
+    return story.story_key === "S-0001";
+}
+function attachRunPlanningDirective(db, runId, story, pipeline) {
     const now = nowISO();
-    const pipeline = config.workflow.pipeline;
-    // Convert to genesis planning story if needed
-    const isGenesisCandidate = storyKey === 'S-0001' || isInitialStory(db, storyKey) ||
-        (story.body_md && story.body_md.length > 100 &&
-            (story.title.toLowerCase().includes('implement') || story.body_md.toLowerCase().includes('implement')));
-    // Skip conversion if there are already many stories (spec already decomposed)
-    const existingStoriesCount = db.prepare("SELECT COUNT(*) as count FROM stories").get();
-    const alreadyDecomposed = existingStoriesCount.count > 10; // Arbitrary threshold
-    if (isGenesisCandidate && !alreadyDecomposed) {
-        const planningTitle = `Plan and decompose: ${story.title}`;
-        const planningBody = `Analyze the requirements and break down "${story.title}" into 50-200 detailed, granular implementation stories. Each story should be focused on a specific, implementable task with clear acceptance criteria.\n\nOriginal request: ${story.body_md || ''}`;
-        db.prepare("UPDATE stories SET title=?, body_md=? WHERE story_key=?").run(planningTitle, planningBody, storyKey);
+    const injectId = `inj_${runId}_genesis_plan`;
+    const body = [
+        `# Genesis planning directive`,
+        ``,
+        `This run is configured to perform a planning/decomposition pass before implementation.`,
+        `Do not edit the origin story title/body. Create additional stories instead.`,
+        ``,
+        `## Required output`,
+        `- Produce 50–200 granular implementation stories with clear acceptance criteria.`,
+        `- Each story: single focused change, explicit done conditions, dependencies listed.`,
+        ``,
+        `## Context`,
+        `- Origin story: ${story.story_key} — ${story.title ?? ""}`,
+        `- Pipeline: ${pipeline.join(" → ")}`,
+        ``,
+    ].join("\n");
+    let hash = null;
+    try {
+        hash = sha256Hex(body);
+    }
+    catch {
+        // Hash is optional; directive must never be blocked by hashing.
+        hash = null;
     }
-    // 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);
+    try {
+        // Do not clobber user edits. If it exists, we leave it.
+        db.prepare(`
+      INSERT OR IGNORE INTO injects (
+        inject_id, type, title, body_md, tags_json, scope, source, priority,
+        expires_at, sha256, created_at, updated_at
+      ) VALUES (
+        ?, 'note', ?, ?, '["genesis","planning","decompose"]', ?, 'tool', 100,
+        NULL, ?, ?, ?
+      )
+    `).run(injectId, "Genesis planning: decompose into stories", body, `run:${runId}`, hash, now, now);
+        db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, ?, ?, ?)").run(newEventId(), runId, EVENT_TYPES.RUN_GENESIS_PLANNING_ATTACHED, JSON.stringify({ story_key: story.story_key, inject_id: injectId }), now);
+    }
+    catch (e) {
+        // Helpful, never required for correctness.
+        warn("Failed to attach genesis planning inject", { run_id: runId, story_key: story.story_key, err: e });
+    }
+}
+function updateRepoStateLastEvent(db, now, fields) {
+    // Contract: repo_state row exists. If not, fail deterministically (don’t “bootstrap” here).
+    const res = db
+        .prepare(`
+      UPDATE repo_state
+      SET last_run_id = COALESCE(?, last_run_id),
+          last_story_key = COALESCE(?, last_story_key),
+          last_event_at = ?,
+          updated_at = ?
+      WHERE id = 1
+    `)
+        .run(fields.last_run_id ?? null, fields.last_story_key ?? null, now, now);
+    if (!res || res.changes === 0) {
+        throw new Error("repo_state missing (id=1). Database not initialized; run init must be performed before workflow.");
+    }
+}
+export function createRunForStory(db, config, storyKey) {
+    return withTx(db, () => {
+        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 = getPipelineFromConfig(config);
+        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);
+        const insertStage = db.prepare("INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'pending', ?, ?)");
+        pipeline.forEach((stageKey, idx) => {
+            insertStage.run(newStageRunId(), run_id, stageKey, idx, now, now);
+        });
+        db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, ?, NULL, ?, ?, ?)").run(newEventId(), run_id, EVENT_TYPES.RUN_STARTED, JSON.stringify({ story_key: storyKey, pipeline }), now);
+        if (shouldAttachPlanningDirective(config, story)) {
+            attachRunPlanningDirective(db, run_id, story, pipeline);
+        }
+        updateRepoStateLastEvent(db, now, { last_run_id: run_id, last_story_key: storyKey });
+        return { run_id };
     });
-    // 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);
+    return withTx(db, () => {
+        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 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 (?, ?, ?, ?, ?, ?)").run(newEventId(), runId, stageKey, EVENT_TYPES.STAGE_STARTED, JSON.stringify({ subagent_type: meta?.subagent_type ?? null }), now);
+        updateRepoStateLastEvent(db, 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);
+    return withTx(db, () => {
+        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})`);
+        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(newEventId(), runId, EVENT_TYPES.RUN_COMPLETED, JSON.stringify({ story_key: run.story_key }), now);
+        updateRepoStateLastEvent(db, 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);
+    return withTx(db, () => {
+        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(newEventId(), runId, stageKey, EVENT_TYPES.RUN_FAILED, JSON.stringify({ error_text: errorText }), now);
+        updateRepoStateLastEvent(db, 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);
+    return withTx(db, () => {
+        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);
+        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(newEventId(), runId, EVENT_TYPES.RUN_ABORTED, JSON.stringify({ reason }), now);
+        updateRepoStateLastEvent(db, now, {});
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrocode-workflow",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/agents/prompts.ts

@@ -72,3 +72,163 @@ I analyzed the requirements and identified key components for implementation.
 
 If blocked, set status="blocked" and add ONE question to questions array. Do not deviate from this format.
 `;
+
+export const QA_AGENT_PROMPT = `🌍 Global Engineering Review Prompt (LOCKED)
+
+Use this prompt when reviewing any codebase.
+
+1️⃣ How every file review starts (MANDATORY)
+
+Before discussing details, always answer:
+
+Simple question this file answers
+
+What decision, contract, or responsibility does this file define?
+
+Things you have at the end of running this code
+
+What objects, capabilities, state, guarantees, or invariants now exist?
+
+If you can't answer these clearly, the file is already suspect.
+
+2️⃣ Canonical RULE set (GLOBAL ENGINEERING INVARIANTS)
+
+These are engineering physics laws.
+Every serious bug maps to one of these.
+No ad-hoc rules are allowed.
+
+enum RULE {
+  CAPABILITY_GUARANTEE =
+    "Expose a capability only when you can guarantee it will execute safely under current runtime conditions.",
+
+  RECOVERY_STRICTER =
+    "Recovery/degraded paths must be simpler and more conservative than the normal path, and must not introduce new failure modes.",
+
+  SOURCE_OF_TRUTH =
+    "For any piece of state, define exactly one authoritative source and explicit precedence rules for any mirrors, caches, or derivations.",
+
+  LIFECYCLE_DETERMINISM =
+    "Initialization and lifecycle must be deterministic: single construction, stable ordering, controlled side effects, and repeatable outcomes.",
+
+  SECURITY_BOUNDARIES =
+    "Security, authorization, and trust boundaries must be explicit, enforced, and never inferred implicitly."
+}
+
+If an issue does not violate one of these rules, it is not a P0/P1 blocker.
+
+3️⃣ Severity model (WHAT "P" MEANS)
+
+Severity is about trust, not annoyance.
+
+P0 — Trust break
+
+Unsafe execution
+
+Corrupted or ambiguous state
+
+Non-deterministic lifecycle
+
+Broken auditability / resumability
+
+Security boundary violations
+
+P1 — Reliability break
+
+Runtime crashes after successful boot
+
+Capabilities exposed but unusable
+
+Degraded mode that lies or half-works
+
+Recovery paths that add fragility
+
+P2 — Quality / polish
+
+Readability, ergonomics, maintainability
+
+No RULE violated
+
+4️⃣ Mandatory P0 / P1 Blocker Format (STRICT)
+
+Every P0 / P1 must be written exactly like this:
+
+P{0|1} — <short human title>
+
+Rule: RULE.<ONE_ENUM_VALUE>
+
+Description:
+A human-readable explanation of how this specific code violates the rule in context.
+This is situational and concrete — not a rule.
+
+What:
+The exact defect or unsafe behavior.
+
+Where:
+Precise file + function + construct / lines.
+
+Proposed fix:
+The smallest possible change that restores the rule.
+(Code snippets if helpful.)
+
+Why:
+How this fix restores the invariant and what class of failures it prevents.
+
+5️⃣ Recovery / Degraded Mode Lens (AUTO-APPLIED)
+
+Whenever code introduces:
+
+limited mode
+
+fallback
+
+catch-based recovery
+
+partial initialization
+
+Automatically evaluate against:
+
+RULE.RECOVERY_STRICTER
+
+RULE.CAPABILITY_GUARANTEE
+
+RULE.LIFECYCLE_DETERMINISM
+
+If recovery adds logic, validation, or ambiguity → it is a blocker.
+
+Recovery must:
+
+reduce capability surface
+
+fail earlier, not later
+
+be simpler than the normal path
+
+provide a clear path back to normal
+
+6️⃣ How to ask for the next file (TEACHING MODE)
+
+Before asking for the next file, always explain:
+
+What this next file likely does (human-readable)
+
+"This file takes X, registers it with Y, then enforces Z..."
+
+Why this file matters next
+
+Which RULE it is likely to uphold or violate, and why reviewing it now reduces risk.
+
+7️⃣ What this frame teaches over time
+
+After repeated use, you stop seeing "random bugs" and start seeing patterns:
+
+CAPABILITY_GUARANTEE violations (exposed but unsafe APIs)
+
+RECOVERY_STRICTER violations (clever fallbacks that explode)
+
+SOURCE_OF_TRUTH drift (DB vs disk vs memory)
+
+LIFECYCLE_DETERMINISM failures (double init, racey wiring)
+
+SECURITY_BOUNDARIES leaks (implicit trust)
+
+At that point, reviews become portable skills, not project-specific knowledge.`;