@ksoftm/create-arc 1.2.0 → 1.4.0

package/README.md

@@ -36,10 +36,13 @@ Requires Node ≥ 18.
 | `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>` | Print one arc's plan, tasks, and status notes. |
-| `next` | Suggest what to work on next. |
+| `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] [--fix]` | Consistency checks — index ↔ file bijection, ID/`next_id` sanity, valid statuses. Exits non-zero on problems (CI-friendly). `--fix` auto-repairs drift. |
 

package/bin/cli.js

@@ -55,7 +55,7 @@ function detectOwner(dir) {
   return "user";
 }
 
-const BOOLEAN_FLAGS = new Set(["json", "help", "version", "fix", "force", "cancelled", "cancel"]);
+const BOOLEAN_FLAGS = new Set(["json", "help", "version", "fix", "force", "cancelled", "cancel", "worklog"]);
 const REPEATABLE_FLAGS = new Set(["task"]);
 
 function parseArgv(argv) {
@@ -212,6 +212,60 @@ 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) {
@@ -583,6 +637,61 @@ function cmdTask(ref, flags, rest) {
   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);
@@ -590,6 +699,16 @@ function cmdShow(ref, flags) {
   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.*");
@@ -622,6 +741,15 @@ function cmdNext(flags) {
     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` : ""}`);
@@ -652,7 +780,7 @@ Steps: run \`arc status\` to see existing arcs; if an open arc already covers th
 
 "$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)",
@@ -662,11 +790,23 @@ Focus: $ARGUMENTS`,
   },
   "arc-status": {
     desc: "ARC: summarize all arcs and what to resume",
-    body: `Run \`npx @ksoftm/create-arc status\` (or read .arc/INDEX.md and each arc). Report every arc's id, status, plan version, task progress, and which in-progress/refining arcs to resume — reading each one's Status Notes and last Worklog entry.`,
+    body: `Run \`arc status\` (or read .arc/INDEX.md). Report every arc's id, status, plan version, and task progress, and call out which in-progress/refining arcs to resume. For any arc that needs detail, run \`arc show <arc>\` for its plan/tasks/status and \`arc log <arc>\` for its worklog history. Then run \`arc next\` to recommend what to pick up.`,
   },
   "arc-resume": {
     desc: "ARC: pick up the in-progress arc cold",
-    body: `Read ./ARC.md. Read .arc/INDEX.md, find arcs in in-progress or refining, open them, read Status Notes and the last Worklog entry, then continue from the open tasks — after running Read Before Editing. If code and the arc disagree, the code is truth: note the drift in the Worklog and correct the arc.`,
+    body: `Read ./ARC.md. Run \`arc next\` to find what to work on, then \`arc show <arc>\` and \`arc log <arc>\` to read its plan, status notes, and last worklog entries. Continue from the open tasks — after running Read Before Editing. If code and the arc disagree, the code is truth: \`arc note <arc> "drift: …" --worklog\` to record it, then correct the arc.`,
+  },
+  "arc-note": {
+    desc: "ARC: quick-capture an instruction or worklog note onto an arc",
+    body: `Capture this onto the relevant arc without rewriting the plan:
+
+"$ARGUMENTS"
+
+If it's a new requirement or instruction, run \`arc note <arc> "$ARGUMENTS"\` (it lands verbatim in §1 Raw Instructions). If it's a progress/decision note about work just done, run \`arc note <arc> "$ARGUMENTS" --worklog\` instead. Use \`arc status\` first if you're unsure which arc this belongs to. If it actually changes the plan or scope, use /arc-refine instead of /arc-note.`,
+  },
+  "arc-log": {
+    desc: "ARC: show an arc's worklog history",
+    body: `Run \`arc log <arc>\` for the arc referenced by "$ARGUMENTS" (resolve it via \`arc status\` if only a topic is given) and summarize its worklog timeline: what was done, in what order, and any decisions or follow-ups recorded. Then state where the arc currently stands and what the next step is.`,
   },
 };
 
@@ -709,7 +849,7 @@ function cmdAgentInit(flags) {
     console.log(`  ${agent.padEnd(9)} ${rel}/  (${Object.keys(ARC_COMMANDS).length} commands)`);
   }
   console.log(`\nAgent commands written (created ${created}, skipped ${skipped}${flags.force ? "" : "; use --force to overwrite"}).`);
-  console.log(`Type /arc-new, /arc-build, /arc-status, /arc-refine, /arc-resume in your agent.`);
+  console.log(`Commands: /arc-new /arc-build /arc-refine /arc-note /arc-log /arc-status /arc-resume`);
   return 0;
 }
 
@@ -730,6 +870,13 @@ const COMMAND_HELP = {
   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]
@@ -763,14 +910,17 @@ Capture & plan
 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>                 one arc's plan, tasks, status
-  next                       what to work on next
+  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".
@@ -800,6 +950,9 @@ 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksoftm/create-arc",
-  "version": "1.2.0",
+  "version": "1.4.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": [