@opengsd/gsd-core 1.14.0 → 1.16.0

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

@@ -6,7 +6,7 @@
  * 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`).
+ * `depends_on`, `autonomous`, `agent_hint`, `files_modified`, `gap_closure`).
  *
  * WHY THIS IS A LEAF MODULE. This logic was written inline inside
  * `cmdPhasePlanIndex` (`src/phase.cts`). Two commands in two different families
@@ -32,9 +32,23 @@
  * 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;
+// #5026 / ADR-4910 §1 absorption: the 7 frontmatter-derived scheduling fields
+// below, plus `objective` as an 8th (see `frontmatterField`'s own docblock),
+// read through `planning-document.cts`'s seam
+// (`readFrontmatterFieldsFromSource`) rather than calling `frontmatter.cts`'s
+// `extractFrontmatter` directly. This module has no canonical `.planning/`-root
+// artifact basename to gate `parsePlanningDoc` on (`*-PLAN.md` lives nested
+// under `.planning/phase/*/plans/`, and two of the five real callers hold only
+// in-memory content with no path at all), so it uses the entry point shaped
+// for exactly that: content in hand, no filename, no other `PlanningDoc`
+// capability (sections/tables/checklists) this module needs. The BULK form
+// (`readFrontmatterFieldsFromSource`, not the single-key
+// `readFrontmatterFieldFromSource`) is used deliberately: `parsePlanDocument`
+// reads several keys off the SAME document, and the single-key entry point
+// would independently re-detect the frontmatter span and re-parse the full
+// YAML once per key. See both functions' docblocks in `planning-document.cts`
+// for the full reasoning.
+const planning_document_cjs_1 = require("./planning-document.cjs");
 // ─── Frozen vocabularies ──────────────────────────────────────────────────────
 /**
  * How a task row was expressed in the document. `auto` is the ordinary
@@ -203,23 +217,80 @@ function extractObjective(content) {
 function planIdFromFile(planFile) {
     return planFile.replace('-PLAN.md', '').replace('PLAN.md', '');
 }
+/**
+ * The frontmatter keys `parsePlanDocument` reads: the 7 scheduling fields
+ * this absorption originally scoped (`wave`, `depends_on`, `autonomous`,
+ * `files_modified`/`files-modified`, `files_deleted`/`files-deleted`,
+ * `agent_hint`, `type` — 9 key spellings across those 7 fields), PLUS
+ * `objective` as an 8th field. `objective` is read through this SAME
+ * frontmatter-key-read path — not a deliberate exclusion, as an earlier
+ * revision of this comment claimed — because `parsePlanDocument`'s return
+ * statement below falls back to `frontmatterField(content, 'objective')`
+ * whenever the `<objective>` XML tag (`extractObjective`, unrelated and
+ * untouched by this absorption) is absent; it is included here simply
+ * because reading it is the exact same pattern as the other seven, and the
+ * migration below naturally covers it. `gap_closure` (#4924) is a 9th field,
+ * absorbed onto this same bulk-read seam by this fix rather than left on the
+ * removed `fm[key]` object-property read it was rebased in against.
+ */
+const FRONTMATTER_READ_KEYS = [
+    'wave',
+    'depends_on',
+    'autonomous',
+    'files_modified',
+    'files-modified',
+    'files_deleted',
+    'files-deleted',
+    'agent_hint',
+    'type',
+    'objective',
+    'gap_closure',
+];
+/**
+ * Read one top-level frontmatter key out of an already-bulk-read
+ * `Record<string, NodeRead>` (`readFrontmatterFieldsFromSource`'s return
+ * value, computed ONCE per `parsePlanDocument` call — see
+ * `FRONTMATTER_READ_KEYS`), unwrapped to the SAME shape a direct `fm[key]`
+ * object-property read would give: the field's value, or `undefined` when it
+ * is absent, the document has no frontmatter, or the frontmatter is
+ * unparseable — `readFrontmatterFieldsFromSource` reports all three of those
+ * as an `ok: false` result per key, and `extractFrontmatter`'s own object
+ * would likewise simply lack the key in every one of those cases.
+ */
+function frontmatterField(fields, key) {
+    const read = fields[key];
+    return read?.ok ? read.value : undefined;
+}
 /**
  * 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.
+ * @param planPath Historically the path passed to `extractFrontmatter`'s
+ *                 truncated-frontmatter diagnostic (#1882) — a stderr-only
+ *                 side channel, never part of this function's return value.
+ *                 #5026: the 9 frontmatter fields below (7 scheduling fields,
+ *                 plus `objective` and `gap_closure`) now read through
+ *                 `readFrontmatterFieldFromSource`, which has no path
+ *                 parameter, so this diagnostic's file-naming/dedup key is a
+ *                 documented, accepted side-effect-only regression (falls
+ *                 back to content-digest dedup, the same fallback
+ *                 `extractFrontmatter` already uses for the two real callers
+ *                 that never had a path to give it). Kept for call-site
+ *                 signature compatibility only.
  */
-function parsePlanDocument(content, planPath = '') {
-    const fm = extractFrontmatter(content, planPath);
+function parsePlanDocument(content, _planPath = '') {
     const xmlTasks = parseXmlTasks(content);
     const tasks = xmlTasks.length > 0 ? xmlTasks : parseMarkdownTasks(content);
-    const parsedWave = parseInt(fm['wave'], 10);
+    // Detect the frontmatter span and parse its YAML ONCE (#5026 follow-up: the
+    // prior per-key `frontmatterField(content, key)` calls each independently
+    // re-detected the span and re-parsed the full YAML from scratch — 10x
+    // redundant detection+parse per call). Every `frontmatterField` read below
+    // shares this SAME parsed result.
+    const fields = (0, planning_document_cjs_1.readFrontmatterFieldsFromSource)(content, FRONTMATTER_READ_KEYS);
+    const parsedWave = parseInt(frontmatterField(fields, 'wave'), 10);
     const declaredWave = Number.isNaN(parsedWave) ? null : parsedWave;
     let dependsOn = [];
-    const fmDeps = fm['depends_on'];
+    const fmDeps = frontmatterField(fields, 'depends_on');
     if (Array.isArray(fmDeps)) {
         dependsOn = fmDeps.map(String);
     }
@@ -227,37 +298,38 @@ function parsePlanDocument(content, planPath = '') {
         dependsOn = [fmDeps];
     }
     let autonomous = true;
-    if (fm['autonomous'] !== undefined) {
+    const fmAutonomous = frontmatterField(fields, 'autonomous');
+    if (fmAutonomous !== undefined) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue comparison
-        autonomous = fm['autonomous'] === 'true' || String(fm['autonomous']) === 'true';
+        autonomous = fmAutonomous === 'true' || String(fmAutonomous) === 'true';
     }
     let filesModified = [];
-    const fmFiles = fm['files_modified'] || fm['files-modified'];
+    const fmFiles = frontmatterField(fields, 'files_modified') || frontmatterField(fields, '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'];
+    const fmDeleted = frontmatterField(fields, 'files_deleted') || frontmatterField(fields, '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'];
+    const fmAgentHint = frontmatterField(fields, '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;
     }
     let planType = null;
-    const fmType = fm['type'];
+    const fmType = frontmatterField(fields, 'type');
     if (fmType !== undefined) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar-to-string
         planType = String(fmType);
     }
     return {
-        objective: extractObjective(content) || fm['objective'] || null,
+        objective: extractObjective(content) || frontmatterField(fields, 'objective') || null,
         type: planType,
         declaredWave,
         dependsOn,
@@ -265,9 +337,59 @@ function parsePlanDocument(content, planPath = '') {
         agentHint,
         filesModified,
         filesDeleted,
+        // extractFrontmatter yields every scalar as a string, so YAML `true` is 'true'.
+        gapClosure: frontmatterField(fields, 'gap_closure') === 'true',
         tasks,
         taskCount: tasks.length,
     };
 }
-const planDocument = { TASK_KIND, parsePlanDocument, planIdFromFile };
+const planDocument = { TASK_KIND, parsePlanDocument, planIdFromFile, extractThreatRegisterIds };
+/**
+ * #4683 — first-cell IDs of the STRIDE register rows inside every
+ * `<threat_model>` block. The register is a markdown table (the
+ * `<threat_model>` template in agents/gsd-planner.md): one row per threat,
+ * first cell `T-{phase}-NN` — decimal phases included — or the reserved
+ * `T-{phase}-SC` supply-chain row. Only digit-suffixed IDs match: `-SC` is
+ * deliberately shared by EVERY plan in a phase (planner rule "Keep
+ * `T-{phase}-SC` in `<threat_model>`"), so it can never be a uniqueness
+ * violation. IDs in prose or non-threat tables never count; only register
+ * rows inside a threat_model block do. One entry per matched row, in document
+ * order — deciding that the same ID in two plans is a collision is the
+ * aggregator's question (init.cts), not the per-document parser's.
+ *
+ * Knowingly unmatched residual classes (#4683 review, accepted): lowercase
+ * `t-47-01`, letter suffixes (`T-47-05A`), annotated first cells
+ * (`| T-47-06 (revised) |`), IDs in non-first cells, and an unterminated
+ * `<threat_model>` block all yield no claim. All are off-template shapes — the
+ * planner template fixes the row grammar — so the residual risk is silent
+ * under-detection, never a false hard-stop.
+ */
+const THREAT_MODEL_BLOCK_RE = /<threat_model>([\s\S]*?)<\/threat_model>/gi;
+const THREAT_REGISTER_ROW_RE = /^[^\S\n]*\|[^\S\n]*(T-\d+(?:\.\d+)?-\d+)[^\S\n]*\|/;
+function extractThreatRegisterIds(content) {
+    // Fenced code blocks are prose, not registers (#4683 review MAJOR): a plan
+    // that QUOTES an existing register — exactly what the gap-closure flow tells
+    // the planner to read — must not have its quoted IDs counted as claims, or
+    // the execute-phase gate would hard-stop a correct phase. Same line-toggling
+    // idiom as the deferred-scope scan in phase.cts.
+    const lines = [];
+    let inFence = false;
+    for (const line of content.split(/\r?\n/)) {
+        if (/^\s*(?:```|~~~)/.test(line)) {
+            inFence = !inFence;
+            lines.push('');
+            continue;
+        }
+        lines.push(inFence ? '' : line);
+    }
+    const ids = [];
+    for (const blockMatch of lines.join('\n').matchAll(THREAT_MODEL_BLOCK_RE)) {
+        for (const line of blockMatch[1].split('\n')) {
+            const row = line.match(THREAT_REGISTER_ROW_RE);
+            if (row)
+                ids.push(row[1]);
+        }
+    }
+    return ids;
+}
 module.exports = planDocument;

package/gsd-core/bin/lib/plan-drift-guard.cjs

@@ -137,6 +137,11 @@ const PHASE_STATUS_RANKS = Object.freeze({
     'phase complete': 2,
     // ROADMAP.md "## Progress" table Status column vocabulary
     'not started': 0,
+    // #5060: `roadmap update-plan-progress`'s own written token (Phase Status
+    // Module's `toRoadmapStatusCell`) for a phase with plans but no summaries
+    // yet — rank 1, the same "work has started" rank as STATE's "ready to
+    // execute" / "in progress".
+    'planned': 1,
     'complete': 2,
     'deferred': 0,
 });