@opengsd/gsd-core 1.10.0 → 1.12.0

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
@@ -186,29 +230,38 @@ const ERROR_REASON = Object.freeze({
     PHASE_VERIFICATION_INCOMPLETE: 'phase_verification_incomplete',
     PHASE_PLAN_COVERAGE_INCOMPLETE: 'phase_plan_coverage_incomplete',
     SUMMARY_NO_PLANNING: 'summary_no_planning',
+    // #3579: workstream-mode fail-safe guards (init.progress, phase.complete) —
+    // distinguishes "no marker/pointer anywhere" from "a marker exists but
+    // didn't resolve" so a JSON-error-mode caller can branch on `reason`
+    // instead of regexing the human message.
+    WORKSTREAM_MODE_NONE_ACTIVE: 'workstream_mode_none_active',
+    WORKSTREAM_MODE_MARKER_UNRESOLVED: 'workstream_mode_marker_unresolved',
     // 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)
+    COMMIT_DOCS_GUARD_NOT_A_REPO: 'commit_docs_guard_not_a_repo',
+    COMMIT_DOCS_GUARD_FOREIGN_HOOK: 'commit_docs_guard_foreign_hook',
+    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
@@ -223,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,
@@ -243,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()) {

package/gsd-core/bin/lib/markdown-sectionizer.cjs

@@ -26,6 +26,7 @@ exports.stripTaggedBlocks = stripTaggedBlocks;
 exports.replaceSection = replaceSection;
 exports.withSection = withSection;
 exports.deleteSection = deleteSection;
+const pattern_cjs_1 = require("./pattern.cjs");
 // ─── stripFencedCode ──────────────────────────────────────────────────────────
 /**
  * CommonMark-correct fenced-code-block stripper.
@@ -792,7 +793,7 @@ function extractTaggedBlocks(content, tagName, allowAttributes = false) {
  * open>` marks the ACTIVE milestone and must be preserved, not stripped (#557).
  */
 function taggedBlockPattern(tagName, flags, allowAttributes) {
-    const esc = tagName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const esc = (0, pattern_cjs_1.escapeRegex)(tagName);
     const open = allowAttributes ? `<${esc}(?:\\s[^>]{0,1000})?>` : `<${esc}>`;
     const boundary = allowAttributes ? `<${esc}[\\s>]` : `<${esc}>`;
     return new RegExp(`${open}((?:(?!${boundary})[\\s\\S])*?)</${esc}>`, flags);