dev-loops 0.6.0 → 0.7.2

package/.claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.6.0",
+  "version": "0.7.2",
   "description": "Agent-harness-agnostic dev-loop: agents, skills, and hooks for GitHub/Copilot-driven development loops.",
   "author": {
     "name": "Manuel Fittko",

package/.claude/agents/dev-loop.md

@@ -12,24 +12,25 @@ Your job is to provide the callable `dev-loop` public façade and route to the c
 
 ## Handoff envelope mandate (first action)
 
-The agent's first action after resolving authoritative state must be to build the handoff envelope via `buildDevLoopHandoffEnvelope()` from `@dev-loops/core`.
+The agent's first action after resolving authoritative state MUST be to build the handoff envelope via `buildDevLoopHandoffEnvelope()` from `@dev-loops/core`.
 
 The envelope is the primary handoff artifact — it is derived from resolver output, settings, and gate state, and it determines:
 - `requiredReads` — the canonical ordered list of files to load
 - `nextAction` — the bounded task to execute
-- `stopRules` — stop boundaries that must not be crossed without authorization
+- `stopRules` — stop boundaries that MUST NOT be crossed without authorization
 - `acceptance` — self-validation criteria for declaring completion
+- `sanctionedCommands` — the operation → wrapper command map (reads/edits/lifecycle), plus the forbidden and orchestrator-owned lists. Carried by DEFAULT on every build so you never re-derive which wrapper performs a GitHub/loop operation. Do NOT restate the map here — the single source of truth is `scripts/loop/sanctioned-commands.mjs`, surfaced verbatim in the envelope.
 
 **Construction sequence:**
 
-1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops@0.6.0 loop startup --issue <n>` for issues, or `npx dev-loops@0.6.0 loop startup --pr <n>` for PRs.
+1. Run the deterministic startup resolver to produce the authoritative state bundle: `npx dev-loops@0.7.2 loop startup --issue <n>` for issues, or `npx dev-loops@0.7.2 loop startup --pr <n>` for PRs.
 2. Pass the resolver output, resolved settings (merged from `.devloops` and `.pi/dev-loop/defaults.yaml`), and current gate state to `buildDevLoopHandoffEnvelope()`.
 3. **Validate the envelope** with `validateHandoffEnvelope()` before consuming any field. If validation returns `ok: false`, reject the handoff with the structured error — do not load requiredReads, do not execute nextAction, do not delegate.
 4. Read the envelope as the first artifact.
 5. Load every path listed in `requiredReads` (in order).
 6. Execute `nextAction` constrained by `stopRules` and `acceptance`.
 
-**The agent must not load skills, route packs, or delegate work before the envelope is built and read.** The derivation contract is [Workflow Handoff Contract](../skills/docs/workflow-handoff-contract.md).
+**The agent MUST NOT load skills, route packs, or delegate work before the envelope is built and read.** The derivation contract is [Workflow Handoff Contract](../skills/docs/workflow-handoff-contract.md).
 
 Prose task composition is a fallback only when `buildDevLoopHandoffEnvelope()` is unavailable (missing `@dev-loops/core` package) — the handoff contract in `skills/docs/workflow-handoff-contract.md` applies in that fallback case.
 
@@ -39,7 +40,7 @@ After the handoff envelope is built and read, load the `dev-loop` skill ([Dev Lo
 
 When that skill is not available at the expected path, resolve it from the skill installation layout (see the skill's "Skill asset path resolution" section).
 
-This entrypoint must stay thin: do not restate the skill's phase sequencing or workflow policy here. The envelope owns handoff sequencing; the skill owns routed strategy execution procedures.
+This entrypoint MUST stay thin: do not restate the skill's phase sequencing or workflow policy here. The envelope owns handoff sequencing; the skill owns routed strategy execution procedures.
 
 Treat the deterministic public routing contract in [Public Dev Loop Contract](../skills/docs/public-dev-loop-contract.md) and the `dev-loop` skill as the authority for choosing the current execution path. Do not force users to choose internal strategy names up front.
 
@@ -56,9 +57,9 @@ If local facts, GitHub facts, and helper/state-machine output do not agree well
 
 ## Subagent delegation
 
-All delegation must originate from the handoff envelope: the envelope's `nextAction`, `requiredReads`, `stopRules`, and `acceptance` define the bounded task. The envelope is passed to child subagents as their primary handoff artifact.
+All delegation MUST originate from the handoff envelope: the envelope's `nextAction`, `requiredReads`, `stopRules`, and `acceptance` define the bounded task. The envelope is passed to child subagents as their primary handoff artifact.
 
-The pi-subagents skill is parent-only, so delegated subagents do not receive orchestration patterns. This section exists as the minimal locally-enforced subset needed for correct delegation — it is not a restatement of the full policy. The `dev-loop` skill owns all procedural rules; this section only declares the invariants the agent must follow when it cannot defer to the skill:
+The pi-subagents skill is parent-only, so delegated subagents do not receive orchestration patterns. This section exists as the minimal locally-enforced subset needed for correct delegation — it is not a restatement of the full policy. The `dev-loop` skill owns all procedural rules; this section only declares the invariants the agent MUST follow when it cannot defer to the skill:
 - One writer thread; `async: true` default; `context: "fresh"` for reviewers.
 - No child subagent spawning beyond assigned fanout work.
 - Bounded tasks with concrete scope, exit conditions, and validation expectations.

package/.claude/agents/fixer.md

@@ -26,6 +26,7 @@ You are a focused review-fix agent. You take an existing pull request with revie
 
 ## Review Workflow
 1. Read unresolved review threads and any general review comments.
+   - Prefer the deterministic helper `scripts/github/list-review-threads.mjs --unresolved-only` to enumerate threads with their reply/resolve ids, rather than hand-writing a GraphQL query.
 2. Group related comments by file and identify the underlying concern behind each comment.
 3. Decide the best resolution for each concern: exact requested change, better alternative fix, explanation-only resolution, or escalation for expert judgment.
 4. If expert input is needed, stop before editing or resolving the thread and report the question, evidence, and options.

package/.claude/agents/refiner.md

@@ -38,7 +38,7 @@ For the active phase, require and produce:
 - if no explicit definition of done exists, add a `Proposed DoD` subsection before the matrix
 - explicit risks, watchpoints, and unresolved questions
 - validation steps and tests to write first
-- durable decisions that should be preserved in the phase doc
+- durable decisions that SHOULD be preserved in the phase doc
 - when the phase includes a bounded audit or scan: prioritized findings, the highest-value follow-up candidates, and an explicit statement of what the current phase will not rewrite or broaden
 - When an audit artifact is provided, treat it as a first-class planning input: summarize the audited scope, list prioritized findings, include the highest-value follow-up candidates, and classify each meaningful finding as exactly one of current-phase scope/AC, DoD expectation, explicit non-goal / defer, or risk/watchpoint
 - Do not invent audit findings when no audit artifact was provided
@@ -83,4 +83,4 @@ Return:
 
 ## Completion quality bar
 - A refinement is complete only when no item in the AC/DoD/Non-goal coverage matrix has status `Partial`, `Unmet`, or `Unverified`.
-- Any `Partial`, `Unmet`, or `Unverified` item means the refinement is still incomplete and must not be presented as ready.
+- Any `Partial`, `Unmet`, or `Unverified` item means the refinement is still incomplete and MUST NOT be presented as ready.

package/.claude/agents/review.md

@@ -30,10 +30,11 @@ This agent has two modes. The default mode is the full-PR review described in th
 
 You are in scoped angle-review mode when the invocation supplies a single review `<angle>` plus a gate-context artifact path (`tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json`, written by `scripts/github/write-gate-context.mjs`). Review like an external code reviewer hunting real bugs, not a process auditor: your job is to find concrete defects in the changed code and its call paths, not to remark that "there is no test" or that a doc section is thin. In that mode:
 
-- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle>` at startup. If it reports `fresh: false` (exit 1) or any error, refuse to proceed and report contamination — do not review on inherited context. "Fresh" here means your context is the **neutral builder artifact + your angle**, and explicitly NOT the main agent's conversation/state or a prior reviewer session's state. The injected neutral bundle is the INTENDED seed (allowed); main-agent or cross-session state bleed still fails closed.
+- **No worktree isolation (mandatory):** you review in the PR's actual worktree/head — the same checkout the gate-context preamble ran in — never a fresh isolated worktree. You are read-only and never mutate files, so isolation buys nothing; a fresh worktree would also be checked out from `main` (not the PR head) and would lack the gitignored, worktree-local gate-context bundle below, so you'd silently review the wrong stale tree (#1135).
+- **Fresh-context guard (mandatory):** run `node scripts/github/verify-fresh-review-context.mjs --scope <angle> --context-path <gate-context-artifact-path>` at startup. If it reports `fresh: false` (exit 1) or any error — including a missing gate-context artifact (`gateContextPresent: false`), which is the fail-closed signal that you're not in the right worktree/head — refuse to proceed and report the failure; do not review on inherited context or without seeded context. "Fresh" here means your context is the **neutral builder artifact + your angle**, and explicitly NOT the main agent's conversation/state or a prior reviewer session's state. The injected neutral bundle is the INTENDED seed (allowed); main-agent or cross-session state bleed still fails closed.
 - **Use the PROVIDED neutral bundle as your base; do NOT re-derive it from scratch:** the gate-context artifact carries the diff (`scope.diffPath`) and a deterministic, neutral adjacent-code bundle in `adjacentCode` (each changed file plus its 1-hop import in/out-edges, with a `stripped`/`truncated`/`missing` manifest). Start from this bundle — it is the build-once, work-deduped seed shared verbatim across all reviewers. Only widen (load more files) per-angle when the bundle genuinely lacks something your angle needs; do not re-build the whole diff/adjacent-code graph yourself.
 - **Single-angle scope:** review ONLY the supplied angle's concern. Read the gate-context artifact for the resolved angle set, change scope (branch, head SHA, touched files), acceptance-criteria pointer, and validation posture. Do not review other angles; the fan-in pass consolidates across angles.
-- **Read the FULL diff, not just hunks:** the gate-context artifact records `scope.diffPath` (a repo-relative path to the complete captured diff) and `scope.changedFiles` (full repo-relative paths). Read the entire diff from `scope.diffPath`; if it is `null` or missing, reconstruct it yourself with `git diff` against the change's base (e.g. `git diff origin/main...HEAD` or the branch/head SHA in `scope`). Do not review off a partial or summarized hunk list — you must see every changed line for your angle.
+- **Read the FULL diff, not just hunks:** the gate-context artifact records `scope.diffPath` (a repo-relative path to the complete captured diff) and `scope.changedFiles` (full repo-relative paths). Read the entire diff from `scope.diffPath`; if it is `null` or missing, reconstruct it yourself with `git diff` against the change's base (e.g. `git diff origin/main...HEAD` or the branch/head SHA in `scope`). Do not review off a partial or summarized hunk list — you MUST see every changed line for your angle.
 - **Reason about ADJACENT related code from the bundle first:** the `adjacentCode` bundle already includes the changed files' callers, callees, and imports (1-hop). Read those entries before opening anything else. For each changed function, trace the real call paths a defect would flow through, and confirm that caller and callee contracts still match (argument shapes, return shapes, error/null conventions, units). If the bundle truncated or stripped a file you need (see its `truncated`/`stripped` manifest), open that file directly to widen.
 - **Review ADVERSARIALLY — hunt concrete defects:** actively try to break the changed code. Hunt for edge cases, missing or wrong input validation, numeric coercion bugs (NaN, Infinity, floats where integers are assumed, negative values, string-to-number coercion), null/undefined handling, off-by-one and boundary conditions, mismatched caller/callee contracts, and dedup/identity bugs (wrong key, reference vs. value equality, unstable ordering). For every finding, give the concrete `file:line` plus the specific failing scenario or input that triggers the defect — not high-altitude "is there a test?" commentary.
 - **Strictly read-only, but WIDEN SCOPE when needed:** never edit files, stage, commit, push, request reviews, resolve threads, or post PR comments. Findings are returned via the output artifact only; fixes are applied later by the fix cycle, not by this agent. Because you are read-only, you MAY open any additional repository files required to judge your angle (callers, callees, contracts, sibling modules, configs, tests) — widening to read adjacent code is expected and safe. Record every file/module you consulted beyond the briefing's `changedFiles`/`diffPath` in the optional `contextWidened` field on your output artifact.
@@ -72,7 +73,7 @@ When NOT given an angle scope, behave exactly as the full-PR review agent descri
 - Prefer concrete findings with file references and impact over generic style commentary.
 - Distinguish clearly between must-fix findings, lower-severity risks, and informational gaps.
 - If the PR description omits required sections, is too thin to ground review without reconstructing intent from commits, or includes verdict status, evidence, or changelog content, treat that as a first-class review issue.
-- The review verdict must carry the acceptance-criteria and definition-of-done assessment in explicit markdown verification tables, including status plus concise evidence for each row.
+- The review verdict MUST carry the acceptance-criteria and definition-of-done assessment in explicit markdown verification tables, including status plus concise evidence for each row.
 - For follow-up reviews on the same PR, do not repost full AC/DoD tables: include only delta rows where status or supporting evidence changed, and explicitly note when there are no AC/DoD deltas.
 - When changelog coverage is needed, include a dedicated `## Changelog` section in the review verdict comment so post-merge automation can consume it without reading the PR description.
 

package/.claude/commands/{auto.md → loop-auto.md}

@@ -2,6 +2,6 @@
 description: "Run an autonomous dev loop on a GitHub issue until the human approval checkpoint."
 argument-hint: "<issue>"
 ---
-<!-- GENERATED from commands/auto.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-auto.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
 Run the `dev-loop` skill with the public intent `auto dev loop on issue $ARGUMENTS`. Resolve authoritative state first, then continue autonomously through the routed loop until a stop condition or the human approval checkpoint. Do not pick an internal strategy name yourself.

package/.claude/commands/loop-continue.md

@@ -0,0 +1,15 @@
+---
+description: "Continue the dev loop — the current in-progress board item, or a given issue/PR."
+argument-hint: "[issue|pr]"
+---
+<!-- GENERATED from commands/loop-continue.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Continue a dev loop. Two forms, both handed to the `dev-loop` skill — do NOT pick an internal strategy yourself.
+
+- With an argument (`$ARGUMENTS` is an issue or PR — `123`, `#123`, or a GitHub URL): run the `dev-loop` skill with the public intent `continue dev loop on $ARGUMENTS`. Resolve that artifact's authoritative state first, then route; ignore board position.
+
+- Bare (no `$ARGUMENTS`): resolve the single continue target from the board. Resolve the board's repo and project the same way the queue commands do, then run `node scripts/projects/resolve-active-board-item.mjs --repo <owner/name> --project <number>`. It continues the single **In Progress** item; if there is none, it picks the **HEAD of Next Up by position**. It fails closed (idle) when Next Up is empty, and still fails closed on multiple In-Progress items. It never pulls from Backlog.
+  - It returns `{ ok: true, target: { kind, number }, source }` (`source` is `"in-progress"` or `"next-up"`) → run the `dev-loop` skill with the public intent `continue dev loop on #<number>` (the resolved `target.number`), so the intent carries the concrete target instead of re-resolving board state.
+  - It returns `{ ok: false, reason }` when there are multiple in-progress items, or when there is nothing in progress **and** Next Up is empty → FAIL CLOSED: print the reason verbatim and instruct the user to run `/loop-continue #N` explicitly (or prioritize a Backlog item into Next Up). Do NOT guess, and never pick from Backlog.
+
+Resolve authoritative state before routing. All paths terminate in the dev-loop skill's `loop startup` → build-envelope → route, stopping at the human-approval checkpoint as usual. No new routing logic here.

package/.claude/commands/loop-enqueue.md

@@ -0,0 +1,22 @@
+---
+description: "Add an issue/PR to the auto queue, or quick-capture a freeform idea as a grilled issue and queue it."
+argument-hint: "<issue-or-pr-number | freeform text>"
+---
+<!-- GENERATED from commands/loop-enqueue.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Add work to the dev-loop queue. Parse `$ARGUMENTS` before acting. The project is auto-resolved from `.devloops` — never pass `--project` and never invent a project number. `<owner/repo>` resolves from the git remote at invocation, same as the other loop commands.
+
+1. **Argument parsing (fail-closed):**
+   - If `$ARGUMENTS` is empty, print `Error: missing argument — provide an issue/PR number or freeform text.` and stop without mutating anything.
+   - If `$ARGUMENTS` is a single integer token, take the **numeric path**. Otherwise take the **freeform path**.
+
+2. **Numeric path (existing issue/PR):**
+   - Run `node scripts/projects/add-queue-item.mjs --repo <owner/repo> --item <n>`.
+   - The script is idempotent and returns `{ ok, item: { status, alreadyPresent } }`. Report the resulting Status column and whether it was already present, e.g. `#<n> is in "Backlog" (already on the board)` or `#<n> added to "Backlog"`.
+   - Exit `3` means the issue/PR was not found (`ITEM_NOT_FOUND` / `CONTENT_NOT_FOUND`): print `Error: issue/PR #<n> not found.` and stop. Do not retry with a guessed project.
+
+3. **Freeform path (quick-capture a new idea):** run these steps in order.
+   1. **Confirm first — no mutation before approval.** Print a one-line preview of the issue to be created (`About to create issue: "<concise title>"`) and STOP for approval. Do not create the issue, grill, or enqueue anything until the human approves.
+   2. **Create the issue.** After approval, create a minimal GitHub issue from the text. The repo has no dedicated create-issue wrapper under `scripts/github/`; the sanctioned create path in this codebase is `gh issue create --repo <owner/repo> --assignee @me --title "<concise title>" --body "<freeform text>"` (the same path used by `skills/docs/issue-intake-procedure.md` and permitted by `skills/docs/main-agent-contract.md`). Title = a concise summary of the text; body = the verbatim freeform text.
+   3. **Grill it.** Run `/loop-grill <n> --auto` (delegates to the `loop-grill` skill). The skill writes a `## Grill findings` section back into the issue body and flags any unresolved items there, so they are visible before pickup. Do not re-implement grilling.
+   4. **Enqueue.** Run `node scripts/projects/add-queue-item.mjs --repo <owner/repo> --item <n>` to add the grill-annotated issue to the board, then report its Status column as in the numeric path. The `strategy: local-first` default is set repo-wide in `.devloops` (`strategy.default: local-first`), so the new issue is already local-first — this repo has no per-issue local-first label or body tag to apply, and you MUST NOT invent one.

package/.claude/commands/loop-grill.md

@@ -0,0 +1,17 @@
+---
+description: "Run a structured Socratic Q&A grill session against an issue or plan file before the dev loop starts."
+argument-hint: "<issue-number> | <path/to/plan.md> [--auto]"
+---
+<!-- GENERATED from commands/loop-grill.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Invoke the `loop-grill` skill with `$ARGUMENTS`. Parse the argument list before acting:
+
+1. **Argument parsing (fail-closed):**
+   - If `$ARGUMENTS` is empty, print `Error: missing argument — provide an issue number or a path to a plan file.` and stop without mutating anything.
+   - Split `$ARGUMENTS` into tokens. The first token is the target (`<issue-number>` or `<path/to/plan.md>`). Remaining tokens may include `--auto`. Any other flag produces `Error: unrecognized flag '<flag>' — only --auto is supported.` and stops.
+   - If the first token looks like an integer, treat it as a tracker-first issue number. Verify the issue exists via `gh issue view <n> --repo <owner/repo> --json number` (exit non-zero = not found); if not found, print `Error: issue #<n> not found.` and stop.
+   - If the first token is a path, resolve it relative to the repo root (or as absolute). If the file does not exist, print `Error: plan file not found: <path>` and stop.
+
+2. **Route to the `loop-grill` skill**, passing the resolved target and the `--auto` flag (if present). The skill owns all grilling logic: gap detection, interactive Q&A or auto-answer, write-back, and verdict emission.
+
+> **Note:** Interactive mode uses `AskUserQuestion` for bounded-choice gaps and plain text turns for open-ended gaps. `AskUserQuestion` is a Claude Code–native construct; use `--auto` as the portable fallback when running outside Claude Code.

package/.claude/commands/{info.md → loop-info.md}

@@ -2,6 +2,6 @@
 description: "Show the read-only dev-loop state summary for an issue or PR."
 argument-hint: "<issue|pr>"
 ---
-<!-- GENERATED from commands/info.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-info.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
-Resolve the read-only dev-loop state for `$ARGUMENTS` via the `loop info` shortcut — no full dev-loop run. If `$ARGUMENTS` is an issue number, run `npx dev-loops@0.6.0 loop info --issue $ARGUMENTS`; if it is a PR number, run `npx dev-loops@0.6.0 loop info --pr $ARGUMENTS`. Report the strategy, route, linked PR / branch, CI, and next action. Do not start implementation.
+Resolve the read-only dev-loop state for `$ARGUMENTS` via the `loop info` shortcut — no full dev-loop run. If `$ARGUMENTS` is an issue number, run `npx dev-loops@0.7.2 loop info --issue $ARGUMENTS`; if it is a PR number, run `npx dev-loops@0.7.2 loop info --pr $ARGUMENTS`. Report the strategy, route, linked PR / branch, CI, and next action. Do not start implementation.

package/.claude/commands/loop-queue-status.md

@@ -0,0 +1,24 @@
+---
+description: "Show the dev-loop queue board grouped by column."
+argument-hint: ""
+---
+<!-- GENERATED from commands/loop-queue-status.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+
+Show the dev-loop queue board. Takes no arguments; if `$ARGUMENTS` is non-empty, ignore it. `<owner/repo>` resolves from the git remote at invocation, same as the other loop commands, and the project is auto-resolved from `.devloops` — never pass `--project`.
+
+1. Run `node scripts/projects/list-queue-items.mjs --repo <owner/repo> --summary`. This is the sanctioned grouped-by-column path: it emits `{ ok, groups: { "<Status>": { count, items } } }` in board column order. Do not re-implement client-side grouping and do not pipe flat output through inline parsers.
+
+2. Render the result human-readably (not raw JSON). Walk `groups` in the order they are returned (board column order — Backlog, Next Up, In Progress, Done). For each column, print the column name with its count, then one line per item as `#<number> <title>`. Example:
+
+   ```
+   Backlog (2)
+     #1035 Add /loop-enqueue and /loop-queue-status commands
+     #1042 Fix article layout
+   Next Up (0)
+   In Progress (1)
+     #1041 Align nav/wrap/prose widths
+   Done (3)
+     ...
+   ```
+
+3. If every column is empty (all counts `0`), print `Queue is empty.` instead of a list.

package/.claude/commands/{start-spike.md → loop-start-spike.md}

@@ -2,7 +2,7 @@
 description: "Start a time-boxed dev-loop spike from a question (or a pre-authored findings file)."
 argument-hint: "<question> | --file <path>"
 ---
-<!-- GENERATED from commands/start-spike.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-start-spike.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
 Start a spike — a time-boxed exploration whose deliverable is a findings document. Two forms; both end in `loop startup --spike <path>` and hand the bundle to the `dev-loop` skill. Do NOT pick an internal strategy yourself, and do NOT invent new spike behavior — this wraps the shipped `--spike` intake (see `skills/docs/spike-mode-contract.md`).
 
@@ -11,6 +11,6 @@ Start a spike — a time-boxed exploration whose deliverable is a findings docum
   - Run `node scripts/refine/scaffold-spike-file.mjs --question "$ARGUMENTS" --out <path> --json`. It writes `## Question` (from the arg) plus stubbed `## Approach`/`## Findings` so the exploration scaffold passes `validateSpikeExplorationSections`; `## Recommendation` is left for the spike to fill in. It returns `{ ok: true, path, question }`.
   - Then run `node scripts/loop/resolve-dev-loop-startup.mjs --spike <path>` and route the resulting bundle through the `dev-loop` skill.
 
-- Pre-authored file (`$ARGUMENTS` begins with `--file <path>`): skip scaffolding and run `node scripts/loop/resolve-dev-loop-startup.mjs --spike <path>` directly, then route. The file must already carry the exploration scaffold (Question/Approach/Findings).
+- Pre-authored file (`$ARGUMENTS` begins with `--file <path>`): skip scaffolding and run `node scripts/loop/resolve-dev-loop-startup.mjs --spike <path>` directly, then route. The file MUST already carry the exploration scaffold (Question/Approach/Findings).
 
 The spike runs under the relaxed `gates.spike` profile. When the exploration reaches a `## Recommendation`, conclude it with `node scripts/refine/exit-spike.mjs --spike-file <path> --disposition <discard|graduate> [--plan-file <path>]` per the spike-mode contract — discard leaves nothing behind, graduate emits a plan file into the local-planning flow. No new routing logic here.

package/.claude/commands/{start.md → loop-start.md}

@@ -2,6 +2,6 @@
 description: "Start a dev loop on a GitHub issue."
 argument-hint: "<issue>"
 ---
-<!-- GENERATED from commands/start.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-start.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
 Run the `dev-loop` skill with the public intent `start dev loop on issue $ARGUMENTS`. Resolve authoritative state first, then route through the deterministic internal strategy. Do not pick an internal strategy name yourself.

package/.claude/commands/{status.md → loop-status.md}

@@ -1,6 +1,6 @@
 ---
 description: "Report dev-loop readiness (gh auth, git repo, subagent availability)."
 ---
-<!-- GENERATED from commands/status.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
+<!-- GENERATED from commands/loop-status.command.md by scripts/claude/generate-claude-assets.mjs — do not edit; edit the source and regenerate. -->
 
 Report dev-loop readiness for this environment. Check, in one pass: `gh` is installed (`command -v gh`), `gh` is authenticated (`gh auth status`), the working directory is inside a git repo (`git rev-parse --is-inside-work-tree`), and the `subagent`/`Agent` capability is available. Summarize which checks passed and the suggested next step. Read-only — do not start implementation.