quest-loop 0.1.0 → 0.3.2

package/lib/runner.mjs

@@ -34,10 +34,11 @@ class RunUsageError extends Error {
 // ---------------------------------------------------------------------------
 
 const HELP = {
-  purpose: "Drive a headless Claude or Codex worker through a quest in native goal mode.",
+  purpose: "Drive a headless Claude or Codex worker through a quest with checkpoint-based stop checks.",
   usage: [
     "quest-run <id> [--worker claude|codex] [--model M] [--effort E]",
     "              [--max-iterations N] [--max-cost USD] [--codex-sandbox MODE]",
+    "              [--codex-goal-mode auto|require|off]",
     "              [--continue-session] [--notify '<cmd>'] [--dry-run] [--json]",
     "quest-run --ready [--parallel N] [--isolate worktree] [--dry-run] [--json]",
   ],
@@ -51,6 +52,7 @@ const HELP = {
     ["--max-tokens <n>", "token cap; governs codex spend since USD is unreported → blocked, exit 11"],
     ["--session-timeout <s>", "per-session wall-clock cap (seconds); a hung worker is killed and the session counts as a stall (default 1800; config defaults.session_timeout)"],
     ["--codex-sandbox <mode>", "codex exec sandbox: read-only | workspace-write | danger-full-access (default workspace-write; config defaults.codex.sandbox). workspace-write BLOCKS git commits — commit quests need danger-full-access"],
+    ["--codex-goal-mode <mode>", "codex goal-tool policy: auto | require | off (default auto; config defaults.codex.goal_mode)"],
     ["--continue-session", "resume the previous session each iteration instead of a fresh one"],
     ["--notify <cmd>", "shell command run on run end (env: QUEST_ID, QUEST_TITLE, FINAL_STATUS, ITERATIONS, COST)"],
     ["--dry-run", "print the exact worker invocation and exit without spawning"],
@@ -68,6 +70,8 @@ const HELP = {
     "codex's default --codex-sandbox workspace-write write-protects .git, so a codex worker",
     "cannot `git commit` under it; a commit-requiring quest must opt into danger-full-access —",
     "an explicit tradeoff (full disk + network access), never escalated silently.",
+    "codex goal tools are optional by default; --codex-goal-mode require blocks honestly if",
+    "the exec surface does not expose or invoke them.",
     "Without --isolate, parallel quests are assumed file-disjoint (no locking beyond the store's).",
     "--isolate worktree leaves the worktree + quest/<id>-<slug> branch in place; the PR is the merge path.",
   ],
@@ -203,7 +207,11 @@ function resolveOptions(front, config, flags) {
   if ((flags["codex-sandbox"] != null || worker === "codex") && !CODEX_SANDBOX_MODES.includes(codexSandbox)) {
     throw new RunUsageError(`--codex-sandbox must be one of ${CODEX_SANDBOX_MODES.join(", ")} (got "${codexSandbox}")`);
   }
-  return { worker, model, effort, maxIterations, maxCost, maxTokens, sessionTimeout, codexSandbox };
+  const codexGoalMode = flags["codex-goal-mode"] ?? config.defaults.codex?.goal_mode ?? "auto";
+  if ((flags["codex-goal-mode"] != null || worker === "codex") && !["auto", "require", "off"].includes(codexGoalMode)) {
+    throw new RunUsageError(`--codex-goal-mode must be one of auto, require, off (got "${codexGoalMode}")`);
+  }
+  return { worker, model, effort, maxIterations, maxCost, maxTokens, sessionTimeout, codexSandbox, codexGoalMode };
 }
 
 function lastSessionIdFor(storeDir, questId, worker) {
@@ -273,6 +281,7 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
       schemaPath: SCHEMA_PATH,
       runStartIso,
       codexSandbox: opts.codexSandbox,
+      codexGoalMode: opts.codexGoalMode,
     };
     const inv = adapter.buildInvocation(initial, config, invOpts);
     if (flags.json) {
@@ -301,6 +310,7 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
     if (initial.status === "complete") {
       finalStatus = "complete";
       exitCode = 0;
+      io.errOut(`quest-run: quest ${id} is already complete — nothing to run. To legally re-enter the loop, run \`quest reopen ${id} --reason "<why>"\` first (never hand-edit the status line).`);
     } else if (initial.status === "cancelled") {
       finalStatus = "cancelled";
       exitCode = 0;
@@ -394,6 +404,7 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
             schemaPath: SCHEMA_PATH,
             runStartIso,
             codexSandbox: opts.codexSandbox,
+            codexGoalMode: opts.codexGoalMode,
           },
           runStartIso,
           iteration: sessionsRun,
@@ -428,6 +439,8 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
         // landed before the kill — a terminal status is still caught at the top
         // of the next iteration, so completions are never lost.
         const progressed = newCheckpoint && !sessionTimedOut;
+        // Journal the session BEFORE any terminal break so `quest runs` telemetry
+        // (iteration count, cost, tokens) is never dropped for the final session.
         local.appendRunEvent(storeDir, {
           event: "iteration_finished",
           run_id: runId,
@@ -441,6 +454,25 @@ async function runQuest(storeDir, config, id, flags, io, { cwd } = {}) {
           status_after: after ? after.status : null,
         });
 
+        // Goal-mode `require`: block whenever create_goal was required but never
+        // observed and the quest is still OPEN — a milestone checkpoint does not
+        // satisfy the requirement. A genuinely complete/blocked/cancelled quest is
+        // respected (its evidence trail stands on its own). A LOST record (`!after`)
+        // is not "open": let the missing-record path at the loop top surface it.
+        const questOpen = after && (after.status === "in_progress" || after.status === "todo");
+        if (opts.worker === "codex" && result.goalToolMissingRequired && questOpen) {
+          await recordBlocked(
+            storeDir,
+            env,
+            id,
+            "runner: codex goal tools were required but no create_goal tool call was observed",
+            "runner codex goal-mode enforcement",
+          );
+          finalStatus = "blocked";
+          exitCode = 10;
+          break;
+        }
+
         if (progressed) {
           stall = 0;
           if (after.status === "complete") {
@@ -538,6 +570,7 @@ async function runReady(storeDir, config, flags, io) {
 
   const summaries = [];
   const done = new Set();
+  const skippedEpics = new Set();
   const inFlight = new Map();
 
   const readyIds = async () => {
@@ -550,6 +583,22 @@ async function runReady(storeDir, config, flags, io) {
     }
   };
 
+  // Ids that at least one quest names as its parent — i.e. epics. Epics are
+  // closed by the orchestrator inline (verify children, run the epic validation
+  // loop, checkpoint), never dispatched to a worker. readyQuests already gates
+  // out epics with open children; this catches the fully-verified epic that has
+  // become "ready" so --ready still refuses to burn a worker run on it. A
+  // direct `quest-run <id>` on an epic stays allowed.
+  const epicIds = async () => {
+    const { stdout, code } = await questCli(storeDir, io.env, ["list", "--json"]);
+    if (code !== 0) return new Set();
+    try {
+      return new Set(JSON.parse(stdout).filter((q) => q.parent !== undefined).map((q) => q.parent));
+    } catch {
+      return new Set();
+    }
+  };
+
   const startOne = (id) => {
     const promise = (async () => {
       let cwd = io.cwd;
@@ -570,8 +619,14 @@ async function runReady(storeDir, config, flags, io) {
   };
 
   for (;;) {
-    const ready = (await readyIds()).filter((id) => !done.has(id) && !inFlight.has(id));
+    const epics = await epicIds();
+    const ready = (await readyIds()).filter((id) => !done.has(id) && !inFlight.has(id) && !skippedEpics.has(id));
     for (const id of ready) {
+      if (epics.has(id)) {
+        skippedEpics.add(id);
+        io.errOut(`quest-run: quest ${id} is an epic (other quests name it as parent) — refusing to auto-dispatch it. Close it inline per $quest:orchestrate: verify its children, run the epic validation loop, then \`quest checkpoint ${id} --status complete\`. Never burn a worker run on an epic.`);
+        continue;
+      }
       if (inFlight.size >= parallel) break;
       startOne(id);
     }
@@ -626,6 +681,7 @@ export async function run(argv, io = {}) {
         "max-tokens": { type: "string" },
         "session-timeout": { type: "string" },
         "codex-sandbox": { type: "string" },
+        "codex-goal-mode": { type: "string" },
         "continue-session": { type: "boolean" },
         notify: { type: "string" },
         "dry-run": { type: "boolean" },

package/lib/store-github.mjs

@@ -20,6 +20,7 @@ import {
   ContractError,
   appendToSection,
   appendUnderCheckpoints,
+  assertReopen,
   assertTransition,
   lintRecord,
   makeCheckpoint,
@@ -267,12 +268,19 @@ export function listQuests(repo, env) {
   });
 }
 
-// Same readiness rule as store-local.readyQuests, over the remote list.
+// Same readiness rule as store-local.readyQuests, over the remote list —
+// including the epic gate: a quest with any non-terminal child (a quest whose
+// parent points at it, not in complete/cancelled) is never ready. Epics are
+// closed by the orchestrator inline, never auto-dispatched; a cancelled child
+// is terminal so it cannot wedge the epic forever.
 export function readyQuests(repo, env) {
   const all = listQuests(repo, env);
   const done = new Set(all.filter((q) => q.status === "complete").map((q) => q.id));
+  const openParents = new Set(
+    all.filter((q) => q.parent !== undefined && q.status !== "complete" && q.status !== "cancelled").map((q) => q.parent),
+  );
   return all
-    .filter((q) => q.status === "todo" && (q.depends_on ?? []).every((d) => done.has(d)))
+    .filter((q) => q.status === "todo" && !openParents.has(q.id) && (q.depends_on ?? []).every((d) => done.has(d)))
     .sort((a, b) => a.priority.localeCompare(b.priority) || a.id - b.id);
 }
 
@@ -372,10 +380,34 @@ export function cancelQuest(repo, id, reason, env) {
   return { front: { ...rec.front, status: "cancelled", updated } };
 }
 
+// Comment-first, mirroring cancelQuest's operation order: post the audited
+// reopen checkpoint, refresh the meta timestamp, then swap the label
+// (quest:complete → quest:in-progress) and reopen the issue via applyStatus.
+export function reopenQuest(repo, id, reason, env) {
+  if (!reason || !reason.trim()) throw new ContractError("reopen requires --reason", { hint: 'example: quest reopen 4 --reason "review found npm audit criticals"' });
+  const rec = reconstruct(viewIssue(repo, id, env));
+  assertReopen(rec.front.status);
+  const block = makeCheckpoint({
+    timestamp: nowIso(),
+    quest_status: "in_progress",
+    iteration: rec.checkpoints.length + 1,
+    changed: "reopened from complete",
+    validation_summary: "reopened for further work; no execution this entry",
+    reopen_reason: reason.trim(),
+  });
+  gh(["issue", "comment", String(id), "--repo", repo, "--body-file", "-"], { env, input: block });
+  const updated = nowIso();
+  writeStoredBody(repo, id, { ...rec.meta, updated }, rec.storedSections, env);
+  applyStatus(repo, id, rec.labels, rec.state, "in_progress", env);
+  return { front: { ...rec.front, status: "in_progress", updated }, checkpoints: [...rec.checkpoints, ...parseCheckpoints(block)] };
+}
+
 export function editQuest(repo, id, { addDoneWhen = [], addMilestone = [], addContext, rationale }, env) {
   if (!rationale || !rationale.trim()) throw new ContractError("edit requires --rationale (scope changes are recorded, per protocol)", { hint: "state why this is a compatible expansion of the Objective" });
   if (!addDoneWhen.length && !addMilestone.length && !addContext) throw new ContractError("nothing to add — pass --add-done-when, --add-milestone, or --add-context", { hint: "the Objective and existing Done-when items are immutable by design" });
   const rec = reconstruct(viewIssue(repo, id, env));
+  if (rec.front.status === "complete") throw new ContractError("cannot edit a complete quest", { hint: "reopen it first with `quest reopen <id> --reason`, then edit — or file a new quest" });
+  if (rec.front.status === "cancelled") throw new ContractError("cannot edit a cancelled quest", { hint: "cancelled is terminal — file a new quest instead" });
   let sections = rec.storedSections;
   for (const item of addDoneWhen) sections = appendToSection(sections, "## Done when", `- [ ] ${item}`);
   for (const item of addMilestone) sections = appendToSection(sections, "## Milestones", `- [ ] ${item}`, { createAfter: "## Validation loop" });

package/lib/store-local.mjs

@@ -4,7 +4,7 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync, statSync, appendFileSync } from "node:fs";
 import { join, basename } from "node:path";
-import { ContractError, appendToSection, appendUnderCheckpoints, assertTransition, lintRecord, makeCheckpoint, nowIso, parseRecord, recordFilename, renderBody, serializeRecord, CHECKPOINT_MARKER } from "./contract.mjs";
+import { ContractError, appendToSection, appendUnderCheckpoints, assertReopen, assertTransition, lintRecord, makeCheckpoint, nowIso, parseRecord, recordFilename, renderBody, serializeRecord, CHECKPOINT_MARKER } from "./contract.mjs";
 
 export class NotFoundError extends Error {
   constructor(id) {
@@ -85,8 +85,15 @@ export function listQuests(storeDir) {
 export function readyQuests(storeDir) {
   const all = listQuests(storeDir);
   const done = new Set(all.filter((q) => q.status === "complete").map((q) => q.id));
+  // Epic gate: a quest with any non-terminal child (a quest whose parent points
+  // at it, not in complete/cancelled) is never ready. Epics are closed by the
+  // orchestrator inline (see $quest:orchestrate), never auto-dispatched. A
+  // cancelled child is terminal so it cannot wedge the epic forever.
+  const openParents = new Set(
+    all.filter((q) => q.parent !== undefined && q.status !== "complete" && q.status !== "cancelled").map((q) => q.parent),
+  );
   return all
-    .filter((q) => q.status === "todo" && (q.depends_on ?? []).every((d) => done.has(d)))
+    .filter((q) => q.status === "todo" && !openParents.has(q.id) && (q.depends_on ?? []).every((d) => done.has(d)))
     .sort((a, b) => a.priority.localeCompare(b.priority) || a.id - b.id);
 }
 
@@ -162,10 +169,33 @@ export function cancelQuest(storeDir, id, reason) {
   });
 }
 
+// The audited path from complete back into the loop (mirrors cancelQuest, but
+// flips complete → in_progress and appends a real checkpoint carrying the
+// reopen_reason). Uses assertReopen, never assertTransition — a checkpoint can
+// never resurrect a complete quest; only this verb can.
+export function reopenQuest(storeDir, id, reason) {
+  if (!reason || !reason.trim()) throw new ContractError("reopen requires --reason", { hint: 'example: quest reopen 4 --reason "review found npm audit criticals"' });
+  return updateQuest(storeDir, id, (q) => {
+    assertReopen(q.front.status);
+    const block = makeCheckpoint({
+      timestamp: nowIso(),
+      quest_status: "in_progress",
+      iteration: q.checkpoints.length + 1,
+      changed: "reopened from complete",
+      validation_summary: "reopened for further work; no execution this entry",
+      reopen_reason: reason.trim(),
+    });
+    const body = appendUnderCheckpoints(q.body, block);
+    return { front: { ...q.front, status: "in_progress" }, body };
+  });
+}
+
 export function editQuest(storeDir, id, { addDoneWhen = [], addMilestone = [], addContext, rationale }) {
   if (!rationale || !rationale.trim()) throw new ContractError("edit requires --rationale (scope changes are recorded, per protocol)", { hint: "state why this is a compatible expansion of the Objective" });
   if (!addDoneWhen.length && !addMilestone.length && !addContext) throw new ContractError("nothing to add — pass --add-done-when, --add-milestone, or --add-context", { hint: "the Objective and existing Done-when items are immutable by design" });
   return updateQuest(storeDir, id, (q) => {
+    if (q.front.status === "complete") throw new ContractError("cannot edit a complete quest", { hint: "reopen it first with `quest reopen <id> --reason`, then edit — or file a new quest" });
+    if (q.front.status === "cancelled") throw new ContractError("cannot edit a cancelled quest", { hint: "cancelled is terminal — file a new quest instead" });
     let body = q.body;
     for (const item of addDoneWhen) body = appendToSection(body, "## Done when", `- [ ] ${item}`);
     for (const item of addMilestone) body = appendToSection(body, "## Milestones", `- [ ] ${item}`, { createAfter: "## Validation loop" });

package/lib/store.mjs

@@ -18,6 +18,7 @@ export function openStore(config, ctx = {}) {
       startQuest: (id) => github.startQuest(repo, id, env),
       appendCheckpoint: (id, cp) => github.appendCheckpoint(repo, id, cp, env),
       cancelQuest: (id, reason) => github.cancelQuest(repo, id, reason, env),
+      reopenQuest: (id, reason) => github.reopenQuest(repo, id, reason, env),
       editQuest: (id, changes) => github.editQuest(repo, id, changes, env),
       lintAll: () => github.lintAll(repo, env),
     };
@@ -31,6 +32,7 @@ export function openStore(config, ctx = {}) {
     startQuest: (id) => local.startQuest(dir, id),
     appendCheckpoint: (id, cp) => local.appendCheckpoint(dir, id, cp),
     cancelQuest: (id, reason) => local.cancelQuest(dir, id, reason),
+    reopenQuest: (id, reason) => local.reopenQuest(dir, id, reason),
     editQuest: (id, changes) => local.editQuest(dir, id, changes),
     lintAll: () => local.lintAll(dir),
   };

package/lib/workers.mjs

@@ -46,7 +46,7 @@ function workInstructions(id) {
   return (
     "Work quest " +
     id +
-    " per the /quest:work skill. The quest store is in this directory. " +
+    " per the $quest:work skill. The quest store is in this directory. " +
     "End every iteration by running quest show " +
     id +
     "."
@@ -242,20 +242,28 @@ const CODEX_CREATE_GOAL_CORRECTION = (id) =>
   "You did not invoke the create_goal tool — you narrated it instead. Call the create_goal tool now " +
   "(a real tool call, not prose) with the stopping condition, verify with get_goal, then continue working quest " +
   id +
-  " per /quest:work.";
+  " per $quest:work.";
 
 export const codex = {
   name: "codex",
 
   buildInvocation(questRecord, config, opts) {
     const { id } = opts;
-    const prompt =
-      "First step: Create a goal for this thread using the create_goal tool (not as prose) with this exact " +
-      "stopping condition: " +
-      stoppingCondition(id, opts.runStartIso) +
-      '. Verify with get_goal. Only call update_goal(status="complete") AFTER `quest checkpoint` succeeded.' +
-      "\n" +
-      workInstructions(id);
+    const goalMode = opts.codexGoalMode ?? "auto";
+    const condition = stoppingCondition(id, opts.runStartIso);
+    // Each mode gets its own complete, self-terminating instruction. Every mode —
+    // including `off` — names the `quest checkpoint` command, which is the sole
+    // machine-verifiable stop signal a headless worker must emit.
+    const goalLine =
+      goalMode === "off"
+        ? `Do not rely on goal tools. Treat this as the run contract — stopping condition: ${condition}. ` +
+          'Record progress with `quest checkpoint`; only report the quest complete AFTER `quest checkpoint` succeeded.'
+        : goalMode === "require"
+          ? `First step: Create a goal for this thread using the create_goal tool (not as prose) with this exact stopping condition: ${condition}. ` +
+            'Verify with get_goal. Only call update_goal(status="complete") AFTER `quest checkpoint` succeeded.'
+          : `If goal tools are available in this exec surface, create a goal for this thread using the create_goal tool with this exact stopping condition: ${condition}. ` +
+            'If you created a goal, verify with get_goal. Only call update_goal(status="complete") AFTER `quest checkpoint` succeeded.';
+    const prompt = goalLine + "\n" + workInstructions(id);
     const artifactsFile = codexArtifactsFile();
     const args = [
       "exec",
@@ -287,7 +295,7 @@ export const codex = {
     const args = ["exec", "resume"];
     if (sessionArg === "--last") args.push("--last");
     else args.push(sessionArg);
-    args.push(text, "--json", "-C", opts.cwd, "--skip-git-repo-check", "-o", artifactsFile, "--output-schema", opts.schemaPath);
+    args.push(text, "--json", "--skip-git-repo-check", "-o", artifactsFile, "--output-schema", opts.schemaPath);
     if (opts.effort) args.push("-c", `model_reasoning_effort=${opts.effort}`);
     const basePath = opts.env?.PATH ?? "";
     const env = { PATH: `${join(opts.pluginRoot, "bin")}:${basePath}` };
@@ -339,8 +347,10 @@ export const codex = {
     const first = await runSegment(this.buildInvocation(questRecord, config, opts));
     let sawGoal = codexUsedCreateGoal(first.events || []);
 
-    // Corrective resume: create_goal was narrated, not invoked.
-    if (!sawGoal) {
+    // Corrective resume only when the caller explicitly requires goal tools.
+    // In auto/off modes the documented Codex exec JSONL + output-schema path is
+    // the contract; goal tools are useful but not assumed available.
+    if (!sawGoal && opts.codexGoalMode === "require") {
       correctiveResume = true;
       resumes += 1;
       const corr = this.buildResume(questRecord, config, opts, "--last", CODEX_CREATE_GOAL_CORRECTION(opts.id));
@@ -348,6 +358,10 @@ export const codex = {
       if (codexUsedCreateGoal(cres.events || [])) sawGoal = true;
     }
 
+    if (opts.codexGoalMode === "require" && !sawGoal) {
+      return { session_id: sessionId, cost_usd: cost, tokens, invocations, sawGoal, correctiveResume, resumes, goalToolMissingRequired: true };
+    }
+
     // Same-session continuation while the stopping condition is unmet.
     while (resumes < CODEX_MAX_RESUMES) {
       const state = await ctx.readState();

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "quest-loop",
-  "version": "0.1.0",
+  "version": "0.3.2",
   "description": "Goal-loop engineering for coding agents: quest contracts, iterative execution with evidence checkpoints, Claude + Codex workers. Ships the `quest` store CLI and the `quest-run` headless runner.",
   "type": "module",
   "engines": { "node": ">=20" },
   "bin": {
-    "quest": "./bin/quest",
-    "quest-run": "./bin/quest-run"
+    "quest": "bin/quest",
+    "quest-run": "bin/quest-run"
   },
   "files": [
     "bin/",

package/skills/orchestrate/SKILL.md

@@ -21,54 +21,131 @@ trails, and escalations only where a human ruling is genuinely needed.
    quest list --ready --json   # the dispatch queue (deps met, priority order)
    quest runs --active         # headless runners that outlived prior sessions
    ```
-2. **Dispatch** each ready quest per its record:
-   - `worker: claude` → spawn the `quest-executor` subagent with the record's
-     `model`/`effort` as the dispatch override; prompt = "Work quest <id> per
-     /quest:work."
-   - `worker: codex`, parallel batches, or anything long-running → run
-     `quest-run <id>` in **background Bash** and keep working; you'll be
-     notified when it exits. Parallel file-disjoint quests:
-     `quest-run --ready --parallel 3` (add `--isolate worktree` when they touch
-     the same files).
-3. **Verify before you believe:** when a worker stops, run
+   For an implementation accepted from `$quest:plan` in Codex Plan Mode, stay in
+   this orchestrator role. Do not implement product code inline; create/lint the
+   quest records if needed, then dispatch workers.
+2. **Pin the wave with native goal mode:**
+   - In Codex, call `create_goal` with this stopping condition:
+     "every quest in the scoped wave shows complete, blocked, or cancelled in
+     `quest list --json` output"; verify it with `get_goal`.
+   - In Claude Code, start the turn with `/goal` using the same condition.
+   If native goal mode is unavailable, say so and keep the Quest checkpoint
+   trail as the hard stop signal; do not pretend a goal was set.
+3. **Dispatch** each ready quest per its record:
+   - In Codex, the default path is native subagents for both serial and
+     parallel waves. If `spawn_agent` is not visible, call `tool_search` once
+     for subagent tools before choosing any fallback. When available, spawn:
+     `agent_type: "quest-executor"` and prompt =
+     `First call create_goal with: quest <id> has a new checkpoint whose
+     quest_status is complete or blocked in \`quest show <id> --json\`; verify
+     with get_goal; work quest <id> per $quest:work; only call
+     update_goal(status="complete") after the checkpoint exists.`
+     If the agent template is missing, run `quest codex install-agents --scope
+     project` (or `$quest:setup`) before dispatching.
+   - In Claude Code, spawn the `quest-executor` subagent with the record's
+     `model`/`effort` as the dispatch override and prompt =
+     `/goal quest <id> has a new checkpoint whose quest_status is complete or
+     blocked in \`quest show <id> --json\`\nWork quest <id> per $quest:work.`
+   - Use `quest-run` only when native subagents are still unavailable after
+     `tool_search`, or when the user explicitly asks for headless/background
+     execution. Codex fallback must require goal mode:
+     `quest-run <id> --worker codex --codex-goal-mode require`. Headless
+     file-disjoint waves can use `quest-run --ready --parallel 3
+     --codex-goal-mode require` (add `--isolate worktree` when they touch the
+     same files). Claude headless runs already enter native `/goal` mode.
+4. **Verify before you believe:** when a worker stops, run
    `quest show <id> --json`. A stop WITHOUT a new checkpoint is a protocol
    violation — redispatch with exactly that instruction. Never accept a chat
    summary in place of a recorded checkpoint.
-4. **Review before accepting complete:** for non-trivial quests, spawn
-   `quest-reviewer` on the diff + checkpoint evidence. Every finding gets a
-   disposition: fixed / follow-up quest filed / rejected-with-reason.
-5. **Rule** (quote evidence, never adjectives):
+5. **Review before accepting complete:** for non-trivial quests, spawn
+   `quest-reviewer` on the diff + checkpoint evidence in the same harness. Give
+   it a goal: return an `accept` or `iterate` verdict with evidence. In Codex,
+   ask it to call `create_goal`/`get_goal` and only `update_goal` after the
+   verdict exists; in Claude Code, prefix the reviewer prompt with `/goal`.
+   Every finding gets a disposition: fixed / follow-up quest filed /
+   rejected-with-reason.
+6. **Rule** (quote evidence, never adjectives):
    - **accept** — the validation_summary's commands actually discharge the
      Done-when items.
    - **iterate-with-feedback** — send the specific gap back (continue the
      subagent, or `quest-run <id> --continue-session`).
-   - **split** — bigger than it looked → `/quest:plan` to decompose; cancel or
+   - **split** — bigger than it looked → `$quest:plan` to decompose; cancel or
      re-parent the original honestly.
    - **escalate-to-human** — surface human-only decisions verbatim. Never
      guess a ruling the human should make.
-6. **Wave done?** When `quest list --ready` empties and nothing is in flight:
-   run `/quest:retro` before starting the next wave.
+7. **Wave done?** When `quest list --ready` empties and nothing is in flight:
+   run `$quest:retro` before starting the next wave.
+
+## Closing an epic
+
+An epic is an ordinary quest that other quests name as `parent`. It is **never
+dispatched to a worker**: `quest list --ready` gates it out while any child is
+non-terminal, and `quest-run --ready` refuses it even once every child is
+terminal (a direct `quest-run <id>` on an epic still runs, but don't — it burns
+a worker on pure verification). Close it inline yourself, spending zero worker
+tokens:
+
+1. **Verify the children are genuinely done:**
+   ```bash
+   quest list --parent <id> --json   # is every child complete or cancelled?
+   ```
+   A `cancelled` child is terminal too — account for why it was dropped; it does
+   not block the epic and you do not wait on it.
+2. **Run the epic's own validation loop** (the integration-level check in its
+   record) and read each child's completion evidence — this is the real work of
+   closing an epic.
+3. **Record the verdict on the epic itself:**
+   ```bash
+   quest start <id>
+   quest checkpoint <id> --status complete \
+     --summary "epic closed inline — children #a #b #c verified, integration loop green" \
+     --validation "<epic validation loop> → <observed result>"
+   ```
+   The checkpoint must **enumerate each child and each epic Done-when item** with
+   its evidence — the same bar every quest meets, just discharged by you inline
+   rather than by a dispatched worker.
+
+## Reopening completed work
+
+When review (or reality) finds a defect in a quest you already marked
+**complete**, never hand-edit the status line and never redispatch a worker onto
+the terminal record — `quest-run` early-exits on a complete quest and journals a
+0-session no-op. Instead reopen it:
+
+```bash
+quest reopen <id> --reason "review found npm audit criticals after completion"
+```
+
+This flips `complete → in_progress` and appends an audited checkpoint carrying
+`reopen_reason`, so the loop keeps custody of the defect trail. Then dispatch the
+quest directly by id (`quest-run <id>` or a `quest-executor` subagent) — reopened
+quests are `in_progress`, so they do **not** re-appear in `quest list --ready`.
+Reopening a child of a **complete** parent epic is allowed (a stderr warning, not
+a block); you then rule whether the epic's completion verdict is falsified and,
+if so, reopen the epic too. `cancelled` is fully terminal — file a new quest.
 
 ## Autonomous waves
 
 For an unattended wave, pin your own session to the outcome with a native goal:
 
 ```
-/goal every quest in this wave shows complete or blocked in `quest list --json` output
+every quest in this wave shows complete, blocked, or cancelled in `quest list --json` output
 ```
 
-The harness then keeps you cycling until the wave is genuinely done.
+In Codex, use the native goal tool when available; in Claude Code, use
+`/goal <condition>`. The harness then keeps you cycling until the wave is
+genuinely done.
 
 ## Worked example
 
 ```bash
 quest list --ready --json     # → [{"id":12,"worker":"claude"…},{"id":13,"worker":"codex"…}]
-# 12 → dispatch quest-executor subagent (model/effort from the record)
-# 13 → background Bash: quest-run 13
+# 12 → spawn quest-executor with a child /goal or create_goal prompt
+# 13 → spawn quest-executor too; use quest-run only if native subagents are unavailable
 # …executor stops →
 quest show 12 --json          # new checkpoint? quest_status? evidence?
 # reviewer on 12's diff → findings dispositioned → accept
 ```
 
-**Next:** contracts weak? `/quest:plan` to fix them first. Wave finished?
-`/quest:retro`. Vocabulary and stop rules: `/quest:protocol`.
+**Next:** contracts weak? `$quest:plan` to fix them first. Wave finished?
+`$quest:retro`. Vocabulary and stop rules: `$quest:protocol`.

package/skills/orchestrate/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Orchestrate Quests"
   short_description: "Dispatch workers on ready quests, verify checkpoints, rule on evidence"
-  default_prompt: "Use $orchestrate to drive the ready quests to completion."
+  default_prompt: "Use $quest:orchestrate to drive the ready quests to completion."

package/skills/plan/SKILL.md

@@ -22,10 +22,41 @@ extra context.
 | Medium | 1 quest, dispatch an executor | needs iterations, fits one Objective |
 | Large | epic parent + child quests in waves | multiple objectives; order via `depends_on` |
 
+## Plan Mode handoff
+
+In Codex Plan Mode, do **not** implement product code after the user accepts a
+plan. Your role is to make the quest records real, then ask before orchestration:
+
+1. Create or confirm the quest records with `quest create` and `quest lint`.
+2. If the user accepted a plan and asked to implement it, your next role is
+   `$quest:orchestrate`, not `$quest:work`. Do not start editing product code in
+   the parent session.
+3. If the user only asked to create quests, ask whether to enter
+   `$quest:orchestrate` and dispatch the ready quests now. Do not silently
+   switch modes.
+4. In `$quest:orchestrate`, set the orchestrator goal for the wave, then spawn
+   goal-mode workers. If the user declines orchestration, stop after listing the
+   ready quest ids and validation commands.
+
+The parent session owns dispatch, checkpoint verification, reviewer rulings, and
+epic closure. The spawned executor owns implementation for exactly one quest.
+The parent session never uses `$quest:work <id>` after a Plan Mode handoff
+unless the user explicitly asks to bypass orchestration for a genuinely small
+single quest.
+
 For epics: create the parent first, then children with `--parent <id>` and
 `--depends-on` expressing the real order. `quest list --ready` becomes the
 dispatch queue — that is the whole wave mechanic.
 
+Keep the **epic itself thin**. Its Done-when is **integration-level only**: it
+checks that the children compose into a working whole (the end-to-end behavior,
+the parity gate, the shipped docs), never a restatement of each child's
+Done-when. Its milestones must **not mirror the children 1:1** — the children
+*are* the decomposition, so re-listing them in the epic body earns no worker and
+wastes review. Give the epic an objective, integration Done-when, and the
+validation loop the orchestrator runs to close it inline (it is never
+dispatched — see `$quest:orchestrate` "Closing an epic").
+
 ## Author the contract
 
 Every field earns its place:
@@ -42,8 +73,12 @@ Every field earns its place:
 - **Context**: files + symbols (`resolveConfig` in `lib/config.mjs`), related
   quests. NEVER bare line numbers — they rot.
 - **Out of scope**: the adjacent work you are explicitly not doing.
-- `--worker` / `--model` / `--effort` / `--max-iterations`: match the tier to
-  the difficulty; the defaults come from `.quests/config.json`.
+- `--worker`, `--model`, and `--effort`: always specify all three explicitly in
+  every `quest create` command you author. Pick them deliberately from the task's
+  risk, ambiguity, context size, and validation cost so the worker starts with
+  an intentional execution profile instead of inheriting blindly from defaults.
+- `--max-iterations`: match the loop budget to the difficulty; defaults in
+  `.quests/config.json` are fallback behavior, not a planning substitute.
 
 **Anti-patterns** (lint catches some, you catch the rest): adjective done-whens
 ("fast", "clean"); validation loops that are prose, not commands; objectives
@@ -52,7 +87,8 @@ hiding three objectives; context by line number; budgets so big they never bind.
 ## Worked example
 
 ```bash
-quest create --title "Add dark mode to settings" \
+quest create --worker codex --model gpt-5.5 --effort medium --max-iterations 4 \
+  --title "Add dark mode to settings" \
   --objective "The settings page offers a dark theme that persists across reloads." \
   --done-when "toggling theme switches the UI and survives reload" \
   --done-when "\`npm test\` passes including new theme tests" \
@@ -65,5 +101,6 @@ quest create --title "Add dark mode to settings" \
 quest lint 12   # always, before dispatch
 ```
 
-**Next:** dispatch with `/quest:orchestrate` (or work it yourself via
-`/quest:work <id>`). Rules and vocabulary: `/quest:protocol`.
+**Next:** dispatch with `$quest:orchestrate`. Only work it yourself via
+`$quest:work <id>` for genuinely small inline work outside Plan Mode and outside
+an accepted Plan Mode handoff. Rules and vocabulary: `$quest:protocol`.

package/skills/plan/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Plan Quests"
   short_description: "Turn an ask into evidence-checkable quest contracts"
-  default_prompt: "Use $plan to decompose this ask into quest contracts via `quest create`."
+  default_prompt: "Use $quest:plan to decompose this ask into quest contracts via `quest create`."