astrocode-workflow 0.1.57 → 0.1.59

package/README.md

@@ -2,6 +2,22 @@
 
 Astrocode is a **DB-first, stage-gated agent harness** for OpenCode, rewritten in an **Oh-My-OpenCode–style plugin architecture**:
 
+## Design Goals & Non-Goals
+
+**Goals**:
+- Deterministic, stage-gated agent workflows
+- Durable SQLite ledger for auditability and resumability
+- Plugin architecture for extensibility
+- Visible continuation with safety rails
+
+**Non-Goals**:
+- General-purpose workflow engine (focused on agent work)
+- Full CI/CD replacement (no deployment pipelines)
+- Distributed runner support (single-machine only)
+- Real-time collaboration features
+
+Contributions should align with these goals.
+
 - TypeScript-first implementation in `src/`
 - OpenCode `config` handler registers **one primary agent** + hidden stage subagents
 - Hooks for **continuation**, **toasts**, and **tool-output truncation**
@@ -25,28 +41,223 @@ This repository is meant to be a clean starting point for Astrocode v2:
 - A **Baton** is a stage output artifact written to disk + recorded in DB (`artifacts` + `stage_runs.summary_md/output_json`).
 - **Continuation** is an explicit directive injected by hooks when a run is still active (`continuations` table).
 
-## Primary tools (high leverage)
+## Glossary & State Machine
+
+### Key Terms
+
+- **Story**: Backlog ticket representing work to be done
+- **Run**: Execution instance of a story (contains stages)
+- **Stage**: Individual step in the pipeline (frame, plan, spec, implement, review, verify, close)
+- **Baton**: Output artifact from a stage (evidence of completion)
+- **Continuation**: System directive to resume active runs
+- **Inject**: Persistent note or policy stored in DB
+
+### Run State Machine
+
+```
+Story: queued → approved → in_progress (has active run) → done/blocked/archived
+
+Run: created → running → completed/failed/aborted
+
+Stage: pending → running → completed/failed → (next stage)
+```
+
+## Stage Gate Semantics
+
+Stages progress deterministically through a fixed pipeline: `frame → plan → spec → implement → review → verify → close`.
+
+- **Approval**: Required only once per story (via `astro_story_approve`). Stages auto-advance without additional approval.
+- **Deterministic Progression**: Each stage's inputs are pinned (story spec, prior stage outputs, config snapshot). Tool outputs are hashed and stored as artifacts for auditability.
+- **Gate Conditions**:
+  - `frame`: Always starts first
+  - `plan`: Requires `frame` completion
+  - `spec`: Requires `plan` completion
+  - `implement`: Requires `spec` completion + valid stage output
+  - `review`: Requires `implement` completion
+  - `verify`: Requires `review` completion
+  - `close`: Requires `verify` completion + all tests pass
+- **Failure Handling**: If a stage fails (error in output or timeout), the run halts. Use `astro_stage_reset` to retry from that stage.
+
+## Artifact Layout
+
+Astrocode writes durable artifacts to `.astro/` with this structure:
+
+```
+.astro/
+├── astro.db                    # SQLite ledger (source of truth for state)
+├── spec.md                     # Current project spec
+├── runs/
+│   └── <run_id>/               # One directory per run
+│       ├── stages/
+│       │   ├── frame/
+│       │   │   ├── summary.md      # Stage output summary
+│       │   │   └── artifacts/      # Stage-specific files
+│       │   ├── plan/
+│       │   │   ├── summary.md
+│       │   │   └── artifacts/
+│       │   └── ...               # spec, implement, review, verify, close
+│       └── run_meta.json       # Run metadata
+└── injects/                    # Persistent notes/policies
+```
+
+**Source of Truth**: DB is canonical for state (runs, stages, approvals). Disk artifacts are evidence payloads, content-addressed by hash for integrity.
 
+## Tools by User Journey
+
+### Setup
 - `astro_init` — initialize `.astro/` + DB schema (idempotent)
-- `astro_status` — compact dashboard of current run/stage + next action
-- `astro_story_queue` — create a story
+- `astro_spec_set` — set/update project spec
+- `astro_spec_get` — get current project spec
+
+### Backlog Management
+- `astro_story_queue` — create a story (ticket)
 - `astro_story_approve` — approve story for execution
-- `astro_workflow_proceed` — deterministic step/loop orchestrator (the main “harness” tool)
-- `astro_stage_start` — start a stage (primitive)
-- `astro_stage_complete` — complete a stage from a stage-agent output (parses `ASTRO_JSON_*` markers)
-- `astro_repair` — repair invariants / recover corrupt state
+- `astro_story_board` — view stories grouped by state
+- `astro_story_set_state` — admin: manually set story state
+
+### Run Lifecycle
+- `astro_status` — compact dashboard of active run/stage + next action
+- `astro_workflow_proceed` — advance pipeline by one step or loop until blocked
+- `astro_run_get` — get run details and stage statuses
+- `astro_run_abort` — abort active run and unlock story
+
+### Stage Lifecycle
+- `astro_stage_start` — start a stage manually
+- `astro_stage_complete` — complete stage from agent output (parses `ASTRO_JSON_*`)
+- `astro_stage_reset` — reset stage back to pending
+- `astro_stage_fail` — manually fail a stage
+
+### Artifacts & Evidence
+- `astro_artifact_put` — write artifact to disk + record in DB
+- `astro_artifact_list` — list artifacts for run/stage
+- `astro_artifact_get` — get artifact content/metadata
+
+### Injects (Notes/Policies)
+- `astro_inject_put` — create/update persistent inject
+- `astro_inject_list` — list injects
+- `astro_inject_get` — get inject content
+- `astro_inject_search` — search injects by query
 
-Advanced (octopus) tools exist for artifacts, injects, and admin controls.
+### Diagnostics & Repair
+- `astro_repair` — repair DB invariants and recover state
+- `astro_inject_eligible` — debug: show eligible injects
+- `astro_inject_debug_due` — debug: comprehensive injection diagnostics
 
-## Continuation (“infinite agency”, but visible)
+## First Run Walkthrough (90 seconds)
+
+Get started with a minimal workflow:
+
+```bash
+# Initialize Astrocode in your project (creates .astro/ directory and DB)
+astro_init
+
+# Create and queue a story (backlog ticket)
+astro_story_queue "Add dark mode toggle to settings page"
+
+# Approve the story for execution (returns story_key)
+astro_story_approve <story_key_from_above>
+
+# Start the deterministic workflow harness (advances stages automatically)
+astro_workflow_proceed
+
+# Check status and next action
+astro_status
+```
+
+Example `astro_status` output when a run is active:
+```
+Active Run: run_abc123 (Story: Add dark mode toggle)
+Current Stage: implement (in_progress)
+Pipeline: frame✓ plan✓ spec✓ implement... review verify close
+Next Action: Wait for stage agent completion, or run astro_workflow_proceed to advance
+```
+
+Success looks like all stages complete with green checkmarks, and your story marked as done.
+
+## Continuation ("infinite agency", but visible)
 
 When a run is active and a session goes idle, or a tool completes, Astrocode injects a **visible** directive like:
 
 `[SYSTEM DIRECTIVE: ASTROCODE — CONTINUE]`
 
-This directive is deduped (hashed + recorded in DB) to avoid spam loops.
+**Injection Triggers**:
+- Session idle timeout (configurable, default 30s)
+- Tool execution completion (when run is still active)
+- Explicit workflow proceed calls
+
+**Dedupe Mechanism**:
+- Directive is hashed (SHA-256 of run_id + stage_key + timestamp + config snapshot)
+- Recorded in `continuations` table to prevent re-injection
+- Ensures deterministic, non-spammy progression
+
+**Safety Rails for Auto-Continue** (when enabled):
+- Rate limit: Max 1 continuation per 10 seconds
+- Max depth: 50 continuations per run
+- Cooldown: 5-minute pause after 10 consecutive continuations
+- Bounds prevent runaway loops while allowing "infinite agency"
+
+## Stage-Agent Output Contract
+
+Stage agents must output text containing `ASTRO_JSON_*` markers for `astro_stage_complete` to parse and advance the pipeline.
+
+**Required Markers**:
+- `ASTRO_JSON_SUMMARY`: Stage completion summary (markdown text)
+- `ASTRO_JSON_OUTPUT`: Structured output data (JSON object)
 
-You can optionally enable bounded auto-continue (rate-limit safe) in config.
+**Schema Shapes**:
+```json
+// ASTRO_JSON_SUMMARY
+{
+  "summary": "## Stage Complete\n\nImplemented the feature as planned..."
+}
+
+// ASTRO_JSON_OUTPUT
+{
+  "status": "success" | "failed",
+  "artifacts": ["path/to/file1", "path/to/file2"],
+  "next_stage_hints": ["consider edge cases"],
+  "errors": ["error message"] // optional
+}
+```
+
+**Example Stage Output**:
+```
+I've completed the implementation stage. All tests pass.
+
+ASTRO_JSON_SUMMARY
+{"summary": "## Implementation Complete\n\nAdded dark mode toggle with React state management."}
+
+ASTRO_JSON_OUTPUT
+{"status": "success", "artifacts": ["src/components/DarkModeToggle.tsx", "src/hooks/useDarkMode.ts"]}
+```
+
+**Failure Modes**:
+- Missing marker: Stage fails, run halts
+- Invalid JSON: Parse error, stage marked failed
+- Status "failed": Stage fails but run can be reset
+
+## Troubleshooting & Recovery
+
+### Common Issues
+
+- **better-sqlite3 install failures**: Ensure build tools are installed (see Runtime Requirements). On macOS: `xcode-select --install`. On Linux: `apt install build-essential python3`.
+- **Locked DB**: Close all OpenCode instances. If persistent, `astro_repair` can unlock and recover.
+- **Corrupted/Incomplete stage run**: Use `astro_stage_reset <stage_key>` to retry. If DB state is invalid, run `astro_repair`.
+- **Runaway continuation loop**: Disable auto-continue in config. Manually abort with `astro_run_abort` and restart.
+
+### astro_repair
+
+Run `astro_repair` to fix DB inconsistencies and recover corrupt state. It:
+- Validates and repairs run/stage invariants
+- Re-syncs disk artifacts with DB records
+- Writes a repair report artifact
+
+It will **not**:
+- Recover lost artifacts from disk
+- Undo committed changes
+- Fix application-level bugs
+
+If repair fails, backup `.astro/` and re-initialize with `astro_init`.
 
 ## Installation
 
@@ -71,6 +282,16 @@ Project config is read from:
 
 Config is validated (Zod via `@opencode-ai/plugin/tool.schema`) and merged with defaults.
 
+## Runtime Requirements
+
+- **Node.js**: >=18.0.0 (for native ESM support)
+- **OpenCode**: >=1.1.19 (minimum plugin API version)
+- **Platforms**:
+  - macOS: Xcode Command Line Tools required (for better-sqlite3 native compilation)
+  - Linux: python3, g++ or clang++ (build essentials)
+  - Windows: Visual Studio Build Tools or Windows SDK
+- **SQLite**: better-sqlite3 handles native compilation automatically, but may require system dependencies on some platforms.
+
 ## Development
 
 ```bash
@@ -80,6 +301,17 @@ npm run build
 
 > NOTE: This repo depends on `better-sqlite3` (native). It is a deliberate v2-alpha choice for performance and DB ergonomics. Backend abstraction is structured so swapping to `bun:sqlite` or `node:sqlite` is straightforward later.
 
+## Versioning & Migrations
+
+Astrocode v2 alpha is under active development. DB schema changes may occur between versions.
+
+- **Schema Updates**: `astro_init` handles schema migrations automatically (idempotent)
+- **Breaking Changes**: May require `astro_repair` or manual DB reset
+- **Backup First**: Always backup `.astro/astro.db` before upgrading
+- **No Downgrades**: Schema migrations are forward-only
+
+If you encounter schema errors, run `astro_repair` or delete `.astro/` and re-run `astro_init`.
+
 ## License
 
 MIT

package/dist/agents/prompts.d.ts

@@ -1,2 +1,3 @@
 export declare const BASE_ORCH_PROMPT = "You are Astro (Orchestrator) for Astrocode.\n\n Mission:\n - Advance a deterministic pipeline: frame \u2192 plan \u2192 spec \u2192 implement \u2192 review \u2192 verify \u2192 close.\n - The SQLite DB is the source of truth. Prefer tools over prose.\n - Never narrate what prompts you received.\n - Keep outputs short; store large outputs as artifacts and reference paths.\n\n Operating rules:\n - Only start new runs when the user explicitly requests implementation, workflow management, or story processing.\n - Answer questions directly when possible without starting workflows.\n - Prefer calling astro_workflow_proceed (step/loop) and astro_status only when actively managing a workflow.\n - Delegate stage work only to the stage subagent matching the current stage.\n - If a stage subagent returns status=blocked, inject the BLOCKED directive and stop.\n - Follow [SYSTEM DIRECTIVE: ASTROCODE \u2014 CONTINUE] by calling astro_workflow_proceed(mode=\"step\", max_steps=1).\n - Never delegate from subagents (enforced by permissions).\n - Be discretionary: assess if the user's request requires workflow initiation or just information.\n";
 export declare const BASE_STAGE_PROMPT = "You are an Astro stage subagent.\n\n***CRITICAL: Follow the latest [SYSTEM DIRECTIVE: ASTROCODE \u2014 STAGE_*] you receive EXACTLY.***\n\nYour output MUST be in this EXACT format:\n\n1) First, a short summary paragraph (1-3 sentences).\n\n2) Then, immediately after, the ASTRO JSON between markers:\n\n<!-- ASTRO_JSON_BEGIN -->\n{\n  \"stage_key\": \"CURRENT_STAGE\",\n  \"status\": \"ok\",\n  \"summary\": \"Brief summary of work done\",\n  \"tasks\": [],\n  \"files\": [],\n  \"questions\": []\n}\n<!-- ASTRO_JSON_END -->\n\nMANDATORY:\n- stage_key must be \"CURRENT_STAGE\"\n- status must be \"ok\", \"blocked\", or \"failed\"\n- summary must be a non-empty string\n- tasks, files, questions must be ARRAYS (use [] for empty)\n- JSON must be valid syntax\n- Use exact markers shown above\n\nARRAY FORMAT EXAMPLES:\n- tasks: [{\"title\": \"Task name\", \"complexity\": 3}]\n- files: [{\"path\": \"file.js\", \"kind\": \"file\"}]\n- questions: [\"What framework to use?\"]\n\nEXAMPLE OUTPUT:\nI analyzed the requirements and identified key components for implementation.\n\n<!-- ASTRO_JSON_BEGIN -->\n{\n  \"stage_key\": \"plan\",\n  \"status\": \"ok\",\n  \"summary\": \"Created implementation plan with 5 main tasks\",\n  \"tasks\": [\n    {\"title\": \"Setup database\", \"complexity\": 3},\n    {\"title\": \"Build API endpoints\", \"complexity\": 5}\n  ],\n  \"files\": [\n    {\"path\": \"schema.prisma\", \"kind\": \"file\"}\n  ],\n  \"questions\": []\n}\n<!-- ASTRO_JSON_END -->\n\nIf blocked, set status=\"blocked\" and add ONE question to questions array. Do not deviate from this format.\n";
+export declare const QA_AGENT_PROMPT = "\uD83C\uDF0D Global Engineering Review Prompt (LOCKED)\n\nUse this prompt when reviewing any codebase.\n\n1\uFE0F\u20E3 How every file review starts (MANDATORY)\n\nBefore discussing details, always answer:\n\nSimple question this file answers\n\nWhat decision, contract, or responsibility does this file define?\n\nThings you have at the end of running this code\n\nWhat objects, capabilities, state, guarantees, or invariants now exist?\n\nIf you can't answer these clearly, the file is already suspect.\n\n2\uFE0F\u20E3 Canonical RULE set (GLOBAL ENGINEERING INVARIANTS)\n\nThese are engineering physics laws.\nEvery serious bug maps to one of these.\nNo ad-hoc rules are allowed.\n\nenum RULE {\n  CAPABILITY_GUARANTEE =\n    \"Expose a capability only when you can guarantee it will execute safely under current runtime conditions.\",\n\n  RECOVERY_STRICTER =\n    \"Recovery/degraded paths must be simpler and more conservative than the normal path, and must not introduce new failure modes.\",\n\n  SOURCE_OF_TRUTH =\n    \"For any piece of state, define exactly one authoritative source and explicit precedence rules for any mirrors, caches, or derivations.\",\n\n  LIFECYCLE_DETERMINISM =\n    \"Initialization and lifecycle must be deterministic: single construction, stable ordering, controlled side effects, and repeatable outcomes.\",\n\n  SECURITY_BOUNDARIES =\n    \"Security, authorization, and trust boundaries must be explicit, enforced, and never inferred implicitly.\"\n}\n\nIf an issue does not violate one of these rules, it is not a P0/P1 blocker.\n\n3\uFE0F\u20E3 Severity model (WHAT \"P\" MEANS)\n\nSeverity is about trust, not annoyance.\n\nP0 \u2014 Trust break\n\nUnsafe execution\n\nCorrupted or ambiguous state\n\nNon-deterministic lifecycle\n\nBroken auditability / resumability\n\nSecurity boundary violations\n\nP1 \u2014 Reliability break\n\nRuntime crashes after successful boot\n\nCapabilities exposed but unusable\n\nDegraded mode that lies or half-works\n\nRecovery paths that add fragility\n\nP2 \u2014 Quality / polish\n\nReadability, ergonomics, maintainability\n\nNo RULE violated\n\n4\uFE0F\u20E3 Mandatory P0 / P1 Blocker Format (STRICT)\n\nEvery P0 / P1 must be written exactly like this:\n\nP{0|1} \u2014 <short human title>\n\nRule: RULE.<ONE_ENUM_VALUE>\n\nDescription:\nA human-readable explanation of how this specific code violates the rule in context.\nThis is situational and concrete \u2014 not a rule.\n\nWhat:\nThe exact defect or unsafe behavior.\n\nWhere:\nPrecise file + function + construct / lines.\n\nProposed fix:\nThe smallest possible change that restores the rule.\n(Code snippets if helpful.)\n\nWhy:\nHow this fix restores the invariant and what class of failures it prevents.\n\n5\uFE0F\u20E3 Recovery / Degraded Mode Lens (AUTO-APPLIED)\n\nWhenever code introduces:\n\nlimited mode\n\nfallback\n\ncatch-based recovery\n\npartial initialization\n\nAutomatically evaluate against:\n\nRULE.RECOVERY_STRICTER\n\nRULE.CAPABILITY_GUARANTEE\n\nRULE.LIFECYCLE_DETERMINISM\n\nIf recovery adds logic, validation, or ambiguity \u2192 it is a blocker.\n\nRecovery must:\n\nreduce capability surface\n\nfail earlier, not later\n\nbe simpler than the normal path\n\nprovide a clear path back to normal\n\n6\uFE0F\u20E3 How to ask for the next file (TEACHING MODE)\n\nBefore asking for the next file, always explain:\n\nWhat this next file likely does (human-readable)\n\n\"This file takes X, registers it with Y, then enforces Z...\"\n\nWhy this file matters next\n\nWhich RULE it is likely to uphold or violate, and why reviewing it now reduces risk.\n\n7\uFE0F\u20E3 What this frame teaches over time\n\nAfter repeated use, you stop seeing \"random bugs\" and start seeing patterns:\n\nCAPABILITY_GUARANTEE violations (exposed but unsafe APIs)\n\nRECOVERY_STRICTER violations (clever fallbacks that explode)\n\nSOURCE_OF_TRUTH drift (DB vs disk vs memory)\n\nLIFECYCLE_DETERMINISM failures (double init, racey wiring)\n\nSECURITY_BOUNDARIES leaks (implicit trust)\n\nAt that point, reviews become portable skills, not project-specific knowledge.";

package/dist/agents/prompts.js

@@ -71,3 +71,162 @@ 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/dist/agents/registry.js

@@ -1,5 +1,5 @@
 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";
 function denyAll() {
     return { "*": "deny" };
 }
@@ -108,6 +108,7 @@ export function createAstroAgents(opts) {
             },
             librarian_name: "Librarian",
             explore_name: "Explore",
+            qa_name: "QA",
             agent_variant_overrides: {}
         };
     }
@@ -215,6 +216,15 @@ export function createAstroAgents(opts) {
         prompt: BASE_STAGE_PROMPT,
         permission: stageReadOnlyPermissions(),
     }, "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", {
         description: "General-purpose fallback agent for delegation.",

package/dist/config/loader.js

@@ -4,6 +4,37 @@ import { parse as parseJsonc } from "jsonc-parser";
 import { AstrocodeConfigSchema } from "./schema";
 import { deepMerge } from "../shared/deep-merge";
 import { warn } from "../shared/log";
+function validateJsonSerializable(obj, path = "") {
+    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 function detectConfigFile(basePathNoExt) {
     const jsoncPath = basePathNoExt + ".jsonc";
     if (fs.existsSync(jsoncPath))
@@ -43,6 +74,9 @@ export function loadAstrocodeConfig(repoRoot) {
         cfg = deepMerge(cfg, projectCfg);
     // 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)
     return cfg;
 }

package/dist/config/schema.d.ts

@@ -21,8 +21,8 @@ export declare const AstrocodeConfigSchema: z.ZodDefault<z.ZodObject<{
     disabled_commands: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
     determinism: z.ZodOptional<z.ZodDefault<z.ZodObject<{
         mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
-            on: "on";
             off: "off";
+            on: "on";
         }>>>;
         strict_stage_order: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     }, z.core.$strip>>>;
@@ -60,6 +60,11 @@ export declare const AstrocodeConfigSchema: z.ZodDefault<z.ZodObject<{
             verify: "verify";
             close: "close";
         }>>>>;
+        genesis_planning: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            off: "off";
+            first_story_only: "first_story_only";
+            always: "always";
+        }>>>;
         default_mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
             step: "step";
             loop: "loop";
@@ -133,6 +138,7 @@ export declare const AstrocodeConfigSchema: z.ZodDefault<z.ZodObject<{
         }, z.core.$strip>>>;
         librarian_name: z.ZodOptional<z.ZodDefault<z.ZodString>>;
         explore_name: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+        qa_name: z.ZodOptional<z.ZodDefault<z.ZodString>>;
         agent_variant_overrides: z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
             variant: z.ZodOptional<z.ZodString>;
             model: z.ZodOptional<z.ZodString>;
@@ -178,6 +184,11 @@ export declare const AstrocodeConfigSchema: z.ZodDefault<z.ZodObject<{
         type_allowlist: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         max_per_turn: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     }, z.core.$strip>>>;
+    debug: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+        telemetry: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>>;
 export type AstrocodeConfig = z.infer<typeof AstrocodeConfigSchema>;
 export {};

package/dist/config/schema.js

@@ -92,6 +92,7 @@ const WorkflowSchema = z.object({
         "verify",
         "close",
     ]),
+    genesis_planning: z.enum(["off", "first_story_only", "always"]).default("first_story_only"),
     default_mode: z.enum(["step", "loop"]).default("step"),
     default_max_steps: z.number().int().positive().default(1),
     loop_max_steps_hard_cap: z.number().int().positive().default(200),
@@ -141,6 +142,7 @@ const AgentsSchema = z.object({
         .default({}),
     librarian_name: z.string().default("Librarian"),
     explore_name: z.string().default("Explore"),
+    qa_name: z.string().default("QA"),
     agent_variant_overrides: z
         .record(z.string(), z.object({
         variant: z.string().optional(),
@@ -170,6 +172,17 @@ const InjectSchema = z
 })
     .partial()
     .default({});
+const DebugSchema = z
+    .object({
+    telemetry: z
+        .object({
+        enabled: z.boolean().default(false),
+    })
+        .partial()
+        .default({}),
+})
+    .partial()
+    .default({});
 const UiSchema = z
     .object({
     toasts: ToastsSchema,
@@ -206,4 +219,5 @@ export const AstrocodeConfigSchema = z.object({
     git: GitSchema,
     ui: UiSchema,
     inject: InjectSchema,
+    debug: DebugSchema,
 }).partial().default({});

package/dist/hooks/continuation-enforcer.d.ts

@@ -14,10 +14,18 @@ type EventInput = {
         properties: any;
     };
 };
+type RuntimeState = {
+    db: SqliteDb | null;
+    limitedMode: boolean;
+    limitedModeReason: null | {
+        code: "db_init_failed" | "schema_too_old" | "schema_downgrade" | "schema_migration_failed";
+        details: any;
+    };
+};
 export declare function createContinuationEnforcer(opts: {
     ctx: any;
     config: AstrocodeConfig;
-    db: SqliteDb;
+    runtime: RuntimeState;
 }): {
     onToolAfter(input: ToolExecuteAfterInput): Promise<void>;
     onChatMessage(_input: ChatMessageInput): Promise<void>;

package/dist/hooks/continuation-enforcer.js

@@ -9,7 +9,8 @@ function msFromIso(iso) {
     return Number.isFinite(t) ? t : 0;
 }
 export function createContinuationEnforcer(opts) {
-    const { ctx, config, db } = opts;
+    const { ctx, config, runtime } = opts;
+    const { db } = runtime;
     const toasts = createToastManager({ ctx, throttleMs: config.ui.toasts.throttle_ms });
     const sessions = new Map();
     function getState(sessionId) {

package/dist/hooks/inject-provider.d.ts

@@ -4,10 +4,18 @@ type ChatMessageInput = {
     sessionID: string;
     agent: string;
 };
+type RuntimeState = {
+    db: SqliteDb | null;
+    limitedMode: boolean;
+    limitedModeReason: null | {
+        code: "db_init_failed" | "schema_too_old" | "schema_downgrade" | "schema_migration_failed";
+        details: any;
+    };
+};
 export declare function createInjectProvider(opts: {
     ctx: any;
     config: AstrocodeConfig;
-    db: SqliteDb;
+    runtime: RuntimeState;
 }): {
     onChatMessage(input: ChatMessageInput): Promise<void>;
 };