@encore-os/eos-spec 0.16.0 → 0.17.0

package/dist/lib/reconcile-core.js.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile-core.js","sourceRoot":"","sources":["../../src/lib/reconcile-core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAuBvD;;oFAEoF;AACpF,MAAM,UAAU,QAAQ,CACtB,OAA2B,EAC3B,QAA4B,EAC5B,SAAsC,IAAI;IAE1C,IAAI,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC;AACvE,CAAC;AAUD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,IAAc,EACd,KAAc,EACd,QAA4B;IAE5B,MAAM,OAAO,GAAG,QAAQ,EAAE,YAAY,IAAI,YAAY,CAAC;IACvD,MAAM,MAAM,GAAG,QAAQ,EAAE,IAAI,IAAI,IAAI,CAAC;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC;IAC5C,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACtD,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACjD,IAAI,IAAI,GAAG,QAAQ,CAAC;QACpB,IAAI,SAAS,KAAK,IAAI;YAAE,IAAI,GAAG,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACjE,+EAA+E;QAC/E,6EAA6E;QAC7E,8EAA8E;QAC9E,+EAA+E;QAC/E,2EAA2E;QAC3E,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;YAC5F,MAAM,IAAI,GAAG,oBAAoB,CAAC,IAAI,EAAE,SAAS,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;YACpG,IAAI,IAAI;gBAAE,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,IAAI,KAAK,QAAQ;YAAE,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACxE,CAAC"}
+{"version":3,"file":"reconcile-core.js","sourceRoot":"","sources":["../../src/lib/reconcile-core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7F,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAuBvD;;oFAEoF;AACpF,MAAM,UAAU,QAAQ,CACtB,OAA2B,EAC3B,QAA4B,EAC5B,SAAsC,IAAI;IAE1C,IAAI,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC;AACvE,CAAC;AAUD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,IAAc,EACd,KAAc,EACd,QAA4B,EAC5B,gBAAyB;IAEzB,MAAM,OAAO,GAAG,QAAQ,EAAE,YAAY,IAAI,YAAY,CAAC;IACvD,MAAM,MAAM,GAAG,QAAQ,EAAE,IAAI,IAAI,IAAI,CAAC;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC;IAC5C,iEAAiE;IACjE,yFAAyF;IACzF,iFAAiF;IACjF,qFAAqF;IACrF,0FAA0F;IAC1F,sFAAsF;IACtF,2EAA2E;IAC3E,MAAM,cAAc,GAAG,gBAAgB,KAAK,SAAS,IAAI,OAAO,KAAK,gBAAgB,CAAC;IACtF,MAAM,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9E,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACjD,IAAI,IAAI,GAAG,QAAQ,CAAC;QACpB,IAAI,SAAS,KAAK,IAAI;YAAE,IAAI,GAAG,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACjE,+EAA+E;QAC/E,6EAA6E;QAC7E,8EAA8E;QAC9E,+EAA+E;QAC/E,2EAA2E;QAC3E,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;YAC5F,MAAM,IAAI,GAAG,oBAAoB,CAAC,IAAI,EAAE,SAAS,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;YACpG,IAAI,IAAI;gBAAE,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,IAAI,KAAK,QAAQ;YAAE,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACxE,CAAC"}

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

@@ -0,0 +1,38 @@
+export type RtmSpecRow = {
+    id: string;
+    core: string;
+    fr: {
+        total: number;
+        verified: number;
+        unverified: string[];
+    };
+    sc: {
+        total: number;
+        met: number;
+        unmet: string[];
+    };
+};
+export type RtmReport = {
+    core: string;
+    /** Specs scanned. */
+    total: number;
+    /** Specs carrying ≥1 FR or SC (the ones the scorecard actually scores). */
+    specsWithReqs: number;
+    fr: {
+        total: number;
+        verified: number;
+    };
+    sc: {
+        total: number;
+        met: number;
+    };
+    /** Fraction of FRs verified (0–1); 1 when there are no FRs (nothing to verify). */
+    frVerifiedPct: number;
+    /** Fraction of SCs met (0–1); 1 when there are no SCs. */
+    scMetPct: number;
+    /** Per-spec rows, only for specs that carry FR/SC requirements. */
+    rows: RtmSpecRow[];
+};
+/** Build the corpus RTM scorecard for `coreFilter` (or all cores). Deterministic (listSpecs
+ *  order). Specs with no FR/SC requirements are counted in `total` but omitted from `rows`. */
+export declare function buildRtmScorecard(repoRoot: string, coreFilter?: string): RtmReport;

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

@@ -0,0 +1,70 @@
+/**
+ * fs-bound driver for the FR/SC RTM scorecard (#79): walk a repo's specs, read each spec's
+ * body + frontmatter ACs, and aggregate the pure {@link deriveScorecard} per spec into a corpus
+ * report. The verdict logic + parsing stay in the pure `rtm-scorecard.ts` (on the `/pure` graph);
+ * this only supplies the corpus walk + file IO, so it lives behind the package main entry.
+ *
+ * On-disk (proof-free) by design: "verified" reads from each AC's frontmatter `status` and each
+ * FR's body `[status]`, not from a live test run. A consumer that wants run-proven coverage feeds
+ * `deriveScorecard` its own `proof` set from `verify-acs`; this static readiness view mirrors the
+ * existing `scorecard` command.
+ */
+import { readFileSync } from 'node:fs';
+import { readFrontmatter, stripFrontmatter } from './frontmatter.js';
+import { collectScorecardItems, deriveScorecard } from './rtm-scorecard.js';
+import { listSpecs } from './specs.js';
+/** Build the corpus RTM scorecard for `coreFilter` (or all cores). Deterministic (listSpecs
+ *  order). Specs with no FR/SC requirements are counted in `total` but omitted from `rows`. */
+export function buildRtmScorecard(repoRoot, coreFilter) {
+    const specs = listSpecs(repoRoot, coreFilter);
+    const rows = [];
+    let frTotal = 0;
+    let frVerified = 0;
+    let scTotal = 0;
+    let scMet = 0;
+    let specsWithReqs = 0;
+    for (const spec of specs) {
+        let text = '';
+        try {
+            text = readFileSync(spec.path, 'utf8');
+        }
+        catch {
+            continue; // unreadable — skip
+        }
+        const fm = readFrontmatter(text);
+        const items = collectScorecardItems(stripFrontmatter(text), fm.acceptance_criteria);
+        const card = deriveScorecard(items);
+        if (card.fr.total === 0 && card.sc.total === 0)
+            continue; // nothing to score
+        specsWithReqs++;
+        frTotal += card.fr.total;
+        frVerified += card.fr.verified;
+        scTotal += card.sc.total;
+        scMet += card.sc.met;
+        rows.push({
+            id: spec.id,
+            core: spec.core,
+            fr: {
+                total: card.fr.total,
+                verified: card.fr.verified,
+                unverified: card.fr.rows.filter((r) => !r.verified).map((r) => r.id),
+            },
+            sc: {
+                total: card.sc.total,
+                met: card.sc.met,
+                unmet: card.sc.rows.filter((r) => !r.met).map((r) => r.id),
+            },
+        });
+    }
+    return {
+        core: coreFilter ?? 'all',
+        total: specs.length,
+        specsWithReqs,
+        fr: { total: frTotal, verified: frVerified },
+        sc: { total: scTotal, met: scMet },
+        frVerifiedPct: frTotal === 0 ? 1 : frVerified / frTotal,
+        scMetPct: scTotal === 0 ? 1 : scMet / scTotal,
+        rows,
+    };
+}
+//# sourceMappingURL=rtm-scorecard-run.js.map

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

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

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

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ */
+/** 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 a single body line into `{ id, kind: 'US' | 'FR', status }`, or null. US and FR
+ *  share one list format (`- **FR-1** [verified] …`); FR is first-class verifiable. */
+export declare function matchBodyRequirement(line: string): {
+    id: string;
+    kind: 'US' | 'FR';
+    status: string;
+} | null;
+/** 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,197 @@
+/**
+ * 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.
+ */
+/** Parse a single body line into `{ id, kind: 'US' | 'FR', status }`, or null. US and FR
+ *  share one list format (`- **FR-1** [verified] …`); FR is first-class verifiable. */
+export function matchBodyRequirement(line) {
+    const m = /^\s*-\s+\*{0,2}((US|FR)-\d+)\*{0,2}\s+\[([a-z_]+)\]/.exec(line);
+    return m ? { id: m[1], kind: m[2], status: m[3] } : null;
+}
+/** 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":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkCH;uFACuF;AACvF,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,CAAC,GAAG,qDAAqD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAgB,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5E,CAAC;AAED;;sDAEsD;AACtD,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,CAAC,GAAG,0EAA0E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChG,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxB,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,CAAC,CAAE;QACT,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS;QACzB,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9D,QAAQ,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,kCAAkC,CAAC,IAAI,EAAE,CAAC,CAAC;KAC7E,CAAC;AACJ,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,CAAC,GAAG,4EAA4E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClG,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,eAAe,CAAC,QAA4B;IAC1D,MAAM,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IACxC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,KAAK,MAAM,EAAE,IAAI,EAAE,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAClC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,YAA6C,EAC7C,WAAwB;IAExB,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,UAAU,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAMzB;IACC,MAAM,EAAE,WAAW,GAAG,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,GAAG,KAAK,EAAE,gBAAgB,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;IACzG,IAAI,QAAQ,IAAI,gBAAgB,EAAE,CAAC;QACjC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,qBAAqB,EAAE,WAAW,EAAE,CAAC;IACxE,CAAC;IACD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iCAAiC,EAAE,WAAW,EAAE,CAAC;IACrF,CAAC;IACD,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;IAC5F,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,8BAA8B,EAAE,WAAW,EAAE,CAAC;IACtG,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC;AAC/G,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,EAAwB,EACxB,IAIC;IAED,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,GAAG,IAAI,CAAC;IAC5D,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC;IAClC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,EAAE,CAAC;IACvE,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC;IACvF,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,iCAAiC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACvF,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;IAC/E,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;IACpF,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,6CAA6C,EAAE,CAAC;AACpH,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,MAAe;IACrE,MAAM,QAAQ,GAAuB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACxD,CAAC,CAAC,MAAM;aACH,MAAM,CAAC,CAAC,CAAC,EAAgC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC;aACzE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACX,EAAE,EAAE,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;YACxC,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;YAC3D,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;YAChC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC;SACnC,CAAC,CAAC;aACF,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;QAC/B,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,OAAO,GAA+B,EAAE,CAAC;IAC/C,MAAM,QAAQ,GAA+B,EAAE,CAAC;IAChD,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,GAAG,EAAE,CAAC;YACR,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI;gBAAE,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACxE,SAAS,CAAC,mDAAmD;QAC/D,CAAC;QACD,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,GAAG,EAAE,CAAC;YACR,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,EAAE;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAClD,CAAC;AAED;+DAC+D;AAC/D,SAAS,YAAY,CAAC,CAAU;IAC9B,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAClB,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACrG,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,eAAe,CAAC,IAA6B,EAAE,QAAwB,EAAE;IACvF,MAAM,EAAE,OAAO,GAAG,EAAE,EAAE,QAAQ,GAAG,EAAE,EAAE,OAAO,GAAG,EAAE,EAAE,QAAQ,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC;IAC1E,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,IAAI,GAAG,EAAU,CAAC;IAC3D,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,IAAI,GAAG,EAAU,CAAC;IAE3D,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAU,CAAC,CAAC,CAAC;IAC7E,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,UAAU,CAAU,CAAC,CAAC,CAAC;IAC/F,MAAM,YAAY,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAE/C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAClC,EAAE,EAAE,EAAE,CAAC,EAAE;QACT,GAAG,SAAS,CAAC;YACX,WAAW,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE;YAC1C,YAAY;YACZ,WAAW;YACX,QAAQ,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,gBAAgB,EAAE,EAAE,CAAC,MAAM,KAAK,UAAU;SAC3C,CAAC;KACH,CAAC,CAAC,CAAC;IAEJ,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEtH,OAAO;QACL,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;QAC7F,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;KACpF,CAAC;AACJ,CAAC;AAED;;;oEAGoE;AACpE,MAAM,CAAC,MAAM,uBAAuB,GAA2B,EAAE,aAAa,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAMjG;gFACgF;AAChF,MAAM,UAAU,UAAU,CACxB,MAA6F;IAE7F,MAAM,GAAG,GAAG,MAAM,EAAE,GAAG,CAAC;IACxB,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,IAAI,uBAAuB,EAAE,CAAC;AAChG,CAAC;AAED;oGACoG;AACpG,MAAM,UAAU,qBAAqB,CACnC,QAAgC,EAChC,SAAiC,uBAAuB;IAExD,MAAM,QAAQ,GAA4D,EAAE,CAAC;IAC7E,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,KAAK;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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;
 /**