@opengsd/gsd-core 1.11.0 → 1.12.0

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

@@ -23,6 +23,9 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateMod = require("./capability-state.cjs");
 const { isCapabilityActive } = capabilityStateMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { formatDiagnosticToken } = ioMod;
 // ─── Constants ───────────────────────────────────────────────────────────────
 const INTEL_DIR = '.planning/intel';
 const INTEL_FILES = {
@@ -32,6 +35,16 @@ const INTEL_FILES = {
     arch: 'arch-decisions.json',
     stack: 'stack.json',
 };
+/**
+ * ADR-3473 §8.5 / #3885: recursion bound for the intel JSON search walk.
+ * Restored from the retired SDK lineage (`sdk/src/query/intel.ts` at `11918dcc3^`),
+ * lost in the ADR-0174 consolidation. Unlike the original, hitting the ceiling is
+ * NOT reported as a silent "no match" — the walk that stops early sets a
+ * `truncated` flag threaded back up to `intelQuery`'s result (Decision 4: a
+ * routine that discards an input says so). The bound is on DEPTH only; breadth
+ * (sibling count at any given depth) is unaffected.
+ */
+const MAX_JSON_SEARCH_DEPTH = 48;
 // ─── Internal helpers ────────────────────────────────────────────────────────
 /**
  * Ensure the intel directory exists under the given planning dir.
@@ -71,16 +84,42 @@ function intelFilePath(planningDir, filename) {
 }
 /**
  * Safely read and parse a JSON intel file.
- * Returns null if file doesn't exist or can't be parsed.
+ *
+ * Returns null for THREE distinct on-disk states, only one of which is a
+ * "quiet" case (#3885, ADR-3473 §8.5):
+ *   - ABSENT (ENOENT, via platformReadSync returning null): silent — not
+ *     every project has every intel file, and callers already loop over
+ *     the full INTEL_FILES set expecting misses. Never pushed to `errors`.
+ *   - UNREADABLE (EACCES/EIO/... — platformReadSync rethrows anything that
+ *     isn't ENOENT): surfaced, naming the file, when `errors` is supplied.
+ *   - MALFORMED (JSON.parse throws on a file that WAS read successfully):
+ *     also surfaced, naming the file — a corrupt intel file used to read
+ *     identically to "no matches", which is the same defect one layer down.
+ *
+ * `errors` is an optional accumulator so callers that want to thread the
+ * outcome into their own result shape can pass an array and read it back
+ * after the call; callers that omit it keep the prior fold-to-null shape.
  */
-function safeReadJson(filePath) {
+function safeReadJson(filePath, errors) {
+    let raw;
+    try {
+        raw = (0, shell_command_projection_cjs_1.platformReadSync)(filePath);
+    }
+    catch (err) {
+        if (errors) {
+            errors.push(`Could not read ${formatDiagnosticToken(filePath)}: ${formatDiagnosticToken(err?.message ?? String(err))}`);
+        }
+        return null;
+    }
+    if (raw === null)
+        return null; // ENOENT — genuinely absent, not an error.
     try {
-        const raw = (0, shell_command_projection_cjs_1.platformReadSync)(filePath);
-        if (raw === null)
-            return null;
         return JSON.parse(raw);
     }
-    catch {
+    catch (err) {
+        if (errors) {
+            errors.push(`Could not parse ${formatDiagnosticToken(filePath)}: ${formatDiagnosticToken(err?.message ?? String(err))}`);
+        }
         return null;
     }
 }
@@ -101,16 +140,17 @@ function hashFile(filePath) {
 }
 /**
  * Search for a term (case-insensitive) in a JSON object's keys and string values.
- * Returns an array of matching entries.
+ * Returns matching entries plus whether the walk hit MAX_JSON_SEARCH_DEPTH.
  */
 function searchJsonEntries(data, term) {
     if (!data || typeof data !== 'object')
-        return [];
+        return { matches: [], truncated: false };
     const entries = data.entries || data;
     if (!entries || typeof entries !== 'object')
-        return [];
+        return { matches: [], truncated: false };
     const lowerTerm = term.toLowerCase();
     const matches = [];
+    const state = { truncated: false };
     for (const [key, value] of Object.entries(entries)) {
         if (key === '_meta')
             continue;
@@ -119,25 +159,40 @@ function searchJsonEntries(data, term) {
             matches.push({ key, value });
             continue;
         }
-        // Check string value match (recursive for objects)
-        if (matchesInValue(value, lowerTerm)) {
+        // Check string value match (recursive for objects/arrays, bounded by depth)
+        if (matchesInValue(value, lowerTerm, 0, state)) {
             matches.push({ key, value });
         }
     }
-    return matches;
+    return { matches, truncated: state.truncated };
 }
 /**
  * Recursively check if a term appears in any string value.
+ *
+ * `depth` counts container unwraps already performed (starts at 0 for the
+ * entry's own value). Strings never fail the ceiling check themselves — only
+ * a container (object/array) refuses to recurse one level deeper once
+ * `depth > MAX_JSON_SEARCH_DEPTH`, at which point `state.truncated` is set so
+ * the caller can report "I stopped looking" rather than a bare "no match".
+ * The bound is on nesting depth only, never on sibling breadth.
  */
-function matchesInValue(value, lowerTerm) {
+function matchesInValue(value, lowerTerm, depth, state) {
     if (typeof value === 'string') {
         return value.toLowerCase().includes(lowerTerm);
     }
     if (Array.isArray(value)) {
-        return value.some(v => matchesInValue(v, lowerTerm));
+        if (depth > MAX_JSON_SEARCH_DEPTH) {
+            state.truncated = true;
+            return false;
+        }
+        return value.some(v => matchesInValue(v, lowerTerm, depth + 1, state));
     }
     if (value && typeof value === 'object') {
-        return Object.values(value).some(v => matchesInValue(v, lowerTerm));
+        if (depth > MAX_JSON_SEARCH_DEPTH) {
+            state.truncated = true;
+            return false;
+        }
+        return Object.values(value).some(v => matchesInValue(v, lowerTerm, depth + 1, state));
     }
     return false;
 }
@@ -150,19 +205,23 @@ function intelQuery(term, planningDir) {
         return disabledResponse();
     const matches = [];
     let total = 0;
+    let truncated = false;
+    const readErrors = [];
     // Search all JSON intel files
     for (const [_key, filename] of Object.entries(INTEL_FILES)) {
         const filePath = intelFilePath(planningDir, filename);
-        const data = safeReadJson(filePath);
+        const data = safeReadJson(filePath, readErrors);
         if (!data)
             continue;
-        const found = searchJsonEntries(data, term);
+        const { matches: found, truncated: fileTruncated } = searchJsonEntries(data, term);
+        if (fileTruncated)
+            truncated = true;
         if (found.length > 0) {
             matches.push({ source: filename, entries: found });
             total += found.length;
         }
     }
-    return { matches, term, total };
+    return { matches, term, total, truncated, read_errors: readErrors };
 }
 /**
  * Report status and staleness of each intel file.
@@ -179,13 +238,14 @@ function intelStatus(planningDir) {
         const filePath = intelFilePath(planningDir, filename);
         const exists = node_fs_1.default.existsSync(filePath);
         if (!exists) {
-            files[filename] = { exists: false, updated_at: null, stale: true };
+            files[filename] = { exists: false, updated_at: null, stale: true, read_error: null };
             overallStale = true;
             continue;
         }
         let updatedAt = null;
         // All intel files are JSON — read _meta.updated_at
-        const data = safeReadJson(filePath);
+        const readErrors = [];
+        const data = safeReadJson(filePath, readErrors);
         if (data && data._meta && data._meta.updated_at) {
             updatedAt = data._meta.updated_at;
         }
@@ -196,7 +256,7 @@ function intelStatus(planningDir) {
         }
         if (stale)
             overallStale = true;
-        files[filename] = { exists: true, updated_at: updatedAt, stale };
+        files[filename] = { exists: true, updated_at: updatedAt, stale, read_error: readErrors[0] ?? null };
     }
     return { files, overall_stale: overallStale };
 }
@@ -207,9 +267,15 @@ function intelDiff(planningDir) {
     if (!isIntelCapabilityActive(planningDir))
         return disabledResponse();
     const snapshotPath = intelFilePath(planningDir, '.last-refresh.json');
-    const snapshot = safeReadJson(snapshotPath);
+    const readErrors = [];
+    const snapshot = safeReadJson(snapshotPath, readErrors);
     if (!snapshot) {
-        return { no_baseline: true };
+        // #3885 (ADR-3473 §8.5): `no_baseline: true` stays true for BOTH a
+        // genuinely-never-snapshotted project (ENOENT, read_error stays null)
+        // AND a present-but-unreadable/malformed snapshot — collapsing those
+        // two into a bare `no_baseline: true` would manufacture "you've never
+        // run a refresh" out of a read failure. `read_error` names which one.
+        return { no_baseline: true, read_error: readErrors[0] ?? null };
     }
     const prevHashes = snapshot.hashes || {};
     const changed = [];
@@ -374,7 +440,9 @@ function intelApiSurface(planningDir) {
     const intelPath = ensureIntelDir(planningDir);
     const apiMapPath = node_path_1.default.join(intelPath, INTEL_FILES.apis);
     const outputPath = node_path_1.default.join(intelPath, 'API-SURFACE.md');
-    const data = safeReadJson(apiMapPath);
+    const readErrors = [];
+    const data = safeReadJson(apiMapPath, readErrors);
+    const readError = readErrors[0] ?? null;
     const entries = (data && data.entries && typeof data.entries === 'object')
         ? Object.entries(data.entries)
         : [];
@@ -392,7 +460,14 @@ function intelApiSurface(planningDir) {
     lines.push('> Generated from `.planning/intel/api-map.json`. Do not edit by hand.');
     lines.push('');
     if (symbolCount === 0) {
-        lines.push('> **Incomplete:** api-map.json has no entries (intel extraction is regex/JS-only or not yet populated).');
+        if (readError) {
+            // #3885: a read/parse failure is NOT "not yet populated" — say so,
+            // rather than manufacturing the wrong reason for the empty surface.
+            lines.push(`> **Incomplete:** ${readError}`);
+        }
+        else {
+            lines.push('> **Incomplete:** api-map.json has no entries (intel extraction is regex/JS-only or not yet populated).');
+        }
         lines.push('> Treat absence here as "unknown", not "does not exist".');
         lines.push('');
     }
@@ -414,7 +489,7 @@ function intelApiSurface(planningDir) {
         }
     }
     (0, shell_command_projection_cjs_1.platformWriteSync)(outputPath, lines.join('\n'));
-    return { written: outputPath, symbolCount, stale };
+    return { written: outputPath, symbolCount, stale, read_error: readError };
 }
 /**
  * Patch _meta.updated_at in a JSON intel file to the current timestamp.

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

@@ -15,6 +15,9 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { setJsonErrorMode, getJsonErrorMode, EXIT_ENVELOPE_REASON, ExitError, setPendingOutcome, projectOutcome, getContractVersion, } = cliExitModule;
 // ─── Temp-file helpers (needed by output()) ──────────────────────────────────
 /**
  * Dedicated GSD temp directory: path.join(os.tmpdir(), 'gsd').
@@ -134,7 +137,48 @@ function writeAllSync(fd, data) {
 function serializeForOutput(result) {
     return JSON.stringify(result, null, 2);
 }
+/**
+ * A payload-carried error, per ADR-2980's own definition (#3912, ADR-3889
+ * §4): `result` is an object carrying a SERIALIZABLE `error` property, in
+ * ANY key order — `{ found: false, error }` counts exactly the same as
+ * `{ error, found: false }`. The discriminator is a serializable error
+ * value, NOT mere key presence: `result.error`'s own truthiness is
+ * irrelevant (falsy `0`/`null`/`''` all count), and neither is `result`'s
+ * prototype (a plain object literal is all any call site here ever
+ * passes) — but `error: undefined` does NOT count, because
+ * `JSON.stringify` (the exact serializer `serializeForOutput` uses to
+ * build the payload the caller actually receives) drops an object
+ * property whose value is `undefined` entirely. A payload built as
+ * `{ found: false, error: undefined }` therefore reaches the wire as
+ * `{"found":false}` — no error at all — and recording DEGRADED for it
+ * would be a false verdict: exit 80 under v2 for output the user sees as
+ * clean. `hasOwnProperty` alone is not enough to answer "does this payload
+ * declare an error"; it must also survive `JSON.stringify`.
+ */
+function isPayloadCarriedError(result) {
+    return typeof result === 'object' && result !== null
+        && Object.prototype.hasOwnProperty.call(result, 'error')
+        && result.error !== undefined;
+}
 function output(result, raw, rawValue) {
+    // #3912 (ADR-3889 §4): a payload-carried error declares DEGRADED into the
+    // pending-outcome cell runMain reads. This is the ONLY new thing output()
+    // does — it still just writes fd 1 and returns; the exit code stays
+    // whatever it already was under v1 (DEGRADED projects to 0), and nothing
+    // here touches process.exitCode directly.
+    //
+    // LAST-WRITE-WINS (review fix): a clean (non-error-shaped) payload CLEARS
+    // the cell rather than leaving a prior degraded declaration in place. A
+    // handler that calls output() more than once per invocation — a
+    // diagnostic error payload followed by a clean final payload — must have
+    // its LATEST declaration win, not its first: the cell reflects "is a
+    // degraded outcome pending right now", not "was one ever declared".
+    if (isPayloadCarriedError(result)) {
+        setPendingOutcome('DEGRADED');
+    }
+    else {
+        setPendingOutcome(undefined);
+    }
     let data;
     if (raw && rawValue !== undefined) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -178,7 +222,7 @@ const ERROR_REASON = Object.freeze({
     CONFIG_PARSE_FAILED: 'config_parse_failed',
     CONFIG_INVALID_KEY: 'config_invalid_key',
     // SDK / gsd-tools dispatch
-    SDK_FAIL_FAST: 'sdk_fail_fast',
+    SDK_FAIL_FAST: EXIT_ENVELOPE_REASON,
     SDK_UNKNOWN_COMMAND: 'sdk_unknown_command',
     SDK_MISSING_ARG: 'sdk_missing_arg',
     // workflow / phase
@@ -195,6 +239,10 @@ const ERROR_REASON = Object.freeze({
     // graphify
     GRAPHIFY_NO_GRAPH: 'graphify_no_graph',
     GRAPHIFY_INVALID_QUERY: 'graphify_invalid_query',
+    // estimate-calibrate (#3882, ADR-3473 §8.2): the phases directory exists
+    // but could not be read — a NON-answer, distinct from a project that
+    // genuinely has zero completed phases yet.
+    ESTIMATE_PHASES_UNREADABLE: 'estimate_phases_unreadable',
     // hooks
     HOOKS_OPT_OUT: 'hooks_opt_out',
     // commit-docs-guard (#3588)
@@ -203,22 +251,17 @@ const ERROR_REASON = Object.freeze({
     COMMIT_DOCS_GUARD_HOOKS_PATH_SET: 'commit_docs_guard_hooks_path_set',
     // security-scan
     SECURITY_SCAN_FAILED: 'security_scan_failed',
+    // --pick (#3365 / #3358, ADR-3473 §8.4): an absent field or non-JSON
+    // command output is a failure, never a demotion to an empty answer at
+    // exit 0. See .gsd/phase/feat-3884-failure-is-a-value/40-design.md.
+    PICK_FIELD_ABSENT: 'pick_field_absent',
+    PICK_OUTPUT_NOT_JSON: 'pick_output_not_json',
     // generic
     USAGE: 'usage',
     UNKNOWN: 'unknown',
 });
-/**
- * Process-level flag: when true, error() emits structured JSON to stderr
- * instead of plain "Error: <message>" text. Set by gsd-tools.cjs when the
- * CLI is invoked with `--json-errors`. Tests opt in to typed-IR error
- * assertions by passing that flag and parsing the JSON.
- *
- * Default off so existing callers and human operators keep their plain-text
- * diagnostics. The structured form is opt-in for tooling and tests (#2974).
- */
-let _jsonErrorMode = false;
-function setJsonErrorMode(v) { _jsonErrorMode = !!v; }
-function getJsonErrorMode() { return _jsonErrorMode; }
+// setJsonErrorMode / getJsonErrorMode now live in cli-exit.cts (imported above)
+// and are re-exported here for the callers that already import them from io.
 /**
  * Emit an error and exit. When the second argument is provided it must be
  * a value from ERROR_REASON; tests can assert on `result.reason`. When the
@@ -233,15 +276,116 @@ function getJsonErrorMode() { return _jsonErrorMode; }
  * human-readable text. Ignored entirely in plain-text mode — the human
  * message is the only thing an operator sees there.
  */
+/**
+ * Render an UNTRUSTED string for embedding inside a human-readable,
+ * plain-text diagnostic (the `'Error: ' + message` line `error()` writes in
+ * non-JSON mode).
+ *
+ * WHY THIS EXISTS AND WHY `error()` DOES NOT DO IT ITSELF: `error()`
+ * deliberately writes its `message` argument verbatim — several callers in
+ * this repo intentionally emit multi-line diagnostics (e.g. the phase-gate
+ * messages), and `error()` has no way to distinguish a legitimate multi-line
+ * message from a hostile one, so it must not mangle newlines generically.
+ * That means any UNTRUSTED substring a caller interpolates into `message`
+ * (an argv token, a JSON key/value read back from a command's own output,
+ * etc.) can smuggle its own `\n` and forge a second `Error: ` line on
+ * stderr — a caller that parses stderr line-by-line would then see a second,
+ * attacker-authored error. Every call site that interpolates untrusted data
+ * into a diagnostic MUST pass that substring through this function first;
+ * `error()` itself stays a dumb, faithful writer.
+ *
+ * `JSON.stringify` is the primitive: it wraps the value in quotes and
+ * escapes control characters (`\n`, `\r`, `\t`, and the rest of the C0
+ * range, plus the quote character itself), so the result can never span
+ * more than one line or introduce an unescaped `"`. Callers embedding the
+ * result MUST NOT add their own surrounding quotes — that would
+ * double-quote it.
+ */
+function formatDiagnosticToken(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Map an ERROR_REASON wire value onto a declared outcome name (#3912,
+ * ADR-3889 §4). Closed over the 25-member enum: every reason gets an
+ * explicit entry below, so a 26th member added without a mapping falls
+ * through to the `?? 'FAIL'` default rather than silently mis-projecting —
+ * and tests/A1 iterates `Object.values(ERROR_REASON)`, so that default is
+ * exactly what makes an unmapped addition visible instead of invisible.
+ *
+ * This function's result is ONLY consulted under v2 (see `error()` below) —
+ * it is deliberately never routed through `projectOutcome` under v1, which
+ * is what keeps the v1 pin intact (`projectOutcome` treats registered names
+ * as version-invariant, so e.g. USAGE would otherwise become 64 today).
+ *
+ * Each non-FAIL choice below is justified inline; `UNKNOWN` and anything
+ * with no clearly better fit stays `FAIL` — the honest default the design
+ * calls for, not a guess dressed up as a specific outcome.
+ */
+const REASON_TO_OUTCOME = Object.freeze({
+    // Bad argv/subcommand/argument — the caller, not the run, is at fault.
+    [ERROR_REASON.CONFIG_INVALID_KEY]: 'USAGE',
+    [ERROR_REASON.SDK_UNKNOWN_COMMAND]: 'USAGE',
+    [ERROR_REASON.SDK_MISSING_ARG]: 'USAGE',
+    [ERROR_REASON.GRAPHIFY_INVALID_QUERY]: 'USAGE',
+    [ERROR_REASON.USAGE]: 'USAGE',
+    // A specific, named thing does not exist / nothing was there to find —
+    // genuine, known emptiness rather than a broken prerequisite.
+    [ERROR_REASON.CONFIG_KEY_NOT_FOUND]: 'NO_INPUT',
+    [ERROR_REASON.SUMMARY_NO_PLANNING]: 'NO_INPUT',
+    [ERROR_REASON.WORKSTREAM_MODE_NONE_ACTIVE]: 'NO_INPUT',
+    // A prerequisite is absent, unreadable, or otherwise not in a state the
+    // run could proceed from — distinct from NO_INPUT's genuine emptiness.
+    [ERROR_REASON.CONFIG_NO_FILE]: 'UNAVAILABLE',
+    [ERROR_REASON.CONFIG_PARSE_FAILED]: 'UNAVAILABLE',
+    [ERROR_REASON.PHASE_NOT_FOUND]: 'UNAVAILABLE',
+    [ERROR_REASON.PHASE_VERIFICATION_INCOMPLETE]: 'UNAVAILABLE',
+    [ERROR_REASON.PHASE_PLAN_COVERAGE_INCOMPLETE]: 'UNAVAILABLE',
+    // Its own docstring: "a marker exists but didn't resolve" — a broken
+    // prerequisite, not the "no marker anywhere" emptiness NONE_ACTIVE covers.
+    [ERROR_REASON.WORKSTREAM_MODE_MARKER_UNRESOLVED]: 'UNAVAILABLE',
+    [ERROR_REASON.GRAPHIFY_NO_GRAPH]: 'UNAVAILABLE',
+    // Its own docstring: "a NON-answer, distinct from a project that
+    // genuinely has zero completed phases yet" — UNAVAILABLE, not NO_INPUT.
+    [ERROR_REASON.ESTIMATE_PHASES_UNREADABLE]: 'UNAVAILABLE',
+    [ERROR_REASON.COMMIT_DOCS_GUARD_NOT_A_REPO]: 'UNAVAILABLE',
+    [ERROR_REASON.COMMIT_DOCS_GUARD_FOREIGN_HOOK]: 'UNAVAILABLE',
+    [ERROR_REASON.COMMIT_DOCS_GUARD_HOOKS_PATH_SET]: 'UNAVAILABLE',
+    // Its own docstring: "an absent field or non-JSON command output is a
+    // failure, never a demotion to an empty answer" — the field/output was
+    // supposed to be there and was not; a prerequisite of the query failed.
+    [ERROR_REASON.PICK_FIELD_ABSENT]: 'UNAVAILABLE',
+    [ERROR_REASON.PICK_OUTPUT_NOT_JSON]: 'UNAVAILABLE',
+    // Self-failure: the run itself broke, not its inputs.
+    [ERROR_REASON.SDK_FAIL_FAST]: 'INTERNAL',
+    [ERROR_REASON.SECURITY_SCAN_FAILED]: 'INTERNAL',
+    // No clearly better fit — the honest default, per design.
+    [ERROR_REASON.HOOKS_OPT_OUT]: 'FAIL',
+    [ERROR_REASON.UNKNOWN]: 'FAIL',
+});
+function outcomeForReason(reason) {
+    return REASON_TO_OUTCOME[reason] ?? 'FAIL';
+}
 function error(message, reason = ERROR_REASON.UNKNOWN, extra) {
-    if (_jsonErrorMode) {
+    if (getJsonErrorMode()) {
         const payload = JSON.stringify({ ok: false, reason, message, ...(extra || {}) }) + '\n';
         writeAllSync(2, payload);
     }
     else {
         writeAllSync(2, 'Error: ' + message + '\n');
     }
-    process.exit(1);
+    // #3912 (ADR-3889 §4): the declaration is version-gated HERE, not inside
+    // projectOutcome — registered names are version-invariant there, so
+    // routing every reason through it unconditionally would change v1 exit
+    // codes today (e.g. USAGE -> 64) and break the pin. Under v1 the exit
+    // stays ExitError(1) unconditionally, byte-identical to every prior
+    // release; only v2 projects the declared outcome through the registry.
+    if (getContractVersion() === 'v2') {
+        throw new ExitError(projectOutcome(outcomeForReason(reason), 'v2'));
+    }
+    // No message passed to ExitError: the stderr write above is already done,
+    // byte-identical to the prior process.exit(1) behavior, and ExitError with
+    // no message means runMain's catch adds nothing further to stderr.
+    throw new ExitError(1);
 }
 module.exports = {
     GSD_TEMP_DIR,
@@ -253,4 +397,5 @@ module.exports = {
     setJsonErrorMode,
     getJsonErrorMode,
     error,
+    formatDiagnosticToken,
 };

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

@@ -21,6 +21,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocator = require("./phase-locator.cjs");
 const node_os_1 = __importDefault(require("node:os"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
@@ -145,9 +147,55 @@ function learningsDelete(id, opts) {
     node_fs_1.default.unlinkSync(filePath);
     return true;
 }
+/**
+ * #3683 — resolve which learnings artifact a copy reads. The extractor writes
+ * phase-scoped `{PHASE_DIR}/{PADDED}-LEARNINGS.md`; the legacy shape is a
+ * project-root `LEARNINGS.md`. The MOST RECENT phase-scoped artifact wins (a
+ * gated completion copies the phase it just wrote); the project-root file is
+ * the fallback when no phase artifact exists. Returns null when neither shape
+ * is present.
+ */
+function resolveLearningsSource(planningDir) {
+    let best = null;
+    const phasesDir = node_path_1.default.join(planningDir, 'phases');
+    // Phase enumeration routes through the sanctioned seam (the #3185 drift
+    // guard rejects ad-hoc re-derivations): no cwd → every phase dir in the
+    // tree, sentinel dirs excluded, unreadable phases dir already degraded to
+    // an empty list by the locator itself.
+    const { value: phaseDirNames } = phaseLocator.listMilestonePhaseDirs(phasesDir);
+    for (const entry of phaseDirNames) {
+        const phaseDir = node_path_1.default.join(phasesDir, entry);
+        let files;
+        try {
+            files = node_fs_1.default.readdirSync(phaseDir);
+        }
+        catch {
+            // An unreadable phase dir (ACL, removal race) must not crash the copy —
+            // skip it and keep scanning.
+            continue;
+        }
+        for (const f of files) {
+            if (!/-LEARNINGS\.md$/i.test(f))
+                continue;
+            const p = node_path_1.default.join(phaseDir, f);
+            try {
+                const m = node_fs_1.default.statSync(p).mtimeMs;
+                if (best === null || m > best.m)
+                    best = { p, m };
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    if (best !== null)
+        return best.p;
+    const rootPath = node_path_1.default.join(planningDir, 'LEARNINGS.md');
+    return node_fs_1.default.existsSync(rootPath) ? rootPath : null;
+}
 function learningsCopyFromProject(planningDir, opts) {
-    const learningsPath = node_path_1.default.join(planningDir, 'LEARNINGS.md');
-    if (!node_fs_1.default.existsSync(learningsPath)) {
+    const learningsPath = resolveLearningsSource(planningDir);
+    if (learningsPath === null) {
         return { total: 0, created: 0, skipped: 0 };
     }
     const content = node_fs_1.default.readFileSync(learningsPath, 'utf-8');
@@ -167,29 +215,52 @@ function learningsCopyFromProject(planningDir, opts) {
             dedupeIndex.set(existing.content_hash, existing.id);
         }
     }
-    // Parse markdown: split on ## headings
+    // Parse markdown: split on ## category headings.
+    // #3683: the real producer (extract-learnings.md write_learnings) writes ##
+    // categories containing ### item headings — each item is ONE learning (the
+    // store's relevance contract caps injection by count, so category-sized
+    // blobs defeat it). A bare ## section with no ### items keeps the legacy
+    // single-learning shape.
     const sections = content.split(/^## /m).slice(1); // skip preamble before first ##
     let created = 0;
     let skipped = 0;
-    for (const section of sections) {
-        const lines = section.trim().split('\n');
-        const title = lines[0].trim();
-        const body = lines.slice(1).join('\n').trim();
-        if (!body)
-            continue;
-        // Extract tags from title (simple: use words as tags)
-        const tags = title.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+    const writeOne = (title, body, extraTags) => {
+        const tags = Array.from(new Set([
+            ...extraTags,
+            ...title.toLowerCase().split(/\s+/).filter(w => w.length > 2),
+        ]));
         const result = learningsWrite({
             source_project: sourceProject,
             learning: body,
             context: title,
             tags,
         }, { ...opts, dedupeIndex });
-        if (result.created) {
+        if (result.created)
             created++;
-        }
-        else {
+        else
             skipped++;
+    };
+    for (const section of sections) {
+        const lines = section.trim().split('\n');
+        const category = lines[0].trim();
+        const body = lines.slice(1).join('\n').trim();
+        if (!body)
+            continue;
+        const categoryTag = category.toLowerCase().split(/\s+/)[0] || '';
+        // Split into ### items when present; otherwise one learning per section.
+        const items = body.split(/^### /m).map(s => s.trim()).filter(s => s.length > 0);
+        const hasItemHeadings = /^### /m.test(body);
+        if (!hasItemHeadings) {
+            writeOne(category, body, categoryTag ? [categoryTag] : []);
+            continue;
+        }
+        for (const item of items) {
+            const itemLines = item.split('\n');
+            const title = itemLines[0].trim();
+            const itemBody = itemLines.slice(1).join('\n').trim();
+            if (!itemBody && !title)
+                continue;
+            writeOne(title, itemBody || title, categoryTag ? [categoryTag] : []);
         }
     }
     return { total: created + skipped, created, skipped };

package/gsd-core/bin/lib/legacy-cleanup.cjs

@@ -262,8 +262,14 @@ function planLegacyCleanup(configDirs, opts = {}) {
     }
   }
 
-  // Legacy shared cache (fixed name from the old package)
-  const legacyCachePath = path.join(homeDir, '.cache', 'gsd', 'gsd-update-check.json');
+  // Legacy shared cache (fixed name from the old package). #3799: under an
+  // explicit configDirs override the cache lives under the SCOPE root(s), not
+  // the default home — the override means "clean only what this redirected
+  // install owns", and the default home's cache belongs to the live install.
+  const cacheRoot = (Array.isArray(opts.configDirs) && opts.configDirs.length > 0)
+    ? opts.configDirs[0]
+    : homeDir;
+  const legacyCachePath = path.join(cacheRoot, '.cache', 'gsd', 'gsd-update-check.json');
   try {
     const stat = fsMod.statSync(legacyCachePath);
     if (stat.isFile()) {