@opengsd/gsd-core 1.14.0 → 1.16.0

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

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evidenceFound = evidenceFound;
+exports.evidenceNone = evidenceNone;
+exports.evidenceUnreadable = evidenceUnreadable;
+exports.evidenceFromError = evidenceFromError;
+exports.readTextEvidence = readTextEvidence;
+exports.readDirEvidence = readDirEvidence;
+exports.readDirEntriesEvidence = readDirEntriesEvidence;
+exports.statEvidence = statEvidence;
+exports.readPlanScanEvidence = readPlanScanEvidence;
+exports.readPlanSetEvidence = readPlanSetEvidence;
+exports.verdictFromEvidence = verdictFromEvidence;
+/**
+ * Gate evidence — what a gate found when it looked (#5170, epic #5056, ADR-5057 §4 third bullet).
+ *
+ * A gate that reads a file or directory has THREE answers, not two:
+ *
+ *   - `found`       the evidence is there; `value` is what was read (an empty file is `found ''`).
+ *   - `none`        the evidence authoritatively does not exist (`ENOENT`, or `ENOTDIR` because a
+ *                   parent component is not a directory, so the path cannot exist). Each gate keeps
+ *                   its own documented policy for `none`.
+ *   - `unreadable`  the evidence may exist but could not be read (`EISDIR`, `EACCES`, `EIO`, an
+ *                   encoding failure ...). `reason` carries the errno code (or the message when
+ *                   the failure had none); `span` names what was being read.
+ *
+ * `unreadable` is never `''`, `false` or an empty list: a tolerant reader that collapses it into
+ * "nothing there" lets a gate pass over content it never saw. `verdictFromEvidence` is the one way
+ * a gate maps evidence to a verdict, and its `unreadable` arm is typed to return an
+ * `UnreadableVerdict`, so a passing verdict from that arm does not type-check.
+ *
+ * `fs` is reached as a namespace object at call time, never destructured at load, so a test can
+ * inject a read failure by replacing the method.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planScanMod = require("./plan-scan.cjs");
+const { scanPhasePlans } = planScanMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+function evidenceFound(value) {
+    return { kind: 'found', value };
+}
+function evidenceNone() {
+    return { kind: 'none' };
+}
+function evidenceUnreadable(reason, span) {
+    return span === undefined ? { kind: 'unreadable', reason } : { kind: 'unreadable', reason, span };
+}
+/** Errno codes meaning "the path cannot hold evidence": absent, or a parent is not a directory. */
+const ABSENT_CODES = new Set(['ENOENT', 'ENOTDIR']);
+/**
+ * Classify a thrown read failure as evidence: absent (`ENOENT`/`ENOTDIR`) is `none`, anything else
+ * is `unreadable` carrying the errno code (or the message when there was none). A gate that wraps a
+ * lookup it does not own (a locator, a roadmap reader) in `try` uses this instead of a bare `catch`.
+ */
+function evidenceFromError(err, span) {
+    return classifyFailure(err, span);
+}
+function classifyFailure(err, span) {
+    const code = err?.code;
+    if (typeof code === 'string' && ABSENT_CODES.has(code))
+        return evidenceNone();
+    if (typeof code === 'string' && code.length > 0)
+        return evidenceUnreadable(code, span);
+    const message = err instanceof Error ? err.message : String(err);
+    return evidenceUnreadable(message.length > 0 ? message : 'unknown read failure', span);
+}
+/** Read a UTF-8 file as evidence. Never throws. */
+function readTextEvidence(filePath) {
+    try {
+        return evidenceFound(node_fs_1.default.readFileSync(filePath, 'utf8'));
+    }
+    catch (err) {
+        return classifyFailure(err, filePath);
+    }
+}
+/** Read a directory's entry names as evidence. Never throws. */
+function readDirEvidence(dirPath) {
+    try {
+        return evidenceFound(node_fs_1.default.readdirSync(dirPath));
+    }
+    catch (err) {
+        return classifyFailure(err, dirPath);
+    }
+}
+/** Read a directory's entries (with types) as evidence. Never throws. */
+function readDirEntriesEvidence(dirPath) {
+    try {
+        return evidenceFound(node_fs_1.default.readdirSync(dirPath, { withFileTypes: true }));
+    }
+    catch (err) {
+        return classifyFailure(err, dirPath);
+    }
+}
+/** Stat a path (following symlinks) as evidence. Never throws. */
+function statEvidence(targetPath) {
+    try {
+        return evidenceFound(node_fs_1.default.statSync(targetPath));
+    }
+    catch (err) {
+        return classifyFailure(err, targetPath);
+    }
+}
+/**
+ * The canonical plan set of a phase directory that is known to exist, as evidence (#5170). Only the
+ * scan's `SCOPE.COMPLETE` is a real answer: `TRUNCATED` (an existing nested `plans/` that could not be
+ * read), `UNREADABLE` and `UNSCOPED` mean the scan did not see every plan, so a short or empty list is
+ * `unreadable` and never "no plans". Every gate that gets its plans from `scanPhasePlans` goes through
+ * this one reader.
+ */
+function readPlanScanEvidence(phaseDir) {
+    const scan = scanPhasePlans(phaseDir);
+    if (scan.scope !== SCOPE.COMPLETE) {
+        return { kind: 'unreadable', reason: `plan scan ${scan.scope}`, span: phaseDir };
+    }
+    return evidenceFound({ planFiles: [...scan.planFiles], summaryFiles: [...scan.summaryFiles] });
+}
+/** The plan half of {@link readPlanScanEvidence}. */
+function readPlanSetEvidence(phaseDir) {
+    const scan = readPlanScanEvidence(phaseDir);
+    return scan.kind === 'unreadable' ? scan : evidenceFound(scan.value.planFiles);
+}
+/** Map evidence to a verdict. Total over the three kinds. */
+function verdictFromEvidence(evidence, arms) {
+    switch (evidence.kind) {
+        case 'found':
+            return arms.found(evidence.value);
+        case 'none':
+            return arms.none();
+        case 'unreadable':
+            return arms.unreadable(evidence.reason, evidence.span);
+    }
+}

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

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gateExitOutcome = gateExitOutcome;
+exports.declareGateExit = declareGateExit;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExit = require("./cli-exit.cjs");
+function gateExitOutcome(verdict, mode) {
+    switch (verdict.outcome) {
+        case 'unreadable':
+            return 'UNAVAILABLE';
+        case 'block':
+            return mode === 'status' ? 'FAIL' : 'PASS';
+        case 'empty':
+            return mode === 'status' ? 'NO_INPUT' : 'PASS';
+        case 'pass':
+        case 'skip':
+        case 'advisory':
+            return 'PASS';
+    }
+}
+/** Declare the exit outcome for a verdict. Call after `output()`, never before. */
+function declareGateExit(verdict, mode) {
+    const outcome = gateExitOutcome(verdict, mode);
+    if (outcome !== 'PASS')
+        cliExit.declareOutcome(outcome);
+    return outcome;
+}

package/gsd-core/bin/lib/gate-gap-analysis-plan-post.cjs

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * `check gap-analysis-plan-post` 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).
+ *
+ * Non-blocking advisory check that runs the post-planning gap analysis after all PLAN.md files are
+ * generated for a phase. Cross-references every REQ-ID and D-ID from REQUIREMENTS.md and CONTEXT.md
+ * against the concatenated text of all *-PLAN.md files, emitting a coverage table.
+ *
+ * This gate is always advisory (`passed: true`, `block: false`) — it never blocks phase advancement.
+ *
+ * Argv after the verb: `<phase-dir> [phase-req-ids]`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateGapAnalysisPlanPost = evaluateGapAnalysisPlanPost;
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const gapCheckerModule = require("./gap-checker.cjs");
+const { runGapAnalysis } = gapCheckerModule;
+function evaluateGapAnalysisPlanPost(input) {
+    const { projectDir, args } = input;
+    const phaseDir = args[0] || '';
+    if (!phaseDir) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.SDK_MISSING_ARG, 'gap-analysis.plan-post requires a phase-dir argument: check gap-analysis.plan-post <phase-dir> [phase-req-ids]');
+    }
+    const resolvedPhaseDir = (0, gate_phase_context_cjs_1.resolveContainedPath)(phaseDir, projectDir);
+    if ((0, gate_verdict_cjs_1.isGateUsageFailure)(resolvedPhaseDir))
+        return resolvedPhaseDir;
+    const phaseReqIds = args[1] ?? undefined;
+    const result = runGapAnalysis(projectDir, resolvedPhaseDir, { phaseReqIds });
+    // Uniform gate contract: block = false (gap-analysis is always advisory, never blocks).
+    // `message` carries the human-readable gap analysis report so the dispatch's advisory branch can
+    // surface it.
+    // #5170 (ADR-5057 §4): a REQUIREMENTS.md, CONTEXT.md, plan, config or phase directory that exists but
+    // could not be read means the table was computed over evidence the analysis never saw. The gate
+    // stays advisory (`block: false`) but the outcome is `unreadable`: exit UNAVAILABLE, never a clean pass.
+    if (result.unreadable !== undefined && result.unreadable.length > 0) {
+        const named = result.unreadable.map((u) => `${u.span} (${u.reason})`).join('; ');
+        return (0, gate_verdict_cjs_1.gateUnreadable)(false, {
+            block: false,
+            passed: false,
+            enabled: result.enabled,
+            table: result.table,
+            summary: result.summary,
+            counts: result.counts,
+            unreadable: result.unreadable,
+            message: `${result.table || result.summary || ''}\nPost-planning gap analysis could not read its evidence: ${named}.`,
+        });
+    }
+    return (0, gate_verdict_cjs_1.gateVerdict)('advisory', false, {
+        block: false,
+        passed: true,
+        enabled: result.enabled,
+        table: result.table,
+        summary: result.summary,
+        counts: result.counts,
+        message: result.table || result.summary || '',
+    });
+}

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

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Gate phase context — path/phase resolution shared by the gate modules (#5139, epic #5056,
+ * ADR-5057 §4 first bullet, design D3).
+ *
+ * Owns the containment helper (a caller-supplied path argument is resolved against the project
+ * directory and must stay inside it; it RETURNS a `GateUsageFailure` on an escape — a gate module
+ * never calls `error()` — and the router turns that failure into the same `error(message,
+ * 'usage')` the pre-move router raised), the phase-directory / ROADMAP lookups and the degraded
+ * verdict of the two verify probes.
+ *
+ * Every lookup answers with typed evidence (#5170, ADR-5057 §4): an absent thing is `none`, a thing
+ * that exists but could not be read is `unreadable`, and nothing here collapses either into `''`.
+ * The tolerant `readIfExists` reader is deleted; a gate reads through `gate-evidence.cts`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveContainedPath = resolveContainedPath;
+exports.unresolvableProbeVerdict = unresolvableProbeVerdict;
+exports.resolvePhaseDir = resolvePhaseDir;
+exports.resolvePhaseDirByToken = resolvePhaseDirByToken;
+exports.findUiSpecInDir = findUiSpecInDir;
+exports.locateUiSpec = locateUiSpec;
+exports.lookupRoadmapPhase = lookupRoadmapPhase;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const security_cjs_1 = require("./security.cjs");
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspaceMod = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspaceMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocatorMod = require("./phase-locator.cjs");
+const { findPhaseInternal } = phaseLocatorMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { normalizePhaseName, matchPhaseDirs } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapModule = require("./roadmap.cjs");
+const { getRoadmapPhaseWithFallback } = roadmapModule;
+/**
+ * Resolve a caller-supplied path (absolute, or relative to `projectDir`) and require the result to
+ * stay inside `projectDir` (realpath containment, ADR-4650). Returns the contained path the
+ * predicate produced, or a `GateUsageFailure` (`usage`, `path escapes its allowed directory: <arg>`).
+ */
+function resolveContainedPath(inputPath, projectDir) {
+    const candidate = node_path_1.default.isAbsolute(inputPath) ? inputPath : node_path_1.default.join(projectDir, inputPath);
+    const contained = (0, security_cjs_1.tryWithinRoot)(candidate, projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+    if (contained === null) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.USAGE, `path escapes its allowed directory: ${inputPath}`);
+    }
+    return contained;
+}
+/**
+ * The verdict of the two verify probes (`verify-command-paths`, `verify-failure-directions`) when
+ * they cannot look: status/commands/counts zeroed, `readError` naming why. The payload is what the
+ * plan-checker parses and must tell "nothing to report" from "could not look" by; the OUTCOME is
+ * `unreadable` (#5170), so the exit status is `UNAVAILABLE` — "could not look" is never a pass and
+ * never exit 0. `block` stays false (the probe's documented policy is unchanged).
+ */
+function unresolvableProbeVerdict(readError) {
+    return (0, gate_verdict_cjs_1.gateUnreadable)(false, {
+        status: 'unresolvable',
+        commands: [],
+        counts: { blocker: 0, warning: 0, total: 0 },
+        readError,
+    });
+}
+/**
+ * Resolve a phase argument to an absolute phase directory. The ONE owner of what three gates
+ * (`ui-plan-gate`, `ui-safety-gate`, `tdd-review-checkpoint`) and the two verify probes each
+ * inlined before #5139. `found` is the absolute directory; `none` is "no such phase"; `unreadable`
+ * is a locator that failed while looking (a gate must not read that as "no phase").
+ */
+function resolvePhaseDir(projectDir, phase) {
+    let result;
+    try {
+        result = findPhaseInternal(projectDir, phase);
+    }
+    catch (err) {
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, `phase ${phase}`);
+    }
+    if (result && typeof result === 'object') {
+        // findPhaseInternal returns { directory: '<relative-posix-path>', ... }
+        // directory is relative to cwd — resolve it to absolute.
+        const relDir = typeof result['directory'] === 'string' ? result['directory'] : '';
+        if (relDir)
+            return (0, gate_evidence_cjs_1.evidenceFound)(node_path_1.default.resolve(projectDir, relDir));
+    }
+    else if (typeof result === 'string' && result !== '') {
+        return (0, gate_evidence_cjs_1.evidenceFound)(result);
+    }
+    return (0, gate_evidence_cjs_1.evidenceNone)();
+}
+/**
+ * Resolve a phase argument to its directory DIRECTLY under a given `phasesDir`, for the two drift
+ * gates (schema-drift, context-drift; #1571, #2528, #5219).
+ *
+ * It is NOT `resolvePhaseDir`: that one asks the phase locator (`findPhaseInternal`), which looks
+ * through the current milestone's phases AND the milestone archives and reads the active workstream.
+ * The drift gates are handed ONE phases directory and must look nowhere else, and they resolve
+ * through the canonical phase-directory matcher (`matchPhaseDirs`, never a naive substring test: a
+ * bare `.includes(phaseArg)` lets a non-existent phase match a different phase whose directory merely
+ * contains the token, e.g. "1" matching "11-expansion"), then fall back to an exact directory name
+ * contained in `phasesDir` (a name escaping it resolves to nothing). Folding it into
+ * `resolvePhaseDir` would widen what those gates inspect, so the two stay apart and each states its
+ * scope. Throws when `phasesDir` cannot be listed; both callers sit inside their non-blocking catch.
+ */
+function resolvePhaseDirByToken(phasesDir, phaseArg) {
+    const normalizedPhase = normalizePhaseName(phaseArg);
+    const dirEntries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
+    const dirNames = dirEntries.filter((e) => e.isDirectory()).map((e) => e.name);
+    const matched = matchPhaseDirs(dirNames, normalizedPhase).matches[0];
+    if (matched)
+        return node_path_1.default.join(phasesDir, matched);
+    const contained = (0, security_cjs_1.tryWithinRoot)(phaseArg, phasesDir);
+    if (contained !== null && (0, gate_evidence_cjs_1.statEvidence)(contained).kind === 'found')
+        return contained;
+    return null;
+}
+/** The `*-UI-SPEC.md` inside `phaseDir` (absolute path): `none` when the directory or the spec is absent. */
+function findUiSpecInDir(phaseDir) {
+    const entries = (0, gate_evidence_cjs_1.readDirEvidence)(phaseDir);
+    if (entries.kind !== 'found')
+        return entries;
+    const found = entries.value.find((f) => /-UI-SPEC\.md$/.test(f));
+    return found ? (0, gate_evidence_cjs_1.evidenceFound)(node_path_1.default.join(phaseDir, found)) : (0, gate_evidence_cjs_1.evidenceNone)();
+}
+/**
+ * The phase's `*-UI-SPEC.md`: `found` (absolute path), `none` (no phase directory, or no spec in
+ * it), or `unreadable` (the phase lookup or the directory read failed — the spec may exist).
+ */
+function locateUiSpec(projectDir, phase) {
+    const phaseDir = resolvePhaseDir(projectDir, phase);
+    if (phaseDir.kind !== 'found')
+        return phaseDir;
+    return findUiSpecInDir(phaseDir.value);
+}
+/**
+ * The ROADMAP phase section for `phase`, through the same two-pass lookup as `roadmap.get-phase`
+ * (current milestone, then the full roadmap). A missing ROADMAP.md means "no roadmap, cannot be
+ * frontend" (`phaseLookupFailed` stays false); a present ROADMAP.md without the phase sets it. A
+ * lookup that FAILED (the reader threw, or ROADMAP.md exists but cannot be read) carries `readError`
+ * — "could not look" — instead of reading as an empty, non-frontend roadmap. Shared by
+ * `ui-plan-gate` and `ui-safety-gate`.
+ */
+function lookupRoadmapPhase(projectDir, phase) {
+    let section;
+    try {
+        section = getRoadmapPhaseWithFallback(projectDir, phase);
+    }
+    catch (err) {
+        const failure = (0, gate_evidence_cjs_1.evidenceFromError)(err, 'ROADMAP.md');
+        if (failure.kind === 'unreadable') {
+            return { phaseSection: '', phaseLookupFailed: false, readError: failure.reason };
+        }
+        return { phaseSection: '', phaseLookupFailed: false };
+    }
+    if (section !== null)
+        return { phaseSection: section, phaseLookupFailed: false };
+    // Distinguish: ROADMAP.md missing (no-roadmap project) vs phase not found in ROADMAP.
+    const roadmap = (0, gate_evidence_cjs_1.readTextEvidence)(node_path_1.default.join(planningDir(projectDir), 'ROADMAP.md'));
+    if (roadmap.kind === 'unreadable') {
+        return { phaseSection: '', phaseLookupFailed: false, readError: roadmap.reason };
+    }
+    return { phaseSection: '', phaseLookupFailed: roadmap.kind === 'found' };
+}

package/gsd-core/bin/lib/gate-predicate-evaluator.cjs

@@ -11,7 +11,7 @@
  * was declaration-only. This module is the generic evaluation path.
  *
  * The workflow gate-dispatch calls this evaluator (via the `gsd_run check predicate`
- * subcommand in check-command-router) for any gate whose `check` carries a
+ * subcommand, implemented by gate-predicate.cts) for any gate whose `check` carries a
  * `predicate` instead of a `query`. The evaluator dispatches by `predicate.kind`
  * and returns the existing `{ block, message }` gate contract. A THROWN error
  * (malformed predicate / unknown kind) is mapped by the CLI wrapper to a

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

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * `check predicate` as a gate module (#5139, epic #5056, ADR-5057 §4 first bullet): generic
+ * evaluator for capability gate `check.predicate` blocks (#2008). It returns a `GateResult`; the
+ * command router formats it. Imports no io module and performs no direct console/stdout/stderr
+ * write (ESLint-enforced).
+ *
+ * The workflow gate-dispatch invokes this for any gate whose `check` carries a `predicate` (instead
+ * of a `query`); the predicate object is passed as `--predicate '<json>'`. The standard `{ block,
+ * message, details? }` gate contract is the payload. A malformed predicate / unknown kind THROWS
+ * inside the evaluator and is mapped here to a `usage` failure (non-zero exit at the router), which
+ * the workflow's two-step gate contract treats as a step-1 command failure routed per the gate's
+ * `onError`.
+ *
+ * Invocation (argv after the verb):
+ *   --predicate '<json>' [--phase-dir <dir>] [--phase-number <n>] [--phase-req-ids <ids>]
+ *
+ * The subprocess runs at the runtime project root (`projectDir`), inheriting the process env.
+ * Interpolation placeholders ${PHASE_NUMBER}/${PHASE_DIR}/${PHASE_REQ_IDS} are substituted from the
+ * flags.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPredicateDeps = buildPredicateDeps;
+exports.evaluateCheckPredicate = evaluateCheckPredicate;
+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_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+const gate_args_cjs_1 = require("./gate-args.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatterMod;
+const security_cjs_1 = require("./security.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const gatePredicateEval = require("./gate-predicate-evaluator.cjs");
+const { evaluatePredicate } = gatePredicateEval;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+/**
+ * Production subprocess binding for the gate-predicate evaluator. Wraps the
+ * bounded `execTool` seam (shell-command-projection) as a `runBoundedShell`
+ * the pure evaluator consumes. `sh -c` runs the interpolated command; the
+ * subprocess inherits the process env and is killed (SIGTERM) on timeout.
+ *
+ * `timedOut` is derived from the kill signal: spawnSync sets `signal: 'SIGTERM'`
+ * when the `timeout` fires, distinct from a normal non-zero exit code. A command
+ * that self-terminates with SIGTERM is indistinguishable at this seam and is
+ * reported as a timeout — either way the gate blocks (non-zero), so the outcome
+ * is fail-closed and correct. See ADR-2008.
+ */
+function buildPredicateDeps() {
+    return {
+        runBoundedShell(opts) {
+            const r = (0, shell_command_projection_cjs_1.execTool)('sh', ['-c', opts.command], { cwd: opts.cwd, timeout: opts.timeoutMs });
+            return {
+                exitCode: r.exitCode,
+                stdout: r.stdout,
+                stderr: r.stderr,
+                signal: r.signal,
+                timedOut: r.timedOut,
+            };
+        },
+        findPhaseArtifact(phaseDir, artifactSuffix) {
+            // #5170 (ADR-5057 §4): an ABSENT directory or artifact is `none` (the artifact is not there);
+            // one that exists but cannot be examined is `unreadable` and THROWS — `evaluateCheckPredicate`
+            // maps a throw to the usage failure the dispatch contract routes by `onError`. It is never
+            // folded into "artifact not found", which a predicate may read as a clean answer.
+            const unreadable = (target, reason) => {
+                throw new Error(`predicate artifact could not be examined: ${target} (${reason})`);
+            };
+            const regularFileOrNull = (candidate) => {
+                const st = (0, gate_evidence_cjs_1.statEvidence)(candidate);
+                if (st.kind === 'unreadable')
+                    return unreadable(candidate, st.reason);
+                return st.kind === 'found' && st.value.isFile() ? candidate : null;
+            };
+            const phaseDirStat = (0, gate_evidence_cjs_1.statEvidence)(phaseDir);
+            if (phaseDirStat.kind === 'unreadable')
+                return unreadable(phaseDir, phaseDirStat.reason);
+            if (phaseDirStat.kind === 'none')
+                return null;
+            if (artifactSuffix === '.' ||
+                artifactSuffix === '..' ||
+                artifactSuffix.includes('\0') ||
+                node_path_1.default.basename(artifactSuffix) !== artifactSuffix ||
+                node_path_1.default.win32.basename(artifactSuffix) !== artifactSuffix) {
+                return null;
+            }
+            const directContained = (0, security_cjs_1.tryWithinRoot)(artifactSuffix, phaseDir);
+            if (directContained !== null) {
+                const direct = regularFileOrNull(directContained);
+                if (direct !== null)
+                    return direct;
+            }
+            const planningContained = (0, security_cjs_1.tryWithinRoot)(node_path_1.default.join('.planning', artifactSuffix), phaseDir);
+            if (planningContained !== null) {
+                const planning = regularFileOrNull(planningContained);
+                if (planning !== null)
+                    return planning;
+            }
+            const listing = (0, gate_evidence_cjs_1.readDirEvidence)(phaseDir);
+            if (listing.kind === 'unreadable')
+                return unreadable(phaseDir, listing.reason);
+            if (listing.kind === 'none')
+                return null;
+            for (const f of listing.value) {
+                if (f.endsWith('-' + artifactSuffix) || f === artifactSuffix) {
+                    const candidateContained = (0, security_cjs_1.tryWithinRoot)(f, phaseDir);
+                    if (candidateContained === null)
+                        continue;
+                    const candidate = regularFileOrNull(candidateContained);
+                    if (candidate !== null)
+                        return candidate;
+                }
+            }
+            return null;
+        },
+        readFrontmatter(filePath) {
+            const content = (0, shell_command_projection_cjs_1.platformReadSync)(filePath);
+            if (content === null)
+                throw new Error(`predicate artifact disappeared before it could be read: ${filePath}`);
+            const parsed = extractFrontmatter(content, filePath);
+            return parsed;
+        },
+    };
+}
+function evaluateCheckPredicate(input) {
+    const { projectDir } = input;
+    const flags = (0, gate_args_cjs_1.parsePredicateFlags)(input.args);
+    const predicateJson = flags['predicate'];
+    if (!predicateJson) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.SDK_MISSING_ARG, 'predicate requires --predicate <json> (the gate hook check.predicate object)');
+    }
+    let predicate;
+    try {
+        predicate = JSON.parse(predicateJson);
+    }
+    catch {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.USAGE, 'predicate --predicate value must be valid JSON');
+    }
+    const rawPhaseDir = flags['phase-dir'];
+    let resolvedPhaseDir = rawPhaseDir;
+    if (typeof rawPhaseDir === 'string' && rawPhaseDir !== '') {
+        const resolved = (0, gate_phase_context_cjs_1.resolveContainedPath)(rawPhaseDir, projectDir);
+        if ((0, gate_verdict_cjs_1.isGateUsageFailure)(resolved))
+            return resolved;
+        resolvedPhaseDir = resolved;
+    }
+    const ctx = {
+        cwd: projectDir,
+        phaseNumber: flags['phase-number'],
+        phaseDir: resolvedPhaseDir,
+        phaseReqIds: flags['phase-req-ids'],
+    };
+    let result;
+    try {
+        result = evaluatePredicate(predicate, ctx, buildPredicateDeps());
+    }
+    catch (e) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.USAGE, `gate predicate evaluation failed: ${e.message}`);
+    }
+    return (0, gate_verdict_cjs_1.gateVerdict)(result.block ? 'block' : 'pass', result.block === true, { ...result });
+}

package/gsd-core/bin/lib/gate-prohibition-enforcement.cjs

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * `check prohibition-enforcement` 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 deterministic test-tier prohibition PRODUCER (#1259, ADR-550 D5d): it locates the wired
+ * mechanical check (node-test or lint-rule), proves it fails first, runs it, builds
+ * `enforcementEvidence` and delivers the `dispositionForProhibition` result
+ * (`runProhibitionEnforcement`, `prohibition-enforcement.cjs`). A producer, not a blocking gate: its
+ * disposition is a delivered answer (an `advisory` verdict, never `block`), and the exit status
+ * follows it through the seam like every other `check <verb>` (#5170, payload mode).
+ *
+ * No-throw contract: a throw anywhere is a non-blocking `unreadable` verdict whose payload is the
+ * producer's fail-closed disposition (flagged, `unverified`, nothing located), never a crash and
+ * never a silent green.
+ *
+ * Argv after the verb: `<request.json>` or `--json '<inline request>'`. A request is
+ * `{ prohibition, check, mode? }`; one that is absent or does not parse is a usage failure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateProhibitionEnforcementGate = evaluateProhibitionEnforcementGate;
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+const prohibition_enforcement_cjs_1 = require("./prohibition-enforcement.cjs");
+/** Parse the request document. A document that does not parse is typed evidence, never a swallowed `null`. */
+function parseDocumentEvidence(text) {
+    try {
+        return (0, gate_evidence_cjs_1.evidenceFound)(JSON.parse(text));
+    }
+    catch (err) {
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, 'request');
+    }
+}
+/**
+ * Parse a `{ prohibition, check, mode }` request from a JSON file path or inline `--json` string.
+ * Returns null when the request is absent, unreadable or does not parse (the caller surfaces a usage
+ * failure, never a throw).
+ */
+function parseRequest(args) {
+    const jsonFlagIdx = args.indexOf('--json');
+    const inline = args[jsonFlagIdx + 1];
+    let payload;
+    if (jsonFlagIdx !== -1 && typeof inline === 'string') {
+        payload = inline;
+    }
+    else if (typeof args[0] === 'string' && args[0]) {
+        const read = (0, gate_evidence_cjs_1.readTextEvidence)(args[0]);
+        if (read.kind !== 'found')
+            return null;
+        payload = read.value;
+    }
+    else {
+        return null;
+    }
+    const document = parseDocumentEvidence(payload);
+    // A JSON `null` has no `check` / `prohibition` to read: it is no request, as an unparsable one is.
+    if (document.kind !== 'found' || document.value === null)
+        return null;
+    const parsed = document.value;
+    const checkRaw = parsed['check'];
+    const check = (checkRaw && typeof checkRaw === 'object')
+        ? checkRaw
+        : null;
+    const modeRaw = parsed['mode'];
+    const mode = typeof modeRaw === 'string' ? modeRaw : undefined;
+    return { prohibition: parsed['prohibition'] ?? null, check, ...(mode ? { mode } : {}) };
+}
+function evaluateProhibitionEnforcementGate(input) {
+    const req = parseRequest(input.args);
+    if (!req) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.SDK_MISSING_ARG, 'prohibition-enforcement requires a JSON request: check prohibition-enforcement <request.json> | --json \'{"prohibition":{...},"check":{...}}\'');
+    }
+    try {
+        const result = (0, prohibition_enforcement_cjs_1.runProhibitionEnforcement)(req.prohibition, req.check, req.mode ? { mode: req.mode } : {});
+        return (0, gate_verdict_cjs_1.gateVerdict)('advisory', false, { ...result });
+    }
+    catch (err) {
+        // The producer's own fail-closed shape (`EnforcementResult`: a `ProhibitionDisposition` plus the
+        // located / kind / evidence provenance): typed, so a change to that shape fails the build here
+        // instead of drifting silently.
+        const failedClosed = {
+            status: 'unverified',
+            flagged: true,
+            tier: null,
+            reason: 'exception: ' + (err instanceof Error ? err.message : String(err)),
+            located: false,
+            kind: null,
+            evidence: [],
+            ...(req.mode ? { mode: req.mode } : {}),
+        };
+        return (0, gate_verdict_cjs_1.gateUnreadable)(false, { ...failedClosed });
+    }
+}