@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/plan-document.cjs

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Plan Document Module — the single parser for a `*-PLAN.md` document BODY.
+ *
+ * Owns: objective extraction, the task-block grammar (`<task>` elements, with
+ * the legacy `## Task N` heading fallback — including the optional `tracker-id`
+ * attribute, ADR-3646 Phase 1, read verbatim and never split here), planned-file
+ * extraction, and the frontmatter-derived scheduling metadata (`wave`,
+ * `depends_on`, `autonomous`, `agent_hint`, `files_modified`).
+ *
+ * WHY THIS IS A LEAF MODULE. This logic was written inline inside
+ * `cmdPhasePlanIndex` (`src/phase.cts`). Two commands in two different families
+ * now need it — `phase.plan-index` and `planning.inspect` (#2790) — so leaving
+ * it in `phase.cts` would force `planning` to depend on `phase`, and copying it
+ * would be the *Generative Fix Divergence* class `CLAUDE.md` names. A leaf owned
+ * by neither family is the seam that matches the actual usage (Conway's Law).
+ *
+ * NOT an ADR-3180 §7 derivation. §6 puts the document-parsing layer explicitly
+ * out of that epic's scope (#2143); this module answers "what does this plan
+ * document say", never "how many plans are outstanding" (that is
+ * `scanPhasePlans`, §7.5) or "is this phase complete" (`isPhaseComplete`, §7.4).
+ *
+ * BEHAVIOUR IS PRESERVED BYTE-FOR-BEHAVIOUR from the prior inline code. In
+ * particular `tasks.length` is exactly the legacy `taskCount`
+ * (`xmlTasks.length || mdTasks.length`), including its known fence-blindness —
+ * a `## Task 1` inside a fenced code block still counts, exactly as it does
+ * today. That is a characterised limit, not an endorsement: changing it would
+ * silently change `phase.plan-index`'s output for existing projects, which is a
+ * Hyrum's-Law break that belongs in its own issue rather than riding along on a
+ * read-only query addition.
+ *
+ * ADR-457 build-at-publish: source in src/plan-document.cts, compiled to
+ * gsd-core/bin/lib/plan-document.cjs (gitignored).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatterMod;
+// ─── Frozen vocabularies ──────────────────────────────────────────────────────
+/**
+ * How a task row was expressed in the document. `auto` is the ordinary
+ * executable task; `checkpoint` is a `<task type="checkpoint:*">` block, which
+ * carries an entirely different element set (`<decision>`/`<what-built>`, no
+ * `<name>`/`<files>`/`<acceptance_criteria>`). Distinguishing them is what
+ * stops a checkpoint from being reported as a malformed auto task.
+ */
+const TASK_KIND = Object.freeze({
+    AUTO: 'auto',
+    CHECKPOINT: 'checkpoint',
+});
+// ─── Task grammar ─────────────────────────────────────────────────────────────
+// The legacy counting rule, preserved verbatim from cmdPhasePlanIndex. `g` is
+// required (we count every occurrence) and these are rebuilt per call rather
+// than hoisted to module scope: a global regex carries mutable `lastIndex`
+// state, and a shared instance is a cross-call contamination bug.
+function xmlTaskOpenings(content) {
+    return [...content.matchAll(/<task(?=[\s>])[^>]*>/gi)];
+}
+function markdownTaskHeadings(content) {
+    return [...content.matchAll(/##\s*Task\s*\d+[^\n]*/gi)];
+}
+/** Extract the value of one attribute from a `<task ...>` opening tag. */
+function tagAttribute(openTag, attr) {
+    const re = new RegExp(`\\b${attr}\\s*=\\s*"([^"]*)"|\\b${attr}\\s*=\\s*'([^']*)'`, 'i');
+    const m = re.exec(openTag);
+    if (!m)
+        return null;
+    const value = (m[1] ?? m[2] ?? '').trim();
+    return value.length > 0 ? value : null;
+}
+/**
+ * Body of the first `<tag>…</tag>` inside `block`, or null. Non-greedy and
+ * case-insensitive; a tag that is opened but never closed yields null rather
+ * than swallowing the rest of the document.
+ */
+function elementBody(block, tag) {
+    const re = new RegExp(`<${tag}\\s*>([\\s\\S]*?)</${tag}\\s*>`, 'i');
+    const m = re.exec(block);
+    return m ? m[1] : null;
+}
+/**
+ * Split a `<files>` body into paths. Comma-separated per the shipped
+ * `templates/phase-prompt.md` grammar; newline-separated forms are tolerated
+ * too (Postel — liberal in what we accept), and the caller records nothing
+ * special for them because a path list is a path list either way.
+ */
+function splitFileList(body) {
+    if (body === null)
+        return [];
+    return body
+        .split(/[,\n]/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+/** `<acceptance_criteria>` carries `- ` bullets, one criterion per line. */
+function splitCriteria(body) {
+    if (body === null)
+        return [];
+    return body
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => line.replace(/^[-*]\s*/, ''))
+        .filter((line) => line.length > 0);
+}
+function collapseWhitespace(value) {
+    if (value === null)
+        return null;
+    const trimmed = value.replace(/\s+/g, ' ').trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Parse the `<task>` blocks. Each opening tag found by `xmlTaskOpenings` yields
+ * exactly one row — the block runs from that tag to its `</task>`, or to the
+ * next opening tag, or to end-of-document. Bounding on the NEXT OPENING rather
+ * than only on `</task>` is what keeps an unclosed block from consuming its
+ * siblings, so the row count still equals the opening count.
+ */
+function parseXmlTasks(content) {
+    const openings = xmlTaskOpenings(content);
+    return openings.map((match, i) => {
+        const start = match.index ?? 0;
+        const openTag = match[0];
+        const nextStart = i + 1 < openings.length ? (openings[i + 1].index ?? content.length) : content.length;
+        const window = content.slice(start, nextStart);
+        const closeIdx = window.search(/<\/task\s*>/i);
+        const block = closeIdx === -1 ? window : window.slice(0, closeIdx);
+        const type = tagAttribute(openTag, 'type');
+        const kind = type !== null && type.toLowerCase().startsWith('checkpoint')
+            ? TASK_KIND.CHECKPOINT
+            : TASK_KIND.AUTO;
+        // A checkpoint block has no <name>/<files>/<acceptance_criteria>/<done> in
+        // the shipped grammar. Reading them anyway would be harmless but dishonest:
+        // the caller must be able to tell "this element is absent because this kind
+        // of task has no such element" from "this element is missing and should not
+        // be".
+        if (kind === TASK_KIND.CHECKPOINT) {
+            return {
+                index: i + 1,
+                kind,
+                type,
+                name: null,
+                plannedFiles: [],
+                acceptanceCriteria: [],
+                done: null,
+                trackerId: null,
+            };
+        }
+        return {
+            index: i + 1,
+            kind,
+            type,
+            name: collapseWhitespace(elementBody(block, 'name')),
+            plannedFiles: splitFileList(elementBody(block, 'files')),
+            acceptanceCriteria: splitCriteria(elementBody(block, 'acceptance_criteria')),
+            done: collapseWhitespace(elementBody(block, 'done')),
+            trackerId: tagAttribute(openTag, 'tracker-id'),
+        };
+    });
+}
+/**
+ * Legacy fallback: `## Task N` headings, used ONLY when the document carries no
+ * `<task>` blocks at all. Deliberately fence-blind, matching the counting rule
+ * `cmdPhasePlanIndex` has always used — see this module's header comment.
+ */
+function parseMarkdownTasks(content) {
+    return markdownTaskHeadings(content).map((match, i) => ({
+        index: i + 1,
+        kind: TASK_KIND.AUTO,
+        type: null,
+        name: collapseWhitespace(match[0].replace(/^##\s*/, '')),
+        plannedFiles: [],
+        acceptanceCriteria: [],
+        done: null,
+        trackerId: null,
+    }));
+}
+// ─── Objective ────────────────────────────────────────────────────────────────
+/**
+ * Preserved verbatim from `cmdPhasePlanIndex`: the first line following an
+ * `<objective>` tag. Deliberately NOT widened to the full element body — that
+ * would change `phase.plan-index`'s existing output for any multi-line
+ * objective.
+ */
+function extractObjective(content) {
+    const m = content.match(/<objective>\s*\n?\s*(.+)/);
+    return m ? m[1].trim() : null;
+}
+// ─── Entry point ──────────────────────────────────────────────────────────────
+/**
+ * The plan id for a plan FILE ENTRY, exactly as `scanPhasePlans` stores it
+ * (root entries bare, nested entries `plans/`-prefixed).
+ *
+ * This is the established derivation from `cmdPhasePlanIndex`, moved here
+ * VERBATIM (#2790) so `phase.plan-index` and `planning.inspect` cannot report
+ * different ids for the same plan — a consumer correlating the two surfaces
+ * needs them to join. Deliberately NOT "improved": it is a display/lookup key
+ * with existing callers, and changing what it returns would be a Hyrum's-Law
+ * break on `phase-plan-index`.
+ */
+function planIdFromFile(planFile) {
+    return planFile.replace('-PLAN.md', '').replace('PLAN.md', '');
+}
+/**
+ * Parse one plan document.
+ *
+ * @param content  Raw `*-PLAN.md` text.
+ * @param planPath Optional path, used only to name the file in `extractFrontmatter`'s
+ *                 truncated-frontmatter diagnostic (#1882). Callers that do not have
+ *                 one omit it — this default IS the shape production uses from the
+ *                 read-only query path.
+ */
+function parsePlanDocument(content, planPath = '') {
+    const fm = extractFrontmatter(content, planPath);
+    const xmlTasks = parseXmlTasks(content);
+    const tasks = xmlTasks.length > 0 ? xmlTasks : parseMarkdownTasks(content);
+    const parsedWave = parseInt(fm['wave'], 10);
+    const declaredWave = Number.isNaN(parsedWave) ? null : parsedWave;
+    let dependsOn = [];
+    const fmDeps = fm['depends_on'];
+    if (Array.isArray(fmDeps)) {
+        dependsOn = fmDeps.map(String);
+    }
+    else if (typeof fmDeps === 'string' && fmDeps.trim() !== '') {
+        dependsOn = [fmDeps];
+    }
+    let autonomous = true;
+    if (fm['autonomous'] !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue comparison
+        autonomous = fm['autonomous'] === 'true' || String(fm['autonomous']) === 'true';
+    }
+    let filesModified = [];
+    const fmFiles = fm['files_modified'] || fm['files-modified'];
+    if (fmFiles) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
+        filesModified = Array.isArray(fmFiles) ? fmFiles.map(String) : [String(fmFiles)];
+    }
+    let filesDeleted = [];
+    const fmDeleted = fm['files_deleted'] || fm['files-deleted'];
+    if (fmDeleted) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
+        filesDeleted = Array.isArray(fmDeleted) ? fmDeleted.map(String) : [String(fmDeleted)];
+    }
+    let agentHint = null;
+    const fmAgentHint = fm['agent_hint'];
+    if (fmAgentHint !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
+        const hintStr = String(fmAgentHint).trim();
+        agentHint = hintStr !== '' ? hintStr : null;
+    }
+    return {
+        objective: extractObjective(content) || fm['objective'] || null,
+        declaredWave,
+        dependsOn,
+        autonomous,
+        agentHint,
+        filesModified,
+        filesDeleted,
+        tasks,
+        taskCount: tasks.length,
+    };
+}
+const planDocument = { TASK_KIND, parsePlanDocument, planIdFromFile };
+module.exports = planDocument;

package/gsd-core/bin/lib/plan-scan.cjs

@@ -88,7 +88,18 @@ function isRootPlanFile(fileName) {
     // substring "PLAN") are not double-counted as plans. (#500 RC2)
     if (isRootSummaryFile(fileName))
         return false;
-    return /\.md$/i.test(fileName) && /PLAN/i.test(fileName);
+    // #3741: the PLAN token must be DELIMITED — anchored at the start or after
+    // a hyphen, and followed only by an optional `-<digits>…` suffix before
+    // `.md` (the `…` keeps the legacy slug form `3-PLAN-01-setup.md` that
+    // gsd-plan-phase writes, per #3128). A bare substring test counted
+    // REPLAN-INPUTS / PLANNING-INPUTS / PLANNING-NOTES as plans, inflating
+    // planCount and STATE.md's derived total_plans. Delimited keeps the
+    // fallback's deliberate permissiveness for legacy single-token names
+    // (`plan.md`, `Plan.md`, `01-PLAN-02.md`, `3-PLAN-01-setup.md`) while
+    // excluding any name where PLAN is merely embedded in a larger word
+    // (REPLAN, PLANNING) — the same anchoring discipline isNestedPlanFile
+    // already applies.
+    return /(^|-)PLAN(-\d+.*)?\.md$/i.test(fileName);
 }
 function isNestedPlanFile(fileName) {
     if (PLAN_OUTLINE_RE.test(fileName))
@@ -108,7 +119,7 @@ function isNestedSummaryFile(fileName) {
  * `allPlanFiles` ENTRY (root form bare, nested form `plans/`-prefixed, exactly
  * as those arrays store them) — root `<phase>-<NN>-PLAN.md`/bare `PLAN.md`,
  * or nested `plans/PLAN-<NN>....md`/`plans/<x>-PLAN-<NN>....md` — WITHOUT
- * `isRootPlanFile`'s loose `/\.md$/i && /PLAN/i` fallback.
+ * `isRootPlanFile`'s loose delimited-PLAN fallback.
  *
  * The `plans/` prefix check is load-bearing, not cosmetic: `isNestedPlanFile`
  * matches ANY basename containing `-PLAN-<digits>...md` with no anchor

package/gsd-core/bin/lib/planning-command-router.cjs

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Planning command router — CLI subcommand dispatcher for `gsd-tools planning`.
+ *
+ * Routes `planning inspect` (#2790) to `planningInspect.cmdPlanningInspect`.
+ * Both the spaced form (`query planning inspect`) and the dotted canonical form
+ * (`query planning.inspect`) reach here identically: `gsd-tools` splits a dotted
+ * command on its FIRST dot before dispatch, so the router never sees the dot.
+ *
+ * v1 accepts NO arguments beyond the subcommand. `--raw`, `--cwd`, `--pick`,
+ * `--default` and `--json-errors` are global and are spliced out of argv by
+ * `gsd-tools`' own `main()` before any router runs, so anything still present at
+ * `args[2]` or beyond is genuinely unrecognised and is a fail-loud USAGE error.
+ * That strictness is deliberate: silently ignoring an argument a caller believed
+ * was scoping the query would return a full-project snapshot presented as a
+ * scoped one — a confidently wrong answer.
+ *
+ * Router signature `{ args, cwd, raw, error }` — identical to the other host
+ * routers. Test seam: pass `_planningInspect` to inject a recording mock; the
+ * `_` prefix follows this repo's established seam convention.
+ *
+ * ADR-457 build-at-publish: source in src/planning-command-router.cts, compiled
+ * to gsd-core/bin/lib/planning-command-router.cjs (gitignored).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningInspect = require("./planning-inspect.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { routeCjsCommandFamily } = cjsCommandRouterAdapter;
+const { ERROR_REASON } = io;
+// ─── Implementation ───────────────────────────────────────────────────────────
+const PLANNING_SUBCOMMANDS = ['inspect'];
+function routePlanningCommand({ args, cwd, raw, error, _planningInspect }) {
+    const mod = _planningInspect ?? planningInspect;
+    routeCjsCommandFamily({
+        args,
+        subcommands: PLANNING_SUBCOMMANDS,
+        unsupported: {},
+        error,
+        unknownMessage: (_subcommand, available) => `Unknown planning subcommand. Available: ${available.join(', ')}`,
+        handlers: {
+            inspect: () => {
+                const extra = args.slice(2);
+                if (extra.length > 0) {
+                    const offender = extra[0];
+                    const shape = offender.startsWith('-') ? 'flag' : 'positional argument';
+                    error(`planning inspect takes no arguments; got ${shape}: ${offender}. ` +
+                        'Usage: gsd-tools query planning inspect', ERROR_REASON.USAGE);
+                    return;
+                }
+                mod.cmdPlanningInspect(cwd, raw);
+            },
+        },
+    });
+}
+module.exports = {
+    routePlanningCommand,
+    PLANNING_SUBCOMMANDS,
+};