quest-loop 0.1.0 → 0.3.0

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.0",
   "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

@@ -22,11 +22,14 @@ trails, and escalations only where a human ruling is genuinely needed.
    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
+   - In Codex, prefer the native `quest-executor` custom agent for an
+     interactive single quest; prompt = "Work quest <id> per $quest:work." If
+     the agent 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 the same prompt.
+   - For headless Codex/Claude work, 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).
@@ -42,22 +45,72 @@ trails, and escalations only where a human ruling is genuinely needed.
      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.
+   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 or blocked 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
 
@@ -70,5 +123,5 @@ 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

@@ -26,6 +26,15 @@ 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:
@@ -65,5 +74,5 @@ 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` (or work it yourself via
+`$quest:work <id>`). 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`."

package/skills/protocol/SKILL.md

@@ -35,5 +35,5 @@ quest protocol
 - A `complete` checkpoint cites backticked commands in `validation_summary`
   and enumerates every Done-when item as Done / Blocked / Cancelled.
 
-**Next:** plan with `/quest:plan`, execute with `/quest:work`, drive with
-`/quest:orchestrate`, improve with `/quest:retro`.
+**Next:** plan with `$quest:plan`, execute with `$quest:work`, drive with
+`$quest:orchestrate`, improve with `$quest:retro`.

package/skills/protocol/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Quest Protocol"
   short_description: "The quest loop rules, checkpoint format, and vocabulary"
-  default_prompt: "Use $protocol to look up the exact quest loop rule before acting."
+  default_prompt: "Use $quest:protocol to look up the exact quest loop rule before acting."

package/skills/protocol/references/contract-spec.md

@@ -72,7 +72,7 @@ updated: 2026-07-07T14:00:00Z
 | `effort` | no | reasoning effort passed to the worker (e.g. `xhigh`); omitted = config default |
 | `max_iterations` | yes | positive integer (counts runner **sessions**) |
 | `max_cost` | no | USD number; omitted = uncapped |
-| `parent` | no | quest id (epic linking; children derived by scanning) |
+| `parent` | no | quest id (epic linking; children derived by scanning). A quest with children is an epic: excluded from `--ready` until every child is terminal (complete/cancelled), and closed by the orchestrator inline — never dispatched to a worker |
 | `depends_on` | no | list of quest ids (wave ordering) |
 | `created` / `updated` | yes | UTC ISO-8601 `…Z` |
 
@@ -135,7 +135,11 @@ Optional free-form note.
 
 - `quest_status` ∈ `in_progress | complete | blocked` — the only legal values.
 - `iteration` required; `pr`, `head_sha`, `failed_approaches`,
-  `compatible_expansion` optional.
+  `compatible_expansion`, `reopen_reason` optional.
+- `reopen_reason` is written only by `quest reopen`: it records why a `complete`
+  quest was legally sent back into the loop (`quest_status: in_progress`), so a
+  fresh session can see why a once-complete quest is in progress again. Old
+  parsers ignore it — `parseCheckpoints` accepts any `- key: value` line.
 - `validation_summary` required. When `quest_status: complete`, lint requires
   at least one backticked command in it (commands, not adjectives).
 - A checkpoint's `quest_status` drives the store `status` transition:
@@ -149,10 +153,15 @@ in_progress → complete        (checkpoint quest_status: complete)
 in_progress → blocked         (checkpoint quest_status: blocked)
 blocked → in_progress         (new checkpoint quest_status: in_progress)
 todo|in_progress|blocked → cancelled   (quest cancel --reason)
+complete → in_progress        (quest reopen --reason ONLY — never a checkpoint)
 ```
 
-Any other transition is illegal (exit 5). `complete` and `cancelled` are
-terminal.
+Any other transition is illegal (exit 5). `cancelled` is fully terminal.
+`complete` is terminal for **checkpoints** — a stray checkpoint can never
+resurrect it — but the `quest reopen <id> --reason` verb provides the one
+audited path back into the loop, flipping `complete → in_progress` and appending
+a checkpoint carrying `reopen_reason`. This is a separate `assertReopen` path in
+`lib/contract.mjs`, deliberately not part of the checkpoint transition table.
 
 ## GitHub backend mapping
 
@@ -161,7 +170,7 @@ terminal.
 | record | `quests/NNN-slug.md` | issue; body = same body sections |
 | orchestration metadata | frontmatter | `<!-- quest:meta -->` HTML block at top of body (same `key: value` lines) |
 | id | frontmatter `id` | issue number |
-| status | frontmatter | labels `quest:todo\|in-progress\|blocked\|complete\|cancelled` (+ marker label `quest`); issue state mirrored (complete → closed-completed, cancelled → closed-not-planned) |
+| status | frontmatter | labels `quest:todo\|in-progress\|blocked\|complete\|cancelled` (+ marker label `quest`); issue state mirrored (complete → closed-completed, cancelled → closed-not-planned, reopen → issue reopened + label swapped back to `quest:in-progress`) |
 | priority | frontmatter | labels `quest-p0\|p1\|p2` |
 | checkpoint | appended section | issue comment, identical bytes |
 | parent/child | child `parent:` | child meta `parent:` + epic body `## Children` task list (`- [ ] #12`) |

package/skills/protocol/references/protocol.md

@@ -1,7 +1,7 @@
 # The quest loop protocol
 
 This is the base protocol every quest execution follows. Local amendments (mined
-from retros, see `/quest:retro`) live in `.quests/amendments.md` and extend this
+from retros, see `$quest:retro`) live in `.quests/amendments.md` and extend this
 document — read both. `quest protocol` prints them together.
 
 ## Vocabulary
@@ -44,7 +44,11 @@ Each iteration:
 6. **Evaluate stop conditions.**
    - `complete` — every "Done when" item is enumerated as
      **Done / Blocked / Cancelled** with its evidence, and no new TODOs or
-     follow-up work remain inside this quest (file a new quest instead).
+     follow-up work remain inside this quest (file a new quest instead). If a
+     completed quest is later found defective, the one legal way back into the
+     loop is `quest reopen <id> --reason` (flips `complete → in_progress`,
+     appends an audited `reopen_reason` checkpoint) — never hand-edit a terminal
+     status line. `cancelled` stays fully terminal.
    - `blocked` — (a) two consecutive iterations failing on the same error,
      (b) a decision only a human can make, or (c) an unsatisfiable "Done when"
      — name the exact discrepancy and the corrected anchor; **never improvise
@@ -81,7 +85,7 @@ When reviewing a finished iteration or run, the orchestrator rules one of:
 - **accept** — the checkpoint's evidence actually satisfies the Done-when items
   it claims (quote the commands; never accept adjectives).
 - **iterate-with-feedback** — send the specific gap back to the executor.
-- **split** — the quest was bigger than it looked; decompose via `/quest:plan`.
+- **split** — the quest was bigger than it looked; decompose via `$quest:plan`.
 - **escalate-to-human** — human-only decisions are surfaced verbatim, never
   guessed.
 
@@ -90,4 +94,8 @@ When reviewing a finished iteration or run, the orchestrator rules one of:
 - **Small** — one quest, worked inline in the current session.
 - **Medium** — one quest dispatched to an executor (subagent or headless run).
 - **Large** — an epic (parent quest) with child quests in dependency waves via
-  `depends_on`; orchestrate wave by wave.
+  `depends_on`; orchestrate wave by wave. The epic itself is never dispatched to
+  a worker: it is gated out of `--ready` while any child is non-terminal, and
+  once the children are done the orchestrator closes it inline (verify children,
+  run the epic validation loop, checkpoint). Keep the epic contract
+  integration-level; its milestones must not mirror the children 1:1.

package/skills/retro/SKILL.md

@@ -46,5 +46,5 @@ quest amend --text "Treat a test that fails twice in one quest as a blocker to e
 quest protocol  # confirm the amendment now rides along
 ```
 
-**Next:** amendments feed every future `/quest:work` orient automatically.
-Start the next wave with `/quest:orchestrate`.
+**Next:** amendments feed every future `$quest:work` orient automatically.
+Start the next wave with `$quest:orchestrate`.

package/skills/retro/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Quest Retro"
   short_description: "Mine finished quest traces into numbered protocol amendments"
-  default_prompt: "Use $retro to turn this wave's traces into protocol amendments."
+  default_prompt: "Use $quest:retro to turn this wave's traces into protocol amendments."

package/skills/setup/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: setup
+description: Use when setting up, validating, updating, or troubleshooting Quest's native Codex plugin integration.
+argument-hint: "[doctor|install-agents]"
+---
+
+# Set up Quest for Codex
+
+Use this for Codex integration work, not for ordinary quest execution.
+
+## Doctor
+
+Check the installed Codex-facing state from the actual Codex surfaces:
+
+```bash
+quest codex doctor
+```
+
+This verifies the Codex CLI, installed `quest@quest` plugin version, hook parser
+health, neutral-directory skill roots, and whether `quest-executor` plus
+`quest-reviewer` are available as native Codex custom agents.
+
+## Install Native Agents
+
+Install the custom agents for this repository:
+
+```bash
+quest codex install-agents --scope project
+```
+
+Use user scope only when you want the agents available everywhere:
+
+```bash
+quest codex 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.
+
+## Update Installed Plugin
+
+Codex installs from marketplace snapshots. After updating or releasing Quest,
+refresh and reinstall, then start a new Codex thread:
+
+```bash
+codex plugin marketplace upgrade quest
+codex plugin add quest@quest
+quest codex doctor
+```
+
+If hooks changed, review/trust the updated hook definitions in Codex when
+prompted, then re-run:
+
+```bash
+codex debug prompt-input "noop"
+```

package/skills/setup/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Quest Setup"
+  short_description: "Validate and install Quest's native Codex integration"
+  default_prompt: "Use $quest:setup to validate Quest's Codex plugin install."
+
+policy:
+  allow_implicit_invocation: false

package/skills/work/SKILL.md

@@ -35,7 +35,7 @@ session can resume from.
      --summary "M2 done — <one line per milestone touched>" \
      --validation "\`npm test\` → 42 passed, 0 failed"
    ```
-6. **Check stop conditions** (see `/quest:protocol` for the full rules):
+6. **Check stop conditions** (see `$quest:protocol` for the full rules):
    - All Done-when items hold with evidence → final checkpoint with
      `--status complete`, whose `--note` enumerates EVERY Done-when item as
      Done / Blocked / Cancelled with its evidence.
@@ -69,5 +69,5 @@ quest show 12
 ```
 
 **Next:** finished or blocked → the orchestrator (or human) rules on your
-checkpoint — see `/quest:orchestrate`. Learned something protocol-worthy →
-mention it so `/quest:retro` can turn it into an amendment.
+checkpoint — see `$quest:orchestrate`. Learned something protocol-worthy →
+mention it so `$quest:retro` can turn it into an amendment.

package/skills/work/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Work a Quest"
   short_description: "Execute one quest iteratively to a checkpointed stop"
-  default_prompt: "Use $work to execute quest <id> per the quest protocol, ending in a recorded checkpoint."
+  default_prompt: "Use $quest:work to execute quest <id> per the quest protocol, ending in a recorded checkpoint."