@opengsd/gsd-core 1.14.0 → 1.15.0

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

@@ -269,5 +269,53 @@ function parsePlanDocument(content, planPath = '') {
         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/planning-document.cjs

@@ -0,0 +1,459 @@
+"use strict";
+/**
+ * Planning Document — the parse -> mutate -> serialize seam for a `.planning/`
+ * root artifact BODY (ADR-4910, epic #4906 Phase 1, #4917).
+ *
+ * Composes the existing structural seams — never reimplements them:
+ *  - `markdown-sectionizer.cjs` (`tokenizeHeadings`, `collectSections`,
+ *    `scanFencedBlocks`, `scanInlineCodeSpans`) for headings/sections and
+ *    fence/inline-code awareness.
+ *  - `markdown-table.cjs` (`splitTableRow`, `isDelimiterRow`,
+ *    `parseMarkdownTable`) for GFM table detection and validation.
+ *  - `artifacts.cjs` (`isCanonicalPlanningFile`) for the artifact-kind gate.
+ *
+ * This phase migrates NO call site — it is purely additive (ADR-4910 §7).
+ * Only `boldField` nodes are writable; `table`/`checklist` nodes parse and
+ * read only. Phase 3 (#4958) checked its own evidence (#4736, #4793) and
+ * found neither needed a table/checklist writer here — see ADR-4910's
+ * 2026-09-24 amendment. A writer for either kind is unclaimed until a real
+ * call site names it.
+ *
+ * Hyrum's Law commitment (row 3 of the design's behaviour table): `serialize`
+ * with zero staged edits returns `doc.source` BYTE-IDENTICAL — never a
+ * re-render (#4499's root cause). Every byte outside an edited `valueSpan` is
+ * the ORIGINAL source, spliced, never regenerated.
+ *
+ * ADR-457 build-at-publish: source in src/planning-document.cts, compiled to
+ * gsd-core/bin/lib/planning-document.cjs (gitignored).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLANNING_ARTIFACTS = void 0;
+exports.parsePlanningDoc = parsePlanningDoc;
+exports.findField = findField;
+exports.readNode = readNode;
+exports.setFieldValue = setFieldValue;
+exports.hasUnreadableNodes = hasUnreadableNodes;
+exports.serialize = serialize;
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const markdown_table_cjs_1 = require("./markdown-table.cjs");
+const artifacts_cjs_1 = require("./artifacts.cjs");
+// `frontmatter.cts` uses `export =` (CJS-style single export object), so it
+// is imported as a default import (esModuleInterop), not a named import.
+const frontmatter_cjs_1 = __importDefault(require("./frontmatter.cjs"));
+const { frontmatterRegion } = frontmatter_cjs_1.default;
+/**
+ * Canonical `.planning/` root artifact basenames this seam recognises,
+ * derived from the SAME registry `isCanonicalPlanningFile` consults
+ * (`artifacts.cts`'s `CANONICAL_EXACT`) — never a second, independently
+ * maintained list.
+ *
+ * Filtered to `.md` names only: `CANONICAL_EXACT` also carries non-markdown
+ * artifacts (`config.json`, `state.json`, `milestone.lock`, …) that this
+ * parser has no grammar for. Handing that JSON/lock content to the markdown
+ * parser below returns a successful EMPTY document (`nodes: []`), which reads
+ * as "this document records nothing" when the truth is "wrong kind entirely"
+ * — the empty-vs-error confusion #4917 / ADR-4910 §5 exists to eliminate. Do
+ * NOT remove this filter to "restore" the full registry.
+ */
+exports.PLANNING_ARTIFACTS = Object.freeze(Array.from(artifacts_cjs_1.CANONICAL_EXACT).filter((name) => name.endsWith('.md')));
+// ─── Internal helpers ───────────────────────────────────────────────────────
+let nodeCounter = 0;
+function mintId(kind) {
+    nodeCounter += 1;
+    return `${kind}-${nodeCounter}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function splitLinesInfo(source) {
+    const out = [];
+    let offset = 0;
+    const rawLines = source.split('\n');
+    for (let i = 0; i < rawLines.length; i++) {
+        const raw = rawLines[i];
+        const hasCR = raw.endsWith('\r');
+        const text = hasCR ? raw.slice(0, -1) : raw;
+        out.push({ text, start: offset, end: offset + text.length });
+        offset += raw.length + 1; // +1 for the '\n' split on ('\r' already counted in raw.length)
+    }
+    return out;
+}
+/**
+ * Locate the frontmatter block, if any, by COMPOSING `frontmatter.cts`'s
+ * `frontmatterRegion` — the fence-detection grammar (byte-0 rule, BOM strip,
+ * `\n---` search, CR handling) lives there, once, and this seam never
+ * re-derives it (ADR-4910 Decision 1).
+ *
+ * `frontmatterRegion` reports the YAML body's own bounds (`region`,
+ * `terminated`, and the possibly BOM-stripped `content`), not this seam's
+ * `Span` shape (an absolute byte range into the UNSTRIPPED `source`,
+ * inclusive of both fences). This adapter translates one into the other by
+ * reading ONLY the two boundary characters `frontmatterRegion` already
+ * anchored (whether the YAML end / closing fence sit on a CRLF line) — it
+ * does not re-scan for the fences themselves.
+ */
+function findFrontmatterSpan(source) {
+    const found = frontmatterRegion(source);
+    if (!found)
+        return null;
+    // `found.content` may be `source` with a single leading BOM stripped;
+    // every offset below is relative to `found.content`, so translate back to
+    // `source` coordinates by the same delta.
+    const bomDelta = source.length - found.content.length;
+    const content = found.content;
+    if (!found.terminated) {
+        return { span: { start: bomDelta, end: bomDelta + content.length }, terminated: false };
+    }
+    // `frontmatterRegion` already did fence DETECTION — `found` being non-null
+    // and `terminated` IS that result. It reports only the YAML body's bounds
+    // (`region`), not an absolute span, so recover the closing fence's end
+    // from `region`'s length. The one thing still read directly here is the
+    // opening fence's fixed-width line ending (`\n` vs `\r\n`), needed to
+    // translate `region`'s length into a `content` offset — not a re-scan for
+    // the fence itself.
+    const headerEnd = content.startsWith('---\r\n') ? 5 : 4;
+    const yamlEnd = headerEnd + found.region.length;
+    const closingLineStart = content[yamlEnd] === '\r' ? yamlEnd + 1 : yamlEnd;
+    const fenceLineStart = closingLineStart + 1;
+    let fenceEnd = fenceLineStart + 3;
+    if (content[fenceEnd] === '\r')
+        fenceEnd += 1;
+    return { span: { start: bomDelta, end: bomDelta + fenceEnd }, terminated: true };
+}
+/** Build the set of 0-based line indices that fall inside a fenced code
+ * block (opening/closing delimiter lines included), so `**Label:**`/table/
+ * checklist scanning never treats fenced content as a node (rows 9/14). */
+function fencedLineIndices(lines) {
+    const raw = lines.map((l) => l.text);
+    const blocks = (0, markdown_sectionizer_cjs_1.scanFencedBlocks)(raw);
+    const set = new Set();
+    for (const b of blocks) {
+        const end = b.closeLineIdx === -1 ? raw.length - 1 : b.closeLineIdx;
+        for (let i = b.openLineIdx; i <= end; i++)
+            set.add(i);
+    }
+    return set;
+}
+/** Matches both shipped bold-field spellings: colon-inside (`**Label:**`,
+ * the original grammar) and colon-outside (`**Label**:`, the canonical form
+ * used throughout `templates/roadmap.md`). Each alternative's trailing
+ * marker is exactly 3 characters (`:**` or `**:`), so `token.slice(2, -3)`
+ * in `parseBoldFieldLine` strips the leading `**` and the spelling-specific
+ * trailing marker identically for both, yielding the same `label` either
+ * way. Deliberately excludes a bare unbolded `Label:` form — see Phase 1's
+ * prose-vs-field disambiguation design. */
+const BOLD_FIELD_RE = /^(\s*)(\*\*[^*\r\n]+(?::\*\*|\*\*:))([ \t]*)([^\r\n]*)$/;
+/** Boundary marking a hand-written trailing annotation on a field line —
+ * the token owner must never destroy prose past this separator. */
+const TRAILING_SEPARATOR_RE = / — /;
+function parseBoldFieldLine(line) {
+    const m = BOLD_FIELD_RE.exec(line.text);
+    if (!m)
+        return null;
+    const [, leading, token, spacing, rest] = m;
+    const labelStart = line.start + leading.length;
+    const labelSpan = { start: labelStart, end: labelStart + token.length };
+    const label = token.slice(2, -3);
+    const restStart = labelSpan.end + spacing.length;
+    const sepMatch = TRAILING_SEPARATOR_RE.exec(rest);
+    const valueRaw = sepMatch ? rest.slice(0, sepMatch.index) : rest;
+    const trimmedValue = valueRaw.replace(/\s+$/, '');
+    const valueSpan = { start: restStart, end: restStart + trimmedValue.length };
+    const trailingSpan = { start: valueSpan.end, end: line.end };
+    return {
+        kind: 'boldField',
+        id: mintId('boldField'),
+        span: { start: labelSpan.start, end: line.end },
+        error: null,
+        label,
+        labelSpan,
+        valueSpan,
+        trailingSpan,
+        value: trimmedValue,
+    };
+}
+/** A checklist line is one whose SOLE bullet, per `iterateBullets` (the same
+ * grammar the repo's other bullet consumers use), is a checkbox marker, OR
+ * whose bullet TEXT begins with a task-list marker.
+ *
+ * `iterateBullets` owns bullet *structure* — is this a bullet, where does its
+ * text start — and continues to own that here unchanged. It only classifies
+ * `-`-prefixed bullets as `checkbox-checked`/`checkbox-unchecked`; GFM also
+ * permits `*` and `+` as bullet markers, and `* [ ] x` / `+ [x] y` are valid
+ * GFM task-list items that `iterateBullets` reports as plain `dash`-family
+ * bullets with the `[ ]`/`[x]` left in the bullet's own text. Widening
+ * `iterateBullets` itself is forbidden by ADR-2143 §2's extend-never-mutate
+ * lock (inherited by this epic), so the task-list-marker interpretation is
+ * layered on here, over the bullet's already-extracted text — never by
+ * re-scanning the raw line with a new hand-rolled regex.
+ *
+ * Known limit inherited from `iterateBullets`, not introduced here:
+ * `-\t[ ] text` (a tab between the marker and the text) is not recognised as
+ * a bullet at all, so it can never become a checklist line. That is a
+ * pre-existing `markdown-sectionizer` boundary affecting every consumer of
+ * `iterateBullets`, and fixing it would mean altering the locked seam. */
+function isChecklistLine(text) {
+    const items = (0, markdown_sectionizer_cjs_1.iterateBullets)(text);
+    if (items.length !== 1)
+        return false;
+    const item = items[0];
+    if (item.marker === 'checkbox-checked' || item.marker === 'checkbox-unchecked')
+        return true;
+    return /^\[[ xX]\] /.test(item.text);
+}
+/**
+ * Scan the document body (everything outside the frontmatter block and
+ * outside fenced code) for `boldField`, `table`, and `checklist` nodes, in
+ * document order.
+ */
+function scanBodyNodes(source, lines, frontmatterEnd) {
+    const fenced = fencedLineIndices(lines);
+    const nodes = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (fenced.has(i) || line.start < frontmatterEnd) {
+            i += 1;
+            continue;
+        }
+        const trimmed = line.text.trim();
+        // Table: a pipe-shaped header line followed by a valid delimiter row.
+        if (trimmed.startsWith('|') && trimmed.indexOf('|', 1) !== -1 && i + 1 < lines.length) {
+            const delimiterLine = lines[i + 1];
+            const delimiterCells = (0, markdown_table_cjs_1.splitTableRow)(delimiterLine.text);
+            const headerCells = (0, markdown_table_cjs_1.splitTableRow)(line.text);
+            if (delimiterLine.text.trim().startsWith('|')
+                && (0, markdown_table_cjs_1.isDelimiterRow)(delimiterCells)
+                && delimiterCells.length === headerCells.length
+                && !fenced.has(i + 1)) {
+                let last = i + 1;
+                while (last + 1 < lines.length && lines[last + 1].text.trim().startsWith('|') && !fenced.has(last + 1)) {
+                    last += 1;
+                }
+                const span = { start: line.start, end: lines[last].end };
+                const tableText = source.slice(span.start, span.end);
+                const parsed = (0, markdown_table_cjs_1.parseMarkdownTable)(tableText);
+                nodes.push(parsed.ok
+                    ? {
+                        kind: 'table',
+                        id: mintId('table'),
+                        span,
+                        error: null,
+                        columns: parsed.value.columns,
+                    }
+                    : {
+                        kind: 'table',
+                        id: mintId('table'),
+                        span,
+                        error: { reason: parsed.reason, span },
+                        columns: null,
+                    });
+                i = last + 1;
+                continue;
+            }
+        }
+        // Checklist: a contiguous run of checkbox-bullet lines.
+        if (isChecklistLine(line.text)) {
+            let last = i;
+            let count = 0;
+            while (last < lines.length && !fenced.has(last) && isChecklistLine(lines[last].text)) {
+                count += 1;
+                last += 1;
+            }
+            last -= 1;
+            const span = { start: line.start, end: lines[last].end };
+            nodes.push({ kind: 'checklist', id: mintId('checklist'), span, error: null, items: count });
+            i = last + 1;
+            continue;
+        }
+        // Bold field.
+        const field = parseBoldFieldLine(line);
+        if (field) {
+            nodes.push(field);
+            i += 1;
+            continue;
+        }
+        i += 1;
+    }
+    return nodes;
+}
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Parse `source` (the raw text of a `.planning/` root artifact) into a
+ * `PlanningDoc`. Document-level `Result` failure is reserved for: `artifact`
+ * not a recognised planning artifact kind, `source` not a readable string, or
+ * an opened-but-never-closed frontmatter fence (ADR-4910 §5's reservation).
+ * A malformed SUB-structure (a ragged table, say) never fails the whole
+ * document — it is recorded as that one node's `error`, and every sibling
+ * node stays readable (row 7). `nodes: []` on a genuinely empty document is
+ * success, not an error (row 15).
+ */
+function parsePlanningDoc(source, artifact) {
+    if (typeof source !== 'string') {
+        return { ok: false, reason: 'unreadable: source is not a string' };
+    }
+    if (typeof artifact !== 'string' ||
+        !(0, artifacts_cjs_1.isCanonicalPlanningFile)(artifact) ||
+        !exports.PLANNING_ARTIFACTS.includes(artifact)) {
+        return {
+            ok: false,
+            reason: `not a markdown planning document (artifact: ${String(artifact)})`,
+        };
+    }
+    const nodes = [];
+    let frontmatterEnd = 0;
+    const fm = findFrontmatterSpan(source);
+    if (fm) {
+        if (!fm.terminated) {
+            return { ok: false, reason: 'no frontmatter terminator' };
+        }
+        nodes.push({ kind: 'frontmatter', id: mintId('frontmatter'), span: fm.span, error: null });
+        frontmatterEnd = fm.span.end;
+    }
+    if (source.length === 0) {
+        return { ok: true, value: { source, artifact, nodes: [], staged: new Map() } };
+    }
+    const lines = splitLinesInfo(source);
+    // Sections: one per heading, in document order — every heading is its own
+    // boundary (`collectSections(source, () => true)`), so a nested `####`
+    // still gets its own SectionNode rather than being folded into its parent.
+    const headings = (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(source);
+    if (headings.length > 0) {
+        const sections = (0, markdown_sectionizer_cjs_1.collectSections)(source, () => true);
+        for (const s of sections) {
+            nodes.push({
+                kind: 'section',
+                id: mintId('section'),
+                span: { start: s.heading.offset, end: s.bodyEnd },
+                error: null,
+                heading: s.heading.text,
+                level: s.heading.level,
+            });
+        }
+    }
+    nodes.push(...scanBodyNodes(source, lines, frontmatterEnd));
+    nodes.sort((a, b) => a.span.start - b.span.start);
+    return { ok: true, value: { source, artifact, nodes, staged: new Map() } };
+}
+/** Find the id of the (first, document-order) `boldField` node whose label
+ * exactly matches `label`, or `null` when none does. */
+function findField(doc, label) {
+    for (const n of doc.nodes) {
+        if (n.kind === 'boldField' && n.label === label)
+            return n.id;
+    }
+    return null;
+}
+/** Read a node by id. Node-scoped failure only — an unknown id or a node
+ * that failed to parse never throws. */
+function readNode(doc, id) {
+    const node = doc.nodes.find((n) => n.id === id);
+    if (!node) {
+        return { ok: false, reason: 'unknown node id', span: { start: 0, end: 0 } };
+    }
+    if (node.error) {
+        return { ok: false, reason: node.error.reason, span: node.error.span };
+    }
+    if (node.kind === 'boldField') {
+        return { ok: true, value: doc.staged.get(id) ?? node.value };
+    }
+    return { ok: true, value: doc.source.slice(node.span.start, node.span.end) };
+}
+/**
+ * Stage a new value for a `boldField` node, returning a NEW `PlanningDoc`
+ * (immutable — `doc` itself is never mutated). Refuses an id this doc did
+ * not mint, and refuses any node kind other than `boldField` — only the
+ * `valueSpan` is ever writable this phase (ADR-4910 §1).
+ */
+function setFieldValue(doc, id, value) {
+    const node = doc.nodes.find((n) => n.id === id);
+    if (!node) {
+        return { ok: false, reason: 'unknown node id' };
+    }
+    if (node.kind !== 'boldField') {
+        return { ok: false, reason: `node kind '${node.kind}' is not writable this phase` };
+    }
+    // #4917 / ADR-4910 Decision 2 & 4: a boldField's token boundary is a LINE
+    // boundary, not just an offset range — a value containing \n or \r escapes
+    // the field's own span and reparses as sibling structure (a forged field)
+    // once spliced back into the source. Decision 4 licenses refusal for any
+    // value the grammar cannot represent; Phase 3 may widen this to escaping,
+    // but Phase 1 refuses outright. Do not remove this as an over-restriction.
+    if (/[\r\n]/.test(value)) {
+        return { ok: false, reason: 'field value must not contain a line break (\\r or \\n)' };
+    }
+    // #4917 / ADR-4910 Decision 4: "a value that cannot be represented in the
+    // grammar is refused by the writer, with a report." This is a GENERAL
+    // round-trip representability check, not a blacklist of forbidden
+    // substrings — the `\r`/`\n` guard above is a narrower special case kept
+    // for its clearer message, but THIS check is the backstop. It rebuilds the
+    // line exactly as it would be written (existing leading/label/spacing +
+    // the new value + the existing trailing text) and re-parses that line
+    // through the SAME `parseBoldFieldLine` grammar the reader uses. If the
+    // value the grammar reads back is not byte-identical to what the caller
+    // staged, the grammar cannot represent this value (e.g. it contains the
+    // ` — ` trailing-separator token, which would silently reclassify the
+    // rest of the value as trailing prose) and the write is refused. Do NOT
+    // replace this with a list of forbidden characters/substrings — the next
+    // separator the grammar grows would silently slip past a blacklist.
+    const leadingText = doc.source.slice(node.span.start, node.labelSpan.start);
+    const tokenText = doc.source.slice(node.labelSpan.start, node.labelSpan.end);
+    const spacingText = doc.source.slice(node.labelSpan.end, node.valueSpan.start);
+    const trailingText = doc.source.slice(node.trailingSpan.start, node.trailingSpan.end);
+    const candidateLine = `${leadingText}${tokenText}${spacingText}${value}${trailingText}`;
+    const candidateInfo = { text: candidateLine, start: 0, end: candidateLine.length };
+    const reparsed = parseBoldFieldLine(candidateInfo);
+    if (!reparsed || reparsed.value !== value) {
+        return {
+            ok: false,
+            reason: 'field value is not representable in the boldField grammar (would not round-trip)',
+        };
+    }
+    const staged = new Map(doc.staged);
+    staged.set(id, value);
+    return { ok: true, value: { source: doc.source, artifact: doc.artifact, nodes: doc.nodes, staged } };
+}
+/** True when any node in `doc` failed to parse. */
+function hasUnreadableNodes(doc) {
+    return doc.nodes.some((n) => n.error !== null);
+}
+/**
+ * Splice every staged edit into `doc.source` and return the resulting text.
+ * With zero staged edits, returns `doc.source` BYTE-IDENTICAL — never a
+ * re-render (row 3). Refuses outright — even with zero staged edits — when
+ * `hasUnreadableNodes(doc)` is true (the ADR-4910 amendment): `serialize`
+ * re-emits the WHOLE document, so the refusal is document-scoped, not
+ * mutation-scoped.
+ */
+function serialize(doc) {
+    if (hasUnreadableNodes(doc)) {
+        return {
+            ok: false,
+            reason: 'unreadable-nodes',
+            nodes: doc.nodes
+                .filter((n) => n.error !== null)
+                .map((n) => ({ id: n.id, kind: n.kind, span: n.error.span, reason: n.error.reason })),
+        };
+    }
+    if (doc.staged.size === 0) {
+        return { ok: true, value: doc.source };
+    }
+    const edits = [];
+    for (const [id, value] of doc.staged) {
+        const node = doc.nodes.find((n) => n.id === id);
+        if (!node || node.kind !== 'boldField')
+            continue; // unreachable: setFieldValue already gated this
+        edits.push({ start: node.valueSpan.start, end: node.valueSpan.end, value });
+    }
+    edits.sort((a, b) => a.start - b.start);
+    let out = '';
+    let cursor = 0;
+    for (const e of edits) {
+        out += doc.source.slice(cursor, e.start) + e.value;
+        cursor = e.end;
+    }
+    out += doc.source.slice(cursor);
+    return { ok: true, value: out };
+}
+// Consumers: require('../gsd-core/bin/lib/planning-document.cjs')
+// Named CJS exports are the canonical surface (ADR-457 .cts → .cjs build-at-publish).

package/gsd-core/bin/lib/planning-inspect.cjs

@@ -917,7 +917,24 @@ function extractDependencyTokens(sectionBody) {
     const m = DEPENDS_ON_LINE_RE.exec(sectionBody);
     if (!m)
         return [];
-    return sortedUnique([...m[1].matchAll(/\d+(?:\.\d+)*/g)].map((t) => t[0]));
+    // #4764: phase REFERENCES, not digit runs — the same prose-anchored grammar
+    // init.manager's dep_phases extraction uses (owner: phase-id.cts's
+    // PHASE_DEP_REF_SOURCE). The whole-field token scrape this replaces pulled
+    // calendar dates, git shas and ledger ids in as dependencies. The grammar's
+    // capture group 1 already excludes the "Phase(s)" anchor word, so no
+    // prefix-strip literal is needed here. Self-exclusion (init.manager drops
+    // the row's own number) is deliberately NOT applied: this reader has no row
+    // context at the extraction site and reports informationally, it does not
+    // gate.
+    const refRe = new RegExp(phaseIdMod.PHASE_DEP_REF_SOURCE, 'gi');
+    const tokenRe = new RegExp(phaseIdMod.PHASE_NUMBER_TOKEN_SOURCE, 'g');
+    const tokens = [];
+    let refMatch;
+    while ((refMatch = refRe.exec(m[1])) !== null) {
+        for (const t of refMatch[1].matchAll(tokenRe))
+            tokens.push(t[0]);
+    }
+    return sortedUnique(tokens);
 }
 /**
  * This phase's own ROADMAP.md section body — milestone-scoped via the SAME

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -114,13 +114,18 @@ const PLANNING_LOCK_RETRY_ERRNOS = new Set([
  * two-readers-two-bases lesson).
  */
 function resolveEnvWorkstream() {
-    return process.env['GSD_WORKSTREAM'] ?? null;
+    const value = process.env['GSD_WORKSTREAM']?.trim();
+    return value || null;
 }
 function planningDir(cwd, ws, project) {
     if (project === undefined)
-        project = process.env['GSD_PROJECT'] ?? null;
+        project = process.env['GSD_PROJECT']?.trim() || null;
+    else if (typeof project === 'string')
+        project = project.trim() || null;
     if (ws === undefined)
         ws = resolveEnvWorkstream();
+    else if (typeof ws === 'string')
+        ws = ws.trim() || null;
     // Reject path separators and traversal components in project/workstream names
     const BAD_SEGMENT = /[/\\]|\.\./;
     if (project && BAD_SEGMENT.test(project)) {
@@ -187,7 +192,7 @@ function worktreesOptedOutUnguarded(cwd) {
     const scoped = ownKey(readCfg(node_path_1.default.join(planningDir(cwd), 'config.json')));
     if (scoped.present)
         return scoped.value === false;
-    if (process.env['GSD_WORKSTREAM']) {
+    if (resolveEnvWorkstream() !== null) {
         const root = ownKey(readCfg(node_path_1.default.join(planningRoot(cwd), 'config.json')));
         if (root.present)
             return root.value === false;

package/gsd-core/bin/lib/pr-branch-patterns.cjs

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * PR-branch `.planning/` path classification patterns — single source of
+ * truth (ADR-4910 §8, epic #4906 Phase 5; issues #4605, #4606).
+ *
+ * `gsd-core/workflows/pr-branch.md` cannot `require()` this module at
+ * runtime — a workflow markdown file has no module system, and its bash
+ * steps are copy-pasted text executed by whatever shell interprets the
+ * workflow. So the three exported constants below are mirrored VERBATIM
+ * into that file's `TRANSIENT_DIRS=`, `STRUCTURAL_RE=`, and
+ * `MILESTONE_PHASES_RE=` bash variable assignments, and
+ * `scripts/lint-pr-branch-pattern-drift.cjs` asserts the mirror never
+ * drifts from this file (compiled to `gsd-core/bin/lib/pr-branch-patterns.cjs`)
+ * as part of `npm run lint:ci`. Change a value here, then update
+ * `gsd-core/workflows/pr-branch.md` to match, or the drift guard fails.
+ *
+ * This module does not read the filesystem and has no dependencies (a leaf
+ * module, mirroring `src/secrets.cts` / `src/planning-scope.cts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MILESTONE_PHASES_RE_SRC = exports.STRUCTURAL_RE_SRC = exports.TRANSIENT_DIRS_SRC = void 0;
+/**
+ * Space-separated list of `.planning/` subdirectory names that are reviewer
+ * noise (PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md, and friends) —
+ * filtered out of a PR branch in BOTH default and strict mode.
+ *
+ * Mirrored verbatim into `gsd-core/workflows/pr-branch.md`'s
+ * `TRANSIENT_DIRS="..."` assignment.
+ */
+exports.TRANSIENT_DIRS_SRC = 'phases quick research threads todos debug seeds codebase ui-reviews';
+/**
+ * Structural planning files — repository planning state, preserved in
+ * default mode and filtered out in strict mode. Anchored on both
+ * alternatives so `.planning/STATEX.md` and `.planning/STATE.md.bak` are
+ * NOT treated as structural. The `milestones` alternative matches only
+ * FILES directly under `.planning/milestones/` (e.g. `v1.0-ROADMAP.md`) —
+ * not a `<milestone>-phases/` subdirectory nested there. That subdirectory
+ * is reviewer noise, not structural state (#4605); it falls through to
+ * `MILESTONE_PHASES_RE_SRC` below instead.
+ *
+ * Mirrored verbatim into `gsd-core/workflows/pr-branch.md`'s
+ * `STRUCTURAL_RE="..."` assignment.
+ */
+exports.STRUCTURAL_RE_SRC = '^\\.planning/(STATE|ROADMAP|MILESTONES|PROJECT|REQUIREMENTS)\\.md$|^\\.planning/milestones/[^/]+\\.md$';
+/**
+ * Milestone-scoped phase-plan directories — the same reviewer noise as
+ * `TRANSIENT_DIRS_SRC`'s `phases` entry, but nested per-milestone once a
+ * project has passed at least one milestone:
+ * `.planning/milestones/<milestone>-phases/`. The milestone slug (`v1.0`,
+ * `m2`, ...) varies per project, so this is declared as a shape, not a
+ * literal path — a single path segment standing in for the slug, anchored
+ * the same way `STRUCTURAL_RE_SRC`'s alternatives are (#4605).
+ *
+ * Mirrored verbatim into `gsd-core/workflows/pr-branch.md`'s
+ * `MILESTONE_PHASES_RE="..."` assignment.
+ */
+exports.MILESTONE_PHASES_RE_SRC = '^\\.planning/milestones/[^/]+-phases/';

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

@@ -234,6 +234,12 @@ function analyzeCoverage(items, resolutions = [], validators) {
     const unresolved = merged.filter((i) => i.status === 'unresolved').length;
     const applicable = merged.length;
     const resolved = applicable - unresolved; // closed set: resolved-status + dismissed
+    // #4656: the unclassified soft-signal rows count toward `applicable` (the
+    // rollup is count-preserving and `resolved = applicable - unresolved` is a
+    // documented identity), so the count is exposed as a SIBLING field — the
+    // zero-applicable guards can then also fire when EVERY requirement is
+    // unclassified, the case the spec-phase/ui-phase docs promise to catch.
+    const unclassified = merged.filter((i) => i.category === 'unclassified').length;
     const byVerification = {};
     for (const tier of validators.verification)
         byVerification[tier] = 0;
@@ -242,7 +248,7 @@ function analyzeCoverage(items, resolutions = [], validators) {
             byVerification[i.verification] = (byVerification[i.verification] ?? 0) + 1;
         }
     }
-    return { items: merged, coverage: { applicable, resolved, unresolved, byVerification } };
+    return { items: merged, coverage: { applicable, resolved, unresolved, unclassified, byVerification } };
 }
 /**
  * The prohibition adapter's injected runtime validators (ADR-550 #5). There is no closed