quest-loop 0.1.0

package/lib/contract.mjs

@@ -0,0 +1,225 @@
+// The quest record contract: field validation, canonical serialization,
+// checkpoint format, lint rules, status transitions. Byte-level spec:
+// skills/protocol/references/contract-spec.md — this module IS that spec in code.
+
+import { parseFrontmatter, serializeFrontmatter, FrontmatterError } from "./frontmatter.mjs";
+
+export const STATUSES = ["todo", "in_progress", "blocked", "complete", "cancelled"];
+export const QUEST_STATUSES = ["in_progress", "complete", "blocked"];
+export const PRIORITIES = ["p0", "p1", "p2"];
+export const WORKERS = ["claude", "codex"];
+export const CHECKPOINT_MARKER = "<!-- quest:checkpoint -->";
+
+const REQUIRED_FRONT = ["id", "title", "status", "priority", "worker", "model", "max_iterations", "created", "updated"];
+const OPTIONAL_FRONT = ["effort", "max_cost", "parent", "depends_on"];
+const FRONT_ORDER = ["id", "title", "status", "priority", "worker", "model", "effort", "max_iterations", "max_cost", "parent", "depends_on", "created", "updated"];
+const REQUIRED_SECTIONS = ["## Objective", "## Done when", "## Validation loop"];
+const SECTION_ORDER = ["## Objective", "## Done when", "## Validation loop", "## Constraints", "## Milestones", "## Context", "## Out of scope", "## Checkpoints"];
+
+export class ContractError extends Error {
+  constructor(message, { hint } = {}) {
+    super(message);
+    this.hint = hint;
+  }
+}
+
+export function nowIso() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+export function slugify(title) {
+  let slug = String(title)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (slug.length > 40) {
+    const cut = slug.slice(0, 41).lastIndexOf("-");
+    slug = slug.slice(0, cut > 0 ? cut : 40);
+  }
+  return slug || "quest";
+}
+
+export function recordFilename(id, title) {
+  return `${String(id).padStart(3, "0")}-${slugify(title)}.md`;
+}
+
+export function parseRecord(text) {
+  let front, body;
+  try {
+    ({ front, body } = parseFrontmatter(text));
+  } catch (err) {
+    if (err instanceof FrontmatterError) throw new ContractError(err.message, { hint: "records are written by `quest` commands; see contract-spec.md for the exact format" });
+    throw err;
+  }
+  return { front, body, checkpoints: parseCheckpoints(body) };
+}
+
+export function parseCheckpoints(body) {
+  const checkpoints = [];
+  const lines = body.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() !== CHECKPOINT_MARKER) continue;
+    const header = lines[i + 1] ?? "";
+    const hm = header.match(/^### (\S+) — quest_status: (\S+)$/);
+    if (!hm) throw new ContractError(`malformed checkpoint header after marker at line ${i + 1}: "${header}"`);
+    const cp = { timestamp: hm[1], quest_status: hm[2], fields: {}, note: "" };
+    let j = i + 2;
+    for (; j < lines.length; j++) {
+      const fm = lines[j].match(/^- ([a-z_]+): (.*)$/);
+      if (!fm) break;
+      cp.fields[fm[1]] = fm[2];
+    }
+    const noteLines = [];
+    for (; j < lines.length && lines[j].trim() !== CHECKPOINT_MARKER && !lines[j].startsWith("### "); j++) {
+      noteLines.push(lines[j]);
+    }
+    cp.note = noteLines.join("\n").trim();
+    checkpoints.push(cp);
+  }
+  return checkpoints;
+}
+
+export function makeCheckpoint({ timestamp, quest_status, iteration, changed, validation_summary, pr, head_sha, failed_approaches, compatible_expansion, note }) {
+  if (!QUEST_STATUSES.includes(quest_status)) {
+    throw new ContractError(`quest_status must be one of ${QUEST_STATUSES.join(" | ")} (got "${quest_status}")`, { hint: "store statuses like todo/cancelled are not checkpoint verdicts" });
+  }
+  for (const [name, v] of [["iteration", iteration], ["changed", changed], ["validation_summary", validation_summary]]) {
+    if (v === undefined || String(v).trim() === "") throw new ContractError(`checkpoint field "${name}" is required`, { hint: "see `quest checkpoint --help` for the full field list" });
+  }
+  if (quest_status === "complete" && !/`[^`]+`/.test(validation_summary)) {
+    throw new ContractError("a `complete` checkpoint's validation_summary must cite at least one backticked command — commands, not adjectives", { hint: 'example: --validation "`npm test` → 42 passed"' });
+  }
+  const oneLine = (name, v) => {
+    if (/\n/.test(String(v))) throw new ContractError(`checkpoint field "${name}" must be a single line (use the trailing note for prose)`);
+    return String(v);
+  };
+  const out = [CHECKPOINT_MARKER, `### ${timestamp} — quest_status: ${quest_status}`, `- iteration: ${oneLine("iteration", iteration)}`];
+  if (pr) out.push(`- pr: ${oneLine("pr", pr)}`);
+  if (head_sha) out.push(`- head_sha: ${oneLine("head_sha", head_sha)}`);
+  out.push(`- changed: ${oneLine("changed", changed)}`);
+  out.push(`- validation_summary: ${oneLine("validation_summary", validation_summary)}`);
+  if (failed_approaches) out.push(`- failed_approaches: ${oneLine("failed_approaches", failed_approaches)}`);
+  if (compatible_expansion) out.push(`- compatible_expansion: ${oneLine("compatible_expansion", compatible_expansion)}`);
+  if (note && String(note).trim() !== "") out.push("", String(note).trim());
+  return out.join("\n");
+}
+
+export function serializeRecord(front, body) {
+  const ordered = {};
+  for (const key of FRONT_ORDER) if (key in front) ordered[key] = front[key];
+  for (const key of Object.keys(front)) if (!(key in ordered)) ordered[key] = front[key];
+  return `${serializeFrontmatter(ordered)}\n\n${body.replace(/^\n+/, "")}`;
+}
+
+const TRANSITIONS = {
+  todo: ["in_progress", "cancelled"],
+  in_progress: ["in_progress", "complete", "blocked", "cancelled"],
+  blocked: ["in_progress", "blocked", "cancelled"],
+  complete: [],
+  cancelled: [],
+};
+
+export function assertTransition(from, to) {
+  if (!(TRANSITIONS[from] ?? []).includes(to)) {
+    throw new ContractError(`illegal status transition: ${from} → ${to}`, {
+      hint: from === "complete" || from === "cancelled" ? `${from} is terminal — file a new quest instead` : `legal from "${from}": ${TRANSITIONS[from].join(", ") || "(none)"}`,
+    });
+  }
+}
+
+export function lintRecord({ front, body, checkpoints }, { filename } = {}) {
+  const problems = [];
+  for (const key of REQUIRED_FRONT) {
+    if (!(key in front)) problems.push(`missing frontmatter key "${key}"`);
+  }
+  for (const key of Object.keys(front)) {
+    if (!REQUIRED_FRONT.includes(key) && !OPTIONAL_FRONT.includes(key)) problems.push(`unknown frontmatter key "${key}"`);
+  }
+  if ("id" in front && (!Number.isInteger(front.id) || front.id < 1)) problems.push(`id must be a positive integer (got ${JSON.stringify(front.id)})`);
+  if ("status" in front && !STATUSES.includes(front.status)) problems.push(`status must be one of ${STATUSES.join(" | ")} (got "${front.status}")`);
+  if ("priority" in front && !PRIORITIES.includes(front.priority)) problems.push(`priority must be one of ${PRIORITIES.join(" | ")} (got "${front.priority}")`);
+  if ("worker" in front && !WORKERS.includes(front.worker)) problems.push(`worker must be one of ${WORKERS.join(" | ")} (got "${front.worker}")`);
+  if ("max_iterations" in front && (!Number.isInteger(front.max_iterations) || front.max_iterations < 1)) problems.push("max_iterations must be a positive integer");
+  if ("depends_on" in front && (!Array.isArray(front.depends_on) || front.depends_on.some((d) => !Number.isInteger(d)))) problems.push("depends_on must be a list of quest ids");
+  if ("parent" in front && !Number.isInteger(front.parent)) problems.push("parent must be a quest id");
+  for (const ts of ["created", "updated"]) {
+    if (ts in front && !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(String(front[ts]))) problems.push(`${ts} must be UTC ISO-8601 ending in Z`);
+  }
+  for (const section of REQUIRED_SECTIONS) {
+    if (!body.split("\n").some((l) => l.trim() === section)) problems.push(`missing required section "${section}"`);
+  }
+  const present = SECTION_ORDER.filter((s) => body.split("\n").some((l) => l.trim() === s));
+  const actual = body.split("\n").map((l) => l.trim()).filter((l) => SECTION_ORDER.includes(l));
+  if (JSON.stringify(present) !== JSON.stringify(actual)) problems.push(`sections out of canonical order (expected ${present.join(" → ")})`);
+  if (filename && "id" in front && "title" in front) {
+    const expected = recordFilename(front.id, front.title);
+    if (filename !== expected) problems.push(`filename "${filename}" does not match canonical "${expected}"`);
+  }
+  for (const [i, cp] of checkpoints.entries()) {
+    if (!QUEST_STATUSES.includes(cp.quest_status)) problems.push(`checkpoint ${i + 1}: quest_status "${cp.quest_status}" not in ${QUEST_STATUSES.join(" | ")}`);
+    for (const req of ["iteration", "changed", "validation_summary"]) {
+      if (!cp.fields[req]) problems.push(`checkpoint ${i + 1}: missing required field "${req}"`);
+    }
+    if (cp.quest_status === "complete" && cp.fields.validation_summary && !/`[^`]+`/.test(cp.fields.validation_summary)) {
+      problems.push(`checkpoint ${i + 1}: complete requires a backticked command in validation_summary`);
+    }
+  }
+  if (front.status === "complete") {
+    const last = checkpoints.at(-1);
+    if (!last || last.quest_status !== "complete") problems.push('status is "complete" but the last checkpoint is not quest_status: complete');
+  }
+  return problems;
+}
+
+// Body rendering + section editing. Shared by every backend so the body bytes
+// are identical whether a record lives on disk (store-local) or as a GitHub
+// issue (store-github).
+
+export function renderBody(title, s) {
+  const lines = [`# ${title}`, "", "## Objective", s.objective.trim(), "", "## Done when"];
+  for (const item of s.doneWhen) lines.push(`- [ ] ${item}`);
+  lines.push("", "## Validation loop", "```bash", s.validation.trim(), "```");
+  if (s.constraints?.length) {
+    lines.push("", "## Constraints");
+    for (const c of s.constraints) lines.push(`- ${c}`);
+  }
+  if (s.milestones?.length) {
+    lines.push("", "## Milestones");
+    for (const [i, m] of s.milestones.entries()) lines.push(`- [ ] M${i + 1} — ${m}`);
+  }
+  if (s.context) lines.push("", "## Context", s.context.trim());
+  if (s.outOfScope?.length) {
+    lines.push("", "## Out of scope");
+    for (const o of s.outOfScope) lines.push(`- ${o}`);
+  }
+  lines.push("", "## Checkpoints", "");
+  return lines.join("\n");
+}
+
+export function appendUnderCheckpoints(body, block) {
+  const hasSection = body.split("\n").some((l) => l.trim() === "## Checkpoints");
+  const trimmed = body.replace(/\n+$/, "");
+  return hasSection ? `${trimmed}\n\n${block}\n` : `${trimmed}\n\n## Checkpoints\n\n${block}\n`;
+}
+
+export function appendToSection(body, section, line, { createAfter } = {}) {
+  const lines = body.split("\n");
+  const start = lines.findIndex((l) => l.trim() === section);
+  if (start === -1) {
+    if (!createAfter) throw new ContractError(`section "${section}" not found`);
+    const anchorEnd = sectionEnd(lines, createAfter);
+    lines.splice(anchorEnd, 0, "", section, line);
+    return lines.join("\n");
+  }
+  lines.splice(sectionEnd(lines, section), 0, line);
+  return lines.join("\n");
+}
+
+function sectionEnd(lines, section) {
+  const start = lines.findIndex((l) => l.trim() === section);
+  if (start === -1) throw new ContractError(`section "${section}" not found`);
+  let end = start + 1;
+  while (end < lines.length && !lines[end].startsWith("## ")) end++;
+  while (end > start + 1 && lines[end - 1].trim() === "") end--;
+  return end;
+}

package/lib/frontmatter.mjs

@@ -0,0 +1,61 @@
+// Strict YAML-subset frontmatter: only `key: scalar` and `key: [a, b]` lines.
+// No nesting, no multi-line values, no quoting. Reject anything else with a
+// precise error — records are written only by this tool, so canonical form is
+// guaranteed and hand-edits that stray from it must fail loudly.
+
+export class FrontmatterError extends Error {}
+
+const KEY_RE = /^([a-z][a-z0-9_]*):(?: (.*))?$/;
+
+function parseScalar(raw) {
+  const s = raw.trim();
+  if (/^-?\d+$/.test(s)) return Number(s);
+  if (/^-?\d+\.\d+$/.test(s)) return Number(s);
+  return s;
+}
+
+export function parseFrontmatter(text) {
+  const lines = text.split("\n");
+  if (lines[0] !== "---") throw new FrontmatterError("record must start with `---` frontmatter fence");
+  const end = lines.indexOf("---", 1);
+  if (end === -1) throw new FrontmatterError("unterminated frontmatter: closing `---` fence not found");
+  const front = {};
+  for (let i = 1; i < end; i++) {
+    const line = lines[i];
+    if (line.trim() === "") continue;
+    const m = line.match(KEY_RE);
+    if (!m) {
+      throw new FrontmatterError(
+        `frontmatter line ${i + 1} is not \`key: value\`: "${line}" (nested/multi-line YAML is not supported; see contract-spec.md)`,
+      );
+    }
+    const [, key, rawValue] = m;
+    if (key in front) throw new FrontmatterError(`duplicate frontmatter key "${key}"`);
+    if (rawValue === undefined || rawValue.trim() === "") {
+      throw new FrontmatterError(`frontmatter key "${key}" has no value (omit optional keys entirely)`);
+    }
+    const v = rawValue.trim();
+    if (v.startsWith("[")) {
+      if (!v.endsWith("]")) throw new FrontmatterError(`frontmatter key "${key}": inline list must close with ]`);
+      const inner = v.slice(1, -1).trim();
+      front[key] = inner === "" ? [] : inner.split(",").map((x) => parseScalar(x));
+    } else {
+      front[key] = parseScalar(v);
+    }
+  }
+  return { front, body: lines.slice(end + 1).join("\n") };
+}
+
+export function serializeFrontmatter(front) {
+  const out = ["---"];
+  for (const [key, value] of Object.entries(front)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      out.push(`${key}: [${value.join(", ")}]`);
+    } else {
+      out.push(`${key}: ${value}`);
+    }
+  }
+  out.push("---");
+  return out.join("\n");
+}

package/lib/help.mjs

@@ -0,0 +1,195 @@
+// All human-facing guidance lives here so it can be snapshot-tested and can't
+// drift silently from the contract. Keep texts deterministic (no timestamps).
+
+export const INTRO = `quest — goal-loop engineering for coding agents
+
+Work is planned as quests: contracts with an Objective, evidence-checkable
+"Done when" items, and a Validation loop. Agents (or you) work them in
+iterations that end in checkpoints; \`quest-run\` drives headless workers.`;
+
+export const COMMANDS = {
+  init: {
+    purpose: "Create a quest store (.quests/) in the current directory",
+    usage: "quest init [--backend local|github] [--repo owner/name] [--agents-md]",
+    flags: [
+      ["--backend <b>", "record storage: local files (default) or github issues"],
+      ["--repo <owner/name>", "required with --backend github"],
+      ["--agents-md", "append a quest orientation section to ./AGENTS.md"],
+    ],
+    example: "quest init",
+  },
+  create: {
+    purpose: "Create a new quest (the only way records are born)",
+    usage: "quest create --title T --objective O --done-when D --validation V [more flags]",
+    flags: [
+      ["--title <t>", "quest title (required)"],
+      ["--objective <o>", "one concrete outcome, ≤3 sentences (required)"],
+      ["--done-when <d>", "evidence-checkable condition; repeatable (≥1 required)"],
+      ["--validation <cmds>", "exact commands run each iteration (required)"],
+      ["--constraint <c>", "hard guardrail; repeatable"],
+      ["--milestone <m>", "discrete testable unit; repeatable"],
+      ["--context <text>", "pointers: files + symbols, related quests"],
+      ["--out-of-scope <o>", "explicit exclusion; repeatable"],
+      ["--parent <id>", "epic this quest belongs to"],
+      ["--depends-on <ids>", "comma-separated quest ids that must complete first"],
+      ["--worker <w>", "claude (default) or codex"],
+      ["--model <m>", "worker model; default inherit (store config)"],
+      ["--effort <e>", "worker reasoning effort (e.g. xhigh)"],
+      ["--max-iterations <n>", "session budget (default from config)"],
+      ["--max-cost <usd>", "cost budget for headless runs"],
+      ["--priority <p>", "p0 | p1 | p2 (default from config)"],
+    ],
+    example: `quest create --title "Add dark mode" \\
+  --objective "Settings page offers a dark theme that persists." \\
+  --done-when "toggling theme updates the UI and survives reload" \\
+  --done-when "\`npm test\` passes including new theme tests" \\
+  --validation "npm test"`,
+  },
+  list: {
+    purpose: "List quests (filter by status, parent, or readiness)",
+    usage: "quest list [--status <s>] [--parent <id>] [--ready] [--json]",
+    flags: [
+      ["--status <s>", "todo | in_progress | blocked | complete | cancelled"],
+      ["--parent <id>", "children of an epic"],
+      ["--ready", "todo quests whose depends_on are all complete (dispatch order)"],
+      ["--json", "machine-readable output"],
+    ],
+    example: "quest list --ready",
+  },
+  show: {
+    purpose: "Show a quest record in full",
+    usage: "quest show <id> [--json]",
+    flags: [["--json", "parsed record: frontmatter, body, checkpoints[]"]],
+    example: "quest show 3 --json",
+  },
+  start: {
+    purpose: "Mark a quest in_progress (todo → in_progress)",
+    usage: "quest start <id>",
+    flags: [],
+    example: "quest start 3",
+  },
+  checkpoint: {
+    purpose: "Record iteration evidence and drive the quest's status",
+    usage: "quest checkpoint <id> --status <s> --summary <what> --validation <evidence> [flags]",
+    flags: [
+      ["--status <s>", "in_progress | complete | blocked (required)"],
+      ["--summary <text>", "what changed, one line per milestone touched (required)"],
+      ["--validation <text>", "commands + observed results; complete requires backticked commands (required)"],
+      ["--iteration <n>", "iteration number (default: previous + 1)"],
+      ["--pr <url>", "pull request for this quest's work"],
+      ["--sha <sha>", "HEAD sha the evidence was gathered at"],
+      ["--failed <text>", "approaches that failed, with reasons"],
+      ["--expansion <text>", "rationale when scope compatibly expanded"],
+      ["--note <text>", "free-form trailing note"],
+    ],
+    example: `quest checkpoint 3 --status complete \\
+  --summary "M2 done — theme persistence via localStorage" \\
+  --validation "\`npm test\` → 42 passed, 0 failed"`,
+  },
+  cancel: {
+    purpose: "Cancel a quest (terminal; reason is recorded)",
+    usage: "quest cancel <id> --reason <why>",
+    flags: [["--reason <why>", "required — recorded in the record"]],
+    example: 'quest cancel 4 --reason "superseded by quest 7"',
+  },
+  edit: {
+    purpose: "Compatibly expand a quest (additions only; anchors are immutable)",
+    usage: "quest edit <id> [--add-done-when D]… [--add-milestone M]… [--add-context C] --rationale <why>",
+    flags: [
+      ["--add-done-when <d>", "append a Done-when item; repeatable"],
+      ["--add-milestone <m>", "append a milestone; repeatable"],
+      ["--add-context <text>", "append to Context"],
+      ["--rationale <why>", "required — why this is a compatible expansion"],
+    ],
+    example: 'quest edit 3 --add-done-when "works in Safari" --rationale "same objective, missed browser"',
+  },
+  lint: {
+    purpose: "Check records against the contract spec",
+    usage: "quest lint [<id> | --all]",
+    flags: [["--all", "lint every record in the store"]],
+    example: "quest lint --all",
+  },
+  amend: {
+    purpose: "Append a numbered protocol amendment (retro output)",
+    usage: "quest amend --text <amendment>",
+    flags: [["--text <t>", "the amendment, imperative, citing its evidence (required)"]],
+    example: 'quest amend --text "Always re-verify cited symbols at orient time — quest 12 lost an iteration to a stale reference."',
+  },
+  protocol: {
+    purpose: "Print the loop protocol + this store's local amendments",
+    usage: "quest protocol",
+    flags: [],
+    example: "quest protocol",
+  },
+  runs: {
+    purpose: "Show headless runner activity (from .quests/runs.ndjson)",
+    usage: "quest runs [--active] [--json]",
+    flags: [
+      ["--active", "only runs that started and have not ended"],
+      ["--json", "machine-readable output"],
+    ],
+    example: "quest runs --active",
+  },
+};
+
+export function renderCommandHelp(name) {
+  const c = COMMANDS[name];
+  const lines = [c.purpose, "", `Usage: ${c.usage}`];
+  if (c.flags.length) {
+    lines.push("", "Flags:");
+    const w = Math.max(...c.flags.map(([f]) => f.length));
+    for (const [flag, desc] of c.flags) lines.push(`  ${flag.padEnd(w)}  ${desc}`);
+  }
+  lines.push("", "Example:", ...c.example.split("\n").map((l) => `  ${l}`));
+  return lines.join("\n");
+}
+
+export function renderGeneralHelp() {
+  const lines = [INTRO, "", "Commands:"];
+  const w = Math.max(...Object.keys(COMMANDS).map((k) => k.length));
+  for (const [name, c] of Object.entries(COMMANDS)) lines.push(`  quest ${name.padEnd(w)}  ${c.purpose}`);
+  lines.push("", "Run `quest <command> --help` for flags and a copy-pasteable example.", "Headless workers: see `quest-run --help`.");
+  return lines.join("\n");
+}
+
+export function renderStatusOverview({ counts, ready, activeRuns, backend }) {
+  const lines = [`Quest store: ${backend} backend`];
+  const parts = ["todo", "in_progress", "blocked", "complete", "cancelled"]
+    .filter((s) => counts[s])
+    .map((s) => `${counts[s]} ${s}`);
+  lines.push(parts.length ? `Quests: ${parts.join(" · ")}` : "Quests: none yet");
+  if (ready.length) {
+    lines.push("", "Ready to work (dependencies met):");
+    for (const q of ready.slice(0, 3)) lines.push(`  ${q.id}. [${q.priority}] ${q.title}`);
+    lines.push("", "Next: `quest show <id>` to read one, or dispatch with `quest-run <id>`.");
+  } else if (!parts.length) {
+    lines.push("", "Next: create your first quest — see `quest create --help` (or use the /quest:plan skill).");
+  } else {
+    lines.push("", "Nothing ready to start. `quest list` to see everything.");
+  }
+  if (activeRuns > 0) lines.push("", `Active headless runs: ${activeRuns} — inspect with \`quest runs --active\`.`);
+  return lines.join("\n");
+}
+
+export function renderNoStore() {
+  return [
+    "No quest store found (searched for .quests/ from here upward).",
+    "",
+    "Get started:",
+    "  quest init            create a local store here",
+    "  quest init --backend github --repo owner/name",
+    "",
+    "Then: `quest create --help` shows how to author your first quest.",
+  ].join("\n");
+}
+
+export function renderInitNextSteps(backend) {
+  return [
+    "",
+    "Store created. Next steps:",
+    "  1. Author a quest:   quest create --help   (or /quest:plan in your agent session)",
+    "  2. Check it:         quest lint --all",
+    "  3. Work it:          /quest:work <id> in-session, or quest-run <id> headless",
+    ...(backend === "github" ? ["", "Records live as GitHub issues; config and amendments stay local in .quests/."] : []),
+  ].join("\n");
+}