@opengsd/gsd-core 1.11.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, scopeToPhase } = 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).
@@ -108,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.
@@ -116,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) ─────────────────────────────────────────────────
 //
@@ -215,12 +291,12 @@ function getPhaseFileStats(phaseDir) {
             scope: scan.scope,
         };
     }
-    const scopedFiles = scopeToPhase(files, node_path_1.default.basename(phaseDir));
+    const scopedFiles = phaseIdModule.scopeToPhase(files, node_path_1.default.basename(phaseDir));
     return {
         plans: scan.planFiles,
         summaries: scan.summaryFiles,
         hasResearch: scopedFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
-        hasContext: findContextMdIn(scopedFiles) !== null,
+        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,
@@ -235,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 [];
@@ -415,6 +491,7 @@ function findOrphanSummaries(planFiles, summaryFiles) {
 }
 module.exports = {
     toPosixPath,
+    normalizeLineEndings,
     detectSubRepos,
     extractOneLinerFromBody,
     pathExistsInternal,

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]' });
+    });
 }

package/gsd-core/bin/lib/estimate-cli.cjs

@@ -21,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CALIBRATION_FILENAME = void 0;
+exports.PhasesUnreadableError = exports.CALIBRATION_FILENAME = void 0;
 exports.readSmartZoneBudget = readSmartZoneBudget;
 exports.readCalibrationSamples = readCalibrationSamples;
 exports.parseTokensFlag = parseTokensFlag;
@@ -39,9 +39,15 @@ const estimation = require("./phase-estimation.cjs");
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
 const configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
+const phaseLocator = require("./phase-locator.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
+const planningScopeMod = require("./planning-scope.cjs");
 const { output, error, ERROR_REASON } = io;
 const { planningDir } = planningWorkspace;
 const { CONFIG_DEFAULTS } = configLoader;
+const { listMilestonePhaseDirs } = phaseLocator;
+const { SCOPE } = planningScopeMod;
 // WIN-1 parity (DEFECT.WINDOWS-FS-OPS): on Windows a concurrent reader, indexer,
 // or AV scanner can transiently hold the rename target open. Retry the transient
 // errnos with backoff, matching the writeLedger / writeConsentStore idiom.
@@ -192,6 +198,24 @@ function cmdEstimateCheck(cwd, args, raw) {
         sample_count: calibration.sampleCount,
     }, raw);
 }
+/**
+ * Thrown by `collectCalibrationSamples` when the phases directory EXISTS but
+ * could not be read (EACCES/EIO, `scope: SCOPE.UNREADABLE`). #3882/ADR-3473
+ * §8.5: that is a NON-answer, not "zero completed phases" — silently
+ * returning `[]` here would make an unreadable directory output-identical to
+ * a genuinely empty one, which is exactly the defect class §8.5 exists to
+ * end. `cmdEstimateCalibrate` catches this and refuses the rebuild instead
+ * of persisting a phantom empty calibration.
+ */
+class PhasesUnreadableError extends Error {
+    phasesRoot;
+    constructor(phasesRoot) {
+        super(`phases directory exists but could not be read: ${phasesRoot}`);
+        this.phasesRoot = phasesRoot;
+        this.name = 'PhasesUnreadableError';
+    }
+}
+exports.PhasesUnreadableError = PhasesUnreadableError;
 /**
  * Pair each completed phase's PLAN estimate with its SUMMARY actuals.
  *
@@ -199,18 +223,25 @@ function cmdEstimateCheck(cwd, args, raw) {
  * A plan with no `estimate` block, a summary with no `actuals`, or a malformed
  * value is skipped rather than guessed — a fabricated sample would silently
  * steer every future estimate.
+ *
+ * #3882 (ADR-3473 §8.2): this used to hand-roll a raw `readdirSync` over the
+ * phases directory, treating every directory (including sentinel phases —
+ * milestone 0 / 999, SENTINEL_RANGES) as a completed phase. A sentinel's
+ * PLAN/SUMMARY pair then silently contributed a phantom sample to the
+ * CALIBRATION FACTOR applied to every future estimate. Routed through the
+ * canonical owner (`listMilestonePhaseDirs`, `src/phase-locator.cts`) called
+ * with NO `cwd` — that combination is already "all milestone windows,
+ * sentinels excluded", exactly what this caller needs; no new API was
+ * required for this half (see the design doc's §3, corrected after
+ * measurement). It also inherits the `scope` discriminator for free, so an
+ * unreadable phases directory is no longer indistinguishable from a real
+ * empty one.
  */
 function collectCalibrationSamples(cwd) {
     const phasesRoot = node_path_1.default.join(planningDir(cwd), 'phases');
-    let phases;
-    try {
-        phases = node_fs_1.default.readdirSync(phasesRoot, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
-            .map((d) => d.name)
-            .sort();
-    }
-    catch {
-        return [];
+    const { value: phases, scope } = listMilestonePhaseDirs(phasesRoot);
+    if (scope === SCOPE.UNREADABLE) {
+        throw new PhasesUnreadableError(phasesRoot);
     }
     const readBlock = (file, key) => {
         let text;
@@ -277,7 +308,20 @@ function collectCalibrationSamples(cwd) {
  * next estimate reads the result.
  */
 function cmdEstimateCalibrate(cwd, _args, raw) {
-    const samples = collectCalibrationSamples(cwd);
+    let samples;
+    try {
+        samples = collectCalibrationSamples(cwd);
+    }
+    catch (err) {
+        if (err instanceof PhasesUnreadableError) {
+            // #3882/ADR-3473 §8.5: refuse rather than silently rebuild the
+            // calibration document from a phantom empty sample set — an
+            // unreadable phases directory must never look output-identical to a
+            // project with genuinely zero completed phases.
+            error(err.message, ERROR_REASON.ESTIMATE_PHASES_UNREADABLE);
+        }
+        throw err;
+    }
     const calibration = estimation.computeCalibration(samples);
     const target = node_path_1.default.join(planningDir(cwd), exports.CALIBRATION_FILENAME);
     let written = true;

package/gsd-core/bin/lib/exit-code-registry.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+// GENERATED FILE — DO NOT EDIT BY HAND.
+// Source of truth: gsd-core/bin/shared/exit-codes.json. Regenerate with:
+//   node scripts/gen-exit-code-registry.cjs --write
+// This exact content is emitted to THREE locations — gsd-core/bin/lib/exit-code-registry.cjs,
+// scripts/lib/exit-code-registry.cjs, and hooks/lib/exit-code-registry.js (the latter two
+// committed so scripts/ and hooks/ consumers work on an unbuilt clone) — all byte-compared by
+// `npm run lint:generated-sync` (#3905 ADR-3889 Phase 1; #3906 Phase 2 added the second copy;
+// #3911 ADR-3889 Phase 7 added the hooks/lib/ copy).
+//
+// exitCodeFor(name) / nameForExitCode(code) are pure and total over this
+// closed table — each throws for anything not registered here.
+
+const EXIT_CODES = Object.freeze([
+  Object.freeze({
+    code: 2,
+    name: "HOOK_DENY",
+    meaning: "Hook protocol deny — the harness blocks the tool call",
+    owner: "hook-adapter",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 64,
+    name: "USAGE",
+    meaning: "Caller error — bad argv, unknown subcommand, missing argument",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 66,
+    name: "NO_INPUT",
+    meaning: "Ran; zero units were in scope, and that emptiness is known to be genuine",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 69,
+    name: "UNAVAILABLE",
+    meaning: "Could not run — prerequisite absent, input unreadable, scope unestablished",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 70,
+    name: "INTERNAL",
+    meaning: "Self-failure — crash, timeout, killed subprocess",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 80,
+    name: "DEGRADED",
+    meaning: "Ran to completion and is reporting a condition through its result payload rather than as a process failure",
+    owner: "gsd-tools",
+    authorizedBy: "ADR-3889 + ADR-2980",
+  })
+]);
+
+const NAME_TO_CODE = new Map(EXIT_CODES.map((entry) => [entry.name, entry.code]));
+const CODE_TO_NAME = new Map(EXIT_CODES.map((entry) => [entry.code, entry.name]));
+
+/**
+ * Resolve the registered exit code for a symbolic name. Pure, total: throws
+ * for anything not an exact, registered, exact-case key — including
+ * non-strings, the empty string, untrimmed strings, wrong case, and
+ * prototype-chain names like `__proto__`/`constructor`/`toString` (a Map
+ * lookup never touches the prototype chain, so these are indistinguishable
+ * from any other unregistered name).
+ *
+ * @param {string} name
+ * @returns {number}
+ */
+function exitCodeFor(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error(`exitCodeFor: name must be a non-empty string, received ${JSON.stringify(name)}`);
+  }
+  if (!NAME_TO_CODE.has(name)) {
+    throw new Error(`exitCodeFor: unregistered exit code name: ${JSON.stringify(name)}`);
+  }
+  return NAME_TO_CODE.get(name);
+}
+
+/**
+ * Reverse of exitCodeFor: resolve the symbolic name for a registered exit
+ * code. Pure, total: throws for anything not an exact, registered code.
+ *
+ * @param {number} code
+ * @returns {string}
+ */
+function nameForExitCode(code) {
+  if (!CODE_TO_NAME.has(code)) {
+    throw new Error(`nameForExitCode: unregistered exit code: ${JSON.stringify(code)}`);
+  }
+  return CODE_TO_NAME.get(code);
+}
+
+module.exports = { EXIT_CODES, exitCodeFor, nameForExitCode };