@opengsd/gsd-core 1.13.0 → 1.15.0

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

@@ -5,7 +5,9 @@
  * truth). Behaviour is preserved byte-for-behaviour from the prior hand-written
  * .cjs; only types are added.
  *
- * Accepts both numeric (D-42) and alphanumeric (D-INFRA-01) IDs.
+ * Accepts numeric (D-42), alphanumeric (D-INFRA-01), and phase-prefixed
+ * (D4-01 — an optional digit-run between the leading letter and the hyphen,
+ * #4130) IDs.
  * Returns {id, text, category, tags, trackable} per decision.
  * CJS callers that only use {id, text} safely ignore the extra fields.
  *
@@ -16,6 +18,11 @@
  * - Outer bullet loop → seam's `iterateBullets` (for the header-fallback path)
  *
  * Resolves #1364 (markdown-header + em-dash recall) and #1365 (fail-loud gate).
+ *
+ * #4130 follow-up (hardening): the three bullet grammars below consume the
+ * decision ID atomically and narrow the em-dash first separator, eliminating
+ * the quadratic-backtracking cliff on pathological single bullets. Output is
+ * byte-identical on all legal inputs — see the notes at DECISION_ID_SOURCE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractDecisions = extractDecisions;
@@ -30,39 +37,130 @@ const DISCRETION_HEADINGS = new Set([
 const NON_TRACKABLE_TAGS = new Set(['informational', 'folded', 'deferred']);
 // ─── Bullet parsers (decisions-specific grammar) ─────────────────────────────
 /**
- * Colon form: `- **D-NN[ [tags]]:** text`
- * (#1343: `[^:*]*` subsumes any pre-colon prose, stops at `:**`)
+ * #4130: the ID grammar every extractor regex below shares, as ONE source.
+ * `D`, an OPTIONAL digit-run phase prefix, a hyphen, then the pre-existing
+ * alphanumeric tail — so `D-01` (bare), `D4-01`/`D12-01` (phase-prefixed,
+ * the reporter's multi-phase convention where bare D-01 collides across
+ * phases), and `D-INFRA-01` (alnum tail) are all the same grammar now.
+ * #2347 had already taught the shape DETECTOR to call `D4-01` decision-shaped
+ * while the EXTRACTOR still anchored on the literal `**D-` — the disagreement
+ * that made a whole phase-prefixed CONTEXT.md report could-not-parse. Deriving
+ * the three grammars (and the token evidence below) from this one constant is
+ * the parity pin: the extractor's ID universe cannot drift from the declared
+ * grammar again without editing this line, which the #4130 property tests
+ * watch from the other side.
+ */
+const DECISION_ID_SOURCE = 'D[0-9]*-[A-Za-z0-9][A-Za-z0-9_-]*';
+/**
+ * #4130 follow-up (hardening): how the three grammars below CONSUME the ID —
+ * atomically, via the `(?=(X))\1` lookahead emulation (lookarounds are atomic
+ * in ECMAScript; the backreference must replay exactly what the lookahead
+ * captured, so the engine can never give the ID tail back one character at a
+ * time). That give-back was quadratic driver #1: the tail class
+ * `[A-Za-z0-9_-]*` overlaps the pre-separator class `[^:*]*` (every id char
+ * is also `[^:*]`), so on a FAILING bullet the base regex re-split the tail
+ * O(n) times with an O(n) scan after each — measured ~1.1s @ 40k chars on
+ * `- **D-` + `a-`×20k (the #4357 review's deferred cliff).
+ *
+ * Byte-identical on all legal inputs: a successful match always consumes the
+ * MAXIMAL id run (the lookahead's own match is exactly that maximal run), and
+ * the continuation's success depends only on the position of the first
+ * `:`/`*` (or `*` for the em-dash form) after the id boundary — id chars
+ * contain neither, so moving the boundary inside the run cannot change
+ * success or any capture. Group 1 stays the full id (the lookahead's capture
+ * IS group 1), so handlers keep reading match[1]/[2]/[3] untouched. Pinned by
+ * the differential property test against a frozen copy of the pre-hardening
+ * grammars and by the regex-lattice test in tests/decisions.test.cjs.
+ */
+/**
+ * #4130: the bold lead-in that ATTEMPTS the ID grammar above — used by the
+ * parse-miss guard and the #3939 join regexes, where recognising MORE shapes
+ * is the conservative direction (an over-broad match can only make a
+ * malformed bullet fail loud). The prefix run is either empty (bare `D-`) or
+ * DIGIT-INITIAL (`4`, `4x` — a phase prefix with a typo still counts as an
+ * attempted ID, so `D4x-01` reaches the guard and fails loud instead of
+ * vanishing), but never letter-initial: `D` + letters + `-` (`Deferred-until`)
+ * is a prose word, and prose must stay `none-present` (#2347's law).
+ */
+const ID_ATTEMPT_SOURCE = 'D(?:[0-9][A-Za-z0-9]*)?-';
+/**
+ * Colon form: `- **D[phase]-NN[ [tags]]:** text`
+ * (#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 = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?[^:*]*:\*\*\s*(.*)$/;
+const bulletColonRe = new RegExp(`^\\s*-\\s+\\*\\*(?=(${DECISION_ID_SOURCE}))\\1(?:\\s*\\[([^\\]]+)\\])?(?:\\u0060[^\\u0060]*\\u0060|[^:*\\u0060])*:\\*\\*\\s*(.*)$`);
 /**
- * Em-dash form: `- **D-NN[ [tags]] — title** body`
+ * 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
  * that lives inside the bold markers; the body (which may be empty) follows
  * outside the closing `**`. This form was not handled pre-T1 (bug #1364).
  *
  * Accepts both U+2014 em-dash (—) and U+2013 en-dash (–) for robustness.
+ *
+ * #4130 follow-up (hardening), quadratic driver #2: the first separator was
+ * `[^*]*[—–]`, whose leading class ALSO accepts the dash — on a failing
+ * dash-laden title the engine retried the separator at every dash position
+ * with an O(n) scan after each (~1.7s @ 40k). Narrowed to `[^*—–]*[—–]`:
+ * the leading class now excludes the dash, so the separator is the FIRST
+ * dash — one viable split, single pass. Behavior-preserving because every
+ * candidate dash lies before the first `*` (the leading class cannot cross
+ * a star), so the trailing `[^*]*` reaches that same first star from any
+ * candidate and `**` succeeds or fails identically; no capture involves the
+ * dash position. The ID is atomic like the other forms (driver #1).
  */
-const bulletEmDashRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\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-NN[ [tags]]: Title.** body`
+ * 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*\\[([^\\]]+)\\])?(?:\\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
+ * above. Bare `D-` attempts behave exactly as before #4130; a digit-initial
+ * prefix run (`D4-`… including a typo'd `D4x-`) is new evidence of an attempt,
+ * so the malformed-prefixed bullet fails loud instead of silently vanishing.
+ */
+const parseMissGuardRe = new RegExp(`^\\s*-\\s+\\*\\*${ID_ATTEMPT_SOURCE}`);
+/**
+ * #4130: bare-token evidence of decision-shaped content — a `D…-<alnum>` token
+ * in running text. `D-01` matched before; the digit-run phase prefix (`D4-01`)
+ * is added so token evidence agrees with the extractor's ID grammar
+ * (DECISION_ID_SOURCE) instead of silently ignoring prefixed mentions.
  */
-const bulletTitledColonRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?[^:*]*:[^:*]*\*\*\s*(.*)$/;
+const decisionTokenRe = new RegExp(`\\bD[0-9]*-[A-Za-z0-9]`, 'm');
 /**
  * #2347: format-agnostic evidence that a block/section holds real decision
  * ENTRIES the parser could not read — a bullet whose bold lead-in is an
  * ID-SHAPED token (uppercase prefix, optional digits, hyphen, alnum), whatever
- * the exact ID grammar. The three parser grammars above all require a `D-`
- * prefix; #1365's fail-loud guard reused that same `\bD-` test as its "is this
- * decision-shaped?" evidence, so any other prefix (e.g. `D5-01`) was invisible
- * to BOTH parser and guard, collapsing `could-not-parse` into a clean
+ * the exact ID grammar. #1365's fail-loud guard originally reused the parser's
+ * own `\bD-` test as its "is this decision-shaped?" evidence, so any prefix the
+ * parser could not read (e.g. `D5-01` then, `DEC-01` now) was invisible to
+ * BOTH parser and guard, collapsing `could-not-parse` into a clean
  * `none-present` pass.
  *
  * The ID-shape requirement (not "any bold bullet") is deliberate: a decisions
@@ -70,25 +168,35 @@ const bulletTitledColonRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([
  * bullets with bold labels (`- **Scope:** …`, `- **Why:** …`, `- **Note:** …`).
  * Those are NOT decision entries and must stay `none-present` — a false
  * `could-not-parse` hard-blocks the plan gate. `[A-Z]+[0-9]*-[A-Za-z0-9]` matches
- * `D-01` / `D5-01` / `DEC-01` but not `Scope:` / `Why:` / `Follow-up:` (mixed
+ * `D-01` / `D4-01` / `DEC-01` but not `Scope:` / `Why:` / `Follow-up:` (mixed
  * case) / `TODO:` (no `-<alnum>` id) — mirroring the parser's own `D-<alnum>`
  * shape without hardcoding the `D`.
+ *
+ * #4130 parity note: for the D-prefixed universe this detector's grammar
+ * (`D` + digit-run + `-` + alnum) is exactly `DECISION_ID_SOURCE` above, so a
+ * well-formed bullet the detector calls decision-shaped is now always one the
+ * extractor can read. The detector stays WIDER on purpose (`DEC-01` is still
+ * evidence): an ID grammar outside the parser's universe must keep failing
+ * loud, never silently passing. The #4130 property tests pin both directions.
  */
 const boldLeadInBulletRe = /^\s*-\s+\*\*[A-Z]+[0-9]*-[A-Za-z0-9]/m;
 /**
- * #3939: a decision bullet's DECLARATION line — the `- **D-NN … **` bold lead-in
- * the three grammars above anchor on — may wrap across a line break. Physical
- * line breaks inside a bullet are markdown-insignificant, and GSD's own
+ * #3939: a decision bullet's DECLARATION line — the `- **D[phase]-NN … **` bold
+ * lead-in the three grammars above anchor on — may wrap across a line break.
+ * Physical line breaks inside a bullet are markdown-insignificant, and GSD's own
  * discuss-phase writer emits the wrapped shape whenever a decision title runs
  * past the wrap column. All three grammars require the closing `**` in the same
- * string as the `- **D-` anchor, so a wrapped declaration matched none of them
+ * string as the `- **D…-` anchor, so a wrapped declaration matched none of them
  * and fell to the #1365 parse-miss guard, forcing `could-not-parse` (which
  * hard-blocks `check.decision-coverage-plan`) on a well-formed CONTEXT.md.
  *
  * The repair is confined to how the LOGICAL bullet is assembled — the grammars
  * themselves are untouched, so every single-line form parses exactly as before.
+ * #4130: the anchor uses `ID_ATTEMPT_SOURCE` (digit-run phase prefixes join
+ * like bare ones; recognising more start shapes only reassembles the logical
+ * bullet, which then parses or fails loud as itself).
  */
-const decisionBulletStartRe = /^\s*-\s+\*\*D-/;
+const decisionBulletStartRe = new RegExp(`^\\s*-\\s+\\*\\*${ID_ATTEMPT_SOURCE}`);
 /**
  * A line that opens a new BLOCK-LEVEL construct, and therefore terminates the
  * bullet above it: a list marker of any family (`-`, `*`, `+`, `1.`, `1)`), an
@@ -136,7 +244,8 @@ const blockConstructRe = /^(?:[-*+]\s|\d+[.)]\s|#{1,6}\s|>\s|\|)/;
  * to watch for a splice.
  *
  * The id character class is deliberately looser than the grammars' (it admits
- * an empty id, so a bare `- **D-` still counts as unsettled). This regex only
+ * an empty id, so a bare `- **D-` still counts as unsettled, and — #4130 — a
+ * digit-run phase prefix between the `D` and the first hyphen). This regex only
  * answers "may an id-adjacent bracket still open here?", where recognising MORE
  * shapes is the conservative direction: an over-broad match can only make a
  * malformed bullet fail loud, while a missed one silently re-classifies.
@@ -145,7 +254,7 @@ const blockConstructRe = /^(?:[-*+]\s|\d+[.)]\s|#{1,6}\s|>\s|\|)/;
  * into `tags` (and therefore into `trackable`). A `[` further along the title is
  * ordinary text and does not restrict the join.
  */
-const tagRegionRe = /^\s*-\s+\*\*D-[A-Za-z0-9_-]*\s*(?:\[([^\]]*))?$/;
+const tagRegionRe = new RegExp(`^\\s*-\\s+\\*\\*D[0-9]*-[A-Za-z0-9_-]*\\s*(?:\\[([^\\]]*))?$`);
 /**
  * #3939 (review): would folding `next` onto a lead-in whose `[tags]` bracket is
  * still open splice the inserted space INTO a tag token?
@@ -304,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();
@@ -347,11 +457,11 @@ function parseDecisionLines(block) {
             current.text += ' ' + trimmed;
             continue;
         }
-        // Colon form: `- **D-NN[ [tags]]:** text`
+        // Colon form: `- **D[phase]-NN[ [tags]]:** text`
         const colonMatch = line.match(bulletColonRe);
         if (colonMatch) {
             flush();
-            const id = `D-${colonMatch[1]}`;
+            const id = colonMatch[1];
             const tags = colonMatch[2]
                 ? colonMatch[2].split(',').map((t) => t.trim().toLowerCase()).filter(Boolean)
                 : [];
@@ -360,11 +470,11 @@ function parseDecisionLines(block) {
             openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
-        // Em-dash form: `- **D-NN[ [tags]] — title** body`
+        // Em-dash form: `- **D[phase]-NN[ [tags]] — title** body`
         const emDashMatch = line.match(bulletEmDashRe);
         if (emDashMatch) {
             flush();
-            const id = `D-${emDashMatch[1]}`;
+            const id = emDashMatch[1];
             const tags = emDashMatch[2]
                 ? emDashMatch[2].split(',').map((t) => t.trim().toLowerCase()).filter(Boolean)
                 : [];
@@ -376,14 +486,14 @@ function parseDecisionLines(block) {
             openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
-        // Titled-colon form: `- **D-NN[ [tags]]: Title.** body` (#1639). Checked LAST — it is
+        // Titled-colon form: `- **D[phase]-NN[ [tags]]: Title.** body` (#1639). Checked LAST — it is
         // a strict superset of bulletColonRe, so it only catches bullets the colon-immediate
         // and em-dash forms missed (minimal blast radius). id + [tags] trackability honored;
         // the body after the closing bold run is reported as text.
         const titledColonMatch = line.match(bulletTitledColonRe);
         if (titledColonMatch) {
             flush();
-            const id = `D-${titledColonMatch[1]}`;
+            const id = titledColonMatch[1];
             const tags = titledColonMatch[2]
                 ? titledColonMatch[2].split(',').map((t) => t.trim().toLowerCase()).filter(Boolean)
                 : [];
@@ -392,12 +502,21 @@ function parseDecisionLines(block) {
             openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
-        // Parse-miss guard (FIX B + #1343): a line that looks like a `D-NN` decision
-        // bullet but failed both patterns — flush, warn, and record the miss.
+        // Parse-miss guard (FIX B + #1343, grammar widened #4130): a line whose bold
+        // lead-in ATTEMPTS the ID grammar but failed all three patterns — flush,
+        // warn, and record the miss. `ID_ATTEMPT_SOURCE` accepts the bare `D-` form
+        // (as before) plus a digit-initial prefix run, so a typo'd phase prefix
+        // (`D4x-01`) fails loud instead of silently vanishing, while a letter-initial
+        // run (`Deferred-until`) stays prose and stays invisible.
         // parseMisses > 0 forces could-not-parse even when other decisions parsed.
-        if (/^\s*-\s+\*\*D-/.test(line)) {
+        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;
         }
@@ -413,7 +532,7 @@ function parseDecisionLines(block) {
         }
     }
     flush();
-    return { decisions: out, parseMisses };
+    return { decisions: out, parseMisses, unreadableIds };
 }
 // ─── Primary entry point: extractDecisions ────────────────────────────────────
 /**
@@ -438,21 +557,21 @@ 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
         // that failed to parse: a bold-lead-in bullet (`- **…**`, any ID grammar — #2347),
-        // a \bD- token in the block text, or an unterminated fence. An empty scaffold
+        // a bare `D[phase]-<alnum>` token (#4130) in the block text, or an unterminated fence. An empty scaffold
         // (<decisions></decisions>) or an all-prose block has no such evidence — treat
         // as none-present so the gate passes cleanly.
-        const hasDecisionTokenInBlock = /\bD-[A-Za-z0-9]/m.test(combined);
+        const hasDecisionTokenInBlock = decisionTokenRe.test(combined);
         const hasBoldLeadInBullet = boldLeadInBulletRe.test(combined);
         if (hasDecisionTokenInBlock || hasBoldLeadInBullet || unterminatedFence) {
             return { decisions: [], outcome: 'could-not-parse' };
@@ -465,20 +584,20 @@ 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
-        // bold-lead-in bullet (`- **…**`, any ID grammar — #2347) or a D- token. A
+        // bold-lead-in bullet (`- **…**`, any ID grammar — #2347) or a `D[phase]-<alnum>` token (#4130). A
         // heading with only prose, sub-headings, or all-discretion content (no such
         // evidence) is a legitimate empty/discretion section → none-present.
-        const hasDecisionTokenInSection = /\bD-[A-Za-z0-9]/m.test(section.body);
+        const hasDecisionTokenInSection = decisionTokenRe.test(section.body);
         const hasBoldLeadInBulletInSection = boldLeadInBulletRe.test(section.body);
         if (hasDecisionTokenInSection || hasBoldLeadInBulletInSection) {
             return { decisions: [], outcome: 'could-not-parse' };
@@ -487,8 +606,8 @@ function extractDecisions(content) {
     }
     // ── Path 3: no blocks, no heading ────────────────────────────────────────────
     // Apply shape heuristics to distinguish none-present from could-not-parse.
-    // We re-use the already-computed unterminatedFence and check for D- tokens.
-    const hasDecisionToken = /\bD-[A-Za-z0-9]/m.test(stripped);
+    // We re-use the already-computed unterminatedFence and check for decision tokens.
+    const hasDecisionToken = decisionTokenRe.test(stripped);
     if (unterminatedFence || hasDecisionToken) {
         return { decisions: [], outcome: 'could-not-parse' };
     }

package/gsd-core/bin/lib/external-descriptor-trust.cjs

@@ -18,13 +18,10 @@
  * concern sharing the word "trust".
  */
 'use strict';
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPathConfined = isPathConfined;
 exports.assertDescriptorConfined = assertDescriptorConfined;
-const node_path_1 = __importDefault(require("node:path"));
+const security_cjs_1 = require("./security.cjs");
 /**
  * Pure LEXICAL path-containment check (cross-platform). `target` is confined
  * to `root` iff resolving it relative to `root` (via `path.resolve` — string
@@ -36,20 +33,38 @@ const node_path_1 = __importDefault(require("node:path"));
  * `root`) that would redirect the LEXICALLY-confined path to a physically
  * different, unconfined location on disk. A caller relying on this for a
  * write-confinement guarantee against a symlink-planting attacker must pair
- * it with a symlink check (or refuse to follow symlinks at write time) — see
- * capability-source.cts's install adapters (:491,577,675), which is what
- * currently keeps every caller of this function's callers symlink-safe: they
- * reject symlinks upstream, before a target ever reaches a lexical-only check
- * like this one.
+ * it with a symlink check (or refuse to follow symlinks at write time). Only
+ * the capability-loader.cts route into assertDescriptorConfined gets this for
+ * free today: capability-source.cts's staging path rejects symlinks upstream,
+ * before a target ever reaches a lexical-only check like this one — see
+ * copyDirRecursive's `entry.isSymbolicLink()` throw (capability-source.cts:585-586)
+ * and the post-copy budget-walk re-check (capability-source.cts:671-674). This
+ * does NOT extend to isPathConfined's other callers: install-engine.cts:1608
+ * and install-profiles.cts:755,880 do not go through capability-source.cts's
+ * adapters at all and have no symlink guard of their own here. Of the
+ * remaining callers, only retired-artifact-cleanup.cts:69 carries its own
+ * defense, via a local `lstatSync(destDir).isSymbolicLink()` check at line 77.
+ *
+ * `opts.pathImpl` (default: the ambient `path` module) lets a caller inject
+ * `path.win32` or `path.posix`. This is security-relevant: the win32 branch
+ * (drive letters, UNC paths, `\` separator) is otherwise only reachable by
+ * actually running this process on a Windows host, so without injection a
+ * win32-specific confinement escape would be unverified on every other
+ * platform. This mirrors the platform-injection seam already used elsewhere
+ * in this repo, e.g. src/shell-command-projection.cts's `opts.platform`
+ * (#4641). All existing 2-arg callers are unaffected: the default resolves to
+ * the ambient `path`, preserving byte-identical behaviour.
+ *
+ * The containment DECISION here now comes from the canonical predicate in
+ * src/security.cts (`tryWithinRootLexical`, ADR-4650 decision 6) — this
+ * function keeps only the lexical RESOLUTION policy (no realpath, no
+ * filesystem access) as its own choice; the comparison itself is shared.
  */
-function isPathConfined(target, root) {
+function isPathConfined(target, root, opts = {}) {
     if (typeof target !== 'string' || typeof root !== 'string' || target.length === 0 || root.length === 0) {
         return false;
     }
-    const rootResolved = node_path_1.default.resolve(root);
-    const targetResolved = node_path_1.default.resolve(root, target);
-    const prefix = rootResolved + node_path_1.default.sep;
-    return targetResolved === rootResolved || targetResolved.startsWith(prefix);
+    return (0, security_cjs_1.tryWithinRootLexical)(target, root, { pathImpl: opts.pathImpl }) !== null;
 }
 /**
  * Assert every destSubpath the descriptor declares (global + local artifact

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

@@ -1394,6 +1394,14 @@ function cmdFrontmatterGet(cwd, filePath, field, raw) {
     // Pass the resolved path so a truncated file is named in the diagnostic and deduplicated
     // per file rather than per content digest (#1882, ADR-1411 wiring clause).
     const fm = extractFrontmatter(content, fullPath);
+    // #4806: an unparseable frontmatter block is a distinct outcome — the file
+    // HAS a frontmatter block but its YAML failed to parse. Reporting
+    // "Field not found" tells the caller the key is absent, which is
+    // indistinguishable from a file that genuinely lacks it.
+    if (fm[FRONTMATTER_UNPARSEABLE] === true) {
+        output({ error: 'Frontmatter is not parseable YAML — fix the syntax error in the frontmatter block', path: filePath }, raw, undefined);
+        return;
+    }
     if (field) {
         const value = fm[field];
         if (value === undefined) {
@@ -1649,4 +1657,9 @@ module.exports = {
     cmdFrontmatterMerge,
     cmdFrontmatterValidate,
     propagateCommentChannel,
+    // #4917 / ADR-4910 Decision 1: additive-only export so `planning-document.cts`
+    // can COMPOSE this seam's fence-detection grammar (byte-0 rule, BOM strip,
+    // CR handling) instead of reimplementing it. No behavior change — same
+    // function `extractFrontmatter`/`frontmatterListEntries` already call.
+    frontmatterRegion,
 };

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

@@ -445,14 +445,17 @@ function graphifyStatus(cwd) {
         return disabledResponse();
     const { graphPath, configured } = resolveGraphLocation(cwd, planningDir);
     if (!node_fs_1.default.existsSync(graphPath)) {
-        return { exists: false, message: configured
+        return { exists: false, graph_path: graphPath, message: configured
                 ? `Configured graph not found at ${graphPath}. Set graphify.graph_path or run /gsd:graphify build.`
                 : 'No graph built yet. Run graphify build to create one.' };
     }
     const stat = node_fs_1.default.statSync(graphPath);
     const graph = safeReadJson(graphPath);
     if (!graph) {
-        return { error: 'Failed to parse graph.json' };
+        // Still surface graph_path (#4836 Minor 1): callers gate on `exists`, not
+        // on this outcome, so without it they'd fall through to the CLI-first
+        // branch with no --graph value to substitute for the <graph> placeholder.
+        return { error: 'Failed to parse graph.json', graph_path: graphPath };
     }
     const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
     const age = Date.now() - stat.mtimeMs;
@@ -482,6 +485,11 @@ function graphifyStatus(cwd) {
         (lastBuildAutoUpdate.status === 'failed' || lastBuildAutoUpdate.status === 'running');
     return {
         exists: true,
+        // The absolute location the whole graphify surface reads, already resolved
+        // through `graphify.graph_path` (#1825). Callers that shell out to the
+        // graphify CLI pass this as `--graph` so the umbrella override is honoured
+        // there too, instead of re-deriving `.planning/graphs/graph.json` (#4836).
+        graph_path: graphPath,
         last_build: stat.mtime.toISOString(),
         node_count: (graph.nodes || []).length,
         edge_count: (graph.edges || graph.links || []).length,

package/gsd-core/bin/lib/gsd2-import.cjs

@@ -307,8 +307,7 @@ function buildStateMd(phaseMap) {
     const currentPhaseNum = currentEntry ? zeroPad(currentEntry.phaseNum) : zeroPad(totalPhases);
     const currentSlug = currentEntry ? slugify(currentEntry.slice.title) : 'complete';
     const status = currentEntry ? 'Ready to plan' : 'All phases complete';
-    const filled = Math.round(pct / 10);
-    const bar = `[${'█'.repeat(filled)}${'░'.repeat(10 - filled)}]`;
+    const bar = `[${(0, phase_lifecycle_cjs_1.renderProgressBar)(pct, 10)}]`;
     const today = clock_cjs_1.realClock.localToday();
     return [
         '# Project State',

package/gsd-core/bin/lib/health-diagnostic-rules/state-consistency.cjs

@@ -158,6 +158,17 @@ const RULE_W002 = {
         const normalizedValid = normalizePhaseTokenSet(validPhases);
         const sortedValid = [...validPhases].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
         const diagnostics = [];
+        // #4257: the valid set above is WORKSTREAM-scoped by construction (every
+        // source field is read from `planningPaths(cwd)`'s base, which resolves
+        // under `.planning/workstreams/<active-ws>/`), and per-workstream phase
+        // numbering is deliberate — so under a workstream the message must NAME
+        // that scope rather than make an unqualified project-wide claim (a
+        // reference to a phase declared only in a SIBLING workstream reads as
+        // "undeclared" against this list; that is the scope speaking, not drift).
+        // Root scope (`workstream === null`, flat or root-planning projects)
+        // keeps the byte-identical message — no clause is appended when none
+        // applies.
+        const scopeClause = snapshot.workstream ? ` in workstream ${snapshot.workstream}` : '';
         for (const ref of snapshot.statePhaseTokens.value) {
             const dotIdx = ref.indexOf('.');
             const head = dotIdx === -1 ? ref : ref.slice(0, dotIdx);
@@ -168,7 +179,7 @@ const RULE_W002 = {
             diagnostics.push({
                 code: 'W002',
                 severity: SEVERITY.WARNING,
-                message: `STATE.md references phase ${ref}, but only phases ${sortedValid.join(', ')} are declared`,
+                message: `STATE.md references phase ${ref}, but only phases ${sortedValid.join(', ')} are declared${scopeClause}`,
                 remedy: adviseRemedy('Review STATE.md manually before changing it; /gsd-health --repair will not overwrite an existing STATE.md for phase mismatches'),
             });
         }

package/gsd-core/bin/lib/health-diagnostic-rules/worktree-health.cjs

@@ -135,7 +135,7 @@ function checkW017(snapshot) {
 function isActiveWorktreePath(activeCwd, worktreePath, platform = process.platform) {
     const active = shellCmdProjection.toComparablePathKey(activeCwd, platform);
     const worktree = shellCmdProjection.toComparablePathKey(worktreePath, platform);
-    return active === worktree || active.startsWith(worktree + '/');
+    return active === worktree || active.startsWith(worktree + '/'); // allow-handrolled-containment: worktree identity matching, not a containment gate
 }
 function checkW027(snapshot) {
     const diagnostics = [];

package/gsd-core/bin/lib/host-runtime-detection.cjs

@@ -24,6 +24,7 @@ exports.resolveReportedRuntime = resolveReportedRuntime;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 const update_context_cjs_1 = require("./update-context.cjs");
 Object.defineProperty(exports, "CODEX_CONFIG_MARKER", { enumerable: true, get: function () { return update_context_cjs_1.CODEX_CONFIG_MARKER; } });
 // Codex sandbox env vars set by the shell tool / Seatbelt child-process spawn.
@@ -127,6 +128,14 @@ function resolveReportedRuntimeUnsafe(projectDir, deps) {
     const explicit = (0, runtime_slash_cjs_1.resolveExplicitRuntime)(projectDir, deps?.env ?? process.env);
     if (explicit)
         return explicit;
+    // #4717: the per-install marker names the runtime that owns THIS tree — a
+    // stronger signal than host sniffing, which misreports every session on a
+    // multi-runtime machine (e.g. a globally exported CODEX_HOME makes a Claude
+    // Code session read as codex). Marker-less trees (dev/source, pre-#2297
+    // installs) fall through to host detection unchanged.
+    const marker = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)((0, runtime_slash_cjs_1.readInstallRuntimeMarker)());
+    if (marker)
+        return marker;
     const detected = detectHostRuntime(deps);
     if (detected.runtime)
         return detected.runtime;