@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.6

package/gsd-core/bin/gsd-tools.cjs

@@ -688,7 +688,7 @@ async function main() {
   // phase / roadmap / milestone / progress / etc.
   const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
     'Commands: agent, agent-skills, assumption-delta, audit-open, audit-uat, check, check-commit, commit, commit-to-subrepo, pr-subrepo, ' +
-    'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, ' +
+    'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, normalize-test-command, ' +
     'current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
     'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
@@ -1291,6 +1291,16 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    case 'normalize-test-command': {
+      // #1857: rewrite a resolved test command to a one-shot form so a
+      // watch-mode runner (vitest/jest) cannot hang a verification gate. Shared
+      // by the regression gate and the post-merge gate. args[1] is the raw
+      // resolved command; --cwd (already parsed into `cwd`) locates package.json.
+      const testCommandNormalizer = require('./lib/normalize-test-command.cjs');
+      testCommandNormalizer.cmdNormalizeTestCommand(cwd, args[1]);
+      break;
+    }
+
     case 'dispatch-should-flatten': {
       // #1708 / #853: typed query replacing the `RUNTIME === 'codex'` prose rule.
       //
@@ -2140,6 +2150,28 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
             }
           }
         } catch { /* best-effort — list still works without the inactive annotation */ }
+        // Issue #2045 (DEFECT 3): derive each capability's SURFACED state from the
+        // SAME resolver `capability state` uses (resolveCapabilityRuntimeState), so
+        // `list` and `state` stop disagreeing. `list` previously derived `status`
+        // purely from ledger-entry existence — an installed-but-not-surfaced cap
+        // reported active in `list` and absent in `state`. Surfaced is evaluated at
+        // the default runtime config dir (the resolver resolves it when undefined),
+        // matching `capability state <id>` with no --config-dir. Best-effort: a
+        // resolver failure leaves surfacedById empty (rows report surfaced:null).
+        const surfacedById = {};
+        // surfacedById is keyed by capId only (NOT `${scope} ${capId}`): surface
+        // state is single-source — one runtime config dir → one .gsd-surface.json
+        // → one surfaced truth per capId — and the loader dedupes overlay caps to
+        // one registry entry per id (first-party-wins). So a cap installed in both
+        // scopes correctly shares one surfaced value across its list rows.
+        try {
+          const surfaceState = capabilityState.resolveCapabilityRuntimeState(cwd, undefined);
+          for (const cap of (surfaceState && surfaceState.capabilities) || []) {
+            if (cap && typeof cap.id === 'string') {
+              surfacedById[cap.id] = cap.surfaced === true;
+            }
+          }
+        } catch { /* best-effort — list still works without the surfaced annotation */ }
         for (const capId of Object.keys(fp)) {
           const cap = fp[capId] || {};
           rows.push({
@@ -2150,6 +2182,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
             source: 'first-party',
             scope: 'first-party',
             status: 'active',
+            surfaced: Object.prototype.hasOwnProperty.call(surfacedById, capId) ? surfacedById[capId] === true : null,
             title: cap.title || null,
           });
         }
@@ -2199,6 +2232,12 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
               scope: sc,
               status,
               reason,
+              // Issue #2045 (DEFECT 3): surfaced reflects surface composition, so
+              // list and state agree. An inactive (unconsented/incompatible) cap is
+              // surfaced:false by definition; otherwise defer to the resolver.
+              surfaced: status === 'active'
+                ? (Object.prototype.hasOwnProperty.call(surfacedById, capId) ? surfacedById[capId] === true : null)
+                : false,
               title: manifest.title || null,
             });
           }

package/gsd-core/bin/lib/api-coverage.cjs

@@ -0,0 +1,466 @@
+"use strict";
+/**
+ * API-Coverage detector + matrix validator (#1562).
+ *
+ * The enforcement half of "Full API Coverage by Default — Opt Out, Never Opt In."
+ * When a phase integrates an external API/service/SDK, the planner must produce a
+ * coverage matrix (COVERAGE.md) enumerating the API's capability surface; every
+ * non-integrated capability is an explicit, reasoned opt-out. The seal-time gate
+ * (capabilities/ai-integration, verify:pre) consumes this module to (a) detect
+ * whether a phase integrates an external API and (b) validate the produced matrix.
+ *
+ * Design notes (rubber-duck'd):
+ *  - DETERMINISTIC + TYPED IR. Both the "does this phase integrate an external
+ *    API?" decision and the "is this matrix complete?" decision are pure
+ *    functions returning typed IR, not LLM judgments — so the low-false-positive
+ *    guarantee (acceptance criterion #4) and the completeness guarantee
+ *    (acceptance #2) are testable. Mirrors assumption-delta.cts (#1561).
+ *  - COMPOUND SIGNAL for low false positives. A bare word like "api" appears in
+ *    countless non-integration phases ("the public API of UserController"). The
+ *    detector requires an INTEGRATION VERB co-occurring with an EXTERNAL-API
+ *    NOUN (or an explicit "<Service> API/SDK" phrase). Single weak tokens do not
+ *    fire. This is the issue's "low false-positive trigger" made mechanical.
+ *  - FENCED CODE BLOCKS ARE STRIPPED first (markdown-sectionizer seam) so a
+ *    trigger term inside a code snippet does not fire.
+ *  - THE DETECTOR IS A FALLBACK. The primary path is the plan:pre contribution
+ *    prompting COVERAGE.md creation. The detector runs only when COVERAGE.md is
+ *    ABSENT, to catch the "nobody decided" case (acceptance #1). Its precision
+ *    therefore matters but is not the only line of defense.
+ *  - MATRIX FORMAT. The matrix is a markdown table (human-editable, diff-friendly)
+ *    with a header row `| capability | decision | reason |` and one row per
+ *    capability. decision ∈ {INTEGRATE, OPT-OUT}. An OPT-OUT row MUST carry a
+ *    non-empty reason. A fenced ```coverage JSON block is also accepted for
+ *    machine-generated matrices. This dual shape is bijective (parse/render
+ *    round-trip) and covered by a fast-check property test.
+ *  - ADDITIVE-ONLY VOCABULARY (Hyrum's Law). Once shipped, the verb/noun sets
+ *    are depended-upon interfaces; they only grow. Tunable via the `terms`
+ *    parameter so teams can widen them without forking.
+ *
+ * Public API:
+ *   detectApiIntegration(text, terms?) -> { detected, signals, terms }
+ *   parseCoverageMatrix(text) -> { rows, errors, format }
+ *   validateCoverageMatrix(text) -> { valid, errors, counts }
+ *   renderCoverageMatrix(rows) -> string
+ *   DEFAULT_API_COVERAGE_TERMS
+ *
+ * CLI:
+ *   echo "$SCOPE" | node gsd-core/bin/lib/api-coverage.cjs [--json]
+ *     exit 0 = integration detected, 1 = none, 2 = startup error
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_COVERAGE_TERMS = void 0;
+exports.detectApiIntegration = detectApiIntegration;
+exports.parseCoverageMatrix = parseCoverageMatrix;
+exports.validateCoverageMatrix = validateCoverageMatrix;
+exports.renderCoverageMatrix = renderCoverageMatrix;
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+/**
+ * Curated default trigger vocabulary. ADDITIVE-ONLY (Hyrum's Law). Tunable via
+ * the `terms` parameter.
+ *
+ * VERBS are deliberately conservative: common verbs like "add", "use", "call",
+ * "implement" are EXCLUDED because they appear in nearly every phase and would
+ * make the gate fire on prose that has nothing to do with an external API. The
+ * verbs kept all connote BRINGING IN an external surface.
+ *
+ * NOUNS name an external-API surface. Bare "client" is excluded — too ambiguous
+ * (client-side UI vs API client). "service" alone is excluded (internal
+ * services); a phase integrating an external service virtually always pairs it
+ * with "API"/"SDK"/"REST"/etc., which the compound verb+noun rule captures.
+ */
+exports.DEFAULT_API_COVERAGE_TERMS = {
+    verbs: [
+        'integrate',
+        'integrates',
+        'integrating',
+        'integration',
+        'wrap',
+        'wraps',
+        'wrapping',
+        'connect',
+        'connects',
+        'connecting',
+        'consume',
+        'consumes',
+        'consuming',
+        'wire',
+        'wires',
+        'wiring',
+        'onboard',
+        'onboarding',
+        'adopt',
+        'adopts',
+        'adopting',
+    ],
+    nouns: [
+        'api',
+        'apis',
+        'sdk',
+        'sdks',
+        'rest',
+        'graphql',
+        'grpc',
+        'endpoint',
+        'endpoints',
+        'oauth',
+        'oauth2',
+        'webhook',
+        'webhooks',
+        'mcp',
+    ],
+};
+/** Hardening caps for the tunable vocabulary (hostile `--terms` defense). */
+const MAX_TERMS_PER_KIND = 200;
+const MAX_TERM_LEN = 32;
+/**
+ * Field-length caps for matrix cell values. Cell content flows from a
+ * semi-trusted COVERAGE.md into the gate `message` that the orchestrator LLM
+ * reads, so it is bounded to keep the prompt-injection surface small and to
+ * document the format contract (short, single-line prose — not paragraphs).
+ */
+const CAPABILITY_MAX_LEN = 80;
+const REASON_MAX_LEN = 200;
+function normalizeTerms(list) {
+    if (!Array.isArray(list))
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const raw of list) {
+        if (typeof raw !== 'string')
+            continue;
+        const t = raw.trim().toLowerCase().slice(0, MAX_TERM_LEN);
+        if (!t || !/[a-z0-9]/.test(t))
+            continue;
+        if (seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
+        if (out.length >= MAX_TERMS_PER_KIND)
+            break;
+    }
+    return out;
+}
+function resolveTerms(terms) {
+    const merge = (key) => {
+        const t = terms && terms[key];
+        return Array.isArray(t) ? normalizeTerms(t) : [...exports.DEFAULT_API_COVERAGE_TERMS[key]];
+    };
+    return { verbs: merge('verbs'), nouns: merge('nouns') };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function makeSnippet(line, anchor) {
+    const cleaned = line.replace(/\s+/g, ' ').trim();
+    if (cleaned.length <= 120)
+        return cleaned;
+    const idx = cleaned.toLowerCase().indexOf(anchor);
+    if (idx < 0)
+        return cleaned.slice(0, 120);
+    const start = Math.max(0, idx - 50);
+    const end = Math.min(cleaned.length, idx + anchor.length + 50);
+    const prefix = start > 0 ? '…' : '';
+    const suffix = end < cleaned.length ? '…' : '';
+    return `${prefix}${cleaned.slice(start, end)}${suffix}`;
+}
+/** `<Service> API` / `<Service> SDK` — a capitalized proper noun immediately
+ *  followed by API/SDK. Strong signal on its own (no verb required).
+ *
+ *  STOPWORDS guard against the false positive where an ordinary capitalized
+ *  sentence starter ("The API …", "An SDK …", "Our REST …") matches the
+ *  `[A-Z]\w+ API` shape. Those are common English, not a service name, so they
+ *  are rejected before counting as a surface signal (acceptance #4 — low false
+ *  positives). */
+const SERVICE_SURFACE_API_RE = /\b([A-Z][A-Za-z0-9_-]{1,})\s+(API|SDK|REST|GraphQL)\b/;
+const SERVICE_STOPWORDS = new Set([
+    'the', 'an', 'a', 'our', 'this', 'these', 'that', 'those', 'new', 'add',
+    'use', 'your', 'my', 'no', 'some', 'any', 'all', 'each', 'every', 'both',
+    'if', 'when', 'while', 'with', 'via', 'using', 'into', 'its', 'their',
+    'we', 'you', 'they', 'it',
+]);
+/**
+ * Detect whether phase-scope prose describes integrating an external API/SDK.
+ *
+ * Fires when EITHER:
+ *   (a) a compound verb+noun signal co-occurs on the same line, OR
+ *   (b) an explicit `<Service> API|SDK|REST|GraphQL` surface appears.
+ *
+ * Non-string inputs degrade to `{ detected: false }` without throwing.
+ */
+function detectApiIntegration(text, terms) {
+    const effective = resolveTerms(terms);
+    if (typeof text !== 'string') {
+        return { detected: false, signals: [], terms: effective };
+    }
+    const stripped = (0, markdown_sectionizer_cjs_1.stripFencedCode)(text.replace(/\r\n/g, '\n')).text;
+    if (stripped.trim().length === 0) {
+        return { detected: false, signals: [], terms: effective };
+    }
+    const signals = [];
+    const seen = new Set();
+    const lines = stripped.split('\n');
+    // (a) compound verb+noun on the same line.
+    if (effective.verbs.length > 0 && effective.nouns.length > 0) {
+        const verbRe = new RegExp('(^|[^a-zA-Z0-9])(' + effective.verbs.map(escapeRegex).join('|') + ')([^a-zA-Z0-9]|$)', 'gi');
+        const nounRe = new RegExp('(^|[^a-zA-Z0-9])(' + effective.nouns.map(escapeRegex).join('|') + ')([^a-zA-Z0-9]|$)', 'gi');
+        for (const line of lines) {
+            verbRe.lastIndex = 0;
+            nounRe.lastIndex = 0;
+            const vMatch = verbRe.exec(line);
+            if (!vMatch)
+                continue;
+            const nMatch = nounRe.exec(line);
+            if (!nMatch)
+                continue;
+            const verb = (vMatch[2] || '').toLowerCase();
+            const noun = (nMatch[2] || '').toLowerCase();
+            const key = `${verb}+${noun}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            signals.push({ verb, noun, snippet: makeSnippet(line, noun) });
+        }
+    }
+    // (b) explicit <Service> API|SDK|REST|GraphQL surface.
+    for (const line of lines) {
+        SERVICE_SURFACE_API_RE.lastIndex = 0;
+        const m = SERVICE_SURFACE_API_RE.exec(line);
+        if (!m)
+            continue;
+        // Reject ordinary capitalized sentence starters ("The API …", "Our REST …").
+        if (SERVICE_STOPWORDS.has((m[1] || '').toLowerCase()))
+            continue;
+        const noun = (m[2] || '').toLowerCase();
+        const key = `surface+${noun}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        signals.push({ verb: '(surface)', noun, snippet: makeSnippet(line, m[1]) });
+    }
+    return { detected: signals.length > 0, signals, terms: effective };
+}
+const VALID_DECISIONS = new Set(['INTEGRATE', 'OPT-OUT']);
+/**
+ * Parse a coverage matrix from COVERAGE.md. Accepts two bijective formats:
+ *
+ *  1. Markdown table (canonical, human-editable):
+ *       | capability | decision | reason |
+ *       |---|---|---|
+ *       | search | INTEGRATE | |
+ *       | playlists | OPT-OUT | not needed yet |
+ *
+ *  2. Fenced ```coverage JSON block (machine-generated):
+ *       ```coverage
+ *       [ {"capability":"search","decision":"INTEGRATE","reason":""}, ... ]
+ *       ```
+ *
+ * Rows are trimmed; decisions upper-cased; missing reason → "". Returns
+ * `{ rows: [], errors: [], format: 'none' }` for empty/non-matrix input.
+ */
+function parseCoverageMatrix(text) {
+    const out = { rows: [], errors: [], format: 'none' };
+    if (typeof text !== 'string')
+        return out;
+    const src = text.replace(/\r\n/g, '\n');
+    // (1) fenced ```coverage JSON block takes precedence if present.
+    // Case-insensitive info string (```coverage and ```Coverage are both legal CommonMark).
+    // allow-adhoc-markdown: extracting a NAMED ```coverage fence (extraction of one tagged block), not stripping all fences — stripFencedCode/extractTaggedBlocks do not cover named-fence extraction.
+    const fenceMatch = src.match(/```coverage\s*\n([\s\S]*?)\n```/i);
+    if (fenceMatch && fenceMatch[1]) {
+        out.format = 'json';
+        let parsed;
+        try {
+            parsed = JSON.parse(fenceMatch[1]);
+        }
+        catch {
+            out.errors.push('fenced ```coverage block is not valid JSON');
+            return out;
+        }
+        if (!Array.isArray(parsed)) {
+            out.errors.push('fenced ```coverage block must be a JSON array');
+            return out;
+        }
+        for (let i = 0; i < parsed.length; i++) {
+            const row = rowFromJson(parsed[i]);
+            if ('error' in row) {
+                out.errors.push(`row[${i}]: ${row.error}`);
+                continue;
+            }
+            out.rows.push(row);
+        }
+        return out;
+    }
+    // (2) markdown table — collect table rows whose decision column parses.
+    const lines = src.split('\n');
+    let sawHeader = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        const cells = trimmed.slice(1, trimmed.endsWith('|') ? -1 : trimmed.length).split('|');
+        if (cells.length < 2)
+            continue;
+        const cleaned = cells.map((c) => c.trim());
+        // skip separator rows (|---|---|); require ≥3 dashes so a literal "-" cell
+        // is not mistaken for a separator.
+        if (cleaned.every((c) => /^:?-{3,}:?$/.test(c)))
+            continue;
+        const decisionCell = (cleaned[1] || '').toUpperCase();
+        // header detection
+        if (!sawHeader && cleaned[0].toLowerCase() === 'capability') {
+            sawHeader = true;
+            out.format = 'table';
+            continue;
+        }
+        if (!VALID_DECISIONS.has(decisionCell)) {
+            // A row that otherwise looks like data (≥3 cells, non-empty capability)
+            // but carries a malformed decision is a real error, not a row to skip
+            // silently — otherwise a single typo'd row collapses the matrix to
+            // "empty" and the user sees a confusing message.
+            if (cleaned.length >= 3 && cleaned[0]) {
+                out.errors.push(`row: decision "${decisionCell}" not in {INTEGRATE, OPT-OUT}`);
+            }
+            continue;
+        }
+        if (out.format === 'none')
+            out.format = 'table';
+        // A coverage row has exactly 3 cells. Extra cells mean an unescaped pipe in
+        // a value silently corrupted the row — surface it rather than parse garbage.
+        if (cleaned.length > 3) {
+            out.errors.push(`row: ${cleaned.length} columns (expected 3 — unescaped pipe in a cell?)`);
+        }
+        out.rows.push({
+            capability: cleaned[0] || '',
+            decision: decisionCell,
+            reason: (cleaned[2] ?? '').trim(),
+        });
+    }
+    return out;
+}
+function rowFromJson(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return { error: 'not an object' };
+    const o = v;
+    const capability = typeof o['capability'] === 'string' ? o['capability'].trim() : '';
+    if (!capability)
+        return { error: 'missing/empty "capability"' };
+    const dRaw = typeof o['decision'] === 'string' ? o['decision'].trim().toUpperCase() : '';
+    if (!VALID_DECISIONS.has(dRaw)) {
+        return { error: `decision "${dRaw}" not in {INTEGRATE, OPT-OUT}` };
+    }
+    const reason = typeof o['reason'] === 'string' ? o['reason'].trim() : '';
+    return { capability, decision: dRaw, reason };
+}
+/**
+ * Validate a parsed matrix. A matrix is valid when:
+ *   - it is non-empty (acceptance #1: "enumerating the API surface"),
+ *   - every capability name is non-empty,
+ *   - every decision is INTEGRATE or OPT-OUT (enforced by parser, re-checked
+ *     here for defense-in-depth),
+ *   - every OPT-OUT row carries a non-empty reason (acceptance #2).
+ *
+ * Un-enumerated remainder is not representable in the format — the gate blocks
+ * when an integration is detected and NO matrix exists. This validator catches
+ * a malformed/partial matrix that does exist.
+ */
+function validateCoverageMatrix(text) {
+    const parsed = parseCoverageMatrix(text);
+    const errors = [...parsed.errors];
+    const rows = parsed.rows;
+    if (rows.length === 0) {
+        if (errors.length === 0)
+            errors.push('matrix is empty — no capabilities enumerated');
+        return { valid: false, errors, counts: { surface: 0, integrate: 0, optout: 0 } };
+    }
+    const seen = new Set();
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        if (!row.capability) {
+            errors.push(`row[${i}]: empty capability name`);
+        }
+        else {
+            // Format contract + prompt-injection bound: cell values must be short,
+            // single-line, pipe-free prose (the matrix is a markdown table whose
+            // content flows into the gate message). Pipes/newlines would corrupt the
+            // table and let a COVERAGE.md inject unbounded text into the seal message.
+            if (/[|\n\r]/.test(row.capability)) {
+                errors.push(`row[${i}]: capability contains a pipe or newline (unsupported in a table cell)`);
+            }
+            if (row.capability.length > CAPABILITY_MAX_LEN) {
+                errors.push(`row[${i}]: capability exceeds ${CAPABILITY_MAX_LEN} chars`);
+            }
+        }
+        if (row.reason && /[|\n\r]/.test(row.reason)) {
+            errors.push(`row[${i}]: reason contains a pipe or newline (unsupported in a table cell)`);
+        }
+        if (row.reason.length > REASON_MAX_LEN) {
+            errors.push(`row[${i}]: reason exceeds ${REASON_MAX_LEN} chars`);
+        }
+        const key = row.capability.toLowerCase();
+        if (key && seen.has(key))
+            errors.push(`row[${i}]: duplicate capability`);
+        if (key)
+            seen.add(key);
+        if (!VALID_DECISIONS.has(row.decision)) {
+            errors.push(`row[${i}]: decision not in {INTEGRATE, OPT-OUT}`);
+        }
+        if (row.decision === 'OPT-OUT' && !row.reason) {
+            errors.push(`row[${i}]: OPT-OUT missing reason`);
+        }
+    }
+    const counts = {
+        surface: rows.length,
+        integrate: rows.filter((r) => r.decision === 'INTEGRATE').length,
+        optout: rows.filter((r) => r.decision === 'OPT-OUT').length,
+    };
+    return { valid: errors.length === 0, errors, counts };
+}
+/** Render rows back to the canonical markdown-table format (bijective with parse). */
+function renderCoverageMatrix(rows) {
+    const body = rows
+        .map((r) => `| ${r.capability} | ${r.decision} | ${r.reason} |`)
+        .join('\n');
+    return `| capability | decision | reason |\n|---|---|---|\n${body}`;
+}
+// ── CLI entry point ──────────────────────────────────────────────────────────
+// Reads phase-scope text from STDIN (not argv) to avoid OS ARG_MAX limits.
+// Invoked by workflow bash as: echo "$SCOPE" | node .../api-coverage.cjs [--json]
+// Exit 0 = integration detected, 1 = none, 2 = startup error. Mirrors
+// assumption-delta.cjs / ui-safety-gate.cjs.
+if (require.main === module) {
+    const argv = process.argv.slice(2);
+    const wantJson = argv.includes('--json');
+    let termsOverride;
+    const verbsIdx = argv.indexOf('--verbs');
+    const verbsVal = verbsIdx !== -1 ? argv[verbsIdx + 1] : undefined;
+    const nounsIdx = argv.indexOf('--nouns');
+    const nounsVal = nounsIdx !== -1 ? argv[nounsIdx + 1] : undefined;
+    // A non-empty, non-flag value is an override. An EMPTY value ("") restores
+    // the curated defaults (does NOT silently zero the vocabulary).
+    const verbsOverride = typeof verbsVal === 'string' && verbsVal.length > 0 && !verbsVal.startsWith('-');
+    const nounsOverride = typeof nounsVal === 'string' && nounsVal.length > 0 && !nounsVal.startsWith('-');
+    if (verbsOverride || nounsOverride) {
+        termsOverride = {};
+        if (verbsOverride) {
+            termsOverride.verbs = verbsVal.split(',').map((t) => t.trim().toLowerCase()).filter(Boolean);
+        }
+        if (nounsOverride) {
+            termsOverride.nouns = nounsVal.split(',').map((t) => t.trim().toLowerCase()).filter(Boolean);
+        }
+    }
+    const chunks = [];
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => {
+        const input = chunks.join('');
+        const result = detectApiIntegration(input, termsOverride);
+        if (wantJson) {
+            process.stdout.write(JSON.stringify(result) + '\n');
+        }
+        process.exit(result.detected ? 0 : 1);
+    });
+    process.stdin.on('error', (err) => {
+        process.stderr.write(`ERROR: api-coverage.cjs stdin read failed: ${err.message}\n`);
+        process.exit(2);
+    });
+}

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

@@ -23,6 +23,9 @@ const { planningDir } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatter;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { PHASE_NUMBER_TOKEN_SOURCE } = phaseIdMod;
 const security_cjs_1 = require("./security.cjs");
 // Terminal UAT states: `complete` (legacy) and `resolved` (post-gap-closure
 // per workflows/execute-phase.md). Hoisted outside scanUatGaps so the Set is
@@ -357,7 +360,7 @@ function scanUatGaps(planDir) {
     const results = [];
     for (const dir of dirs) {
         const phaseDir = node_path_1.default.join(phasesDir, dir);
-        const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+        const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
         const phaseNum = phaseMatch ? phaseMatch[1] : dir;
         let files;
         try {
@@ -420,7 +423,7 @@ function scanVerificationGaps(planDir) {
     const results = [];
     for (const dir of dirs) {
         const phaseDir = node_path_1.default.join(phasesDir, dir);
-        const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+        const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
         const phaseNum = phaseMatch ? phaseMatch[1] : dir;
         let files;
         try {
@@ -475,7 +478,7 @@ function scanContextQuestions(planDir) {
     const results = [];
     for (const dir of dirs) {
         const phaseDir = node_path_1.default.join(phasesDir, dir);
-        const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+        const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
         const phaseNum = phaseMatch ? phaseMatch[1] : dir;
         let files;
         try {

package/gsd-core/bin/lib/capability-loader.cjs

@@ -18,10 +18,12 @@
  *     `gsd-core-` / `anthropic-` id prefix) is rejected.
  *   - Load-time re-gate (default-resilient): an overlay that fails validation or
  *     whose `engines.gsd` does not satisfy the running GSD version is SKIPPED
- *     with a warning — it never crashes the loop. EXCEPTION (per-hook-kind
- *     policy): a skipped capability that declares a `gate` is recorded in
- *     `_overlay.incompatibleGateCapIds` so the loop resolver can fail CLOSED for
- *     that gate rather than silently proceeding as if it had passed.
+ *     with a warning — it never crashes the loop. A skipped capability that
+ *     declares a `gate` is additionally recorded in
+ *     `_overlay.incompatibleGateCapIds` / `_overlay.blockedGates` so the loop
+ *     resolver can surface a loud fail-OPEN advisory for that gate (#2009): the
+ *     un-evaluable gate is skipped (not enforced) with a remediation message,
+ *     rather than silently vanishing.
  *
  * The merged registry is materialized by the canonical `buildRegistry`
  * (re-exported from the generator, which ships) over a cap-map reconstructed
@@ -779,12 +781,12 @@ function loadRegistry(options = {}) {
         // to load. Clear the map (the first-party base never lists overlay commandRoots — first-party
         // command modules ship in bin/lib/, not via _overlay.commandRoots).
         meta.commandRoots = {};
-        // #1461 OVL-2 fail-CLOSED on compose failure (HIGH): the fallback DROPS every accepted overlay,
-        // so any accepted overlay that DECLARED a gate would have its gate silently vanish → a blocking
-        // gate FAILS OPEN, violating ADR-1244 (a skipped capability declaring a gate must FAIL CLOSED).
+        // #1461 OVL-2 (HIGH): on compose failure the fallback DROPS every accepted overlay, so any
+        // accepted overlay that DECLARED a gate would have its gate silently vanish with no trace.
         // Record each dropped gate-declaring overlay's gate as blocked using the SAME extraction the
-        // per-candidate `skip()` closure uses (gatePointsOf), so loop-resolver injects the synthetic
-        // blocking gate at each declared point exactly as it would for a per-candidate skip.
+        // per-candidate `skip()` closure uses (gatePointsOf), so loop-resolver surfaces the loud
+        // fail-OPEN advisory (#2009) at each declared point exactly as it would for a per-candidate
+        // skip — the gate does not silently disappear.
         for (const cap of overlayCaps) {
             const gatePoints = gatePointsOf(cap);
             if (gatePoints.length === 0)