orcastrator 0.2.13 → 0.2.15

package/README.md

@@ -22,7 +22,17 @@ Start with a plain-language goal:
 orca "add auth to the app"
 ```
 
-Orca will create a run, plan tasks, execute them, and persist run state.
+Orca will create a run, plan tasks, run a pre-execution review/improvement pass on the task graph, execute the reviewed graph, and persist run state.
+
+### Pre-execution review-improvement stage
+
+After planning, Orca runs a structured review pass that can edit the task graph before execution starts. The review output is schema-validated and supports concrete graph operations:
+
+- update task fields (`name`, `description`, `acceptance_criteria`)
+- add/remove task
+- add/remove dependency
+
+The edited graph is re-validated as a DAG. If review output is invalid, Orca fails with an actionable error by default. You can configure `review.onInvalid: "warn_skip"` to log a warning and continue with the original planner graph.
 
 ## Spec And Plan Files
 
@@ -92,6 +102,10 @@ export default {
   codex: {
     model: "gpt-5.3-codex",       // override the codex model
     multiAgent: true,              // enable codex multi-agent (see below)
+  },
+  review: {
+    enabled: true,                 // default true
+    onInvalid: "fail"             // or "warn_skip"
   }
 };
 ```
@@ -135,6 +149,7 @@ Global:
 - `--on-milestone <cmd>`
 - `--on-task-complete <cmd>`
 - `--on-task-fail <cmd>`
+- `--on-invalid-plan <cmd>`
 - `--on-complete <cmd>`
 - `--on-error <cmd>`
 
@@ -188,7 +203,7 @@ Global:
 
 - `--anthropic-key <key>`
 - `--openai-key <key>`
-- `--check` (API key lookup order: CLI flag → process env → `~/.openclaw/openclaw.json` `env.vars` → `~/.claude/.env` → `~/.config/claude/.env` → `./.env`)
+- `--check` (API key lookup order: CLI flag → process env → `~/.openclaw/openclaw.json` `env.vars` → `~/.claude/.env` → `~/.config/claude/.env`)
 - `--global`
 - `--project`
 
@@ -204,6 +219,7 @@ Hook names:
 - `onMilestone`
 - `onTaskComplete`
 - `onTaskFail`
+- `onInvalidPlan`
 - `onComplete`
 - `onError`
 
@@ -222,6 +238,15 @@ Run IDs are generated as:
 - Project: `./orca.config.js` or `./orca.config.ts`
 - Explicit: `--config <path>`
 
+### Project Instruction Files
+
+During planning, Orca automatically injects project instruction files when present:
+
+1. `AGENTS.md`
+2. `CLAUDE.md`
+
+Files are discovered from the project root (nearest `.git` from the spec/task context) and injected in that order.
+
 ### Run State Locations
 
 - Run status: `<runsDir>/<run-id>/status.json`
@@ -230,8 +255,54 @@ Run IDs are generated as:
 
 ## Development
 
+Install dependencies with npm (primary lockfile):
+
+```bash
+npm install
+```
+
+Run local development and tests with Bun (faster runtime for this project):
+
 ```bash
-bun install
-bun test
 bun run src/cli/index.ts "your goal here"
+bun test src
+```
+
+## Validation pipeline
+
+Use the full validation gate before opening/publishing changes:
+
+```bash
+npm run validate
 ```
+
+This runs, in order:
+
+1. `npm run lint` (Oxlint syntax/style/static rules)
+2. `npm run lint:type-aware` (Oxlint + tsgolint alpha type-aware + type-check diagnostics)
+3. `npm run typecheck` (TypeScript Native Preview via `tsgo --noEmit`, with environment fallback to `tsc --noEmit`)
+4. `npm run test`
+5. `npm run build`
+
+`npm run build` remains `tsc` because the native preview compiler is used here as a fast typecheck gate; production JS emission stays on stable `typescript` for predictable package output.
+
+## Package manager + lockfile policy
+
+Orca uses a mixed runtime/tooling model on purpose:
+
+- **npm is canonical for dependency resolution, release builds, and deterministic installs**.
+- **Bun is used as a runtime/test runner in local workflows** (`dev`, `start`, `test`).
+
+Commit both lockfiles:
+
+- `package-lock.json` — canonical dependency graph for npm/CI/publish
+- `bun.lock` — Bun runtime resolution parity for local Bun commands
+
+When dependencies change, update both lockfiles in the same PR:
+
+```bash
+npm install
+bun install
+```
+
+This keeps npm and Bun behavior aligned without forcing a disruptive full migration.

package/dist/agents/claude/session.js

@@ -1,5 +1,6 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
+import { TaskGraphReviewPayloadSchema } from "../../core/task-graph-review.js";
 import { parseAgentJson } from "../../utils/agent-json.js";
 const PlannedTaskSchema = z.object({
     id: z.string().min(1),
@@ -101,6 +102,23 @@ const EXECUTION_OUTPUT_FORMAT = {
     type: "json_schema",
     schema: EXECUTION_OUTPUT_SCHEMA,
 };
+const REVIEW_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["changes"],
+    properties: {
+        changes: {
+            type: "array",
+            items: {
+                type: "object"
+            }
+        }
+    }
+};
+const REVIEW_OUTPUT_FORMAT = {
+    type: "json_schema",
+    schema: REVIEW_OUTPUT_SCHEMA,
+};
 function buildPlanningPrompt(spec, systemContext) {
     return [
         systemContext,
@@ -127,6 +145,27 @@ function buildTaskExecutionPrompt(task, runId, cwd, systemContext) {
         "If you cannot complete the task, set outcome=failed and provide a concise error.",
     ].join("\n\n");
 }
+function buildTaskGraphReviewPrompt(tasks, systemContext) {
+    return [
+        systemContext,
+        "You are Orca's pre-execution task-graph reviewer.",
+        "Return only structured review operations in the configured schema.",
+        "Allowed operations: update_task (name/description/acceptance_criteria), add_task, remove_task, add_dependency, remove_dependency.",
+        "Return an empty changes array if no edits are needed.",
+        "Current task graph JSON:",
+        JSON.stringify(tasks, null, 2)
+    ].join("\n\n");
+}
+function parseStructuredTaskGraphReviewPayload(payload, rawResponse = "") {
+    const result = TaskGraphReviewPayloadSchema.safeParse(payload);
+    if (!result.success) {
+        throw formatSchemaError("Claude structured review payload failed schema validation", result.error);
+    }
+    return {
+        changes: result.data.changes,
+        rawResponse
+    };
+}
 function extractAssistantText(message) {
     if (!message || typeof message !== "object") {
         return null;
@@ -277,6 +316,22 @@ export async function planSpec(spec, systemContext, config) {
         claudeQuery.close();
     }
 }
+export async function reviewTaskGraph(tasks, systemContext, config) {
+    const claudeQuery = query({
+        prompt: buildTaskGraphReviewPrompt(tasks, systemContext),
+        options: buildClaudeQueryOptions(config, REVIEW_OUTPUT_FORMAT),
+    });
+    try {
+        const { rawResponse, structuredOutput } = await collectSessionResult(claudeQuery);
+        if (structuredOutput === undefined) {
+            throwMissingStructuredOutput("review");
+        }
+        return parseStructuredTaskGraphReviewPayload(structuredOutput, rawResponse);
+    }
+    finally {
+        claudeQuery.close();
+    }
+}
 export async function executeTask(task, runId, config, systemContext) {
     const claudeQuery = query({
         prompt: buildTaskExecutionPrompt(task, runId, process.cwd(), systemContext),

package/dist/agents/codex/session.js

@@ -1,4 +1,5 @@
 import { CodexClient } from "@ratley/codex-client";
+import { TaskGraphReviewPayloadSchema } from "../../core/task-graph-review.js";
 function buildPlanningPrompt(spec, systemContext) {
     return [
         systemContext,
@@ -33,6 +34,36 @@ function buildTaskExecutionPrompt(task, runId, cwd, systemContext) {
         "Do not wrap it in markdown fences. Do not add any text after the JSON line. The JSON line is required.",
     ].join("\n\n");
 }
+function buildTaskGraphReviewPrompt(tasks, systemContext) {
+    return [
+        systemContext,
+        "You are Orca's pre-execution task-graph reviewer.",
+        "Return JSON matching this shape exactly: {\"changes\":[...operations...]}",
+        "Allowed operation shapes:",
+        "- {\"op\":\"update_task\",\"taskId\":\"...\",\"fields\":{\"name\"?:string,\"description\"?:string,\"acceptance_criteria\"?:string[]}}",
+        "- {\"op\":\"add_task\",\"task\":<full task object>}",
+        "- {\"op\":\"remove_task\",\"taskId\":\"...\"}",
+        "- {\"op\":\"add_dependency\",\"taskId\":\"...\",\"dependsOn\":\"...\"}",
+        "- {\"op\":\"remove_dependency\",\"taskId\":\"...\",\"dependsOn\":\"...\"}",
+        "Return ONLY JSON. No markdown.",
+        "Current task graph:",
+        JSON.stringify(tasks, null, 2),
+    ].join("\n\n");
+}
+function parseTaskGraphReview(raw) {
+    const parsed = JSON.parse(extractJson(raw));
+    const result = TaskGraphReviewPayloadSchema.safeParse(parsed);
+    if (!result.success) {
+        const details = result.error.issues
+            .map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`)
+            .join("; ");
+        throw new Error(`Codex review response failed schema validation. ${details}`);
+    }
+    return {
+        changes: result.data.changes,
+        rawResponse: raw,
+    };
+}
 function extractAgentText(result) {
     if (result.agentMessage.length > 0) {
         return result.agentMessage;
@@ -192,6 +223,21 @@ export async function createCodexSession(cwd, config) {
                 rawResponse,
             };
         },
+        async reviewTaskGraph(tasks, systemContext) {
+            const effort = getEffort(config);
+            const result = effort
+                ? await client.runTurn({
+                    threadId,
+                    effort,
+                    input: [{ type: "text", text: buildTaskGraphReviewPrompt(tasks, systemContext) }],
+                })
+                : await client.runTurn({
+                    threadId,
+                    input: [{ type: "text", text: buildTaskGraphReviewPrompt(tasks, systemContext) }],
+                });
+            const rawResponse = extractAgentText(result);
+            return parseTaskGraphReview(rawResponse);
+        },
         async executeTask(task, runId, systemContext) {
             const effort = getEffort(config);
             const result = effort
@@ -299,6 +345,15 @@ export async function planSpec(spec, systemContext, config) {
         await session.disconnect();
     }
 }
+export async function reviewTaskGraph(tasks, systemContext, config) {
+    const session = await createCodexSession(process.cwd(), config);
+    try {
+        return await session.reviewTaskGraph(tasks, systemContext);
+    }
+    finally {
+        await session.disconnect();
+    }
+}
 export async function executeTask(task, runId, config, systemContext) {
     const session = await createCodexSession(process.cwd(), config);
     try {

package/dist/cli/commands/cancel.js

@@ -37,7 +37,7 @@ export async function cancelCommandHandler(options) {
         return;
     }
     const cancelledAt = new Date().toISOString();
-    let cancelledTaskId = null;
+    let cancelledTaskId;
     const tasks = run.tasks.map((task) => {
         if (task.status === "in_progress") {
             cancelledTaskId = task.id;

package/dist/cli/commands/run.js

@@ -7,7 +7,7 @@ import { InvalidArgumentError } from "commander";
 import { createCodexSession } from "../../agents/codex/session.js";
 import { ensureCodexMultiAgent } from "../../core/codex-config.js";
 import { resolveConfig } from "../../core/config-loader.js";
-import { runPlanner } from "../../core/planner.js";
+import { InvalidPlanError, runPlanner } from "../../core/planner.js";
 import { runTaskRunner } from "../../core/task-runner.js";
 import { createOpenclawHookHandler, detectOpenclawAvailability } from "../../hooks/adapters/openclaw.js";
 import { createStdoutHookHandler } from "../../hooks/adapters/stdout.js";
@@ -19,6 +19,7 @@ const ALL_HOOKS = [
     "onMilestone",
     "onTaskComplete",
     "onTaskFail",
+    "onInvalidPlan",
     "onComplete",
     "onError"
 ];
@@ -26,6 +27,7 @@ const VALID_HOOK_NAMES = new Set([
     "onMilestone",
     "onTaskComplete",
     "onTaskFail",
+    "onInvalidPlan",
     "onComplete",
     "onError"
 ]);
@@ -63,6 +65,7 @@ function buildCliCommandHooks(options) {
         ...(options.onMilestone ? { onMilestone: options.onMilestone } : {}),
         ...(options.onTaskComplete ? { onTaskComplete: options.onTaskComplete } : {}),
         ...(options.onTaskFail ? { onTaskFail: options.onTaskFail } : {}),
+        ...(options.onInvalidPlan ? { onInvalidPlan: options.onInvalidPlan } : {}),
         ...(options.onComplete ? { onComplete: options.onComplete } : {}),
         ...(options.onError ? { onError: options.onError } : {})
     };
@@ -118,11 +121,6 @@ export async function runCommandHandler(options) {
         console.log(`Run ID: ${runId}`);
         const store = createStore();
         await store.createRun(runId, specPath);
-        await runPlanner(specPath, store, runId, effectiveConfig);
-        await store.updateRun(runId, {
-            mode: "run",
-            overallStatus: "running"
-        });
         const cliCommandHooks = buildCliCommandHooks(options);
         const dispatcher = new HookDispatcher({
             commandHooks: {
@@ -162,6 +160,28 @@ export async function runCommandHandler(options) {
         const emitHook = async (event) => {
             await dispatcher.dispatch(event);
         };
+        try {
+            await runPlanner(specPath, store, runId, effectiveConfig);
+        }
+        catch (error) {
+            if (error instanceof InvalidPlanError) {
+                await emitHook({
+                    runId: runId,
+                    hook: "onInvalidPlan",
+                    message: `invalid-plan:${error.stage}`,
+                    timestamp: new Date().toISOString(),
+                    error: error.message,
+                    metadata: {
+                        stage: error.stage
+                    }
+                });
+            }
+            throw error;
+        }
+        await store.updateRun(runId, {
+            mode: "run",
+            overallStatus: "running"
+        });
         const executor = effectiveConfig?.executor ?? "codex";
         if (executor === "codex") {
             const cwd = process.cwd();
@@ -253,6 +273,7 @@ export function registerRunCommand(program) {
         .option("--on-milestone <cmd>", "Shell hook command for onMilestone")
         .option("--on-task-complete <cmd>", "Shell hook command for onTaskComplete")
         .option("--on-task-fail <cmd>", "Shell hook command for onTaskFail")
+        .option("--on-invalid-plan <cmd>", "Shell hook command for onInvalidPlan")
         .option("--on-complete <cmd>", "Shell hook command for onComplete")
         .option("--on-error <cmd>", "Shell hook command for onError")
         .action(async (goal, commandOptions) => {

package/dist/cli/commands/setup.js

@@ -57,7 +57,7 @@ export function resolveApiKey(flagValue, envVarName, openclawConfigPathOrOptions
         return envValue.trim();
     }
     const options = typeof openclawConfigPathOrOptions === "string"
-        ? { ...(maybeOptions ?? {}), openclawConfigPath: openclawConfigPathOrOptions }
+        ? { ...maybeOptions, openclawConfigPath: openclawConfigPathOrOptions }
         : (openclawConfigPathOrOptions ?? {});
     const homedir = options.homedir ?? os.homedir();
     const openclawValue = readOpenclawEnvVar(envVarName, options.openclawConfigPath, homedir);
@@ -65,7 +65,6 @@ export function resolveApiKey(flagValue, envVarName, openclawConfigPathOrOptions
         return openclawValue;
     }
     const dotenvValue = readDotEnvFallback(envVarName, {
-        cwd: options.cwd ?? process.cwd(),
         homedir
     });
     if (dotenvValue) {
@@ -104,8 +103,7 @@ function readOpenclawEnvVar(envVarName, openclawConfigPath, homedir = os.homedir
 function readDotEnvFallback(envVarName, options) {
     const candidatePaths = [
         path.join(options.homedir, ".claude", ".env"),
-        path.join(options.homedir, ".config", "claude", ".env"),
-        path.join(options.cwd, ".env")
+        path.join(options.homedir, ".config", "claude", ".env")
     ];
     for (const candidatePath of candidatePaths) {
         const value = readEnvVarFromDotEnvFile(candidatePath, envVarName);

package/dist/core/config-loader.js

@@ -52,7 +52,10 @@ function coerceConfig(candidate) {
     }
     if ("executor" in candidate && candidate.executor !== undefined) {
         if (candidate.executor !== "claude" && candidate.executor !== "codex") {
-            throw new Error(`Config.executor must be 'claude' or 'codex', got ${String(candidate.executor)}`);
+            const executorDisplay = typeof candidate.executor === "string"
+                ? candidate.executor
+                : (JSON.stringify(candidate.executor) ?? describeType(candidate.executor));
+            throw new Error(`Config.executor must be 'claude' or 'codex', got ${executorDisplay}`);
         }
     }
     if ("claude" in candidate && candidate.claude !== undefined) {
@@ -77,6 +80,22 @@ function coerceConfig(candidate) {
             parseCodexEffort(candidate.codex.effort);
         }
     }
+    if ("review" in candidate && candidate.review !== undefined) {
+        if (!isObject(candidate.review)) {
+            throw new Error(`Config.review must be an object, got ${describeType(candidate.review)}`);
+        }
+        if ("enabled" in candidate.review && candidate.review.enabled !== undefined && typeof candidate.review.enabled !== "boolean") {
+            throw new Error(`Config.review.enabled must be a boolean, got ${describeType(candidate.review.enabled)}`);
+        }
+        if ("onInvalid" in candidate.review && candidate.review.onInvalid !== undefined) {
+            if (candidate.review.onInvalid !== "fail" && candidate.review.onInvalid !== "warn_skip") {
+                const onInvalidDisplay = typeof candidate.review.onInvalid === "string"
+                    ? candidate.review.onInvalid
+                    : (JSON.stringify(candidate.review.onInvalid) ?? describeType(candidate.review.onInvalid));
+                throw new Error(`Config.review.onInvalid must be 'fail' or 'warn_skip', got ${onInvalidDisplay}`);
+            }
+        }
+    }
     return candidate;
 }
 export async function loadConfig(configPath) {
@@ -112,6 +131,9 @@ export function mergeConfigs(...configs) {
         if (merged.pr !== undefined || config.pr !== undefined) {
             merged.pr = { ...merged.pr, ...config.pr };
         }
+        if (merged.review !== undefined || config.review !== undefined) {
+            merged.review = { ...merged.review, ...config.review };
+        }
         if (merged.hooks !== undefined || config.hooks !== undefined) {
             merged.hooks = { ...merged.hooks, ...config.hooks };
         }

package/dist/core/planner.js

@@ -1,14 +1,30 @@
 import { promises as fs } from "node:fs";
-import { planSpec as planSpecWithClaude } from "../agents/claude/session.js";
-import { planSpec as planSpecWithCodex } from "../agents/codex/session.js";
+import path from "node:path";
+import { planSpec as planSpecWithClaude, reviewTaskGraph as reviewTaskGraphWithClaude } from "../agents/claude/session.js";
+import { planSpec as planSpecWithCodex, reviewTaskGraph as reviewTaskGraphWithCodex } from "../agents/codex/session.js";
 import { logger } from "../utils/logger.js";
 import { loadSkills } from "../utils/skill-loader.js";
 import { validateDAG } from "./dependency-graph.js";
+import { applyTaskGraphReviewChanges, summarizeReviewChanges } from "./task-graph-review.js";
 const DEFAULT_SYSTEM_CONTEXT = "You are Orca planner.";
+const PROJECT_INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
+const PROJECT_INSTRUCTION_CHAR_CAP = 4_000;
+export class InvalidPlanError extends Error {
+    stage;
+    constructor(stage, message) {
+        super(message);
+        this.name = "InvalidPlanError";
+        this.stage = stage;
+    }
+}
 let testPlanSpecOverride = null;
+let testReviewTaskGraphOverride = null;
 export function setPlanSpecForTests(fn) {
     testPlanSpecOverride = fn;
 }
+export function setReviewTaskGraphForTests(fn) {
+    testReviewTaskGraphOverride = fn;
+}
 function resolvePlanSpecImpl(config) {
     if (testPlanSpecOverride) {
         return testPlanSpecOverride;
@@ -16,6 +32,13 @@ function resolvePlanSpecImpl(config) {
     const executor = config?.executor ?? "codex";
     return executor === "claude" ? planSpecWithClaude : planSpecWithCodex;
 }
+function resolveReviewTaskGraphImpl(config) {
+    if (testReviewTaskGraphOverride) {
+        return testReviewTaskGraphOverride;
+    }
+    const executor = config?.executor ?? "codex";
+    return executor === "claude" ? reviewTaskGraphWithClaude : reviewTaskGraphWithCodex;
+}
 function formatSkillsSection(skills) {
     const formattedSkills = skills.map((skill) => [
         `### ${skill.name}`,
@@ -26,20 +49,139 @@ function formatSkillsSection(skills) {
     ].join("\n"));
     return ["## Available Skills", "", ...formattedSkills].join("\n");
 }
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveProjectContextDir(specPath) {
+    let currentDir = path.dirname(path.resolve(specPath));
+    while (true) {
+        const gitMarker = path.join(currentDir, ".git");
+        if (await pathExists(gitMarker)) {
+            return currentDir;
+        }
+        const parent = path.dirname(currentDir);
+        if (parent === currentDir) {
+            return path.dirname(path.resolve(specPath));
+        }
+        currentDir = parent;
+    }
+}
+async function loadProjectInstructions(specPath) {
+    const projectDir = await resolveProjectContextDir(specPath);
+    const instructions = [];
+    for (const fileName of PROJECT_INSTRUCTION_FILES) {
+        const filePath = path.join(projectDir, fileName);
+        if (!(await pathExists(filePath))) {
+            continue;
+        }
+        const rawContent = await fs.readFile(filePath, "utf8");
+        const content = rawContent.slice(0, PROJECT_INSTRUCTION_CHAR_CAP);
+        instructions.push({
+            fileName,
+            filePath,
+            content,
+            truncated: rawContent.length > PROJECT_INSTRUCTION_CHAR_CAP
+        });
+    }
+    return instructions;
+}
+function formatProjectInstructionsSection(instructions) {
+    const parts = ["## Project Instructions"];
+    for (const instruction of instructions) {
+        parts.push("");
+        parts.push(`### ${instruction.fileName} (${instruction.filePath})`);
+        parts.push("");
+        parts.push("```md");
+        parts.push(instruction.content);
+        parts.push("```");
+        if (instruction.truncated) {
+            parts.push(`(truncated to ${PROJECT_INSTRUCTION_CHAR_CAP} characters)`);
+        }
+    }
+    return parts.join("\n");
+}
+function buildSystemContext(skills, instructions) {
+    const sections = [DEFAULT_SYSTEM_CONTEXT];
+    if (instructions.length > 0) {
+        sections.push(formatProjectInstructionsSection(instructions));
+    }
+    if (skills.length > 0) {
+        sections.push(formatSkillsSection(skills));
+    }
+    return sections.join("\n\n");
+}
+async function runTaskGraphReview(tasks, systemContext, config) {
+    if (config?.review?.enabled === false) {
+        return { finalTasks: tasks, review: null };
+    }
+    logger.info("Review started: pre-execution task graph improvement pass");
+    const reviewFn = resolveReviewTaskGraphImpl(config);
+    let review;
+    try {
+        review = await reviewFn(tasks, systemContext, config);
+    }
+    catch (error) {
+        if (config?.review?.onInvalid === "warn_skip") {
+            logger.warn(`Review output invalid; skipping review changes (${error instanceof Error ? error.message : String(error)})`);
+            return { finalTasks: tasks, review: null };
+        }
+        throw new InvalidPlanError("review", `Review output invalid. ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (review.changes.length === 0) {
+        logger.info("Review made no changes");
+        return { finalTasks: tasks, review };
+    }
+    const updated = applyTaskGraphReviewChanges(tasks, review.changes);
+    try {
+        validateDAG(updated);
+    }
+    catch (error) {
+        throw new InvalidPlanError("review", error instanceof Error ? error.message : String(error));
+    }
+    const summary = summarizeReviewChanges(review.changes).join("; ");
+    logger.success(`Review made ${review.changes.length} changes: ${summary}`);
+    return { finalTasks: updated, review };
+}
 export async function runPlanner(specPath, store, runId, config) {
     const spec = await fs.readFile(specPath, "utf8");
-    const skills = await loadSkills(config);
-    const systemContext = skills.length === 0
-        ? DEFAULT_SYSTEM_CONTEXT
-        : `${DEFAULT_SYSTEM_CONTEXT}\n\n${formatSkillsSection(skills)}`;
+    const [skills, instructions] = await Promise.all([loadSkills(config), loadProjectInstructions(specPath)]);
+    const systemContext = buildSystemContext(skills, instructions);
     const planSpecImpl = resolvePlanSpecImpl(config);
     const result = await planSpecImpl(spec, systemContext, config);
-    validateDAG(result.tasks);
-    await store.writeTasks(runId, result.tasks);
+    try {
+        validateDAG(result.tasks);
+    }
+    catch (error) {
+        throw new InvalidPlanError("planner", error instanceof Error ? error.message : String(error));
+    }
+    let finalTasks = result.tasks;
+    try {
+        const reviewed = await runTaskGraphReview(result.tasks, systemContext, config);
+        finalTasks = reviewed.finalTasks;
+    }
+    catch (error) {
+        if (config?.review?.onInvalid === "warn_skip") {
+            logger.warn(`Review changes rejected; proceeding with planner graph (${error instanceof Error ? error.message : String(error)})`);
+            finalTasks = result.tasks;
+        }
+        else if (error instanceof InvalidPlanError) {
+            throw error;
+        }
+        else {
+            throw new InvalidPlanError("review", `Review stage failed. ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    await store.writeTasks(runId, finalTasks);
     await store.updateRun(runId, {
         overallStatus: "planning",
-        tasks: result.tasks,
+        tasks: finalTasks,
         milestones: ["plan-complete"]
     });
-    logger.success(`Plan complete: ${result.tasks.length} tasks`);
+    logger.success(`Plan complete: ${finalTasks.length} tasks`);
 }

package/dist/core/task-graph-review.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+const TaskSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string(),
+    dependencies: z.array(z.string()),
+    acceptance_criteria: z.array(z.string()),
+    status: z.enum(["pending", "in_progress", "done", "failed", "cancelled"]),
+    retries: z.number(),
+    maxRetries: z.number(),
+    startedAt: z.string().optional(),
+    finishedAt: z.string().optional(),
+    lastError: z.string().optional()
+}).strict();
+const ReviewOperationSchema = z.discriminatedUnion("op", [
+    z.object({
+        op: z.literal("update_task"),
+        taskId: z.string().min(1),
+        fields: z.object({
+            name: z.string().min(1).optional(),
+            description: z.string().optional(),
+            acceptance_criteria: z.array(z.string()).optional()
+        }).strict()
+    }).strict(),
+    z.object({
+        op: z.literal("add_task"),
+        task: TaskSchema
+    }).strict(),
+    z.object({
+        op: z.literal("remove_task"),
+        taskId: z.string().min(1)
+    }).strict(),
+    z.object({
+        op: z.literal("add_dependency"),
+        taskId: z.string().min(1),
+        dependsOn: z.string().min(1)
+    }).strict(),
+    z.object({
+        op: z.literal("remove_dependency"),
+        taskId: z.string().min(1),
+        dependsOn: z.string().min(1)
+    }).strict()
+]);
+export const TaskGraphReviewPayloadSchema = z.object({
+    changes: z.array(ReviewOperationSchema)
+}).strict();
+function findTaskIndex(tasks, taskId) {
+    return tasks.findIndex((task) => task.id === taskId);
+}
+export function summarizeReviewChanges(changes) {
+    return changes.map((change) => {
+        switch (change.op) {
+            case "update_task": {
+                const keys = Object.keys(change.fields);
+                return `update_task(${change.taskId}: ${keys.join(",") || "no fields"})`;
+            }
+            case "add_task":
+                return `add_task(${change.task.id})`;
+            case "remove_task":
+                return `remove_task(${change.taskId})`;
+            case "add_dependency":
+                return `add_dependency(${change.taskId}<-${change.dependsOn})`;
+            case "remove_dependency":
+                return `remove_dependency(${change.taskId}<-${change.dependsOn})`;
+            default:
+                return "unknown";
+        }
+    });
+}
+export function applyTaskGraphReviewChanges(tasks, changes) {
+    const nextTasks = tasks.map((task) => ({ ...task, dependencies: [...task.dependencies], acceptance_criteria: [...task.acceptance_criteria] }));
+    for (const change of changes) {
+        switch (change.op) {
+            case "update_task": {
+                const index = findTaskIndex(nextTasks, change.taskId);
+                if (index === -1) {
+                    throw new Error(`Review update_task failed: task not found (${change.taskId})`);
+                }
+                const current = nextTasks[index];
+                nextTasks[index] = {
+                    ...current,
+                    ...("name" in change.fields ? { name: change.fields.name ?? current.name } : {}),
+                    ...("description" in change.fields ? { description: change.fields.description ?? current.description } : {}),
+                    ...("acceptance_criteria" in change.fields
+                        ? { acceptance_criteria: [...(change.fields.acceptance_criteria ?? current.acceptance_criteria)] }
+                        : {})
+                };
+                break;
+            }
+            case "add_task": {
+                if (findTaskIndex(nextTasks, change.task.id) !== -1) {
+                    throw new Error(`Review add_task failed: task already exists (${change.task.id})`);
+                }
+                nextTasks.push({
+                    ...change.task,
+                    dependencies: [...change.task.dependencies],
+                    acceptance_criteria: [...change.task.acceptance_criteria]
+                });
+                break;
+            }
+            case "remove_task": {
+                const index = findTaskIndex(nextTasks, change.taskId);
+                if (index === -1) {
+                    throw new Error(`Review remove_task failed: task not found (${change.taskId})`);
+                }
+                nextTasks.splice(index, 1);
+                break;
+            }
+            case "add_dependency": {
+                const index = findTaskIndex(nextTasks, change.taskId);
+                if (index === -1) {
+                    throw new Error(`Review add_dependency failed: task not found (${change.taskId})`);
+                }
+                const current = nextTasks[index];
+                if (!current.dependencies.includes(change.dependsOn)) {
+                    current.dependencies = [...current.dependencies, change.dependsOn];
+                }
+                break;
+            }
+            case "remove_dependency": {
+                const index = findTaskIndex(nextTasks, change.taskId);
+                if (index === -1) {
+                    throw new Error(`Review remove_dependency failed: task not found (${change.taskId})`);
+                }
+                const current = nextTasks[index];
+                current.dependencies = current.dependencies.filter((dependency) => dependency !== change.dependsOn);
+                break;
+            }
+        }
+    }
+    return nextTasks;
+}

package/dist/hooks/adapters/stdout.js

@@ -1,4 +1,4 @@
-export function createStdoutHookHandler(prefix = "[hook]") {
+export function createStdoutHookHandler(prefix = "[hook]", write = console.log) {
     return async (event) => {
         const line = {
             prefix,
@@ -10,6 +10,6 @@ export function createStdoutHookHandler(prefix = "[hook]") {
             error: event.error,
             metadata: event.metadata
         };
-        console.log(JSON.stringify(line));
+        write(JSON.stringify(line));
     };
 }

package/dist/hooks/dispatcher.js

@@ -64,7 +64,10 @@ export class HookDispatcher {
                 ...process.env,
                 ORCA_MSG: event.message,
                 ORCA_RUN_ID: event.runId,
-                ORCA_TASK_ID: event.taskId ?? ""
+                ORCA_TASK_ID: event.taskId ?? "",
+                ORCA_HOOK: event.hook,
+                ORCA_ERROR: event.error ?? "",
+                ORCA_STAGE: typeof event.metadata?.stage === "string" ? event.metadata.stage : ""
             }
         });
     }

package/dist/utils/agent-json.js

@@ -3,7 +3,7 @@ function tryParseJson(input) {
         return JSON.parse(input);
     }
     catch {
-        return null;
+        return undefined;
     }
 }
 function extractFencedCandidates(text) {
@@ -54,7 +54,7 @@ function extractFirstJsonObjectOrArray(text) {
                 depth -= 1;
                 if (depth === 0) {
                     const candidate = text.slice(start, end + 1).trim();
-                    if (tryParseJson(candidate) !== null) {
+                    if (tryParseJson(candidate) !== undefined) {
                         return candidate;
                     }
                     break;
@@ -76,7 +76,7 @@ export function parseAgentJson(raw) {
     }
     for (const candidate of candidates) {
         const parsed = tryParseJson(candidate);
-        if (parsed !== null) {
+        if (parsed !== undefined) {
             return parsed;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcastrator",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "type": "module",
   "bin": {
     "orca": "dist/cli/index.js"
@@ -9,11 +9,15 @@
     "build": "tsc",
     "dev": "bun run src/cli/index.ts",
     "lint": "oxlint src/",
-    "typecheck": "tsc --noEmit",
-    "test": "bun test",
+    "typecheck": "node ./scripts/typecheck.mjs",
+    "test": "bun test src",
     "start": "bun run src/cli/index.ts",
     "prepare": "husky",
-    "postbuild": "chmod +x dist/cli/index.js"
+    "postbuild": "chmod +x dist/cli/index.js",
+    "lint:type-aware": "oxlint --type-aware --type-check --deny-warnings src/ --ignore-pattern \"**/*.test.ts\"",
+    "typecheck:native": "tsgo --noEmit",
+    "typecheck:tsc": "tsc --noEmit",
+    "validate": "npm run lint && npm run lint:type-aware && npm run typecheck && npm run test && npm run build"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.47",
@@ -21,14 +25,16 @@
     "@ratley/codex-client": "^0.1.3",
     "chalk": "^5.3.0",
     "commander": "^13.1.0",
-    "zod": "^3.24.1"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/bun": "^1.2.21",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.0",
-    "oxlint": "^0.15.14",
-    "typescript": "^5.8.2"
+    "oxlint": "^1.49.0",
+    "typescript": "^5.8.2",
+    "@typescript/native-preview": "^7.0.0-dev.20260219.1",
+    "oxlint-tsgolint": "^0.14.1"
   },
   "lint-staged": {
     "*.ts": [