#!/usr/bin/env node
// specs.mjs: where every spec under specs/ stands, read from its files.
//
// The pipeline skills (plan, document, implement, revise-plan, finalize,
// review, handoff) all need the same filesystem facts: which specs exist, what
// a spec's PLAN-DRAFT says, which phases are open, how many tasks are done.
// Those have one correct answer, so this script computes them instead of each
// prompt re-deriving them by hand. It also performs the two mechanical writes
// (a Phase Checklist marker, the archive move), with --dry-run.
//
// Shell listing only matters to people: specs/ is gitignored, so editor search
// tools skip it. This script reads the disk directly and does not care.
import fs from "node:fs";
import path from "node:path";
import { EXIT, fail, out, parseArgs, run, readText, isDir, rel, eol, consoleLib, isoDate, phaseFiles } from "./common.mjs";
const USAGE = `
specs.mjs: spec state for the Plan2Code pipeline skills. JSON on stdout.
node specs.mjs list [--root
]
Every active spec under specs/ (never specs--completed/), newest first:
state, detail, PLAN-DRAFT files with their **Status:** line, overview,
phase count. Also the names already archived in specs--completed/.
node specs.mjs status [--root ]
One spec in full: the overview's Phase Checklist, Parallel Execution
Groups, per-phase task counts by marker, task-numbering problems,
completion, the implement phase-selection verdict ("next"), the pending
phases, and consistency checks. is specs/, , or a path
to its overview.md.
node specs.mjs metrics --step document|finalize [--set key=value ...]
The METRICS_JSON comment for that step, countable fields computed from
the files; judgment fields come from --set (numbers only).
document: total_tasks, tasks_per_phase, phase_count,
parallel_groups_identified computed; pass
--set verification_items_added=N (your Verification Summary's
Added total; the VERIFICATION comments are reported as a check).
finalize: completion_rate_at_audit, tasks_completed, tasks_total; pass
--set verification_failures_found=N
--set documentation_updates_needed=N.
node specs.mjs mark --phase --to open|in-progress|done [--dry-run]
Set phase N's Phase Checklist marker in overview.md ([ ], [/], [x]).
done also sets the phase file's Status line (**Status:**, **Status**:
or Status:) to Complete (and warns if tasks are unfinished); open on a
Complete phase sets it to In Progress. Warns when the phase file has no
Status line. Refuses a phase with duplicate checklist rows, and refuses
in-progress -> open (started work stays marked).
node specs.mjs archive [--dry-run]
Move specs// to specs--completed//. Refuses if the target
exists, or if is not a folder directly under specs/.
Markers: [ ] pending · [/] in progress · [x] complete · [!] blocked · [?] assumed.
Exit: 0 ok · 2 bad arguments · 3 spec not found · 4 cannot parse / check
failed · 5 refused.
`;
/* ------------------------------------------------------------- resolving */
function realOrResolved(p) {
try {
return fs.realpathSync.native(p);
} catch {
return path.resolve(p);
}
}
const samePath = (a, b) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
// Read-only commands (status, metrics) accept an archived spec, because
// Finalize reads its own spec after Step 6 moved it. Writes never do.
function resolveSpec(root, arg, { allowArchived = false } = {}) {
if (!arg) fail(EXIT.USAGE, "missing-spec", "Name the spec: specs/, , or its overview.md path.", "Run `specs.mjs list` to see the active specs.");
let p = arg.replace(/\\/g, "/").replace(/\/+$/, "");
if (/\/overview\.md$/i.test(p) || /\/phase-[^/]*\.md$/i.test(p)) p = p.replace(/\/[^/]+$/, "");
const abs = path.isAbsolute(p) ? p : p.includes("/") ? path.join(root, p) : path.join(root, "specs", p);
const relPath = rel(root, abs);
if (!allowArchived && /(^|\/)specs--completed(\/|$)/.test(relPath)) {
fail(EXIT.REFUSED, "archived-spec", `${relPath} is archived; the pipeline only changes active specs under specs/.`, "Pick an active spec from `specs.mjs list`.");
}
// A spec is a folder directly under specs/ (or specs--completed/ for a read).
// Without this, `archive .` would move all of specs/ and `archive ./src` a
// source folder.
const homes = [path.join(root, "specs"), ...(allowArchived ? [path.join(root, "specs--completed")] : [])].map(realOrResolved);
const parent = realOrResolved(path.dirname(path.resolve(abs)));
if (!homes.some((h) => samePath(h, parent))) {
fail(EXIT.REFUSED, "not-a-spec", `${relPath} is not a spec folder: a spec sits directly under specs/${allowArchived ? " (or specs--completed/)" : ""}.`, "Pass specs/ or ; run `specs.mjs list` to see the active specs.");
}
if (!isDir(abs)) {
fail(EXIT.NOT_FOUND, "spec-not-found", `No spec folder at ${relPath}.`, "Run `specs.mjs list` from the project root (or pass --root) to see the active specs.");
}
return { dir: abs, rel: relPath, name: path.basename(abs) };
}
/* -------------------------------------------------------------- parsing */
const MARKERS = { " ": "pending", "/": "in-progress", x: "complete", X: "complete", "!": "blocked", "?": "assumed" };
// Task 2.3, a lettered sub-task 3.6a, or a named one such as a testing task 1.T.
const TASK_RE = /^\s*[-*] \[(.)\]\s+\*\*Task\s+(\d+)\.(\d+|[A-Za-z]+)([a-z]*)\b/;
const CHECKBOX_RE = /^\s*[-*] \[(.)\]/;
// The Status line in any of the forms people write it: **Status:**, **Status**:
// or a plain Status:, optionally as a list item. Groups: everything up to the
// value (kept as written when the value is rewritten), the value, trailing blanks.
const STATUS_RE = /^([ \t]*(?:[-*][ \t]*)?(?:\*\*Status:\*\*|\*\*Status\*\*:|Status:)[ \t]*)(.+?)([ \t]*)$/m;
function statusOf(text) {
const m = (text || "").match(STATUS_RE);
return m ? m[2] : null;
}
/** A markdown section's lines: from its heading to the next heading of the same or higher level. */
function section(text, headingRe) {
const lines = text.split(/\r?\n/);
const start = lines.findIndex((l) => /^#{1,6}\s/.test(l) && headingRe.test(l));
if (start === -1) return null;
const level = lines[start].match(/^#+/)[0].length;
let end = lines.length;
for (let i = start + 1; i < lines.length; i++) {
const m = lines[i].match(/^(#+)\s/);
if (m && m[1].length <= level) {
end = i;
break;
}
}
return { start, end, lines: lines.slice(start + 1, end) };
}
function plainText(s) {
return s
.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
.replace(/[*_`]/g, "")
.replace(/\s+/g, " ")
.trim();
}
/** Phase Checklist rows: the first "Phase N" on each checkbox line names the phase. */
function parseChecklist(overview) {
const sec = section(overview, /Phase Checklist/i);
if (!sec) return { found: false, phases: [], unparsed: [] };
const phases = [];
const unparsed = [];
sec.lines.forEach((line, i) => {
const m = line.match(CHECKBOX_RE);
if (!m) return;
const text = plainText(line.replace(CHECKBOX_RE, ""));
const num = text.match(/\bPhase\s+(\d+)\b/i);
if (!num) {
unparsed.push({ line: sec.start + 2 + i, text: line.trim() });
return;
}
const after = text.slice(num.index + num[0].length).replace(/^\s*[:\-–—]\s*/, "");
const name = after.split(/\s+[-–—]\s+|\s+\(|\s+_\(|:\s|\s+see\s+phase-/i)[0].replace(/\s*phase-\d+\.md\s*$/i, "").trim();
phases.push({
number: Number(num[1]),
marker: m[1],
state: MARKERS[m[1]] || "unknown",
name: name.replace(/\s*\[Milestone[^\]]*\]\s*$/i, "") || `Phase ${num[1]}`,
line: sec.start + 2 + i,
});
});
return { found: true, phases, unparsed };
}
/** "2, 3", "2-4" and "2–4" (or an em dash) alike: ranges expand, so a group cell never loses a phase. */
function phaseList(cell) {
const outList = [];
for (const part of cell.match(/\d+\s*[-–\u2014]\s*\d+|\d+/g) || []) {
const r = part.match(/^(\d+)\s*[-–\u2014]\s*(\d+)$/);
if (r && Number(r[2]) >= Number(r[1]) && Number(r[2]) - Number(r[1]) < 100) {
for (let n = Number(r[1]); n <= Number(r[2]); n++) outList.push(n);
} else outList.push(...part.match(/\d+/g).map(Number));
}
return [...new Set(outList)];
}
/** Parallel Execution Groups table: real groups only (a named group with 2+ phases). */
function parseGroups(overview) {
const sec = section(overview, /Parallel Execution Groups/i);
if (!sec) return { found: false, groups: [] };
const groups = [];
const seen = new Set();
for (const line of sec.lines) {
if (!/^\s*\|/.test(line) || /^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
const cells = line.split("|").slice(1, -1).map((c) => c.trim());
if (cells.length < 2 || /^group$/i.test(cells[0])) continue;
const id = plainText(cells[0]);
const phases = phaseList(cells[1]);
// "None", a dash, a single phase, a group its author labelled sequential
// ("A (sequential)"), or a Phases cell written as a chain ("1 → 2") is not
// a parallel group.
if (!id || /^(none|-|–|—)$/i.test(id) || /\bsequential\b/i.test(id) || /→|->|\bthen\b/i.test(cells[1]) || phases.length < 2) continue;
const key = `${id}:${phases.join(",")}`;
if (seen.has(key)) continue;
seen.add(key);
groups.push({ id, phases, reason: plainText(cells[2] || "") });
}
return { found: true, groups };
}
function firstSentence(text) {
const t = plainText(text);
const m = t.match(/^(.+?[.!?])(\s|$)/);
return (m ? m[1] : t).slice(0, 240);
}
function parsePhaseFile(file, number) {
const text = readText(file) || "";
const lines = text.split(/\r?\n/);
const title = (lines.find((l) => /^#\s/.test(l)) || "").replace(/^#\s+/, "").trim();
const status = statusOf(text);
const counts = { pending: 0, "in-progress": 0, complete: 0, blocked: 0, assumed: 0, unknown: 0 };
const tasks = [];
const strayCheckboxes = [];
const unmatchedTasks = [];
let heading = "";
lines.forEach((line, i) => {
const h = line.match(/^#{1,6}\s+(.*)$/);
if (h) heading = plainText(h[1]);
const t = line.match(TASK_RE);
if (t) {
const state = MARKERS[t[1]] || "unknown";
counts[state]++;
const named = !/^\d+$/.test(t[3]);
tasks.push({ id: `${t[2]}.${t[3]}${t[4]}`, phase: Number(t[2]), seq: named ? null : Number(t[3]), named, suffix: t[4], marker: t[1], state, line: i + 1 });
return;
}
// A line that looks like a task but is not counted as one (Task 1.4A,
// "1. [ ] **Task", a non-bold "- [ ] Task 1.3") would make the audit undercount.
if (/^\s*(?:[-*]|\d+\.)\s+\[.\].*\bTask\s+\d+\./i.test(line)) unmatchedTasks.push({ line: i + 1, text: line.trim().slice(0, 120) });
if (CHECKBOX_RE.test(line)) strayCheckboxes.push({ line: i + 1, section: heading, text: line.trim().slice(0, 120) });
});
// Numbering: every task belongs to this phase, the base numbers run 1..n with
// no gaps or repeats, and a lettered task (3.6a) sits after its base (3.6).
// Named tasks (1.T) are outside the numeric sequence.
const numbering = [];
const bases = [];
for (const t of tasks) {
if (t.phase !== number) numbering.push(`Task ${t.id} is in phase-${number}.md but numbered for Phase ${t.phase}`);
if (!t.suffix && !t.named) bases.push(t.seq);
}
const seenIds = new Set();
for (const t of tasks) {
if (seenIds.has(t.id)) numbering.push(`Task ${t.id} appears more than once`);
seenIds.add(t.id);
if (t.suffix && !t.named && !bases.includes(t.seq)) numbering.push(`Task ${t.id} has no base Task ${t.phase}.${t.seq}`);
}
bases.forEach((seq, i) => {
if (seq !== i + 1 && !numbering.some((n) => n.startsWith("Task numbering"))) {
numbering.push(`Task numbering is not sequential: expected ${number}.${i + 1}, found ${number}.${seq}`);
}
});
const overviewSec = section(text, /^#{1,6}\s+Overview\b/i);
const goalText = overviewSec ? overviewSec.lines.join("\n").split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !/^[-*|>]/.test(p)) : "";
return {
title,
status,
goal: goalText ? firstSentence(goalText) : null,
total: tasks.length,
counts,
open: counts.pending + counts["in-progress"] + counts.blocked + counts.unknown,
// Open work a phase cannot be approved over; blocked tasks may stand ([!] is allowed at sign-off).
unfinished: counts.pending + counts["in-progress"] + counts.unknown,
tasks,
numbering,
strayCheckboxes,
unmatchedTasks,
};
}
function planDrafts(dir) {
return fs
.readdirSync(dir)
.filter((n) => /^PLAN-DRAFT.*\.md$/i.test(n))
.sort()
.map((file) => ({
file,
archived: /-prev\.md$/i.test(file),
status: statusOf(readText(path.join(dir, file))),
}));
}
/* ---------------------------------------------------------------- status */
function specStatus(spec) {
const overviewPath = path.join(spec.dir, "overview.md");
const overview = readText(overviewPath);
const files = phaseFiles(spec.dir);
// An empty overview.md still exists; only a missing one is "no overview".
const hasOverview = overview !== null;
const checklist = hasOverview ? parseChecklist(overview) : { found: false, phases: [], unparsed: [] };
const groups = hasOverview ? parseGroups(overview) : { found: false, groups: [] };
const checks = [];
const check = (level, code, message) => checks.push({ level, code, message });
for (const [n, names] of files.extra) {
check("warn", "duplicate-phase-file", `Phase ${n} has more than one file: using ${files.get(n)}, ignoring ${names.join(", ")}`);
}
const rowsByNumber = new Map();
for (const r of checklist.phases) rowsByNumber.set(r.number, [...(rowsByNumber.get(r.number) || []), r]);
for (const [n, rows] of rowsByNumber) {
if (rows.length > 1) check("error", "duplicate-checklist-row", `Phase ${n} has ${rows.length} rows in the Phase Checklist (overview.md lines ${rows.map((r) => r.line).join(", ")}); the first one is used`);
}
const phases = [];
const numbers = new Set([...checklist.phases.map((p) => p.number), ...files.keys()]);
for (const number of [...numbers].sort((a, b) => a - b)) {
const row = checklist.phases.find((p) => p.number === number) || null;
const file = files.get(number) || null;
const parsed = file ? parsePhaseFile(path.join(spec.dir, file), number) : null;
phases.push({
number,
name: row ? row.name : parsed ? parsed.title.replace(/^Phase\s+\d+\s*[:\-–—]?\s*/i, "") : `Phase ${number}`,
checklist: row ? row.state : null,
marker: row ? row.marker : null,
file,
status: parsed ? parsed.status : null,
goal: parsed ? parsed.goal : null,
tasks: parsed ? { total: parsed.total, open: parsed.open, ...parsed.counts } : null,
blockedTasks: parsed ? parsed.tasks.filter((t) => t.state === "blocked").map((t) => t.id) : [],
assumedTasks: parsed ? parsed.tasks.filter((t) => t.state === "assumed").map((t) => t.id) : [],
openTasks: parsed ? parsed.tasks.filter((t) => ["pending", "in-progress", "blocked", "unknown"].includes(t.state)).map((t) => t.id) : [],
});
if (!row && hasOverview) check("error", "missing-checklist-row", `phase-${number}.md has no row in overview.md's Phase Checklist`);
if (row && !file) check("error", "missing-phase-file", `Phase Checklist lists Phase ${number} but there is no phase-${number}.md`);
if (parsed) {
for (const n of parsed.numbering) check("error", "task-numbering", `phase-${number}.md: ${n}`);
// Prerequisites and criteria are plain bullets by rule; other checkbox
// blocks (a Phase Testing list) are the template's own and are not tasks.
for (const s of parsed.strayCheckboxes.filter((c) => /prerequisite|criteria/i.test(c.section))) {
check("warn", "criteria-checkbox", `phase-${number}.md:${s.line} is a checkbox under "${s.section}"; prerequisites and criteria use plain bullets`);
}
if (parsed.total === 0) check("warn", "no-tasks", `phase-${number}.md has no **Task ${number}.N:** checkbox lines`);
for (const u of parsed.unmatchedTasks) {
check("warn", "uncounted-task", `phase-${number}.md:${u.line} looks like a task but is not counted (a task line is "- [ ] **Task ${number}.N:**"): ${u.text}`);
}
const done = parsed.counts.complete + parsed.counts.assumed;
const rowDone = row && (row.state === "complete" || row.state === "assumed");
// A phase may be approved with blocked [!] tasks left (Implementation
// Mode's self-review allows "[x] or blocked [!]"); only unfinished work is an error.
if (rowDone && parsed.unfinished > 0) {
check("error", "checked-with-open-tasks", `Phase ${number} is [${row.marker}] in overview.md but ${parsed.unfinished} task(s) are not done (${phases.at(-1).openTasks.filter((id) => !phases.at(-1).blockedTasks.includes(id)).join(", ")})`);
} else if (rowDone && parsed.counts.blocked > 0) {
check("info", "approved-with-blocked", `Phase ${number} is [${row.marker}] with ${parsed.counts.blocked} blocked task(s) (${phases.at(-1).blockedTasks.join(", ")})`);
}
if (row && row.state === "pending" && parsed.total > 0 && done > 0) {
// Done tasks under a [ ] phase with work still open is what a re-opened
// phase looks like (revise-plan); with nothing open it is a missed mark.
if (parsed.unfinished > 0) check("info", "partly-done-unchecked", `Phase ${number} is [ ] with ${done} task(s) done and ${parsed.unfinished} open (normal for a re-opened phase)`);
else check("warn", "unchecked-with-done-tasks", `Phase ${number} is [ ] in overview.md but all ${done} unblocked task(s) are done`);
}
if (row && !rowDone && row.state !== "pending" && parsed.total > 0 && parsed.unfinished === 0) {
check("info", "done-not-approved", `Phase ${number}: every task is done but overview.md still shows [${row.marker}] (normal until the user approves the phase)`);
}
}
}
if (!hasOverview) check("error", "no-overview", `${spec.rel} has no overview.md`);
else if (!checklist.found) check("error", "no-checklist", "overview.md has no ## Phase Checklist section");
for (const u of checklist.unparsed) check("warn", "unparsed-checklist-row", `overview.md:${u.line} is a checkbox in the Phase Checklist with no "Phase N" in it: ${u.text}`);
for (const g of groups.groups) {
for (const n of g.phases) if (!numbers.has(n)) check("error", "group-unknown-phase", `Parallel group ${g.id} names Phase ${n}, which does not exist`);
}
// Totals. Completed = [x] plus [?] (assumed complete); [?] is reported on its own too.
// Incomplete = [ ] + [/] (+ unreadable markers); Blocked is its own column.
const totals = { total: 0, complete: 0, assumed: 0, pending: 0, "in-progress": 0, blocked: 0, unknown: 0 };
for (const p of phases) if (p.tasks) for (const k of Object.keys(totals)) totals[k] += p.tasks[k] || 0;
const completed = totals.complete + totals.assumed;
const completion = totals.total ? completed / totals.total : null;
return {
ok: true,
spec: spec.rel,
name: spec.name,
overview: hasOverview ? "overview.md" : null,
planDrafts: planDrafts(spec.dir),
phases,
parallelGroups: groups.groups,
totals: { ...totals, completed, incomplete: totals.pending + totals["in-progress"] + totals.unknown },
completion: completion === null ? null : Number(completion.toFixed(4)),
completionPercent: completion === null ? null : Math.round(completion * 100),
next: nextPhase(phases, groups.groups, checklist.found),
pending: phases
.filter((p) => p.checklist && p.checklist !== "complete" && p.checklist !== "assumed")
.map((p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null, open: p.tasks ? p.tasks.open : null, goal: p.goal })),
checks,
};
}
/**
* Implementation Mode's phase-selection table, applied mechanically.
* 2+ workable phases in the same parallel group, consecutive -> choose (warn if all [/])
* a single [/] -> ask-resume · a single [ ] -> auto-start · nothing workable -> none
*/
function nextPhase(phases, groups, haveChecklist) {
if (!haveChecklist) return { action: "none", reason: "no Phase Checklist in overview.md" };
const ordered = phases.filter((p) => p.checklist);
const isDone = (p) => p.checklist === "complete" || p.checklist === "assumed";
const workable = ordered.filter((p) => p.checklist === "pending" || p.checklist === "in-progress");
if (!workable.length) {
return { action: "none", reason: ordered.length && ordered.every(isDone) ? "every phase is complete" : "no [ ] or [/] phase in the Phase Checklist" };
}
const first = workable[0];
const brief = (p) => ({ number: p.number, name: p.name, state: p.checklist, tasks: p.tasks ? p.tasks.total : null });
// A blocked [!] phase ahead of the pick is skipped, but never silently.
const skipped = ordered.slice(0, ordered.indexOf(first)).filter((p) => !isDone(p)).map(brief);
const note = skipped.length ? { skipped, warning: `skipping ${skipped.map((p) => `Phase ${p.number} [${p.state}]`).join(", ")} ahead of it` } : {};
const group = groups.find((g) => g.phases.includes(first.number));
if (group) {
// Consecutive same-group incomplete phases, in checklist order, starting at the first workable one.
const run = [];
for (const p of ordered.slice(ordered.indexOf(first))) {
if (!group.phases.includes(p.number)) break;
if (isDone(p)) continue;
if (p.checklist === "pending" || p.checklist === "in-progress") run.push(p);
else break;
}
if (run.length >= 2) {
const allStarted = run.every((p) => p.checklist === "in-progress");
const warnings = [
...(allStarted ? ["every option is already [/]: another agent may be working on it, so picking one risks duplicated work"] : []),
...(note.warning ? [note.warning] : []),
];
return {
action: "choose",
group: group.id,
options: run.map(brief),
...(note.skipped ? { skipped: note.skipped } : {}),
...(warnings.length ? { warning: warnings.join("; ") } : {}),
};
}
}
return { action: first.checklist === "in-progress" ? "ask-resume" : "auto-start", phase: brief(first), ...note };
}
/* --------------------------------------------------------------- commands */
async function cmdList(args) {
const root = path.resolve(args.root || ".");
const { scanProject } = await consoleLib();
const scan = scanProject(root);
const specs = scan.specs.map((s) => {
const dir = path.join(root, s.dir);
let names = [];
try {
names = fs.readdirSync(dir);
} catch {}
return {
dir: s.dir,
name: s.name,
state: s.state,
detail: s.detail,
touched: s.touched ? new Date(s.touched).toISOString() : null,
planDrafts: planDrafts(dir),
overview: names.includes("overview.md"),
phaseFiles: names.filter((n) => /^phase-\d+\b.*\.md$/i.test(n)).length,
pathfinder: isDir(path.join(dir, "pathfinder")),
};
});
let completed = [];
try {
completed = fs.readdirSync(path.join(root, "specs--completed")).filter((n) => isDir(path.join(root, "specs--completed", n))).sort();
} catch {}
out({
ok: true,
root,
hasAgents: scan.hasAgents,
specsDir: isDir(path.join(root, "specs")),
specs,
completed,
...(specs.length ? {} : { note: "No active specs under specs/." }),
});
}
async function cmdStatus(args) {
const root = path.resolve(args.root || ".");
out(specStatus(resolveSpec(root, args._[1], { allowArchived: true })));
}
function countVerificationAdded(dir) {
let n = 0;
for (const name of fs.readdirSync(dir)) {
if (!/\.md$/i.test(name) || /^PLAN-/i.test(name)) continue;
n += ((readText(path.join(dir, name)) || "").match(/ comments are a cross-check only.
if (!("verification_items_added" in sets)) fail(EXIT.USAGE, "missing-set", "document needs --set verification_items_added=N (the Added column total of your Verification Summary).", `The spec has ${countVerificationAdded(spec.dir)} comment(s), as a cross-check.`);
metrics = {
step: "document",
total_tasks: st.totals.total,
tasks_per_phase: withTasks.map((p) => p.tasks.total),
phase_count: st.phases.length,
parallel_groups_identified: st.parallelGroups.length,
...sets,
};
hint = { verificationCommentsFound: countVerificationAdded(spec.dir) };
} else {
const missing = ["verification_failures_found", "documentation_updates_needed"].filter((k) => !(k in sets));
if (missing.length) fail(EXIT.USAGE, "missing-set", `finalize needs ${missing.map((k) => `--set ${k}=N`).join(" and ")}.`, "Those two counts are your judgment from Steps 2 and 4.");
metrics = {
step: "finalize",
completion_rate_at_audit: st.completion === null ? 0 : Number(st.completion.toFixed(2)),
tasks_completed: st.totals.completed,
tasks_total: st.totals.total,
...sets,
};
}
out({ ok: true, spec: spec.rel, metrics, comment: ``, ...(hint || {}), checks: st.checks.filter((c) => c.level === "error") });
}
// The house style of every METRICS_JSON comment: {"key": value, "list": [1, 2]}.
function spacedJson(obj) {
const v = (x) => (Array.isArray(x) ? `[${x.map(v).join(", ")}]` : x && typeof x === "object" ? spacedJson(x) : JSON.stringify(x));
return `{${Object.entries(obj).map(([k, x]) => `${JSON.stringify(k)}: ${v(x)}`).join(", ")}}`;
}
const TO = { open: " ", "in-progress": "/", done: "x" };
async function cmdMark(args) {
const root = path.resolve(args.root || ".");
const spec = resolveSpec(root, args._[1]);
const number = Number(args.phase);
if (!Number.isInteger(number) || number < 0) fail(EXIT.USAGE, "bad-phase", "--phase needs a phase number.", "Example: --phase 2");
if (!(args.to in TO)) fail(EXIT.USAGE, "bad-to", "--to must be open, in-progress or done.", "open = [ ], in-progress = [/], done = [x]");
const overviewPath = path.join(spec.dir, "overview.md");
const overview = readText(overviewPath);
if (overview === null) fail(EXIT.NOT_FOUND, "no-overview", `${spec.rel} has no overview.md.`, "Run /plan2code-2-document first.");
const checklist = parseChecklist(overview);
const rows = checklist.phases.filter((p) => p.number === number);
const row = rows[0];
if (!row) fail(EXIT.NOT_FOUND, "no-row", `overview.md's Phase Checklist has no row for Phase ${number}.`, "Run `specs.mjs status` to see the phases it lists.");
if (rows.length > 1) fail(EXIT.REFUSED, "duplicate-row", `Phase ${number} has ${rows.length} rows in the Phase Checklist (lines ${rows.map((r) => r.line).join(", ")}); marking one would be a guess.`, "Remove the duplicate row, then rerun.");
const target = TO[args.to];
if (row.marker === "/" && target === " ") {
fail(EXIT.REFUSED, "no-reset", `Phase ${number} is [/]; started work is never reset to [ ].`, "Leave it [/] (a later session resumes it), or mark it done once approved.");
}
const changes = [];
const lines = overview.split(/\r?\n/);
const idx = row.line - 1;
const next = lines[idx].replace(/\[(.)\]/, `[${target}]`);
if (next !== lines[idx]) {
lines[idx] = next;
changes.push({ file: `${spec.rel}/overview.md`, line: row.line, from: `[${row.marker}]`, to: `[${target}]` });
}
// The phase file's Status line follows: done -> Complete; re-opening a Complete
// phase -> In Progress (revise-plan), so the two files never disagree.
let phaseText = null;
let phasePath = null;
let unfinished = [];
const warnings = [];
const file = phaseFiles(spec.dir).get(number);
if (file) {
phasePath = path.join(spec.dir, file);
const text = readText(phasePath) || "";
const parsed = parsePhaseFile(phasePath, number);
unfinished = parsed.tasks.filter((t) => ["pending", "in-progress", "unknown"].includes(t.state)).map((t) => t.id);
const status = statusOf(text);
const want = target === "x" ? "Complete" : target === " " && status && /^complete$/i.test(status) ? "In Progress" : null;
if (status && want && status !== want) {
phaseText = text.replace(STATUS_RE, (_, before, _value, after) => before + want + after);
changes.push({ file: `${spec.rel}/${file}`, field: "Status", from: status, to: want });
}
// done and open keep the Status line in step; with none to find, say so.
if (!status && target !== "/") warnings.push(`${file} has no Status line, so only the Phase Checklist checkbox changed; add a "**Status:** " line under its title.`);
}
if (!args["dry-run"]) {
if (changes.some((c) => c.file.endsWith("overview.md"))) fs.writeFileSync(overviewPath, lines.join(eol(overview)));
if (phaseText !== null) fs.writeFileSync(phasePath, phaseText);
}
const doneEarly = target === "x" && unfinished.length > 0;
if (doneEarly) warnings.unshift(`Phase ${number} was marked done with ${unfinished.length} unfinished task(s): ${unfinished.join(", ")}. Mark only a phase the user approved.`);
out({
ok: true,
spec: spec.rel,
phase: number,
name: row.name,
dryRun: !!args["dry-run"],
changed: changes.length > 0,
changes,
...(warnings.length ? { warning: warnings.join(" ") } : {}),
...(doneEarly ? { unfinished } : {}),
});
}
function listRel(dir, base = dir) {
const outList = [];
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, e.name);
if (e.isDirectory()) outList.push(...listRel(p, base));
else outList.push(rel(base, p));
}
return outList.sort();
}
async function cmdArchive(args) {
const root = path.resolve(args.root || ".");
const spec = resolveSpec(root, args._[1]);
const target = path.join(root, "specs--completed", spec.name);
if (fs.existsSync(target)) {
fail(EXIT.REFUSED, "target-exists", `specs--completed/${spec.name}/ already exists; nothing was moved.`, "Ask the user whether to merge by hand or archive under another name.");
}
const files = listRel(spec.dir);
if (!args["dry-run"]) {
fs.mkdirSync(path.dirname(target), { recursive: true });
try {
fs.renameSync(spec.dir, target);
} catch (err) {
// A rename across volumes (or a locked file on Windows) fails; copy then remove.
try {
fs.cpSync(spec.dir, target, { recursive: true, errorOnExist: true, force: false });
} catch (copyErr) {
fail(EXIT.INVALID, "archive-failed", `Could not move or copy ${spec.rel} (${err.code || err.message}; copy: ${copyErr.code || copyErr.message}).`, `Close anything holding files in ${spec.rel} open, check specs--completed/${spec.name} for a partial copy, then rerun.`);
}
try {
fs.rmSync(spec.dir, { recursive: true, force: true });
} catch (rmErr) {
fail(EXIT.INVALID, "source-not-removed", `Copied to specs--completed/${spec.name}/ but could not remove ${spec.rel} (${rmErr.code || rmErr.message}); both copies now exist.`, `Close whatever holds files in ${spec.rel} open, then delete it by hand. The archive is complete.`);
}
}
}
const sourceGone = args["dry-run"] ? null : !fs.existsSync(spec.dir);
const moved = args["dry-run"] ? null : listRel(target);
if (!args["dry-run"] && !(sourceGone && moved.length === files.length)) {
fail(
EXIT.INVALID,
"archive-unverified",
`The move of ${spec.rel} to specs--completed/${spec.name}/ did not verify: ${moved.length} of ${files.length} file(s) at the target, and ${spec.rel} ${sourceGone ? "is gone" : "still exists"}.`,
`Compare ${spec.rel} with specs--completed/${spec.name}/ and finish the move by hand; archive refuses to rerun while the target exists.`
);
}
out({
ok: true,
dryRun: !!args["dry-run"],
from: spec.rel,
to: `specs--completed/${spec.name}`,
files,
...(args["dry-run"] ? {} : { sourceRemoved: sourceGone, filesAtTarget: moved.length, archivedOn: isoDate() }),
});
}
run(USAGE, async (argv) => {
const args = parseArgs(argv, { booleans: ["dry-run"], values: ["root", "step", "phase", "to"], lists: ["set"] });
const cmd = args._[0];
const commands = { list: cmdList, status: cmdStatus, metrics: cmdMetrics, mark: cmdMark, archive: cmdArchive };
if (!commands[cmd]) fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: list, status, metrics, mark, archive. Run with --help.");
await commands[cmd](args);
});