@encore-os/eos-spec 0.16.0 → 0.18.0

package/dist/lib/rtm-scorecard.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The FR/SC Requirements-Traceability-Matrix (RTM) scorecard — a NON-VACUOUS coverage
+ * derivation folded into the engine from encoreos's repo-local `scripts/specs/verify-acs.mjs`
+ * (issue #79). It answers "how much of this spec's Definition of Done (its functional
+ * requirements FR-N and success criteria SC-N) is actually proven?" — where "proven" is
+ * defined so a coverage-free corpus cannot read 100% (the vacuity guard):
+ *
+ *   - an **FR** is verified iff it has ≥1 covering AC and every covering AC is verified,
+ *     OR it carries its own proof. An FR with zero covering ACs and no own-proof is NOT
+ *     verified — that is the property the vacuity guard pins.
+ *   - an **SC** is met iff it references ≥1 AC, at least one referenced AC is verified,
+ *     AND every NFR it gates is green. An SC that references no AC is NOT met.
+ *
+ * PURE (fs-free): it reads a spec's body text + already-parsed `acceptance_criteria`, so it
+ * sits on the `/pure` graph and a browser bundle (Spec Studio) can compute the scorecard
+ * client-side. The corpus walk + file IO that feed it stay in the command layer. Trace edges
+ * (AC→FR via `fr_refs`, SC→AC/NFR via reference parens) mirror the engine's existing model.
+ */
+import { matchBodyRequirement } from './body-requirements.js';
+export { matchBodyRequirement };
+/** An AC block the scorecard reasons over: its id, terminal status, and the FR/NFR ids it
+ *  covers (from frontmatter `fr_refs` / `nfr_refs`). Sourced from the parsed frontmatter. */
+export type ScorecardAcBlock = {
+    id: string;
+    status?: string;
+    fr_refs?: string[];
+    nfr_refs?: string[];
+};
+/** A body requirement/NFR item (`- **FR-1** [status] …`). */
+export type ScorecardRequirementItem = {
+    id: string;
+    status: string;
+};
+/** A success criterion parsed from the body, with the ACs/NFRs it traces to. */
+export type SuccessCriterionItem = {
+    id: string;
+    status: string;
+    ac_refs: string[];
+    nfr_refs: string[];
+};
+/** Proof accumulated from a verification run: AC/FR ids proven by a passing backing test.
+ *  Empty ⇒ the scorecard reflects on-disk statuses only (still non-vacuous). */
+export type ScorecardProof = {
+    provenAcIds?: Set<string>;
+    provenFrIds?: Set<string>;
+};
+export type FrVerdict = {
+    verified: boolean;
+    reason: string;
+    coveringAcs: string[];
+};
+export type ScVerdictResult = {
+    met: boolean;
+    reason: string;
+};
+export type Scorecard = {
+    fr: {
+        total: number;
+        verified: number;
+        rows: Array<{
+            id: string;
+        } & FrVerdict>;
+    };
+    sc: {
+        total: number;
+        met: number;
+        rows: Array<{
+            id: string;
+        } & ScVerdictResult>;
+    };
+};
+/** Parse one body line into a success criterion `{ id, status, ac_refs, nfr_refs }`, or null.
+ *  SC lines carry trailing reference parens — `(US-3, AC-6)`, `(US-1, FR-1, NFR-1)` — from
+ *  which the AC and NFR ids are scraped (dedup'd). */
+export declare function matchSuccessCriterion(line: string): SuccessCriterionItem | null;
+/** Match a body NFR item (`- **NFR-perf-1** [status] …`) — the gates an SC verdict checks. */
+export declare function matchNfrItem(line: string): ScorecardRequirementItem | null;
+/** Invert the AC→FR trace edges (each AC's `fr_refs`) into `FR id → [covering AC ids]`. */
+export declare function coveringAcsByFr(acBlocks: ScorecardAcBlock[]): Map<string, string[]>;
+/** True if an AC is verified — status `verified` on disk OR proven in this run. */
+export declare function isAcVerified(acId: string, acStatusById: Map<string, string | undefined>, provenAcIds: Set<string>): boolean;
+/**
+ * The NON-VACUOUS FR verdict. An FR counts verified iff (a) it has ≥1 covering AC and every
+ * covering AC is verified, or (b) the FR itself is proven. Zero covering ACs and no own-proof
+ * ⇒ NOT verified (the vacuity guard: a coverage-free corpus cannot read 100%).
+ */
+export declare function frVerdict(opts: {
+    coveringAcs?: string[];
+    acStatusById: Map<string, string | undefined>;
+    provenAcIds: Set<string>;
+    frProven?: boolean;
+    frVerifiedOnDisk?: boolean;
+}): FrVerdict;
+/**
+ * The NON-VACUOUS SC verdict. An SC counts met iff (a) it references ≥1 AC and at least one
+ * referenced AC is verified, and (b) every NFR it gates is green. A missing NFR (not in the
+ * spec) is ungreen — a dangling gate cannot be assumed satisfied. An SC referencing no AC is
+ * NOT met.
+ */
+export declare function scVerdict(sc: SuccessCriterionItem, opts: {
+    acStatusById: Map<string, string | undefined>;
+    provenAcIds: Set<string>;
+    nfrVerifiedById: Map<string, boolean>;
+}): ScVerdictResult;
+/** The items one spec's scorecard reasons over (body-parsed FR/SC/NFR + frontmatter AC blocks). */
+export type ScorecardItems = {
+    frItems: ScorecardRequirementItem[];
+    acBlocks: ScorecardAcBlock[];
+    scItems: SuccessCriterionItem[];
+    nfrItems: ScorecardRequirementItem[];
+};
+/**
+ * Collect the scorecard items for one spec from its BODY text (FR/US/NFR/SC list lines) and
+ * its already-parsed `acceptance_criteria` frontmatter (AC id/status/fr_refs/nfr_refs). Pure —
+ * the caller supplies the body (frontmatter-stripped) and the raw AC array. US items are not
+ * scored (they trace via ACs) so they are not returned.
+ */
+export declare function collectScorecardItems(bodyText: string, rawAcs: unknown): ScorecardItems;
+/** Derive the whole FR/SC scorecard for one spec — the single non-vacuous entry point. */
+export declare function deriveScorecard(spec: Partial<ScorecardItems>, proof?: ScorecardProof): Scorecard;
+/** Advisory coverage ratchet floors (warn-level, NEVER fatal): the fraction of FRs that clear
+ *  the non-vacuous bar and of SCs that are met. Conservative defaults; a consumer overrides via
+ *  `rtm.ratchets` in `specs/config.yaml`. Kept advisory so a young/low-coverage corpus stays
+ *  green while a real regression below the floor still surfaces. */
+export declare const COVERAGE_RATCHET_FLOORS: Record<string, number>;
+/** The resolved RTM config: whether the scorecard is enabled + the effective ratchet floors.
+ *  `resolveRtm` duck-types the config (no fs-bound `SpecConfig` import) so this stays pure. */
+export type RtmConfig = {
+    enabled: boolean;
+    ratchets: Record<string, number>;
+};
+/** Resolve the opt-in RTM scorecard config; defaults to disabled + the built-in floors, so a
+ *  repo without an `rtm:` block (or with `enabled` falsy) gets no scorecard. */
+export declare function resolveRtm(config: {
+    rtm?: {
+        enabled?: boolean;
+        ratchets?: Record<string, number>;
+    };
+} | null | undefined): RtmConfig;
+/** Compare measured coverage (`{ frVerifiedPct, scMetPct, … }`, each 0–1) against the advisory
+ *  floors. Returns the breaches (empty ⇒ none). Pure — the caller decides whether to print/warn. */
+export declare function checkCoverageRatchets(measured: Record<string, number>, floors?: Record<string, number>): Array<{
+    metric: string;
+    floor: number;
+    value: number;
+}>;

package/dist/lib/rtm-scorecard.js

@@ -0,0 +1,194 @@
+/**
+ * The FR/SC Requirements-Traceability-Matrix (RTM) scorecard — a NON-VACUOUS coverage
+ * derivation folded into the engine from encoreos's repo-local `scripts/specs/verify-acs.mjs`
+ * (issue #79). It answers "how much of this spec's Definition of Done (its functional
+ * requirements FR-N and success criteria SC-N) is actually proven?" — where "proven" is
+ * defined so a coverage-free corpus cannot read 100% (the vacuity guard):
+ *
+ *   - an **FR** is verified iff it has ≥1 covering AC and every covering AC is verified,
+ *     OR it carries its own proof. An FR with zero covering ACs and no own-proof is NOT
+ *     verified — that is the property the vacuity guard pins.
+ *   - an **SC** is met iff it references ≥1 AC, at least one referenced AC is verified,
+ *     AND every NFR it gates is green. An SC that references no AC is NOT met.
+ *
+ * PURE (fs-free): it reads a spec's body text + already-parsed `acceptance_criteria`, so it
+ * sits on the `/pure` graph and a browser bundle (Spec Studio) can compute the scorecard
+ * client-side. The corpus walk + file IO that feed it stay in the command layer. Trace edges
+ * (AC→FR via `fr_refs`, SC→AC/NFR via reference parens) mirror the engine's existing model.
+ */
+import { matchBodyRequirement } from './body-requirements.js';
+// Re-export the body-requirement parser for backward compatibility (and convenience).
+export { matchBodyRequirement };
+/** Parse one body line into a success criterion `{ id, status, ac_refs, nfr_refs }`, or null.
+ *  SC lines carry trailing reference parens — `(US-3, AC-6)`, `(US-1, FR-1, NFR-1)` — from
+ *  which the AC and NFR ids are scraped (dedup'd). */
+export function matchSuccessCriterion(line) {
+    const m = /^\s*-\s+\*\*(SC-\d+(?:\.\d+)*)\b[^*\n]*\*\*\s*(?:\[([a-z_]+)\])?\s*(.*)$/.exec(line);
+    if (!m)
+        return null;
+    const tail = m[3] ?? '';
+    return {
+        id: m[1],
+        status: m[2] ?? 'planned',
+        ac_refs: [...new Set(tail.match(/\bAC-\d+(?:\.\d+)*/g) ?? [])],
+        nfr_refs: [...new Set(tail.match(/\bNFR(?:-[a-z]+)?-\d+(?:\.\d+)*/g) ?? [])],
+    };
+}
+/** Match a body NFR item (`- **NFR-perf-1** [status] …`) — the gates an SC verdict checks. */
+export function matchNfrItem(line) {
+    const m = /^\s*-\s+\*{0,2}(NFR(?:-[a-z]+)?-\d+(?:\.\d+)*)\*{0,2}(?:\s+\[([a-z_]+)\])?/.exec(line);
+    return m ? { id: m[1], status: m[2] ?? 'planned' } : null;
+}
+/** Invert the AC→FR trace edges (each AC's `fr_refs`) into `FR id → [covering AC ids]`. */
+export function coveringAcsByFr(acBlocks) {
+    const map = new Map();
+    for (const ac of acBlocks) {
+        for (const fr of ac.fr_refs ?? []) {
+            if (!map.has(fr))
+                map.set(fr, []);
+            map.get(fr).push(ac.id);
+        }
+    }
+    return map;
+}
+/** True if an AC is verified — status `verified` on disk OR proven in this run. */
+export function isAcVerified(acId, acStatusById, provenAcIds) {
+    return acStatusById.get(acId) === 'verified' || provenAcIds.has(acId);
+}
+/**
+ * The NON-VACUOUS FR verdict. An FR counts verified iff (a) it has ≥1 covering AC and every
+ * covering AC is verified, or (b) the FR itself is proven. Zero covering ACs and no own-proof
+ * ⇒ NOT verified (the vacuity guard: a coverage-free corpus cannot read 100%).
+ */
+export function frVerdict(opts) {
+    const { coveringAcs = [], acStatusById, provenAcIds, frProven = false, frVerifiedOnDisk = false } = opts;
+    if (frProven || frVerifiedOnDisk) {
+        return { verified: true, reason: 'own @verifies proof', coveringAcs };
+    }
+    if (coveringAcs.length === 0) {
+        return { verified: false, reason: 'no covering AC and no own proof', coveringAcs };
+    }
+    const unverified = coveringAcs.filter((ac) => !isAcVerified(ac, acStatusById, provenAcIds));
+    if (unverified.length === 0) {
+        return { verified: true, reason: `${coveringAcs.length} covering AC(s) all verified`, coveringAcs };
+    }
+    return { verified: false, reason: `covering AC(s) not yet verified: ${unverified.join(', ')}`, coveringAcs };
+}
+/**
+ * The NON-VACUOUS SC verdict. An SC counts met iff (a) it references ≥1 AC and at least one
+ * referenced AC is verified, and (b) every NFR it gates is green. A missing NFR (not in the
+ * spec) is ungreen — a dangling gate cannot be assumed satisfied. An SC referencing no AC is
+ * NOT met.
+ */
+export function scVerdict(sc, opts) {
+    const { acStatusById, provenAcIds, nfrVerifiedById } = opts;
+    const acRefs = sc.ac_refs ?? [];
+    const nfrRefs = sc.nfr_refs ?? [];
+    if (acRefs.length === 0) {
+        return { met: false, reason: 'references no AC (cannot be proven)' };
+    }
+    const verifiedAcs = acRefs.filter((ac) => isAcVerified(ac, acStatusById, provenAcIds));
+    if (verifiedAcs.length === 0) {
+        return { met: false, reason: `no referenced AC is verified (${acRefs.join(', ')})` };
+    }
+    const ungreenNfrs = nfrRefs.filter((nfr) => nfrVerifiedById.get(nfr) !== true);
+    if (ungreenNfrs.length > 0) {
+        return { met: false, reason: `NFR gate(s) not green: ${ungreenNfrs.join(', ')}` };
+    }
+    return { met: true, reason: `${verifiedAcs.length}/${acRefs.length} referenced AC(s) verified, NFR gates green` };
+}
+/**
+ * Collect the scorecard items for one spec from its BODY text (FR/US/NFR/SC list lines) and
+ * its already-parsed `acceptance_criteria` frontmatter (AC id/status/fr_refs/nfr_refs). Pure —
+ * the caller supplies the body (frontmatter-stripped) and the raw AC array. US items are not
+ * scored (they trace via ACs) so they are not returned.
+ */
+export function collectScorecardItems(bodyText, rawAcs) {
+    const acBlocks = Array.isArray(rawAcs)
+        ? rawAcs
+            .filter((e) => !!e && typeof e === 'object')
+            .map((e) => ({
+            id: typeof e.id === 'string' ? e.id : '',
+            status: typeof e.status === 'string' ? e.status : undefined,
+            fr_refs: coerceIdList(e.fr_refs),
+            nfr_refs: coerceIdList(e.nfr_refs),
+        }))
+            .filter((a) => a.id !== '')
+        : [];
+    const frItems = [];
+    const nfrItems = [];
+    const scItems = [];
+    for (const line of bodyText.split('\n')) {
+        const req = matchBodyRequirement(line);
+        if (req) {
+            if (req.kind === 'FR')
+                frItems.push({ id: req.id, status: req.status });
+            continue; // US items are traced via ACs, not scored directly
+        }
+        const nfr = matchNfrItem(line);
+        if (nfr) {
+            nfrItems.push(nfr);
+            continue;
+        }
+        const sc = matchSuccessCriterion(line);
+        if (sc)
+            scItems.push(sc);
+    }
+    return { frItems, acBlocks, scItems, nfrItems };
+}
+/** Coerce a frontmatter ref field (`fr_refs`/`nfr_refs`) to a string id list — accepts a YAML
+ *  array of strings or a single string; anything else ⇒ []. */
+function coerceIdList(v) {
+    if (typeof v === 'string')
+        return v.trim() === '' ? [] : [v.trim()];
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim());
+    return [];
+}
+/** Derive the whole FR/SC scorecard for one spec — the single non-vacuous entry point. */
+export function deriveScorecard(spec, proof = {}) {
+    const { frItems = [], acBlocks = [], scItems = [], nfrItems = [] } = spec;
+    const provenAcIds = proof.provenAcIds ?? new Set();
+    const provenFrIds = proof.provenFrIds ?? new Set();
+    const acStatusById = new Map(acBlocks.map((a) => [a.id, a.status]));
+    const nfrVerifiedById = new Map(nfrItems.map((n) => [n.id, n.status === 'verified']));
+    const coveringByFr = coveringAcsByFr(acBlocks);
+    const frRows = frItems.map((fr) => ({
+        id: fr.id,
+        ...frVerdict({
+            coveringAcs: coveringByFr.get(fr.id) ?? [],
+            acStatusById,
+            provenAcIds,
+            frProven: provenFrIds.has(fr.id),
+            frVerifiedOnDisk: fr.status === 'verified',
+        }),
+    }));
+    const scRows = scItems.map((sc) => ({ id: sc.id, ...scVerdict(sc, { acStatusById, provenAcIds, nfrVerifiedById }) }));
+    return {
+        fr: { total: frRows.length, verified: frRows.filter((r) => r.verified).length, rows: frRows },
+        sc: { total: scRows.length, met: scRows.filter((r) => r.met).length, rows: scRows },
+    };
+}
+/** Advisory coverage ratchet floors (warn-level, NEVER fatal): the fraction of FRs that clear
+ *  the non-vacuous bar and of SCs that are met. Conservative defaults; a consumer overrides via
+ *  `rtm.ratchets` in `specs/config.yaml`. Kept advisory so a young/low-coverage corpus stays
+ *  green while a real regression below the floor still surfaces. */
+export const COVERAGE_RATCHET_FLOORS = { frVerifiedPct: 0, scMetPct: 0 };
+/** Resolve the opt-in RTM scorecard config; defaults to disabled + the built-in floors, so a
+ *  repo without an `rtm:` block (or with `enabled` falsy) gets no scorecard. */
+export function resolveRtm(config) {
+    const rtm = config?.rtm;
+    return { enabled: rtm?.enabled === true, ratchets: rtm?.ratchets ?? COVERAGE_RATCHET_FLOORS };
+}
+/** Compare measured coverage (`{ frVerifiedPct, scMetPct, … }`, each 0–1) against the advisory
+ *  floors. Returns the breaches (empty ⇒ none). Pure — the caller decides whether to print/warn. */
+export function checkCoverageRatchets(measured, floors = COVERAGE_RATCHET_FLOORS) {
+    const breaches = [];
+    for (const [metric, floor] of Object.entries(floors)) {
+        const value = measured[metric];
+        if (typeof value === 'number' && value < floor)
+            breaches.push({ metric, floor, value });
+    }
+    return breaches;
+}
+//# sourceMappingURL=rtm-scorecard.js.map

package/dist/lib/rtm-scorecard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rtm-scorecard.js","sourceRoot":"","sources":["../../src/lib/rtm-scorecard.ts"],"names":[],"mappings":"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"}

package/dist/lib/spec-pure.d.ts

@@ -8,6 +8,22 @@ export declare const SPEC_ID_GRAMMAR: {
     readonly pattern: "<core>(-[A-Z]{1,4})?-<n>(.<n>)?(-(EN-<n>|E<n>|P<n>(.<n>)?(-EN-<n>)?))?";
     readonly caseInsensitive: true;
 };
+/**
+ * Remove regions that legitimately QUOTE compliance-sounding words as examples,
+ * so the keyword heuristic in {@link detectSensitive} reads only load-bearing
+ * prose. Strips, per line: fenced code blocks (``` … ``` / ~~~ … ~~~), a
+ * `## Examples` heading section — an EXACT `Examples`/`Example` heading title only
+ * (so `## Examples of Regulated Data` is a normal heading, its body left as
+ * scannable prose) — down to the next same-or-higher heading, and Gherkin step
+ * lines. `Scenario:` / `Example(s):` / `Given` / `When` / `Then` openers strip
+ * unconditionally; `And` / `But` strip ONLY when the immediately preceding
+ * non-blank line (no intervening blank line) was itself a Gherkin step/opener —
+ * a standalone `And`/`But` prose line (e.g. a paragraph continuation) is left in
+ * place. Pure string transform — no fs, stays on the `/pure` graph. Callers apply
+ * it to the keyword-match INPUT only; opt-in/opt-out markers are still read from
+ * the raw text.
+ */
+export declare function stripExampleRegions(text: string): string;
 /** True when a generated test source has ≥1 ACTIVE `test(` block (not `test.fixme`/
  *  `test.describe`) and is not an AC-less placeholder. Pure (operates on source text). */
 export declare function hasActiveGeneratedTestSource(source: string): boolean;
@@ -88,6 +104,28 @@ export declare function declaredSpecId(declaredId: string | null | undefined, co
  * Returns the resolved spec id, or null when the file is not a primary spec.
  */
 export declare function resolveSpecFileId(core: string, filename: string, declaredId?: string | null): string | null;
+/**
+ * True when an on-disk filename PARSES to a well-formed primary-spec id yet the corpus
+ * loader would silently DROP it ({@link resolveSpecFileId} → null) for a reason a
+ * frontmatter `id:` could rescue — a reserved lifecycle word (REVIEW / ANALYSIS /
+ * CLARIFICATION …) landed inside a real feature slug and no `id:` disambiguates it. This
+ * is the silent-authoring-drop class issue #76 surfaces: the file reads as spec X to a
+ * human but never reaches spec-index.json / navigator / reconcile / recall.
+ *
+ * Deliberately EXCLUDES bona-fide sibling artifacts that legitimately carry a parent id
+ * and are SUPPOSED to be non-primary, so the surfacer stays quiet on a healthy corpus:
+ *   - dedicated CONTEXT/CLARIFICATION/ENHANCEMENTS/EXPANSION files ({@link isDedicatedArtifactFile}),
+ *   - `{ID}-PHASE…` lifecycle files ({@link isPhaseLifecycleFile}),
+ *   - descriptor-suffix artifacts (`-TASKS`/`-PLAN`/`-RESEARCH`/… — {@link DERIVATIVE_DESCRIPTOR_RE}),
+ *   - and a LONE terminal descriptor (`{ID}-REVIEW`, `{ID}-ANALYSIS`): only files with real
+ *     slug content AFTER the id (≥2 slug words) are flagged, i.e. the reserved word is
+ *     embedded in a feature name (`{ID}-compliance-review-workflow`), not the whole slug.
+ *
+ * The residue is exactly the case the mint-time guard (spec-id-guard → {@link resolveSpecFileId})
+ * blocks on `create`/`promote`, made visible for files already on disk. Pure (fs-free); the
+ * fs walk that feeds it lives in specs.ts `findSkippedSpecFiles`.
+ */
+export declare function isSilentlySkippedSpecFile(core: string, filename: string, declaredId?: string | null): boolean;
 /** The skip rules `collectSpecsFromDirectory` applies to one filename. */
 export declare function isPrimarySpecFile(filename: string): boolean;
 /**

package/dist/lib/spec-pure.js

@@ -27,27 +27,125 @@ export const SPEC_ID_GRAMMAR = {
 };
 /** The marker the generator emits for an AC-less spec. */
 const GENERATED_NO_AC_MARKER = 'no acceptance_criteria — run encore-spec-ac-draft first';
-/** Keywords that mark a spec as carrying sensitive data — PHI/PII/billing/
- *  credentialing. The `/spec-pipeline` step-3b compliance gate fires on these
- *  mentions in ANY core (not just the regulated `cl/pm/hr/rh/gr` set), so the
- *  engine must detect them to gate `hasComplianceForSensitive` at parity with the
- *  command prose. Matched at word boundaries, case-insensitively, over frontmatter
- *  + body. Kept to high-signal regime tokens so an incidental mention never trips
- *  it; a spec can also opt in explicitly via a `<!-- sensitive -->`/`<!-- sensitive: -->`
- *  marker or a `sensitive`/`phi`/`pii`/`billing`/`credentialing` tag. */
-const SENSITIVE_KEYWORD_RE = /\b(PHI|PII|protected health information|personally identifiable information|billing|claims?|reimbursement|remittance advice|credentialing|payer enrollment|HIPAA|42 CFR Part 2)\b/i;
-/** True when the spec text (frontmatter + body) signals sensitive data: a
- *  high-signal regime keyword, an explicit `<!-- sensitive -->` marker, or a
- *  `sensitive`/`phi`/`pii`/`billing`/`credentialing` tag. Pure (operates on the raw
- *  spec text + the parsed `tags` array). Independent of `isRegulated` — a non-
- *  regulated FA billing or PF credentialing spec is `isSensitive` without being a
- *  regulated core, which is exactly the parity gap Finding A item 2 names. */
+/**
+ * Remove regions that legitimately QUOTE compliance-sounding words as examples,
+ * so the keyword heuristic in {@link detectSensitive} reads only load-bearing
+ * prose. Strips, per line: fenced code blocks (``` … ``` / ~~~ … ~~~), a
+ * `## Examples` heading section — an EXACT `Examples`/`Example` heading title only
+ * (so `## Examples of Regulated Data` is a normal heading, its body left as
+ * scannable prose) — down to the next same-or-higher heading, and Gherkin step
+ * lines. `Scenario:` / `Example(s):` / `Given` / `When` / `Then` openers strip
+ * unconditionally; `And` / `But` strip ONLY when the immediately preceding
+ * non-blank line (no intervening blank line) was itself a Gherkin step/opener —
+ * a standalone `And`/`But` prose line (e.g. a paragraph continuation) is left in
+ * place. Pure string transform — no fs, stays on the `/pure` graph. Callers apply
+ * it to the keyword-match INPUT only; opt-in/opt-out markers are still read from
+ * the raw text.
+ */
+export function stripExampleRegions(text) {
+    const out = [];
+    let inFence = false;
+    let exampleHeadingDepth = 0; // 0 ⇒ not inside a `## Examples` section
+    let inGherkinStep = false; // true right after a line that opened/continued a Gherkin step sequence
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('```') || trimmed.startsWith('~~~')) {
+            inFence = !inFence;
+            inGherkinStep = false;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const heading = /^(#{1,6})\s+(.*)$/.exec(trimmed);
+        if (heading) {
+            inGherkinStep = false;
+            const depth = heading[1].length;
+            if (exampleHeadingDepth && depth <= exampleHeadingDepth)
+                exampleHeadingDepth = 0;
+            if (!exampleHeadingDepth && /^\s*examples?\s*$/i.test(heading[2])) {
+                exampleHeadingDepth = depth;
+                continue;
+            }
+            if (exampleHeadingDepth)
+                continue;
+            out.push(line);
+            continue;
+        }
+        if (exampleHeadingDepth) {
+            inGherkinStep = false;
+            continue;
+        }
+        if (/^(Scenario|Examples?|Given|When|Then)\b/i.test(trimmed)) {
+            inGherkinStep = true;
+            continue;
+        }
+        if (inGherkinStep && /^(And|But)\b/i.test(trimmed))
+            continue;
+        inGherkinStep = false;
+        out.push(line);
+    }
+    return out.join('\n');
+}
+/** Compliance keyword matcher, split by signal strength. Matched at word boundaries,
+ *  case-insensitively. HIGH-signal tokens are checked against the RAW text (a regime
+ *  token is meaningful wherever it sits, even inside an example); LOW-signal tokens are
+ *  checked against the EXAMPLE-STRIPPED text (see {@link stripExampleRegions}) so a
+ *  billing/claims word quoted inside a Gherkin or fenced example on a non-regulated spec
+ *  no longer trips the compliance gate. See {@link detectSensitive} for exactly which
+ *  text each regex runs over.
+ *
+ *  HIGH-signal tokens name a regulated regime directly, so a SINGLE hit flags the
+ *  spec. The three low-signal tokens are common non-regulated business words, so
+ *  they flag only on ≥2 DISTINCT token TYPES (see {@link countDistinctLowSignalTypes});
+ *  two hits of the SAME token do not qualify. A spec can still opt in/out explicitly
+ *  (see {@link detectSensitive}). */
+const HIGH_SIGNAL_RE = /\b(PHI|PII|protected health information|personally identifiable information|remittance advice|credentialing|payer enrollment|HIPAA|42 CFR Part 2)\b/i;
+/** Low-signal compliance tokens — global so {@link countDistinctLowSignalTypes} can
+ *  enumerate every occurrence. */
+const LOW_SIGNAL_RE = /\b(billing|claims?|reimbursement)\b/gi;
+/** Count of DISTINCT low-signal token types in `text` (`claim`/`claims` collapse to
+ *  one type). ≥2 is the low-signal fire threshold. */
+function countDistinctLowSignalTypes(text) {
+    const types = new Set();
+    for (const match of text.matchAll(LOW_SIGNAL_RE)) {
+        const token = match[1].toLowerCase();
+        types.add(token.startsWith('claim') ? 'claims' : token);
+    }
+    return types.size;
+}
+/** True when the spec text (frontmatter + body) signals sensitive data. Precedence:
+ *  an explicit opt-IN wins TRUE (an anchored `<!-- sensitive -->`/`<!-- sensitive: -->`
+ *  marker or a `sensitive`/`phi`/`pii`/`billing`/`credentialing` tag), then an explicit
+ *  opt-OUT wins FALSE (an anchored `<!-- not-sensitive -->` marker or a `not-sensitive`
+ *  tag), otherwise the keyword heuristic: a HIGH-signal hit against the RAW text (so a
+ *  regime token cannot be hidden by sitting on a Given/When/Then/Scenario/Examples opener
+ *  line that {@link stripExampleRegions} would otherwise strip — a hard-gate fail-open),
+ *  OR ≥2 distinct LOW-signal token types against the EXAMPLE-STRIPPED text (so ordinary
+ *  billing/claims prose quoted in a Gherkin/fenced example does not false-positive).
+ *  Marker/tag detection runs on the RAW text (a deliberate marker anywhere is intentional)
+ *  BEFORE any stripping; the markers stay fully anchored so `not-sensitive` can never
+ *  substring-match `sensitive`. Pure; independent of `isRegulated`. */
 function detectSensitive(text, tags) {
     if (/<!--\s*sensitive\s*(?::[^>]*)?-->/i.test(text))
         return true;
     if (tags.some((t) => /^(sensitive|phi|pii|billing|credentialing)$/i.test(String(t).trim())))
         return true;
-    return SENSITIVE_KEYWORD_RE.test(text);
+    if (/<!--\s*not-sensitive\s*(?::[^>]*)?-->/i.test(text))
+        return false;
+    if (tags.some((t) => /^not-sensitive$/i.test(String(t).trim())))
+        return false;
+    // HIGH-signal tokens are matched on the RAW text: a regime token (PHI, HIPAA, 42 CFR
+    // Part 2, …) is meaningful wherever it appears, INCLUDING inside a Gherkin/example
+    // region — a spec that says "Given the PHI we store is encrypted" is still describing
+    // PHI, and stripExampleRegions unconditionally strips bare Given/When/Then/Scenario/
+    // Examples opener lines, which would otherwise remove the token before it is ever
+    // matched (a hard-gate fail-open). Only the LOW-signal English words (billing/claims/
+    // reimbursement — common outside any regulated context) are the example-block
+    // false-positive source stripExampleRegions exists to suppress (#64c), so that scan
+    // alone runs on the stripped text.
+    if (HIGH_SIGNAL_RE.test(text))
+        return true;
+    return countDistinctLowSignalTypes(stripExampleRegions(text)) >= 2;
 }
 /** True when a generated test source has ≥1 ACTIVE `test(` block (not `test.fixme`/
  *  `test.describe`) and is not an AC-less placeholder. Pure (operates on source text). */
@@ -192,13 +290,19 @@ export function isLifecycleArtifact(filename) {
         return new RegExp(`${left}${esc}${right}`).test(upper);
     });
 }
+/** Uppercase descriptor suffixes that mark a file as a derivative artifact OF a primary
+ *  spec (a `{ID}-TASKS.md`, `{ID}-PLAN.md`, …) rather than a spec itself. Factored out so
+ *  {@link isDerivativeArtifact} and {@link isSilentlySkippedSpecFile} agree byte-for-byte
+ *  on which reserved suffixes are EXPECTED non-primaries. Matched against the UPPER-CASED
+ *  basename, so no `i` flag is needed. */
+const DERIVATIVE_DESCRIPTOR_RE = /-(TASKS|PLAN|CONTEXT|RESEARCH|NAVIGATION|RECOMMENDATION|RECOMMENDATIONS|DECISION|DECISIONS|SUMMARY|IMPLEMENTATION|WORKSTREAM|AUDIT|REPORT|SIGNOFF|READINESS|EXPANSION|WORKSHEET|PATTERNS)/;
 /** True when a filename + its containing dir indicate a derivative artifact, not a primary spec. */
 export function isDerivativeArtifact(dirName, filename) {
     if (NON_PRIMARY_DIRS.has(dirName))
         return true;
     if (isLifecycleArtifact(filename) || isPhaseLifecycleFile(filename))
         return true;
-    return /-(TASKS|PLAN|CONTEXT|RESEARCH|NAVIGATION|RECOMMENDATION|RECOMMENDATIONS|DECISION|DECISIONS|SUMMARY|IMPLEMENTATION|WORKSTREAM|AUDIT|REPORT|SIGNOFF|READINESS|EXPANSION|WORKSHEET|PATTERNS)/i.test(specBasename(filename).toUpperCase());
+    return DERIVATIVE_DESCRIPTOR_RE.test(specBasename(filename).toUpperCase());
 }
 /** Uppercase derivative-artifact descriptors that, by repo convention, live ALONGSIDE
  *  primary specs in `specs/{core}/specs|ux/` AND deliberately carry the PARENT spec's
@@ -279,6 +383,47 @@ export function resolveSpecFileId(core, filename, declaredId) {
         return id;
     return null;
 }
+/**
+ * True when an on-disk filename PARSES to a well-formed primary-spec id yet the corpus
+ * loader would silently DROP it ({@link resolveSpecFileId} → null) for a reason a
+ * frontmatter `id:` could rescue — a reserved lifecycle word (REVIEW / ANALYSIS /
+ * CLARIFICATION …) landed inside a real feature slug and no `id:` disambiguates it. This
+ * is the silent-authoring-drop class issue #76 surfaces: the file reads as spec X to a
+ * human but never reaches spec-index.json / navigator / reconcile / recall.
+ *
+ * Deliberately EXCLUDES bona-fide sibling artifacts that legitimately carry a parent id
+ * and are SUPPOSED to be non-primary, so the surfacer stays quiet on a healthy corpus:
+ *   - dedicated CONTEXT/CLARIFICATION/ENHANCEMENTS/EXPANSION files ({@link isDedicatedArtifactFile}),
+ *   - `{ID}-PHASE…` lifecycle files ({@link isPhaseLifecycleFile}),
+ *   - descriptor-suffix artifacts (`-TASKS`/`-PLAN`/`-RESEARCH`/… — {@link DERIVATIVE_DESCRIPTOR_RE}),
+ *   - and a LONE terminal descriptor (`{ID}-REVIEW`, `{ID}-ANALYSIS`): only files with real
+ *     slug content AFTER the id (≥2 slug words) are flagged, i.e. the reserved word is
+ *     embedded in a feature name (`{ID}-compliance-review-workflow`), not the whole slug.
+ *
+ * The residue is exactly the case the mint-time guard (spec-id-guard → {@link resolveSpecFileId})
+ * blocks on `create`/`promote`, made visible for files already on disk. Pure (fs-free); the
+ * fs walk that feeds it lives in specs.ts `findSkippedSpecFiles`.
+ */
+export function isSilentlySkippedSpecFile(core, filename, declaredId) {
+    if (!filename.endsWith('.md'))
+        return false;
+    const base = specBasename(filename);
+    const id = extractSpecId(filename, core);
+    if (!id)
+        return false; // basename doesn't parse to a spec id → not an intended primary spec
+    if (resolveSpecFileId(core, filename, declaredId) !== null)
+        return false; // loader already indexes it → fine
+    if (isDedicatedArtifactFile(filename))
+        return false; // CONTEXT/CLARIFICATION/ENHANCEMENTS/EXPANSION — legit sibling
+    if (isPhaseLifecycleFile(filename))
+        return false; // {ID}-PHASE… — legit lifecycle artifact
+    if (DERIVATIVE_DESCRIPTOR_RE.test(base.toUpperCase()))
+        return false; // -TASKS/-PLAN/-RESEARCH/… — legit descriptor
+    // Only flag when real slug content follows the id — a lone terminal descriptor
+    // (`{ID}-REVIEW`, `{ID}-ANALYSIS`) is an artifact, not a dropped spec.
+    const remainder = base.slice(id.length).replace(/^-+/, '');
+    return remainder.includes('-');
+}
 /** The skip rules `collectSpecsFromDirectory` applies to one filename. */
 export function isPrimarySpecFile(filename) {
     if (!filename.endsWith('.md'))