@ebullient/qrspi-x 0.10.0

package/dist/qrspi-x.mjs

@@ -0,0 +1,3532 @@
+#!/usr/bin/env node
+
+// src/command/Result.ts
+function toJson(result) {
+  const { exitCode, findings, wrote, text, ...fields } = result;
+  const json = { ...fields };
+  if (findings && findings.length > 0) {
+    json.findings = findings;
+  }
+  if (wrote && wrote.length > 0) {
+    json.wrote = wrote;
+  }
+  return json;
+}
+function ok(fields) {
+  return { exitCode: 0, ...fields };
+}
+function warn(fields, findings, wrote) {
+  return { exitCode: 3, ...fields, findings, wrote };
+}
+function blocked(findings, wrote) {
+  return { exitCode: 1, findings, wrote };
+}
+
+// src/command/Root.ts
+import { join as join5 } from "node:path";
+
+// src/workspace/Decisions.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+function decisionsPath(root) {
+  return join(root, "decisions.md");
+}
+function decisionsAt(root) {
+  async function add3(text) {
+    let existing = "";
+    try {
+      existing = await readFile(decisionsPath(root), "utf8");
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        throw err;
+      }
+    }
+    await mkdir(root, { recursive: true });
+    await writeFile(decisionsPath(root), `${existing}- ${text}
+`);
+  }
+  async function read3() {
+    try {
+      return await readFile(decisionsPath(root), "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return "";
+      }
+      throw err;
+    }
+  }
+  return { add: add3, read: read3 };
+}
+
+// src/workspace/Git.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+function gitAt(cwd) {
+  async function isClean() {
+    const { stdout } = await run("git", ["status", "--porcelain"], {
+      cwd
+    });
+    return stdout.trim().length === 0;
+  }
+  async function headSha() {
+    const { stdout } = await run("git", ["rev-parse", "HEAD"], { cwd });
+    return stdout.trim();
+  }
+  async function isAncestor(commit) {
+    try {
+      await run("git", ["merge-base", "--is-ancestor", commit, "HEAD"], {
+        cwd
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async function originRepo() {
+    try {
+      const { stdout } = await run(
+        "git",
+        ["remote", "get-url", "origin"],
+        {
+          cwd
+        }
+      );
+      return parseGitHubRepo(stdout);
+    } catch {
+      return void 0;
+    }
+  }
+  return { isClean, headSha, isAncestor, originRepo };
+}
+function parseGitHubRepo(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("Repository cannot be empty.");
+  }
+  const sshMatch = trimmed.match(
+    /^(?:ssh:\/\/)?git@([^:/]+)[:/]([^/]+)\/([^/]+?)(?:\.git)?$/
+  );
+  if (sshMatch) {
+    const [, host, owner, repo] = sshMatch;
+    if (host !== "github.com") {
+      throw new Error(
+        `Unsupported host "${host}". Only github.com is supported.`
+      );
+    }
+    return { owner, repo };
+  }
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+    try {
+      const url = new URL(trimmed);
+      if (url.hostname !== "github.com") {
+        throw new Error(
+          `Unsupported host "${url.hostname}". Only github.com is supported.`
+        );
+      }
+      const match = url.pathname.match(
+        /^\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/.*)?$/
+      );
+      if (match) {
+        return { owner: match[1], repo: match[2] };
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message.startsWith("Unsupported host")) {
+        throw e;
+      }
+      throw new Error(
+        `Invalid repository URL "${input}". Expected a github.com repository URL.`
+      );
+    }
+  }
+  const shorthandMatch = trimmed.match(
+    /^([^/#\s:]+)\/([^/#\s:]+?)(?:\.git)?$/
+  );
+  if (shorthandMatch) {
+    return { owner: shorthandMatch[1], repo: shorthandMatch[2] };
+  }
+  throw new Error(
+    `Invalid repository "${input}". Expected owner/repo shorthand or a github.com repository URL.`
+  );
+}
+
+// src/workspace/History.ts
+import { appendFile, mkdir as mkdir2, readFile as readFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+var DEFAULT_TAIL = 20;
+function historyPath(root) {
+  return join2(root, "history.jsonl");
+}
+function historyAt(root) {
+  async function readAll() {
+    let text;
+    try {
+      text = await readFile2(historyPath(root), "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return [];
+      }
+      throw err;
+    }
+    return text.split("\n").filter((line) => line.length > 0).map((line) => JSON.parse(line));
+  }
+  async function append(entry) {
+    await appendLine(entry);
+  }
+  async function appendLine(entry) {
+    const line = `${JSON.stringify({ ...entry, timestamp: (/* @__PURE__ */ new Date()).toISOString() })}
+`;
+    await mkdir2(root, { recursive: true });
+    await appendFile(historyPath(root), line);
+  }
+  async function conditionalAppend(filter, unless, entry) {
+    const entries = await readAll();
+    const matches = entries.filter(
+      (candidate) => Object.entries(filter).every(
+        ([key, value]) => candidate[key] === value
+      )
+    );
+    const last = matches[matches.length - 1];
+    if (last && Object.entries(unless).every(([key, value]) => last[key] === value)) {
+      return false;
+    }
+    await appendLine(entry);
+    return true;
+  }
+  async function read3(filters = {}) {
+    const { tail, all, ...fieldFilters } = filters;
+    let entries = await readAll();
+    for (const [key, value] of Object.entries(fieldFilters)) {
+      if (value === void 0) {
+        continue;
+      }
+      entries = entries.filter((entry) => entry[key] === value);
+    }
+    if (all) {
+      return entries;
+    }
+    const limit = tail ?? DEFAULT_TAIL;
+    return entries.slice(Math.max(entries.length - limit, 0));
+  }
+  async function isParked() {
+    const entries = await readAll();
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const kind = entries[i].kind;
+      if (kind === "note") {
+        continue;
+      }
+      return kind === "park";
+    }
+    return false;
+  }
+  return { append, conditionalAppend, read: read3, isParked };
+}
+
+// src/workspace/LoopState.ts
+import { mkdir as mkdir3, readFile as readFile4, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join4 } from "node:path";
+
+// src/workspace/Workspace.ts
+import { access, readdir, readFile as readFile3, stat } from "node:fs/promises";
+import { join as join3 } from "node:path";
+
+// src/workspace/ApproachDecision.ts
+function isDecided(text) {
+  const match = /^## Decision\s*\n([\s\S]*?)(?=\n## |\s*$)/m.exec(text);
+  if (!match) {
+    return false;
+  }
+  const body = match[1].trim();
+  return body !== "" && body !== "None.";
+}
+
+// src/workspace/PhaseFile.ts
+var STEP_MARKER_PATTERN = /^### Step \d+.*\r?\n(?:[ \t]*\r?\n)*[ \t]*- (\[[ ~x!]\])/gm;
+function parseSteps(text) {
+  const markers = [];
+  for (const match of text.matchAll(STEP_MARKER_PATTERN)) {
+    markers.push(match[1]);
+  }
+  return markers;
+}
+function isPhaseComplete(text) {
+  const markers = parseSteps(text);
+  return markers.length > 0 && markers.every((marker) => marker === "[x]");
+}
+
+// src/workspace/PlanTable.ts
+var STATUS_MARKERS = /* @__PURE__ */ new Set(["[ ]", "[~]", "[x]", "[!]"]);
+function parsePlanTable(text) {
+  const rows = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim().startsWith("|")) {
+      continue;
+    }
+    const cells = line.split("|").slice(1, -1).map((cell) => cell.trim());
+    if (cells.length < 6) {
+      continue;
+    }
+    const [phase, name, dependsOn, , , status] = cells;
+    if (phase === "Phase" || /^-+$/.test(phase)) {
+      continue;
+    }
+    if (!STATUS_MARKERS.has(status)) {
+      continue;
+    }
+    rows.push({
+      phase,
+      name,
+      dependsOn: parseDependsOn(dependsOn),
+      status
+    });
+  }
+  return rows;
+}
+var DependencyCycleError = class extends Error {
+  constructor(cycle) {
+    super(`Dependency cycle in plan.md: ${cycle.join(" -> ")}`);
+    this.cycle = cycle;
+    this.name = "DependencyCycleError";
+  }
+  cycle;
+};
+var UnknownPhaseError = class extends Error {
+  constructor(phaseId) {
+    super(`Unknown phase id: ${phaseId}`);
+    this.phaseId = phaseId;
+    this.name = "UnknownPhaseError";
+  }
+  phaseId;
+};
+function phaseGraphAt(rows) {
+  const byId = new Map(rows.map((row) => [row.phase, row]));
+  function isDone(phaseId, seen) {
+    if (seen.has(phaseId)) {
+      throw new DependencyCycleError([...seen, phaseId]);
+    }
+    const row = byId.get(phaseId);
+    if (!row) {
+      throw new UnknownPhaseError(phaseId);
+    }
+    if (incomplete(row)) {
+      return false;
+    }
+    const nextSeen = new Set(seen).add(phaseId);
+    return row.dependsOn.every((id) => isDone(id, nextSeen));
+  }
+  function isSatisfied(phaseId) {
+    const row = byId.get(phaseId);
+    if (!row) {
+      throw new UnknownPhaseError(phaseId);
+    }
+    return row.dependsOn.every((id) => isDone(id, /* @__PURE__ */ new Set([phaseId])));
+  }
+  function visitDependencies(phaseId, seen, out, visited) {
+    if (seen.has(phaseId)) {
+      throw new DependencyCycleError([...seen, phaseId]);
+    }
+    if (visited.has(phaseId)) {
+      return;
+    }
+    const row = byId.get(phaseId);
+    if (!row) {
+      throw new UnknownPhaseError(phaseId);
+    }
+    const nextSeen = new Set(seen).add(phaseId);
+    for (const depId of row.dependsOn) {
+      visitDependencies(depId, nextSeen, out, visited);
+    }
+    visited.add(phaseId);
+    if (incomplete(row)) {
+      out.push(phaseId);
+    }
+  }
+  function resolveScope(selector) {
+    const scope = parseSelector(selector, rows);
+    const out = [];
+    const visited = /* @__PURE__ */ new Set();
+    for (const phaseId of scope) {
+      visitDependencies(phaseId, /* @__PURE__ */ new Set(), out, visited);
+    }
+    return { scope, phaseIds: out };
+  }
+  return { rows, isSatisfied: (id) => isSatisfied(id), resolveScope };
+}
+function parseSelector(selector, rows) {
+  if (selector === "all") {
+    return rows.map((row) => row.phase);
+  }
+  if (selector.includes("..")) {
+    const [from, to] = selector.split("..");
+    const fromIndex = rows.findIndex((row) => row.phase === from);
+    const toIndex = rows.findIndex((row) => row.phase === to);
+    if (fromIndex === -1) {
+      throw new UnknownPhaseError(from);
+    }
+    if (toIndex === -1) {
+      throw new UnknownPhaseError(to);
+    }
+    if (toIndex < fromIndex) {
+      throw new Error(
+        `Invalid range "${selector}": "${to}" comes before "${from}" in plan.md.`
+      );
+    }
+    return rows.slice(fromIndex, toIndex + 1).map((row) => row.phase);
+  }
+  if (selector.includes(",")) {
+    return selector.split(",").map((id) => id.trim());
+  }
+  return [selector];
+}
+function parseDependsOn(cell) {
+  if (cell === "" || cell.toLowerCase() === "none") {
+    return [];
+  }
+  return cell.split(",").map((id) => id.trim()).filter(Boolean);
+}
+function completed(row) {
+  return row.status === "[x]";
+}
+function incomplete(row) {
+  return !completed(row);
+}
+
+// src/workspace/ReviewVerdict.ts
+function parseVerdict(text) {
+  const match = /^## Verdict:\s*(PASS WITH CONDITIONS|PASS|FAIL)\s*$/m.exec(
+    text
+  );
+  return match?.[1];
+}
+function isPending(text) {
+  return /^## Verdict:\s*PENDING\s*$/m.test(text);
+}
+function parseVerdictSummary(text) {
+  const match = /^## Verdict:.*\n+(.+)$/m.exec(text);
+  return match?.[1]?.trim();
+}
+
+// src/workspace/Workspace.ts
+var NoActivePhaseError = class extends Error {
+  constructor(blockedPhases) {
+    super(
+      `No active phase: every incomplete row is blocked on an unsatisfied dependency (${blockedPhases.join(", ")}).`
+    );
+    this.blockedPhases = blockedPhases;
+    this.name = "NoActivePhaseError";
+  }
+  blockedPhases;
+};
+function phaseFilePath(phaseId) {
+  return `plans/plan-phase-${phaseId}.md`;
+}
+function reviewPath(label) {
+  return `reviews/${label}.md`;
+}
+function reviewStem(opts) {
+  if (opts.phase === void 0) {
+    throw new Error("review labels require opts.phase.");
+  }
+  return opts.step !== void 0 ? `phase-${opts.phase}-step-${opts.step}` : `phase-${opts.phase}`;
+}
+function reReviewLabel(phaseId) {
+  return `${reviewStem({ phase: phaseId })}-r1`;
+}
+function parseReviewLabel(label) {
+  const phaseId = /^phase-([^-]+)(?:-|$)/.exec(label)?.[1];
+  return { phaseId, isReReview: /-r\d+$/.test(label) };
+}
+function workspaceAt(root) {
+  let graph;
+  const readGraph = () => {
+    if (!graph) {
+      graph = readFile3(join3(root, "plan.md"), "utf8").then(parsePlanTable).then(phaseGraphAt);
+    }
+    return graph;
+  };
+  async function deriveStep() {
+    if (await exists(join3(root, "plan.md"))) {
+      const { rows } = await readGraph();
+      const allDone = rows.every(completed);
+      return allDone ? "done" : "implement";
+    }
+    if (await exists(join3(root, "spec.md"))) {
+      return "plan";
+    }
+    if (await exists(join3(root, "approach.md"))) {
+      const text = await readFile3(join3(root, "approach.md"), "utf8");
+      return isDecided(text) ? "spec" : "shape";
+    }
+    if (await exists(join3(root, "research.md"))) {
+      return "research";
+    }
+    if (await exists(join3(root, "queries.md"))) {
+      return "research";
+    }
+    return "query";
+  }
+  async function isPhaseComplete2(phaseId) {
+    try {
+      const text = await readFile3(
+        join3(root, phaseFilePath(phaseId)),
+        "utf8"
+      );
+      return isPhaseComplete(text);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return false;
+      }
+      throw err;
+    }
+  }
+  async function checkProgress(phaseId) {
+    const { isSatisfied } = await readGraph();
+    const phaseText = await readFile3(
+      join3(root, phaseFilePath(phaseId)),
+      "utf8"
+    );
+    const markers = parseSteps(phaseText);
+    return {
+      dependenciesSatisfied: isSatisfied(phaseId),
+      total: markers.length,
+      complete: markers.filter((marker) => marker === "[x]").length
+    };
+  }
+  async function findActivePhase() {
+    const { rows, isSatisfied } = await readGraph();
+    const blockedPhases = [];
+    for (const row of rows) {
+      if (completed(row)) {
+        continue;
+      }
+      if (!isSatisfied(row.phase)) {
+        blockedPhases.push(row.phase);
+        continue;
+      }
+      const satisfaction = await checkProgress(row.phase);
+      const phaseFile = phaseFilePath(row.phase);
+      const phaseFileMtime = (await stat(join3(root, phaseFile))).mtime;
+      let staleInput;
+      if (await exists(join3(root, "spec.md"))) {
+        const specMtime = (await stat(join3(root, "spec.md"))).mtime;
+        if (phaseFileMtime < specMtime) {
+          staleInput = { phaseFile, specMtime, phaseFileMtime };
+        }
+      }
+      return {
+        phase: row.phase,
+        planProgress: `${satisfaction.complete}/${satisfaction.total} steps`,
+        staleInput
+      };
+    }
+    throw new NoActivePhaseError(blockedPhases);
+  }
+  async function nextLabel(type, opts = {}) {
+    if (type === "review") {
+      if (opts.phase === void 0) {
+        throw new Error("nextLabel('review') requires opts.phase.");
+      }
+      const stem = reviewStem(opts);
+      return nextInSequence(
+        join3(root, "reviews"),
+        stem,
+        (n) => `${stem}-r${n}`
+      );
+    }
+    if (type === "final") {
+      return nextInSequence(
+        join3(root, "reviews"),
+        "final",
+        (n) => `final-r${n}`
+      );
+    }
+    return nextNumbered(join3(root, "backups"), (n) => `${type}-${n}`);
+  }
+  async function nextFile(type, opts) {
+    const label = await nextLabel(type, opts);
+    return type === "review" || type === "final" ? reviewPath(label) : `backups/${label}.md`;
+  }
+  async function lastLabel(type, opts = {}) {
+    if (type === "review") {
+      if (opts.phase === void 0) {
+        throw new Error("lastLabel('review') requires opts.phase.");
+      }
+      const stem = reviewStem(opts);
+      return lastInSequence(
+        join3(root, "reviews"),
+        stem,
+        (n) => `${stem}-r${n}`
+      );
+    }
+    return lastInSequence(
+      join3(root, "reviews"),
+      "final",
+      (n) => `final-r${n}`
+    );
+  }
+  async function lastFile(type, opts) {
+    const label = await lastLabel(type, opts);
+    return label === void 0 ? void 0 : reviewPath(label);
+  }
+  async function pendingReviewLabel(phaseId) {
+    const label = await lastLabel("review", { phase: phaseId });
+    if (label === void 0) {
+      return void 0;
+    }
+    const text = await readFile3(join3(root, reviewPath(label)), "utf8");
+    return isPending(text) ? label : void 0;
+  }
+  async function resolveScope(selector) {
+    const { resolveScope: resolve2 } = await readGraph();
+    return resolve2(selector);
+  }
+  async function isPhaseDone(phaseId) {
+    const { rows } = await readGraph();
+    const row = rows.find((r) => r.phase === phaseId);
+    if (!row) {
+      throw new UnknownPhaseError(phaseId);
+    }
+    return completed(row);
+  }
+  async function reviewExists(label) {
+    return exists(join3(root, reviewPath(label)));
+  }
+  return {
+    deriveStep,
+    isPhaseComplete: isPhaseComplete2,
+    checkProgress,
+    findActivePhase,
+    nextLabel,
+    nextFile,
+    lastLabel,
+    lastFile,
+    pendingReviewLabel,
+    resolveScope,
+    isPhaseDone,
+    reviewExists
+  };
+}
+async function usedStems(dir) {
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    names = [];
+  }
+  return new Set(names.map((name) => name.replace(/\.md$/, "")));
+}
+async function nextInSequence(dir, bareLabel, nth) {
+  const used = await usedStems(dir);
+  if (!used.has(bareLabel)) {
+    return bareLabel;
+  }
+  for (let n = 1; ; n++) {
+    const candidate = nth(n);
+    if (!used.has(candidate)) {
+      return candidate;
+    }
+  }
+}
+async function lastInSequence(dir, bareLabel, nth) {
+  const used = await usedStems(dir);
+  if (!used.has(bareLabel)) {
+    return void 0;
+  }
+  let last = bareLabel;
+  for (let n = 1; ; n++) {
+    const candidate = nth(n);
+    if (!used.has(candidate)) {
+      return last;
+    }
+    last = candidate;
+  }
+}
+async function nextNumbered(dir, nth) {
+  const used = await usedStems(dir);
+  for (let n = 1; ; n++) {
+    const candidate = nth(n);
+    if (!used.has(candidate)) {
+      return candidate;
+    }
+  }
+}
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/workspace/LoopState.ts
+var LoopAlreadyRunningError = class extends Error {
+  constructor() {
+    super(
+      "A loop is already running; stop or abandon it before starting another."
+    );
+    this.name = "LoopAlreadyRunningError";
+  }
+};
+var RepairAlreadySpentError = class extends Error {
+  constructor(phaseId) {
+    super(`Phase ${phaseId}'s one --loop repair attempt is already spent.`);
+    this.phaseId = phaseId;
+    this.name = "RepairAlreadySpentError";
+  }
+  phaseId;
+};
+function loopStatePath(root) {
+  return join4(root, "loop-state.json");
+}
+function loopStateAt(root, workspace) {
+  async function readState() {
+    let text;
+    try {
+      text = await readFile4(loopStatePath(root), "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return void 0;
+      }
+      throw err;
+    }
+    return JSON.parse(text);
+  }
+  async function writeState(state) {
+    await mkdir3(root, { recursive: true });
+    await writeFile2(loopStatePath(root), JSON.stringify(state, null, 2));
+  }
+  async function deleteState() {
+    await rm(loopStatePath(root), { force: true });
+  }
+  async function repairSpent(phaseId) {
+    return workspace.reviewExists(reReviewLabel(phaseId));
+  }
+  async function start2(selector) {
+    if (await readState()) {
+      throw new LoopAlreadyRunningError();
+    }
+    const { scope, phaseIds } = await workspace.resolveScope(selector);
+    await writeState({
+      scope,
+      phaseIds,
+      cycle: 0,
+      phaseId: phaseIds[0],
+      bases: {},
+      conditions: []
+    });
+    return phaseIds;
+  }
+  async function advance2() {
+    const state = await readState();
+    if (!state) {
+      return;
+    }
+    if (!await workspace.isPhaseDone(state.phaseId)) {
+      return;
+    }
+    const nextCycle = state.cycle + 1;
+    if (nextCycle >= state.phaseIds.length) {
+      await deleteState();
+      return;
+    }
+    await writeState({
+      ...state,
+      cycle: nextCycle,
+      phaseId: state.phaseIds[nextCycle],
+      inFlight: void 0,
+      checkpoint: void 0
+    });
+  }
+  async function writeInFlight(task, phaseId, opts = {}) {
+    const state = await readState();
+    if (!state) {
+      return;
+    }
+    if (task === "repair" && await repairSpent(phaseId)) {
+      throw new RepairAlreadySpentError(phaseId);
+    }
+    const bases = { ...state.bases };
+    if ((task === "implement" || task === "review") && opts.baseSha !== void 0) {
+      if (opts.resetBase) {
+        bases[phaseId] = opts.baseSha;
+      } else {
+        bases[phaseId] ??= opts.baseSha;
+      }
+    }
+    await writeState({
+      ...state,
+      bases,
+      inFlight: { task, phaseId, label: opts.label }
+    });
+  }
+  async function clearInFlight() {
+    const state = await readState();
+    if (!state) {
+      return;
+    }
+    await writeState({ ...state, inFlight: void 0 });
+  }
+  async function updateCheckpoint(phaseId, label, verdict) {
+    const state = await readState();
+    if (!state) {
+      return;
+    }
+    const withoutPhase = state.conditions.filter(
+      (c) => c.phaseId !== phaseId
+    );
+    const conditions = verdict === "PASS WITH CONDITIONS" ? [...withoutPhase, { phaseId, label }] : verdict === "PASS" ? withoutPhase : state.conditions;
+    await writeState({
+      ...state,
+      checkpoint: { phaseId, label, verdict },
+      conditions
+    });
+  }
+  async function stop2(reason) {
+    const state = await readState();
+    if (!state || state.stoppedReason === reason) {
+      return;
+    }
+    await writeState({ ...state, stoppedReason: reason });
+  }
+  async function ok2() {
+    const state = await readState();
+    if (!state) {
+      return;
+    }
+    await writeState({ ...state, stoppedReason: void 0 });
+  }
+  async function abandon2() {
+    await deleteState();
+  }
+  async function status() {
+    const state = await readState();
+    if (!state) {
+      return void 0;
+    }
+    const base = {
+      scope: state.scope,
+      phaseIds: state.phaseIds,
+      cycle: state.cycle,
+      phaseId: state.phaseId,
+      stoppedReason: state.stoppedReason,
+      checkpoint: state.checkpoint,
+      conditions: state.conditions
+    };
+    if (state.stoppedReason !== void 0) {
+      return { ...base, action: "acknowledge-required" };
+    }
+    const baseSha = state.bases[state.phaseId];
+    const diff = baseSha ? `git diff ${baseSha}..HEAD` : void 0;
+    if (!state.checkpoint) {
+      const implemented = await workspace.isPhaseComplete(state.phaseId);
+      if (!implemented) {
+        return { ...base, action: "implement" };
+      }
+      const inFlightLabel = state.inFlight?.task === "review" && state.inFlight.phaseId === state.phaseId ? state.inFlight.label : void 0;
+      const label = inFlightLabel ?? await workspace.pendingReviewLabel(state.phaseId) ?? await workspace.nextLabel("review", {
+        phase: state.phaseId
+      });
+      return { ...base, action: "review", label, diff };
+    }
+    if (state.checkpoint.verdict === "PASS" || state.checkpoint.verdict === "PASS WITH CONDITIONS") {
+      return { ...base, action: "advance" };
+    }
+    const reReview = reReviewLabel(state.phaseId);
+    if (state.checkpoint.label === reReview) {
+      return { ...base, action: "stop" };
+    }
+    const reReviewLaunched = await workspace.reviewExists(reReview);
+    if (!reReviewLaunched) {
+      return {
+        ...base,
+        action: "repair",
+        review: reviewPath(state.checkpoint.label)
+      };
+    }
+    return { ...base, action: "re-review", label: reReview, diff };
+  }
+  return {
+    start: start2,
+    advance: advance2,
+    writeInFlight,
+    clearInFlight,
+    updateCheckpoint,
+    stop: stop2,
+    ok: ok2,
+    status,
+    abandon: abandon2,
+    read: readState
+  };
+}
+
+// src/command/Root.ts
+function resolveRoot(project, feature) {
+  return join5(project, "qrspi", feature);
+}
+function resolveServices(root, project, overrides = {}) {
+  const workspace = overrides.workspace ?? workspaceAt(root);
+  return {
+    workspace,
+    loopState: overrides.loopState ?? loopStateAt(root, workspace),
+    history: overrides.history ?? historyAt(root),
+    decisions: overrides.decisions ?? decisionsAt(root),
+    git: overrides.git ?? gitAt(project)
+  };
+}
+var commonOptions = [
+  {
+    flag: "--feature <feature>",
+    required: true,
+    description: "The feature workspace under ./qrspi/."
+  },
+  {
+    flag: "--project <path>",
+    required: false,
+    description: "The project root holding ./qrspi/; defaults to the current directory."
+  }
+];
+
+// src/command/decision.ts
+var addHelp = {
+  name: "add",
+  summary: "Append <why> verbatim as one Markdown bullet to decisions.md.",
+  flags: [
+    ...commonOptions,
+    {
+      flag: "--text <why>",
+      required: true,
+      description: "The decision and its rationale, verbatim."
+    }
+  ],
+  example: 'qrspi-x decision add --text "Skipping Shape: this feature is a one-file fix." --feature widget --project .'
+};
+var readHelp = {
+  name: "read",
+  summary: "Print decisions.md verbatim.",
+  flags: [...commonOptions],
+  example: "qrspi-x decision read --feature widget --project ."
+};
+var help = {
+  name: "decision",
+  summary: "Durable rationale (why): add-only, read verbatim.",
+  actions: [addHelp, readHelp]
+};
+async function add(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { decisions } = resolveServices(root, opts.project, services);
+  await decisions.add(opts.text);
+  return ok();
+}
+async function read(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { decisions } = resolveServices(root, opts.project, services);
+  return decisions.read();
+}
+
+// src/command/Help.ts
+function renderHelp(help10, action) {
+  if (action) {
+    const found = help10.actions?.find((a) => a.name === action);
+    if (!found) {
+      return `Unknown action "${action}" for "${help10.name}".`;
+    }
+    return renderAction(help10.name, found);
+  }
+  return renderCommand(help10);
+}
+function renderToolHelp(commands) {
+  const lines = ["Commands:"];
+  for (const c of commands) {
+    lines.push(`  ${c.name} - ${c.summary} (qrspi-x --help ${c.name})`);
+  }
+  lines.push(
+    "",
+    "Output:",
+    "  Commands normally print JSON to stdout.",
+    "  decision read, history read, next-file, and import print bare content or a path.",
+    "",
+    "Exit codes:",
+    "  0 success, 1 blocked/refused, 2 usage error, 3 usable result with findings, 4 unexpected error."
+  );
+  return lines.join("\n");
+}
+function renderCommand(help10) {
+  const lines = [help10.name, "", help10.summary];
+  if (help10.usage) {
+    lines.push("", "Usage:", `  ${help10.usage}`);
+  }
+  if (help10.flags && help10.flags.length > 0) {
+    lines.push("", "Flags:", ...renderFlags(help10.flags));
+  }
+  if (help10.actions && help10.actions.length > 0) {
+    lines.push("", "Actions:");
+    for (const a of help10.actions) {
+      lines.push(
+        `  ${a.name} - ${a.summary} (qrspi-x --help ${help10.name} ${a.name})`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+function renderAction(commandName, action) {
+  const lines = [`${commandName} ${action.name}`, "", action.summary];
+  if (action.usage) {
+    lines.push("", "Usage:", `  ${action.usage}`);
+  }
+  if (action.flags && action.flags.length > 0) {
+    lines.push("", "Flags:", ...renderFlags(action.flags));
+  }
+  const examples = action.examples ?? (action.example ? [action.example] : []);
+  if (examples.length > 0) {
+    lines.push(
+      "",
+      examples.length === 1 ? "Example:" : "Examples:",
+      ...examples.map((example) => `  ${example}`)
+    );
+  }
+  return lines.join("\n");
+}
+function renderFlags(flags) {
+  const lines = [];
+  for (const f of flags) {
+    lines.push(`  ${f.flag}`);
+    const tag = f.required ? "required" : "optional";
+    lines.push(`      (${tag}) ${f.description}`);
+  }
+  return lines;
+}
+
+// src/command/history.ts
+var addHelp2 = {
+  name: "add",
+  summary: "Append a selective 'what happened' entry to history.jsonl.",
+  flags: [
+    ...commonOptions,
+    {
+      flag: "--text <what happened>",
+      required: true,
+      description: "The fact worth recording, verbatim."
+    }
+  ],
+  example: 'qrspi-x history add --text "Shape skipped" --feature widget --project .'
+};
+var readHelp2 = {
+  name: "read",
+  summary: "Print matching history.json entries verbatim, as a JSON array.",
+  flags: [
+    ...commonOptions,
+    {
+      flag: "--tail <N>",
+      required: false,
+      description: "The last N matching entries. Default when neither --tail nor --all is given (N=20)."
+    },
+    {
+      flag: "--all",
+      required: false,
+      description: "Every matching entry, no limit. Mutually exclusive with --tail."
+    },
+    {
+      flag: "--kind <task>",
+      required: false,
+      description: "Only entries whose kind matches (e.g. review, loop)."
+    },
+    {
+      flag: "--phase <N>",
+      required: false,
+      description: "Only entries tagged with that phase."
+    }
+  ],
+  example: "qrspi-x history read --kind review --phase 2 --tail 5 --feature widget --project ."
+};
+var help2 = {
+  name: "history",
+  summary: "Selective timeline (what happened): add-only, filterable read.",
+  actions: [addHelp2, readHelp2]
+};
+async function add2(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { history } = resolveServices(root, opts.project, services);
+  await history.append({ kind: "note", text: opts.text });
+  return ok();
+}
+async function read2(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { history } = resolveServices(root, opts.project, services);
+  return history.read({
+    tail: opts.tail,
+    all: opts.all,
+    kind: opts.kind,
+    phase: opts.phase
+  });
+}
+
+// src/command/import.ts
+import { execFile as nodeExecFile } from "node:child_process";
+import { access as access2, mkdir as mkdir4, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join6 } from "node:path";
+import { promisify as promisify2 } from "node:util";
+var defaultRun = promisify2(nodeExecFile);
+var help3 = {
+  name: "import",
+  summary: "Fetch a GitHub issue or pull request into request.md.",
+  usage: "qrspi-x import <number> [--feature <name>] [--repo <owner/repo | url>] [--project <path>]",
+  flags: [
+    {
+      flag: "<number>",
+      required: true,
+      description: "GitHub issue or PR number (e.g. 42 or #42)."
+    },
+    {
+      flag: "--feature <name>",
+      required: false,
+      description: "Explicit feature name instead of default gh-<repo>-<n>."
+    },
+    {
+      flag: "--repo <owner/repo | url>",
+      required: false,
+      description: "Target repo (shorthand or URL); defaults to project's git origin remote."
+    },
+    {
+      flag: "--project <path>",
+      required: false,
+      description: "The project root holding ./qrspi/; defaults to the current directory."
+    }
+  ]
+};
+async function runImport(opts, services = {}) {
+  const issueNumber = parseIssueNumber(opts.number);
+  if (issueNumber === void 0) {
+    return {
+      exitCode: 1,
+      text: `Invalid issue number "${opts.number}".
+Provide a positive issue or pull request number (e.g. 42 or #42).`
+    };
+  }
+  let explicitRepo;
+  if (opts.repo) {
+    try {
+      explicitRepo = parseGitHubRepo(opts.repo);
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      if (message.startsWith("Unsupported host")) {
+        return {
+          exitCode: 1,
+          text: `${message}
+Only github.com repositories are supported.`
+        };
+      }
+      return {
+        exitCode: 1,
+        text: `${message}
+Provide a valid GitHub repository shorthand (owner/repo) or URL.`
+      };
+    }
+  }
+  const resolvedServices = resolveServices(
+    resolveRoot(opts.project, "tmp"),
+    opts.project,
+    services
+  );
+  const execFile2 = services.execFile ?? defaultRun;
+  const fetchFn = services.fetch ?? fetch;
+  const fetchRes = await executeFetch(
+    issueNumber,
+    explicitRepo,
+    opts,
+    resolvedServices,
+    execFile2,
+    fetchFn
+  );
+  if (!fetchRes.ok) {
+    if (fetchRes.kind === "ambiguous") {
+      return {
+        exitCode: 1,
+        text: `${fetchRes.message}
+Specify the repository with --repo <owner/repo | url>.`
+      };
+    }
+    if (fetchRes.kind === "not-found") {
+      return {
+        exitCode: 1,
+        text: `${fetchRes.message}
+Double-check the repository and issue/PR number.`
+      };
+    }
+    return {
+      exitCode: 1,
+      text: `${fetchRes.message}
+Ensure you have access to the repository (e.g. gh auth login for private repositories).`
+    };
+  }
+  let featureName;
+  if (opts.feature) {
+    if (!isValidFeatureName(opts.feature)) {
+      return {
+        exitCode: 1,
+        text: `Feature name "${opts.feature}" is invalid.
+Feature names must match [a-z0-9]+(-[a-z0-9]+)*.`
+      };
+    }
+    featureName = opts.feature;
+  } else {
+    const normRepo = normalizeRepoName(fetchRes.data.repo);
+    featureName = `gh-${normRepo}-${fetchRes.data.number}`;
+  }
+  const featureRoot = resolveRoot(opts.project, featureName);
+  try {
+    await access2(featureRoot);
+    return {
+      exitCode: 1,
+      text: `Feature workspace already exists at ${featureRoot}.
+Resume work there or specify a distinct name with --feature <name>.`
+    };
+  } catch {
+  }
+  await mkdir4(featureRoot, { recursive: true });
+  const title = fetchRes.data.title;
+  const body = fetchRes.data.body;
+  const content = body.trim().length > 0 ? `# ${title}
+
+${body}
+` : `# ${title}
+`;
+  const requestPath = join6(featureRoot, "request.md");
+  await writeFile3(requestPath, content, "utf8");
+  return {
+    exitCode: 0,
+    feature: featureName,
+    path: requestPath,
+    source: {
+      owner: fetchRes.data.owner,
+      repo: fetchRes.data.repo,
+      number: fetchRes.data.number,
+      fetchedVia: fetchRes.data.fetchedVia
+    },
+    text: `Imported ${fetchRes.data.owner}/${fetchRes.data.repo}#${fetchRes.data.number} into ${requestPath} (via ${fetchRes.data.fetchedVia}).
+Next: qrspi-x:init ${featureName} (or qrspi-x:query ${featureName} to skip straight to Query).`
+  };
+}
+function parseIssueNumber(input) {
+  const match = input.trim().match(/^#?(\d+)$/);
+  if (!match) return void 0;
+  return Number.parseInt(match[1], 10);
+}
+function isNotFoundErr(err) {
+  if (!err || typeof err !== "object") return false;
+  const msg = `${err.message || ""} ${err.stderr || ""} ${err.stdout || ""}`.toLowerCase();
+  return msg.includes("could not resolve to an issue or pull request") || msg.includes("could not resolve to an issue") || msg.includes("could not resolve to a pull request") || msg.includes("not found") || msg.includes("404") || msg.includes("no issue found") || msg.includes("no pull request found");
+}
+function isNoRepoErr(err) {
+  if (!err || typeof err !== "object") return false;
+  const msg = `${err.message || ""} ${err.stderr || ""} ${err.stdout || ""}`.toLowerCase();
+  return msg.includes("not a git repository") || msg.includes("no git remote") || msg.includes("could not determine base repo") || msg.includes("no default repository") || msg.includes(
+    "none of the git remotes configured for this repository point to a known github host"
+  );
+}
+function isValidFeatureName(name) {
+  return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(name);
+}
+function normalizeRepoName(repo) {
+  return repo.toLowerCase().replace(/[._]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+async function executeFetch(issueNumber, explicitRepo, opts, services, execFile2, fetchFn) {
+  const git = services.git;
+  let owner = explicitRepo?.owner;
+  let repo = explicitRepo?.repo;
+  const baseArgs = [String(issueNumber)];
+  if (owner && repo) {
+    baseArgs.push("--repo", `${owner}/${repo}`);
+  }
+  baseArgs.push("--json", "title,body");
+  let ghOutcome;
+  try {
+    const { stdout } = await execFile2(
+      "gh",
+      ["issue", "view", ...baseArgs],
+      {
+        cwd: opts.project
+      }
+    );
+    const json = JSON.parse(stdout);
+    ghOutcome = {
+      ok: true,
+      title: json.title ?? "",
+      body: json.body ?? ""
+    };
+  } catch (issueErr) {
+    if (isNoRepoErr(issueErr)) {
+      ghOutcome = { ok: false, reason: "no-repo", error: issueErr };
+    } else if (isNotFoundErr(issueErr)) {
+      try {
+        const { stdout } = await execFile2(
+          "gh",
+          ["pr", "view", ...baseArgs],
+          {
+            cwd: opts.project
+          }
+        );
+        const json = JSON.parse(stdout);
+        ghOutcome = {
+          ok: true,
+          title: json.title ?? "",
+          body: json.body ?? ""
+        };
+      } catch (prErr) {
+        if (isNoRepoErr(prErr)) {
+          ghOutcome = { ok: false, reason: "no-repo", error: prErr };
+        } else if (isNotFoundErr(prErr)) {
+          ghOutcome = {
+            ok: false,
+            reason: "not-found",
+            error: prErr
+          };
+        } else {
+          ghOutcome = { ok: false, reason: "other", error: prErr };
+        }
+      }
+    } else {
+      ghOutcome = { ok: false, reason: "other", error: issueErr };
+    }
+  }
+  if (ghOutcome.ok) {
+    if (!owner || !repo) {
+      const inferred = await git?.originRepo();
+      if (inferred) {
+        owner = inferred.owner;
+        repo = inferred.repo;
+      }
+    }
+    if (owner && repo) {
+      return {
+        ok: true,
+        data: {
+          title: ghOutcome.title,
+          body: ghOutcome.body,
+          owner,
+          repo,
+          number: issueNumber,
+          fetchedVia: "gh"
+        }
+      };
+    }
+  }
+  if (!owner || !repo) {
+    const inferred = await git?.originRepo();
+    if (inferred) {
+      owner = inferred.owner;
+      repo = inferred.repo;
+    } else {
+      return {
+        ok: false,
+        kind: "ambiguous",
+        message: `Reference "#${issueNumber}" has no target repository specified and none could be inferred from git remote. Specify --repo <owner/repo | url>.`
+      };
+    }
+  }
+  try {
+    const url = `https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}`;
+    const res = await fetchFn(url, {
+      headers: { "User-Agent": "qrspi-x-import" }
+    });
+    if (res.status === 404) {
+      if (!ghOutcome.ok && ghOutcome.reason === "not-found") {
+        return {
+          ok: false,
+          kind: "not-found",
+          message: `Issue/PR #${issueNumber} not found in repository ${owner}/${repo}.`
+        };
+      }
+      return {
+        ok: false,
+        kind: "fetch-failed",
+        message: `Failed to fetch ${owner}/${repo}#${issueNumber}: gh failed and REST fallback returned 404.`
+      };
+    }
+    if (!res.ok) {
+      return {
+        ok: false,
+        kind: "fetch-failed",
+        message: `Failed to fetch ${owner}/${repo}#${issueNumber}: gh failed and REST fallback returned HTTP ${res.status}.`
+      };
+    }
+    const data = await res.json();
+    return {
+      ok: true,
+      data: {
+        title: data.title ?? "",
+        body: data.body ?? "",
+        owner,
+        repo,
+        number: issueNumber,
+        fetchedVia: "rest"
+      }
+    };
+  } catch (restErr) {
+    if (!ghOutcome.ok && ghOutcome.reason === "not-found") {
+      return {
+        ok: false,
+        kind: "not-found",
+        message: `Issue/PR #${issueNumber} not found in repository ${owner}/${repo}.`
+      };
+    }
+    return {
+      ok: false,
+      kind: "fetch-failed",
+      message: `Failed to fetch ${owner}/${repo}#${issueNumber}: gh failed and REST error: ${restErr instanceof Error ? restErr.message : String(restErr)}`
+    };
+  }
+}
+
+// src/command/log.ts
+import { readFile as readFile5 } from "node:fs/promises";
+import { join as join7 } from "node:path";
+var reasonFlag = {
+  flag: '--reason "<why>"',
+  required: false,
+  description: "A rerun/resume worth noting in history.jsonl."
+};
+var implementHelp = {
+  name: "implement",
+  summary: "Record implement/repair completion: reads plan.md/phase markers, clears inFlight.",
+  flags: [
+    ...commonOptions,
+    {
+      flag: "--phase <id>",
+      required: true,
+      description: "The phase that finished."
+    },
+    reasonFlag
+  ],
+  example: "qrspi-x log implement --feature widget --project . --phase 1"
+};
+var repairHelp = {
+  name: "repair",
+  summary: "Alias for `log implement` \u2014 identical validation, same call.",
+  flags: implementHelp.flags,
+  example: "qrspi-x log repair --feature widget --project . --phase 1"
+};
+var reviewHelp = {
+  name: "review",
+  summary: "Record a review verdict: reads reviews/<label>.md, always writes, updates loop-state.json's checkpoint/conditions.",
+  flags: [
+    ...commonOptions,
+    {
+      flag: "--label <label>",
+      required: true,
+      description: "The review artifact's label (from status's next.label or next-file)."
+    }
+  ],
+  example: "qrspi-x log review --feature widget --project . --label phase-1"
+};
+var parkHelp = {
+  name: "park",
+  summary: "Mark the feature not-currently-active. Not a gate; always appends to history.jsonl.",
+  flags: [...commonOptions, reasonFlag],
+  example: 'qrspi-x log park --feature widget --project . --reason "waiting on design review"'
+};
+var help4 = {
+  name: "log",
+  summary: "Record completed work, after the fact, from real on-disk evidence.",
+  actions: [implementHelp, repairHelp, reviewHelp, parkHelp]
+};
+async function logImplement(opts, implementKind, services) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { workspace, loopState, history } = resolveServices(
+    root,
+    opts.project,
+    services
+  );
+  if (!await workspace.isPhaseComplete(opts.phase)) {
+    return blocked([
+      {
+        code: "phase-not-complete",
+        message: `Phase ${opts.phase}'s steps aren't all [x] yet.`
+      }
+    ]);
+  }
+  await history.conditionalAppend(
+    { kind: implementKind, phase: opts.phase },
+    { action: "end" },
+    {
+      kind: implementKind,
+      action: "end",
+      phase: opts.phase,
+      ...opts.reason !== void 0 ? { text: opts.reason } : {}
+    }
+  );
+  await loopState.clearInFlight();
+  return ok();
+}
+async function implement(opts, services = {}) {
+  return logImplement(opts, "implement", services);
+}
+async function repair(opts, services = {}) {
+  return logImplement(opts, "repair", services);
+}
+async function review(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { loopState, history } = resolveServices(
+    root,
+    opts.project,
+    services
+  );
+  const path = reviewPath(opts.label);
+  const text = await readFile5(join7(root, path), "utf8");
+  const verdict = parseVerdict(text);
+  if (!verdict) {
+    return blocked([
+      {
+        code: "no-verdict",
+        message: `${path} has no ## Verdict: line yet.`
+      }
+    ]);
+  }
+  const { phaseId, isReReview } = parseReviewLabel(opts.label);
+  const outcome = phaseId === void 0 ? "final" : verdict === "FAIL" ? isReReview ? "stop" : "repair" : "advance";
+  const conditions = verdict === "PASS WITH CONDITIONS" ? [parseVerdictSummary(text) ?? ""] : void 0;
+  await history.conditionalAppend(
+    { kind: "review", label: opts.label },
+    { action: "end" },
+    {
+      kind: "review",
+      action: "end",
+      label: opts.label,
+      ...phaseId !== void 0 ? { phase: phaseId } : {},
+      verdict,
+      outcome,
+      ...conditions ? { conditions } : {}
+    }
+  );
+  if (phaseId !== void 0) {
+    await loopState.updateCheckpoint(phaseId, opts.label, verdict);
+    await loopState.clearInFlight();
+  }
+  return ok();
+}
+async function park(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { history, decisions } = resolveServices(
+    root,
+    opts.project,
+    services
+  );
+  if (await history.isParked()) {
+    return ok();
+  }
+  await history.append({
+    kind: "park",
+    ...opts.reason !== void 0 ? { text: opts.reason } : {}
+  });
+  if (opts.reason !== void 0) {
+    await decisions.add(opts.reason);
+  }
+  return ok();
+}
+
+// src/command/loop.ts
+var startHelp = {
+  name: "start",
+  summary: "Resolve a selector and create loop-state.json. Use all, one phase id, a row range like 2..4, or a comma list like 1,3.",
+  usage: "qrspi-x loop start <selector> --feature <feature> --project <path>",
+  flags: [...commonOptions],
+  examples: [
+    "qrspi-x loop start all --feature widget --project .",
+    "qrspi-x loop start 2..4 --feature widget --project .",
+    "qrspi-x loop start 1,3 --feature widget --project ."
+  ]
+};
+var advanceHelp = {
+  name: "advance",
+  summary: "Use after the current phase is complete and marked [x] to move the loop pointer to the next phase; it does not clear a stop.",
+  usage: "qrspi-x loop advance --feature <feature> --project <path>",
+  flags: [...commonOptions],
+  example: "qrspi-x loop advance --feature widget --project ."
+};
+var stopHelp = {
+  name: "stop",
+  summary: "Record a stop (agent self-stop or human intervention). Called only by autoloop itself.",
+  usage: 'qrspi-x loop stop "<reason>" --feature <feature> --project <path>',
+  flags: [...commonOptions],
+  example: 'qrspi-x loop stop "dirty-tree after repair" --feature widget --project .'
+};
+var okHelp = {
+  name: "ok",
+  summary: "Use only after status reports acknowledge-required and a human has resolved the stop; clears the stop without advancing the phase.",
+  usage: 'qrspi-x loop ok ["<reason>"] --feature <feature> --project <path>',
+  flags: [...commonOptions],
+  example: 'qrspi-x loop ok "retried with --base" --feature widget --project .'
+};
+var abandonHelp = {
+  name: "abandon",
+  summary: "End the run (reject a proposed scope, or end an active one). Removes loop-state.json.",
+  usage: 'qrspi-x loop abandon "<reason>" --feature <feature> --project <path>',
+  flags: [...commonOptions],
+  example: 'qrspi-x loop abandon "scope too large" --feature widget --project .'
+};
+var help5 = {
+  name: "loop",
+  summary: "Own loop-state.json's scope and lifecycle: start/advance/stop/ok/abandon.",
+  actions: [startHelp, advanceHelp, stopHelp, okHelp, abandonHelp]
+};
+async function writeLoopEntry(services, action, reason) {
+  if (action !== "stop" && reason === void 0) {
+    return;
+  }
+  await services.history.conditionalAppend(
+    { kind: "loop", action },
+    { text: reason },
+    {
+      kind: "loop",
+      action,
+      ...reason !== void 0 ? { text: reason } : {}
+    }
+  );
+}
+async function start(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const resolved = resolveServices(root, opts.project, services);
+  try {
+    const phaseIds = await resolved.loopState.start(opts.selector);
+    return ok({ phaseIds });
+  } catch (err) {
+    if (err instanceof Error) {
+      return blocked([{ code: "loop-refused", message: err.message }]);
+    }
+    throw err;
+  }
+}
+async function advance(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const resolved = resolveServices(root, opts.project, services);
+  await resolved.loopState.advance();
+  return ok();
+}
+async function stop(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const resolved = resolveServices(root, opts.project, services);
+  await resolved.loopState.stop(opts.reason);
+  await writeLoopEntry(resolved, "stop", opts.reason);
+  return ok();
+}
+async function loopOk(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const resolved = resolveServices(root, opts.project, services);
+  await resolved.loopState.ok();
+  await writeLoopEntry(resolved, "ok", opts.reason);
+  const status = await resolved.loopState.status();
+  return ok({ action: status?.action });
+}
+async function abandon(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const resolved = resolveServices(root, opts.project, services);
+  await writeLoopEntry(resolved, "abandon", opts.reason);
+  await resolved.loopState.abandon();
+  return ok();
+}
+
+// src/command/next-file.ts
+var help6 = {
+  name: "next-file",
+  summary: "Print the next artifact path for <type>: query, research, approach, spec, review, or final.",
+  usage: "qrspi-x next-file <type> --feature <feature> --project <path> [--phase <id>] [--step <k>]",
+  flags: [
+    ...commonOptions,
+    {
+      flag: "--phase <id>",
+      required: false,
+      description: "The phase id; required for review artifacts."
+    },
+    {
+      flag: "--step <k>",
+      required: false,
+      description: "The step number for a step-scoped review."
+    }
+  ]
+};
+var TYPES = [
+  "query",
+  "research",
+  "approach",
+  "spec",
+  "review",
+  "final"
+];
+async function run2(type, opts, services = {}) {
+  if (!TYPES.includes(type)) {
+    throw new Error(
+      `Unknown next-file type "${type}" (expected one of: ${TYPES.join(", ")}).`
+    );
+  }
+  if (type === "review" && opts.phase === void 0) {
+    throw new Error("next-file review requires --phase <id>.");
+  }
+  const root = resolveRoot(opts.project, opts.feature);
+  const { workspace } = resolveServices(root, opts.project, services);
+  return workspace.nextFile(type, {
+    phase: opts.phase,
+    step: opts.step
+  });
+}
+
+// src/command/plugin.ts
+import { execFile as nodeExecFile4 } from "node:child_process";
+import { readdir as readdir4, readFile as readFile8 } from "node:fs/promises";
+import { homedir as homedir2 } from "node:os";
+import { join as join10 } from "node:path";
+import { promisify as promisify5 } from "node:util";
+
+// src/plugin/GitHub.ts
+import { execFile as nodeExecFile2 } from "node:child_process";
+import { promisify as promisify3 } from "node:util";
+
+// src/plugin/Manifest.ts
+var REQUIRED_STRING_FIELDS = [
+  "version",
+  "releaseTag",
+  "downloadedAt",
+  "archiveHash"
+];
+function parseManifest(text) {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+  if (!isValidManifestShape(data)) {
+    return void 0;
+  }
+  return data;
+}
+function isValidManifestShape(data) {
+  if (typeof data !== "object" || data === null) {
+    return false;
+  }
+  const record = data;
+  for (const field of REQUIRED_STRING_FIELDS) {
+    if (typeof record[field] !== "string" || record[field] === "") {
+      return false;
+    }
+  }
+  const payloadPaths = record.payloadPaths;
+  if (!Array.isArray(payloadPaths) || payloadPaths.length === 0) {
+    return false;
+  }
+  for (const path of payloadPaths) {
+    if (typeof path !== "string" || path === "" || !isPayloadPathSafe(path)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isPayloadPathSafe(path) {
+  return !path.includes("/") && !path.includes("\\") && path !== "." && path !== "..";
+}
+function isCurrentWith(a, b) {
+  return a.version === b.version && a.archiveHash === b.archiveHash;
+}
+var RELEASE_TAG_PATTERN = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?$/;
+function parseReleaseTag(tag) {
+  const match = RELEASE_TAG_PATTERN.exec(tag);
+  if (!match) {
+    return void 0;
+  }
+  return {
+    tag,
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] !== void 0
+  };
+}
+
+// src/plugin/GitHub.ts
+var defaultRun2 = promisify3(nodeExecFile2);
+function gitHubAt(repository, cwd, deps = {}) {
+  const execFile2 = deps.execFile ?? defaultRun2;
+  const repoSlug = `${repository.owner}/${repository.repo}`;
+  async function resolveRelease(requested) {
+    if (requested !== void 0) {
+      if (!parseReleaseTag(requested)) {
+        return {
+          ok: false,
+          reason: "invalid-tag",
+          message: `"${requested}" is not a valid release tag. Expected unprefixed SemVer (e.g. 1.2.3), matching the project's release-tag format.`
+        };
+      }
+      const exists2 = await releaseExists(requested);
+      if (exists2.status === "error") {
+        return {
+          ok: false,
+          reason: "lookup-failed",
+          message: `Failed to look up release "${requested}" in ${repoSlug}: ${exists2.message}`
+        };
+      }
+      if (exists2.status === "not-found") {
+        return {
+          ok: false,
+          reason: "not-found",
+          message: `Release "${requested}" was not found in ${repoSlug}.`
+        };
+      }
+      return { ok: true, tag: requested };
+    }
+    const latest = await latestEligibleTag();
+    if (!latest) {
+      return {
+        ok: false,
+        reason: "no-eligible",
+        message: `No eligible release tag found in ${repoSlug}.`
+      };
+    }
+    return { ok: true, tag: latest };
+  }
+  async function releaseExists(tag) {
+    try {
+      await execFile2(
+        "gh",
+        [
+          "release",
+          "view",
+          tag,
+          "--repo",
+          repoSlug,
+          "--json",
+          "tagName"
+        ],
+        { cwd }
+      );
+      return { status: "exists" };
+    } catch (err) {
+      if (isNotFoundError(err)) {
+        return { status: "not-found" };
+      }
+      return { status: "error", message: errorText(err) };
+    }
+  }
+  async function latestEligibleTag() {
+    const { stdout } = await execFile2(
+      "gh",
+      [
+        "release",
+        "list",
+        "--repo",
+        repoSlug,
+        "--exclude-drafts",
+        "--exclude-pre-releases",
+        "--order",
+        "desc",
+        "--limit",
+        "1",
+        "--json",
+        "tagName"
+      ],
+      { cwd }
+    );
+    const releases = JSON.parse(stdout);
+    const tag = releases[0]?.tagName;
+    return tag && parseReleaseTag(tag) ? tag : void 0;
+  }
+  async function verifyAttestation(assetPath) {
+    try {
+      await execFile2(
+        "gh",
+        [
+          "attestation",
+          "verify",
+          assetPath,
+          "--repo",
+          repoSlug,
+          "--format",
+          "json"
+        ],
+        { cwd }
+      );
+      return { ok: true };
+    } catch (err) {
+      if (isGhMissing(err)) {
+        return {
+          ok: false,
+          reason: "gh-missing",
+          message: "GitHub CLI (gh) is required to verify release attestations and was not found. Install gh and try again; attestation verification cannot be skipped."
+        };
+      }
+      return {
+        ok: false,
+        reason: "verification-failed",
+        message: `Attestation verification failed for ${assetPath}: ${errorText(err)}`
+      };
+    }
+  }
+  async function checkFreshness(installedVersion) {
+    let latestTag;
+    try {
+      latestTag = await latestEligibleTag();
+    } catch (err) {
+      return { status: "unknown", message: errorText(err) };
+    }
+    if (!latestTag) {
+      return { status: "unknown" };
+    }
+    const latest = parseReleaseTag(latestTag);
+    if (!latest) {
+      return { status: "unknown" };
+    }
+    const installed = parseReleaseTag(installedVersion);
+    if (!installed) {
+      return { status: "unknown", latest: latestTag };
+    }
+    const isNewer = latest.major !== installed.major ? latest.major > installed.major : latest.minor !== installed.minor ? latest.minor > installed.minor : latest.patch > installed.patch;
+    return isNewer ? { status: "update-available", latest: latestTag } : { status: "up-to-date" };
+  }
+  return { resolveRelease, verifyAttestation, checkFreshness };
+}
+function isGhMissing(err) {
+  const code = err?.code;
+  return code === "ENOENT";
+}
+function errorText(err) {
+  if (err && typeof err === "object") {
+    const stderr = err.stderr;
+    if (stderr?.trim()) {
+      return stderr.trim();
+    }
+    const message = err.message;
+    if (message) {
+      return message;
+    }
+  }
+  return String(err);
+}
+function isNotFoundError(err) {
+  const code = err?.code;
+  const stderr = err?.stderr ?? "";
+  const message = err?.message ?? "";
+  return code === "GH_NOT_FOUND" || /release not found/i.test(`${stderr}
+${message}`);
+}
+
+// src/plugin/Staging.ts
+import { execFile as nodeExecFile3 } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  mkdir as mkdir5,
+  mkdtemp,
+  readdir as readdir2,
+  readFile as readFile6,
+  readFile as readFileBuffer,
+  rename,
+  rm as rm2,
+  writeFile as writeFile4
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join as join8 } from "node:path";
+import { promisify as promisify4 } from "node:util";
+import yauzl from "yauzl";
+var defaultRun3 = promisify4(nodeExecFile3);
+function stagingAt(targetDir, repoSlug, cwd, deps = {}) {
+  const execFile2 = deps.execFile ?? defaultRun3;
+  const doRename = deps.rename ?? rename;
+  const doRm = deps.rm ?? rm2;
+  async function download(releaseTag) {
+    const workDir = await mkdtemp(join8(tmpdir(), "qrspi-stage-"));
+    const cleanup = () => rm2(workDir, { recursive: true, force: true });
+    const archivePath = join8(workDir, "release.zip");
+    const downloadResult = await downloadAsset(
+      execFile2,
+      repoSlug,
+      cwd,
+      releaseTag,
+      archivePath
+    );
+    if (!downloadResult.ok) {
+      await cleanup();
+      return downloadResult;
+    }
+    return { ok: true, archivePath, cleanup };
+  }
+  async function extractAndCommit(archivePath, releaseTag) {
+    const workDir = dirname(archivePath);
+    try {
+      const archiveBytes = await readFileBuffer(archivePath);
+      const archiveHash = createHash("sha256").update(archiveBytes).digest("hex");
+      const extractedDir = join8(workDir, "extracted");
+      await mkdir5(extractedDir, { recursive: true });
+      const extractResult = await extractZip(archivePath, extractedDir);
+      if (!extractResult.ok) {
+        return extractResult;
+      }
+      const manifestName = "qrspi-manifest.json";
+      const manifestPath = join8(extractedDir, manifestName);
+      let authorManifest;
+      try {
+        authorManifest = JSON.parse(
+          await readFile6(manifestPath, "utf8")
+        );
+      } catch (err) {
+        return {
+          ok: false,
+          reason: "invalid-manifest",
+          message: `Release ${releaseTag} is missing a readable qrspi-manifest.json: ${errorText2(err)}`
+        };
+      }
+      const payloadPaths = await listTopLevelEntries(
+        extractedDir,
+        manifestName
+      );
+      const stamped = {
+        ...authorManifest,
+        releaseTag,
+        downloadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        archiveHash,
+        payloadPaths
+      };
+      if (!isValidManifestShape(stamped)) {
+        return {
+          ok: false,
+          reason: "invalid-manifest",
+          message: `Release ${releaseTag}'s manifest is missing required fields after stamping installer metadata.`
+        };
+      }
+      await writeFile4(
+        manifestPath,
+        JSON.stringify(stamped, null, 4),
+        "utf8"
+      );
+      await commit(extractedDir);
+      return { ok: true, manifest: stamped };
+    } finally {
+      await rm2(workDir, { recursive: true, force: true });
+    }
+  }
+  async function commit(extractedDir) {
+    await mkdir5(dirname(targetDir), { recursive: true });
+    const backupDir = `${targetDir}.previous-${Date.now()}`;
+    const stagedDir = `${targetDir}.incoming-${Date.now()}`;
+    await doRename(extractedDir, stagedDir);
+    let hadPrevious = true;
+    try {
+      await doRename(targetDir, backupDir);
+    } catch (err) {
+      if (!isNotFound(err)) {
+        throw err;
+      }
+      hadPrevious = false;
+    }
+    try {
+      await doRename(stagedDir, targetDir);
+    } catch (err) {
+      let cleanupErr;
+      try {
+        await doRm(stagedDir, { recursive: true, force: true });
+      } catch (error) {
+        cleanupErr = error;
+      }
+      if (hadPrevious) {
+        try {
+          await doRename(backupDir, targetDir);
+        } catch (restoreErr) {
+          const errors = [err, restoreErr];
+          if (cleanupErr) errors.push(cleanupErr);
+          throw new AggregateError(
+            errors,
+            "Failed to install the staged plugin and restore the previous install"
+          );
+        }
+      }
+      if (cleanupErr) {
+        throw new AggregateError(
+          [err, cleanupErr],
+          "Failed to install the staged plugin and clean up its temporary directory"
+        );
+      }
+      throw err;
+    }
+    if (hadPrevious) {
+      await doRm(backupDir, { recursive: true, force: true });
+    }
+  }
+  return { download, extractAndCommit };
+}
+async function downloadAsset(execFile2, repoSlug, cwd, releaseTag, destPath) {
+  try {
+    await execFile2(
+      "gh",
+      [
+        "release",
+        "download",
+        releaseTag,
+        "--repo",
+        repoSlug,
+        "--pattern",
+        "*.zip",
+        "--output",
+        destPath,
+        "--clobber"
+      ],
+      { cwd }
+    );
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "download-failed",
+      message: `Failed to download release ${releaseTag} from ${repoSlug}: ${errorText2(err)}`
+    };
+  }
+}
+async function listTopLevelEntries(extractedDir, exclude) {
+  const entries = await readdir2(extractedDir);
+  return entries.filter((entry) => entry !== exclude).sort();
+}
+async function extractZip(archivePath, destDir) {
+  try {
+    const zipfile = await yauzl.openPromise(archivePath, {
+      lazyEntries: false
+    });
+    try {
+      for await (const entry of zipfile.eachEntry()) {
+        const invalid = yauzl.validateFileName(entry.fileName);
+        if (invalid) {
+          throw new Error(
+            `Unsafe path in release archive: ${entry.fileName} (${invalid})`
+          );
+        }
+        const entryPath = join8(destDir, entry.fileName);
+        if (entry.fileName.endsWith("/")) {
+          await mkdir5(entryPath, { recursive: true });
+          continue;
+        }
+        await mkdir5(dirname(entryPath), { recursive: true });
+        const readStream = await zipfile.openReadStreamPromise(entry);
+        await writeStreamToFile(readStream, entryPath);
+      }
+    } finally {
+      zipfile.close();
+    }
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "extraction-failed",
+      message: `Failed to extract release archive: ${errorText2(err)}`
+    };
+  }
+}
+function writeStreamToFile(readStream, destPath) {
+  return new Promise((resolve2, reject) => {
+    const chunks = [];
+    readStream.on("data", (chunk) => chunks.push(chunk));
+    readStream.on("end", async () => {
+      try {
+        await writeFile4(destPath, Buffer.concat(chunks));
+        resolve2();
+      } catch (err) {
+        reject(err);
+      }
+    });
+    readStream.on("error", reject);
+  });
+}
+function errorText2(err) {
+  if (err && typeof err === "object") {
+    const stderr = err.stderr;
+    if (stderr?.trim()) {
+      return stderr.trim();
+    }
+    const message = err.message;
+    if (message) {
+      return message;
+    }
+  }
+  return String(err);
+}
+function isNotFound(err) {
+  return err?.code === "ENOENT";
+}
+
+// src/plugin/Target.ts
+import {
+  cp,
+  lstat,
+  mkdir as mkdir6,
+  readdir as readdir3,
+  readFile as readFile7,
+  readlink,
+  rename as rename2,
+  rm as rm3,
+  symlink
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname as dirname2, join as join9, resolve } from "node:path";
+var AGENT_TARGETS = {
+  claude: (home) => join9(home, ".claude", "skills", "qrspi-x"),
+  codex: (home) => join9(home, ".agents", "skills", "qrspi-x"),
+  bob: (home) => join9(home, ".bob", "plugins", "qrspi-x")
+};
+var AGENT_NAMES = Object.keys(AGENT_TARGETS);
+function isAgentName(value) {
+  return Object.hasOwn(AGENT_TARGETS, value);
+}
+function targetPathFor(agent, home = homedir()) {
+  return AGENT_TARGETS[agent](home);
+}
+async function probeTarget(targetDir, installDir) {
+  let stats;
+  try {
+    stats = await lstat(targetDir);
+  } catch (err) {
+    if (!isNotFound2(err)) {
+      return { state: "error", message: errorText3(err) };
+    }
+    return { state: "absent" };
+  }
+  if (stats.isSymbolicLink()) {
+    let resolved;
+    try {
+      resolved = resolve(dirname2(targetDir), await readlink(targetDir));
+    } catch (err) {
+      return { state: "error", message: errorText3(err) };
+    }
+    if (resolved !== resolve(installDir)) {
+      return {
+        state: "unmanaged",
+        reason: `symlink resolves to ${resolved}, not ${installDir}`
+      };
+    }
+    try {
+      await lstat(resolved);
+    } catch (err) {
+      if (!isNotFound2(err)) {
+        return { state: "error", message: errorText3(err) };
+      }
+      return { state: "unmanaged", reason: "dangling symlink" };
+    }
+    return { state: "managed", mode: "symlink" };
+  }
+  if (!stats.isDirectory()) {
+    return { state: "unmanaged", reason: "a file, not a directory" };
+  }
+  const manifestPath = join9(targetDir, "qrspi-manifest.json");
+  let manifestText;
+  try {
+    manifestText = await readFile7(manifestPath, "utf8");
+  } catch (err) {
+    if (!isNotFound2(err)) {
+      return { state: "error", message: errorText3(err) };
+    }
+    return { state: "unmanaged", reason: "no manifest found" };
+  }
+  const manifest = parseManifest(manifestText);
+  if (!manifest) {
+    return { state: "unmanaged", reason: "manifest is invalid" };
+  }
+  for (const payloadPath of manifest.payloadPaths) {
+    try {
+      await lstat(join9(targetDir, payloadPath));
+    } catch (err) {
+      if (!isNotFound2(err)) {
+        return { state: "error", message: errorText3(err) };
+      }
+      return {
+        state: "unmanaged",
+        reason: `manifest-declared path "${payloadPath}" is missing`
+      };
+    }
+  }
+  return { state: "managed", mode: "copy", manifest };
+}
+function isNotFound2(err) {
+  return err?.code === "ENOENT";
+}
+function isCurrent(probe, centralManifest) {
+  if (probe.state !== "managed") {
+    return false;
+  }
+  if (probe.mode === "symlink") {
+    return true;
+  }
+  return isCurrentWith(probe.manifest, centralManifest);
+}
+async function placeTarget(targetDir, installDir, requested, deps = {}) {
+  const doSymlink = deps.symlink ?? symlink;
+  const doCopy = deps.cp ?? cp;
+  const doRename = deps.rename ?? rename2;
+  const doRm = deps.rm ?? rm3;
+  async function copy() {
+    await mkdir6(dirname2(targetDir), { recursive: true });
+    const tempPath = `${targetDir}.qrspi-incoming-${Date.now()}`;
+    await doCopy(installDir, tempPath, { recursive: true });
+    const backupPath = `${targetDir}.qrspi-previous-${Date.now()}`;
+    let hadPrevious = true;
+    try {
+      await doRename(targetDir, backupPath);
+    } catch (err) {
+      if (!isNotFound2(err)) {
+        throw err;
+      }
+      hadPrevious = false;
+    }
+    try {
+      await doRename(tempPath, targetDir);
+    } catch (err) {
+      await doRm(tempPath, { recursive: true, force: true });
+      if (hadPrevious) {
+        await doRename(backupPath, targetDir);
+      }
+      throw err;
+    }
+    if (hadPrevious) {
+      await doRm(backupPath, { recursive: true, force: true });
+    }
+    return { ok: true, mode: "copy" };
+  }
+  async function link() {
+    await mkdir6(dirname2(targetDir), { recursive: true });
+    const tempPath = `${targetDir}.qrspi-incoming-${Date.now()}`;
+    await doSymlink(installDir, tempPath);
+    const replacingDirectory = await isExistingDirectory(targetDir);
+    if (!replacingDirectory) {
+      try {
+        await rename2(tempPath, targetDir);
+      } catch (err) {
+        await rm3(tempPath, { force: true });
+        throw err;
+      }
+      return { ok: true, mode: "symlink" };
+    }
+    const backupPath = `${targetDir}.qrspi-previous-${Date.now()}`;
+    await rename2(targetDir, backupPath);
+    try {
+      await rename2(tempPath, targetDir);
+    } catch (err) {
+      await rm3(tempPath, { force: true });
+      await rename2(backupPath, targetDir);
+      throw err;
+    }
+    await rm3(backupPath, { recursive: true, force: true });
+    return { ok: true, mode: "symlink" };
+  }
+  if (requested === "copy") {
+    return copy();
+  }
+  try {
+    return await link();
+  } catch (err) {
+    if (!isEperm(err)) {
+      throw err;
+    }
+    if (requested === "symlink") {
+      return {
+        ok: false,
+        reason: "symlink-unavailable",
+        message: `Cannot create a symlink at ${targetDir}: ${errorText3(err)}`
+      };
+    }
+    return copy();
+  }
+}
+function isEperm(err) {
+  return err?.code === "EPERM";
+}
+async function isExistingDirectory(path) {
+  try {
+    const stats = await lstat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function clearUnmanagedTarget(targetDir) {
+  await rm3(targetDir, { recursive: true, force: true });
+}
+var MANIFEST_FILE_NAME = "qrspi-manifest.json";
+async function removeTarget(targetDir, probe, force) {
+  if (probe.mode === "symlink") {
+    await rm3(targetDir, { force: true });
+    return { ok: true };
+  }
+  const declared = /* @__PURE__ */ new Set([
+    ...probe.manifest.payloadPaths,
+    MANIFEST_FILE_NAME
+  ]);
+  const entries = await readdir3(targetDir);
+  const extraPaths = entries.filter((entry) => !declared.has(entry));
+  if (extraPaths.length > 0 && !force) {
+    return { ok: false, reason: "blocked-by-extras", extraPaths };
+  }
+  for (const entry of entries) {
+    if (declared.has(entry)) {
+      await rm3(join9(targetDir, entry), { recursive: true, force: true });
+    }
+  }
+  if (extraPaths.length === 0) {
+    await rm3(targetDir, { recursive: true, force: true });
+  }
+  return { ok: true };
+}
+function errorText3(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/command/plugin.ts
+var defaultRun4 = promisify5(nodeExecFile4);
+var QRSPI_X_REPO = {
+  owner: "ebullient",
+  repo: "qrspi-x"
+};
+var releaseFlag = {
+  flag: "--release <tag>",
+  required: false,
+  description: "Install this release tag instead of GitHub's own latest-eligible release."
+};
+var installHelp = {
+  name: "install",
+  summary: "Download, verify, and stage a release into ~/.qrspi/plugin, replacing any existing content.",
+  flags: [releaseFlag],
+  example: "qrspi-x plugin install --release 1.2.3"
+};
+var initHelp = {
+  name: "init",
+  summary: "Place the installed plugin content at one agent's fixed target.",
+  flags: [
+    {
+      flag: "--agent <claude|codex|bob>",
+      required: true,
+      description: "Which agent's fixed target to place content at."
+    },
+    {
+      flag: "--copy",
+      required: false,
+      description: "Force copy mode. Mutually exclusive with --symlink."
+    },
+    {
+      flag: "--symlink",
+      required: false,
+      description: "Force symlink mode, failing cleanly if unavailable rather than falling back. Mutually exclusive with --copy."
+    },
+    {
+      flag: "--force",
+      required: false,
+      description: "Don't refuse an unmanaged (foreign) target; delete it and place fresh content there instead, for the one named agent. No effect on an absent or already-managed target."
+    }
+  ],
+  example: "qrspi-x plugin init --agent claude"
+};
+var statusHelp = {
+  name: "status",
+  summary: "Report the installed version, each agent's placement, and GitHub release freshness. Makes no changes.",
+  flags: [],
+  example: "qrspi-x plugin status"
+};
+var updateHelp = {
+  name: "update",
+  summary: "Re-run install, then re-place every initialized agent not already current with the freshly staged release.",
+  flags: [
+    releaseFlag,
+    {
+      flag: "--force",
+      required: false,
+      description: "Don't refuse an unmanaged (foreign) target; delete it and place fresh content there instead, for each unmanaged agent found during the sweep. No effect on an absent or already-current agent."
+    }
+  ],
+  example: "qrspi-x plugin update"
+};
+var removeHelp = {
+  name: "remove",
+  summary: "Remove one agent's placed files or symlink from its fixed target. Never touches ~/.qrspi/plugin or any other agent.",
+  flags: [
+    {
+      flag: "--agent <claude|codex|bob>",
+      required: true,
+      description: "Which agent's fixed target to remove."
+    },
+    {
+      flag: "--force",
+      required: false,
+      description: "Don't refuse an unmanaged (foreign) target; delete it instead, for this one agent, with nothing placed afterward. Separately, copy mode only: also proceed when the target directory contains paths beyond the manifest-declared payload, removing only those declared paths and leaving the extras in place. No effect in symlink mode."
+    }
+  ],
+  example: "qrspi-x plugin remove --agent claude"
+};
+var help7 = {
+  name: "plugin",
+  summary: "Human-invoked only: install/init/update/status/remove the central plugin payload and agent targets.",
+  actions: [installHelp, initHelp, statusHelp, updateHelp, removeHelp]
+};
+async function runInstall(opts, services = {}) {
+  const execFile2 = services.execFile ?? defaultRun4;
+  const home = services.homeDir ?? homedir2();
+  const targetDir = join10(home, ".qrspi", "plugin");
+  const repoSlug = `${QRSPI_X_REPO.owner}/${QRSPI_X_REPO.repo}`;
+  const github = services.github ?? gitHubAt(QRSPI_X_REPO, home, { execFile: execFile2 });
+  const staging = services.staging ?? stagingAt(targetDir, repoSlug, home, { execFile: execFile2 });
+  const resolved = await github.resolveRelease(opts.release);
+  if (!resolved.ok) {
+    return fail(resolved.reason, resolved.message);
+  }
+  const downloadResult = await staging.download(resolved.tag);
+  if (!downloadResult.ok) {
+    return fail(downloadResult.reason, downloadResult.message);
+  }
+  const attestation = await github.verifyAttestation(
+    downloadResult.archivePath
+  );
+  if (!attestation.ok) {
+    await downloadResult.cleanup();
+    return fail(attestation.reason, attestation.message);
+  }
+  const staged = await staging.extractAndCommit(
+    downloadResult.archivePath,
+    resolved.tag
+  );
+  if (!staged.ok) {
+    return fail(staged.reason, staged.message);
+  }
+  return ok({
+    release: resolved.tag,
+    version: staged.manifest.version,
+    installedAt: targetDir,
+    text: `Installed release ${resolved.tag} into ${targetDir}.`
+  });
+}
+async function runInit(opts, services = {}) {
+  if (opts.copy && opts.symlink) {
+    const message = "--copy and --symlink are mutually exclusive.";
+    return fail("conflicting-mode", message);
+  }
+  if (!isAgentName(opts.agent)) {
+    const message = `Unknown agent "${opts.agent}". Supported agents: ${AGENT_NAMES.join(", ")}.`;
+    return fail("unknown-agent", message);
+  }
+  const agent = opts.agent;
+  const home = services.homeDir ?? homedir2();
+  const installDir = join10(home, ".qrspi", "plugin");
+  const installCheck = await checkInstall(installDir);
+  if (!installCheck.ok) {
+    const message = installCheck.reason === "not-installed" ? `No plugin install found at ${installDir}. Run "qrspi-x plugin install" first.` : `Could not read ${installDir}: ${installCheck.message}`;
+    return fail(installCheck.reason, message);
+  }
+  const inspection = await inspectAgent(agent, home, installDir);
+  if ("error" in inspection) {
+    return inspection.error;
+  }
+  const { targetDir, probe } = inspection;
+  if (probe.state === "unmanaged" && !opts.force) {
+    const message = `${targetDir} is not a QRSPI-X-managed target (${probe.reason}). Refusing to touch it. Re-run with --force to delete it and place fresh content there.`;
+    return fail("unmanaged-target", message);
+  }
+  if (probe.state === "unmanaged" && opts.force) {
+    const clearUnmanaged = services.clearUnmanaged ?? clearUnmanagedTarget;
+    try {
+      await clearUnmanaged(targetDir);
+    } catch (err) {
+      const message = `Could not clear unmanaged target ${targetDir}: ${errorText4(err)}`;
+      return fail("cleanup-failed", message);
+    }
+  }
+  const requested = opts.copy ? "copy" : opts.symlink ? "symlink" : probe.state === "managed" ? probe.mode : void 0;
+  const place = services.place ?? placeTarget;
+  const placed = await place(targetDir, installDir, requested);
+  if (!placed.ok) {
+    return fail(placed.reason, placed.message);
+  }
+  return ok({
+    agent,
+    mode: placed.mode,
+    target: targetDir,
+    text: `Placed ${agent}'s plugin content at ${targetDir} (${placed.mode} mode).`
+  });
+}
+async function runRemove(opts, services = {}) {
+  if (!isAgentName(opts.agent)) {
+    const message = `Unknown agent "${opts.agent}". Supported agents: ${AGENT_NAMES.join(", ")}.`;
+    return fail("unknown-agent", message);
+  }
+  const agent = opts.agent;
+  const home = services.homeDir ?? homedir2();
+  const installDir = join10(home, ".qrspi", "plugin");
+  const inspection = await inspectAgent(agent, home, installDir);
+  if ("error" in inspection) {
+    return inspection.error;
+  }
+  const { targetDir, probe } = inspection;
+  if (probe.state === "absent") {
+    return ok({
+      agent,
+      removed: false,
+      text: `${agent} is not installed at ${targetDir}. Nothing to do.`
+    });
+  }
+  if (probe.state === "unmanaged") {
+    if (!opts.force) {
+      const message = `${targetDir} is not a QRSPI-X-managed target (${probe.reason}). Refusing to touch it. Re-run with --force to delete it.`;
+      return fail("unmanaged-target", message);
+    }
+    const clearUnmanaged = services.clearUnmanaged ?? clearUnmanagedTarget;
+    try {
+      await clearUnmanaged(targetDir);
+    } catch (err) {
+      const message = `Could not clear unmanaged target ${targetDir}: ${errorText4(err)}`;
+      return fail("cleanup-failed", message);
+    }
+    return ok({
+      agent,
+      removed: true,
+      target: targetDir,
+      text: `Removed ${agent}'s unmanaged content from ${targetDir}.`
+    });
+  }
+  const remove = services.remove ?? removeTarget;
+  const removed = await remove(targetDir, probe, opts.force === true);
+  if (!removed.ok) {
+    const message = `${targetDir} contains paths not placed by init: ${removed.extraPaths.join(", ")}. Re-run with --force to remove only the plugin's own paths and leave these in place.`;
+    return fail(removed.reason, message);
+  }
+  return ok({
+    agent,
+    removed: true,
+    target: targetDir,
+    text: `Removed ${agent}'s plugin content from ${targetDir}.`
+  });
+}
+async function inspectAgent(agent, home, installDir) {
+  const targetDir = targetPathFor(agent, home);
+  const probe = await probeTarget(targetDir, installDir);
+  if (probe.state === "error") {
+    const message = `Could not probe ${targetDir}: ${probe.message}`;
+    return { targetDir, error: fail("probe-failed", message) };
+  }
+  return { targetDir, probe };
+}
+async function placeForUpdate(place, targetDir, installDir, requested) {
+  try {
+    return await place(targetDir, installDir, requested);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "placement-failed",
+      message: errorText4(err)
+    };
+  }
+}
+async function runUpdate(opts, services = {}) {
+  const home = services.homeDir ?? homedir2();
+  const installDir = join10(home, ".qrspi", "plugin");
+  const installResult = await runInstall(
+    { release: opts.release },
+    {
+      execFile: services.execFile,
+      homeDir: home,
+      github: services.github,
+      staging: services.staging
+    }
+  );
+  if (installResult.exitCode !== 0) {
+    return installResult;
+  }
+  const manifestPath = join10(installDir, "qrspi-manifest.json");
+  let centralManifest;
+  try {
+    const manifestText = await readFile8(manifestPath, "utf8");
+    const parsed = parseManifest(manifestText);
+    if (!parsed) {
+      const message = `Freshly staged manifest at ${manifestPath} is invalid.`;
+      return fail("invalid-manifest", message);
+    }
+    centralManifest = parsed;
+  } catch (err) {
+    const message = `Could not read ${manifestPath}: ${errorText4(err)}`;
+    return fail("manifest-read-failed", message);
+  }
+  const place = services.place ?? placeTarget;
+  const results = [];
+  const processedAgents = /* @__PURE__ */ new Set();
+  let stoppedEarly = false;
+  const inspections = await Promise.all(
+    AGENT_NAMES.map((agent) => inspectAgent(agent, home, installDir))
+  );
+  for (const [index, inspection] of inspections.entries()) {
+    if (stoppedEarly) {
+      break;
+    }
+    const agent = AGENT_NAMES[index];
+    processedAgents.add(agent);
+    if ("error" in inspection) {
+      return inspection.error;
+    }
+    const { targetDir, probe } = inspection;
+    if (probe.state === "absent") {
+      results.push({ agent, outcome: "skipped-not-initialized" });
+      continue;
+    }
+    if (probe.state === "unmanaged") {
+      if (!opts.force) {
+        results.push({
+          agent,
+          outcome: "failed",
+          reason: "unmanaged-target",
+          message: `${targetDir} is not a QRSPI-X-managed target (${probe.reason}). Refusing to touch it. Re-run with --force to delete it and place fresh content there.`
+        });
+        continue;
+      }
+      try {
+        const clearUnmanaged = services.clearUnmanaged ?? clearUnmanagedTarget;
+        await clearUnmanaged(targetDir);
+      } catch (err) {
+        results.push({
+          agent,
+          outcome: "failed",
+          reason: "placement-failed",
+          message: errorText4(err)
+        });
+        stoppedEarly = true;
+        continue;
+      }
+    } else if (isCurrent(probe, centralManifest)) {
+      results.push({
+        agent,
+        outcome: "already-current",
+        mode: probe.mode
+      });
+      continue;
+    }
+    const requested = probe.state === "unmanaged" ? void 0 : probe.mode;
+    const placed = await placeForUpdate(
+      place,
+      targetDir,
+      installDir,
+      requested
+    );
+    if (!placed.ok) {
+      results.push({
+        agent,
+        outcome: "failed",
+        reason: placed.reason,
+        message: placed.message
+      });
+      stoppedEarly = true;
+      continue;
+    }
+    results.push({ agent, outcome: "updated", mode: placed.mode });
+  }
+  const notReached = AGENT_NAMES.filter(
+    (agent) => !processedAgents.has(agent)
+  ).map(
+    (agent) => ({
+      agent,
+      outcome: "failed",
+      reason: "not-reached",
+      message: "Not reached: an earlier agent's update failed."
+    })
+  );
+  const allResults = [...results, ...notReached];
+  const hasFailure = allResults.some((r) => r.outcome === "failed");
+  return {
+    exitCode: hasFailure ? 1 : 0,
+    release: installResult.release,
+    version: installResult.version,
+    agents: allResults,
+    text: updateSummaryText(installResult, allResults)
+  };
+}
+function updateSummaryText(installResult, results) {
+  const parts = [String(installResult.text ?? "")];
+  for (const r of results) {
+    switch (r.outcome) {
+      case "updated":
+        parts.push(`${r.agent}: updated (${r.mode} mode).`);
+        break;
+      case "already-current":
+        parts.push(`${r.agent}: already current.`);
+        break;
+      case "skipped-not-initialized":
+        parts.push(`${r.agent}: not initialized, skipped.`);
+        break;
+      case "failed":
+        parts.push(`${r.agent}: failed (${r.reason}).`);
+        break;
+    }
+  }
+  return parts.join(" ");
+}
+async function runStatus(services = {}) {
+  const execFile2 = services.execFile ?? defaultRun4;
+  const home = services.homeDir ?? homedir2();
+  const installDir = join10(home, ".qrspi", "plugin");
+  const manifestPath = join10(installDir, "qrspi-manifest.json");
+  let installedVersion;
+  try {
+    const manifestText = await readFile8(manifestPath, "utf8");
+    installedVersion = parseManifest(manifestText)?.version;
+  } catch (err) {
+    if (err?.code !== "ENOENT") {
+      const message = `Could not read ${manifestPath}: ${errorText4(err)}`;
+      return fail("manifest-read-failed", message);
+    }
+  }
+  const inspections = await Promise.all(
+    AGENT_NAMES.map((agent) => inspectAgent(agent, home, installDir))
+  );
+  const agents = [];
+  for (const [index, inspection] of inspections.entries()) {
+    if ("error" in inspection) {
+      return inspection.error;
+    }
+    const { probe } = inspection;
+    const agent = AGENT_NAMES[index];
+    if (probe.state === "absent") {
+      agents.push({ agent, present: false });
+    } else if (probe.state === "managed") {
+      agents.push({ agent, present: true, mode: probe.mode });
+    } else {
+      agents.push({ agent, present: true, mode: "unmanaged" });
+    }
+  }
+  const github = services.github ?? gitHubAt(QRSPI_X_REPO, home, { execFile: execFile2 });
+  const freshness = await github.checkFreshness(
+    installedVersion ?? ""
+  );
+  return ok({
+    installed: installedVersion !== void 0,
+    version: installedVersion,
+    agents,
+    freshness,
+    text: `${installedVersion ? `Installed version ${installedVersion}.` : "No plugin installed."} ${freshnessText(freshness)}`.trim()
+  });
+}
+function freshnessText(freshness) {
+  switch (freshness.status) {
+    case "update-available":
+      return `Update available: ${freshness.latest}.`;
+    case "up-to-date":
+      return "Up to date.";
+    case "unknown":
+      if (freshness.message) {
+        return `Error checking available releases: ${freshness.message}`;
+      }
+      return freshness.latest ? `Latest available: ${freshness.latest}.` : "";
+  }
+}
+async function checkInstall(installDir) {
+  let entries;
+  try {
+    entries = await readdir4(installDir);
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      return { ok: false, reason: "not-installed" };
+    }
+    return {
+      ok: false,
+      reason: "install-check-failed",
+      message: errorText4(err)
+    };
+  }
+  return entries.length > 0 ? { ok: true } : { ok: false, reason: "not-installed" };
+}
+function errorText4(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function fail(code, message) {
+  return {
+    exitCode: 1,
+    code,
+    text: message
+  };
+}
+
+// src/command/start.ts
+import { readFile as readFile9 } from "node:fs/promises";
+import { join as join11 } from "node:path";
+var phaseFlag = {
+  flag: "--phase <id>",
+  required: true,
+  description: "The phase this unit of work targets."
+};
+var loopFlag = {
+  flag: "--loop",
+  required: false,
+  description: "Write the pre-spawn crash-safety intent to loop-state.json before the caller spawns its agent."
+};
+var baseFlag = {
+  flag: "--base <commit-ish>",
+  required: false,
+  description: "Explicitly overwrite loop-state.json's recorded base for this phase. Fixes base-not-ancestor/phase-base-reset; --loop only."
+};
+var implementHelp2 = {
+  name: "implement",
+  summary: "Confirm it's clear to implement <phase>, or report why not.",
+  flags: [...commonOptions, phaseFlag, loopFlag, baseFlag],
+  example: "qrspi-x start implement --feature widget --project . --phase 1 --loop"
+};
+var reviewHelp2 = {
+  name: "review",
+  summary: "Confirm it's clear to review <phase>, or report why not.",
+  flags: [...commonOptions, phaseFlag, loopFlag, baseFlag],
+  example: "qrspi-x start review --feature widget --project . --phase 1 --loop"
+};
+var repairHelp2 = {
+  name: "repair",
+  summary: "Confirm it's clear to repair <phase>'s last FAIL, or report why not.",
+  flags: [...commonOptions, phaseFlag, loopFlag],
+  example: "qrspi-x start repair --feature widget --project . --phase 1 --loop"
+};
+var help8 = {
+  name: "start",
+  summary: "Begin implement/review/repair: confirm ready, or report blockers.",
+  actions: [implementHelp2, reviewHelp2, repairHelp2]
+};
+async function resolveBase(opts, git, loopState, hasWorkBegun) {
+  if (opts.base !== void 0) {
+    return { baseSha: opts.base, resetBase: true };
+  }
+  const state = await loopState.read();
+  const recordedBase = state?.bases[opts.phase];
+  if (recordedBase === void 0) {
+    if (await hasWorkBegun()) {
+      return {
+        baseSha: await git.headSha(),
+        resetBase: false,
+        finding: {
+          code: "phase-base-reset",
+          message: `Phase ${opts.phase} has steps begun but no base recorded; its checkpoint diff will start at the current commit. Pass --base <commit-ish> to point at where its work actually began.`
+        }
+      };
+    }
+    return { baseSha: await git.headSha(), resetBase: false };
+  }
+  if (!await git.isAncestor(recordedBase)) {
+    return {
+      baseSha: recordedBase,
+      resetBase: false,
+      finding: {
+        code: "base-not-ancestor",
+        message: `Phase ${opts.phase}'s recorded base ${recordedBase} is no longer an ancestor of HEAD; retry with --base <commit-ish>.`
+      }
+    };
+  }
+  return { baseSha: recordedBase, resetBase: false };
+}
+async function writeBegin(history, kind, filter, rest = {}) {
+  await history.conditionalAppend({ kind, ...filter }, { action: "begin" }, {
+    kind,
+    action: "begin",
+    ...filter,
+    ...rest
+  });
+}
+async function implement2(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { workspace, loopState, history, git } = resolveServices(
+    root,
+    opts.project,
+    services
+  );
+  if (!await git.isClean()) {
+    return blocked([
+      { code: "dirty-tree", message: "working tree is not clean" }
+    ]);
+  }
+  const progress = await workspace.checkProgress(opts.phase);
+  if (!progress.dependenciesSatisfied) {
+    return blocked([
+      {
+        code: "incomplete-dependency",
+        message: `Phase ${opts.phase} depends on a phase that isn't done yet.`
+      }
+    ]);
+  }
+  if (!opts.loop) {
+    await writeBegin(history, "implement", { phase: opts.phase });
+    return ok({ phaseId: opts.phase });
+  }
+  const { baseSha, resetBase, finding } = await resolveBase(
+    opts,
+    git,
+    loopState,
+    async () => progress.complete > 0
+  );
+  await loopState.writeInFlight("implement", opts.phase, {
+    baseSha,
+    resetBase
+  });
+  await writeBegin(history, "implement", { phase: opts.phase });
+  return finding ? warn({ phaseId: opts.phase }, [finding]) : ok({ phaseId: opts.phase });
+}
+async function review2(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { workspace, loopState, history, git } = resolveServices(
+    root,
+    opts.project,
+    services
+  );
+  if (!await workspace.isPhaseComplete(opts.phase)) {
+    return blocked([
+      {
+        code: "phase-not-complete",
+        message: `Phase ${opts.phase}'s steps aren't all [x] yet.`
+      }
+    ]);
+  }
+  const state = opts.loop ? await loopState.read() : void 0;
+  const inFlightLabel = state?.inFlight?.task === "review" && state.inFlight.phaseId === opts.phase ? state.inFlight.label : void 0;
+  let label = inFlightLabel;
+  if (label === void 0) {
+    label = await workspace.pendingReviewLabel(opts.phase);
+  }
+  if (label === void 0) {
+    label = await workspace.nextLabel("review", { phase: opts.phase });
+  }
+  if (!opts.loop) {
+    await writeBegin(history, "review", { label }, { phase: opts.phase });
+    return ok({ label });
+  }
+  const progress = await workspace.checkProgress(opts.phase);
+  const { baseSha, resetBase, finding } = await resolveBase(
+    opts,
+    git,
+    loopState,
+    // review only ever runs after implement has started the phase
+    // under --loop, so a missing base here means the same thing as
+    // for implement: work is underway with nothing recorded.
+    async () => progress.complete > 0
+  );
+  await loopState.writeInFlight("review", opts.phase, {
+    label,
+    baseSha,
+    resetBase
+  });
+  await writeBegin(history, "review", { label }, { phase: opts.phase });
+  const diff = `git diff ${baseSha}..HEAD`;
+  return finding ? warn({ label, diff }, [finding]) : ok({ label, diff });
+}
+async function repair2(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { workspace, loopState, history } = resolveServices(
+    root,
+    opts.project,
+    services
+  );
+  const state = await loopState.read();
+  const path = opts.loop && state?.checkpoint ? reviewPath(state.checkpoint.label) : await workspace.lastFile("review", { phase: opts.phase });
+  if (path === void 0) {
+    return blocked([
+      {
+        code: "no-fail-review",
+        message: `No review exists yet for phase ${opts.phase}.`
+      }
+    ]);
+  }
+  const text = await readFile9(join11(root, path), "utf8");
+  if (parseVerdict(text) !== "FAIL") {
+    return blocked([
+      {
+        code: "no-fail-review",
+        message: `Phase ${opts.phase}'s last review (${path}) isn't a FAIL.`
+      }
+    ]);
+  }
+  if (!opts.loop) {
+    await writeBegin(history, "repair", { phase: opts.phase });
+    return ok({ review: path });
+  }
+  try {
+    await loopState.writeInFlight("repair", opts.phase);
+  } catch (err) {
+    if (err instanceof RepairAlreadySpentError) {
+      return blocked([
+        {
+          code: "repair-already-spent",
+          message: err.message
+        }
+      ]);
+    }
+    throw err;
+  }
+  await writeBegin(history, "repair", { phase: opts.phase });
+  return ok({ review: path });
+}
+
+// src/command/status.ts
+var help9 = {
+  name: "status",
+  summary: "Read-only: implementation/review/loop facts. Never writes.",
+  flags: [...commonOptions]
+};
+async function run3(opts, services = {}) {
+  const root = resolveRoot(opts.project, opts.feature);
+  const { workspace, loopState, history } = resolveServices(
+    root,
+    opts.project,
+    services
+  );
+  const parked = await history.isParked();
+  const current = {};
+  const next = {};
+  const findings = [];
+  let step;
+  if (parked) {
+    step = "parked";
+  } else {
+    step = await workspace.deriveStep();
+  }
+  current.step = step;
+  if (step === "implement") {
+    try {
+      const active = await workspace.findActivePhase();
+      current.phase = active.phase;
+      current.planProgress = active.planProgress;
+      if (active.staleInput) {
+        findings.push({
+          code: "stale-input",
+          message: `${active.staleInput.phaseFile} predates spec.md (phase file ${active.staleInput.phaseFileMtime.toISOString()}, spec.md ${active.staleInput.specMtime.toISOString()}).`
+        });
+      }
+    } catch (err) {
+      if (err instanceof NoActivePhaseError) {
+        findings.push({
+          code: "all-phases-blocked",
+          message: `Every incomplete phase is blocked on an unsatisfied dependency (${err.blockedPhases.join(", ")}).`
+        });
+      } else if (err instanceof DependencyCycleError || err instanceof UnknownPhaseError) {
+        findings.push({
+          code: "plan-unreadable",
+          message: err.message
+        });
+      } else {
+        throw err;
+      }
+    }
+  }
+  const loopStatus = await loopState.status();
+  let loop;
+  if (loopStatus) {
+    const { action, label, diff, review: review3, ...rest } = loopStatus;
+    loop = rest;
+    next.action = action;
+    next.label = label;
+    next.diff = diff;
+    next.review = review3;
+  } else if (current.phase) {
+    next.label = await workspace.nextLabel("review", {
+      phase: current.phase
+    });
+  }
+  const fields = {
+    current,
+    ...Object.keys(next).length > 0 ? { next } : {},
+    ...loop ? { loop } : {}
+  };
+  return findings.length > 0 ? warn(fields, findings) : ok(fields);
+}
+
+// src/cli.ts
+var commandHelps = [
+  help,
+  help2,
+  help4,
+  help5,
+  help6,
+  help8,
+  help9,
+  help3,
+  help7
+];
+var commandNames = new Set(commandHelps.map((entry) => entry.name));
+var UsageError = class extends Error {
+};
+function processIo() {
+  return {
+    cwd: process.cwd(),
+    stdout: (line) => process.stdout.write(`${line}
+`),
+    stderr: (line) => process.stderr.write(`${line}
+`)
+  };
+}
+async function main(argv, io = processIo()) {
+  try {
+    if (argv.length === 0) {
+      io.stdout(renderToolHelp(commandHelps));
+      return 0;
+    }
+    if (argv[0] === "--version") {
+      io.stdout(version());
+      return 0;
+    }
+    if (argv.includes("--help") || argv.includes("-h")) {
+      const positionals2 = [];
+      for (const arg of argv) {
+        if (arg === "--help" || arg === "-h") {
+          continue;
+        }
+        if (arg.startsWith("-")) {
+          break;
+        }
+        positionals2.push(arg);
+      }
+      return emitHelp(positionals2, io);
+    }
+    const command = argv[0];
+    if (command === void 0 || !commandNames.has(command)) {
+      throw new UsageError(`Unknown command "${command ?? ""}"`);
+    }
+    const { positionals, options } = parseOptions(argv.slice(1));
+    validateOptions(command, positionals, options);
+    const result = command === "plugin" ? await dispatchPlugin(positionals, options) : command === "import" ? await dispatchImport(
+      positionals,
+      options,
+      projectAndOptionalFeature(options, io.cwd)
+    ) : await dispatch(
+      command,
+      positionals,
+      options,
+      projectAndFeature(options, io.cwd)
+    );
+    if (typeof result === "string") {
+      io.stdout(result);
+    } else if (Array.isArray(result)) {
+      io.stdout(JSON.stringify(result));
+    } else if (typeof result.text === "string") {
+      io.stdout(result.text);
+    } else {
+      io.stdout(JSON.stringify(toJson(result)));
+    }
+    return typeof result === "object" && !Array.isArray(result) ? result.exitCode : 0;
+  } catch (error) {
+    if (error instanceof UsageError) {
+      io.stderr(error.message);
+      return 2;
+    }
+    io.stderr(
+      error instanceof Error ? error.stack ?? error.message : String(error)
+    );
+    return 4;
+  }
+}
+function emitHelp(args, io) {
+  const command = args[0];
+  if (command === void 0) {
+    io.stdout(renderToolHelp(commandHelps));
+    return 0;
+  }
+  const help10 = commandHelps.find((entry) => entry.name === command);
+  if (help10 === void 0) {
+    io.stderr(`Unknown command "${command}"`);
+    return 2;
+  }
+  const action = args[1];
+  if (action === void 0) {
+    io.stdout(renderHelp(help10));
+    return 0;
+  }
+  io.stdout(renderHelp(help10, action));
+  return 0;
+}
+function parseOptions(args) {
+  const positionals = [];
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+    const equals = token.indexOf("=");
+    const name = equals === -1 ? token : token.slice(0, equals);
+    const attached = equals === -1 ? void 0 : token.slice(equals + 1);
+    if (name === "--loop" || name === "--all" || name === "--copy" || name === "--symlink" || name === "--force") {
+      setOption(options, name.slice(2), true);
+      continue;
+    }
+    const value = attached ?? args[++i];
+    if (value === void 0 || value === "" || attached === void 0 && value.startsWith("--")) {
+      throw new UsageError(`${name} requires a non-empty value`);
+    }
+    setOption(options, name.slice(2), value);
+  }
+  return { positionals, options };
+}
+function flagName(flag) {
+  if (!flag.startsWith("--")) return void 0;
+  const token = flag.split(/[\s=]/, 1)[0];
+  return token.slice(2);
+}
+function allowedFlagNames(flags) {
+  const names = /* @__PURE__ */ new Set();
+  for (const f of flags ?? []) {
+    const name = flagName(f.flag);
+    if (name) names.add(name);
+  }
+  return names;
+}
+function validateOptions(command, positionals, options) {
+  const help10 = commandHelps.find((c) => c.name === command);
+  if (!help10) {
+    return;
+  }
+  let flags;
+  let scope = command;
+  if (help10.actions && help10.actions.length > 0) {
+    const actionName = positionals[0];
+    const action = help10.actions.find(
+      (a) => a.name === actionName
+    );
+    if (!action) {
+      throw new UsageError(
+        `Unknown ${command} action "${actionName ?? ""}"`
+      );
+    }
+    flags = action.flags;
+    scope = `${command} ${actionName}`;
+  } else {
+    flags = help10.flags;
+  }
+  const allowed = allowedFlagNames(flags);
+  for (const name of Object.keys(options)) {
+    if (!allowed.has(name)) {
+      throw new UsageError(`Unknown option "--${name}" for "${scope}"`);
+    }
+  }
+}
+function setOption(options, name, value) {
+  if (options[name] !== void 0) {
+    throw new UsageError(`--${name} was given more than once`);
+  }
+  options[name] = value;
+}
+function required(options, name) {
+  const value = options[name];
+  if (typeof value !== "string") {
+    throw new UsageError(`--${name} is required`);
+  }
+  return value;
+}
+function projectAndOptionalFeature(options, cwd) {
+  const project = options.project;
+  const feature = options.feature;
+  return {
+    feature: typeof feature === "string" ? feature : void 0,
+    project: typeof project === "string" ? project : cwd
+  };
+}
+function projectAndFeature(options, cwd) {
+  const project = options.project;
+  return {
+    feature: required(options, "feature"),
+    project: typeof project === "string" ? project : cwd
+  };
+}
+async function dispatch(command, positionals, options, common) {
+  switch (command) {
+    case "status":
+      return dispatchStatus(positionals, common);
+    case "next-file":
+      return dispatchNextFile(positionals, options, common);
+    case "loop":
+      return dispatchLoop(positionals, common);
+    case "decision":
+      return dispatchDecision(positionals, options, common);
+    case "history":
+      return dispatchHistory(positionals, options, common);
+    case "start":
+      return dispatchStart(positionals, options, common);
+    case "log":
+      return dispatchLog(positionals, options, common);
+    default:
+      throw new UsageError(`Unknown command "${command}"`);
+  }
+}
+function dispatchStatus(positionals, common) {
+  if (positionals.length !== 0) {
+    throw new UsageError("status takes no positional arguments");
+  }
+  return run3(common);
+}
+function dispatchNextFile(positionals, options, common) {
+  const type = positionals[0];
+  if (type === void 0 || positionals.length !== 1) {
+    throw new UsageError("next-file requires exactly one type");
+  }
+  return run2(type, {
+    ...common,
+    phase: typeof options.phase === "string" ? options.phase : void 0,
+    step: typeof options.step === "string" ? Number(options.step) : void 0
+  });
+}
+async function dispatchImport(positionals, options, common) {
+  const number = positionals[0];
+  if (number === void 0 || positionals.length !== 1) {
+    throw new UsageError("import requires exactly one issue or PR number");
+  }
+  const repo = typeof options.repo === "string" ? options.repo : void 0;
+  return runImport({
+    number,
+    project: common.project,
+    feature: common.feature,
+    repo
+  });
+}
+async function dispatchPlugin(positionals, options) {
+  const action = singleAction("plugin", positionals);
+  switch (action) {
+    case "install":
+      return runInstall({ release: optional(options, "release") });
+    case "init":
+      return runInit({
+        agent: required(options, "agent"),
+        copy: options.copy === true,
+        symlink: options.symlink === true,
+        force: options.force === true
+      });
+    case "status":
+      return runStatus();
+    case "update":
+      return runUpdate({
+        release: optional(options, "release"),
+        force: options.force === true
+      });
+    case "remove":
+      return runRemove({
+        agent: required(options, "agent"),
+        force: options.force === true
+      });
+    default:
+      throw new UsageError(`Unknown plugin action "${action}"`);
+  }
+}
+function singleAction(command, positionals) {
+  const action = positionals[0];
+  if (action === void 0 || positionals.length !== 1) {
+    throw new UsageError(`${command} requires exactly one action`);
+  }
+  return action;
+}
+function dispatchDecision(positionals, options, common) {
+  const action = singleAction("decision", positionals);
+  switch (action) {
+    case "add":
+      return add({ ...common, text: required(options, "text") });
+    case "read":
+      return read(common);
+    default:
+      throw new UsageError(`Unknown decision action "${action}"`);
+  }
+}
+function dispatchHistory(positionals, options, common) {
+  const action = singleAction("history", positionals);
+  switch (action) {
+    case "add":
+      return add2({ ...common, text: required(options, "text") });
+    case "read": {
+      if (options.all === true && options.tail !== void 0) {
+        throw new UsageError(
+          "history read cannot combine --all and --tail"
+        );
+      }
+      return read2({
+        ...common,
+        tail: typeof options.tail === "string" ? Number(options.tail) : void 0,
+        all: options.all === true,
+        kind: typeof options.kind === "string" ? options.kind : void 0,
+        phase: typeof options.phase === "string" ? options.phase : void 0
+      });
+    }
+    default:
+      throw new UsageError(`Unknown history action "${action}"`);
+  }
+}
+function dispatchStart(positionals, options, common) {
+  const action = singleAction("start", positionals);
+  const task = {
+    ...common,
+    phase: required(options, "phase"),
+    loop: options.loop === true,
+    base: typeof options.base === "string" ? options.base : void 0
+  };
+  switch (action) {
+    case "implement":
+      return implement2(task);
+    case "review":
+      return review2(task);
+    case "repair":
+      return repair2(task);
+    default:
+      throw new UsageError(`Unknown start action "${action}"`);
+  }
+}
+function dispatchLog(positionals, options, common) {
+  const action = singleAction("log", positionals);
+  switch (action) {
+    case "implement":
+      return implement({
+        ...common,
+        phase: required(options, "phase"),
+        reason: optional(options, "reason")
+      });
+    case "repair":
+      return repair({
+        ...common,
+        phase: required(options, "phase"),
+        reason: optional(options, "reason")
+      });
+    case "review":
+      return review({ ...common, label: required(options, "label") });
+    case "park":
+      return park({ ...common, reason: optional(options, "reason") });
+    default:
+      throw new UsageError(`Unknown log action "${action}"`);
+  }
+}
+async function dispatchLoop(positionals, common) {
+  const action = positionals[0];
+  const arg = positionals[1];
+  switch (action) {
+    case "start": {
+      if (arg === void 0 || positionals.length !== 2) {
+        throw new UsageError(
+          "loop start requires exactly one selector"
+        );
+      }
+      return start({ ...common, selector: arg });
+    }
+    case "advance": {
+      if (positionals.length !== 1) {
+        throw new UsageError("loop advance takes no arguments");
+      }
+      return advance(common);
+    }
+    case "stop": {
+      if (arg === void 0 || positionals.length !== 2) {
+        throw new UsageError("loop stop requires exactly one reason");
+      }
+      return stop({ ...common, reason: arg });
+    }
+    case "ok": {
+      if (positionals.length > 2) {
+        throw new UsageError("loop ok takes at most one reason");
+      }
+      return loopOk({ ...common, reason: arg });
+    }
+    case "abandon": {
+      if (arg === void 0 || positionals.length !== 2) {
+        throw new UsageError(
+          "loop abandon requires exactly one reason"
+        );
+      }
+      return abandon({ ...common, reason: arg });
+    }
+    default:
+      throw new UsageError(`Unknown loop action "${action ?? ""}"`);
+  }
+}
+function optional(options, name) {
+  return typeof options[name] === "string" ? options[name] : void 0;
+}
+function version() {
+  return true ? "0.10.0+g6a64539" : "0.0.0-dev";
+}
+
+// src/bin.ts
+process.exitCode = await main(process.argv.slice(2));