@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/gate-codebase-drift.cjs

@@ -0,0 +1,285 @@
+"use strict";
+/**
+ * `check verify-codebase-drift` as a gate module (#5219, epic #5056, ADR-5057 §4 closing arm C): it
+ * returns a `GateResult`; the command router formats it. Imports no io module and performs no direct
+ * console/stdout/stderr write (ESLint-enforced).
+ *
+ * The `drift` capability's gate at `execute:wave:post`. It diffs the repository's HEAD against the
+ * commit `.planning/codebase/STRUCTURE.md` was last mapped at (`last_mapped_commit`, stamped by
+ * `stamp-codebase-map`) and reports structural change the map does not describe (`detectDrift`,
+ * `drift.cjs`). Non-blocking unless the drift crosses the configured threshold (`block` = the drift
+ * library's `actionRequired`).
+ *
+ * Dispatched gate, payload exit mode (see `gate-schema-drift.cts`): a blocking verdict is exit 0 and
+ * "could not look" is exit 69 (#5170).
+ *
+ * Non-blocking contract: a throw anywhere yields a non-blocking `unreadable` verdict, never a crash.
+ *
+ * Argv after the verb: none.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateCodebaseDriftGate = evaluateCodebaseDriftGate;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_config_cjs_1 = require("./gate-config.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+const planningWorkspace = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- worktree-safety.cjs is an export= CommonJS module
+const worktreeSafetyMod = require("./worktree-safety.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- onboard-projection.cjs is an export= CommonJS module
+const onboardProjectionMod = require("./onboard-projection.cjs");
+// drift.cjs is a pure library that imports no gate or verify module, so it is loaded at the top.
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- drift.cjs is an export= CommonJS module
+const driftModule = require("./drift.cjs");
+const drift = driftModule;
+/**
+ * A mapped-commit stamp must be a hex object id (abbreviated to at least 7, or a full SHA-1 / SHA-256
+ * id) before git sees it. A ref name (`HEAD`), a shorter abbreviation and an option-shaped value
+ * (`--batch`) are not baselines: each is routed to `unresolvable-mapped-commit`, so no stamp can reach
+ * `git cat-file` / `git diff` as anything but an object id.
+ */
+const HEX_OBJECT_ID_RE = /^[0-9a-f]{7,64}$/i;
+const { planningDir, planningRoot } = planningWorkspace;
+// Single owner of git C-quoted-path decoding (see #4081 note at the --name-status parse loop).
+const { decodeGitQuotedPath } = worktreeSafetyMod;
+const { REQUIRED_CODEBASE_MAP_FILES } = onboardProjectionMod;
+/**
+ * A generated document is read only when it is a regular file (symlinks followed) no larger than
+ * this: a FIFO would block the gate forever and a huge file would exhaust memory.
+ */
+const MAX_DOCUMENT_BYTES = 1048576;
+function readDocument(file) {
+    const st = node_fs_1.default.statSync(file);
+    if (!st.isFile())
+        throw new Error('not a regular file');
+    if (st.size > MAX_DOCUMENT_BYTES)
+        throw new Error(`larger than ${MAX_DOCUMENT_BYTES} bytes`);
+    return node_fs_1.default.readFileSync(file, 'utf-8');
+}
+/**
+ * The drift gates' fixed non-answer payload; `skip` is a documented "nothing to compare", `unreadable`
+ * is "could not look" (#5170) and exits UNAVAILABLE. Both keep the non-blocking payload.
+ */
+function nonAnswer(reason, extra = {}) {
+    return {
+        // Uniform gate contract: block = action_required (false when skipped).
+        block: false,
+        skipped: true,
+        reason,
+        action_required: false,
+        directive: 'none',
+        elements: [],
+        ...extra,
+    };
+}
+function skipped(reason, extra = {}) {
+    return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, nonAnswer(reason, extra));
+}
+function unreadable(reason, extra = {}) {
+    return (0, gate_verdict_cjs_1.gateUnreadable)(false, nonAnswer(reason, extra));
+}
+function runCodebaseDriftGate(cwd) {
+    const codebaseDir = node_path_1.default.join(planningDir(cwd), 'codebase');
+    const structurePath = node_path_1.default.join(codebaseDir, 'STRUCTURE.md');
+    let structureMd;
+    try {
+        structureMd = readDocument(structurePath);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return skipped('no-structure-md');
+        }
+        return unreadable('cannot-read-structure-md: ' + (err instanceof Error ? err.message : String(err)));
+    }
+    const lastMapped = drift['readMappedCommit'](structurePath);
+    const revProbe = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', 'HEAD'], { cwd });
+    if (revProbe.exitCode !== 0) {
+        return skipped('not-a-git-repo');
+    }
+    // #3418: an absent or unresolvable baseline means NO COMPARISON IS POSSIBLE.
+    // It is neither zero drift nor total drift, and reporting it as either is a
+    // lie the consumer cannot detect. The former fallback diffed HEAD against
+    // the empty tree, so every tracked file read as newly added and the gate
+    // reported maximum drift identically on every run -- which made a genuinely
+    // stale map indistinguishable from a fresh one, and let `spawn_mapper` fire
+    // a whole-repo remap while presenting itself as an incremental one.
+    if (!lastMapped) {
+        return skipped('no-mapped-commit', { last_mapped_commit: null });
+    }
+    // A stamp that is not a hex object id is not a baseline (a ref name such as `HEAD` would "resolve" to
+    // a commit and diff against the wrong object; an option-shaped value must never reach git): same arm
+    // as a stamp git cannot resolve, and no git call is made with it.
+    if (!HEX_OBJECT_ID_RE.test(lastMapped)) {
+        return unreadable('unresolvable-mapped-commit', { last_mapped_commit: lastMapped });
+    }
+    const baseProbe = (0, shell_command_projection_cjs_1.execGit)(['cat-file', '-t', lastMapped], { cwd });
+    if (baseProbe.exitCode !== 0 || baseProbe.stdout.trim() !== 'commit') {
+        // A stamp git cannot resolve: history rewrite, GC, or a shallow clone.
+        // Distinct reason from 'no-mapped-commit' -- the map claims a baseline,
+        // this repository just cannot see it, which is an operator-actionable
+        // difference (re-map vs. unshallow). A resolvable non-commit (a tree or
+        // blob sha) is the same class of bad baseline: git would happily diff
+        // against it and report drift against the wrong object.
+        // The repository cannot resolve the baseline the map claims: it could not look (#5170).
+        return unreadable('unresolvable-mapped-commit', { last_mapped_commit: lastMapped });
+    }
+    const base = lastMapped;
+    const diff = (0, shell_command_projection_cjs_1.execGit)(['diff', '--name-status', base, 'HEAD'], { cwd });
+    if (diff.exitCode !== 0) {
+        return unreadable('git-diff-failed');
+    }
+    // #3418: GSD's own planning artifacts are not codebase structure. A
+    // map-codebase run commits `.planning/codebase/*.md`, so a correctly
+    // stamped baseline would be re-poisoned by the very commit that carries
+    // the stamp -- the next gate invocation would report the map's own seven
+    // documents as seven new directories, back over the default threshold of
+    // three. Derived from planningRoot() rather than a hardcoded literal so a
+    // repoint of the planning root cannot leave this filter behind.
+    //
+    // `git diff --name-status` always prints repo-root-relative paths, so a cwd
+    // below the root needs the `sub/` prefix or the filter matches nothing.
+    // That prefix comes from git (`--show-prefix`: root-relative, forward
+    // slashes, trailing slash, empty at the root). The rejected alternative was
+    // path.relative(`--show-toplevel`, cwd), which mixes two path producers: on
+    // Windows os.tmpdir() hands back the 8.3 short form while git resolves the
+    // long one, so relative() between them yields a `../..` chain that matches
+    // nothing. The `.planning` half below is safe to compute with relative()
+    // because both of its sides are the same cwd string.
+    const prefixProbe = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--show-prefix'], { cwd });
+    const repoPrefix = prefixProbe.exitCode === 0 ? prefixProbe.stdout.trim() : '';
+    const planningPrefix = repoPrefix + node_path_1.default.relative(cwd, planningRoot(cwd)).split(node_path_1.default.sep).join('/') + '/';
+    const isPlanningArtifact = (file) => file.split('\\').join('/').startsWith(planningPrefix);
+    const added = [];
+    const modified = [];
+    const deleted = [];
+    for (const line of diff.stdout.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        const m = line.match(/^([A-Z])\d*\t(.+?)(?:\t(.+))?$/);
+        if (!m)
+            continue;
+        const status = m[1];
+        // execGit sets no core.quotepath config, so git's default `true` applies:
+        // any path containing non-ASCII bytes (or `"`, `\`, control bytes) is
+        // C-quoted — `"docs/\350\256\276…/overview.md"`. Capturing that verbatim
+        // garbles affected_paths/elements and makes isPathMapped compare the
+        // quoted prefix (`"docs`) against STRUCTURE.md, misclassifying DOCUMENTED
+        // directories as new_dir (#4081). Decode with the single owner of the
+        // git C-quote seam (worktree-safety.cjs); a non-quoted value — the plain
+        // ASCII common case — passes through untouched. Both capture groups are
+        // decoded: R/C lines carry old AND new paths, either may be quoted.
+        // A rename is a deletion of the old path plus an addition of the new
+        // one; a copy leaves its source in place and adds only the new path.
+        const oldPath = decodeGitQuotedPath(m[2]);
+        const newPath = m[3] ? decodeGitQuotedPath(m[3]) : oldPath;
+        const put = (file, into) => {
+            if (!isPlanningArtifact(file))
+                into.push(file);
+        };
+        if (status === 'R') {
+            put(oldPath, deleted);
+            put(newPath, added);
+        }
+        else if (status === 'C')
+            put(newPath, added);
+        else if (status === 'A')
+            put(newPath, added);
+        else if (status === 'M' || status === 'T')
+            put(newPath, modified);
+        else if (status === 'D')
+            put(newPath, deleted);
+    }
+    // Every generated document is territory the map describes, so all seven are
+    // read (the one owner of the names is REQUIRED_CODEBASE_MAP_FILES).
+    // STRUCTURE.md was read above; an unreadable other document is omitted and
+    // named rather than sinking the whole check, and an absent one is simply
+    // not part of this map (a `--fast` map writes four of the seven).
+    const documents = {};
+    const documentsRead = [];
+    const documentsUnreadable = [];
+    for (const name of REQUIRED_CODEBASE_MAP_FILES) {
+        if (name === 'STRUCTURE.md') {
+            documents[name] = structureMd;
+            documentsRead.push(name);
+            continue;
+        }
+        try {
+            documents[name] = readDocument(node_path_1.default.join(codebaseDir, name));
+            documentsRead.push(name);
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                documentsUnreadable.push(name);
+        }
+    }
+    // loadConfig() returns a flattened object — there is no nested `workflow`
+    // key. Read the workflow-scoped keys through the quiet gate-config reader (the dot-path
+    // resolver `config-get workflow.*` shares: workstream config first, then the project
+    // root's; a missing or malformed config is "key absent", nothing is printed).
+    const configuredThreshold = (0, gate_config_cjs_1.readWorkflowConfigValue)(cwd, 'workflow.drift_threshold').value;
+    const threshold = Number.isInteger(configuredThreshold) && configuredThreshold >= 1
+        ? configuredThreshold
+        : 3;
+    const action = (0, gate_config_cjs_1.readWorkflowConfigValue)(cwd, 'workflow.drift_action').value === 'auto-remap' ? 'auto-remap' : 'warn';
+    const driftResult = drift['detectDrift']({
+        addedFiles: added,
+        modifiedFiles: modified,
+        deletedFiles: deleted,
+        documents,
+        threshold,
+        action,
+        runtime: (0, runtime_slash_cjs_1.resolveRuntime)(cwd),
+    });
+    const actionRequired = !!driftResult['actionRequired'];
+    // Paths are attacker-controlled (they come from git); the raw values stay
+    // in the library result, the CLI JSON carries display-safe renderings and
+    // a bounded withheld list with its true size alongside.
+    const display = drift['displaySafePath'];
+    const WITHHELD_LIST_CAP = 50;
+    const withheldAll = driftResult['withheldPaths'] || [];
+    const elementsRaw = driftResult['elements'] || [];
+    const isSkipped = !!driftResult['skipped'];
+    const payload = {
+        // Uniform gate contract: block = action_required.
+        block: actionRequired,
+        skipped: isSkipped,
+        reason: driftResult['reason'] || null,
+        action_required: actionRequired,
+        directive: driftResult['directive'],
+        spawn_mapper: !!driftResult['spawnMapper'],
+        affected_paths: driftResult['affectedPaths'] || [],
+        withheld_paths: withheldAll.slice(0, WITHHELD_LIST_CAP).map((p) => display(p)),
+        withheld_count: withheldAll.length,
+        documents_read: documentsRead,
+        documents_unreadable: documentsUnreadable,
+        elements: elementsRaw.map((e) => ({ category: e.category, path: display(e.path) })),
+        threshold,
+        action,
+        last_mapped_commit: lastMapped,
+        message: driftResult['message'] || '',
+    };
+    // #5170: the drift was detected over fewer documents than the map has. A BLOCKING verdict stands
+    // (more documents could only add territory the map describes); anything else was computed from
+    // evidence the gate never saw and is `unreadable` (exit UNAVAILABLE), never a clean pass or skip.
+    return actionRequired
+        ? (0, gate_verdict_cjs_1.gateVerdict)('block', true, payload)
+        : documentsUnreadable.length > 0
+            ? (0, gate_verdict_cjs_1.gateUnreadable)(false, payload)
+            : (0, gate_verdict_cjs_1.gateVerdict)(isSkipped ? 'skip' : 'pass', false, payload);
+}
+function evaluateCodebaseDriftGate(input) {
+    // Non-blocking contract: a throw anywhere yields the non-blocking payload; the exit status says
+    // "could not look" (#5170) rather than a clean exit 0.
+    try {
+        return runCodebaseDriftGate(input.projectDir);
+    }
+    catch (err) {
+        return unreadable('exception: ' + (err && err instanceof Error ? err.message : String(err)));
+    }
+}

package/gsd-core/bin/lib/gate-config.cjs

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Gate config — the one place a gate reads a `workflow.*` switch (#5139, epic #5056, ADR-5057
+ * Phase 6, design D5; fixes #4978).
+ *
+ * A gate module may not import `./io.cjs` and may not hand-parse `config.json`. It reads its switch
+ * through the shared dot-path resolver `config-get workflow.*` is defined by
+ * (`capability-activation.cts` `resolveConfigKey`): own-property traversal (a prototype-chain key
+ * is never a value), the active workstream's config first, then the project root's, and a missing,
+ * unreadable or non-object config is simply "the key is absent".
+ *
+ * The lookup is NESTED-ONLY. A top-level `context_coverage_gate` / `auto_advance` /
+ * `_auto_chain_active` is never read — `config-get workflow.<key>` does not answer it either, so a
+ * gate and `config-get` can no longer disagree about the same config file (#4978).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWorkflowConfigValue = readWorkflowConfigValue;
+exports.isDecisionCoverageGateEnabled = isDecisionCoverageGateEnabled;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityActivationMod = require("./capability-activation.cjs");
+const { resolveConfigKey } = capabilityActivationMod;
+/**
+ * The resolved raw value of a dotted config key, or `{ found: false }` when absent/unreadable.
+ * QUIET: a malformed config.json is "key absent" with nothing written to stderr (the pre-#5139
+ * gate readers printed nothing either); `config-get` keeps its one-time parse warning.
+ */
+function readWorkflowConfigValue(projectDir, dotKey) {
+    return resolveConfigKey(dotKey, { config: {}, cwd: projectDir, registry: {}, quiet: true });
+}
+/**
+ * `workflow.context_coverage_gate`: the decision-coverage gates' on/off switch.
+ * A boolean is taken as written; the strings `'true'`/`'false'` (any case) are coerced; anything
+ * else — including an absent key or an unreadable config — leaves the gate ENABLED.
+ */
+function isDecisionCoverageGateEnabled(projectDir) {
+    const resolved = readWorkflowConfigValue(projectDir, 'workflow.context_coverage_gate');
+    const value = resolved.found ? resolved.value : undefined;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const lower = value.toLowerCase();
+        if (lower === 'false' || lower === 'true')
+            return lower !== 'false';
+    }
+    return true;
+}

package/gsd-core/bin/lib/gate-context-drift.cjs

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * `check verify-context-drift` as a gate module (#5219, epic #5056, ADR-5057 §4 closing arm C): it
+ * returns a `GateResult`; the command router formats it. Imports no io module and performs no direct
+ * console/stdout/stderr write (ESLint-enforced).
+ *
+ * The `drift` capability's gate at `plan:pre` (#3348). It reports the phase's upstream artifacts
+ * (RESEARCH, PATTERNS, VALIDATION, SPEC) whose effective last-changed time is STRICTLY BEFORE the
+ * phase CONTEXT.md's own: the decisions moved after the artifact was written. Non-blocking unless
+ * `workflow.context_drift_action` is `block`.
+ *
+ * Dispatched gate, payload exit mode (see `gate-schema-drift.cts`): a blocking verdict is exit 0 and
+ * "could not look" is exit 69 (#5170).
+ *
+ * Non-blocking contract: a throw anywhere (an invalid GSD_WORKSTREAM, an unreadable file) yields a
+ * non-blocking `unreadable` verdict, never a crash.
+ *
+ * Argv after the verb: `<phase>`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeContextDrift = computeContextDrift;
+exports.evaluateContextDriftGate = evaluateContextDriftGate;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+const gate_config_cjs_1 = require("./gate-config.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+const planningWorkspace = require("./planning-workspace.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
+const verificationMod = require("./verification.cjs");
+const { planningDir } = planningWorkspace;
+const { defaultPhaseCleanCommitTimesMs } = verificationMod;
+/**
+ * Pure comparator: which of `entries` have an effective last-changed time
+ * STRICTLY BEFORE `contextEffectiveMs` (CONTEXT.md's own effective time)? Strict
+ * `<` is "stale" (matches findStaleVerificationSummary's own strict `>` convention
+ * for "newer than" elsewhere in this codebase — an artifact committed in the SAME
+ * commit/second as CONTEXT.md is in sync, not stale).
+ */
+function computeContextDrift(contextEffectiveMs, entries) {
+    return entries.filter((e) => e.effectiveMs < contextEffectiveMs).map((e) => e.file);
+}
+function buildContextDriftMessage(staleArtifacts, phaseArg) {
+    const parts = [`CONTEXT.md decisions are newer than: ${staleArtifacts.join(', ')}.`];
+    if (staleArtifacts.some((f) => f.endsWith('-RESEARCH.md'))) {
+        parts.push(`Regenerate research: /gsd:plan-phase ${phaseArg} --research.`);
+    }
+    if (staleArtifacts.some((f) => f.endsWith('-PATTERNS.md'))) {
+        parts.push('Regenerate patterns: delete the PATTERNS.md file, then re-run /gsd:plan-phase.');
+    }
+    if (staleArtifacts.some((f) => f.endsWith('-VALIDATION.md') || (f.endsWith('-SPEC.md') && !f.endsWith('-AI-SPEC.md') && !f.endsWith('-UI-SPEC.md')))) {
+        parts.push('Regenerate or manually reconcile VALIDATION.md / SPEC.md against the current decisions.');
+    }
+    parts.push('Do not hand-inject the newer decisions into a prompt as a substitute for regenerating — that carries the staleness forward.');
+    return parts.join(' ');
+}
+/** The non-blocking context-drift payload for an arm that did not compare artifacts: `skip` or `unreadable`. */
+function contextDriftPayload(build, reason, message = '') {
+    return build(false, { block: false, skipped: true, reason, stale_artifacts: [], message });
+}
+function runContextDriftGate(cwd, phaseArg) {
+    const pDir = planningDir(cwd);
+    const phasesDir = node_path_1.default.join(pDir, 'phases');
+    // `none`: a documented "nothing to compare" (no CONTEXT.md, no upstream artifact).
+    const skip = (reason, message = '') => contextDriftPayload((block, payload) => (0, gate_verdict_cjs_1.gateVerdict)('skip', block, payload), reason, message);
+    // An unresolvable phase is "could not look" (#5170): there is no phase directory to compare.
+    const unresolvable = () => contextDriftPayload(gate_verdict_cjs_1.gateUnreadable, 'phase-not-found', `Phase directory not found: ${phaseArg}`);
+    // The same policy as `verify schema-drift`: an ABSENT phases tree is `none` (the documented
+    // "nothing to compare" skip); one that exists but cannot be examined is `unreadable`.
+    const phasesRoot = (0, gate_evidence_cjs_1.statEvidence)(phasesDir);
+    if (phasesRoot.kind === 'unreadable') {
+        return contextDriftPayload(gate_verdict_cjs_1.gateUnreadable, 'phases-dir-unreadable', `Could not examine ${phasesDir} (${phasesRoot.reason})`);
+    }
+    if (phasesRoot.kind === 'none') {
+        return skip('no-phases-directory', 'No phases directory');
+    }
+    // Same phase-directory resolution rule the schema-drift gate uses (#1571, #2528):
+    // matchPhaseDirs, never a naive substring test.
+    const phaseDir = (0, gate_phase_context_cjs_1.resolvePhaseDirByToken)(phasesDir, phaseArg);
+    if (!phaseDir) {
+        return unresolvable();
+    }
+    const phaseEntries = (0, gate_evidence_cjs_1.readDirEvidence)(phaseDir);
+    if (phaseEntries.kind !== 'found') {
+        return unresolvable();
+    }
+    const phaseFiles = phaseEntries.value.slice().sort();
+    const contextFile = phaseFiles.find((f) => f.endsWith('-CONTEXT.md'));
+    if (!contextFile) {
+        return skip('no-context-md');
+    }
+    const researchFile = phaseFiles.find((f) => f.endsWith('-RESEARCH.md'));
+    const patternsFile = phaseFiles.find((f) => f.endsWith('-PATTERNS.md'));
+    const validationFile = phaseFiles.find((f) => f.endsWith('-VALIDATION.md'));
+    const specFile = phaseFiles.find((f) => f.endsWith('-SPEC.md') && !f.endsWith('-AI-SPEC.md') && !f.endsWith('-UI-SPEC.md'));
+    const upstreamFiles = [researchFile, patternsFile, validationFile, specFile].filter((f) => !!f);
+    if (upstreamFiles.length === 0) {
+        return skip('no-upstream-artifacts');
+    }
+    const allFiles = [contextFile, ...upstreamFiles];
+    const cleanCommitMs = defaultPhaseCleanCommitTimesMs(phaseDir, allFiles);
+    const effectiveTimeMs = (file) => cleanCommitMs.has(file)
+        ? cleanCommitMs.get(file)
+        : node_fs_1.default.statSync(node_path_1.default.join(phaseDir, file)).mtimeMs;
+    const contextMs = effectiveTimeMs(contextFile);
+    const driftEntries = upstreamFiles.map((f) => ({ file: f, effectiveMs: effectiveTimeMs(f) }));
+    const staleArtifacts = computeContextDrift(contextMs, driftEntries);
+    // Through the quiet gate-config reader (workstream config first, then the project root's; a
+    // missing or malformed config is "key absent", nothing is printed).
+    const action = (0, gate_config_cjs_1.readWorkflowConfigValue)(cwd, 'workflow.context_drift_action').value === 'block' ? 'block' : 'warn';
+    const block = staleArtifacts.length > 0 && action === 'block';
+    const message = staleArtifacts.length > 0 ? buildContextDriftMessage(staleArtifacts, phaseArg) : '';
+    return (0, gate_verdict_cjs_1.gateVerdict)(block ? 'block' : (staleArtifacts.length > 0 ? 'advisory' : 'pass'), block, {
+        block,
+        skipped: false,
+        stale_artifacts: staleArtifacts,
+        action,
+        message,
+    });
+}
+function evaluateContextDriftGate(input) {
+    const phaseArg = input.args[0] || '';
+    if (!phaseArg) {
+        // UNKNOWN: the pre-move `error('Usage…')` named no reason, and the reason is observable (#5219).
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.UNKNOWN, 'Usage: verify context-drift <phase>');
+    }
+    // Non-blocking contract: a throw anywhere (an invalid GSD_WORKSTREAM, an unreadable file)
+    // yields the non-blocking payload; the exit status says "could not look" (#5170) rather than
+    // a clean exit 0.
+    try {
+        return runContextDriftGate(input.projectDir, phaseArg);
+    }
+    catch (err) {
+        return contextDriftPayload(gate_verdict_cjs_1.gateUnreadable, 'exception: ' + (err instanceof Error ? err.message : String(err)));
+    }
+}

package/gsd-core/bin/lib/gate-decision-coverage-plan.cjs

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * `check decision-coverage-plan` — blocking plan-phase decision-coverage gate
+ * (#2492, #1365 fail-loud, #2770 empty-arg fail-closed), as a gate module (#5139, epic #5056,
+ * ADR-5057 §4 first bullet): it returns a `GateResult`; the command router formats it.
+ * Imports no io module and performs no direct console/stdout/stderr write (ESLint-enforced).
+ *
+ * Invocation (the context path may be supplied EITHER way; #4130 follow-up), argv after the verb:
+ *   <phase-dir> <context-path>          (positional, the workflow caller's form)
+ *   --context <path> [<phase-dir>]
+ *
+ * `--context <path>` follows the sibling flag convention (`check predicate`,
+ * #2008): `--flag value` pairs parsed by the shared partitionPredicateArgs
+ * pass, the flag WINNING over a same-purpose positional when both appear,
+ * and a valueless `--context` counting as no context at all (it falls
+ * through to the #2770 caller-error branch, not to the "CONTEXT.md missing"
+ * green skip). The positional form keeps working unchanged — no sibling
+ * check verb deprecates positionals and the plan-phase workflow passes them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateDecisionCoveragePlan = evaluateDecisionCoveragePlan;
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+const gate_args_cjs_1 = require("./gate-args.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+const gate_config_cjs_1 = require("./gate-config.cjs");
+const decision_coverage_support_cjs_1 = require("./decision-coverage-support.cjs");
+/**
+ * The verdict when CONTEXT.md or a plan could not be read. The blocking policy is unchanged
+ * (`block: true`, fail-closed like the neighbouring arms); the outcome is `unreadable`, so the exit
+ * status is UNAVAILABLE and nothing is certified from content the gate never saw (#5170).
+ */
+function unreadableDecisionGate(readError) {
+    return (0, gate_verdict_cjs_1.gateUnreadable)(true, {
+        passed: false,
+        skipped: false,
+        reason: 'unreadable evidence',
+        total: null,
+        covered: null,
+        readError,
+        message: `Decision coverage gate could not read its evidence (${readError}). Fix the file permissions or encoding, then re-run the gate.`,
+    });
+}
+/** The verdict when there is no CONTEXT.md: the legitimate green skip (authoritatively `none`, never `unreadable`). */
+function contextMissingSkip() {
+    return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { passed: true, skipped: true, reason: 'CONTEXT.md missing', total: 0, covered: 0, uncovered: [], message: 'No CONTEXT.md - nothing to check.' });
+}
+function evaluateDecisionCoveragePlan(input) {
+    const { projectDir, args } = input;
+    // Partition the argv AFTER the verb so flag tokens and their values never land in a
+    // positional slot.
+    const { flags, positionals } = (0, gate_args_cjs_1.partitionPredicateArgs)(args);
+    let phaseDir = '';
+    if (positionals[0]) {
+        const resolved = (0, gate_phase_context_cjs_1.resolveContainedPath)(positionals[0], projectDir);
+        if ((0, gate_verdict_cjs_1.isGateUsageFailure)(resolved))
+            return resolved;
+        phaseDir = resolved;
+    }
+    // A VALUELESS `--context` stays a bare token in the positionals (sibling
+    // parser semantics); it must not then be read as the context PATH — a
+    // `--`-prefixed "path" is a caller mistake, and #2770's law says a missing
+    // context argument fails CLOSED, never a silent "CONTEXT.md missing" green
+    // skip. So only a non-flag positional may serve as the context.
+    const positionalContext = positionals[1] && !positionals[1].startsWith('--') ? positionals[1] : '';
+    const contextArg = flags['context'] ?? positionalContext ?? '';
+    let contextPath = '';
+    if (contextArg) {
+        const resolved = (0, gate_phase_context_cjs_1.resolveContainedPath)(contextArg, projectDir);
+        if ((0, gate_verdict_cjs_1.isGateUsageFailure)(resolved))
+            return resolved;
+        contextPath = resolved;
+    }
+    if (!(0, gate_config_cjs_1.isDecisionCoverageGateEnabled)(projectDir)) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { passed: true, skipped: true, reason: 'workflow.context_coverage_gate is false', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate disabled by config.' });
+    }
+    // #2770: an EMPTY/MISSING contextPath argument is a CALLER ERROR (the workflow
+    // forgot to pass the path — e.g. a shell variable lost between Bash blocks), not
+    // evidence the phase has no CONTEXT.md. Fail closed (mirrors #1365 fail-loud) so a
+    // blocking gate cannot silently certify success on a caller mistake.
+    if (!contextArg || contextArg === '') {
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, { passed: false, skipped: false, reason: 'missing context path argument', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate called without a context path argument — the caller (e.g. the plan-phase workflow) must pass the CONTEXT.md path. An empty argument is a caller error, not evidence there is nothing to check (#2770).' });
+    }
+    // One stat answers both questions (#5170): `none` (ENOENT/ENOTDIR) is a REAL path whose file
+    // genuinely does not exist — the LEGITIMATE green skip. `fs.existsSync` answered `false` for an
+    // EACCES on a parent too, certifying "nothing to check" over a CONTEXT.md the gate never saw.
+    const contextStat = (0, gate_evidence_cjs_1.statEvidence)(contextPath);
+    if (contextStat.kind === 'none') {
+        return contextMissingSkip();
+    }
+    // #4794: a NON-FILE path (a directory — the adjacent same-looking positional
+    // swapped, the issue's repro 2) is a caller error like #2770's empty argument:
+    // the read yields nothing, and the gate used to certify passed:true on a phase
+    // full of decisions. Fail closed, naming it. A stat failure other than "absent"
+    // answers the SAME fail-closed JSON (outcome `unreadable`), never a throw.
+    const contextIsFile = contextStat.kind === 'found' && contextStat.value.isFile();
+    if (!contextIsFile) {
+        const contextKind = contextStat.kind === 'found'
+            ? (contextStat.value.isDirectory() ? 'directory' : 'non-file entry')
+            : 'unreadable path';
+        const notAFile = { passed: false, skipped: false, reason: 'context path is not a file', total: null, covered: null, message: `Decision coverage gate: the context path "${contextArg}" is not a readable file (${contextKind}). Swap the adjacent positionals or pass --context <path-to-CONTEXT.md>.` };
+        // Fail-closed policy is unchanged (`block: true`); a path that could not even be examined is
+        // "could not look" (#5170), so its outcome is `unreadable` and the exit status follows it.
+        return contextStat.kind === 'unreadable' ? (0, gate_verdict_cjs_1.gateUnreadable)(true, notAFile) : (0, gate_verdict_cjs_1.gateVerdict)('block', true, notAFile);
+    }
+    const extracted = (0, decision_coverage_support_cjs_1.loadDecisionExtraction)(contextPath);
+    if (extracted.kind === 'unreadable')
+        return unreadableDecisionGate(`${extracted.span ?? contextPath}: ${extracted.reason}`);
+    if (extracted.kind === 'none') {
+        return contextMissingSkip();
+    }
+    const { trackable: decisions, outcome, unreadableIds } = extracted.value;
+    // #1365 fail-loud gate: any could-not-parse outcome must NOT silently pass —
+    // even when some decisions were extracted (e.g. D-01 valid but D-02 malformed).
+    // A parse-miss on ANY bullet means the gate cannot certify full coverage.
+    // Fire independent of decisions.length so a partial-parse still blocks.
+    if (outcome === 'could-not-parse') {
+        // #4794: nothing was measured — the answer must not carry the fields of a
+        // gate that did. total/covered are null (a type change is the point:
+        // 0 reads as data, null does not), `uncovered` is OMITTED (the list was
+        // never built), and the ids that failed to parse are carried so a caller
+        // capturing stdout knows which decision to fix.
+        const partialParse = decisions.length > 0;
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, {
+            passed: false,
+            skipped: false,
+            reason: 'could-not-parse',
+            total: null,
+            covered: null,
+            unreadable: unreadableIds,
+            message: (partialParse
+                ? 'Decision coverage gate: decisions could not be fully parsed — one or more ' +
+                    '`- **D-NN ...**` bullets appear malformed (missing `:` or ` — ` separator, or a phase ' +
+                    'prefix that is not a digit run, e.g. `D4x-01`). Fix the bullet format so all decisions ' +
+                    'can be read before re-running the gate.'
+                : 'Decision coverage gate: could not parse decisions — possible format mismatch. ' +
+                    'The CONTEXT.md appears to be decision-shaped (has a <decisions> block, a decisions heading, ' +
+                    'or D- tokens) but no decision bullets could be extracted. Check the formatting of the decisions ' +
+                    'block and ensure bullets follow the `- **D-NN:** text`, `- **D4-NN:** text` (phase-prefixed), ' +
+                    'or `- **D-NN — title** body` form. An ID grammar the parser does not support (e.g. `DEC-01`) ' +
+                    'also lands here.')
+                + (unreadableIds.length > 0 ? ' Unreadable ids: ' + unreadableIds.join(', ') + '.' : ''),
+        });
+    }
+    if (decisions.length === 0) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { passed: true, skipped: true, reason: 'no trackable decisions', total: 0, covered: 0, uncovered: [], message: 'No trackable decisions in CONTEXT.md.' });
+    }
+    const planContents = (0, decision_coverage_support_cjs_1.loadPlanContents)(phaseDir);
+    if (planContents.kind === 'unreadable')
+        return unreadableDecisionGate(`${planContents.span ?? phaseDir}: ${planContents.reason}`);
+    const sections = planContents.value.map(decision_coverage_support_cjs_1.extractPlanDesignatedSections);
+    const uncovered = [];
+    let covered = 0;
+    for (const decision of decisions) {
+        if (sections.some((section) => (0, decision_coverage_support_cjs_1.decisionMentioned)(section, decision)))
+            covered++;
+        else
+            uncovered.push({ id: decision.id, text: decision.text, category: decision.category });
+    }
+    const passed = uncovered.length === 0;
+    return (0, gate_verdict_cjs_1.gateVerdict)(passed ? 'pass' : 'block', !passed, {
+        passed,
+        skipped: false,
+        total: decisions.length,
+        covered,
+        uncovered,
+        message: (0, decision_coverage_support_cjs_1.buildPlanMessage)(uncovered),
+    });
+}