@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/decision-coverage-support.cjs

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Decision-coverage support — the shared reading/matching helpers of the two decision-coverage
+ * gates (#5139, epic #5056, ADR-5057 §4 first bullet, design D3/D4).
+ *
+ * Moved verbatim (behaviour preserved) from `check-command-router.cts`, with the raw-content
+ * parsers replaced by their owning seams:
+ *   - the frontmatter `must_haves` / `truths` / `objective` blocks are read through the
+ *     Frontmatter Module (`frontmatterKeyBlockText`, the moved `extractYamlBlock`: raw text off
+ *     the one fence owner's block, so frontmatter the YAML parser refuses is still scanned), and
+ *     the SUMMARY `files_modified` list through its parsed reader (`rawFrontmatterField`), not a
+ *     `files_modified:` regex;
+ *   - the XML-tag body extraction lives in `markdown-sectionizer.cts` (`extractXmlTagBodies`).
+ *
+ * The router-facing gate modules (`gate-decision-coverage-plan.cts`,
+ * `gate-decision-coverage-verify.cts`) import from here. This module imports no io module and
+ * performs no direct console/stdout/stderr write (ESLint-enforced).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decisionMentioned = decisionMentioned;
+exports.loadPlanContents = loadPlanContents;
+exports.loadSummaryContents = loadSummaryContents;
+exports.loadDecisionExtraction = loadDecisionExtraction;
+exports.extractPlanDesignatedSections = extractPlanDesignatedSections;
+exports.buildPlanMessage = buildPlanMessage;
+exports.buildVerifyMessage = buildVerifyMessage;
+exports.phaseCommitMessages = phaseCommitMessages;
+exports.readModifiedFilesContent = readModifiedFilesContent;
+const node_path_1 = __importDefault(require("node:path"));
+const decisions_cjs_1 = require("./decisions.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const security_cjs_1 = require("./security.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+const gate_evaluation_scope_cjs_1 = require("./gate-evaluation-scope.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { rawFrontmatterField, frontmatterKeyBlockText } = frontmatterMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planScanMod = require("./plan-scan.cjs");
+const { scanPhasePlans } = planScanMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// ─── Decision matching ────────────────────────────────────────────────────────
+function normalizePhrase(text) {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    return String(text || '')
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+const SOFT_PHRASE_MIN_WORDS = 6;
+function softPhrase(text) {
+    const words = normalizePhrase(text).split(' ').filter(Boolean);
+    if (words.length < SOFT_PHRASE_MIN_WORDS)
+        return '';
+    return words.slice(0, SOFT_PHRASE_MIN_WORDS).join(' ');
+}
+function decisionMentioned(haystack, decision) {
+    if (!haystack)
+        return false;
+    if (new RegExp(`\\b${decision.id}\\b`).test(haystack))
+        return true;
+    const phrase = softPhrase(decision.text);
+    return phrase ? normalizePhrase(haystack).includes(phrase) : false;
+}
+// ─── File reading ─────────────────────────────────────────────────────────────
+/**
+ * The contents of the phase files `pick` selects (#5170, ADR-5057 §4). An ABSENT phase directory
+ * is "no files" (`found []`); a directory or file that exists but cannot be read is `unreadable` —
+ * a gate must not take "could not read the plan" for "the plan does not cite the decision".
+ */
+function readPhaseFiles(phaseDir, pick) {
+    const entries = (0, gate_evidence_cjs_1.readDirEvidence)(phaseDir);
+    if (entries.kind === 'none')
+        return (0, gate_evidence_cjs_1.evidenceFound)([]);
+    if (entries.kind === 'unreadable')
+        return entries;
+    const contents = [];
+    // #3183 (lint-plan-count-drift): source live plan/summary files from the single
+    // owner (scanPhasePlans) instead of a local readdirSync filter — picks up bare PLAN.md and
+    // nested plans/, and excludes plans marked `status: superseded`.
+    // Only SCOPE.COMPLETE is a real answer: an existing nested plans/ that could not be read (TRUNCATED)
+    // would otherwise hand the gate a short plan set and let it conclude "no plan cites the decision".
+    const scan = scanPhasePlans(phaseDir);
+    if (scan.scope !== SCOPE.COMPLETE) {
+        return { kind: 'unreadable', reason: `plan scan ${scan.scope}`, span: phaseDir };
+    }
+    for (const entry of pick(scan)) {
+        const read = (0, gate_evidence_cjs_1.readTextEvidence)(node_path_1.default.join(phaseDir, entry));
+        if (read.kind === 'unreadable')
+            return read;
+        if (read.kind === 'found')
+            contents.push(read.value);
+    }
+    return (0, gate_evidence_cjs_1.evidenceFound)(contents);
+}
+function loadPlanContents(phaseDir) {
+    return readPhaseFiles(phaseDir, (scan) => scan.planFiles);
+}
+/**
+ * #3183 (lint-plan-count-drift): same single-owner sourcing as `loadPlanContents` —
+ * scanPhasePlans's summaryFiles instead of a local `-SUMMARY.md` readdirSync filter.
+ */
+function loadSummaryContents(phaseDir) {
+    return readPhaseFiles(phaseDir, (scan) => scan.summaryFiles);
+}
+/**
+ * The decisions of `CONTEXT.md`. `none` is an absent file (the caller's legitimate "nothing to
+ * check"); `unreadable` is a file that exists but could not be read — it must never be extracted as
+ * empty text, which would certify "no trackable decisions".
+ */
+function loadDecisionExtraction(contextPath) {
+    const read = (0, gate_evidence_cjs_1.readTextEvidence)(contextPath);
+    if (read.kind !== 'found')
+        return read;
+    const extraction = (0, decisions_cjs_1.extractDecisions)(read.value);
+    return (0, gate_evidence_cjs_1.evidenceFound)({
+        trackable: extraction.decisions.filter((d) => d.trackable),
+        outcome: extraction.outcome,
+        unreadableIds: extraction.unreadableIds ?? [],
+    });
+}
+// ─── Plan surfaces scanned for a decision citation ────────────────────────────
+const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
+function stripCommentsAndFences(text) {
+    // HTML-comment stripping stays caller-side (the seam does not strip HTML comments).
+    // Stop-at-next-open body (ReDoS-safe, #2128); an UNCLOSED `<!--` does not match,
+    // so downstream tags are preserved (unlike a `(?:-->|$)` fallback, which would
+    // wipe to EOF and fail-close the decision-coverage gate).
+    const htmlStripped = text.replace(/<!--(?:(?!<!--)[\s\S])*?-->/g, ' ');
+    // Fenced-code stripping: delegate to the canonical CommonMark-correct seam.
+    // replaces the prior independent regex copy (```` ``` ``` ````  + `~~~ ~~~`).
+    return (0, markdown_sectionizer_cjs_1.stripFencedCode)(htmlStripped).text;
+}
+function extractPlanDesignatedSections(planContent) {
+    if (!planContent)
+        return '';
+    const cleaned = stripCommentsAndFences(planContent);
+    // The block is the one the one fence owner finds; the body starts after the closing fence
+    // line's line ending.
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(cleaned);
+    const body = fence?.closed ? cleaned.slice(fence.closingFenceEnd).replace(/^\r?\n/, '') : cleaned;
+    const parts = [];
+    for (const key of ['must_haves', 'truths', 'objective']) {
+        const block = frontmatterKeyBlockText(cleaned, key);
+        if (block)
+            parts.push(block);
+    }
+    // Replace hand-rolled split(/\r?\n/) + heading walk with the seam's collectSections.
+    // stopPredicate fires on EVERY heading (collectSections needs to start a section at
+    // each heading), then we filter to designated ones — same semantics as the prior
+    // inDesignated flag: emit the heading line + body only when DESIGNATED_HEADINGS_RE matches.
+    const sections = (0, markdown_sectionizer_cjs_1.collectSections)(body, () => true);
+    const bodyParts = [];
+    for (const section of sections) {
+        const headingLine = '#'.repeat(section.heading.level) + ' ' + section.heading.text;
+        if (DESIGNATED_HEADINGS_RE.test(headingLine)) {
+            bodyParts.push(headingLine);
+            if (section.body)
+                bodyParts.push(section.body);
+        }
+    }
+    parts.push(bodyParts.join('\n'));
+    parts.push((0, markdown_sectionizer_cjs_1.extractXmlTagBodies)(cleaned));
+    return parts.join('\n\n');
+}
+function buildPlanMessage(uncovered) {
+    if (uncovered.length === 0)
+        return 'All trackable CONTEXT.md decisions are covered by plans.';
+    return [
+        '## Decision Coverage Gap',
+        '',
+        `${uncovered.length} CONTEXT.md decision(s) are not covered by any plan:`,
+        '',
+        ...uncovered.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
+        '',
+        'Resolve by citing `D-NN:` in any of the scanned plan surfaces: front-matter',
+        '`must_haves`/`truths`/`objective`, a `## must_haves`/`truths`/`tasks`/`objective`',
+        'heading, or an `<objective>`/`<tasks>`/`<task>`/`<action>`/`<read_first>`/`<behavior>`/`<verify>`/`<acceptance_criteria>`/`<done>`',
+        'tag body. Other locations (prose outside those headings, comments, other XML tags) are not scanned.',
+        'OR move the decision to `### Claude\'s Discretion` / tag it `[informational]` if it should not be tracked.',
+    ].join('\n');
+}
+function buildVerifyMessage(notHonored) {
+    if (notHonored.length === 0)
+        return 'All trackable CONTEXT.md decisions are honored by shipped artifacts.';
+    return [
+        '### Decision Coverage (warning)',
+        '',
+        `${notHonored.length} decision(s) not found in shipped artifacts:`,
+        '',
+        ...notHonored.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
+        '',
+        'This is a soft warning - verification status is unchanged.',
+    ].join('\n');
+}
+// ─── Shipped-artifact haystack (verify gate) ──────────────────────────────────
+/**
+ * The subjects and bodies of the PHASE'S OWN commits (#5164, ADR-5057 §4) — the evaluation-scope
+ * resolver's commit set for `phaseDir`, not the last 200 commits of whatever branch is checked
+ * out. A phase with no recorded task commits widens to the commits in its directory range (the
+ * resolver says so); an unreadable phase or repository yields '' ("could not look"), and a git
+ * failure on a non-git project dir writes nothing to the terminal.
+ */
+function phaseCommitMessages(projectDir, phaseDir) {
+    const scope = (0, gate_evaluation_scope_cjs_1.resolveEvaluationScope)(projectDir, { kind: 'phase', phase: '', phaseDir }, { includeBody: true, includeFiles: false });
+    return scope.commits.map((c) => `${c.subject}\n${c.body ?? ''}`).join('\n');
+}
+/** Cap on files read across all SUMMARYs, and on bytes read per file. */
+const MODIFIED_FILES_MAX_COUNT = 50;
+const MODIFIED_FILES_MAX_BYTES = 256 * 1024;
+/**
+ * The contents of every file the SUMMARYs list under frontmatter `files_modified`, contained to
+ * `projectDir` and capped at `MODIFIED_FILES_MAX_COUNT` files / `MODIFIED_FILES_MAX_BYTES` each.
+ */
+function readModifiedFilesContent(projectDir, summaries) {
+    const out = [];
+    let total = 0;
+    for (const summary of summaries) {
+        if (!summary)
+            continue;
+        if (total >= MODIFIED_FILES_MAX_COUNT)
+            break;
+        const field = rawFrontmatterField(summary, 'files_modified');
+        const listed = field && Array.isArray(field.value) ? field.value : [];
+        for (const entry of listed) {
+            if (total >= MODIFIED_FILES_MAX_COUNT)
+                break;
+            if (typeof entry !== 'string')
+                continue;
+            const file = entry.trim();
+            if (!file)
+                continue;
+            // Migrated off the hand-rolled prefix check (ADR-4650): resolve+contain in one
+            // step via the canonical realpath predicate — the eventual read below follows
+            // symlinks, so containment must be decided on the resolved target, not a lexical
+            // prefix. Read the value the predicate RETURNED; do not re-derive the path.
+            const candidate = node_path_1.default.isAbsolute(file) ? file : node_path_1.default.join(projectDir, file);
+            const contained = (0, security_cjs_1.tryWithinRoot)(candidate, projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+            if (contained === null)
+                continue;
+            // An absent listed file contributes nothing readable (`''`); one that exists but cannot be
+            // read is `unreadable` — the decision it may cite was never seen (#5170).
+            const read = (0, gate_evidence_cjs_1.readTextEvidence)(contained);
+            if (read.kind === 'unreadable')
+                return read;
+            const content = read.kind === 'found' ? read.value : '';
+            out.push(content.length > MODIFIED_FILES_MAX_BYTES ? content.slice(0, MODIFIED_FILES_MAX_BYTES) : content);
+            total++;
+        }
+    }
+    return (0, gate_evidence_cjs_1.evidenceFound)(out.join('\n\n'));
+}

package/gsd-core/bin/lib/decisions.cjs

@@ -85,14 +85,14 @@ const DECISION_ID_SOURCE = 'D[0-9]*-[A-Za-z0-9][A-Za-z0-9_-]*';
 const ID_ATTEMPT_SOURCE = 'D(?:[0-9][A-Za-z0-9]*)?-';
 /**
  * Colon form: `- **D[phase]-NN[ [tags]]:** text`
- * (#1343: `[^:*]*` subsumes any pre-colon prose, stops at `:**`)
+ * (#1343: the pre-colon run subsumes any pre-colon prose, stops at `:**`; #4788: the run is code-span-aware — a backticked span is consumed whole, so a `:` or `*` INSIDE it is data, never grammar)
  * Group 1 captures the FULL id including any phase prefix (#4130).
  * The ID is consumed atomically `(?=(…))\1` — see the hardening note above
  * the constants (#4130 follow-up); with the tail unable to give back, the
  * remaining `[^:*]*:` scan has a single viable split and the whole match is
  * linear in line length.
  */
-const bulletColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?[^:*]*:\\*\\*\\s*(.*)$`);
+const bulletColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?(?:\\u0060[^\\u0060]*\\u0060|[^:*\\u0060])*:\\*\\*\\s*(.*)$`);
 /**
  * Em-dash form: `- **D[phase]-NN[ [tags]] — title** body`
  * The em-dash (U+2014) or its lookalike separates the ID+tags group from a title
@@ -112,22 +112,32 @@ const bulletColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1
  * candidate and `**` succeeds or fails identically; no capture involves the
  * dash position. The ID is atomic like the other forms (driver #1).
  */
-const bulletEmDashRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?[^*—–]*[—–][^*]*\\*\\*\\s*(.*)$`);
+const bulletEmDashRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?(?:\\u0060[^\\u0060]*\\u0060|[^*—–\\u0060])*[—–](?:\\u0060[^\\u0060]*\\u0060|[^*\\u0060])*\\*\\*\\s*(.*)$`);
 /**
  * Titled-colon form: `- **D[phase]-NN[ [tags]]: Title.** body`
  * A title sits between the colon and the closing `**` (so the `:**` anchor of
  * bulletColonRe fails, and there is no em-dash for bulletEmDashRe). This is a strict
  * superset of the colon-immediate form, so it MUST be checked AFTER bulletColonRe and
- * bulletEmDashRe — it only catches bullets those two miss. The title run is `[^:*]*` (no
- * colon, no `*`) so a genuinely-malformed bullet with a colon in the pre-separator run
- * (e.g. `D-07 ratio 3:1:**`) still fails the anchor and falls through to the parse-miss
- * guard — matching bulletColonRe's `[^:*]*` discipline that the separator colon is the
- * only colon permitted before `**`. (#1639)
+ * bulletEmDashRe — it only catches bullets those two miss. The title runs are code-span-aware
+ * (#4788) but still exclude `*`, so a genuinely-malformed bullet with no bare colon at all
+ * before `**` still fails the anchor and falls through to the parse-miss guard — the #1639
+ * fail-loud discipline: the separator must be a BARE colon before `**`. A code span's
+ * `:`/`*` is data, never grammar; an UNTERMINATED backtick now fails loud (previously it was
+ * an ordinary character) — the deliberate cost of span opacity.
+ *
+ * #4793/#4958: the pre-separator run tolerates a bare colon as prose ONLY when it is
+ * immediately followed by whitespace (`:(?=\s)`), e.g. a natural sentence colon in
+ * `D-02: Two managers … same pair: the second is rejected.`. A colon with no following
+ * whitespace (a compact/ratio-style colon like `3:1`) is never consumed by this branch, so
+ * it still hard-caps the pre-separator run and the #1639/#4130/#1343 negative-space fixtures
+ * (e.g. `D-07 ratio 3:1:**`) still fail loud. The post-separator branch is unchanged and
+ * still excludes colons, so normal greedy backtracking selects the LAST valid split (a bare
+ * colon followed by whitespace, or the anchor colon itself) before the closing `**`.
  *
  * The ID is consumed atomically `(?=(…))\1` like the other forms — the
  * hardening note above the constants explains why (#4130 follow-up).
  */
-const bulletTitledColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?[^:*]*:[^:*]*\\*\\*\\s*(.*)$`);
+const bulletTitledColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?(?:\\u0060[^\\u0060]*\\u0060|:(?=\\s)|[^:*\\u0060])*:(?:\\u0060[^\\u0060]*\\u0060|[^:*\\u0060])*\\*\\*\\s*(.*)$`);
 /**
  * #4130: the parse-miss guard's probe — a line whose bold lead-in ATTEMPTS the
  * ID grammar (see `ID_ATTEMPT_SOURCE`) but failed all three bullet patterns
@@ -403,6 +413,7 @@ function parseDecisionLines(block) {
     let current = null;
     let openIndent = null;
     let parseMisses = 0;
+    const unreadableIds = [];
     const flush = () => {
         if (current) {
             current.text = current.text.trim();
@@ -501,6 +512,11 @@ function parseDecisionLines(block) {
         if (parseMissGuardRe.test(line)) {
             flush();
             parseMisses += 1;
+            // #4794: carry the attempted id so a caller capturing stdout (a JSON gate)
+            // can name the decision to fix — today it exists only in this stderr warn.
+            const attempted = line.match(/\*\*\s*(D(?:[0-9][A-Za-z0-9]*)?-[A-Za-z0-9_-]*)/);
+            if (attempted && !unreadableIds.includes(attempted[1]))
+                unreadableIds.push(attempted[1]);
             console.warn(`parseDecisions: ignored unparseable decision bullet: ${trimmed}`);
             continue;
         }
@@ -516,7 +532,7 @@ function parseDecisionLines(block) {
         }
     }
     flush();
-    return { decisions: out, parseMisses };
+    return { decisions: out, parseMisses, unreadableIds };
 }
 // ─── Primary entry point: extractDecisions ────────────────────────────────────
 /**
@@ -541,13 +557,13 @@ function extractDecisions(content) {
     const taggedBlocks = (0, markdown_sectionizer_cjs_1.extractTaggedBlocks)(stripped, 'decisions');
     if (taggedBlocks.length > 0) {
         const combined = taggedBlocks.join('\n\n');
-        const { decisions, parseMisses } = parseDecisionLines(combined);
+        const { decisions, parseMisses, unreadableIds } = parseDecisionLines(combined);
         if (decisions.length > 0 && parseMisses === 0) {
             return { decisions, outcome: 'parsed' };
         }
         // FIX B: parse-misses present — could-not-parse even if some decisions extracted.
         if (parseMisses > 0) {
-            return { decisions, outcome: 'could-not-parse' };
+            return { decisions, outcome: 'could-not-parse', unreadableIds };
         }
         // FIX A: Block present but 0 extracted and no parse-misses.
         // Only report could-not-parse when there is genuine evidence of real decisions
@@ -568,13 +584,13 @@ function extractDecisions(content) {
     // stripFences:true → inner fences inside the section body are stripped.
     const section = (0, markdown_sectionizer_cjs_1.collectSection)(content, (h) => /decisions?\b/i.test(h.text), { levelBounded: true, stripFences: true });
     if (section !== null) {
-        const { decisions, parseMisses } = parseDecisionLines(section.body);
+        const { decisions, parseMisses, unreadableIds } = parseDecisionLines(section.body);
         if (decisions.length > 0 && parseMisses === 0) {
             return { decisions, outcome: 'parsed' };
         }
         // FIX B: parse-misses present — could-not-parse even if some decisions extracted.
         if (parseMisses > 0) {
-            return { decisions, outcome: 'could-not-parse' };
+            return { decisions, outcome: 'could-not-parse', unreadableIds };
         }
         // FIX A: Heading found but 0 extracted and no parse-misses.
         // Report could-not-parse when the section body holds a decision-entry-shaped