quest-loop 0.3.4 → 0.3.6

package/lib/store-github.mjs

@@ -31,6 +31,7 @@ import {
   serializeRecord,
 } from "./contract.mjs";
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.mjs";
+import { computeQueue, lintGraphReferences } from "./graph.mjs";
 import { NotFoundError } from "./store-local.mjs";
 
 export class GhError extends Error {
@@ -268,20 +269,15 @@ export function listQuests(repo, env) {
   });
 }
 
-// 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.
+// Same shared queue rule as store-local.readyQuests, over the remote list.
+// readyQuests returns only worker-dispatchable quests; inline-close-ready epics
+// are exposed separately by queueState.
 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" && !openParents.has(q.id) && (q.depends_on ?? []).every((d) => done.has(d)))
-    .sort((a, b) => a.priority.localeCompare(b.priority) || a.id - b.id);
+  return queueState(repo, env).workerReady;
+}
+
+export function queueState(repo, env) {
+  return computeQueue(listQuests(repo, env));
 }
 
 export function createQuest(repo, defaults, fields, sections, env) {
@@ -433,14 +429,20 @@ export function editQuest(repo, id, { addDoneWhen = [], addMilestone = [], addCo
 
 export function lintAll(repo, env) {
   const results = [];
+  const valid = [];
   for (const issue of listIssues(repo, env)) {
     try {
       const rec = reconstruct(issue);
       results.push({ file: rec.file, id: rec.front.id, problems: lintRecord(rec, { filename: rec.file }) });
+      valid.push({ ...rec.front, file: rec.file });
     } catch (err) {
       results.push({ file: `#${issue.number}`, id: issue.number ?? null, problems: [err.message] });
     }
   }
+  const graphProblems = lintGraphReferences(valid);
+  for (const result of results) {
+    if (result.id !== null) result.problems.push(...(graphProblems.get(result.id) ?? []));
+  }
   return results;
 }
 

package/lib/store-local.mjs

@@ -5,6 +5,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync, statSync, appendFileSync } from "node:fs";
 import { join, basename } from "node:path";
 import { ContractError, appendToSection, appendUnderCheckpoints, assertReopen, assertTransition, lintRecord, makeCheckpoint, nowIso, parseRecord, recordFilename, renderBody, serializeRecord, CHECKPOINT_MARKER } from "./contract.mjs";
+import { computeQueue, lintGraphReferences } from "./graph.mjs";
 
 export class NotFoundError extends Error {
   constructor(id) {
@@ -83,18 +84,11 @@ 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" && !openParents.has(q.id) && (q.depends_on ?? []).every((d) => done.has(d)))
-    .sort((a, b) => a.priority.localeCompare(b.priority) || a.id - b.id);
+  return queueState(storeDir).workerReady;
+}
+
+export function queueState(storeDir) {
+  return computeQueue(listQuests(storeDir));
 }
 
 export function createQuest(storeDir, defaults, fields, bodySections) {
@@ -238,16 +232,22 @@ export function readRuns(storeDir) {
 
 export function lintAll(storeDir) {
   const results = [];
+  const valid = [];
   for (const file of recordFiles(storeDir)) {
     const text = readFileSync(join(questsDir(storeDir), file), "utf8");
     try {
       const record = parseRecord(text);
       const problems = lintRecord(record, { filename: file });
       results.push({ file, id: record.front.id, problems });
+      valid.push({ ...record.front, file });
     } catch (err) {
       results.push({ file, id: null, problems: [err.message] });
     }
   }
+  const graphProblems = lintGraphReferences(valid);
+  for (const result of results) {
+    if (result.id !== null) result.problems.push(...(graphProblems.get(result.id) ?? []));
+  }
   return results;
 }
 

package/lib/store.mjs

@@ -15,6 +15,7 @@ export function openStore(config, ctx = {}) {
       loadQuest: (id) => github.loadQuest(repo, id, env),
       listQuests: () => github.listQuests(repo, env),
       readyQuests: () => github.readyQuests(repo, env),
+      queueState: () => github.queueState(repo, env),
       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),
@@ -29,6 +30,7 @@ export function openStore(config, ctx = {}) {
     loadQuest: (id) => local.loadQuest(dir, id),
     listQuests: () => local.listQuests(dir),
     readyQuests: () => local.readyQuests(dir),
+    queueState: () => local.queueState(dir),
     startQuest: (id) => local.startQuest(dir, id),
     appendCheckpoint: (id, cp) => local.appendCheckpoint(dir, id, cp),
     cancelQuest: (id, reason) => local.cancelQuest(dir, id, reason),

package/lib/workers.mjs

@@ -353,7 +353,7 @@ export const codex = {
     if (!sawGoal && opts.codexGoalMode === "require") {
       correctiveResume = true;
       resumes += 1;
-      const corr = this.buildResume(questRecord, config, opts, "--last", CODEX_CREATE_GOAL_CORRECTION(opts.id));
+      const corr = this.buildResume(questRecord, config, opts, sessionId || "--last", CODEX_CREATE_GOAL_CORRECTION(opts.id));
       const cres = await runSegment(corr);
       if (codexUsedCreateGoal(cres.events || [])) sawGoal = true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quest-loop",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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" },

package/skills/orchestrate/SKILL.md

@@ -18,9 +18,16 @@ trails, and escalations only where a human ruling is genuinely needed.
 
 1. **Adopt state** (especially at session start):
    ```bash
-   quest list --ready --json   # the dispatch queue (deps met, priority order)
+   quest list --queue --json   # orchestration state: worker_ready + inline_close_ready_epics
    quest runs --active         # headless runners that outlived prior sessions
    ```
+   `worker_ready` is the worker dispatch queue (deps met, priority order);
+   `inline_close_ready_epics` is the set of epics you close yourself after
+   verifying children and the epic validation loop. `quest list --ready --json`
+   remains a dispatch-only shortcut for `worker_ready`.
+   When the checkout, plugin cache, and installed package may differ, run the
+   checkout binary (`./bin/quest`) or verify `PATH` with `quest --version`
+   before trusting queue or dispatch behavior.
    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.
@@ -31,7 +38,7 @@ trails, and escalations only where a human ruling is genuinely needed.
    - 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:
+3. **Dispatch** each `worker_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:
@@ -73,16 +80,17 @@ trails, and escalations only where a human ruling is genuinely needed.
      re-parent the original honestly.
    - **escalate-to-human** — surface human-only decisions verbatim. Never
      guess a ruling the human should make.
-7. **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 --queue --json` shows no `worker_ready` or
+   `inline_close_ready_epics`, and nothing is in flight, run `$quest:retro` (read skill `$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
+dispatched to a worker**: it does not belong in `worker_ready`, 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). Once it is closeable, `quest list --queue --json` reports it in
+`inline_close_ready_epics`; close it inline yourself, spending zero worker
 tokens:
 
 1. **Verify the children are genuinely done:**
@@ -119,7 +127,8 @@ 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`.
+quests are `in_progress`, so they do **not** re-appear in `worker_ready` or
+`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.
@@ -139,7 +148,7 @@ genuinely done.
 ## Worked example
 
 ```bash
-quest list --ready --json     # → [{"id":12,"worker":"claude"…},{"id":13,"worker":"codex"…}]
+quest list --queue --json     # → {"worker_ready":[{"id":12…},{"id":13…}],"inline_close_ready_epics":[]}
 # 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 →

package/skills/plan/SKILL.md

@@ -27,14 +27,16 @@ extra context.
 In Codex Plan Mode, do **not** implement product code after the user accepts a
 plan. The same parent agent/session that processes `$quest:plan` owns the
 handoff: make the quest records real, then adopt `$quest:orchestrate` by
-default.
+default when the user asks to implement the plan. The parent session never uses
+`$quest:work <id>` after a Plan Mode handoff unless the user explicitly asks to.
 
 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, the same parent
    session becomes `$quest:orchestrate`, not `$quest:work`. Do not start editing
-   product code in the parent session.
-3. In `$quest:orchestrate`, set the orchestrator goal for the wave, then spawn
-   goal-mode workers.
+   product code in the parent session. Read skill `$quest:orchestrate` and follow its rules for dispatching workers and closing epics inline.
+3. In `$quest:orchestrate`, inspect `quest list --queue --json`, set the
+   orchestrator goal for the wave, then spawn goal-mode workers for
+   `worker_ready` quests.
 4. Stop after listing the ready quest ids and validation commands only when the
    user explicitly asked for create-only/no-dispatch behavior such as "only
    create quests", "do not dispatch", or "stop after planning".
@@ -46,8 +48,15 @@ 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.
+`--depends-on` expressing the real order. `quest list --queue --json` shows the
+wave order: `worker_ready` quests are dispatched, and
+`inline_close_ready_epics` are closed inline by the orchestrator after children
+finish. `quest list --ready` remains only the dispatch shortcut for
+`worker_ready`.
+
+When local checkout, plugin cache, and installed package versions can differ,
+author and lint with the checkout binary (`./bin/quest`) or verify `PATH` with
+`quest --version` before relying on queue semantics or generated records.
 
 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,
@@ -104,4 +113,4 @@ quest lint 12   # always, before dispatch
 
 **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`.
+an accepted Plan Mode handoff, when user explicitly asked for it. Rules and vocabulary: `$quest:protocol`.

package/skills/setup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: setup
-description: Use when setting up, validating, updating, or troubleshooting Quest's native Codex or Claude plugin integration.
-argument-hint: "[doctor|install-agents|init]"
+description: Use when setting up, validating, updating, opening, or troubleshooting Quest's native Codex or Claude plugin integration.
+argument-hint: "[doctor|fix|open|install-agents|init]"
 ---
 
 # Set up Quest native agents
@@ -19,9 +19,10 @@ agent templates for both providers:
 - `.claude/agents/quest-reviewer.md`
 
 Use `quest init --no-agents` when you only want the quest store. If an existing
-project template conflicts, init fails before creating `.quests/`; inspect the
-file, run the explicit provider install command with `--force` only when you
-intend replacement, then rerun `quest init`.
+project template is stale and still identifies itself as Quest's agent, init
+replaces it. If another file conflicts, init fails before creating `.quests/`;
+inspect the file, run the explicit provider install command with `--force` only
+when you intend replacement, then rerun `quest init`.
 
 Project-scoped agent templates install at the Git repository root. For a nested
 quest store, use `quest init --no-agents` in the nested directory and set
@@ -32,7 +33,7 @@ quest store, use `quest init --no-agents` in the nested directory and set
 Check the installed Codex-facing state from the actual Codex surfaces:
 
 ```bash
-quest codex doctor
+quest codex doctor --fix
 ```
 
 This verifies the Codex CLI, `quest` binary on PATH, `multi_agent` and `goals`
@@ -45,7 +46,14 @@ use `quest-run --codex-goal-mode require` only as the headless fallback.
 Check the installed Claude-facing state from the actual Claude surfaces:
 
 ```bash
-quest claude doctor
+quest claude doctor --fix
+```
+
+Open an interactive provider only after the same repair/check gate passes:
+
+```bash
+quest codex open
+quest claude open
 ```
 
 ## Install Native Agents
@@ -70,9 +78,10 @@ quest claude install-agents --scope user
 ```
 
 If an existing file conflicts, inspect it first. Use `--force` only when you
-intend to replace that custom agent with Quest's bundled definition. Symlinked
-agent template files can be written through with `--force`; keep the provider
-agent directories themselves as real directories.
+intend to replace that custom agent with Quest's bundled definition. Stale
+Quest-owned templates are replaced without `--force`. Symlinked agent template
+files can be written through with `--force`; keep the provider agent directories
+themselves as real directories.
 
 ## Update Installed Plugin
 
@@ -82,7 +91,14 @@ refresh and reinstall, then start a new Codex thread:
 ```bash
 codex plugin marketplace upgrade quest
 codex plugin add quest@quest
-quest codex doctor
+quest codex doctor --fix
+```
+
+Claude updates through its plugin manager. After updating, restart Claude Code:
+
+```bash
+claude plugin update quest@quest
+quest claude doctor --fix
 ```
 
 If hooks changed, review/trust the updated hook definitions in Codex when