@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/gap-checker.cjs

@@ -19,21 +19,18 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
 const { output, error, formatDiagnosticToken } = io;
 const pattern_cjs_1 = require("./pattern.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningPaths, planningDir, findContextMdIn } = planningWorkspace;
 const decisions_cjs_1 = require("./decisions.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 // 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 phaseIdMod = require("./phase-id.cjs");
 const { scopeToPhase } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -143,21 +140,42 @@ function formatGapTable(rows) {
     }).join('\n');
     return `## Post-Planning Gap Analysis\n\n${header}\n${body}\n`;
 }
+function parseJsonEvidence(text, span) {
+    try {
+        return (0, gate_evidence_cjs_1.evidenceFound)(JSON.parse(text));
+    }
+    catch (err) {
+        return (0, gate_evidence_cjs_1.evidenceFromError)(err, span);
+    }
+}
+/**
+ * Is the gap analysis enabled? An ABSENT config means the default (enabled). A config that exists
+ * but cannot be read or parsed also runs the analysis (the conservative direction: the check is not
+ * silently switched off), and is reported in `unreadable` so the verdict is never a clean pass
+ * (#5170, ADR-5057 §4).
+ */
 function readGate(cwd) {
     const cfgPath = node_path_1.default.join(planningDir(cwd), 'config.json');
-    try {
-        const raw = JSON.parse(node_fs_1.default.readFileSync(cfgPath, 'utf-8'));
+    const text = (0, gate_evidence_cjs_1.readTextEvidence)(cfgPath);
+    if (text.kind === 'none')
+        return { enabled: true, unreadable: [] };
+    if (text.kind === 'unreadable')
+        return { enabled: true, unreadable: [{ reason: text.reason, span: cfgPath }] };
+    const parsed = parseJsonEvidence(text.value, cfgPath);
+    if (parsed.kind === 'unreadable')
+        return { enabled: true, unreadable: [{ reason: parsed.reason, span: cfgPath }] };
+    if (parsed.kind === 'found') {
+        const raw = parsed.value;
         if (raw && typeof raw === 'object' && 'workflow' in raw) {
             const wf = raw['workflow'];
             if (wf && typeof wf === 'object' && 'post_planning_gaps' in wf) {
                 const val = wf['post_planning_gaps'];
                 if (typeof val === 'boolean')
-                    return val;
+                    return { enabled: val, unreadable: [] };
             }
         }
     }
-    catch { /* fall through */ }
-    return true;
+    return { enabled: true, unreadable: [] };
 }
 /**
  * Same-prefix ascending numeric range, e.g. `SEL-01..SEL-03`. Both sides must
@@ -298,7 +316,10 @@ function normalizePhaseReqIds(rawVal) {
 }
 function runGapAnalysis(cwd, phaseDir, options = {}) {
     const phaseReqIds = normalizePhaseReqIds(options.phaseReqIds);
-    if (!readGate(cwd)) {
+    const gate = readGate(cwd);
+    const unreadable = [...gate.unreadable];
+    const unreadableField = () => (unreadable.length > 0 ? { unreadable } : {});
+    if (!gate.enabled) {
         return {
             enabled: false,
             rows: [],
@@ -311,7 +332,12 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     }
     const absPhaseDir = node_path_1.default.isAbsolute(phaseDir) ? phaseDir : node_path_1.default.join(cwd, phaseDir);
     const reqPath = planningPaths(cwd).requirements;
-    const reqMd = node_fs_1.default.existsSync(reqPath) ? node_fs_1.default.readFileSync(reqPath, 'utf-8') : '';
+    // An absent REQUIREMENTS.md has no requirements; one that exists but cannot be read is `unreadable`
+    // (a thrown read used to crash, and `existsSync` said "absent" for an EACCES on a parent).
+    const reqRead = (0, gate_evidence_cjs_1.readTextEvidence)(reqPath);
+    if (reqRead.kind === 'unreadable')
+        unreadable.push({ reason: reqRead.reason, span: reqPath });
+    const reqMd = reqRead.kind === 'found' ? reqRead.value : '';
     let reqItems = parseRequirements(reqMd).map(r => ({ ...r, source: 'REQUIREMENTS.md' }));
     // Scope the requirements comparison to the phase's mapped REQ-IDs (#447).
     // A phase that maps no requirements (phase_req_ids null/TBD) must not report
@@ -325,7 +351,9 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
         const wanted = new Set(phaseReqIds);
         const foundIds = new Set(reqItems.map(r => r.id));
         reqItems = reqItems.filter(r => wanted.has(r.id));
-        ghostReqIds = phaseReqIds.filter(id => !foundIds.has(id));
+        // An unreadable REQUIREMENTS.md registers nothing, so "missing from REQUIREMENTS.md" would be a
+        // false claim about every ID; the unreadable read is reported instead.
+        ghostReqIds = reqRead.kind === 'unreadable' ? [] : phaseReqIds.filter(id => !foundIds.has(id));
     }
     // Read the phase directory once; reuse the listing for both context detection
     // and plan-file enumeration (avoids redundant readdirSync calls).
@@ -343,6 +371,8 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     const phaseDirReadError = phaseDirScope === SCOPE.UNREADABLE
         ? `Could not read phase directory ${formatDiagnosticToken(absPhaseDir)}`
         : null;
+    if (phaseDirScope === SCOPE.UNREADABLE)
+        unreadable.push({ reason: 'the directory could not be listed', span: absPhaseDir });
     // #3511-class: scope the raw listing to this phase dir before the
     // phase-numbered -CONTEXT.md predicate. `phaseDirFiles` itself stays raw —
     // it is also reused below only as a `.length > 0` guard ahead of
@@ -351,31 +381,40 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
     const scopedPhaseDirFiles = scopeToPhase(phaseDirFiles, node_path_1.default.basename(absPhaseDir));
     const ctxFile = findContextMdIn(scopedPhaseDirFiles);
     const ctxPath = ctxFile ? node_path_1.default.join(absPhaseDir, ctxFile) : null;
-    const ctxMd = ctxPath ? node_fs_1.default.readFileSync(ctxPath, 'utf-8') : '';
+    const ctxRead = ctxPath ? (0, gate_evidence_cjs_1.readTextEvidence)(ctxPath) : null;
+    if (ctxPath && ctxRead && ctxRead.kind === 'unreadable')
+        unreadable.push({ reason: ctxRead.reason, span: ctxPath });
+    const ctxMd = ctxRead && ctxRead.kind === 'found' ? ctxRead.value : '';
     // Use extractDecisions so gap-checker can distinguish could-not-parse from none-present.
     const ctxExtraction = (0, decisions_cjs_1.extractDecisions)(ctxMd);
     const dItems = ctxExtraction.decisions.map(d => ({ ...d, source: 'CONTEXT.md' }));
     const items = [...reqItems, ...dItems];
     let planText = '';
-    try {
-        if (phaseDirFiles.length > 0) {
-            // #3183 (lint-plan-count-drift): source the live plan-file list from
-            // the single owner (scanPhasePlans) instead of a local `-PLAN\.md$`
-            // filter on the already-read listing — picks up bare PLAN.md, nested
-            // plans/, and excludes superseded plans, none of which the prior
-            // root-only exact-suffix filter did.
-            const files = scanPhasePlans(absPhaseDir).planFiles;
-            planText = files.map(f => {
-                try {
-                    return node_fs_1.default.readFileSync(node_path_1.default.join(absPhaseDir, f), 'utf-8');
-                }
-                catch {
-                    return '';
-                }
+    if (phaseDirFiles.length > 0) {
+        // #3183 (lint-plan-count-drift): source the live plan-file list from
+        // the single owner (scanPhasePlans) instead of a local `-PLAN\.md$`
+        // filter on the already-read listing — picks up bare PLAN.md, nested
+        // plans/, and excludes superseded plans, none of which the prior
+        // root-only exact-suffix filter did.
+        // #5170: a scan that did not see every plan (an existing nested plans/ that could not be read,
+        // SCOPE.TRUNCATED) is `unreadable`, never a short plan set that reports the missing plans' IDs
+        // as "Not covered".
+        const planSet = (0, gate_evidence_cjs_1.readPlanSetEvidence)(absPhaseDir);
+        if (planSet.kind === 'unreadable') {
+            unreadable.push({ reason: planSet.reason, span: planSet.span ?? absPhaseDir });
+        }
+        else {
+            planText = planSet.value.map(f => {
+                const planPath = node_path_1.default.join(absPhaseDir, f);
+                const plan = (0, gate_evidence_cjs_1.readTextEvidence)(planPath);
+                // A plan that exists but cannot be read is `unreadable`, never an empty slice of the text the
+                // coverage is detected in (it would report every ID it holds as "Not covered").
+                if (plan.kind === 'unreadable')
+                    unreadable.push({ reason: plan.reason, span: planPath });
+                return plan.kind === 'found' ? plan.value : '';
             }).join('\n');
         }
     }
-    catch { /* unreadable */ }
     // FIX D (#1365): surface decision could-not-parse independently of whether
     // requirements items exist. Without this, a could-not-parse on decisions is
     // silently masked whenever REQUIREMENTS.md has ≥1 item — the mismatch must
@@ -411,6 +450,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
                 counts: { total: rows.length, covered, uncovered },
                 phase_dir_read_error: phaseDirReadError,
                 phase_dir_scope: phaseDirScope,
+                ...unreadableField(),
             };
         }
         return {
@@ -421,6 +461,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             counts: { total: 0, covered: 0, uncovered: 0 },
             phase_dir_read_error: phaseDirReadError,
             phase_dir_scope: phaseDirScope,
+            ...unreadableField(),
         };
     }
     // #1365: if no items at all, surface a clean no-check message.
@@ -439,6 +480,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
             counts: { total: 0, covered: 0, uncovered: 0 },
             phase_dir_read_error: phaseDirReadError,
             phase_dir_scope: phaseDirScope,
+            ...unreadableField(),
         };
     }
     const rows = sortRows([
@@ -458,6 +500,7 @@ function runGapAnalysis(cwd, phaseDir, options = {}) {
         counts: { total: rows.length, covered, uncovered },
         phase_dir_read_error: phaseDirReadError,
         phase_dir_scope: phaseDirScope,
+        ...unreadableField(),
     };
 }
 function cmdGapAnalysis(cwd, args, raw) {

package/gsd-core/bin/lib/gate-api-coverage-verify-pre.cjs

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * `check api-coverage.verify-pre` 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).
+ *
+ * BLOCKING seal-time gate for the ai-integration capability (#1562). Enforces "Full API Coverage by
+ * Default — Opt Out, Never Opt In." A phase that integrates an external API/SDK/service may not seal
+ * until a COVERAGE.md matrix enumerates the surface and every non-integrated capability is an
+ * explicit, reasoned opt-out.
+ *
+ * Contract (two touch points composed into one check):
+ *   1. If COVERAGE.md exists in the phase dir → validate it (acceptance #2).
+ *      Block on any validation error (empty matrix, OPT-OUT without reason,
+ *      duplicate/empty capability).
+ *   2. If COVERAGE.md is absent → run detectApiIntegration over the phase scope
+ *      (PLAN.md body, then ROADMAP phase section as fallback). If a strong
+ *      external-API-integration signal is detected → BLOCK ("integration
+ *      detected without coverage matrix"). If no signal → PASS (treat as a
+ *      non-API phase; acceptance #4 — low false positives).
+ *
+ * The detector is the FALLBACK for the "nobody decided / forgot the matrix" case; the primary path
+ * is the plan:pre contribution prompting COVERAGE.md.
+ *
+ * Argv after the verb: `<phase-dir-or-token>`. Payload: the uniform gate contract
+ * `{ block, passed, message, ...details }`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPhaseScope = readPhaseScope;
+exports.evaluateApiCoverageVerifyPre = evaluateApiCoverageVerifyPre;
+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");
+// 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;
+const security_cjs_1 = require("./security.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapModule = require("./roadmap.cjs");
+const { getRoadmapPhaseWithFallback } = roadmapModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const apiCoverageMod = require("./api-coverage.cjs");
+const { detectApiIntegration, validateCoverageMatrix } = apiCoverageMod;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// 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;
+// NOTE: `fs` is used as a namespace object at call time (never destructured at load) so tests can
+// monkeypatch its methods for failure injection.
+function readPhaseScope(projectDir, phaseDir, phaseNumber) {
+    const chunks = [];
+    let readError = null;
+    // A MISSING phase directory is fine (no plans yet → fall through to the
+    // roadmap). Checked up front (rather than via a readdirSync catch) because
+    // #3183 (lint-plan-count-drift) now sources the plan-file list from the
+    // single owner (scanPhasePlans) instead of a local `-PLAN\.md$` readdirSync
+    // filter — picks up bare PLAN.md and nested plans/, and excludes
+    // superseded plans, none of which the prior root-only exact-suffix filter
+    // did.
+    // `fs.existsSync` answered `false` for an EACCES on a parent, skipping plans the gate never saw and
+    // letting detection run over a roadmap fallback; the stat keeps that case an unreadable scope (#5170).
+    const phaseDirStat = (0, gate_evidence_cjs_1.statEvidence)(phaseDir);
+    if (phaseDirStat.kind === 'unreadable') {
+        return {
+            text: '',
+            readError: `could not read the phase directory: ${phaseDirStat.reason}`,
+        };
+    }
+    if (phaseDirStat.kind === 'found') {
+        const scan = scanPhasePlans(phaseDir);
+        if (scan.scope !== SCOPE.COMPLETE) {
+            // Directory exists but scanPhasePlans could not see all of it: its own readdirSync(phaseDir)
+            // failed (UNREADABLE) or the nested plans/ directory exists and could not be read
+            // (TRUNCATED). Only COMPLETE is a real answer; a short plan set is never evidence of "no
+            // plans" (#2365 review, #5170), so the gate must not pass over it.
+            return {
+                text: '',
+                readError: `could not read the phase directory: scanPhasePlans reported scope ${scan.scope.toUpperCase()}`,
+            };
+        }
+        const plans = [...scan.planFiles].sort();
+        for (const p of plans) {
+            const plan = (0, gate_evidence_cjs_1.readTextEvidence)(node_path_1.default.join(phaseDir, p));
+            if (plan.kind === 'found') {
+                chunks.push(plan.value);
+            }
+            else if (!readError) {
+                // A plan file the scan listed that cannot be read (or vanished since) — record it and keep
+                // reading the rest so the message names the first failure.
+                readError = `could not read ${p}: ${plan.kind === 'unreadable' ? plan.reason : 'it disappeared since the scan'}`;
+            }
+        }
+    }
+    if (readError)
+        return { text: chunks.join('\n\n'), readError };
+    if (chunks.join('').trim().length > 0)
+        return { text: chunks.join('\n\n'), readError: null };
+    // Fallback: ONLY this phase's ROADMAP section (not the whole file, which
+    // would pollute detection with sibling-phase prose). A MISSING roadmap/section
+    // is non-fatal; a roadmap that exists but cannot be read is a real failure.
+    if (phaseNumber) {
+        try {
+            const section = getRoadmapPhaseWithFallback(projectDir, phaseNumber);
+            if (section)
+                return { text: section, readError: null };
+        }
+        catch (err) {
+            // An absent roadmap/section is "not there yet"; any other failure is a real read failure.
+            if ((0, gate_evidence_cjs_1.evidenceFromError)(err, 'ROADMAP.md').kind === 'unreadable') {
+                return {
+                    text: '',
+                    readError: `could not read the roadmap fallback: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        }
+    }
+    return { text: '', readError: null };
+}
+function evaluateApiCoverageVerifyPre(input) {
+    const { projectDir, args } = input;
+    const phaseArg = typeof args[0] === 'string' ? args[0] : '';
+    if (!phaseArg) {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.SDK_MISSING_ARG, 'api-coverage.verify-pre requires a phase argument: check api-coverage.verify-pre <phase-dir-or-token>');
+    }
+    const pDir = planningDir(projectDir);
+    const phasesRoot = node_path_1.default.join(pDir, 'phases');
+    // SECURITY (path traversal): the phase argument is taken ONLY as a phase
+    // token — its basename — and resolved by findPhaseInternal strictly under
+    // .planning/phases/ (or a milestone archive). The raw arg is never used as a
+    // path, so `..`, absolute paths, and arbitrary directories cannot reach a
+    // file read. Mirrors the schema-drift gate's (gate-schema-drift.cts) token-match approach.
+    let token = (0, shell_command_projection_cjs_1.posixNormalize)(phaseArg).split('/').filter(Boolean).pop() || '';
+    // A token like ".." or "." carries no phase identity → unresolvable.
+    if (token === '.' || token === '..')
+        token = '';
+    // Not a GSD project (no phases tree at all) → fail-open: nothing to gate. Only an ABSENT tree
+    // (`none`) is that answer; one that exists but cannot be examined (an EACCES on a parent) is
+    // `unreadable` — `fs.existsSync` said `false` for it and certified "not a GSD project" (#5170).
+    const phasesRootStat = (0, gate_evidence_cjs_1.statEvidence)(phasesRoot);
+    if (phasesRootStat.kind === 'unreadable') {
+        return (0, gate_verdict_cjs_1.gateUnreadable)(true, {
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            read_error: phasesRootStat.reason,
+            message: `api-coverage: could not examine .planning/phases (${phasesRootStat.reason}) — ` +
+                'refusing to treat an unreadable phases tree as "not a GSD project". ' +
+                'Fix the directory permissions before sealing.',
+        });
+    }
+    if (phasesRootStat.kind === 'none') {
+        return (0, gate_verdict_cjs_1.gateVerdict)('pass', false, {
+            block: false,
+            passed: true,
+            coverage_present: false,
+            detected: false,
+            message: 'api-coverage: no .planning/phases directory; gate skipped (not a GSD project layout)',
+        });
+    }
+    // Resolve the phase dir under the contained phases root.
+    let resolvedDir = null;
+    let phaseNumber = '';
+    if (token) {
+        const found = findPhaseInternal(projectDir, token);
+        if (found && found.directory) {
+            // findPhaseInternal's `directory` is relative to the project root; anchor it to `projectDir`
+            // (not the process cwd) so the gate reads the same files in-process as it does from the CLI.
+            resolvedDir = node_path_1.default.resolve(projectDir, found.directory);
+            phaseNumber = found.phase_number || '';
+        }
+    }
+    if (!resolvedDir) {
+        // The phases tree EXISTS but THIS phase could not be resolved. For a
+        // BLOCKING gate, fail-closed: a missing phase dir must not silently bypass
+        // the coverage requirement. (Distinguished from "no .planning at all"
+        // above, which is a genuine non-GSD-project → pass.)
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, {
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            phase_lookup_failed: true,
+            message: `api-coverage: could not resolve phase "${phaseArg}" under .planning/phases/. ` +
+                'Resolve the phase directory (or produce COVERAGE.md) before sealing.',
+        });
+    }
+    // Defense-in-depth: the resolved dir must be inside the phases root (or a
+    // milestone archive under .planning/milestones).
+    const milestonesRoot = node_path_1.default.join(pDir, 'milestones');
+    // Lexical containment (ADR-4650): resolvedDir is a directory path, not read
+    // through here — mirrors the prior path.resolve(root, candidate)-based check
+    // without introducing a filesystem/realpath dependency this defense-in-depth
+    // recheck never had.
+    if ((0, security_cjs_1.tryWithinRootLexical)(resolvedDir, phasesRoot) === null &&
+        (0, security_cjs_1.tryWithinRootLexical)(resolvedDir, milestonesRoot) === null) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, {
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            message: 'api-coverage: resolved phase dir escapes .planning/ — refusing to evaluate',
+        });
+    }
+    // (1) locate COVERAGE.md — prefer the exact name, then a single *-COVERAGE.md.
+    let coverageFile = '';
+    let suffixed = [];
+    // #5170 (ADR-5057 §4): a phase directory that EXISTS but cannot be listed is `unreadable` —
+    // a COVERAGE.md may be in it — and never falls through to the detector, whose pass would be
+    // certified from a directory the gate never saw. An ABSENT directory (`none`) has no matrix and
+    // proceeds to detection, as before. The blocking policy is unchanged (fail-closed).
+    const listing = (0, gate_evidence_cjs_1.readDirEntriesEvidence)(resolvedDir);
+    if (listing.kind === 'unreadable') {
+        return (0, gate_verdict_cjs_1.gateUnreadable)(true, {
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            read_error: listing.reason,
+            message: `api-coverage: could not read the phase directory (${listing.reason}) — ` +
+                'refusing to certify the coverage matrix from a directory that could not be listed. ' +
+                'Fix the directory permissions before sealing.',
+        });
+    }
+    if (listing.kind === 'found') {
+        const files = listing.value.filter((e) => e.isFile()).map((e) => e.name);
+        const exact = files.find((f) => /^COVERAGE\.md$/i.test(f));
+        if (exact) {
+            coverageFile = exact;
+        }
+        else {
+            suffixed = files.filter((f) => /-COVERAGE\.md$/i.test(f)).sort();
+            if (suffixed.length === 1)
+                coverageFile = suffixed[0];
+        }
+    }
+    if (coverageFile) {
+        const matrix = (0, gate_evidence_cjs_1.readTextEvidence)(node_path_1.default.join(resolvedDir, coverageFile));
+        if (matrix.kind !== 'found') {
+            // COVERAGE.md exists but is unreadable (EACCES/EIO/encoding), or vanished between the
+            // listing and the read. Fail-closed (policy unchanged) and `unreadable` (outcome).
+            return (0, gate_verdict_cjs_1.gateUnreadable)(true, {
+                block: true,
+                passed: false,
+                coverage_present: true,
+                message: `api-coverage: COVERAGE.md exists but is unreadable — fix file permissions/encoding before sealing`,
+            });
+        }
+        const matrixText = matrix.value;
+        const v = validateCoverageMatrix(matrixText);
+        if (v.valid) {
+            if (v.none_declared) {
+                // The declaration is the human override for the detector — it PASSES
+                // even when detection fires (that is acceptance #5's point: the
+                // detector is fallible and the declaration is the reasoned overrule).
+                // But a contradiction must be VISIBLE, not silent: re-run detection
+                // over the phase scope and surface any signals it still finds
+                // (#2365 review S-1).
+                const declScope = readPhaseScope(projectDir, resolvedDir, phaseNumber);
+                const declDetection = detectApiIntegration(declScope.text);
+                const declSignals = declDetection.signals.map((s) => ({ verb: s.verb, noun: s.noun }));
+                // The declaration legitimately wins even over a read error (it is the
+                // human overrule), but if scope was incomplete we say so — the contract
+                // is that contradictions stay visible, not silent (#2365 review).
+                const baseMsg = declDetection.detected
+                    ? `api-coverage: COVERAGE.md declares no external API integration, overriding ${declSignals.length} detected signal(s) — confirm the declaration is accurate`
+                    : 'api-coverage: COVERAGE.md declares no external API integration — matrix not required';
+                return (0, gate_verdict_cjs_1.gateVerdict)('pass', false, {
+                    block: false,
+                    passed: true,
+                    coverage_present: true,
+                    matrix: coverageFile,
+                    counts: v.counts,
+                    none_declared: true,
+                    detected: declDetection.detected,
+                    ...(declDetection.detected ? { signals: declSignals } : {}),
+                    ...(declScope.readError ? { scope_read_error: declScope.readError } : {}),
+                    message: declScope.readError
+                        ? `${baseMsg} (note: phase scope was incompletely read — ${declScope.readError})`
+                        : baseMsg,
+                });
+            }
+            return (0, gate_verdict_cjs_1.gateVerdict)('pass', false, {
+                block: false,
+                passed: true,
+                coverage_present: true,
+                matrix: coverageFile,
+                counts: v.counts,
+                message: `api-coverage: matrix present (${v.counts.surface} capabilities, ${v.counts.optout} opt-out)`,
+            });
+        }
+        // Fixed-template message (no raw cell content echoed into the LLM-facing
+        // message). The structured `errors` array is safe (row-indexed, no cell
+        // values) and travels as data for tooling that wants detail.
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, {
+            block: true,
+            passed: false,
+            coverage_present: true,
+            matrix: coverageFile,
+            error_count: v.errors.length,
+            errors: v.errors,
+            message: `api-coverage: COVERAGE.md has ${v.errors.length} problem(s) — fix the matrix (every capability INTEGRATE or OPT-OUT with a reason) before sealing`,
+        });
+    }
+    if (suffixed.length > 1) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, {
+            block: true,
+            passed: false,
+            coverage_present: false,
+            message: `api-coverage: multiple *-COVERAGE.md files found (${suffixed.length}) — consolidate into one COVERAGE.md before sealing`,
+        });
+    }
+    // (2) no matrix — detect whether this phase integrates an external API.
+    const scope = readPhaseScope(projectDir, resolvedDir, phaseNumber);
+    if (scope.readError) {
+        // Fail-closed: an unreadable plan could be the one describing the
+        // integration, so we cannot certify "no integration" — block and surface it. The blocking
+        // policy is unchanged; the outcome is `unreadable` (exit UNAVAILABLE, #5170).
+        return (0, gate_verdict_cjs_1.gateUnreadable)(true, {
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            message: `api-coverage: could not read the phase scope (${scope.readError}); ` +
+                'refusing to certify no external-API integration from incomplete scope. ' +
+                'Fix the unreadable plan file, or add a COVERAGE.md declaration.',
+        });
+    }
+    // An EMPTY scope is not a negative verdict. This gate's neighbouring arms
+    // already fail closed (unresolvable phase → block; unreadable plan → block),
+    // but a phase with no plan body AND no roadmap section fell through to
+    // detection over zero bytes and CERTIFIED "no external-API integration" —
+    // clearing a blocking seal gate on a probe that examined nothing
+    // (ADR-3889 failure class (c), #3909). The discriminator is BYTES EXAMINED,
+    // never SIGNALS FOUND: a phase with real plans and no API vocabulary still
+    // reaches the pass below unchanged.
+    if (scope.text.trim() === '') {
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, {
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            scope_unavailable: true,
+            message: 'api-coverage: the phase scope is empty — no plan body and no roadmap section were ' +
+                'found, so nothing was examined. Refusing to certify no external-API integration ' +
+                'from an unestablished scope. Add the phase plan, or add a COVERAGE.md declaration.',
+        });
+    }
+    const detection = detectApiIntegration(scope.text);
+    if (detection.detected) {
+        // Surface only verb/noun (typed, bounded) — NOT raw prose snippets — so the
+        // gate output cannot relay injected PLAN.md instructions to the orchestrator.
+        const signals = detection.signals.map((s) => ({ verb: s.verb, noun: s.noun }));
+        return (0, gate_verdict_cjs_1.gateVerdict)('block', true, {
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: true,
+            signals,
+            message: 'api-coverage: external-API integration detected without a coverage matrix. ' +
+                'Produce COVERAGE.md enumerating the API surface (every capability INTEGRATE or ' +
+                'OPT-OUT with a reason) before sealing. Full coverage is the default.',
+        });
+    }
+    return (0, gate_verdict_cjs_1.gateVerdict)('pass', false, {
+        block: false,
+        passed: true,
+        coverage_present: false,
+        detected: false,
+        message: 'api-coverage: no external-API integration detected; coverage matrix not required',
+    });
+}

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

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Gate argv parsing — the one `--flag value` / positional splitter the flag-taking `check` verbs
+ * share (#5139, epic #5056, design D2/D3).
+ *
+ * Moved verbatim from `check-command-router.cts` so a gate module can take the argv after its verb
+ * and the router's `check predicate` arm can keep using the same parser: there is exactly one, so
+ * the flag-taking check verbs cannot drift apart. Pure; no I/O.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.partitionPredicateArgs = partitionPredicateArgs;
+exports.parsePredicateFlags = parsePredicateFlags;
+/**
+ * Split an args array into `--flag value` pairs and the leftover positional
+ * tokens, in ONE pass, with the semantics `check predicate` established
+ * (#2008): a `--flag` followed by a non-`--` token consumes it as the value
+ * (last write wins); a `--flag` with no value stays a bare token and moves to
+ * the positionals; everything else is positional. `parsePredicateFlags` is
+ * the flags half of this same pass — there is exactly one parser, so the
+ * flag-taking check verbs cannot drift apart (#4130 follow-up: `check
+ * decision-coverage-plan --context <path>` shares it).
+ */
+function partitionPredicateArgs(args) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (typeof a !== 'string')
+            continue;
+        if (!a.startsWith('--')) {
+            positionals.push(a);
+            continue;
+        }
+        const key = a.slice(2);
+        const next = args[i + 1];
+        if (key.length > 0 && typeof next === 'string' && !next.startsWith('--')) {
+            // defineProperty, not `flags[key] = next`: an own data property for EVERY caller-supplied
+            // key. A plain assignment of `--__proto__ v` set nothing (the pair was consumed and its
+            // value silently lost), and assigning through a caller-controlled key is the
+            // prototype-pollution sink shape.
+            Object.defineProperty(flags, key, { value: next, enumerable: true, writable: true, configurable: true });
+            i++;
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { flags, positionals };
+}
+/** Parse `--flag value` pairs from an args array into a map (last write wins). */
+function parsePredicateFlags(args) {
+    return partitionPredicateArgs(args).flags;
+}