Files
plan2code/skills/plan2code-0-pathfinder/scripts/pathfinder.mjs
T

1295 lines
63 KiB
JavaScript

#!/usr/bin/env node
// pathfinder.mjs: the mechanical half of Pathfinder's map.
//
// Pathfinder's question files are ground truth and map.md is an index rebuilt
// from them. Everything about that index has one correct answer: which marker
// each row carries, which questions are on the frontier, which are blocked or
// stranded, what NN comes next, what the Trail Footer looks like, which
// clearing checks pass, which dates fall in a brief's range. This script
// computes all of it and performs the bookkeeping writes (reconcile, claim,
// resolve, rule out), so the agent spends its attention on the decisions.
//
// It never writes an ## Answer, never decides a question, never scores
// confidence. Those stay with the agent and the human.
import fs from "node:fs";
import path from "node:path";
import { EXIT, fail, out, parseArgs, run, readText, isDir, rel, eol, isoDate, stamp, now } from "./common.mjs";
const USAGE = `
pathfinder.mjs: Pathfinder map bookkeeping. JSON on stdout (trail: --text prints the footer itself).
<map> is specs/<idea>/pathfinder, specs/<idea>, <idea>, or a path to map.md.
node pathfinder.mjs reconcile <map> [--dry-run]
Work Step 2. Files win: an ## Answer under a non-resolved State becomes
resolved; a missing Resolved: date is backfilled from Claimed: (today if
none); a claim with no answer is reset to open; every map marker is
rebuilt from the files (missing rows added, rows for deleted files and
duplicate rows dropped); **Next NN:** keeps the high-water mark. Lists
research questions to re-fire (no Research complete line). Run it at
session start or with nothing claimed.
node pathfinder.mjs frontier <map>
Read-only: the frontier (open, unclaimed, unblocked, lowest NN first),
the open claim, blocked questions with their blockers, stranded
questions (blocked by something out of scope), next NN, counts, drift.
node pathfinder.mjs claim <map> <NN> [--dry-run]
Work Step 4: State claimed + Claimed: now in the file, then the map row
[/]. Refuses a question that is not open, is blocked, or while another
claim is open.
node pathfinder.mjs resolve <map> <NN> [--dry-run]
Work Step 7, after you appended ## Answer (ending in a **Gist:** line):
State resolved + Resolved: today, the map row [x] with gist and date,
every other marker rebuilt (reports what just unblocked), Updated bumped.
node pathfinder.mjs rule-out <map> <NN> --reason "<why>" [--dry-run]
State out-of-scope (no Answer), a reason line under ## Question, the map
row [-], one line in ## Out of scope. Reports newly stranded questions.
--dry-run on a write command works everything out and writes nothing; the
JSON says dryRun and mapWritten. The read-only commands write nothing anyway.
node pathfinder.mjs trail <map> --form A|B|C [--item "<probe>" ...] [--text]
The Trail Footer, built from the files: heading, path, legend, named
legend, confidence line, then Part 2. Form B needs 1-3 --item. Form C
also returns the menu options (takeable questions) for the question tool;
pass --resolved-this-session <N> and --heavy (a contested or Locked:
yes decision) so it can recommend a question or Start fresh.
node pathfinder.mjs gate <map>
The Clearing Gate's mechanical checks and the handoff preflight: zero
[ ] [/] [!] rows, empty fog, a Gist on every resolved answer, an existing
PLAN-DRAFT to update in place, the four hard caps, the map's scores >= 18.
Lists what stays your judgment.
node pathfinder.mjs lint <map>
Standing rules: loop tokens anywhere under specs/<idea>/, checkboxes or
METRICS_JSON in question files, reserved names inside pathfinder/, the
six schema lines, NN rules, Blocked by: targets and cycles, the banner,
and metrics-scraper bait (collector patterns) in map.md, briefs and a
pathfinder-written PLAN-DRAFT.
node pathfinder.mjs brief-data <map> [--range today|this-week|full|since:<YYYY-MM-DD>|<YYYY-MM-DD>..<YYYY-MM-DD>]
Everything a brief is built from, filtered by Resolved: date, plus the
file path to write. Run reconcile first (it reports drift if you did not).
Exit: 0 ok · 2 bad arguments · 3 map / question not found · 4 a check failed
or a file cannot be parsed · 5 refused (rule broken).
`;
const BANNER = "> Pathfinder planning note - decisions, not implementation work. Archive with the spec; do not delete.";
const SCHEMA_KEYS = ["Type", "State", "Blocked by", "Claimed", "Resolved", "Locked"];
const TYPES = ["grill · HITL", "research · AFK", "sketch · HITL", "legwork · HITL", "legwork · AFK"];
const STATES = ["open", "claimed", "resolved", "out-of-scope"];
const GLYPH = { x: "●", "/": "◉", " ": "○", "!": "⊘", "-": "⊝" };
const LOOP_TOKENS = /\b(TASK_COMPLETE|PHASE_COMPLETE|ALL_TASKS_COMPLETE|IMPLEMENTATION_COMPLETE|SPEC_COMPLETE|WORK_COMPLETE)\b/;
// The metrics collector's own scrape patterns (plan2code-metrics/src/collector.ts).
const SCRAPE = [
{ name: "overall confidence with %", re: /(?:Overall|Final|Total)?\s*\**[Cc]onfidence\**[:\s*]+(\d{1,3})%/ },
{ name: "confidence table cell", re: /[|]\s*[Cc]onfidence\s*[|]\s*(\d{1,3})/ },
{ name: "bare Requirements + number", re: /[Rr]equirements?[:\s|]+(\d{1,2})/ },
{ name: "bare Feasibility + number", re: /[Ff]easibility[:\s|]+(\d{1,2})/ },
{ name: "bare Integration + number", re: /[Ii]ntegration[:\s|]+(\d{1,2})/ },
{ name: "bare Risk + number", re: /[Rr]isk[:\s|]+(\d{1,2})/ },
];
const DIMENSIONS = [
{ key: "Requirements-clarity", word: "Requirements" },
{ key: "Feasibility-technical", word: "Feasibility" },
{ key: "Integration-points", word: "Integration" },
{ key: "Risk-assessment", word: "Risk" },
];
/* ------------------------------------------------------------- locating */
function locate(root, arg) {
if (!arg) fail(EXIT.USAGE, "missing-map", "Name the map: specs/<idea>/pathfinder, specs/<idea>, or <idea>.", "Example: node pathfinder.mjs frontier specs/audit-export/pathfinder");
let p = arg.replace(/\\/g, "/").replace(/\/+$/, "");
if (/\/map\.md$/i.test(p)) p = p.replace(/\/map\.md$/i, "");
let abs = path.isAbsolute(p) ? p : p.includes("/") ? path.join(root, p) : path.join(root, "specs", p);
if (path.basename(abs) !== "pathfinder") abs = path.join(abs, "pathfinder");
const ideaDir = path.dirname(abs);
if (!isDir(ideaDir)) fail(EXIT.NOT_FOUND, "no-idea", `No idea folder at ${rel(root, ideaDir)}.`, "Check the idea name with `ls specs/` (shell, not Glob: specs/ is gitignored).");
return { root, pf: abs, ideaDir, idea: path.basename(ideaDir), mapPath: path.join(abs, "map.md"), qDir: path.join(abs, "questions"), relPf: rel(root, abs) };
}
function requireMap(loc) {
const text = readText(loc.mapPath);
if (text === null) fail(EXIT.NOT_FOUND, "no-map", `${loc.relPf}/map.md does not exist.`, "No map yet means Chart Step 0 (Intent Gate); Chart Step 5 writes map.md.");
return text;
}
/* -------------------------------------------------------------- parsing */
/**
* "## Heading" -> body text (until the next ## heading). Headings inside a
* fenced code block are content, not structure: a paper sketch in ## Evidence
* may well quote a "## Answer". The first occurrence of a heading wins.
*/
function sections(text) {
const map = new Map();
const hits = [];
let fence = null;
let offset = 0;
for (const line of text.split("\n")) {
const f = line.match(/^\s{0,3}(`{3,}|~{3,})/);
if (f) {
if (!fence) fence = f[1][0];
else if (f[1][0] === fence) fence = null;
} else if (!fence) {
const h = line.match(/^## +(.+?)\s*$/);
if (h) hits.push({ index: offset, length: line.length, name: h[1].trim() });
}
offset += line.length + 1;
}
hits.forEach((h, i) => {
const start = h.index + h.length;
const end = i + 1 < hits.length ? hits[i + 1].index : text.length;
const key = h.name.toLowerCase();
if (!map.has(key)) map.set(key, { heading: h.name, start: h.index, bodyStart: start, end, body: text.slice(start, end) });
});
return map;
}
function stripComments(s) {
return s.replace(/<!--[\s\S]*?-->/g, "");
}
function hasContent(sec) {
return !!sec && stripComments(sec.body).trim().length > 0;
}
function parseGist(answerBody) {
const lines = answerBody.split(/\r?\n/);
const i = lines.findIndex((l) => /^\s*\*\*Gist:\*\*/.test(l));
if (i === -1) return null;
const parts = [lines[i].replace(/^\s*\*\*Gist:\*\*\s*/, "")];
for (let j = i + 1; j < lines.length && lines[j].trim() && !/^\s*(\*\*|#|[-*] )/.test(lines[j]); j++) parts.push(lines[j].trim());
return parts.join(" ").replace(/\s+/g, " ").trim() || null;
}
// "02, 04" -> ["02", "04"]. Only the leading list of numbers counts, so a
// trailing note ("02 (needs the Phase 2 answer)") adds nothing; duplicates drop.
function parseBlockers(v) {
if (!v || /^none$/i.test(v.trim())) return [];
const lead = (v.match(/^[\s\d,]+/) || [""])[0];
return [...new Set((lead.match(/\d+/g) || []).map((n) => n.padStart(2, "0")))];
}
function parseQuestion(file, text) {
// NN is zero-padded wherever it is compared (findQ, Blocked by:), so a
// "1-export.md" is question 01, not a question nobody can name (lint flags it).
const rawNN = path.basename(file).match(/^(\d+)-/)[1];
const nn = rawNN.padStart(2, "0");
const firstSection = text.search(/^## /m);
const header = firstSection === -1 ? text : text.slice(0, firstSection);
const fields = {};
for (const line of header.split(/\r?\n/)) {
const m = line.match(/^(Type|State|Blocked by|Claimed|Resolved|Locked):\s*(.*?)\s*$/);
if (m && !(m[1] in fields)) fields[m[1]] = m[2];
}
const secs = sections(text);
const answer = secs.get("answer");
const evidence = secs.get("evidence");
const question = secs.get("question");
const name = ((text.match(/^# +(.+?)\s*$/m) || [])[1] || path.basename(file, ".md")).trim();
const type = fields.Type || null;
return {
nn,
rawNN,
file: path.basename(file),
name,
fields,
type,
kind: type ? type.split("·")[0].trim().toLowerCase() : null,
state: (fields.State || "").toLowerCase() || null,
blockedBy: parseBlockers(fields["Blocked by"]),
claimed: fields.Claimed && !/^none$/i.test(fields.Claimed) ? fields.Claimed : null,
resolved: fields.Resolved && !/^none$/i.test(fields.Resolved) ? fields.Resolved : null,
locked: /^yes$/i.test(fields.Locked || ""),
hasAnswer: hasContent(answer),
answerBody: answer ? answer.body : "",
gist: answer ? parseGist(answer.body) : null,
// Consequences under any of the names the playbooks use: a grill's
// "Consequences", a research answer's "What this implies", or a stated
// "breaks if reversed" for a locked decision.
hasConsequences: answer ? /\*\*(Consequences|What this implies)\b|^#{2,6}\s*(Consequences|What this implies)\b|^\s*Consequences\s*[:—-]|\bif (this is |it is )?reversed\b|breaks if reversed/im.test(answer.body) : false,
hasEvidence: hasContent(evidence),
researchComplete: evidence ? (evidence.body.match(/\*\*Research complete:\*\*\s*(\d{4}-\d{2}-\d{2})/) || [])[1] || null : null,
questionText: question ? stripComments(question.body).trim() : "",
banner: text.trimStart().startsWith(BANNER),
};
}
function loadQuestions(loc) {
if (!isDir(loc.qDir)) return [];
return fs
.readdirSync(loc.qDir)
.filter((n) => /^\d+-.*\.md$/i.test(n))
.sort((a, b) => parseInt(a, 10) - parseInt(b, 10) || a.localeCompare(b))
.map((n) => {
const full = path.join(loc.qDir, n);
return { ...parseQuestion(full, readText(full) || ""), path: full };
});
}
// The name is non-greedy and anchored on the link, so a name with a "]" in it
// ("Retention [legal] hold") still parses back to the row rowFor wrote.
const ROW_RE = /^\s*[-*] \[(.)\]\s*\[(.+?)\]\(\.?\/?questions\/([^)\s]+)\)(.*)$/;
const ROW_START = /^\s*[-*] \[.\]/;
const CONTINUATION = /^\s{2,}\S/;
const LINK_DONE = /\]\(\.?\/?questions\/[^)\s]*\)/;
// An indented line that opens its own item: an author's sub-bullet or note,
// never a wrapped piece of the row.
const OWN_ITEM = /^\s*([-*+] |\d+[.)] |>|<!--)/;
/**
* Checklist rows as blocks: the row line plus its wrapped, indented
* continuation lines (a long name or gist wraps, sometimes inside the link),
* then any indented lines the author hung under it (`extra`: sub-bullets,
* notes), which belong to the row but are never regenerated. Once the link is
* finished, an indented line that opens its own item starts `extra`; so does
* everything after it. The row part is matched as one joined line.
* Returns [{ start, lines, rowLines, extra, m }]; `lines` is the whole block.
*/
function rowBlocks(lines, from, to) {
const blocks = [];
for (let i = from; i < to; i++) {
if (!ROW_START.test(lines[i])) continue;
const start = i;
const rowLines = [lines[i]];
const extra = [];
const joined = () => rowLines.map((l, k) => (k ? l.trim() : l)).join(" ");
while (i + 1 < to && CONTINUATION.test(lines[i + 1]) && !ROW_START.test(lines[i + 1])) {
const next = lines[++i];
if (!extra.length && (!LINK_DONE.test(joined()) || !OWN_ITEM.test(next))) rowLines.push(next);
else extra.push(next);
}
blocks.push({ start, lines: [...rowLines, ...extra], rowLines, extra, m: joined().match(ROW_RE) });
}
return blocks;
}
function checklistRange(lines) {
const h = lines.findIndex((l) => /^## +Question Checklist\s*$/i.test(l));
if (h === -1) return null;
let end = lines.findIndex((l, i) => i > h && /^## /.test(l));
if (end === -1) end = lines.length;
return { head: h, end };
}
function parseMap(text) {
const secs = sections(text);
const field = (k) => ((text.match(new RegExp(`^\\*\\*${k}:\\*\\*\\s*(.+?)\\s*$`, "m")) || [])[1] || null);
const status = field("Status");
const confLine = field("Confidence");
let scores = null;
if (confLine) {
scores = {};
for (const d of DIMENSIONS) {
const m = confLine.match(new RegExp(`${d.key}\\s+(\\d{1,2})\\s*/\\s*25`, "i"));
scores[d.word] = m ? Number(m[1]) : null;
}
if (Object.values(scores).every((v) => v === null)) scores = null;
}
const bullets = (sec) =>
sec
? stripComments(sec.body)
.split(/\r?\n(?=\s*[-*] )/)
.map((b) => b.trim())
.filter((b) => /^[-*] /.test(b))
.map((b) => b.replace(/^[-*] /, "").replace(/\s*\r?\n\s*/g, " ").trim())
: [];
const checklist = secs.get("question checklist");
const allLines = text.split(/\r?\n/);
const range = checklistRange(allLines);
const rows = range
? rowBlocks(allLines, range.head + 1, range.end)
.filter((b) => b.m)
.map(({ m }) => ({ marker: m[1], name: m[2].replace(/\s+/g, " ").trim(), file: m[3], rest: m[4] }))
: [];
const groundRules = bullets(secs.get("ground rules"));
// The canonical line is "`AGENTS.md` is absent." (chart.md); the skill's own
// gate wording ("No `AGENTS.md`.") and plain variants count too.
const agentsAbsent = groundRules.some((b) => /AGENTS\.md/.test(b) && (/\b(absent|missing|not present|does not exist|without)\b/i.test(b) || /\bno\s+`?AGENTS\.md\b/i.test(b)) && !/\bexists and governs\b/i.test(b));
return {
status: status ? status.replace(/\*+/g, "").trim() : null,
updated: field("Updated"),
plan: field("Plan"),
confidenceLine: confLine,
scores,
destination: secs.get("destination") ? stripComments(secs.get("destination").body).trim() : null,
groundRules,
agentsAbsent,
fog: bullets(secs.get("not yet specified")),
outOfScope: bullets(secs.get("out of scope")),
rows,
hasChecklist: !!checklist,
};
}
/* ------------------------------------------------------------ deriving */
/** The marker each question's map row should carry, from its file alone. */
function markerFor(q, byNN) {
if (q.state === "resolved") return "x";
if (q.state === "claimed") return "/";
if (q.state === "out-of-scope") return "-";
const blocked = q.blockedBy.some((b) => !byNN.get(b) || byNN.get(b).state !== "resolved");
return blocked ? "!" : " ";
}
function derive(questions) {
const byNN = new Map(questions.map((q) => [q.nn, q]));
for (const q of questions) q.marker = markerFor(q, byNN);
return byNN;
}
function openBlockers(q, byNN) {
return q.blockedBy.filter((b) => !byNN.get(b) || byNN.get(b).state !== "resolved");
}
/** A fresh row in the map template's format: gist and date on [x], the blocker on [!]. */
function rowFor(q, byNN, nameOverride) {
const name = nameOverride || q.name;
const link = `- [${q.marker}] [${name}](./questions/${q.file})`;
if (q.marker === "x") {
const date = q.resolved ? ` *(${q.resolved})*` : "";
return q.gist ? `${link} — ${q.gist}${date}` : `${link}${date}`;
}
if (q.marker === "!") return `${link} — Blocked by ${openBlockers(q, byNN).join(", ")}`;
if (q.marker === "-") return `${link} — out of scope, see below`;
return link;
}
/**
* An existing row (its first line plus any wrapped continuation lines) with the
* marker the files call for. The row's own wording is kept: only the marker
* changes, plus the suffix a marker change makes wrong. A row that turns [x]
* without a gist, or any row in `regenerate`, is written fresh instead. Lines
* the author hung under the row (`extra`) follow it either way.
*/
function updateRow({ lines: block, rowLines, extra, m }, q, byNN, regenerate) {
const name = m ? m[2].replace(/\s+/g, " ").trim() : null;
if (regenerate || !m) return [rowFor(q, byNN, name), ...extra];
const oldMarker = m[1];
if (oldMarker === q.marker) return block;
const hasSuffix = /^\s*—/.test(m[4]);
if (q.marker === "x" && !(oldMarker === "x" && hasSuffix)) return [rowFor(q, byNN, name), ...extra];
if (q.marker === "!" || q.marker === "-" || oldMarker === "!" || oldMarker === "-" || oldMarker === "x") {
// The tail ("— Blocked by", "— out of scope", a resolved row's gist and
// date) belongs to the old marker.
return [rowFor(q, byNN, name), ...extra];
}
return [rowLines[0].replace(/\[(.)\]/, `[${q.marker}]`), ...rowLines.slice(1), ...extra];
}
/**
* Rebuild ## Question Checklist's markers from the files. Rows keep their text
* and their place; missing rows are added after the last row, rows whose file
* is gone are dropped. `regenerate` names NNs whose row is rewritten from the
* file (resolve).
* Returns { text, changes }.
*/
function rebuildChecklist(mapText, questions, byNN, regenerate = new Set()) {
const nl = eol(mapText);
const parsed = parseMap(mapText);
const changes = [];
const before = new Map(parsed.rows.map((r) => [r.file, r]));
for (const q of questions) {
const old = before.get(q.file);
if (!old) changes.push({ change: "row-added", nn: q.nn, name: q.name, marker: `[${q.marker}]` });
else if (old.marker !== q.marker) changes.push({ change: "marker", nn: q.nn, name: old.name, from: `[${old.marker}]`, to: `[${q.marker}]` });
}
for (const r of parsed.rows) if (!questions.some((q) => q.file === r.file)) changes.push({ change: "row-dropped", file: r.file, name: r.name, why: "no such question file" });
const lines = mapText.split(/\r?\n/);
const range = checklistRange(lines);
const byFile = new Map(questions.map((q) => [q.file, q]));
if (!range) {
// No checklist section: add one before ## Not yet specified (or at the end).
const rows = questions.map((q) => rowFor(q, byNN));
let at = lines.findIndex((l) => /^## +Not yet specified\s*$/i.test(l));
if (at === -1) at = lines.length;
lines.splice(at, 0, "## Question Checklist", "", ...rows, "");
changes.push({ change: "section-added", section: "Question Checklist" });
return { text: lines.join(nl), changes };
}
// Rebuild in place: every existing row block is updated where it stands, so
// grouping lines and comments between rows stay where the author put them.
// Rows whose file is gone are dropped; rows for new files go after the last row.
const blocks = rowBlocks(lines, range.head + 1, range.end);
const seen = new Set();
const out = [];
let i = range.head + 1;
let lastRowEnd = -1;
for (const b of blocks) {
while (i < b.start) out.push(lines[i++]);
i = b.start + b.lines.length;
if (!b.m) {
// A checkbox row with no ./questions/ link is not ours to judge: keep it, say so.
out.push(...b.lines);
changes.push({ change: "row-kept-unparsed", line: b.start + 1, text: b.lines[0].trim().slice(0, 120), why: "no ./questions/NN-*.md link; fix it by hand" });
} else if (byFile.has(b.m[3]) && !seen.has(b.m[3])) {
seen.add(b.m[3]);
const q = byFile.get(b.m[3]);
out.push(...updateRow(b, q, byNN, regenerate.has(q.nn)));
} else if (byFile.has(b.m[3])) {
// A second row for a file already listed: the first one stands.
changes.push({ change: "row-dropped", file: b.m[3], name: b.m[2].replace(/\s+/g, " ").trim(), why: "duplicate row" });
}
lastRowEnd = out.length;
}
const fresh = questions.filter((q) => !seen.has(q.file)).map((q) => rowFor(q, byNN));
if (lastRowEnd === -1) {
// No rows yet: after the section's leading blank lines and comment block.
let k = i;
while (k < range.end && !lines[k].trim()) k++;
if (k < range.end && lines[k].trim().startsWith("<!--")) {
while (k < range.end && !lines[k].includes("-->")) k++;
k++;
}
while (i < k) out.push(lines[i++]);
while (out.length && !out[out.length - 1].trim()) out.pop();
out.push("", ...fresh);
while (i < range.end && !lines[i].trim()) i++;
out.push("");
} else {
out.splice(lastRowEnd, 0, ...fresh);
}
while (i < range.end) out.push(lines[i++]);
lines.splice(range.head + 1, range.end - range.head - 1, ...out);
return { text: lines.join(nl), changes };
}
/** Set (or insert, in schema order) one Key: value line in a question file's header. */
function setField(text, key, value) {
const nl = eol(text);
const lines = text.split(/\r?\n/);
const limit = (() => {
const i = lines.findIndex((l) => /^## /.test(l));
return i === -1 ? lines.length : i;
})();
const keyRe = (k) => new RegExp(`^${k}:\\s*`);
const at = lines.slice(0, limit).findIndex((l) => keyRe(key).test(l));
if (at !== -1) {
lines[at] = `${key}: ${value}`;
return lines.join(nl);
}
// Insert after the nearest earlier schema key present, else before the nearest later one.
const order = SCHEMA_KEYS.indexOf(key);
for (let k = order - 1; k >= 0; k--) {
const i = lines.slice(0, limit).findIndex((l) => keyRe(SCHEMA_KEYS[k]).test(l));
if (i !== -1) {
lines.splice(i + 1, 0, `${key}: ${value}`);
return lines.join(nl);
}
}
for (let k = order + 1; k < SCHEMA_KEYS.length; k++) {
const i = lines.slice(0, limit).findIndex((l) => keyRe(SCHEMA_KEYS[k]).test(l));
if (i !== -1) {
lines.splice(i, 0, `${key}: ${value}`);
return lines.join(nl);
}
}
fail(EXIT.INVALID, "no-schema", `Cannot place ${key}: in a file with no schema lines.`, "Add the six Key: value lines under the H1 (see questions.md).");
}
/**
* Set (or insert) one **Key:** value line in the map's header block. Status
* goes first; a new key goes right after Status, or with `last` at the end of
* the block of **Key:** lines that Status opens.
*/
function setMapField(text, key, value, { last = false } = {}) {
const re = new RegExp(`^\\*\\*${key}:\\*\\*.*$`, "m");
if (re.test(text)) return text.replace(re, `**${key}:** ${value}`);
const nl = eol(text);
const lines = text.split(/\r?\n/);
const statusAt = lines.findIndex((l) => /^\*\*Status:\*\*/.test(l));
if (key !== "Status" && statusAt !== -1) {
let at = statusAt + 1;
if (last) while (at < lines.length && /^\*\*[^*]+:\*\*/.test(lines[at])) at++;
lines.splice(at, 0, `**${key}:** ${value}`);
return lines.join(nl);
}
const updatedAt = lines.findIndex((l) => /^\*\*Updated:\*\*/.test(l));
if (updatedAt !== -1) {
lines.splice(updatedAt, 0, `**${key}:** ${value}`);
return lines.join(nl);
}
const h1 = lines.findIndex((l) => /^# /.test(l));
let at = h1 === -1 ? 0 : h1 + 1;
while (at < lines.length && (lines[at].trim() === "" || /^\*[^*].*\*$/.test(lines[at].trim()))) at++;
lines.splice(at, 0, `**${key}:** ${value}`, "");
return lines.join(nl);
}
function writeFile(file, text, dry) {
if (!dry) fs.writeFileSync(file, text);
}
/* -------------------------------------------------------------- frontier */
function frontierOf(questions, byNN) {
const open = questions.filter((q) => q.state === "open");
const isUnblocked = (q) => q.blockedBy.every((b) => byNN.get(b) && byNN.get(b).state === "resolved");
// State: open means unclaimed (reconcile clears a stray Claimed: date on one).
const frontier = open.filter(isUnblocked).map((q) => ({ nn: q.nn, name: q.name, type: q.type, file: q.file, ...(q.blockedBy.length ? { unblockedBy: q.blockedBy.map((b) => byNN.get(b).name) } : {}) }));
const blocked = open
.filter((q) => !isUnblocked(q))
.map((q) => ({
nn: q.nn,
name: q.name,
blockedBy: q.blockedBy.map((b) => ({ nn: b, name: byNN.get(b) ? byNN.get(b).name : null, state: byNN.get(b) ? byNN.get(b).state : "missing" })).filter((b) => b.state !== "resolved"),
}));
const stranded = blocked.filter((q) => q.blockedBy.some((b) => b.state === "out-of-scope" || b.state === "missing"));
const claimed = questions.filter((q) => q.state === "claimed").map((q) => ({ nn: q.nn, name: q.name, claimed: q.claimed, hasAnswer: q.hasAnswer }));
return { frontier, blocked, stranded, claimed };
}
function nextNN(loc, questions) {
const nums = questions.map((q) => parseInt(q.nn, 10));
// The directory listing (any NN-*.md, even unparseable ones), plus every NN
// still referenced by a Blocked by: line or a link in map.md or any question
// file, plus the map's **Next NN:** high-water mark: a deleted file's number
// is never handed out again, so no link or blocker can rot.
if (isDir(loc.qDir)) {
for (const n of fs.readdirSync(loc.qDir)) {
if (!/^\d+-/.test(n)) continue;
nums.push(parseInt(n, 10));
if (/\.md$/i.test(n)) for (const m of (readText(path.join(loc.qDir, n)) || "").matchAll(/questions\/(\d+)-/g)) nums.push(parseInt(m[1], 10));
}
}
for (const q of questions) for (const b of q.blockedBy) nums.push(parseInt(b, 10));
const mapText = readText(loc.mapPath) || "";
for (const m of mapText.matchAll(/questions\/(\d+)-/g)) nums.push(parseInt(m[1], 10));
const max = nums.length ? Math.max(...nums) : -1;
return String(Math.max(max + 1, highWater(mapText))).padStart(2, "0");
}
/** The map's **Next NN:** line as a number (0 when absent or unreadable). */
function highWater(mapText) {
const m = mapText.match(/^\*\*Next NN:\*\*\s*(\d+)\s*$/m);
return m ? parseInt(m[1], 10) : 0;
}
/**
* Persist the high-water mark: **Next NN:** set to `next` (computed before the
* map is rebuilt, so a row about to be dropped still counts). It only rises.
* Returns { text, change } where change is null when the line already says so.
*/
function keepNextNN(mapText, next) {
const field = (mapText.match(/^\*\*Next NN:\*\*\s*(.*?)\s*$/m) || [])[1];
if (field === next) return { text: mapText, change: null };
return { text: setMapField(mapText, "Next NN", next, { last: true }), change: { change: "next-nn", from: field ?? null, to: next } };
}
function counts(questions, map) {
const total = questions.filter((q) => q.state !== "out-of-scope").length;
const resolved = questions.filter((q) => q.state === "resolved").length;
return { resolved, total, outOfScope: questions.filter((q) => q.state === "out-of-scope").length, fog: map ? map.fog.length : 0 };
}
function drift(questions, map) {
const rows = new Map(map.rows.map((r) => [r.file, r.marker]));
const d = [];
const seen = new Map();
for (const r of map.rows) seen.set(r.file, (seen.get(r.file) || 0) + 1);
for (const [file, n] of seen) if (n > 1) d.push(`map row ${file} appears ${n} times`);
for (const q of questions) {
if (!rows.has(q.file)) d.push(`${q.file} has no map row`);
else if (rows.get(q.file) !== q.marker) d.push(`${q.file}: map shows [${rows.get(q.file)}], file says [${q.marker}]`);
}
for (const r of map.rows) if (!questions.some((q) => q.file === r.file)) d.push(`map row ${r.file} has no question file`);
return d;
}
/* ----------------------------------------------------------- commands */
async function cmdReconcile(loc, args) {
const dry = !!args["dry-run"];
let mapText = requireMap(loc);
const repairs = [];
const today = isoDate();
const files = isDir(loc.qDir)
? fs.readdirSync(loc.qDir).filter((n) => /^\d+-.*\.md$/i.test(n)).sort((a, b) => parseInt(a, 10) - parseInt(b, 10) || a.localeCompare(b))
: [];
// Work out every repair in memory first; nothing is written until all files
// are known to be repairable, so a bad file can never leave the map half done.
const planned = [];
const findings = [];
for (const name of files) {
const full = path.join(loc.qDir, name);
const before = readText(full) || "";
let text = before;
const q = parseQuestion(full, text);
const local = [];
try {
if (q.hasAnswer && q.state !== "resolved" && q.state !== "out-of-scope") {
text = setField(text, "State", "resolved");
local.push({ nn: q.nn, name: q.name, repair: "state-resolved", detail: `has an ## Answer but State was ${q.state || "missing"}` });
q.state = "resolved";
}
if (q.state === "resolved" && !q.resolved) {
const date = q.claimed ? q.claimed.slice(0, 10) : today;
text = setField(text, "Resolved", date);
local.push({ nn: q.nn, name: q.name, repair: "resolved-backfilled", detail: `Resolved: ${date} (from ${q.claimed ? "Claimed:" : "today"})` });
}
if (q.state === "claimed" && !q.hasAnswer) {
text = setField(setField(text, "State", "open"), "Claimed", "none");
local.push({ nn: q.nn, name: q.name, repair: "stale-claim-reset", detail: `claimed ${q.claimed || "(no date)"} with no answer: a crashed session; reset to open` });
} else if (q.state === "open" && q.claimed) {
// An open question carrying a claim date is half-claimed: neither on
// the frontier nor held. Open wins.
text = setField(text, "Claimed", "none");
local.push({ nn: q.nn, name: q.name, repair: "stray-claim-cleared", detail: `State: open but Claimed: ${q.claimed}; cleared the date` });
}
} catch (err) {
if (!err || !err.exit) throw err;
findings.push({ nn: q.nn, file: name, finding: "unrepairable", detail: `${err.message} Left untouched.` });
// Still a question file: it keeps its map row (claim and resolve see it
// too), with its text as it stands.
planned.push({ full, before, text: before });
continue;
}
if (q.state === "out-of-scope" && q.hasAnswer) {
// A scope boundary is not a decision: an Answer under out-of-scope is not
// promoted to resolved. Say so; the human decides which one is wrong.
findings.push({ nn: q.nn, file: name, finding: "out-of-scope-with-answer", detail: "State: out-of-scope but it has an ## Answer: either the ruling or the answer is wrong; ask the human" });
}
repairs.push(...local);
planned.push({ full, before, text });
}
if (!dry) for (const p of planned) if (p.text !== p.before) fs.writeFileSync(p.full, p.text);
const questions = planned.map((p) => ({ ...parseQuestion(p.full, p.text), path: p.full }));
const byNN = derive(questions);
// Before the rebuild drops any row: a deleted file's link still counts.
const next = nextNN(loc, questions);
const parsedMap = parseMap(mapText);
const { text: rebuilt, changes } = rebuildChecklist(mapText, questions, byNN);
mapText = rebuilt;
let statusSet = null;
if (!parsedMap.status || !/^(Charting|Working|Cleared)$/i.test(parsedMap.status)) {
mapText = setMapField(mapText, "Status", "Working");
statusSet = "Working";
}
const kept = keepNextNN(mapText, next);
mapText = kept.text;
if (kept.change) changes.push(kept.change);
const mapChanged = mapText !== readText(loc.mapPath);
writeFile(loc.mapPath, mapText, dry);
const refire = questions
.filter((q) => q.kind === "research" && q.state !== "resolved" && q.state !== "out-of-scope" && !q.researchComplete)
.map((q) => ({ nn: q.nn, name: q.name, path: q.path, question: q.questionText, partialEvidence: q.hasEvidence }));
out({
ok: true,
map: `${loc.relPf}/map.md`,
dryRun: dry,
repairs,
...(findings.length ? { findings } : {}),
mapChanges: changes,
...(statusSet ? { statusSet: `**Status:** was missing or unreadable; set to ${statusSet}` } : {}),
mapWritten: mapChanged && !dry,
nextNN: next,
refire,
counts: counts(questions, parseMap(mapText)),
});
}
async function cmdFrontier(loc) {
const map = parseMap(requireMap(loc));
const questions = loadQuestions(loc);
const byNN = derive(questions);
const f = frontierOf(questions, byNN);
const c = counts(questions, map);
out({
ok: true,
map: `${loc.relPf}/map.md`,
status: map.status,
...f,
nextNN: nextNN(loc, questions),
counts: c,
nothingOpen: !questions.some((q) => q.state === "open" || q.state === "claimed"),
allBlocked: f.frontier.length === 0 && f.blocked.length > 0 && f.claimed.length === 0,
drift: drift(questions, map),
...(drift(questions, map).length ? { next: "Run reconcile: the map disagrees with the files." } : {}),
});
}
function findQ(questions, nnArg) {
if (!nnArg) fail(EXIT.USAGE, "missing-nn", "Name the question by its NN.", "Example: claim specs/x/pathfinder 03");
const nn = String(nnArg).padStart(2, "0");
const q = questions.find((x) => x.nn === nn);
if (!q) fail(EXIT.NOT_FOUND, "no-question", `No question ${nn} in questions/.`, "Run `frontier` to see the question numbers.");
return q;
}
/**
* The map rewrite every write command ends with: the high-water mark (from the
* map as it was, before its rows changed), then the file, unless a dry run.
* Returns whether the map was written.
*/
function saveMap(loc, before, mapText, next, dry) {
mapText = keepNextNN(mapText, next).text;
writeFile(loc.mapPath, mapText, dry);
return mapText !== before && !dry;
}
async function cmdClaim(loc, args) {
const dry = !!args["dry-run"];
const original = requireMap(loc);
let mapText = original;
const questions = loadQuestions(loc);
const byNN = derive(questions);
const q = findQ(questions, args._[2]);
const other = questions.find((x) => x.state === "claimed" && x.nn !== q.nn);
if (other) fail(EXIT.REFUSED, "claim-open", `${other.nn} ${other.name} is already claimed; one claim at a time.`, "Record or release that claim first (reconcile resets a claim with no answer).");
if (q.state === "claimed") {
out({ ok: true, nn: q.nn, name: q.name, already: true, claimed: q.claimed, file: rel(loc.root, q.path), dryRun: dry, mapWritten: false });
return;
}
if (q.state !== "open") fail(EXIT.REFUSED, "not-open", `${q.nn} ${q.name} is ${q.state}, not open.`, "Pick a question from the frontier.");
const blockers = q.blockedBy.filter((b) => !byNN.get(b) || byNN.get(b).state !== "resolved");
if (blockers.length) fail(EXIT.REFUSED, "blocked", `${q.nn} ${q.name} is blocked by ${blockers.join(", ")}.`, "Pick an unblocked question, or resolve its blocker first.");
const when = stamp();
const next = nextNN(loc, questions);
// The file first, then the map: both saved before any work on the question.
let text = readText(q.path);
text = setField(setField(text, "State", "claimed"), "Claimed", when);
writeFile(q.path, text, dry);
q.state = "claimed";
q.claimed = when;
derive(questions);
mapText = rebuildChecklist(mapText, questions, byNN).text;
const mapWritten = saveMap(loc, original, mapText, next, dry);
out({ ok: true, nn: q.nn, name: q.name, claimed: when, type: q.type, file: rel(loc.root, q.path), blockedBy: q.blockedBy, dryRun: dry, mapWritten });
}
async function cmdResolve(loc, args) {
const dry = !!args["dry-run"];
const original = requireMap(loc);
let mapText = original;
const questions = loadQuestions(loc);
let byNN = derive(questions);
const q = findQ(questions, args._[2]);
if (q.state === "out-of-scope") fail(EXIT.REFUSED, "out-of-scope", `${q.nn} ${q.name} is out of scope; it gets no Answer.`, "Nothing to resolve.");
if (!q.hasAnswer) fail(EXIT.INVALID, "no-answer", `${q.nn} ${q.name} has no ## Answer yet.`, "Append ## Answer (decision, rejected, consequences, **Gist:** last) first, then rerun.");
if (!q.gist) fail(EXIT.INVALID, "no-gist", `${q.nn} ${q.name}'s ## Answer has no **Gist:** line.`, "End the Answer with a one-line **Gist:**, then rerun.");
const blockedBefore = new Set(questions.filter((x) => x.marker === "!").map((x) => x.nn));
const today = isoDate();
// Re-running resolve on an already-resolved question keeps its original date.
const date = q.state === "resolved" && q.resolved ? q.resolved : today;
const next = nextNN(loc, questions);
let text = readText(q.path);
text = setField(setField(text, "State", "resolved"), "Resolved", date);
writeFile(q.path, text, dry);
q.state = "resolved";
q.resolved = date;
byNN = derive(questions);
mapText = rebuildChecklist(mapText, questions, byNN, new Set([q.nn])).text;
mapText = setMapField(mapText, "Updated", today);
const mapWritten = saveMap(loc, original, mapText, next, dry);
const unblocked = questions.filter((x) => blockedBefore.has(x.nn) && x.marker === " ").map((x) => ({ nn: x.nn, name: x.name }));
const f = frontierOf(questions, byNN);
out({ ok: true, nn: q.nn, name: q.name, resolved: q.resolved, gist: q.gist, unblocked, frontier: f.frontier, counts: counts(questions, parseMap(mapText)), dryRun: dry, mapWritten });
}
async function cmdRuleOut(loc, args) {
const dry = !!args["dry-run"];
const original = requireMap(loc);
let mapText = original;
const reason = (args.reason || "").trim();
if (!reason) fail(EXIT.USAGE, "missing-reason", "--reason is required: one line on why this sits past the destination.", 'Example: --reason "the destination names MS Teams only"');
const questions = loadQuestions(loc);
const q = findQ(questions, args._[2]);
if (q.state === "resolved") fail(EXIT.REFUSED, "resolved", `${q.nn} ${q.name} is resolved; a decision is not ruled out after the fact.`, "If the destination was redrawn, that is a fresh map.");
const next = nextNN(loc, questions);
let text = readText(q.path);
text = setField(setField(text, "State", "out-of-scope"), "Claimed", "none");
const nl = eol(text);
// One line under ## Question saying why, as its own paragraph.
if (!/^Out of scope: /m.test(text)) text = text.replace(/^## +Question[ \t]*(?:\r?\n[ \t]*)*\r?\n/m, (h) => `${h.trimEnd()}${nl}${nl}Out of scope: ${reason}${nl}${nl}`);
writeFile(q.path, text, dry);
q.state = "out-of-scope";
const byNN = derive(questions);
mapText = rebuildChecklist(mapText, questions, byNN).text;
const line = `- [${q.name}](./questions/${q.file}) — ${reason}`;
const mapNl = eol(mapText);
const lines = mapText.split(/\r?\n/);
const at = lines.findIndex((l) => /^## +Out of scope\s*$/i.test(l));
if (!lines.some((l) => l.includes(`](./questions/${q.file})`) && !/^\s*[-*] \[.\]/.test(l))) {
if (at === -1) {
lines.push("", "## Out of scope", "", line);
} else {
let end = lines.findIndex((l, i) => i > at && /^## /.test(l));
if (end === -1) end = lines.length;
let insert = end;
while (insert > at + 1 && !lines[insert - 1].trim()) insert--;
lines.splice(insert, 0, line);
}
}
mapText = lines.join(mapNl);
mapText = setMapField(mapText, "Updated", isoDate());
const mapWritten = saveMap(loc, original, mapText, next, dry);
const f = frontierOf(questions, byNN);
out({ ok: true, nn: q.nn, name: q.name, state: "out-of-scope", outOfScopeLine: line, stranded: f.stranded, dryRun: dry, mapWritten, next: f.stranded.length ? "Re-frame each stranded question's ## Question to drop the dependency, or rule it out too." : undefined });
}
/* --------------------------------------------------------------- trail */
function confidenceLine(scores) {
if (!scores) return null;
const vals = DIMENSIONS.map((d) => ({ word: d.word, v: scores[d.word] }));
if (vals.some((x) => x.v === null)) return null;
const low = vals.filter((x) => x.v < 18).map((x) => x.word);
if (low.length) return `Confidence: not yet — ${low.join(", ")} still ${low.length === 1 ? "needs" : "need"} work.`;
const border = vals.filter((x) => x.v < 20).map((x) => x.word);
if (border.length) return `Confidence: solid, but ${border.join(", ")} ${border.length === 1 ? "is" : "are"} borderline.`;
return "Confidence: solid.";
}
function wrapJoin(parts, indent = " ", width = 100) {
const lines = [];
let cur = "";
for (const p of parts) {
const next = cur ? `${cur} · ${p}` : p;
if (cur && indent.length + next.length > width) {
lines.push(indent + cur);
cur = p;
} else cur = next;
}
if (cur) lines.push(indent + cur);
return lines;
}
// Init comes first only while the ground rules record AGENTS.md absent AND it is
// still missing: one written since charting needs no init detour.
function needsInit(loc, map) {
return map.agentsAbsent && !fs.existsSync(path.join(loc.root, "AGENTS.md"));
}
function resumeCommand(loc, map) {
if (/^cleared$/i.test(map.status || "")) {
return needsInit(loc, map) ? "`/plan2code-init`, then `/plan2code-1-plan --web`" : "`/plan2code-1-plan --web`";
}
return `\`/plan2code-0-pathfinder ${loc.relPf} --web\``;
}
// What the human reads a question as: its name on the checklist row (the
// trail and the menu come from the rows), falling back to the file's H1.
function displayName(map, q) {
const row = map.rows.find((r) => r.file === q.file);
return row ? row.name : q.name;
}
function buildTrail(loc, map, questions, byNN) {
const c = counts(questions, map);
const status = map.status || "Working";
const cleared = /^cleared$/i.test(status);
const stops = questions.map((q) => q.marker);
let pathStr = "START ";
stops.forEach((m, i) => {
if (i > 0) pathStr += m === "x" || m === "/" ? "━" : "··";
pathStr += GLYPH[m] || "○";
});
const allWalked = stops.length > 0 && stops.every((m) => m === "x" || m === "-");
if (c.fog > 0) pathStr += " ····⚑";
else pathStr += stops.length === 0 ? "⚑" : allWalked ? "━⚑" : "··⚑";
if (cleared) pathStr += " arrived";
const lines = [`🧭 ${loc.idea} · ${status} · ${c.resolved}/${c.total} cleared`, ` ${pathStr}`];
if (!cleared) {
const order = [["x", "● done"], ["/", "◉ here"], [" ", "○ open"], ["!", "⊘ blocked"], ["-", "⊝ out of scope"]];
const legend = order.filter(([m]) => stops.includes(m)).map(([, t]) => t);
legend.push("⚑ destination");
if (c.fog > 0) legend.push(`~${c.fog} fog`);
lines.push(` ${legend.join(" · ")}`);
const position = new Map(questions.map((q, i) => [q.nn, i + 1]));
const named = questions.map((q, i) => {
const tag =
q.marker === "x" ? " ✔" :
q.marker === "/" ? " ◀ here" :
q.marker === "-" ? " (out of scope)" :
q.marker === "!" ? ` (blocked:${openBlockers(q, byNN).map((b) => position.get(b) || "missing").join(",")})` : "";
return `${i + 1} ${displayName(map, q)}${tag}`;
});
lines.push(...wrapJoin(named));
}
const conf = confidenceLine(map.scores);
if (conf) lines.push(` ${conf}`);
return lines;
}
async function cmdTrail(loc, args) {
const map = parseMap(requireMap(loc));
const questions = loadQuestions(loc);
const byNN = derive(questions);
const form = String(args.form || "").toUpperCase();
if (!["A", "B", "C"].includes(form)) fail(EXIT.USAGE, "bad-form", "--form must be A (session ends), B (you asked the human something) or C (the menu after a recorded decision).", "Pick by what this turn does, not by the map's status.");
const trail = buildTrail(loc, map, questions, byNN);
const cmd = resumeCommand(loc, map);
let part2;
let menu;
if (form === "A") {
part2 = ["NEXT STEP · start a new conversation and run:", cmd];
} else if (form === "B") {
const items = args.item || [];
if (!items.length) fail(EXIT.USAGE, "missing-items", "Form B names every outstanding item: pass 1-3 --item.", 'Example: --item "Q1 Duration model" --item "Q2 Contract while held"');
if (items.length > 3) fail(EXIT.REFUSED, "too-many-items", `${items.length} items; the cap is three probes per turn.`, "Hold the rest for the next batch.");
const joined = items.join(" · ");
part2 = ["WAITING ON YOU · answer here, in this conversation:", ...(joined.length > 100 ? items : [joined])];
} else {
if (/^cleared$/i.test(map.status || "")) fail(EXIT.REFUSED, "cleared", "The map is Cleared: there is no menu, the session ends (Form A).", "Use --form A.");
if (questions.some((q) => q.state === "claimed")) fail(EXIT.REFUSED, "claim-open", "A question is still claimed; Form C is only for the turn after a recorded decision, with nothing claimed.", "Record the decision (resolve), or use Form B while you are still asking.");
const f = frontierOf(questions, byNN);
// Nothing takeable means there is no menu to offer: an empty frontier is a
// stop (Work Step 4), and a stop is Form A.
if (!f.frontier.length) fail(EXIT.REFUSED, "no-frontier", "Nothing on the frontier to offer: every open question is blocked, or none is left.", "Use --form A (report the blocked chain, or go to The Clearing Gate).");
part2 = ["OR START FRESH · new conversation, paste:", cmd];
const resolvedThisSession = Number(args["resolved-this-session"] || 0);
const checkpoint = resolvedThisSession >= 3 || !!args.heavy;
const options = f.frontier.slice(0, 3).map((x) => {
const q = byNN.get(x.nn);
return { label: displayName(map, q), nn: x.nn, type: x.type, ...(x.unblockedBy ? { note: `can now be decided: ${x.unblockedBy.join(", ")} landed` } : {}) };
});
menu = {
header: "Next step",
question: checkpoint ? "Continue here, or start fresh? Everything is saved. I recommend starting fresh, to keep me sharp." : "Continue here, or start fresh? Everything is saved.",
options: [...options, { label: "Start fresh" }],
recommended: checkpoint ? "Start fresh" : options[0].label,
why: checkpoint ? (args.heavy ? "a heavy, contested or locked decision just landed" : `${resolvedThisSession} questions resolved this session`) : "lowest NN on the frontier",
...(f.frontier.length > 3 ? { more: f.frontier.slice(3).map((x) => displayName(map, byNN.get(x.nn))) } : {}),
};
}
const text = [...trail, "", ...part2].join("\n");
if (args.text) {
process.stdout.write(text + "\n");
return;
}
out({ ok: true, form, text, ...(menu ? { menu } : {}) });
}
/* ---------------------------------------------------------------- gate */
// The testing-posture answer must name types, cadence and coverage. Matched as
// keywords, case-insensitive ("run after each phase, moderate coverage" counts),
// and never inside the answer's Rejected block, where a losing option is named.
const TYPES_RE = /\b(unit|integration|end-to-end|e2e|none)\b/i;
const CADENCE_RE = /after each phase|dedicated (testing )?phase/i;
const COVERAGE_RE = /critical paths?|moderate|comprehensive/i;
const CADENCE = ["Run after each phase", "Dedicated phase only"];
const COVERAGE = ["Critical paths", "Moderate (~60-80%)", "Comprehensive (>80%)"];
function withoutRejected(body) {
return body.replace(/^\s*\*\*Rejected\b[\s\S]*?(?=^\s*\*\*(?!Rejected)[A-Z]|^#{1,6}\s|(?![\s\S]))/m, "");
}
async function cmdGate(loc) {
const map = parseMap(requireMap(loc));
const questions = loadQuestions(loc);
const byNN = derive(questions);
const checks = [];
const add = (id, pass, detail) => checks.push({ id, pass, ...(detail ? { detail } : {}) });
const d = drift(questions, map);
add("markers-match-files", d.length === 0, d.length ? `${d.length} drift(s): run reconcile first. ${d.slice(0, 5).join("; ")}` : null);
const notDone = questions.filter((q) => ["/", " ", "!"].includes(q.marker));
add("no-open-claimed-blocked", notDone.length === 0, notDone.length ? notDone.map((q) => `${q.nn} ${q.name} [${q.marker}]`).join(", ") : null);
add("fog-empty", map.fog.length === 0, map.fog.length ? `${map.fog.length} bullet(s) in ## Not yet specified` : null);
const noGist = questions.filter((q) => q.state === "resolved" && (!q.hasAnswer || !q.gist));
add("every-resolved-has-gist", noGist.length === 0, noGist.length ? noGist.map((q) => `${q.nn} ${q.name}`).join(", ") : null);
const drafts = fs.readdirSync(loc.ideaDir).filter((n) => /^PLAN-DRAFT-.*\.md$/i.test(n) && !/-prev\.md$/i.test(n));
// Hard caps: while one holds, that dimension cannot exceed 17.
const caps = [];
const testing = questions.find((q) => /testing posture/i.test(q.name));
if (!testing || testing.state !== "resolved") caps.push({ dimension: "Requirements", why: testing ? `${testing.name} is not resolved` : "no testing-posture question exists" });
else {
const a = withoutRejected(testing.answerBody);
const missing = [];
if (!TYPES_RE.test(a)) missing.push("types");
if (!CADENCE_RE.test(a)) missing.push(`cadence (${CADENCE.join(" / ")})`);
if (!COVERAGE_RE.test(a)) missing.push(`coverage (${COVERAGE.join(" / ")})`);
if (missing.length) caps.push({ dimension: "Requirements", why: `the testing-posture answer omits ${missing.join(", ")}` });
}
for (const q of questions.filter((x) => x.kind === "research" && x.state === "resolved" && !x.hasEvidence)) caps.push({ dimension: "Feasibility", why: `research ${q.nn} ${q.name} is resolved with an empty ## Evidence` });
for (const q of questions.filter((x) => x.locked && x.state === "resolved" && !x.hasConsequences)) caps.push({ dimension: "Risk", why: `Locked: yes ${q.nn} ${q.name} records no consequences` });
add("hard-caps", caps.length === 0, caps.length ? caps.map((c) => `${c.dimension} <= 17: ${c.why}`).join("; ") : null);
const scores = map.scores;
const scored = scores && DIMENSIONS.every((x) => scores[x.word] !== null);
const low = scored ? DIMENSIONS.filter((x) => scores[x.word] < 18).map((x) => `${x.word} ${scores[x.word]}`) : [];
add("scores-at-least-18", !!scored && low.length === 0, !scored ? "map.md has no complete **Confidence:** line (Requirements-clarity NN/25 · ...)" : low.length ? `below 18: ${low.join(", ")}` : null);
const mechanicalPass = checks.every((c) => c.pass);
out({
ok: true,
map: `${loc.relPf}/map.md`,
mechanicalPass,
checks,
caps,
existingPlanDraft: drafts.length ? drafts.map((n) => rel(loc.root, path.join(loc.ideaDir, n))) : null,
planDraftPath: drafts.length ? rel(loc.root, path.join(loc.ideaDir, drafts.sort().at(-1))) : `${rel(loc.root, loc.ideaDir)}/PLAN-DRAFT-${isoDate().replace(/-/g, "")}.md`,
agentsAbsent: map.agentsAbsent,
initFirst: needsInit(loc, map),
judgment: [
"Score the four dimensions against the written record (handoff.md rubric), then update the map's **Confidence:** line and rerun gate.",
"The destination is reachable with nothing left to decide: no ## Answer defers a choice to whoever implements it.",
"Integration cap: every system named in ## Destination has a resolved question touching it.",
],
});
}
/* ---------------------------------------------------------------- lint */
function walk(dir) {
const outList = [];
if (!isDir(dir)) return outList;
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
const p = path.join(dir, e.name);
if (e.isDirectory()) {
if (e.name === "node_modules" || e.name.startsWith(".")) continue;
outList.push(...walk(p));
} else outList.push(p);
}
return outList;
}
function scrapeHits(text) {
const hits = [];
for (const s of SCRAPE) {
const m = text.match(s.re);
if (m) hits.push(`${s.name}: "${m[0].trim()}"`);
}
return hits;
}
async function cmdLint(loc) {
const problems = [];
const add = (level, file, message) => problems.push({ level, file: rel(loc.root, file), message });
// Loop tokens: anywhere under specs/<idea>/ in text files.
for (const f of walk(loc.ideaDir)) {
if (!/\.(md|txt|json|ya?ml|csv)$/i.test(f)) continue;
const t = readText(f) || "";
const m = t.match(LOOP_TOKENS);
if (m) add("error", f, `contains the loop completion token ${m[0]} (the loop scans specs/ for these)`);
}
// Reserved names inside pathfinder/.
for (const f of walk(loc.pf)) {
const b = path.basename(f);
if (/^overview\.md$|^phase-\d+.*\.md$|^PLAN-DRAFT-.*\.md$|^PLAN-CONVERSATION-.*\.md$/i.test(b)) add("error", f, `${b} is a reserved name; never create it inside pathfinder/`);
if (/\.md$/i.test(b) && /METRICS_JSON/.test(readText(f) || "")) add("error", f, "contains METRICS_JSON; pathfinder is not a metered step");
}
// Question files.
const questions = loadQuestions(loc);
const byNN = new Map();
for (const q of questions) {
const t = readText(q.path) || "";
if (byNN.has(q.nn)) add("error", q.path, `NN ${q.nn} is used by ${byNN.get(q.nn).file} too; NN is never reused`);
byNN.set(q.nn, q);
if (q.rawNN.length < 2) add("error", q.path, `NN "${q.rawNN}" is not zero-padded; rename it to ${q.file.replace(/^\d+/, q.nn)}`);
if (/^\s*[-*] \[.\]/m.test(t)) add("error", q.path, "has a checkbox line; question files use plain bullets (the loop and metrics read checkboxes)");
if (!q.banner) add("warn", q.path, "does not open with the Pathfinder planning-note banner");
for (const k of SCHEMA_KEYS) {
if (k in q.fields) continue;
// Maps older than the Resolved: line get it backfilled by reconcile.
if (k === "Resolved") add("warn", q.path, "is missing the Resolved: schema line (an older map); reconcile backfills it");
else add("error", q.path, `is missing the ${k}: schema line`);
}
if (q.type && !TYPES.includes(q.type)) add("error", q.path, `Type: "${q.type}" is not one of ${TYPES.join(" | ")}`);
if (q.state && !STATES.includes(q.state)) add("error", q.path, `State: "${q.state}" is not one of ${STATES.join(" | ")}`);
if (q.fields.Locked && !/^(yes|no)$/i.test(q.fields.Locked)) add("warn", q.path, `Locked: "${q.fields.Locked}" should be yes or no`);
if (q.fields.Resolved && !/^(none|\d{4}-\d{2}-\d{2})$/i.test(q.fields.Resolved)) add("error", q.path, `Resolved: "${q.fields.Resolved}" should be none or YYYY-MM-DD`);
if (q.fields.Claimed && !/^(none|\d{4}-\d{2}-\d{2} \d{2}:\d{2})$/i.test(q.fields.Claimed)) add("warn", q.path, `Claimed: "${q.fields.Claimed}" should be none or YYYY-MM-DD HH:mm`);
if (q.state === "out-of-scope" && q.hasAnswer) add("warn", q.path, "is out of scope but has an ## Answer; a scope boundary is not a decision");
if (q.state === "resolved" && !q.gist) add("error", q.path, "is resolved but its ## Answer has no **Gist:** line");
}
const zero = questions.find((q) => q.nn === "00");
if (questions.length && !zero) add("warn", loc.qDir, "no 00-codebase-context.md; 00 always exists");
if (zero && !/^00-codebase-context\.md$/.test(zero.file)) add("error", zero.path, "NN 00 is always 00-codebase-context.md");
for (const q of questions) {
for (const b of q.blockedBy) {
if (!byNN.has(b)) add("error", q.path, `Blocked by: ${b}, which does not exist`);
if (b === q.nn) add("error", q.path, "is blocked by itself");
}
}
// Cycles in Blocked by: a three-colour depth-first search (grey = on the
// current path, black = fully explored), so each question is explored once
// however densely the questions block each other. Every back edge is a
// cycle, reported once, against the question it starts from.
const reported = new Set();
const colour = new Map();
const pathStack = [];
const visit = (nn) => {
colour.set(nn, "grey");
pathStack.push(nn);
for (const b of byNN.get(nn).blockedBy) {
if (!byNN.has(b)) continue;
if (colour.get(b) === "grey") {
const c = [...pathStack.slice(pathStack.indexOf(b)), b];
const key = [...new Set(c)].sort().join(",");
if (!reported.has(key)) {
reported.add(key);
add("error", byNN.get(b).path, `Blocked by: cycle ${c.join(" -> ")}; a cycle is one decision phrased twice (merge them or drop an edge)`);
}
} else if (!colour.has(b)) visit(b);
}
pathStack.pop();
colour.set(nn, "black");
};
for (const q of questions) if (!colour.has(q.nn)) visit(q.nn);
// Scraper bait in the files the collector or a reader treats as planning output.
const baitFiles = [loc.mapPath, ...walk(path.join(loc.pf, "briefs"))];
for (const n of fs.existsSync(loc.ideaDir) ? fs.readdirSync(loc.ideaDir) : []) {
if (!/^PLAN-DRAFT-.*\.md$/i.test(n)) continue;
const t = readText(path.join(loc.ideaDir, n)) || "";
// Only a pathfinder-written draft (no METRICS_JSON yet); Plan's Phase 7 owns the rest.
if (/plan2code-0-pathfinder/.test(t) && !/METRICS_JSON/.test(t)) baitFiles.push(path.join(loc.ideaDir, n));
}
for (const f of baitFiles) {
const t = readText(f);
if (t === null) continue;
for (const h of scrapeHits(t)) add("error", f, `metrics-scraper bait (${h}); hyphenate the dimension label or reword`);
const isBrief = /briefs[\\/]/.test(f);
if (isBrief) {
if (/%/.test(t)) add("error", f, "contains %; a brief carries no percent signs");
if (/\b\d{1,2}\s*\/\s*25\b/.test(t)) add("error", f, "contains a raw NN/25 score; a brief uses the plain-English confidence line only");
if (/^\s*[-*] \[.\]/m.test(t)) add("error", f, "has a checkbox line; no checkboxes under specs/<idea>/pathfinder/");
} else if (f === loc.mapPath) {
// The collector does not scrape map.md, but chart.md keeps it free of % so
// nothing copied out of it into a plan can carry one.
if (/%/.test(t)) add("warn", f, "contains %; the map keeps percent signs off the page (chart.md)");
} else if (/^##\s+Planning Metrics\b/m.test(t)) {
add("error", f, "has a ## Planning Metrics section; a pathfinder-written draft leaves that to /plan2code-1-plan Phase 7");
}
}
const errors = problems.filter((p) => p.level === "error").length;
const report = { checked: rel(loc.root, loc.ideaDir), errors, warnings: problems.length - errors, problems };
if (!errors) {
out({ ok: true, ...report });
return;
}
// The failure shape (error, message, next, the same line on stderr), written
// here rather than through fail(), which would drop the problems list.
const message = `lint found ${errors} error${errors === 1 ? "" : "s"}.`;
const next = "Fix each error in problems, then rerun lint.";
out({ ok: false, error: "lint-failed", message, next, ...report });
process.stderr.write(`error: ${message}\nnext: ${next}\n`);
process.exitCode = EXIT.INVALID;
}
/* ---------------------------------------------------------- brief-data */
function rangeOf(spec) {
const today = isoDate();
const d = now();
if (!spec || spec === "today") return { from: today, to: today, label: "today", covers: today };
if (spec === "full") return { from: null, to: today, label: "so far", covers: `everything to ${today}` };
if (spec === "this-week") {
const monday = new Date(d.getFullYear(), d.getMonth(), d.getDate() - ((d.getDay() + 6) % 7));
const from = isoDate(monday);
return { from, to: today, label: "this week", covers: `${from} to ${today}` };
}
const real = (s) => {
const [y, mo, da] = s.split("-").map(Number);
const dt = new Date(y, mo - 1, da);
if (dt.getFullYear() !== y || dt.getMonth() !== mo - 1 || dt.getDate() !== da) fail(EXIT.USAGE, "bad-date", `${s} is not a calendar date.`, "Use YYYY-MM-DD.");
return s;
};
let m = spec.match(/^since:(\d{4}-\d{2}-\d{2})$/);
if (m) {
real(m[1]);
if (m[1] > today) fail(EXIT.USAGE, "bad-range", `since:${m[1]} is in the future (today is ${today}).`, "Pick a date on or before today.");
return { from: m[1], to: today, label: `since ${m[1]}`, covers: `${m[1]} to ${today}` };
}
m = spec.match(/^(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})$/);
if (m) {
real(m[1]);
real(m[2]);
if (m[1] > m[2]) fail(EXIT.USAGE, "bad-range", `${m[1]} is after ${m[2]}.`, "Write the earlier date first.");
return { from: m[1], to: m[2], label: `${m[1]} to ${m[2]}`, covers: `${m[1]} to ${m[2]}` };
}
fail(EXIT.USAGE, "bad-range", `Unknown range "${spec}".`, "Use today, this-week, full, since:YYYY-MM-DD or YYYY-MM-DD..YYYY-MM-DD.");
}
function rejectedLines(answerBody) {
// The "Rejected" block of an answer, as written: the agent compresses it to one line each.
const m = answerBody.match(/\*\*Rejected\.?\*\*\.?\s*\r?\n([\s\S]*?)(?=\r?\n\s*\*\*[A-Z]|\r?\n## |$)/);
if (!m) return [];
return m[1].split(/\r?\n(?=\s*[-*] )/).map((s) => s.replace(/^\s*[-*]\s*/, "").replace(/\s*\r?\n\s*/g, " ").trim()).filter(Boolean);
}
async function cmdBriefData(loc, args) {
const map = parseMap(requireMap(loc));
const questions = loadQuestions(loc);
const byNN = derive(questions);
const range = rangeOf(args.range);
const inRange = (date) => !!date && (!range.from || date >= range.from) && date <= range.to;
const decided = questions
.filter((q) => q.state === "resolved" && inRange(q.resolved))
.map((q) => ({ name: q.name, resolved: q.resolved, gist: q.gist, rejected: rejectedLines(q.answerBody), hardToReverse: q.locked }));
const resolvedInRange = new Set(questions.filter((q) => q.state === "resolved" && inRange(q.resolved)).map((q) => q.nn));
const f = frontierOf(questions, byNN);
const ready = f.frontier.map((x) => {
const q = byNN.get(x.nn);
const landed = q.blockedBy.filter((b) => resolvedInRange.has(b)).map((b) => ({ name: byNN.get(b).name, resolved: byNN.get(b).resolved }));
return { name: x.name, ...(landed.length ? { justUnblockedBy: landed } : {}) };
});
// Briefs never show an NN: a blocker whose file is gone reads as such.
const waiting = f.blocked.map((b) => ({ name: displayName(map, byNN.get(b.nn)), waitingOn: b.blockedBy.map((x) => x.name || "a question that no longer exists") }));
const c = counts(questions, map);
const cleared = /^cleared$/i.test(map.status || "");
const file = `${loc.relPf}/briefs/brief-${isoDate().replace(/-/g, "")}.md`;
out({
ok: true,
file,
exists: fs.existsSync(path.join(loc.root, file)),
drift: drift(questions, map),
undatedResolved: questions.filter((q) => q.state === "resolved" && !q.resolved).map((q) => q.name),
title: `${loc.idea.replace(/-/g, " ").replace(/^./, (s) => s.toUpperCase())} - decisions brief`,
covers: range.covers,
decidedHeading: `Decided ${range.label}`,
progress: `${c.resolved} of ${c.total} decisions made`,
destination: map.destination,
decided,
// Link markup dropped (a brief has no links); placeholder bullets ("None yet.") skipped.
// A link text may hold one level of brackets ("Retention [legal] hold").
ruledOut: map.outOfScope.map((b) => b.replace(/\[((?:[^[\]]|\[[^\]]*\])+)\]\([^)]*\)/g, "$1")).filter((b) => !/^(none|nothing)\b[^—:]*\.?$/i.test(b.trim())),
ready,
waiting,
fog: map.fog,
confidence: confidenceLine(map.scores),
nextStep: cleared ? { plan: map.plan, command: "/plan2code-1-plan" } : { command: `/plan2code-0-pathfinder ${loc.relPf}` },
pointer: `${loc.relPf}/questions/`,
...(decided.length ? {} : { note: "No decisions were recorded in this period." }),
});
}
/* ---------------------------------------------------------------- main */
run(USAGE, async (argv) => {
const args = parseArgs(argv, {
booleans: ["dry-run", "text", "heavy"],
values: ["root", "form", "reason", "range", "resolved-this-session"],
lists: ["item"],
});
const cmd = args._[0];
const commands = {
reconcile: cmdReconcile,
frontier: cmdFrontier,
claim: cmdClaim,
resolve: cmdResolve,
"rule-out": cmdRuleOut,
trail: cmdTrail,
gate: cmdGate,
lint: cmdLint,
"brief-data": cmdBriefData,
};
if (!commands[cmd]) fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", `Commands: ${Object.keys(commands).join(", ")}. Run with --help.`);
const loc = locate(path.resolve(args.root || "."), args._[1]);
await commands[cmd](loc, args);
});