@ksoftm/create-arc 1.1.0 → 1.3.0

package/README.md

@@ -32,11 +32,21 @@ Requires Node ≥ 18.
 | Command | What it does |
 |---|---|
 | `init [dir]` | Scaffold `ARC.md` + `.arc/` (index, template, standing maintenance arc, `notes/`, `archive/`). Idempotent — never overwrites. |
-| `new "Title" [--dir=.] [--tags=a,b]` | Take the next sequential ID, create the arc from the template, and register its row in the index. |
+| `new "Title" [--goal …] [--task …] [--tags a,b]` | Take the next ID, create the arc, register its row. `--goal`/`--task` prefill the plan and tasks. |
+| `start <arc>` | Set an arc to in-progress and log it. `<arc>` is an id or slug. |
+| `task <arc> <n> [done\|start\|block\|cancel\|pending]` | Toggle a task marker; `--add "text"` appends a new task. |
+| `block <arc> [--reason …]` | Set an arc to blocked, recording the reason in the worklog. |
+| `refine <arc> "…"` | Fold a new instruction into an arc: append to §1, bump plan_version, log §3, set refining. |
+| `note <arc> "…"` | Quick-append to §1 Raw Instructions (or §5 Worklog with `--worklog`). |
+| `log <arc> [--json]` | Show the arc's worklog timeline. |
+| `done <arc>` | Mark done, log it, move the file to `archive/`, move its index row. |
+| `archive <arc> [--cancelled]` | Archive an arc (outcome done, or cancelled). |
+| `show <arc> [--json]` | Print one arc's plan, tasks, and status notes. |
+| `next [--json]` | Suggest what to work on next. |
 | `status [dir] [--json]` | Print a table (or JSON) of every arc: ID, status, plan version, task progress, and which to resume. |
-| `doctor [dir]` | Consistency checks — index ↔ file bijection, ID/`next_id` sanity, valid statuses. Exits non-zero on problems (CI-friendly). |
+| `doctor [dir] [--fix]` | Consistency checks — index ↔ file bijection, ID/`next_id` sanity, valid statuses. Exits non-zero on problems (CI-friendly). `--fix` auto-repairs drift. |
 
-Common options: `--owner NAME` (defaults to `git config user.name`); `--tags a,b` on `new`; `--json` on `status`; `--agents a,b` and `--force` on `agent-init`; `--version`, `--help`.
+Common options: `--owner NAME` (defaults to `git config user.name`); `--goal`/`--task` on `new`; `--reason` on `block`/`archive`; `--cancelled` on `archive`; `--fix` on `doctor`; `--json` on `status`; `--agents a,b` and `--force` on `agent-init`; `--version`, `--help`. Per-command help: `arc help <command>`.
 
 Installs two equivalent binaries: **`arc`** and **`create-arc`**.
 

package/bin/cli.js

@@ -12,7 +12,7 @@
 
 import { execFileSync } from "node:child_process";
 import {
-  existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync,
+  existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync,
 } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -55,19 +55,24 @@ function detectOwner(dir) {
   return "user";
 }
 
-const BOOLEAN_FLAGS = new Set(["json", "help", "version"]);
+const BOOLEAN_FLAGS = new Set(["json", "help", "version", "fix", "force", "cancelled", "cancel", "worklog"]);
+const REPEATABLE_FLAGS = new Set(["task"]);
 
 function parseArgv(argv) {
   const flags = {}; const pos = [];
+  const set = (key, val) => {
+    if (REPEATABLE_FLAGS.has(key)) (flags[key] ??= []).push(val);
+    else flags[key] = val;
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a.startsWith("--")) {
       const eq = a.indexOf("=");
-      if (eq > -1) { flags[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+      if (eq > -1) { set(a.slice(2, eq), a.slice(eq + 1)); continue; }
       const key = a.slice(2);
       const next = argv[i + 1];
       if (!BOOLEAN_FLAGS.has(key) && next !== undefined && !next.startsWith("--")) {
-        flags[key] = next; i++;            // --owner NAME form
+        set(key, next); i++;               // --owner NAME form
       } else flags[key] = true;            // --json / trailing flag form
     } else pos.push(a);
   }
@@ -92,6 +97,175 @@ function listArcFiles(arcDir) {
   return { active: ls(arcDir), archived: ls(join(arcDir, "archive")) };
 }
 
+/* ---------------------- shared arc-mutation helpers ---------------------- */
+
+// Resolve a project dir's .arc, failing clearly if uninitialized.
+function arcDirOf(flags, target) {
+  const dir = resolve(flags?.dir ?? target ?? ".");
+  const arcDir = join(dir, ".arc");
+  return { dir, arcDir, exists: existsSync(arcDir) };
+}
+
+// Find an arc file by id ("ARC-0007" / "7" / "0007") or by a slug substring.
+// Searches active first, then archive. Returns { path, archived } or null.
+function findArc(arcDir, ref) {
+  const { active, archived } = listArcFiles(arcDir);
+  const all = [...active.map((p) => ({ p, archived: false })),
+               ...archived.map((p) => ({ p, archived: true }))];
+  if (!ref) return null;
+  const raw = String(ref).trim();
+  const num = raw.replace(/^ARC-/i, "").replace(/[^0-9]/g, "");
+  const id = num ? `ARC-${num.padStart(4, "0")}` : null;
+  // exact id match on filename
+  if (id) {
+    const hit = all.find(({ p }) => basename(p).toUpperCase().startsWith(id));
+    if (hit) return { path: hit.p, archived: hit.archived };
+  }
+  // slug substring match (case-insensitive), unique-or-first
+  const matches = all.filter(({ p }) => basename(p).toLowerCase().includes(raw.toLowerCase()));
+  if (matches.length) return { path: matches[0].p, archived: matches[0].archived };
+  return null;
+}
+
+// Set a frontmatter field, bump `updated` to today, and (optionally) sync the
+// INDEX.md row for this arc. Returns the new frontmatter values of interest.
+function updateArcFrontmatter(arcPath, changes) {
+  let text = readText(arcPath);
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return fail(`${basename(arcPath)}: no YAML frontmatter`);
+  let front = fm[1];
+  for (const [k, v] of Object.entries(changes)) front = setField(front, k, v);
+  if (!("updated" in changes)) front = setField(front, "updated", today());
+  text = text.slice(0, fm.index) + `---\n${front}\n---` + text.slice(fm.index + fm[0].length);
+  writeFileSync(arcPath, text);
+  return front;
+}
+
+// Sync the INDEX.md row (status, plan v, updated) for a given arc id.
+function syncIndexRow(arcDir, id, { status, planVersion } = {}) {
+  const indexPath = join(arcDir, "INDEX.md");
+  if (!existsSync(indexPath)) return;
+  const lines = readText(indexPath).split("\n");
+  let changed = false;
+  for (let i = 0; i < lines.length; i++) {
+    const cells = lines[i].split("|");
+    if (cells.length >= 8 && cells[1].trim().toUpperCase() === id) {
+      if (status !== undefined) cells[3] = ` ${status} `;
+      if (planVersion !== undefined) cells[4] = ` ${planVersion} `;
+      cells[5] = ` ${today()} `;
+      lines[i] = cells.join("|");
+      changed = true;
+      break;
+    }
+  }
+  if (changed) writeFileSync(indexPath, lines.join("\n"));
+}
+
+// Move an arc row from the Active table to the Archived table in INDEX.md.
+function moveIndexRowToArchived(arcDir, id, outcome) {
+  const indexPath = join(arcDir, "INDEX.md");
+  if (!existsSync(indexPath)) return;
+  const lines = readText(indexPath).split("\n");
+  const archivedHeadIdx = lines.findIndex((l) => /^##\s+Archived/i.test(l));
+  let rowIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (archivedHeadIdx !== -1 && i >= archivedHeadIdx) break;
+    const cells = lines[i].split("|");
+    if (cells.length >= 8 && cells[1].trim().toUpperCase() === id) { rowIdx = i; break; }
+  }
+  if (rowIdx === -1) return;
+  const cells = lines[rowIdx].split("|");
+  const title = cells[2].trim();
+  const file = cells[7].trim();   // [name](path)
+  const archivedRow = `| ${id} | ${title} | ${outcome} | ${today()} | ${file} |`;
+  lines.splice(rowIdx, 1);                     // remove from Active
+  // re-find Archived head (index shifted), then drop a placeholder "— | —" row if present
+  let head = lines.findIndex((l) => /^##\s+Archived/i.test(l));
+  if (head === -1) { lines.push("", "## Archived", "", "| ID | Title | Outcome | Closed | File |", "|---|---|---|---|---|"); head = lines.length - 2; }
+  // insert after the Archived table separator (first |---| after head)
+  let sep = -1;
+  for (let i = head + 1; i < lines.length; i++) {
+    if (/^\|?\s*:?-{2,}/.test(lines[i])) { sep = i; break; }
+  }
+  const insertAt = sep !== -1 ? sep : head;
+  // remove an empty placeholder archived row ("| — | — | …")
+  if (lines[insertAt + 1] && /^\|\s*—\s*\|/.test(lines[insertAt + 1])) lines.splice(insertAt + 1, 1);
+  lines.splice(insertAt + 1, 0, archivedRow);
+  writeFileSync(indexPath, lines.join("\n"));
+}
+
+// Append a worklog entry under "## 5 · Worklog".
+function appendWorklog(arcPath, note) {
+  let text = readText(arcPath);
+  const stamp = new Date().toISOString().slice(0, 16).replace("T", " ");
+  const entry = `\n### ${stamp} — ${note}\n`;
+  const m = text.match(/^## 5 · Worklog\n/m);
+  if (!m) { writeFileSync(arcPath, text + entry); return; }
+  // insert right after the Worklog heading (and its leading HTML comment if present)
+  const afterHead = m.index + m[0].length;
+  text = text.slice(0, afterHead) + entry + text.slice(afterHead);
+  writeFileSync(arcPath, text);
+}
+
+// Get the current plan_version int from an arc.
+function planVersionOf(arcPath) {
+  return parseInt(field(frontmatter(readText(arcPath)), "plan_version", "1"), 10) || 1;
+}
+
+// Count existing instructions (I1, I2, …) in §1 to compute the next index.
+function nextInstructionIndex(text) {
+  const nums = [...text.matchAll(/^### I(\d+)\b/gm)].map((m) => parseInt(m[1], 10));
+  return (nums.length ? Math.max(...nums) : 0) + 1;
+}
+
+// Append a verbatim instruction to "## 1 · Raw Instructions". Returns the new I-index.
+function appendInstruction(arcPath, instruction, source = "chat") {
+  let text = readText(arcPath);
+  const idx = nextInstructionIndex(text);
+  const quoted = String(instruction).trim().split("\n").map((l) => `> ${l}`).join("\n");
+  const entry = `\n### I${idx} — ${today()} (source: ${source})\n${quoted}\n`;
+  const sec = text.match(/(^## 1 · Raw Instructions\n)([\s\S]*?)(?=^## )/m);
+  if (!sec) { writeFileSync(arcPath, text + entry); return idx; }
+  // append at the end of §1, before the next "## "
+  const insertAt = sec.index + sec[1].length + sec[2].replace(/\n*$/, "\n").length;
+  const head = text.slice(0, sec.index + sec[1].length);
+  const bodyTrimmed = sec[2].replace(/\n+$/, "\n");
+  text = head + bodyTrimmed + entry + "\n" + text.slice(sec.index + sec[0].length);
+  writeFileSync(arcPath, text);
+  return idx;
+}
+
+// Append a Refinement Log entry under "## 3 · Refinement Log" for a version bump.
+function appendRefinement(arcPath, version, changed, instructionIdx) {
+  let text = readText(arcPath);
+  const trigger = instructionIdx ? ` — triggered by I${instructionIdx}` : "";
+  const entry = `\n### v${version} — ${today()}${trigger}\n- changed: ${changed}\n`;
+  const m = text.match(/^## 3 · Refinement Log\n/m);
+  if (!m) { writeFileSync(arcPath, text + entry); return; }
+  // insert right after the heading + its leading HTML comment (the example block)
+  let afterHead = m.index + m[0].length;
+  const rest = text.slice(afterHead);
+  const lead = rest.match(/^(\s*<!--[\s\S]*?-->\n)/);   // skip the template's example comment
+  if (lead) afterHead += lead[0].length;
+  text = text.slice(0, afterHead) + entry + text.slice(afterHead);
+  writeFileSync(arcPath, text);
+}
+
+// Extract worklog entries (### timestamp — note + bullet lines) from §5.
+function readWorklog(arcPath) {
+  const text = readText(arcPath);
+  const sec = text.match(/^## 5 · Worklog\n([\s\S]*?)(?=^## |\Z)/m)?.[1] ?? "";
+  const body = sec.replace(/<!--[\s\S]*?-->/g, "").trim();
+  if (!body) return [];
+  // split on entry headers, keep the header text
+  const parts = body.split(/(?=^### )/m).map((s) => s.trim()).filter(Boolean);
+  return parts.map((p) => {
+    const head = p.match(/^### (.+)/)?.[1] ?? "";
+    const lines = p.split("\n").slice(1).map((l) => l.trim()).filter(Boolean);
+    return { head, lines };
+  });
+}
+
 /* -------------------------------- commands ------------------------------- */
 
 function cmdInit(target, flags) {
@@ -160,6 +334,18 @@ function cmdNew(title, flags) {
     front = setField(front, "tags", `[${tags}]`);
   }
   body = body.replace("# ARC-0000 · <Title>", `# ${id} · ${title}`);
+
+  // Optional prefill: --goal sets the Plan goal line; --task adds first tasks.
+  if (flags.goal) {
+    body = body.replace(/\*\*Goal:\*\* <[^>]*>/, `**Goal:** ${String(flags.goal).trim()}`);
+  }
+  const tasks = flags.task ? (Array.isArray(flags.task) ? flags.task : [flags.task]) : [];
+  if (tasks.length) {
+    const block = tasks.map((t, i) => `- [ ] T${i + 1} ${String(t).trim()}`).join("\n");
+    // Replace the placeholder "- [ ] T1 <…>" lines under "## 4 · Tasks" with real tasks.
+    body = body.replace(/^- \[ \] T\d+ <[^>]*>(?:\n- \[ \] T\d+ <[^>]*>)*/m, block);
+  }
+
   writeFileSync(dest, `---\n${front}\n---\n${body}`);
 
   // update the index: bump next_id, insert registry row
@@ -272,16 +458,18 @@ function cmdStatus(target, flags) {
   return 0;
 }
 
-function cmdDoctor(target) {
-  const dir = resolve(target ?? ".");
+function cmdDoctor(target, flags = {}) {
+  const dir = resolve(flags.dir ?? target ?? ".");
   const arcDir = join(dir, ".arc");
   const indexPath = join(arcDir, "INDEX.md");
-  let failures = 0, warnings = 0;
+  const doFix = !!flags.fix;
+  let failures = 0, warnings = 0, fixed = 0;
   const ok = (msg) => console.log(`  OK    ${msg}`);
   const bad = (msg) => { console.log(`  FAIL  ${msg}`); failures++; };
   const warn = (msg) => { console.log(`  WARN  ${msg}`); warnings++; };
+  const fix = (msg) => { console.log(`  FIX   ${msg}`); fixed++; };
 
-  if (!existsSync(arcDir)) return fail(`${arcDir} not found — run \`create-arc init\` first`);
+  if (!existsSync(arcDir)) return fail(`${arcDir} not found — run \`arc init\` first`);
   if (!existsSync(indexPath)) { bad(".arc/INDEX.md missing"); return finish(); }
 
   const index = readText(indexPath);
@@ -292,19 +480,39 @@ function cmdDoctor(target) {
   const nm = index.match(/^next_id:\s*ARC-(\d+)\s*$/m);
   const maxId = Math.max(-1, ...all.map(({ p }) => parseInt(basename(p).match(/^ARC-(\d+)/)?.[1] ?? "-1", 10)));
   if (!nm) bad("next_id missing or malformed in INDEX.md");
-  else if (parseInt(nm[1], 10) <= maxId) bad(`next_id ARC-${nm[1]} is not greater than highest existing arc ARC-${String(maxId).padStart(4, "0")}`);
-  else ok(`next_id ARC-${nm[1]} > highest arc id`);
+  else if (parseInt(nm[1], 10) <= maxId) {
+    if (doFix) {
+      const next = `ARC-${String(maxId + 1).padStart(4, "0")}`;
+      writeFileSync(indexPath, readText(indexPath).replace(/^next_id:\s*ARC-\d+\s*$/m, `next_id: ${next}`));
+      fix(`next_id → ${next} (was ARC-${nm[1]})`);
+    } else bad(`next_id ARC-${nm[1]} is not greater than highest existing arc ARC-${String(maxId).padStart(4, "0")}`);
+  } else ok(`next_id ARC-${nm[1]} > highest arc id`);
+
+  // index row status map (id → status cell), for status-drift repair
+  const rowStatus = new Map();
+  for (const line of index.split("\n")) {
+    const cells = line.split("|");
+    if (cells.length >= 8 && /^ARC-\d{4}$/.test(cells[1].trim())) rowStatus.set(cells[1].trim(), cells[3].trim());
+  }
 
   // file <-> index bijection, frontmatter integrity
   const indexIds = new Set([...index.matchAll(/^\|\s*(ARC-\d{4})\s*\|/gm)].map((x) => x[1]));
-  for (const { p } of all) {
+  for (const { p, archived: isArch } of all) {
     const fileId = basename(p).match(/^(ARC-\d{4})/)?.[1];
     const front = frontmatter(readText(p));
     const fmId = field(front, "id");
     const status = field(front, "status");
-    if (fmId !== fileId) bad(`${basename(p)}: frontmatter id '${fmId}' != filename id '${fileId}'`);
+    if (fmId !== fileId) {
+      if (doFix) { updateArcFrontmatter(p, { id: fileId }); fix(`${basename(p)}: frontmatter id '${fmId}' → '${fileId}'`); }
+      else bad(`${basename(p)}: frontmatter id '${fmId}' != filename id '${fileId}'`);
+    }
     if (!VALID_STATUSES.has(status)) bad(`${basename(p)}: invalid status '${status}'`);
     if (!indexIds.has(fileId)) bad(`${basename(p)}: no row in INDEX.md`);
+    // status drift: active arc's index cell disagrees with its frontmatter
+    else if (!isArch && VALID_STATUSES.has(status) && rowStatus.get(fileId) && rowStatus.get(fileId) !== status) {
+      if (doFix) { syncIndexRow(arcDir, fileId, { status }); fix(`${fileId}: index status '${rowStatus.get(fileId)}' → '${status}'`); }
+      else warn(`${fileId}: index status '${rowStatus.get(fileId)}' != frontmatter '${status}' (use --fix)`);
+    }
     const inProg = [...readText(p).matchAll(/^- \[>\]/gm)].length;
     if (inProg > 2) warn(`${basename(p)}: ${inProg} tasks marked [>] — keep at most 1–2 in progress`);
   }
@@ -315,13 +523,242 @@ function cmdDoctor(target) {
   return finish();
 
   function finish() {
+    const fx = fixed ? `, ${fixed} fixed` : "";
     console.log(failures
-      ? `\ndoctor: ${failures} problem(s), ${warnings} warning(s)`
-      : `\ndoctor: healthy (${warnings} warning(s))`);
+      ? `\ndoctor: ${failures} problem(s), ${warnings} warning(s)${fx}`
+      : `\ndoctor: healthy (${warnings} warning(s)${fx})`);
     return failures ? 1 : 0;
   }
 }
 
+/* ------------------------ lifecycle / task commands ----------------------- */
+
+// Shared: resolve an arc by reference for a mutating command.
+function resolveForMutation(ref, flags) {
+  const { arcDir, exists } = arcDirOf(flags);
+  if (!exists) return { err: fail("`.arc` not found — run `arc init` first") };
+  if (!ref) return { err: fail("which arc? pass an id or slug, e.g. `ARC-0007` or `rate-limit`") };
+  const found = findArc(arcDir, ref);
+  if (!found) return { err: fail(`no arc matching '${ref}' (try \`arc status\` to list them)`) };
+  const id = basename(found.path).match(/^(ARC-\d{4})/)?.[1];
+  return { arcDir, path: found.path, archived: found.archived, id };
+}
+
+function setStatus(ref, flags, status, { note } = {}) {
+  const r = resolveForMutation(ref, flags);
+  if (r.err) return r.err;
+  if (r.archived) return fail(`${r.id} is archived — restore it first`);
+  updateArcFrontmatter(r.path, { status });
+  syncIndexRow(r.arcDir, r.id, { status });
+  if (note) appendWorklog(r.path, note);
+  console.log(`${r.id} → ${status}`);
+  return 0;
+}
+
+const cmdStart = (ref, flags) => setStatus(ref, flags, "in-progress", { note: "started (status → in-progress)" });
+const cmdReview = (ref, flags) => setStatus(ref, flags, "review", { note: "moved to review" });
+
+function cmdBlock(ref, flags) {
+  const reason = flags.reason || flags.r;
+  return setStatus(ref, flags, "blocked", {
+    note: reason ? `blocked: ${reason}` : "blocked",
+  });
+}
+
+function cmdDone(ref, flags) {
+  const r = resolveForMutation(ref, flags);
+  if (r.err) return r.err;
+  if (r.archived) { console.log(`${r.id} is already archived`); return 0; }
+  updateArcFrontmatter(r.path, { status: "done" });
+  appendWorklog(r.path, "completed (status → done)");
+  // move file into archive/ and move the INDEX row to Archived
+  const archiveDir = join(r.arcDir, "archive");
+  mkdirSync(archiveDir, { recursive: true });
+  const destPath = join(archiveDir, basename(r.path));
+  renameSync(r.path, destPath);
+  moveIndexRowToArchived(r.arcDir, r.id, "done");
+  console.log(`${r.id} → done · moved to .arc/archive/${basename(r.path)}`);
+  return 0;
+}
+
+function cmdArchive(ref, flags) {
+  const r = resolveForMutation(ref, flags);
+  if (r.err) return r.err;
+  if (r.archived) { console.log(`${r.id} is already archived`); return 0; }
+  const outcome = flags.cancelled || flags.cancel ? "cancelled" : "done";
+  if (outcome === "cancelled") {
+    updateArcFrontmatter(r.path, { status: "cancelled" });
+    appendWorklog(r.path, flags.reason ? `cancelled: ${flags.reason}` : "cancelled");
+  }
+  const archiveDir = join(r.arcDir, "archive");
+  mkdirSync(archiveDir, { recursive: true });
+  renameSync(r.path, join(archiveDir, basename(r.path)));
+  moveIndexRowToArchived(r.arcDir, r.id, outcome);
+  console.log(`${r.id} → ${outcome} · archived`);
+  return 0;
+}
+
+// arc task <ref> <n> [done|start|block|cancel|pending]  — toggle one task marker
+// arc task <ref> --add "text"                            — append a new task
+function cmdTask(ref, flags, rest) {
+  const r = resolveForMutation(ref, flags);
+  if (r.err) return r.err;
+  let text = readText(r.path);
+  const secRe = /(^## 4 · Tasks\n)([\s\S]*?)(?=^## |\Z)/m;
+  const sec = text.match(secRe);
+  if (!sec) return fail(`${r.id}: no "## 4 · Tasks" section`);
+  let body = sec[2];
+
+  if (flags.add) {
+    const nums = [...body.matchAll(/^- \[[ >x!-]\]\s*T(\d+)/gm)].map((m) => parseInt(m[1], 10));
+    const next = (nums.length ? Math.max(...nums) : 0) + 1;
+    const line = `- [ ] T${next} ${String(flags.add).trim()}\n`;
+    body = body.replace(/\n*$/, "\n") + line;
+    text = text.slice(0, sec.index) + sec[1] + body + text.slice(sec.index + sec[0].length);
+    writeFileSync(r.path, text);
+    updateArcFrontmatter(r.path, {});
+    console.log(`${r.id}: added T${next}`);
+    return 0;
+  }
+
+  const n = rest?.[0];
+  const action = (rest?.[1] || "done").toLowerCase();
+  if (!n) return fail("usage: arc task <arc> <task-number> [done|start|block|cancel|pending]  (or --add \"text\")");
+  const marker = { done: "x", start: ">", block: "!", cancel: "-", pending: " " }[action];
+  if (marker === undefined) return fail(`unknown task action '${action}'`);
+  const tnum = String(n).replace(/[^0-9]/g, "");
+  const re = new RegExp(`^(- \\[)[ >x!-](\\]\\s*T${tnum}\\b.*)$`, "m");
+  if (!re.test(body)) return fail(`${r.id}: task T${tnum} not found`);
+  body = body.replace(re, `$1${marker}$2`);
+  text = text.slice(0, sec.index) + sec[1] + body + text.slice(sec.index + sec[0].length);
+  writeFileSync(r.path, text);
+  updateArcFrontmatter(r.path, {});
+  console.log(`${r.id}: T${tnum} → [${marker}]`);
+  return 0;
+}
+
+// arc refine <arc> "instruction" [--changed "…"] [--source chat|voice|issue|review]
+// Appends the instruction verbatim to §1, bumps plan_version, logs §3, sets refining.
+function cmdRefine(ref, flags, rest) {
+  const r = resolveForMutation(ref, flags);
+  if (r.err) return r.err;
+  if (r.archived) return fail(`${r.id} is archived — restore it before refining`);
+  const instruction = (rest || []).join(" ").trim() || (typeof flags.note === "string" ? flags.note : "");
+  if (!instruction) return fail('what changed? usage: arc refine <arc> "the new instruction" [--changed "plan delta"]');
+
+  const iIdx = appendInstruction(r.path, instruction, flags.source || "chat");
+  const nextVer = planVersionOf(r.path) + 1;
+  const changed = (typeof flags.changed === "string" && flags.changed) || instruction;
+  appendRefinement(r.path, nextVer, changed, iIdx);
+  updateArcFrontmatter(r.path, { plan_version: nextVer, status: "refining" });
+  syncIndexRow(r.arcDir, r.id, { status: "refining", planVersion: nextVer });
+  appendWorklog(r.path, `refined to plan v${nextVer} (I${iIdx})`);
+  console.log(`${r.id} → refining · plan v${nextVer} · recorded I${iIdx}`);
+  console.log(`Next: update §2 Plan to reflect v${nextVer}, then adjust Tasks.`);
+  return 0;
+}
+
+// arc note <arc> "text" [--worklog] — quick-append an instruction (default) or a worklog note.
+function cmdNote(ref, flags, rest) {
+  const r = resolveForMutation(ref, flags);
+  if (r.err) return r.err;
+  const note = (rest || []).join(" ").trim() || (typeof flags.note === "string" ? flags.note : "");
+  if (!note) return fail('usage: arc note <arc> "text" [--worklog]');
+  if (flags.worklog) {
+    appendWorklog(r.path, note);
+    updateArcFrontmatter(r.path, {});
+    console.log(`${r.id}: worklog note added`);
+  } else {
+    const iIdx = appendInstruction(r.path, note, flags.source || "chat");
+    updateArcFrontmatter(r.path, {});
+    console.log(`${r.id}: recorded I${iIdx} in Raw Instructions`);
+  }
+  return 0;
+}
+
+// arc log <arc> [--json] — show an arc's worklog timeline.
+function cmdLog(ref, flags) {
+  const r = resolveForMutation(ref, flags);
+  if (r.err) return r.err;
+  const entries = readWorklog(r.path);
+  const a = parseArc(r.path, r.archived);
+  if (flags.json) { console.log(JSON.stringify({ id: a.id, title: a.title, worklog: entries }, null, 2)); return 0; }
+  console.log(`${a.id} · ${a.title} — worklog (${entries.length} entr${entries.length === 1 ? "y" : "ies"})`);
+  if (!entries.length) { console.log("  (no worklog entries yet)"); return 0; }
+  for (const e of entries) {
+    console.log(`\n• ${e.head}`);
+    for (const l of e.lines) console.log(`    ${l}`);
+  }
+  return 0;
+}
+
+// arc show <ref> — print one arc's plan, tasks, and status notes.
+function cmdShow(ref, flags) {
+  const r = resolveForMutation(ref, flags);
+  if (r.err) return r.err;
+  const text = readText(r.path);
+  const a = parseArc(r.path, r.archived);
+  const sec = (n, title) => text.match(new RegExp(`^## ${n} · ${title}\\n([\\s\\S]*?)(?=^## |\\Z)`, "m"))?.[1]?.trim() ?? "";
+  if (flags.json) {
+    const clean = (s) => s.replace(/<!--[\s\S]*?-->/g, "").trim();
+    console.log(JSON.stringify({
+      ...a,
+      plan: clean(sec(2, "Plan \\(current[^)]*\\)") || sec(2, "Plan.*")),
+      tasks: clean(sec(4, "Tasks")),
+      status_notes: clean(sec(6, "Status Notes")),
+    }, null, 2));
+    return 0;
+  }
+  console.log(`${a.id} · ${a.title}`);
+  console.log(`status: ${a.status}${r.archived ? " (archived)" : ""} · plan v${a.plan_version} · tasks ${a.tasks_total ? `${a.tasks_done}/${a.tasks_total}` : "—"} · updated ${a.updated}`);
+  const plan = sec(2, "Plan \\(current[^)]*\\)") || sec(2, "Plan.*");
+  if (plan) { console.log("\n— Plan —"); console.log(plan.replace(/<!--[\s\S]*?-->/g, "").trim()); }
+  const tasks = sec(4, "Tasks");
+  if (tasks) { console.log("\n— Tasks —"); console.log(tasks.replace(/<!--[\s\S]*?-->/g, "").trim()); }
+  const notes = sec(6, "Status Notes");
+  if (notes) { console.log("\n— Status —"); console.log(notes.replace(/<!--[\s\S]*?-->/g, "").trim()); }
+  console.log(`\nfile: ${r.path}`);
+  return 0;
+}
+
+// arc next — suggest what to work on (active_focus, then in-progress, then planned).
+function cmdNext(flags) {
+  const { arcDir, exists } = arcDirOf(flags);
+  if (!exists) return fail("`.arc` not found — run `arc init` first");
+  const { active } = listArcFiles(arcDir);
+  if (!active.length) return (console.log("no active arcs — `arc new \"Title\"` to begin"), 0);
+  const arcs = active.map((p) => parseArc(p, false))
+    // The standing maintenance arc (ARC-0000) is always in-progress; only surface
+    // it as "next" when it actually has unfinished tasks and nothing else is active.
+    .filter((a) => !(a.id === "ARC-0000" && a.tasks_in_progress === 0));
+  if (!arcs.length) return (console.log("no actionable arcs — `arc new \"Title\"` to begin"), 0);
+  const idx = existsSync(join(arcDir, "INDEX.md")) ? readText(join(arcDir, "INDEX.md")) : "";
+  const focus = idx.match(/^active_focus:\s*(.+)$/m)?.[1]?.trim();
+
+  const byStatus = (s) => arcs.filter((a) => a.status === s);
+  const pick =
+    (focus && focus !== "—" && arcs.find((a) => a.id === focus || a.title.includes(focus))) ||
+    byStatus("in-progress")[0] || byStatus("refining")[0] ||
+    byStatus("planned")[0] || byStatus("review")[0] || byStatus("draft")[0];
+
+  if (flags.json) {
+    console.log(JSON.stringify({
+      next: pick ? { id: pick.id, title: pick.title, status: pick.status,
+                     tasks_done: pick.tasks_done, tasks_total: pick.tasks_total,
+                     tasks_blocked: pick.tasks_blocked } : null,
+      blocked: byStatus("blocked").map((a) => a.id),
+    }, null, 2));
+    return 0;
+  }
+  if (!pick) { console.log("nothing actionable — all arcs are blocked or done"); return 0; }
+  console.log(`next: ${pick.id} · ${pick.title}  [${pick.status}]`);
+  console.log(`  tasks ${pick.tasks_total ? `${pick.tasks_done}/${pick.tasks_total}` : "—"}${pick.tasks_blocked ? ` · ${pick.tasks_blocked} blocked` : ""}`);
+  console.log(`  open:  arc show ${pick.id}`);
+  const blocked = byStatus("blocked");
+  if (blocked.length) console.log(`  (blocked: ${blocked.map((a) => a.id).join(", ")})`);
+  return 0;
+}
+
 /* --------------------------------- main ----------------------------------- */
 
 function fail(msg) { console.error(`error: ${msg}`); return 1; }
@@ -335,7 +772,7 @@ const ARC_COMMANDS = {
 
 "$ARGUMENTS"
 
-Steps: read .arc/INDEX.md; if an open arc already covers this, append the instruction verbatim and refine its plan; otherwise create a new arc (use \`npx @ksoftm/create-arc new "<short title>"\`, or create the file from .arc/_TEMPLATE.md and register it in INDEX.md). Record the raw instruction verbatim, draft the Plan with checkable acceptance criteria, and list the Tasks. Do not start coding until the plan is acknowledged.`,
+Steps: run \`arc status\` to see existing arcs; if an open arc already covers this, append the instruction verbatim and refine its plan; otherwise create a new arc with \`arc new "<short title>" --goal "<one-line goal>" --task "<first task>" --task "<next task>"\`. Then record the raw instruction verbatim in §1, finish the Plan with checkable acceptance criteria, and refine the Tasks. Do not start coding until the plan is acknowledged.`,
   },
   "arc-refine": {
     desc: "ARC: fold a new instruction into an existing arc (Refine)",
@@ -343,11 +780,11 @@ Steps: read .arc/INDEX.md; if an open arc already covers this, append the instru
 
 "$ARGUMENTS"
 
-Append it verbatim as the next Raw Instruction, add a Refinement Log entry (new plan_version, what changed, task impact), rewrite the Plan to reflect only the current intent, and adjust the Tasks. Move dropped scope to "Out of scope". Never edit the append-only sections retroactively.`,
+Run \`arc refine <arc> "$ARGUMENTS" --changed "<one-line plan delta>"\` — this appends the instruction verbatim to §1, bumps plan_version, adds a §3 Refinement Log entry, and sets the arc to refining. Then rewrite §2 Plan to reflect only the current intent, adjust §4 Tasks (move dropped scope to "Out of scope"), and resume construction only once the plan and tasks absorb the change. Never edit the append-only sections retroactively.`,
   },
   "arc-build": {
     desc: "ARC: do the work for the active arc (Read Before / Update After Editing)",
-    body: `Read ./ARC.md. Before editing: read .arc/INDEX.md, fully read the arc(s) covering the files you'll touch, and read the real source files. Work the task list in order, marking one task in progress. After editing: advance task states, append a Worklog entry (tasks, files read, files changed, summary, decisions, follow-ups), update the arc frontmatter and its INDEX row, and reference the arc id in the commit. An edit without a worklog entry is unfinished.
+    body: `Read ./ARC.md. Before editing: run \`arc status\` (or read .arc/INDEX.md), fully read the arc(s) covering the files you'll touch, and read the real source files. Mark a task in progress with \`arc task <arc> <n> start\`, do the work, then tick it with \`arc task <arc> <n> done\`. After editing: append a Worklog entry (tasks, files read, files changed, summary, decisions, follow-ups), keep the arc's Status Notes current, and reference the arc id in the commit. When the arc is finished, run \`arc done <arc>\` to mark it done and archive it. An edit without a worklog entry is unfinished.
 
 Focus: $ARGUMENTS`,
   },
@@ -404,22 +841,81 @@ function cmdAgentInit(flags) {
   return 0;
 }
 
-function help() {
+const COMMAND_HELP = {
+  init: `arc init [dir] [--owner=NAME]
+  Scaffold ARC.md + .arc/ in dir (default: current). Idempotent — never overwrites.
+  --owner NAME   arc owner (default: git config user.name)`,
+  new: `arc new "Short imperative title" [options]
+  Create the next arc and register it in INDEX.md.
+  --goal "…"     prefill the Plan goal line
+  --task "…"     add a first task (repeatable: --task a --task b)
+  --tags a,b     frontmatter tags
+  --owner NAME   arc owner
+  --dir DIR      project dir (default: current)`,
+  start: `arc start <arc>
+  Set an arc to in-progress and log it. <arc> is an id or slug (e.g. ARC-0007 or rate-limit).`,
+  done: `arc done <arc>
+  Mark an arc done, log it, move the file to .arc/archive/, and move its INDEX row to Archived.`,
+  block: `arc block <arc> [--reason "…"]
+  Set an arc to blocked, recording the reason in the worklog.`,
+  refine: `arc refine <arc> "the new instruction" [--changed "plan delta"] [--source chat|voice|issue|review]
+  Fold a new instruction into an arc: append it verbatim to §1, bump plan_version,
+  add a §3 Refinement Log entry, and set status to refining.`,
+  note: `arc note <arc> "text" [--worklog] [--source …]
+  Quick-append a note. Default goes to §1 Raw Instructions; --worklog appends to §5 Worklog.`,
+  log: `arc log <arc> [--json]
+  Show an arc's worklog timeline (newest entries as recorded).`,
+  archive: `arc archive <arc> [--cancelled] [--reason "…"]
+  Archive an arc. Default outcome is "done"; --cancelled archives it as cancelled.`,
+  task: `arc task <arc> <n> [done|start|block|cancel|pending]
+  Toggle task T<n>'s marker. Default action is "done".
+  arc task <arc> --add "text"   append a new task`,
+  show: `arc show <arc>
+  Print one arc's plan, tasks, and status notes.`,
+  next: `arc next
+  Suggest what to work on (active_focus → in-progress → planned).`,
+  status: `arc status [dir] [--json]
+  Table of every arc: id, status, plan version, task progress.`,
+  doctor: `arc doctor [dir] [--fix]
+  Consistency checks (exit 1 on problems). --fix auto-repairs index/status drift.`,
+  "agent-init": `arc agent-init [--agents=a,b] [--force]
+  Write /arc-* slash commands for AI agents (agents: ${Object.keys(AGENT_TARGETS).join(", ")}; default: all).`,
+};
+
+function help(topic) {
+  if (topic && COMMAND_HELP[topic]) { console.log(COMMAND_HELP[topic]); return 0; }
   console.log(`create-arc v${PKG.version} — ARC plan-driven development (Align → Refine → Construct)
 (alias: \`arc\`)
 
-Usage:
-  arc init [dir] [--owner=NAME]            scaffold ARC.md + .arc/ (idempotent)
-  arc new "Title" [--dir=.] [--tags=a,b]   create + register the next arc
-  arc status [dir] [--json]                status table across all arcs
-  arc doctor [dir]                         consistency checks (exit 1 on problems)
-  arc agent-init [--agents=a,b] [--force]  write /slash commands for AI agents
-                                           (agents: ${ALL_AGENTS.join(", ")}; default: all)
-
-Run with npx (no install): npx @ksoftm/create-arc <command>
-Install globally:          npm i -g @ksoftm/create-arc   then: arc <command>
-Project dev dependency:    npm i -D @ksoftm/create-arc   then: npx arc <command>
-
+Setup
+  init [dir]                 scaffold ARC.md + .arc/ (idempotent)
+  agent-init [--agents=…]    write /arc-* slash commands for AI agents
+
+Capture & plan
+  new "Title" [--goal …] [--task …] [--tags a,b]
+                             create + register the next arc
+
+Work the arc
+  start <arc>                → in-progress
+  task <arc> <n> [action]    tick a task ([done]/start/block/cancel/pending); --add "text"
+  refine <arc> "…"           fold in a new instruction (bumps plan version → refining)
+  note <arc> "…"             quick-append to Raw Instructions; --worklog for a worklog note
+  block <arc> [--reason …]   → blocked
+  done <arc>                 → done + archive (file + index row)
+  archive <arc> [--cancelled]
+
+Inspect
+  status [dir] [--json]      table of every arc
+  show <arc> [--json]        one arc's plan, tasks, status
+  log <arc> [--json]         an arc's worklog timeline
+  next [--json]              what to work on next
+  doctor [dir] [--fix]       consistency checks (+ auto-repair)
+
+<arc> is an id or slug: ARC-0007, 7, or a slug substring like "rate-limit".
+Per-command help:  arc help <command>   (e.g. arc help new)
+
+Run with npx: npx @ksoftm/create-arc <command>
+Install:      npm i -g @ksoftm/create-arc   then use \`arc\`
 Protocol reference: ARC.md in your project root after init.`);
   return 0;
 }
@@ -427,14 +923,28 @@ Protocol reference: ARC.md in your project root after init.`);
 const { pos, flags } = parseArgv(process.argv.slice(2));
 const cmd = pos[0];
 
+// per-command help: `arc help new` or `arc new --help`
+if (flags.help && cmd && cmd !== "help") { process.exit(help(cmd)); }
+
 let code;
 if (flags.version || cmd === "version") { console.log(PKG.version); code = 0; }
-else if (!cmd || cmd === "help" || flags.help) code = help();
+else if (!cmd || cmd === "help") code = help(pos[1]);
 else if (cmd === "init") code = cmdInit(pos[1], flags);
 else if (cmd === "new") code = cmdNew(pos.slice(1).join(" "), flags);
 else if (cmd === "status") code = cmdStatus(pos[1], flags);
-else if (cmd === "doctor") code = cmdDoctor(pos[1]);
+else if (cmd === "doctor") code = cmdDoctor(pos[1], flags);
 else if (cmd === "agent-init" || cmd === "agents") code = cmdAgentInit(flags);
+else if (cmd === "start") code = cmdStart(pos[1], flags);
+else if (cmd === "done") code = cmdDone(pos[1], flags);
+else if (cmd === "block") code = cmdBlock(pos[1], flags);
+else if (cmd === "review") code = cmdReview(pos[1], flags);
+else if (cmd === "refine") code = cmdRefine(pos[1], flags, pos.slice(2));
+else if (cmd === "note") code = cmdNote(pos[1], flags, pos.slice(2));
+else if (cmd === "log") code = cmdLog(pos[1], flags);
+else if (cmd === "archive") code = cmdArchive(pos[1], flags);
+else if (cmd === "task") code = cmdTask(pos[1], flags, pos.slice(2));
+else if (cmd === "show" || cmd === "view") code = cmdShow(pos[1], flags);
+else if (cmd === "next") code = cmdNext(flags);
 else code = fail(`unknown command '${cmd}' — try: arc help`);
 
 process.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksoftm/create-arc",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": false,
   "description": "Scaffold and manage ARC — plan-driven development for AI agents (Align → Refine → Construct). Pure-Markdown plans, tasks, worklogs and statuses in .arc/, for any language and any agent.",
   "keywords": [