qualia-framework 6.5.0 → 6.7.0

package/bin/state.js

@@ -12,6 +12,21 @@ const TRACKING_FILE = path.join(PLANNING, "tracking.json");
 const LOCK_FILE = path.join(PLANNING, ".state.lock");
 const JOURNAL_FILE = path.join(PLANNING, ".state.journal");
 
+// ─── A5: per-increment, concurrency-aware layout ────────
+// When `.planning/increments/` exists, the committed source of truth is one
+// file per increment (carrying status + claimed_by + branch). STATE.md and
+// tracking.json become LOCAL (gitignored) generated views, so two people on
+// two branches never conflict on the planning files: they touch different
+// increment files, and the only per-step-mutated files (STATE.md, tracking.json,
+// cursor) are never committed. Projects without `increments/` keep the legacy
+// single-file behavior verbatim — all new behavior is gated on hasIncrementLayout().
+const INCREMENTS_DIR = path.join(PLANNING, "increments");
+const RELEASES_DIR = path.join(PLANNING, "releases");
+const CURSOR_FILE = path.join(PLANNING, ".cursor.json");
+const BACKUP_DIR = path.join(PLANNING, ".backup");
+const GITIGNORE_FILE = path.join(PLANNING, ".gitignore");
+const MIGRATION_MANIFEST = path.join(PLANNING, "migration-manifest.json");
+
 // ─── Atomic write (tmp + rename) ─────────────────────────
 // Prevents half-written files when SIGINT, OOM, or AV scanners
 // interrupt mid-write. Same-filesystem rename is atomic on POSIX
@@ -212,6 +227,467 @@ function writeTracking(t) {
   atomicWrite(TRACKING_FILE, JSON.stringify(t, null, 2) + "\n");
 }
 
+// ─── A5: increment / release / cursor layer (additive) ───
+// All functions below are pure I/O + render helpers for the per-increment
+// layout. Nothing in the legacy path calls them; they activate only once a
+// project has been migrated (hasIncrementLayout() === true).
+
+// Identity for claim ownership. Mirrors state-ledger.js actor() (env-based,
+// not git config) so claimed_by matches the ledger's recorded actor.
+function actor() {
+  return (
+    process.env.QUALIA_ACTOR ||
+    process.env.CLAUDE_USER_NAME ||
+    process.env.USER ||
+    process.env.USERNAME ||
+    "unknown"
+  );
+}
+
+function hasIncrementLayout() {
+  try {
+    return fs.existsSync(INCREMENTS_DIR);
+  } catch {
+    return false;
+  }
+}
+
+// Defense-in-depth: an increment id is interpolated into a file path, so it
+// must never contain path separators or `..`. Reject anything that isn't a
+// plain inc-slug token before it reaches path.join().
+function isValidIncrementId(id) {
+  return typeof id === "string" && /^inc-[A-Za-z0-9_-]+$/.test(id);
+}
+
+function slugify(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40) || "increment";
+}
+
+function incrementId(num, name) {
+  return `inc-${String(num).padStart(4, "0")}-${slugify(name)}`;
+}
+
+// Roadmap statuses in legacy STATE.md use a few non-canonical tokens
+// ("ready", "—", "completed"). Normalize to the canonical state-machine
+// statuses so migrated increments transition with the existing VALID_FROM.
+function mapRoadmapStatus(raw) {
+  const v = String(raw || "").toLowerCase().trim().replace(/\s+/g, "_");
+  if (v === "ready" || v === "—" || v === "-" || v === "" || v === "todo") return "setup";
+  if (v === "completed" || v === "complete" || v === "done") return "verified";
+  const known = ["setup", "planned", "built", "verified", "polished", "shipped", "handed_off", "failed"];
+  return known.includes(v) ? v : "setup";
+}
+
+// CRLF-tolerant frontmatter parser for increment / release files. Returns
+// { fields, body } where fields is a flat key->string map of the `key: value`
+// lines between the leading `---` fences, and body is everything after.
+function parseFrontmatter(content) {
+  if (!content) return null;
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) return null;
+  const fields = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-zA-Z0-9_]+):\s*(.*?)\r?$/);
+    if (kv) fields[kv[1]] = kv[2].trim();
+  }
+  return { fields, body: m[2] || "" };
+}
+
+function parseIncrementMd(content) {
+  const fm = parseFrontmatter(content);
+  if (!fm || !fm.fields.id) return null;
+  const f = fm.fields;
+  const num = parseInt(f.num || f.phase) || 0;
+  return {
+    id: f.id,
+    release: f.release || "r1",
+    num,
+    phase: num, // phase == num: the original roadmap index, kept for back-compat
+    title: f.title || "",
+    goal: f.goal || "",
+    archetype: f.archetype || "",
+    status: f.status || "setup",
+    claimed_by: f.claimed_by || "",
+    branch: f.branch || "",
+    verification: f.verification || "pending",
+    gap_cycles: parseInt(f.gap_cycles) || 0,
+    tasks_done: parseInt(f.tasks_done) || 0,
+    tasks_total: parseInt(f.tasks_total) || 0,
+    wave: parseInt(f.wave) || 0,
+    build_count: parseInt(f.build_count) || 0,
+    deploy_count: parseInt(f.deploy_count) || 0,
+    deployed_url: f.deployed_url || "",
+    body: fm.body,
+  };
+}
+
+function renderIncrementMd(inc) {
+  const fm = [
+    `id: ${inc.id}`,
+    `release: ${inc.release || "r1"}`,
+    `num: ${inc.num}`,
+    `title: ${inc.title || ""}`,
+    `goal: ${inc.goal || ""}`,
+    `archetype: ${inc.archetype || ""}`,
+    `status: ${inc.status || "setup"}`,
+    `claimed_by: ${inc.claimed_by || ""}`,
+    `branch: ${inc.branch || ""}`,
+    `verification: ${inc.verification || "pending"}`,
+    `gap_cycles: ${inc.gap_cycles || 0}`,
+    `tasks_done: ${inc.tasks_done || 0}`,
+    `tasks_total: ${inc.tasks_total || 0}`,
+    `wave: ${inc.wave || 0}`,
+    `build_count: ${inc.build_count || 0}`,
+    `deploy_count: ${inc.deploy_count || 0}`,
+    `deployed_url: ${inc.deployed_url || ""}`,
+  ].join("\n");
+  // Preserve an existing body verbatim (round-trip safe); seed a default body
+  // with a DoD section the first time an increment is materialized.
+  const body = (inc.body && inc.body.trim())
+    ? inc.body.replace(/^\n+/, "")
+    : `# ${inc.title || inc.id}\n\nGoal: ${inc.goal || "TBD"}\n\n## Acceptance Criteria\n- TBD\n\n## Definition of Done\n- [ ] TBD\n`;
+  return `---\n${fm}\n---\n\n${body}`;
+}
+
+function incrementPath(id) {
+  return path.join(INCREMENTS_DIR, `${id}.md`);
+}
+
+function readIncrement(id) {
+  try {
+    return parseIncrementMd(fs.readFileSync(incrementPath(id), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeIncrement(inc) {
+  if (!fs.existsSync(INCREMENTS_DIR)) fs.mkdirSync(INCREMENTS_DIR, { recursive: true });
+  atomicWrite(incrementPath(inc.id), renderIncrementMd(inc));
+}
+
+function listIncrements() {
+  try {
+    return fs
+      .readdirSync(INCREMENTS_DIR)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => readIncrement(f.replace(/\.md$/, "")))
+      .filter(Boolean)
+      .sort((a, b) => a.num - b.num);
+  } catch {
+    return [];
+  }
+}
+
+// Definition-of-Done gate input: scan an increment body for open checklist
+// lines. A line `- [ ] ...` is OPEN unless it carries a `WAIVED:` marker.
+function incrementOpenDoD(inc) {
+  if (!inc || !inc.body) return [];
+  const open = [];
+  for (const line of inc.body.split(/\r?\n/)) {
+    const m = line.match(/^\s*[-*]\s*\[\s\]\s*(.+?)\s*$/);
+    if (m && !/WAIVED:/i.test(line)) open.push(m[1]);
+  }
+  return open;
+}
+function incrementWaivedDoD(inc) {
+  if (!inc || !inc.body) return [];
+  const waived = [];
+  for (const line of inc.body.split(/\r?\n/)) {
+    if (/^\s*[-*]\s*\[\s\]/.test(line) && /WAIVED:/i.test(line)) waived.push(line.trim());
+  }
+  return waived;
+}
+
+// ─── Release files ──────────────────────────────────────
+function parseReleaseMd(content) {
+  const fm = parseFrontmatter(content);
+  if (!fm || !fm.fields.id) return null;
+  const incs = [];
+  for (const line of fm.body.split(/\r?\n/)) {
+    const m = line.match(/^\s*[-*]\s*(inc-[a-z0-9-]+)\s*$/i);
+    if (m) incs.push(m[1]);
+  }
+  return {
+    id: fm.fields.id,
+    title: fm.fields.title || "",
+    type: fm.fields.type || "rolling",
+    status: fm.fields.status || "active",
+    increments: incs,
+  };
+}
+function renderReleaseMd(rel) {
+  const list = (rel.increments || []).map((i) => `- ${i}`).join("\n");
+  return `---\nid: ${rel.id}\ntitle: ${rel.title || ""}\ntype: ${rel.type || "rolling"}\nstatus: ${rel.status || "active"}\n---\n\n## Increments\n${list}\n`;
+}
+function releasePath(rid) {
+  return path.join(RELEASES_DIR, `${rid}.md`);
+}
+function readRelease(rid) {
+  try {
+    return parseReleaseMd(fs.readFileSync(releasePath(rid), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeRelease(rel) {
+  if (!fs.existsSync(RELEASES_DIR)) fs.mkdirSync(RELEASES_DIR, { recursive: true });
+  atomicWrite(releasePath(rel.id), renderReleaseMd(rel));
+}
+function listReleases() {
+  try {
+    return fs
+      .readdirSync(RELEASES_DIR)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => readRelease(f.replace(/\.md$/, "")))
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// ─── Local cursor (never committed) ─────────────────────
+function readCursor() {
+  try {
+    return JSON.parse(fs.readFileSync(CURSOR_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeCursor(c) {
+  atomicWrite(CURSOR_FILE, JSON.stringify(c, null, 2) + "\n");
+}
+
+const A5_DONE_STATUSES = new Set(["verified", "polished", "shipped", "handed_off"]);
+
+// The "active" increment for dashboard/tracking mirroring: explicit cursor,
+// else the first not-yet-done increment, else the last.
+function activeIncrement(increments, cursor) {
+  if (!increments.length) return null;
+  const cur = cursor && cursor.current_increment;
+  if (cur) {
+    const hit = increments.find((i) => i.id === cur);
+    if (hit) return hit;
+  }
+  return increments.find((i) => !A5_DONE_STATUSES.has(i.status)) || increments[increments.length - 1];
+}
+
+// Build the writeStateMd() input object from increments — STATE.md becomes a
+// pure projection of the committed increment files.
+function dashboardStateFromIncrements(increments, active, t) {
+  return {
+    phase: active ? active.num : 1,
+    total_phases: increments.length || 1,
+    phase_name: active ? active.title : "",
+    status: active ? active.status : "setup",
+    assigned_to: active ? active.claimed_by : "",
+    profile: (t && t.profile) || "strict",
+    verification: active ? active.verification : "pending",
+    last_activity: (t && t.last_activity) || "State regenerated from increments",
+    phases: increments.map((i) => ({ num: i.num, name: i.title, goal: i.goal, status: i.status })),
+    blockers: t && Array.isArray(t.blockers) && t.blockers.length ? t.blockers.join("; ") : "None.",
+    resume: (t && t.resume) || "—",
+  };
+}
+
+// Regenerate the two LOCAL views (tracking.json + STATE.md) from the committed
+// increment files. tracking.json stays FAT (mirrors the active increment +
+// keeps identity/lifetime) so all back-compat consumers keep working; it gains
+// a per-increment index + releases index + mode for the ERP. Idempotent.
+function regenerateViews(activity) {
+  const increments = listIncrements();
+  const cursor = readCursor();
+  const active = activeIncrement(increments, cursor);
+  const t = ensureLifetime(readTracking() || {});
+  if (activity) t.last_activity = activity;
+
+  // Mirror the active increment's per-phase fields into tracking for consumers.
+  if (active) {
+    t.phase = active.num;
+    t.phase_name = active.title;
+    t.status = active.status;
+    t.verification = active.verification;
+    t.tasks_done = active.tasks_done;
+    t.tasks_total = active.tasks_total;
+    t.wave = active.wave;
+    t.build_count = active.build_count;
+    t.deploy_count = active.deploy_count;
+    t.deployed_url = active.deployed_url || t.deployed_url || "";
+    t.gap_cycles = t.gap_cycles || {};
+    t.gap_cycles[String(active.num)] = active.gap_cycles;
+  }
+  t.total_phases = increments.length;
+  t.mode = t.mode || (listReleases()[0] ? listReleases()[0].type : "rolling");
+  // Lightweight indexes for the ERP / dashboards (derived, not authoritative).
+  t.increments = increments.map((i) => ({
+    id: i.id, num: i.num, title: i.title, status: i.status,
+    claimed_by: i.claimed_by, branch: i.branch, verification: i.verification,
+  }));
+  t.releases = listReleases().map((r) => ({ id: r.id, type: r.type, status: r.status, increments: r.increments }));
+  t.next_command = active
+    ? nextCommand(active.status, active.num, increments.length, active.verification)
+    : "/qualia";
+  t.last_updated = new Date().toISOString();
+  writeTracking(t);
+
+  // STATE.md dashboard (gitignored projection).
+  writeStateMd(dashboardStateFromIncrements(increments, active, t));
+  return { increments, active, tracking: t };
+}
+
+// ─── A5: increment-aware check (read-only, concurrency router) ───
+// Returns the response shape legacy consumers expect PLUS the concurrency
+// fields: my_claim, next_increment, claimed_increments[]. It never writes, so
+// it's safe inside the /qualia parallel Bash batch and never conflicts.
+function cmdCheckIncrement(opts) {
+  const me = actor();
+  const increments = listIncrements();
+  const t = ensureLifetime(readTracking() || {});
+  if (!increments.length) {
+    return output({ ok: false, error: "NO_INCREMENTS", message: "increments/ exists but is empty. Run `state.js migrate` or `state.js fix`." });
+  }
+  const isDone = (i) => A5_DONE_STATUSES.has(i.status);
+  const claimed_increments = increments
+    .filter((i) => i.claimed_by && i.claimed_by !== me && !isDone(i))
+    .map((i) => ({ id: i.id, num: i.num, title: i.title, status: i.status, claimed_by: i.claimed_by, branch: i.branch }));
+  const mine = increments.find((i) => i.claimed_by === me && !isDone(i));
+  const next_unclaimed = increments.find((i) => !isDone(i) && (!i.claimed_by || i.claimed_by === me));
+  const focus = mine || next_unclaimed || activeIncrement(increments, readCursor());
+  const totalPhases = increments.length;
+  const allDone = increments.every(isDone);
+  const next_command = mine
+    ? nextCommand(mine.status, mine.num, totalPhases, mine.verification)
+    : next_unclaimed
+      ? nextCommand(next_unclaimed.status, next_unclaimed.num, totalPhases, next_unclaimed.verification)
+      : (allDone ? "/qualia-polish" : "/qualia");
+
+  output({
+    ok: true,
+    layout: "increments",
+    phase: focus ? focus.num : 1,
+    phase_name: focus ? focus.title : "",
+    total_phases: totalPhases,
+    status: focus ? focus.status : "setup",
+    assigned_to: focus ? focus.claimed_by : "",
+    profile: resolveProfile(null, t),
+    milestone: t.milestone || 1,
+    milestone_name: t.milestone_name || "",
+    milestones: t.milestones || [],
+    lifetime: t.lifetime,
+    verification: focus ? focus.verification : "pending",
+    gap_cycles: focus ? focus.gap_cycles : 0,
+    gap_cycle_limit: getGapCycleLimit(),
+    tasks_done: focus ? focus.tasks_done : 0,
+    tasks_total: focus ? focus.tasks_total : 0,
+    deployed_url: focus ? focus.deployed_url : "",
+    actor: me,
+    my_claim: mine ? mine.id : "",
+    next_increment: next_unclaimed ? next_unclaimed.id : "",
+    claimed_increments,
+    increments: increments.map((i) => ({ id: i.id, num: i.num, title: i.title, status: i.status, claimed_by: i.claimed_by, branch: i.branch, verification: i.verification })),
+    next_command,
+  });
+}
+
+// ─── A5: increment-aware transition ─────────────────────
+// Operates on ONE increment file (by --id or cursor). The committed mutation
+// is a single increment file; tracking.json + STATE.md are regenerated locally.
+function cmdTransitionIncrement(opts, target) {
+  const increments = listIncrements();
+
+  // note/activity short-circuit — log to (local) tracking + regenerate.
+  if (target === "note" || target === "activity") {
+    const t = ensureLifetime(readTracking() || {});
+    if (opts.notes) t.notes = opts.notes;
+    if (opts.tasks_done) {
+      const c = parseInt(opts.tasks_done) || 0;
+      if (c > 0) t.lifetime.tasks_completed += c;
+    }
+    writeTracking(t);
+    regenerateViews(opts.notes || "Activity logged");
+    return output({ ok: true, action: target, layout: "increments" });
+  }
+
+  // Resolve the target increment: explicit --id, else --phase N (back-compat
+  // with phase-addressed skills: maps to the increment whose num === N), else
+  // the cursor, else the active increment.
+  if (opts.id && !isValidIncrementId(opts.id)) return output(fail("INVALID_ID", `Invalid increment id '${opts.id}' (must match inc-<slug>).`));
+  const byPhase = opts.phase ? (increments.find((i) => i.num === parseInt(opts.phase)) || {}).id : "";
+  const id = opts.id || byPhase || readCursor().current_increment || "";
+  const inc = id ? readIncrement(id) : activeIncrement(increments, readCursor());
+  if (!inc) return output(fail("UNKNOWN_INCREMENT", id ? `No increment '${id}' under ${INCREMENTS_DIR}` : "No active increment — set the cursor or pass --id."));
+
+  const phase = inc.num;
+  const prevStatus = inc.status;
+  const check = checkPreconditions({ phase, status: inc.status, total_phases: increments.length }, target, { ...opts, phase });
+  if (!check.ok) {
+    const forceable = ["PRECONDITION_FAILED", "GAP_CYCLE_LIMIT", "INVALID_PLAN"];
+    if (opts.force && forceable.includes(check.error)) {
+      console.error(`WARNING: Forcing transition despite: ${check.message}`);
+    } else {
+      return output(check);
+    }
+  }
+
+  const t = ensureLifetime(readTracking() || {});
+  inc.status = target;
+  if (target === "planned") {
+    if (prevStatus === "verified") inc.gap_cycles = (inc.gap_cycles || 0) + 1;
+  } else if (target === "built") {
+    inc.tasks_done = parseInt(opts.tasks_done) || 0;
+    inc.tasks_total = parseInt(opts.tasks_total) || 0;
+    inc.wave = parseInt(opts.wave) || 0;
+    inc.build_count = (inc.build_count || 0) + 1;
+  } else if (target === "verified") {
+    inc.verification = opts.verification;
+    if (opts.verification !== "pass") {
+      inc.status = "failed";
+    } else {
+      t.lifetime.tasks_completed += inc.tasks_done || 0;
+      t.lifetime.phases_completed += 1;
+      inc.gap_cycles = 0;
+      // Auto-advance the cursor to the next increment on a pass.
+      const idx = increments.findIndex((i) => i.id === inc.id);
+      const nextInc = increments[idx + 1];
+      if (nextInc) writeCursor({ current_increment: nextInc.id });
+    }
+  } else if (target === "shipped") {
+    inc.deployed_url = opts.deployed_url || "";
+    inc.deploy_count = (inc.deploy_count || 0) + 1;
+  }
+
+  writeIncrement(inc);
+  writeTracking(t); // persist lifetime bump before regenerate re-reads tracking
+  regenerateViews(`${target} (${inc.id})`);
+
+  const ledger = recordLedgerEvent({ action: target, phase_before: phase, phase_after: inc.num, status_before: prevStatus, status_after: inc.status });
+  _trace("state-transition", "allow", { layout: "increments", id: inc.id, status: inc.status, previous_status: prevStatus, verification: inc.verification });
+
+  const result = {
+    ok: true,
+    layout: "increments",
+    id: inc.id,
+    phase: inc.num,
+    phase_name: inc.title,
+    status: inc.status,
+    previous_status: prevStatus,
+    verification: inc.verification,
+    gap_cycles: inc.gap_cycles || 0,
+    next_command: nextCommand(inc.status, inc.num, increments.length, inc.verification),
+  };
+  if (ledger.ok) {
+    result.ledger_event_id = ledger.event_id;
+    result.ledger_event_hash = ledger.event_hash;
+  } else if (ledger.error) {
+    result.ledger_error = ledger.error;
+  }
+  output(result);
+}
+
 // Ensure lifetime + milestone fields exist (backward compat for old tracking files)
 function ensureLifetime(t) {
   if (!t) return t;
@@ -602,6 +1078,8 @@ function resolveProfile(s, t) {
 }
 
 function cmdCheck(opts) {
+  // A5: migrated projects route through the concurrency-aware, read-only check.
+  if (hasIncrementLayout()) return cmdCheckIncrement(opts);
   const t = readTracking();
   const s = parseStateMd(readState());
   // True NO_PROJECT only when BOTH the durable tracking AND the dashboard are
@@ -844,6 +1322,9 @@ function cmdTransition(opts) {
   const target = opts.to;
   if (!target) return output(fail("MISSING_ARG", "--to is required"));
 
+  // A5: migrated projects transition per-increment (one committed file).
+  if (hasIncrementLayout()) return cmdTransitionIncrement(opts, target);
+
   const beforeStateRaw = readState();
   const beforeTrackingRaw = readTrackingRaw();
   const t = parseTrackingRaw(beforeTrackingRaw);
@@ -1253,6 +1734,242 @@ function cmdFix(opts) {
   output(result);
 }
 
+// ─── A5: .planning/.gitignore ───────────────────────────
+// The structural fix: the only files mutated every step (STATE.md, tracking.json,
+// cursor) are LOCAL; only increment/release files are committed. This gitignore
+// enforces that. Kept in sync with templates/planning.gitignore.
+const PLANNING_GITIGNORE = [
+  "# A5: per-step-mutated planning state is LOCAL (generated views), never committed.",
+  "# Only increments/ and releases/ are the durable, committed source of truth —",
+  "# so two people on two branches never conflict on the planning files.",
+  "STATE.md",
+  "tracking.json",
+  ".cursor.json",
+  ".state.lock",
+  ".state.journal",
+  ".backup/",
+  "migration-manifest.json",
+  "",
+].join("\n");
+
+function writePlanningGitignore() {
+  atomicWrite(GITIGNORE_FILE, PLANNING_GITIGNORE);
+}
+
+// ─── A5: non-destructive migration ──────────────────────
+// Converts a legacy single-file project (STATE.md + tracking.json) to the
+// per-increment layout. Backs up both files first, writes a reversible
+// manifest, is idempotent (re-run is a no-op once increments/ exists), and
+// supports `migrate --revert` to restore byte-identical originals.
+function cmdMigrate(opts) {
+  if (opts.revert) return cmdMigrateRevert(opts);
+
+  // Idempotent guard: already migrated → no-op.
+  if (hasIncrementLayout()) {
+    return output({ ok: true, action: "migrate", already_migrated: true, message: "increments/ already exists — nothing to do." });
+  }
+
+  const stateRaw = readState();
+  const trackingRaw = readTrackingRaw();
+  if (!stateRaw && !trackingRaw) {
+    return output(fail("NO_PROJECT", "No .planning/ found. Nothing to migrate."));
+  }
+
+  const s = parseStateMd(stateRaw);
+  const t = ensureLifetime(readTracking() || {});
+  if (!s || !s.phases || !s.phases.length) {
+    return output(fail("MIGRATE_NO_ROADMAP", "Could not parse a roadmap from STATE.md. Run `state.js fix` first, then migrate."));
+  }
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const created = [];
+  let ids = [];
+
+  try {
+    // 1. Backup originals.
+    if (!fs.existsSync(BACKUP_DIR)) { fs.mkdirSync(BACKUP_DIR, { recursive: true }); created.push(BACKUP_DIR); }
+    const backupState = stateRaw != null ? path.join(BACKUP_DIR, `STATE.md.${stamp}`) : null;
+    const backupTracking = trackingRaw != null ? path.join(BACKUP_DIR, `tracking.json.${stamp}`) : null;
+    if (backupState) atomicWrite(backupState, stateRaw);
+    if (backupTracking) atomicWrite(backupTracking, trackingRaw);
+
+    // 2. One increment file per roadmap phase. The CURRENT phase carries the
+    //    live status/verification from tracking; others use the roadmap row.
+    const curPhase = Number(t.phase || s.phase) || s.phase;
+    for (const p of s.phases) {
+      const id = incrementId(p.num, p.name);
+      const isCurrent = p.num === curPhase;
+      const status = isCurrent
+        ? mapRoadmapStatus(t.status || s.status || p.status)
+        : mapRoadmapStatus(p.status);
+      const inc = {
+        id,
+        release: "r1",
+        num: p.num,
+        title: p.name,
+        goal: p.goal || "",
+        archetype: t.type || "",
+        status,
+        claimed_by: "",
+        branch: "",
+        verification: isCurrent ? (t.verification || "pending") : "pending",
+        gap_cycles: (t.gap_cycles || {})[String(p.num)] || 0,
+        tasks_done: isCurrent ? (t.tasks_done || 0) : 0,
+        tasks_total: isCurrent ? (t.tasks_total || 0) : 0,
+        wave: isCurrent ? (t.wave || 0) : 0,
+        build_count: isCurrent ? (t.build_count || 0) : 0,
+        deploy_count: isCurrent ? (t.deploy_count || 0) : 0,
+        deployed_url: isCurrent ? (t.deployed_url || "") : "",
+        // Legacy increments carry a satisfied DoD line so the ship gate never
+        // retroactively traps a phase that predates A5's DoD tracking.
+        body: `# ${p.name}\n\nGoal: ${p.goal || "TBD"}\n\n## Acceptance Criteria\n- (migrated from legacy roadmap)\n\n## Definition of Done\n- [x] Legacy increment migrated from STATE.md roadmap (pre-A5 — DoD not retroactively tracked)\n`,
+      };
+      writeIncrement(inc);
+      ids.push(id);
+      created.push(incrementPath(id));
+    }
+
+    // 3. Wrap all increments in a single rolling release.
+    const rel = { id: "r1", title: t.milestone_name || "Release 1", type: t.mode || "rolling", status: "active", increments: ids };
+    writeRelease(rel);
+    created.push(releasePath("r1"));
+
+    // 4. Cursor points at the current phase's increment.
+    const curId = ids[curPhase - 1] || ids[0];
+    writeCursor({ current_increment: curId });
+    created.push(CURSOR_FILE);
+
+    // 5. gitignore the now-local views.
+    writePlanningGitignore();
+    created.push(GITIGNORE_FILE);
+
+    // 6. Manifest (reversible).
+    const manifest = {
+      migrated_at: new Date().toISOString(),
+      schema: "a5-increments-v1",
+      backup: { state: backupState, tracking: backupTracking },
+      created,
+      increment_ids: ids,
+      cursor: curId,
+    };
+    atomicWrite(MIGRATION_MANIFEST, JSON.stringify(manifest, null, 2) + "\n");
+
+    // 7. Regenerate the local views (tracking index + STATE.md) from increments.
+    regenerateViews();
+  } catch (e) {
+    return output(fail("MIGRATE_WRITE_ERROR", e.message));
+  }
+
+  recordLedgerEvent({ action: "migrate", phase_before: s.phase, phase_after: s.phase, status_before: s.status, status_after: s.status });
+
+  output({
+    ok: true,
+    action: "migrate",
+    increments: created.filter((c) => c.includes("increments")).length,
+    increment_ids: ids,
+    cursor: ids[(Number(t.phase || s.phase) || s.phase) - 1] || ids[0],
+    note: "STATE.md + tracking.json are now gitignored generated views. If they were previously committed, run `git rm --cached .planning/STATE.md .planning/tracking.json` to stop tracking them. Revert anytime with `state.js migrate --revert`.",
+    next_command: nextCommand(s.status, s.phase, s.total_phases, t.verification),
+  });
+}
+
+function cmdMigrateRevert(opts) {
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(MIGRATION_MANIFEST, "utf8"));
+  } catch {
+    return output(fail("NO_MANIFEST", "No migration-manifest.json found — nothing to revert."));
+  }
+  try {
+    // Restore originals byte-identically.
+    if (manifest.backup && manifest.backup.state && fs.existsSync(manifest.backup.state)) {
+      atomicWrite(STATE_FILE, fs.readFileSync(manifest.backup.state, "utf8"));
+    }
+    if (manifest.backup && manifest.backup.tracking && fs.existsSync(manifest.backup.tracking)) {
+      atomicWrite(TRACKING_FILE, fs.readFileSync(manifest.backup.tracking, "utf8"));
+    }
+    // Remove generated layout.
+    for (const dir of [INCREMENTS_DIR, RELEASES_DIR]) {
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+    }
+    for (const f of [CURSOR_FILE, GITIGNORE_FILE, MIGRATION_MANIFEST]) {
+      try { fs.unlinkSync(f); } catch {}
+    }
+  } catch (e) {
+    return output(fail("REVERT_ERROR", e.message));
+  }
+  output({ ok: true, action: "migrate-revert", restored: true, message: "Restored STATE.md + tracking.json from backup; removed increments/, releases/, cursor, gitignore, manifest." });
+}
+
+// ─── A5: claim an increment for exclusive work ──────────
+// Writes claimed_by (this actor) + branch onto ONE increment file — committed
+// on the feature branch. A second actor claiming a held increment is refused.
+function cmdClaim(opts) {
+  if (!hasIncrementLayout()) {
+    return output(fail("NOT_MIGRATED", "No increments/ — run `state.js migrate` first."));
+  }
+  const id = opts.id || (readCursor().current_increment || "");
+  if (!id) return output(fail("MISSING_ARG", "--id is required (or set the cursor)"));
+  if (!isValidIncrementId(id)) return output(fail("INVALID_ID", `Invalid increment id '${id}' (must match inc-<slug>).`));
+  const inc = readIncrement(id);
+  if (!inc) return output(fail("UNKNOWN_INCREMENT", `No increment '${id}' under ${INCREMENTS_DIR}`));
+
+  const me = actor();
+  if (inc.claimed_by && inc.claimed_by !== me && !opts.force) {
+    return output(fail("ALREADY_CLAIMED", `Increment '${id}' is held by '${inc.claimed_by}' (branch '${inc.branch}'). Use --force to steal.`));
+  }
+
+  inc.claimed_by = me;
+  inc.branch = opts.branch || inc.branch || "";
+  writeIncrement(inc);
+  writeCursor({ current_increment: id });
+  regenerateViews(`Claimed ${id} (${me})`);
+  recordLedgerEvent({ action: "claim", phase_before: inc.num, phase_after: inc.num, status_before: inc.status, status_after: inc.status });
+  output({ ok: true, action: "claim", id, claimed_by: me, branch: inc.branch, status: inc.status, next_command: nextCommand(inc.status, inc.num, listIncrements().length, inc.verification) });
+}
+
+// ─── A5: release (ship) an increment + clear its claim ──
+// Sets the increment to shipped, records the deployed URL, runs the
+// Definition-of-Done gate (profile-aware), and clears claimed_by so the file
+// merges to main untouched by other actors.
+function cmdRelease(opts) {
+  if (!hasIncrementLayout()) {
+    return output(fail("NOT_MIGRATED", "No increments/ — run `state.js migrate` first."));
+  }
+  const id = opts.id || (readCursor().current_increment || "");
+  if (!id) return output(fail("MISSING_ARG", "--id is required (or set the cursor)"));
+  if (!isValidIncrementId(id)) return output(fail("INVALID_ID", `Invalid increment id '${id}' (must match inc-<slug>).`));
+  const inc = readIncrement(id);
+  if (!inc) return output(fail("UNKNOWN_INCREMENT", `No increment '${id}' under ${INCREMENTS_DIR}`));
+  if (!opts.deployed_url) return output(fail("MISSING_ARG", "--deployed-url is required for release"));
+
+  // Definition-of-Done gate (profile-aware). strict: ANY open `- [ ]` line
+  // blocks (no waivers). standard: open lines allowed only if each is WAIVED.
+  // --force (OWNER override) bypasses either.
+  const profile = resolveProfile(null, readTracking());
+  const open = incrementOpenDoD(inc); // open AND unwaived
+  const anyOpenLine = /(^|\n)\s*[-*]\s*\[\s\]/.test(inc.body || "");
+  if (!opts.force) {
+    if (profile === "strict" && anyOpenLine) {
+      return output(fail("DOD_INCOMPLETE", `Definition of Done has unchecked items (strict profile, no waivers). Check or remove them before release, or use --force.`));
+    }
+    if (profile === "standard" && open.length) {
+      return output(fail("DOD_INCOMPLETE", `Definition of Done has ${open.length} unchecked item(s) without a WAIVED: reason (standard profile). Waive with a reason or check them, or use --force.`));
+    }
+  }
+
+  inc.status = "shipped";
+  inc.deployed_url = opts.deployed_url;
+  inc.deploy_count = (inc.deploy_count || 0) + 1;
+  const wasClaimedBy = inc.claimed_by;
+  inc.claimed_by = ""; // release the claim
+  writeIncrement(inc);
+  regenerateViews(`Released ${id} → shipped`);
+  recordLedgerEvent({ action: "release", phase_before: inc.num, phase_after: inc.num, status_before: wasClaimedBy ? "claimed" : inc.status, status_after: "shipped" });
+  _trace("state-release", "allow", { id, deployed_url: inc.deployed_url });
+  output({ ok: true, action: "release", id, status: "shipped", deployed_url: inc.deployed_url, claim_cleared_from: wasClaimedBy || "", next_command: "/qualia-report" });
+}
+
 function cmdValidatePlan(opts) {
   const phase = parseInt(opts.phase) || 1;
   const planFile = path.join(PLANNING, `phase-${phase}-plan.md`);
@@ -2014,11 +2731,20 @@ try {
     case "next-report-id":
       cmdNextReportId(opts);
       break;
+    case "migrate":
+      cmdMigrate(opts);
+      break;
+    case "claim":
+      cmdClaim(opts);
+      break;
+    case "release":
+      cmdRelease(opts);
+      break;
     default:
       output(
         fail(
           "UNKNOWN_COMMAND",
-          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|backfill-milestones|next-report-id> [--options]`
+          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|backfill-milestones|next-report-id|migrate|claim|release> [--options]`
         )
       );
   }