@opengsd/gsd-core 1.7.0 → 1.8.0

package/gsd-core/bin/lib/adapter-imperative.cjs

@@ -43,7 +43,14 @@ function createImperativeAdapter({ runtime }, options = {}) {
         runtime,
         registry,
         install(intent) {
-            installEngine.installRuntimeArtifacts(runtime, intent.configDir, intent.scope, intent.resolvedProfile, intent.resolveAttribution);
+            // #2322: thread the SAME composed registry (loaded above, includeInstalled:true)
+            // this adapter exposes via `.registry` into the engine call, so the skills
+            // kind's stage() closure can bind an installed third-party capability
+            // skill to its declaring capId at staging time — this is the PRIMARY
+            // install path (bin/install.js prefers the adapter over the direct
+            // installRuntimeArtifacts fallback), so without this the adapter path
+            // never staged a third-party capability skill regardless of registration.
+            installEngine.installRuntimeArtifacts(runtime, intent.configDir, intent.scope, intent.resolvedProfile, intent.resolveAttribution, registry);
         },
         uninstall(intent) {
             installEngine.uninstallRuntimeArtifacts(runtime, intent.configDir, intent.scope);

package/gsd-core/bin/lib/agent-command-router.cjs

@@ -10,6 +10,20 @@
 const io = require("./io.cjs");
 const { output, error, ERROR_REASON } = io;
 // ─── Constants ────────────────────────────────────────────────────────────────
+/**
+ * #2296 — The runtime enum of failure classes `classifyAgentFailure` can emit.
+ *
+ * `AgentFailureResult`'s class strings are TypeScript types, which erase at
+ * runtime. Any second surface that needs to validate a class (the
+ * `resolve-execution --failure-class` flag) would otherwise have to re-declare
+ * the literals, giving two lists that can silently diverge. This frozen enum is
+ * the single runtime source both surfaces consume.
+ */
+const AGENT_FAILURE_CLASSES = Object.freeze({
+    QUOTA_EXCEEDED: 'quota-exceeded',
+    CLASSIFY_HANDOFF_BUG: 'classify-handoff-bug',
+    UNKNOWN_FAILURE: 'unknown-failure',
+});
 const QUOTA_SENTINELS = [
     '429',
     'usage_limit_reached',
@@ -36,23 +50,23 @@ function classifyAgentFailure(body) {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
     const normalized = String(body ?? '').toLowerCase();
     if (normalized.trim() === '') {
-        return { class: 'unknown-failure' };
+        return { class: AGENT_FAILURE_CLASSES.UNKNOWN_FAILURE };
     }
     for (const sentinel of QUOTA_SENTINELS) {
         if (normalized.includes(sentinel)) {
             const retryAfterSeconds = parseRetryAfter(body);
             return retryAfterSeconds === undefined
-                ? { class: 'quota-exceeded', sentinel }
-                : { class: 'quota-exceeded', sentinel, retryAfterSeconds };
+                ? { class: AGENT_FAILURE_CLASSES.QUOTA_EXCEEDED, sentinel }
+                : { class: AGENT_FAILURE_CLASSES.QUOTA_EXCEEDED, sentinel, retryAfterSeconds };
         }
     }
     if (normalized.includes(CLASSIFY_HANDOFF_SENTINEL)) {
         return {
-            class: 'classify-handoff-bug',
+            class: AGENT_FAILURE_CLASSES.CLASSIFY_HANDOFF_BUG,
             sentinel: CLASSIFY_HANDOFF_SENTINEL,
         };
     }
-    return { class: 'unknown-failure' };
+    return { class: AGENT_FAILURE_CLASSES.UNKNOWN_FAILURE };
 }
 function routeAgentCommand({ args, raw }) {
     const subcommand = args[1];
@@ -63,6 +77,7 @@ function routeAgentCommand({ args, raw }) {
     output(classifyAgentFailure(bodyArgs.join(' ')), raw, undefined);
 }
 module.exports = {
+    AGENT_FAILURE_CLASSES,
     classifyAgentFailure,
     routeAgentCommand,
 };

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

@@ -17,11 +17,20 @@
  *    (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.
+ *    detector requires an INTEGRATION VERB and an EXTERNAL-API NOUN in the SAME
+ *    CLAUSE (#2365 — same-line co-occurrence across unrelated clauses over-fired;
+ *    the clause boundary, not a word-gap cap, is the relationship test), or an
+ *    explicit "<Service> API/SDK" phrase naming a real service. Single weak
+ *    tokens do not fire. This is the issue's "low false-positive trigger" made
+ *    mechanical.
+ *  - CODE AND PATHS ARE NOT PROSE. Fenced code blocks and inline code spans are
+ *    stripped first (markdown-sectionizer seam), and path-shaped tokens
+ *    (`src/app/api/...`, URLs) are masked, so a trigger term inside code or a
+ *    first-party route path does not fire (#2365).
+ *  - NO-INTEGRATION DECLARATION (#2365 acceptance #5). A COVERAGE.md consisting
+ *    of `No external API integration: <reason>` is a valid, reasoned way for a
+ *    phase to state that no external surface exists — the alternative to
+ *    fabricating a matrix row when the detector is overruled by a human.
  *  - 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
@@ -171,19 +180,185 @@ function makeSnippet(line, anchor) {
  *  `[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/;
+// Service-name length is bounded ({1,40}) so a hostile "A-A-A-…-A-x" run cannot
+// drive the greedy group into O(n^2) backtracking (#2365 review). Nearly all
+// vendor names fit; a >41-char service token before API/SDK would be missed by
+// this surface path (it would still fire via the compound verb+noun rule) —
+// an accepted bound.
+const SERVICE_SURFACE_API_RE = /\b([A-Z][A-Za-z0-9_-]{1,40})\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',
 ]);
+/** #2365 — the detector is FAIL-CLOSED: it leans toward detecting, because a
+ *  false positive is cheaply dismissed by a one-line COVERAGE.md "no external
+ *  API integration" declaration, whereas a false NEGATIVE silently lets a real
+ *  external-API phase past a BLOCKING gate. So the only prose the detector
+ *  actively suppresses is the classes that are unambiguously NOT external
+ *  integration: first-party route paths, verb/noun in unrelated clauses, and
+ *  descriptive/protocol "<Word> API" prose with no named service.
+ *
+ *  CLAUSE_BOUNDARY_RE: a verb and a noun form ONE compound action only inside
+ *  one grammatical clause — sentence punctuation and table-cell walls (`|`)
+ *  end a clause. `-` is deliberately absent (it would split hyphenated words).
+ *  There is deliberately NO word-gap cap inside a clause: a cap cannot separate
+ *  a genuine long integration clause (F4, 21 words) from a long internal-UI
+ *  clause (18 words) — the clause boundary is the only sound signal, and the
+ *  declaration handles the residual false positives. */
+const CLAUSE_BOUNDARY_RE = /[,;:.!?|()—–]/;
+/** Same character class as CLAUSE_BOUNDARY_RE, as a set — for scanning a token's
+ *  trailing punctuation without an unanchored `[…]+$` regex, whose backtracking
+ *  is O(n^2) on a long punctuation run (#2365 review). */
+const CLAUSE_BOUNDARY_CHARS = new Set([',', ';', ':', '.', '!', '?', '|', '(', ')', '—', '–']);
+/*  DELIBERATELY NO cross-clause binding. Detection is same-clause only. Binding
+ *  a verb in one clause to a noun in another ("Integrate Stripe, exposing its
+ *  endpoints"; "Integrate Stripe; use its endpoints") requires knowing "Stripe"
+ *  is a vendor and "its" refers to it — a vendor dictionary + coreference, which
+ *  trek-e's brief rules out in principle. Every lexical cross-clause rule tried
+ *  (word-gap cap, participle continuation) traded a false negative for a false
+ *  positive across four review rounds. So a service named ONLY in a clause
+ *  separate from its API noun, with no explicit `<Service> API` surface, is a
+ *  DOCUMENTED fail-open limitation — cheaply covered by the COVERAGE.md
+ *  declaration and rare in real phase prose, which says "integrate the X API". */
+/** In the `<Service> API|SDK` surface position, these capture words are NOT a
+ *  named third-party service: locality/scope descriptors ("Internal API",
+ *  "Public API") and bare protocol names ("REST API", "GraphQL API"). A real
+ *  vendor name (Stripe, Shopify) is none of these, so rejecting them costs no
+ *  true positives while killing the descriptive-prose false positives (#2365
+ *  acceptance #3, review F8). */
+const SURFACE_DESCRIPTOR_WORDS = new Set([
+    'internal', 'external', 'public', 'private', 'local', 'in-house', 'first-party',
+    'generic', 'shared', 'common', 'legacy', 'rest', 'restful', 'graphql', 'grpc',
+    'soap', 'rpc', 'http', 'https', 'json', 'xml',
+]);
+/** Locality qualifiers that, when they immediately precede a `<Service> API`,
+ *  mark it as first-party ("internal Payments API") — negative evidence for an
+ *  EXTERNAL-API surface signal. Only unambiguously-internal words: "external"
+ *  is deliberately absent (an external API IS external). */
+const INTERNAL_DESCRIPTORS = new Set(['internal', 'in-house', 'local', 'first-party', 'private']);
+/** A capitalized compound modifier ("Resolver-only", "Read-only", "E-commerce"
+ *  — lowercase letter right after the hyphen) is an adjective phrase, not a
+ *  service name. Real hyphenated services capitalize the second segment
+ *  ("T-Mobile"). */
+const COMPOUND_MODIFIER_RE = /^[A-Z][A-Za-z0-9]*-[a-z]/;
+const URL_TOKEN_RE = /^[([<"'`]*[a-z][a-z0-9+.-]*:\/\//i;
+const LOCAL_URL_RE = /^[([<"'`]*[a-z][a-z0-9+.-]*:\/\/(?:localhost|127(?:\.\d{1,3}){1,3}|0\.0\.0\.0|\[::1\])(?=[:/?#]|$)/i;
+/** A scheme-less token that STARTS with a dotted hostname whose final label is
+ *  alphabetic ("api.stripe.com/v1") — a bare external API host. A first-party
+ *  route path ("src/app/api/…") has no dotted head, and an IP host ("127.1/…")
+ *  has a numeric final label, so neither matches (#2365 review F2). */
+const DOMAIN_HEAD_RE = /^[([<"'`]*(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}(?=[:/?#]|$)/i;
+/** Mask whitespace-delimited tokens with an interior `/` — file paths, framework
+ *  routes (`src/app/api/...`), URLs. They are references, not integration prose
+ *  (#2365 root cause 2: `/` counted as a word boundary, so first-party route
+ *  paths matched the noun vocabulary). Two carve-outs keep genuine signals:
+ *   - a slashed token whose segments are ALL noun-vocabulary words ("API/SDK",
+ *     "REST/GraphQL") is prose shorthand, not a path — left unmasked;
+ *   - a non-local URL is masked, but noun terms inside it are collected as
+ *     compound-rule evidence (the old detector caught "connect to
+ *     https://api.stripe.com" via the `api` segment; losing that would
+ *     fail-open). */
+function scanLineTokens(line, nounRe, nounSet) {
+    const urlNouns = [];
+    let masked = '';
+    const tokenRe = /\S+/g;
+    let last = 0;
+    let m;
+    while ((m = tokenRe.exec(line)) !== null) {
+        const rawTok = m[0];
+        masked += line.slice(last, m.index);
+        last = m.index + rawTok.length;
+        // Peel trailing clause-boundary punctuation off the token and keep it
+        // LITERAL in `masked` — masking it away would erase a clause split and pair
+        // unrelated verb/noun across it (#2365 review F6: "…example.com, document…").
+        // A backward char scan (not a `[…]+$` regex) keeps this linear.
+        let trailLen = 0;
+        while (trailLen < rawTok.length && CLAUSE_BOUNDARY_CHARS.has(rawTok[rawTok.length - 1 - trailLen])) {
+            trailLen++;
+        }
+        const trail = trailLen ? rawTok.slice(rawTok.length - trailLen) : '';
+        const tok = trailLen ? rawTok.slice(0, rawTok.length - trailLen) : rawTok;
+        if (!/\S[\\/]\S/.test(tok)) {
+            masked += rawTok;
+            continue;
+        }
+        const segments = tok.split(/[\\/]/).map((s) => s.replace(/[^A-Za-z0-9]/g, ''));
+        if (segments.every((s) => s.length > 0 && (nounSet.has(s.toLowerCase()) || /^v\d+$/i.test(s))) &&
+            segments.some((s) => nounSet.has(s.toLowerCase()))) {
+            masked += rawTok; // "API/SDK", "API/v2" — noun shorthand, not a path
+            continue;
+        }
+        // A scheme URL or a bare external hostname is an external dependency
+        // reference: mask it from prose but keep it as compound-rule evidence. A
+        // first-party route path has neither a scheme nor a dotted host, so it is
+        // masked WITHOUT contributing nouns (#2365 root cause 2).
+        // A non-local URL that NAMES an API vocabulary word ("api.stripe.com/v1")
+        // is external-dependency evidence, so its vocab nouns feed the compound
+        // rule. We deliberately do NOT treat every path-bearing URL as an endpoint:
+        // that fired on ordinary asset/link URLs ("…/theme.css", "…?next=/x") and
+        // recreated routine UI-phase false positives (#2365 review). A bare external
+        // host that names no vocabulary word ("graph.microsoft.com") and is not
+        // written as "<Service> API" is therefore a DOCUMENTED fail-open limitation.
+        const isSchemeUrl = URL_TOKEN_RE.test(tok) && !LOCAL_URL_RE.test(tok);
+        const isDomainUrl = !URL_TOKEN_RE.test(tok) && DOMAIN_HEAD_RE.test(tok);
+        if (nounRe && (isSchemeUrl || isDomainUrl)) {
+            for (const f of collectTermMatches(nounRe, tok)) {
+                urlNouns.push({ term: f.term, start: m.index, end: m.index + tok.length });
+            }
+        }
+        masked += ' '.repeat(tok.length) + trail;
+    }
+    masked += line.slice(last);
+    return { masked, urlNouns };
+}
+/** All term matches in a clause, with offsets. `re` must be global with the
+ *  term in group 2 and a consumed leading boundary in group 1. */
+function collectTermMatches(re, clause) {
+    const out = [];
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(clause)) !== null) {
+        const start = m.index + (m[1] || '').length;
+        out.push({ term: (m[2] || '').toLowerCase(), start, end: start + (m[2] || '').length });
+        if (m[0].length === 0)
+            re.lastIndex++;
+    }
+    return out;
+}
+/** Split a line into clause segments, keeping each segment's start offset so
+ *  line-level spans (masked URL tokens) can be mapped into their clause. */
+function splitClauses(masked) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i <= masked.length; i++) {
+        if (i === masked.length || CLAUSE_BOUNDARY_RE.test(masked[i])) {
+            out.push({ text: masked.slice(start, i), start });
+            start = i + 1;
+        }
+    }
+    return out;
+}
 /**
  * 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.
+ * FAIL-CLOSED: it leans toward detecting, because a false positive is dismissed
+ * by a one-line COVERAGE.md declaration while a false negative silently slips a
+ * real external-API phase past a blocking gate. It fires when EITHER:
+ *   (a) an integration VERB and an API NOUN share one CLAUSE ("integrate the
+ *       Stripe API", "Connect … to api.stripe.com") — the clause boundary is the
+ *       whole relationship test, so verb/noun in DIFFERENT clauses do not pair
+ *       (#2365 acceptance #2). There is NO cross-clause binding: a service named
+ *       only in a clause separate from its API noun is a documented limitation.
+ *   (b) an explicit `<Service> API|SDK|REST|GraphQL` surface names a service
+ *       that is not a stopword, a locality/protocol descriptor, a compound
+ *       modifier, or first-party-qualified ("Stripe API", "Spotify SDK").
+ *
+ * Fenced code, inline code spans, and path-shaped tokens are excluded before
+ * matching. A package-shaped inline span (`@stripe/stripe-js`, `stripe-sdk`)
+ * and a URL that NAMES an API vocab word ("api.stripe.com/v1") still count as
+ * noun/dependency evidence; a bare host that names none does not.
  *
  * Non-string inputs degrade to `{ detected: false }` without throwing.
  */
@@ -199,46 +374,137 @@ function detectApiIntegration(text, terms) {
     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}`;
+    const hasCompoundTerms = effective.verbs.length > 0 && effective.nouns.length > 0;
+    // Trailing boundary is a LOOKAHEAD (not consumed) so back-to-back terms
+    // separated by one boundary char are both found.
+    const verbRe = hasCompoundTerms
+        ? new RegExp('(^|[^a-zA-Z0-9])(' + effective.verbs.map(escapeRegex).join('|') + ')(?=[^a-zA-Z0-9]|$)', 'gi')
+        : null;
+    const nounRe = hasCompoundTerms
+        ? new RegExp('(^|[^a-zA-Z0-9])(' + effective.nouns.map(escapeRegex).join('|') + ')(?=[^a-zA-Z0-9]|$)', 'gi')
+        : null;
+    const surfaceRe = new RegExp(SERVICE_SURFACE_API_RE.source, 'g');
+    const nounSet = new Set(effective.nouns);
+    const emitPair = (vTerm, nTerm, snippetLine) => {
+        const key = `${vTerm}+${nTerm}`;
         if (seen.has(key))
-            continue;
+            return;
         seen.add(key);
-        signals.push({ verb: '(surface)', noun, snippet: makeSnippet(line, m[1]) });
+        signals.push({ verb: vTerm, noun: nTerm, snippet: makeSnippet(snippetLine, nTerm) });
+    };
+    for (const rawLine of lines) {
+        // Inline code spans are code, not prose — mask them (length-preserving so
+        // offsets keep lining up), but keep package-shaped span content as noun
+        // evidence (#2365 review FN-4: `stripe-sdk` names a dependency).
+        const inlineSpans = (0, markdown_sectionizer_cjs_1.scanInlineCodeSpans)(rawLine);
+        let line = rawLine;
+        const spanNouns = [];
+        for (const s of inlineSpans) {
+            line = line.slice(0, s.start) + ' '.repeat(s.end - s.start) + line.slice(s.end);
+            const content = s.content.trim();
+            if (content.length === 0 || /\s/.test(content))
+                continue;
+            const segs = content.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+            if (segs.length < 2)
+                continue; // a bare `api` span is a code identifier
+            const hit = segs.find((seg) => nounSet.has(seg));
+            if (hit)
+                spanNouns.push({ term: hit, start: s.start, end: s.end });
+        }
+        // Path-shaped tokens (routes, file names, URLs) are references, not prose.
+        const { masked, urlNouns } = scanLineTokens(line, nounRe, nounSet);
+        const clauses = splitClauses(masked);
+        const extraNouns = urlNouns.concat(spanNouns);
+        // (a) compound verb+noun — SAME CLAUSE ONLY. There is no word-gap cap (a cap
+        // cannot tell a long genuine clause from a long internal one) and no
+        // cross-clause binding (see the note by CLAUSE_BOUNDARY_CHARS): the clause
+        // boundary is the whole relationship test. Nouns are NOT filtered on
+        // "internal" qualification here — "integrate the internal API" is a
+        // fail-closed positive; the declaration dismisses it if wrong.
+        if (verbRe && nounRe) {
+            for (const clause of clauses) {
+                const verbs = collectTermMatches(verbRe, clause.text);
+                if (verbs.length === 0)
+                    continue;
+                const nouns = collectTermMatches(nounRe, clause.text);
+                const nounTerms = new Set(nouns.map((t) => t.term));
+                for (const u of extraNouns) {
+                    if (u.start >= clause.start && u.end <= clause.start + clause.text.length) {
+                        nounTerms.add(u.term);
+                    }
+                }
+                if (nounTerms.size === 0)
+                    continue;
+                for (const vTerm of new Set(verbs.map((t) => t.term))) {
+                    for (const nTerm of nounTerms)
+                        emitPair(vTerm, nTerm, rawLine);
+                }
+            }
+        }
+        // (b) explicit <Service> API|SDK|REST|GraphQL surface — scan every candidate
+        // in every clause (a rejected first candidate must not shadow a later
+        // genuine service; #2365 review C-1).
+        for (const clause of clauses) {
+            surfaceRe.lastIndex = 0;
+            let m;
+            while ((m = surfaceRe.exec(clause.text)) !== null) {
+                const svc = m[1] || '';
+                const svcLower = svc.toLowerCase();
+                // Reject capitalized sentence starters ("The API"), locality/protocol
+                // descriptors ("Internal API", "REST API"), compound modifiers
+                // ("Resolver-only API"), and services qualified first-party
+                // ("internal Payments API"). A real vendor name is none of these.
+                if (SERVICE_STOPWORDS.has(svcLower))
+                    continue;
+                if (SURFACE_DESCRIPTOR_WORDS.has(svcLower))
+                    continue;
+                if (COMPOUND_MODIFIER_RE.test(svc))
+                    continue;
+                if (isInternallyQualified(masked, clause.start + m.index))
+                    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(rawLine, svc) });
+            }
+        }
     }
     return { detected: signals.length > 0, signals, terms: effective };
 }
+/** True when the word IMMEDIATELY ADJACENT before `offset` is a locality
+ *  descriptor ("internal Payments API") — first-party qualification is negative
+ *  evidence for an EXTERNAL-API signal. Only plain spaces/tabs may separate the
+ *  descriptor from the service: any intervening punctuation means the descriptor
+ *  belongs to a prior clause/sentence and must NOT qualify ("The cache is
+ *  private. Stripe API …" — `private` is a different sentence; #2365 review).
+ *  Looks back through a BOUNDED window, not the whole prefix, to stay linear. */
+const QUALIFIER_LOOKBACK = 24; // longest descriptor ("first-party") + separators
+function isInternallyQualified(masked, offset) {
+    const from = offset > QUALIFIER_LOOKBACK ? offset - QUALIFIER_LOOKBACK : 0;
+    const window = masked.slice(from, offset);
+    // Only whitespace and markdown emphasis/wrapper markers (`*_~\`) may separate
+    // the descriptor from the service, so "The **internal** Payments API" still
+    // qualifies — but NOT a clause/sentence boundary, so "…is private. Stripe API"
+    // does not (the descriptor is a different sentence; #2365 review).
+    const m = /([A-Za-z0-9'-]+)[\s*_~`]*$/.exec(window);
+    if (!m)
+        return false;
+    // A word truncated by the window start is not a descriptor match (its real
+    // start lies before the window) — fail toward detection.
+    if (from > 0 && m.index === 0 && /[A-Za-z0-9'-]/.test(masked[from - 1]))
+        return false;
+    return INTERNAL_DESCRIPTORS.has(m[1].toLowerCase());
+}
+/** Matches a declaration line such as
+ *  `No external API integration: <reason>` (also `**bold**` and em-dash
+ *  separators). The reason is REQUIRED — a bare declaration does not parse.
+ *  Deliberately NOT matched: blockquoted lines (`> No external …` is quoted
+ *  text, not a declaration) and anything inside fenced code or HTML comments
+ *  (both stripped before the scan; #2365 review C-3). */
+const NO_INTEGRATION_DECLARATION_RE = /^\s*(?:\*\*)?no external api integration(?:\*\*)?\s*(?:[:—–-]|--)\s*(\S[^\n]*)$/im;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
 const VALID_DECISIONS = new Set(['INTEGRATE', 'OPT-OUT']);
 /**
  * Parse a coverage matrix from COVERAGE.md. Accepts two bijective formats:
@@ -258,10 +524,17 @@ const VALID_DECISIONS = new Set(['INTEGRATE', 'OPT-OUT']);
  * `{ rows: [], errors: [], format: 'none' }` for empty/non-matrix input.
  */
 function parseCoverageMatrix(text) {
-    const out = { rows: [], errors: [], format: 'none' };
+    const out = { rows: [], errors: [], format: 'none', declaration: null };
     if (typeof text !== 'string')
         return out;
     const src = text.replace(/\r\n/g, '\n');
+    // #2365 acceptance #5: a "no external API integration" declaration. Scanned
+    // on fence-stripped, comment-stripped text so an example inside a code block
+    // or an HTML comment does not count.
+    const declMatch = NO_INTEGRATION_DECLARATION_RE.exec((0, markdown_sectionizer_cjs_1.stripFencedCode)(src).text.replace(HTML_COMMENT_RE, ''));
+    if (declMatch) {
+        out.declaration = { none: true, reason: (declMatch[1] || '').trim() };
+    }
     // (1) fenced ```coverage JSON block takes precedence if present.
     // Case-insensitive info string (```coverage and ```Coverage are both legal CommonMark).
     const fenceBody = (0, markdown_sectionizer_cjs_1.extractFencedBlock)(src, 'coverage');
@@ -366,6 +639,26 @@ function validateCoverageMatrix(text) {
     const parsed = parseCoverageMatrix(text);
     const errors = [...parsed.errors];
     const rows = parsed.rows;
+    // #2365 acceptance #5: a reasoned no-integration declaration with no rows
+    // satisfies the gate. A declaration ALONGSIDE rows is contradictory — the
+    // file must say one thing.
+    if (parsed.declaration) {
+        if (rows.length > 0) {
+            errors.push('declares "no external API integration" but also contains coverage rows — remove the declaration or the rows');
+        }
+        else {
+            if (parsed.declaration.reason.length > REASON_MAX_LEN) {
+                errors.push(`declaration reason exceeds ${REASON_MAX_LEN} chars`);
+            }
+            const valid = errors.length === 0;
+            return {
+                valid,
+                errors,
+                counts: { surface: 0, integrate: 0, optout: 0 },
+                none_declared: valid,
+            };
+        }
+    }
     if (rows.length === 0) {
         if (errors.length === 0)
             errors.push('matrix is empty — no capabilities enumerated');