astrocode-workflow 0.1.58 → 0.2.0

package/dist/workflow/state-machine.js

@@ -1,6 +1,55 @@
+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";
+import { SCHEMA_VERSION } from "../state/schema";
+import { injectChatPrompt } from "../ui/inject";
+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",
+};
+async function emitUi(ui, text, toast) {
+    if (!ui)
+        return;
+    // Prefer toast (if provided) AND also inject chat (for audit trail / visibility).
+    // If you want toast-only, pass a toast function and omit ctx/sessionId.
+    if (toast && ui.toast) {
+        try {
+            await ui.toast(toast);
+        }
+        catch {
+            // non-fatal
+        }
+    }
+    try {
+        await injectChatPrompt({
+            ctx: ui.ctx,
+            sessionId: ui.sessionId,
+            text,
+            agent: ui.agentName ?? "Astro",
+        });
+    }
+    catch {
+        // non-fatal (workflow correctness is DB-based)
+    }
+}
+function tableExists(db, tableName) {
+    try {
+        const row = db
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+            .get(tableName);
+        return row?.name === tableName;
+    }
+    catch {
+        return false;
+    }
+}
 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 +79,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 +90,212 @@ 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 });
+    warn("Unexpected stage status in decideNextAction", { status: current.status, stage_key: current.status });
     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;
+    warn(`Invalid 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) {
+    if (!tableExists(db, "injects"))
+        return;
     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");
+    const hash = sha256Hex(body);
+    try {
+        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);
     }
-    // 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);
+    catch (e) {
+        warn("Failed to attach genesis planning inject", { run_id: runId, story_key: story.story_key, err: e });
+    }
+}
+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);
+        }
+        db.prepare(`
+      INSERT INTO repo_state (id, schema_version, created_at, updated_at, last_run_id, last_story_key, last_event_at)
+      VALUES (1, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        last_run_id=excluded.last_run_id,
+        last_story_key=excluded.last_story_key,
+        last_event_at=excluded.last_event_at,
+        updated_at=excluded.updated_at
+    `).run(SCHEMA_VERSION, now, now, run_id, storyKey, now);
+        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);
-}
-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);
+/**
+ * STAGE MOVEMENT (START) — now async so UI injection is deterministic.
+ */
+export async function startStage(db, runId, stageKey, meta) {
+    // Do DB work inside tx, capture what we need for UI outside.
+    const payload = 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);
+        db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+        const story = db.prepare("SELECT story_key, title FROM stories WHERE story_key=?").get(run.story_key);
+        return {
+            now,
+            story_key: run.story_key,
+            story_title: story?.title ?? "",
+        };
+    });
+    // Deterministic UI emission AFTER commit (never inside tx).
+    await emitUi(meta?.ui, [
+        `🟦 Stage started`,
+        `- Run: \`${runId}\``,
+        `- Stage: \`${stageKey}\``,
+        `- Story: \`${payload.story_key}\` — ${payload.story_title || "(untitled)"}`,
+    ].join("\n"), {
+        title: "Stage started",
+        message: `${stageKey} (${payload.story_key})`,
+        variant: "info",
+        durationMs: 2500,
+    });
+}
+/**
+ * STAGE CLOSED (RUN COMPLETED) — now async so UI injection is deterministic.
+ */
+export async function completeRun(db, runId, ui) {
+    const payload = 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);
+        db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+        const story = db.prepare("SELECT story_key, title FROM stories WHERE story_key=?").get(run.story_key);
+        return { now, story_key: run.story_key, story_title: story?.title ?? "" };
+    });
+    await emitUi(ui, [
+        `✅ Run completed`,
+        `- Run: \`${runId}\``,
+        `- Story: \`${payload.story_key}\` — ${payload.story_title || "(untitled)"}`,
+    ].join("\n"), {
+        title: "Run completed",
+        message: `${payload.story_key} — done`,
+        variant: "success",
+        durationMs: 3000,
+    });
+}
+/**
+ * STAGE CLOSED (RUN FAILED) — now async so UI injection is deterministic.
+ */
+export async function failRun(db, runId, stageKey, errorText, ui) {
+    const payload = 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);
+        db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+        const story = db.prepare("SELECT story_key, title FROM stories WHERE story_key=?").get(run.story_key);
+        return { now, story_key: run.story_key, story_title: story?.title ?? "" };
+    });
+    await emitUi(ui, [
+        `⛔ Run failed`,
+        `- Run: \`${runId}\``,
+        `- Stage: \`${stageKey}\``,
+        `- Story: \`${payload.story_key}\` — ${payload.story_title || "(untitled)"}`,
+        `- Error: ${errorText}`,
+    ].join("\n"), {
+        title: "Run failed",
+        message: `${stageKey}: ${errorText}`,
+        variant: "error",
+        durationMs: 4500,
+    });
 }
 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);
+        db.prepare("UPDATE repo_state SET last_event_at=?, updated_at=? WHERE id=1").run(now, now);
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrocode-workflow",
-  "version": "0.1.58",
+  "version": "0.2.0",
   "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.`;

package/src/agents/registry.ts

@@ -2,7 +2,7 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 import type { AstrocodeConfig } from "../config/schema";
 import { deepMerge } from "../shared/deep-merge";
 import { applyModelTuning } from "../shared/model-tuning";
-import { BASE_ORCH_PROMPT, BASE_STAGE_PROMPT } from "./prompts";
+import { BASE_ORCH_PROMPT, BASE_STAGE_PROMPT, QA_AGENT_PROMPT } from "./prompts";
 
 type PermissionValue = "ask" | "allow" | "deny";
 type PermissionMap = Record<string, PermissionValue>;
@@ -136,6 +136,7 @@ export function createAstroAgents(opts: {
       },
       librarian_name: "Librarian",
       explore_name: "Explore",
+      qa_name: "QA",
       agent_variant_overrides: {}
     };
   }
@@ -301,6 +302,20 @@ export function createAstroAgents(opts: {
     "utility"
   );
 
+  // QA agent for code review and verification
+  agents[pluginConfig.agents.qa_name] = mk(
+    pluginConfig.agents.qa_name,
+    {
+      description: "QA agent: Global engineering review with canonical rules and severity model.",
+      mode: "subagent",
+      hidden: false, // Make it visible for delegation
+      temperature: 0.1,
+      prompt: QA_AGENT_PROMPT,
+      permission: stageReadOnlyPermissions(), // Read-only for safety
+    },
+    "utility"
+  );
+
   // Fallback general agent for delegation failures
   agents["General"] = mk(
     "General",

package/src/config/loader.ts

@@ -5,6 +5,37 @@ import { AstrocodeConfigSchema, type AstrocodeConfig } from "./schema";
 import { deepMerge } from "../shared/deep-merge";
 import { info, warn } from "../shared/log";
 
+function validateJsonSerializable(obj: any, path = ""): void {
+  if (obj === null || obj === undefined) return;
+  if (typeof obj === "boolean" || typeof obj === "number" || typeof obj === "string") return;
+
+  if (typeof obj === "bigint") {
+    throw new Error(`Config contains non-JSON-serializable bigint at ${path}`);
+  }
+  if (typeof obj === "symbol") {
+    throw new Error(`Config contains non-JSON-serializable symbol at ${path}`);
+  }
+  if (typeof obj === "function") {
+    throw new Error(`Config contains non-JSON-serializable function at ${path}`);
+  }
+  if (obj instanceof Date) {
+    throw new Error(`Config contains non-JSON-serializable Date at ${path}`);
+  }
+  if (obj instanceof Map || obj instanceof Set) {
+    throw new Error(`Config contains non-JSON-serializable ${obj.constructor.name} at ${path}`);
+  }
+
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      validateJsonSerializable(obj[i], `${path}[${i}]`);
+    }
+  } else if (typeof obj === "object") {
+    for (const key of Object.keys(obj)) {
+      validateJsonSerializable(obj[key], path ? `${path}.${key}` : key);
+    }
+  }
+}
+
 export type ConfigFileDetection =
   | { format: "jsonc" | "json"; path: string }
   | { format: "none"; path: string };
@@ -46,10 +77,14 @@ export function loadAstrocodeConfig(repoRoot: string): AstrocodeConfig {
   if (legacyCfg) cfg = deepMerge(cfg, legacyCfg);
   if (projectCfg) cfg = deepMerge(cfg, projectCfg);
 
-  // Ensure the final config is fully validated with all required defaults
-  cfg = AstrocodeConfigSchema.parse(cfg);
+   // Ensure the final config is fully validated with all required defaults
+   cfg = AstrocodeConfigSchema.parse(cfg);
+
+   // CRITICAL CONTRACT: ensure config is JSON-serializable for recovery mode compatibility
+   // This prevents silent data corruption in cloneConfig's JSON fallback
+   validateJsonSerializable(cfg);
 
-  // Config loaded successfully (silent)
+   // Config loaded successfully (silent)
 
-  return cfg;
+   return cfg;
 }