@opengsd/gsd-core 1.10.0 → 1.12.0

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

@@ -14,8 +14,18 @@ exports.DYNAMIC_KEY_PATTERNS = exports.RUNTIME_STATE_KEYS = exports.VALID_CONFIG
 exports.normalizeLegacyKeys = normalizeLegacyKeys;
 exports.mergeDefaults = mergeDefaults;
 exports.migrateOnDisk = migrateOnDisk;
+exports.isConfigSection = isConfigSection;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+// ⚠️ DO NOT add a sibling `.cjs` import to this module. `configuration.cjs` must load
+// from an install layout containing ONLY itself plus `bin/shared/*.manifest.json` —
+// that is the #3571 contract, pinned by "co-located bin/shared manifests let
+// configuration.cjs load without sdk/shared" in tests/install.test.cjs. A `require`
+// for a sibling that the installer does not co-locate fails at load time with
+// MODULE_NOT_FOUND. This is why #3760's out-of-band diagnostic is emitted by this
+// module's CALLERS (`cmdMigrateConfig` in config.cts, `loadConfigResolved` in
+// config-loader.cts) rather than here: `normalizeLegacyKeys` reports refusals
+// in-band via `skipped[]`, which keeps it both pure AND dependency-free.
 // In .cts (CommonJS output) files, `require` is available as a global.
 const _require = require;
 // ─── Manifest requires ───────────────────────────────────────────────────────
@@ -109,42 +119,107 @@ function deepMergeConfig(base, overlay) {
     }
     return result;
 }
+/** Type name for a report — `'array'` for arrays, otherwise `typeof`. */
+function describeSectionType(value) {
+    return Array.isArray(value) ? 'array' : typeof value;
+}
+/**
+ * Is `value` usable as a config SECTION — something a nested key can be written into?
+ *
+ * Three cases, and the distinction between the second and third is the whole of #3760:
+ *
+ *  - `null` / `undefined` — ABSENT. Not a section yet, but nothing is lost by creating one.
+ *    Callers substitute `{}`; this predicate reports `false` and callers check for absence
+ *    separately, so the two are never conflated.
+ *  - a non-null, non-array `object` — a SECTION. Spreading it is safe and correct.
+ *  - anything else (string, number, boolean, array) — a PRESENT NON-OBJECT, i.e. user data
+ *    that a spread would destroy. `{...'main'}` is `{0:'m',1:'a',2:'i',3:'n'}`; `{...7}` is
+ *    `{}`. An array is included here because `typeof [] === 'object'` and `{...['a']}` is
+ *    `{0:'a'}` — the identical expansion a bare `typeof` guard would wave through.
+ *
+ * This is the nested-section analog of the top-level shape check ADR-227 already requires
+ * in `_readConfigFile` (`config-loader.cts`): valid JSON is not the same as a config object.
+ * It lives here, exported, rather than being copied into `config-loader.cts`, because two
+ * hand-rolled copies of one predicate is `DEFECT.GENERATIVE-FIX` by construction — the same
+ * reasoning that made `unusable-input.cts` a shared seam.
+ */
+function isConfigSection(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 // ─── Exported functions ───────────────────────────────────────────────────────
+/**
+ * Hoist a legacy top-level key into its canonical nested section.
+ *
+ * Refuses — and reports the refusal — when the destination section is present but is not an
+ * object. Refusing means leaving BOTH the section and the legacy key exactly as they were and
+ * pushing no `Normalization`, so this block never marks the config dirty and nothing it
+ * touched can be written back. That is the #3760 contract: never expand, never drop, never
+ * persist a shape the user did not write.
+ */
+function hoistLegacyKey(result, normalizations, skipped, legacyKey, section, field) {
+    const raw = result[section];
+    // `null`/`undefined` mean "no section yet" and have always been treated as absent here.
+    // They carry no user data, so creating the section loses nothing.
+    const absent = raw === null || raw === undefined;
+    if (!absent && !isConfigSection(raw)) {
+        skipped.push({
+            from: legacyKey,
+            to: `${section}.${field}`,
+            section,
+            reason: 'non_object_section',
+            value: result[legacyKey],
+            sectionType: describeSectionType(raw),
+        });
+        return;
+    }
+    // `raw` is already narrowed by the isConfigSection guard above.
+    const existing = absent ? {} : raw;
+    const value = result[legacyKey];
+    // Canonical nested wins when it is already set; otherwise the legacy value is hoisted.
+    result[section] = existing[field] === undefined
+        ? { ...existing, [field]: value }
+        : { ...existing };
+    delete result[legacyKey];
+    normalizations.push({ from: legacyKey, to: `${section}.${field}`, value });
+}
 function normalizeLegacyKeys(parsed) {
     const result = { ...parsed };
     const normalizations = [];
+    const skipped = [];
     // 1. branching_strategy → git.branching_strategy
     if (Object.prototype.hasOwnProperty.call(result, 'branching_strategy')) {
-        const value = result['branching_strategy'];
-        const git = (result['git'] ?? {});
-        if (git['branching_strategy'] === undefined) {
-            result['git'] = { ...git, branching_strategy: value };
-        }
-        else {
-            // canonical nested wins — just delete the stale top-level
-            result['git'] = { ...git };
-        }
-        delete result['branching_strategy'];
-        normalizations.push({ from: 'branching_strategy', to: 'git.branching_strategy', value });
+        hoistLegacyKey(result, normalizations, skipped, 'branching_strategy', 'git', 'branching_strategy');
     }
     // 2. top-level sub_repos → planning.sub_repos
     if (Object.prototype.hasOwnProperty.call(result, 'sub_repos')) {
-        const value = result['sub_repos'];
-        const planning = (result['planning'] ?? {});
-        if (planning['sub_repos'] === undefined) {
-            result['planning'] = { ...planning, sub_repos: value };
-        }
-        else {
-            // canonical nested wins — just drop the stale top-level
-            result['planning'] = { ...planning };
-        }
-        delete result['sub_repos'];
-        normalizations.push({ from: 'sub_repos', to: 'planning.sub_repos', value });
+        hoistLegacyKey(result, normalizations, skipped, 'sub_repos', 'planning', 'sub_repos');
     }
     // 3. multiRepo: true → marker (filesystem detection deferred to migrateOnDisk / caller)
     if (result['multiRepo'] === true) {
-        delete result['multiRepo'];
-        normalizations.push({ from: 'multiRepo', to: 'planning.sub_repos', value: true, requiresFilesystem: true });
+        // #3760: refuse here too, for the same reason as blocks 1 and 2 — and it must be
+        // decided HERE, not in the caller. The caller is the one that runs filesystem
+        // detection, but whether `planning` can receive the result is knowable from the
+        // parsed config alone. Deciding it later meant `multiRepo` had already been
+        // deleted and a Normalization already pushed: the config was written, the
+        // sub_repos injection silently no-opped against the non-object section, and the
+        // user's `multiRepo: true` was consumed with nothing to show for it and no
+        // diagnostic. Refusing here keeps the marker, keeps the config clean of a
+        // migration that did not happen, and gives all three callers the same report.
+        const planning = result['planning'];
+        if (planning !== null && planning !== undefined && !isConfigSection(planning)) {
+            skipped.push({
+                from: 'multiRepo',
+                to: 'planning.sub_repos',
+                section: 'planning',
+                reason: 'non_object_section',
+                value: true,
+                sectionType: describeSectionType(planning),
+            });
+        }
+        else {
+            delete result['multiRepo'];
+            normalizations.push({ from: 'multiRepo', to: 'planning.sub_repos', value: true, requiresFilesystem: true });
+        }
     }
     // 4. top-level depth → granularity
     if (Object.prototype.hasOwnProperty.call(result, 'depth') && !Object.prototype.hasOwnProperty.call(result, 'granularity')) {
@@ -154,26 +229,36 @@ function normalizeLegacyKeys(parsed) {
         delete result['depth'];
         normalizations.push({ from: 'depth', to: 'granularity', value: mapped });
     }
-    return { parsed: result, normalizations };
+    // 5. top-level base_branch → git.base_branch
+    if (Object.prototype.hasOwnProperty.call(result, 'base_branch')) {
+        hoistLegacyKey(result, normalizations, skipped, 'base_branch', 'git', 'base_branch');
+    }
+    return { parsed: result, normalizations, skipped };
 }
 function mergeDefaults(parsed) {
     // Start with a deep clone of defaults, then overlay parsed
     const defaults = structuredClone(CONFIG_DEFAULTS);
     return deepMergeConfig(defaults, parsed);
 }
-function migrateOnDisk(cwd, workstream) {
-    const configPath = (0, node_path_1.join)(planningDir(cwd, workstream), 'config.json');
+function migrateOnDisk(cwd, workstream, configPathOverride) {
+    // #3749: the caller (cmdMigrateConfig in config.cts) supplies the config
+    // path resolved through planning-workspace's PROJECT-aware planningDir.
+    // This module cannot import that sibling (#3571 install-layout contract),
+    // and its own local planningDir above is deliberately workstream-only —
+    // resolving here through the local copy made migrate-config under
+    // GSD_PROJECT rewrite the ROOT config instead of the scoped one.
+    const configPath = configPathOverride ?? (0, node_path_1.join)(planningDir(cwd, workstream), 'config.json');
     let raw;
     try {
         raw = (0, node_fs_1.readFileSync)(configPath, 'utf-8');
     }
     catch {
         // File missing — nothing to migrate
-        return { migrated: false, normalizations: [], wrote: null };
+        return { migrated: false, normalizations: [], wrote: null, skipped: [] };
     }
     const trimmed = raw.trim();
     if (trimmed === '') {
-        return { migrated: false, normalizations: [], wrote: null };
+        return { migrated: false, normalizations: [], wrote: null, skipped: [] };
     }
     let parsed;
     try {
@@ -181,23 +266,30 @@ function migrateOnDisk(cwd, workstream) {
     }
     catch {
         // Malformed — can't migrate
-        return { migrated: false, normalizations: [], wrote: null };
-    }
-    const { parsed: normalized, normalizations } = normalizeLegacyKeys(parsed);
-    if (normalizations.length === 0) {
-        return { migrated: false, normalizations: [], wrote: null };
+        return { migrated: false, normalizations: [], wrote: null, skipped: [] };
     }
+    const { parsed: normalized, normalizations, skipped } = normalizeLegacyKeys(parsed);
     // Resolve multiRepo filesystem detection
     const result = { ...normalized };
     for (const norm of normalizations) {
         if (norm.requiresFilesystem) {
             const detected = detectSubRepos(cwd);
             if (detected.length > 0) {
-                const planning = (result['planning'] ?? {});
-                result['planning'] = { ...planning, sub_repos: detected, commit_docs: false };
+                // #3760: `requiresFilesystem` is pushed by block 3 only when `planning` was
+                // absent or an object, and nothing between there and here changes it — so
+                // `isConfigSection` picks between merge and create, and never has to discard.
+                const planning = result['planning'];
+                const existing = isConfigSection(planning) ? planning : {};
+                result['planning'] = { ...existing, sub_repos: detected, commit_docs: false };
             }
         }
     }
+    if (normalizations.length === 0) {
+        // Nothing changed — and that now includes the case where every legacy key was
+        // REFUSED. Returning early here is what keeps the corrupted-section input from
+        // reaching writeFileSync at all.
+        return { migrated: false, normalizations: [], wrote: null, skipped };
+    }
     try {
         (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(result, null, 2));
     }
@@ -205,5 +297,5 @@ function migrateOnDisk(cwd, workstream) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new Error(`Failed to write migrated config at ${configPath}: ${msg}`);
     }
-    return { migrated: true, normalizations, wrote: configPath };
+    return { migrated: true, normalizations, wrote: configPath, skipped };
 }

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

@@ -15,6 +15,22 @@
  *   - node:fs / node:path (stdlib)
  *   - ./phase-id.cjs       (comparePhaseNum, used by readSubdirectories)
  *   - ./planning-workspace.cjs (findContextMdIn, used by getPhaseFileStats)
+ *
+ * #3883 (ADR-3473 §8.3): two of this module's cyclic partners require
+ * generateSlugInternal, the canonical slug formula:
+ *   - phase-id.cjs requires this module directly.
+ *   - planning-workspace.cjs is a cyclic partner via a longer path:
+ *     core-utils.cjs -> planning-workspace.cjs -> active-workstream-store.cjs
+ *     -> workstream-name-policy.cjs -> core-utils.cjs.
+ * Both are genuine circular requires. They are safe ONLY because every side
+ * accesses the other's exports lazily, through the live module-namespace
+ * object (`phaseIdModule.foo(...)` / `planningWorkspace.foo(...)`) inside a
+ * function body, never via a top-level destructure — a top-level
+ * `const { foo } = require(...)` copies the binding at import time and would
+ * silently capture `undefined` whichever module loses the load-order race.
+ * This is an absolute rule with no exception in this file: every cyclic
+ * partner's export is accessed through its module-namespace object, never
+ * destructured at the top level.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -23,12 +39,58 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
-const { comparePhaseNum } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { findContextMdIn } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCommandProjection = require("./shell-command-projection.cjs");
+// ─── Line-ending normalization ─────────────────────────────────────────────────
+/**
+ * Normalize every line ending in `content` to a bare `\n`, ONCE — the shared
+ * seam every document-READ boundary in this codebase should route through
+ * (#3707-CR follow-up MAJOR).
+ *
+ * CommonMark treats a lone CR (no paired LF) as a line ending — such a
+ * document RENDERS as separate lines to a human reader — but a parser that
+ * splits/tokenizes/scans on `\n` alone treats a lone-CR-separated document as
+ * ONE unbroken line, hiding every row boundary in it. `src/uat.cts` originally
+ * carried this exact fix as a PRIVATE, unexported function applied inside two
+ * of its own parse functions (`parseUatItemsWithStats`, `parseCurrentTest`) —
+ * which is why two OTHER read sites in the same module (`cmdAuditUat`'s
+ * VERIFICATION and deferred-items.md ingresses) were missed: normalizing
+ * per-parser means every new parser must remember to call it. Promoted here,
+ * to the shared leaf module every document consumer can reach without a new
+ * dependency edge, so normalization can be applied at the READ boundary
+ * instead — every current and future parser fed from a boundary that calls
+ * this gets normalized text by construction.
+ *
+ * `/\r\n?/g` is deliberately ONE alternation, not two separate replaces: a
+ * two-pass `replace(/\r\n/g,'\n').replace(/\r/g,'\n')` is equivalent here
+ * because the first pass already consumes every CRLF pair before the second
+ * pass ever runs, but a single regex avoids relying on pass ORDER and matches
+ * greedily left-to-right in one scan, so a CRLF is always consumed as ONE
+ * unit (never left as a stray trailing `\r` after the `\n` half is matched
+ * first) and a lone CR — including one immediately followed by nothing, i.e.
+ * at EOF, or by another lone CR — is still replaced.
+ *
+ * This is deliberately NOT a length-preserving transform (CRLF, two UTF-16
+ * units, becomes LF, one), so any offsets a caller computes must be compared
+ * only against THIS normalized string, never against the original raw text.
+ *
+ * U+2028 LINE SEPARATOR / U+2029 PARAGRAPH SEPARATOR (#3078-CR) are
+ * DELIBERATELY NOT folded here, unlike `\r`/`\r\n`. Folding is unnecessary:
+ * `String.prototype.split('\n')` never treats U+2028/U+2029 as a delimiter,
+ * so an exotic separator can never manufacture a fake line start for a
+ * consumer that scans lines produced by `split('\n')`, rather than anchoring
+ * a multiline (`/m`) regex directly over unsplit text. Only the latter
+ * pattern is vulnerable to the ECMA-262 LineTerminator set including these
+ * two code points. This module performs no line-anchored matching of its
+ * own; a caller that scans lines should split first and match per-line
+ * rather than anchor `/m` over unsplit text — this comment makes no claim
+ * about whether any particular caller currently does so.
+ */
+function normalizeLineEndings(content) {
+    return content.replace(/\r\n?/g, '\n');
+}
 // ─── Path helpers ────────────────────────────────────────────────────────────
 /**
  * Normalize a relative path to always use forward slashes (cross-platform).
@@ -72,17 +134,30 @@ function extractOneLinerFromBody(content) {
     if (!content)
         return null;
     const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-    const body = normalized.replace(/^---\n[\s\S]*?\n---\n*/, '');
-    const match = body.match(/^#[^\n]*\n+\*\*([^*\n]+)\*\*([^\n]*)/m);
-    if (!match)
-        return null;
-    const boldInner = match[1].trim();
-    const afterBold = match[2];
-    if (/:\s*$/.test(boldInner)) {
-        const prose = afterBold.trim();
-        return prose.length > 0 ? prose : null;
+    const body = normalized.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n*/, '');
+    // #3170: anchor to a summary-shaped heading (Summary / Overview /
+    // Accomplishments) so an incidental first heading (a rule list, task
+    // breakdown, deviation note) does not contribute its first bold run as the
+    // deliverable one-liner. Iterate headings in document order and extract from
+    // the first summary-shaped one that has a bold run; fall back to null (not the
+    // wrong text) when no such heading exists.
+    const headingRe = /^#+\s*([^\n]*)\n+\*\*([^*\n]+)\*\*([^\n]*)/gm;
+    let match;
+    while ((match = headingRe.exec(body)) !== null) {
+        if (!/summary|overview|accomplish/i.test(match[1]))
+            continue;
+        const boldInner = match[2].trim();
+        const afterBold = match[3];
+        if (/:\s*$/.test(boldInner)) {
+            const prose = afterBold.trim();
+            if (prose.length > 0)
+                return prose;
+        }
+        else if (boldInner.length > 0) {
+            return boldInner;
+        }
     }
-    return boldInner.length > 0 ? boldInner : null;
+    return null;
 }
 // ─── Misc utilities ───────────────────────────────────────────────────────────
 function pathExistsInternal(cwd, targetPath) {
@@ -95,7 +170,19 @@ function pathExistsInternal(cwd, targetPath) {
         return false;
     }
 }
-function generateSlugInternal(text) {
+/**
+ * #3883 (ADR-3473 §8.3 remediation): `maxLen` lets a caller state its own
+ * truncation contract instead of being forced into this function's
+ * historical 60-char cap. Some call sites truncated at 60 before the #3883
+ * consolidation (commands.cts:cmdGenerateSlug) and some never truncated at
+ * all (phase-id.cts toDir/getPhaseDirFromPhaseId, the init.cts/phase-locator
+ * phase_slug sites, workstream-name-policy.cts toWorkstreamSlug) — collapsing
+ * every caller onto a single hard-coded 60 introduced two identity
+ * collisions (distinct >60-char names/phase-slugs truncating to the same
+ * value) that did not exist pre-migration. `maxLen: 60` remains the default
+ * so untouched callers keep prior behavior; pass `null` for no truncation.
+ */
+function generateSlugInternal(text, maxLen = 60) {
     if (!text)
         return null;
     // #2849: strip leading/trailing hyphens AFTER truncation, not only before.
@@ -103,7 +190,9 @@ function generateSlugInternal(text) {
     // the strip step exists to prevent. Truncation cannot add a leading hyphen, so
     // running the full ^-+|-+$ pass last is equivalent for leading hyphens and
     // fixes the trailing-hyphen-after-truncation case.
-    return transliterateForSlug(text).replace(/[^a-z0-9]+/g, '-').substring(0, 60).replace(/^-+|-+$/g, '');
+    const collapsed = transliterateForSlug(text).replace(/[^a-z0-9]+/g, '-');
+    const truncated = maxLen === null ? collapsed : collapsed.substring(0, maxLen);
+    return truncated.replace(/^-+|-+$/g, '');
 }
 // ─── Transliteration (#2848) ─────────────────────────────────────────────────
 //
@@ -151,27 +240,66 @@ function transliterateForSlug(text) {
     }
     return out;
 }
-// ─── Phase file helpers ──────────────────────────────────────────────────────
-/** Filter a file list to just PLAN.md / *-PLAN.md entries. */
-function filterPlanFiles(files) {
-    return files.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
-}
-/** Filter a file list to just SUMMARY.md / *-SUMMARY.md entries. */
-function filterSummaryFiles(files) {
-    return files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
-}
 /**
  * Read a phase directory and return counts/flags for common file types.
+ *
+ * #3183 (ADR-3180 Decision 2): `plans`/`summaries` are derived from the
+ * canonical `scanPhasePlans` rather than a local re-derivation, so this
+ * primitive can no longer diverge from the single owner of live-plan
+ * counting. `scanPhasePlans`
+ * lives in plan-scan.cjs, which itself imports `countMatchedSummaries` from
+ * THIS module — a top-level import here would be circular, so the require
+ * is deferred (lazy, inside the function body) to break the cycle at load
+ * time. This mirrors the lazy-require seam already used elsewhere in this
+ * repo (see src/audit-command-router.cts) for the same "module A needs
+ * module B which needs module A" shape.
+ *
+ * `hasResearch`/`hasContext`/`hasVerification`/`hasReviews` stay on the raw
+ * `readdirSync` listing — they are not plan-scan concerns.
+ *
+ * #3511 BLOCKER-2: the raw listing is scoped through `scopeToPhase` (keyed on
+ * `path.basename(phaseDir)`) before any of the four artifact predicates run,
+ * so a stray cross-phase file (e.g. `04-VERIFICATION.md` sitting inside phase
+ * 03's directory) cannot flip `hasResearch`/`hasContext`/`hasVerification`/
+ * `hasReviews` true for a phase it does not belong to — the same membership
+ * rule every other aggregate phase-directory scan (`uat.cts`, `audit.cts`,
+ * `phase.cts`, `state.cts`) already routes through. `hasContext` is scoped by
+ * passing the already-scoped array into `findContextMdIn` at this call site
+ * only — `findContextMdIn` itself is unchanged and its other 4 call sites
+ * (roadmap.cts, gap-checker.cts, init.cts) are unaffected.
+ *
+ * Degrades on an unreadable directory instead of throwing: empty arrays,
+ * every flag false, scope UNREADABLE (mirroring scanPhasePlans's own
+ * degrade path).
  */
 function getPhaseFileStats(phaseDir) {
-    const files = node_fs_1.default.readdirSync(phaseDir);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const scanPhasePlans = require('./plan-scan.cjs');
+    const scan = scanPhasePlans(phaseDir);
+    let files;
+    try {
+        files = node_fs_1.default.readdirSync(phaseDir);
+    }
+    catch {
+        return {
+            plans: scan.planFiles,
+            summaries: scan.summaryFiles,
+            hasResearch: false,
+            hasContext: false,
+            hasVerification: false,
+            hasReviews: false,
+            scope: scan.scope,
+        };
+    }
+    const scopedFiles = phaseIdModule.scopeToPhase(files, node_path_1.default.basename(phaseDir));
     return {
-        plans: filterPlanFiles(files),
-        summaries: filterSummaryFiles(files),
-        hasResearch: files.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
-        hasContext: findContextMdIn(files) !== null,
-        hasVerification: files.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'),
-        hasReviews: files.some(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'),
+        plans: scan.planFiles,
+        summaries: scan.summaryFiles,
+        hasResearch: scopedFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
+        hasContext: planningWorkspace.findContextMdIn(scopedFiles) !== null,
+        hasVerification: scopedFiles.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'),
+        hasReviews: scopedFiles.some(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'),
+        scope: scan.scope,
     };
 }
 /**
@@ -183,7 +311,7 @@ function readSubdirectories(dirPath, sort = false) {
     try {
         const entries = node_fs_1.default.readdirSync(dirPath, { withFileTypes: true });
         const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
-        return sort ? dirs.sort((a, b) => comparePhaseNum(a, b)) : dirs;
+        return sort ? dirs.sort((a, b) => phaseIdModule.comparePhaseNum(a, b)) : dirs;
     }
     catch {
         return [];
@@ -297,6 +425,35 @@ function summaryCandidates(plan) {
     const extended = base.match(/^(\d+)-PLAN-(\d+)/i);
     if (extended)
         candidates.push(dir + extended[1] + '-' + extended[2] + '-SUMMARY.md');
+    // #3183: canonical-id form. Restores the coverage of the pre-migration
+    // bespoke I001 rule (verify.cts, pre-#3183, via validate.cjs's now-unused
+    // `canonicalPlanStem` — behaviourally identical to `extractCanonicalPlanId`,
+    // confirmed empirically), which matched a plan carrying a descriptive slug
+    // after its <phase>-<plan> id — e.g. `68-01-scaffolding-PLAN.md` — against
+    // a summary named only by the bare id — `68-01-SUMMARY.md`. None of the
+    // three candidates above produce that filename.
+    //
+    // Narrowed to the case `extractCanonicalPlanId` actually extracted an
+    // <id>-<id> pair (its result differs from the plan's own PLAN-stripped
+    // base). When no pair is found it falls back to returning that same base
+    // unchanged, which would otherwise push a redundant candidate identical to
+    // the `<stem>-SUMMARY.md` form above (e.g. `setup-PLAN.md` -> canonical
+    // 'setup' -> 'setup-SUMMARY.md', already candidate #2) rather than the
+    // original rule's actual behavior of matching only real id pairs.
+    //
+    // Collision, matching the original rule byte-for-behaviour: two plans that
+    // share the same <phase>-<plan> id but differ only in their descriptive
+    // slug (`68-01-alpha-PLAN.md` + `68-01-beta-PLAN.md`) both generate the
+    // SAME candidate `68-01-SUMMARY.md` and therefore BOTH read as summarized
+    // off one shared summary file. This is not a new regression: the
+    // pre-migration bespoke rule collapsed the same way (it populated one
+    // `summaryBases` Set keyed by canonical stem, so any plan whose canonical
+    // stem hit the set counted as matched, with no cardinality check against
+    // how many plans shared that stem).
+    const planStem = base.replace(/-PLAN$/i, '');
+    const canonicalId = extractCanonicalPlanId(base + '.md');
+    if (canonicalId !== planStem)
+        candidates.push(dir + canonicalId + '-SUMMARY.md');
     return candidates;
 }
 /**
@@ -314,19 +471,37 @@ function findUnsummarizedPlans(planFiles, summaryFiles) {
     const summarySet = new Set(summaryFiles);
     return planFiles.filter((plan) => !summaryCandidates(plan).some((c) => summarySet.has(c)));
 }
+/**
+ * #3183: the mirror image of `findUnsummarizedPlans` — the summary files in
+ * `summaryFiles` that do NOT pair with ANY plan in `planFiles`, using the
+ * identical `summaryCandidates` matching rule as `countMatchedSummaries` /
+ * `findUnsummarizedPlans`. Callers that must name orphaned summaries (a
+ * stray non-plan summary, or a summary whose plan was renamed/removed) need
+ * this instead of a bespoke exact-suffix Set-diff, which cannot recognize
+ * the nested or extended naming forms `summaryCandidates` already handles —
+ * a divergence that produced false "orphan summary" warnings.
+ */
+function findOrphanSummaries(planFiles, summaryFiles) {
+    const claimed = new Set();
+    for (const plan of planFiles) {
+        for (const candidate of summaryCandidates(plan))
+            claimed.add(candidate);
+    }
+    return summaryFiles.filter((s) => !claimed.has(s));
+}
 module.exports = {
     toPosixPath,
+    normalizeLineEndings,
     detectSubRepos,
     extractOneLinerFromBody,
     pathExistsInternal,
     generateSlugInternal,
     transliterateForSlug,
-    filterPlanFiles,
-    filterSummaryFiles,
     getPhaseFileStats,
     readSubdirectories,
     timeAgo,
     extractCanonicalPlanId,
     countMatchedSummaries,
     findUnsummarizedPlans,
+    findOrphanSummaries,
 };

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

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractDecisions = extractDecisions;
 exports.parseDecisions = parseDecisions;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const token_scanner_cjs_1 = require("./token-scanner.cjs");
 const DISCRETION_HEADINGS = new Set([
     "claude's discretion",
     'claudes discretion',
@@ -89,12 +90,14 @@ function parseDecisionLines(block) {
     let category = '';
     let inDiscretion = false;
     let current = null;
+    let openIndent = null;
     let parseMisses = 0;
     const flush = () => {
         if (current) {
             current.text = current.text.trim();
             out.push(current);
             current = null;
+            openIndent = null;
         }
     };
     for (const line of lines) {
@@ -115,6 +118,23 @@ function parseDecisionLines(block) {
             inDiscretion = DISCRETION_HEADINGS.has(normalized);
             continue;
         }
+        // Nested bullet under an open decision (#3212 Phase 3, #3169): a bullet
+        // indented deeper than the currently-open decision's own bullet is that
+        // decision's elaboration (e.g. a cross-reference to a sibling decision),
+        // not a fresh declaration attempt — fold it into current.text exactly
+        // like a continuation line, before it ever reaches the declaration/
+        // parse-miss regexes below. A bullet at the SAME or a SHALLOWER indent
+        // is unaffected — tested exactly as before this fix. See design doc
+        // .gsd/phase/chore-3414-tokenizer-first-seam/40-design.md §1.3 for why
+        // nesting depth, not bullet content, is the signal that distinguishes
+        // this from a genuinely malformed top-level declaration.
+        if (current &&
+            openIndent !== null &&
+            trimmed.startsWith('-') &&
+            (0, token_scanner_cjs_1.indentWidth)(line) > openIndent) {
+            current.text += ' ' + trimmed;
+            continue;
+        }
         // Colon form: `- **D-NN[ [tags]]:** text`
         const colonMatch = line.match(bulletColonRe);
         if (colonMatch) {
@@ -125,6 +145,7 @@ function parseDecisionLines(block) {
                 : [];
             const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
             current = { id, text: colonMatch[3], category, tags, trackable };
+            openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
         // Em-dash form: `- **D-NN[ [tags]] — title** body`
@@ -140,6 +161,7 @@ function parseDecisionLines(block) {
             // title itself is embedded in the bold run but we report the body as text
             // (consistent with how the gate cares only about coverage, not title/body split).
             current = { id, text: emDashMatch[3] || '', category, tags, trackable };
+            openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
         // Titled-colon form: `- **D-NN[ [tags]]: Title.** body` (#1639). Checked LAST — it is
@@ -155,6 +177,7 @@ function parseDecisionLines(block) {
                 : [];
             const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
             current = { id, text: titledColonMatch[3] || '', category, tags, trackable };
+            openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
         // Parse-miss guard (FIX B + #1343): a line that looks like a `D-NN` decision

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

@@ -27,6 +27,9 @@ exports.validateResolution = validateResolution;
 exports.proposeEdges = proposeEdges;
 exports.analyzeCoverage = analyzeCoverage;
 const probe_core_cjs_1 = require("./probe-core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { runMain } = cliExitModule;
 /**
  * Word-boundary cues mapping requirement prose -> data/behavior shape.
  * Heuristic and intentionally lossy; an authored `shapes` array overrides it.
@@ -192,5 +195,10 @@ function analyzeCoverage(requirements, resolutions = []) {
  * `require.main === module` so it runs only when the compiled `.cjs` is executed directly.
  */
 if (require.main === module) {
-    (0, probe_core_cjs_1.runProbeCli)((requirements, resolutions) => analyzeCoverage(requirements, resolutions), { usage: 'edge-probe.cjs <requirements.json> [resolutions.json]' });
+    // runProbeCli's default `exit` now throws ExitError (src/probe-core.cts) rather
+    // than calling process.exit directly, so this entry point must run under
+    // runMain to translate that throw into process.exitCode.
+    runMain(() => {
+        (0, probe_core_cjs_1.runProbeCli)((requirements, resolutions) => analyzeCoverage(requirements, resolutions), { usage: 'edge-probe.cjs <requirements.json> [resolutions.json]' });
+    });
 }