@encore-os/eos-spec 0.3.1

package/dist/lib/requirements.js

@@ -0,0 +1,179 @@
+/**
+ * Typed acceptance-criteria / user-story / functional-requirement schema for spec
+ * frontmatter, plus a lenient normalizer. Adapted from encoreos's
+ * `ac-response-parser.ts`, but reads already-parsed YAML frontmatter values
+ * (objects) rather than an LLM JSON response, and coerces scalar Given/When/Then
+ * strings into single-element arrays so scalar-shaped legacy specs parse unchanged.
+ */
+/** The status values the audit's "AC Validated" gate accepts as closed
+ *  (everything except `planned`). */
+export const TERMINAL_AC_STATUSES = ['verified', 'hand_closed', 'deferred'];
+export const AC_ID_RE = /^AC-\d+$/;
+export const US_ID_RE = /^US-\d+$/;
+export const FR_ID_RE = /^FR-\d+$/;
+/** Scalar string -> `[string]`; array -> trimmed non-empty strings; anything else -> `[]`. */
+export function coerceStringArray(v) {
+    if (typeof v === 'string') {
+        const t = v.trim();
+        return t === '' ? [] : [t];
+    }
+    if (Array.isArray(v)) {
+        return v.filter((x) => typeof x === 'string' && x.trim() !== '').map((x) => x.trim());
+    }
+    return [];
+}
+function toStatus(v) {
+    if (v === 'verified' || v === 'hand_closed' || v === 'deferred')
+        return v;
+    return 'planned';
+}
+function isValidStatus(v) {
+    return v === 'planned' || v === 'verified' || v === 'hand_closed' || v === 'deferred';
+}
+/**
+ * Normalizes a raw YAML frontmatter `acceptance_criteria` value into typed
+ * `AcceptanceCriterion` objects, collecting `ShapeIssue`s for any structural
+ * problems found. An entry with an unrecognized status is still included with
+ * `status` defaulted to `'planned'` plus a ShapeIssue — callers must check
+ * `issues` before trusting `status`.
+ */
+export function normalizeAcceptanceCriteria(raw) {
+    const issues = [];
+    if (raw === undefined)
+        return { acs: [], issues };
+    if (!Array.isArray(raw)) {
+        return { acs: [], issues: [{ field: 'acceptance_criteria', message: 'must be a list of acceptance criteria' }] };
+    }
+    const acs = [];
+    raw.forEach((entry, i) => {
+        if (!entry || typeof entry !== 'object') {
+            issues.push({ field: `acceptance_criteria[${i}]`, message: 'entry is not a mapping' });
+            return;
+        }
+        const rec = entry;
+        const id = typeof rec.id === 'string' ? rec.id : undefined;
+        if (!id) {
+            issues.push({ field: `acceptance_criteria[${i}]`, message: 'missing string id' });
+            return;
+        }
+        const statementOnly = rec.statement_only === true;
+        const given = coerceStringArray(rec.given);
+        const when = coerceStringArray(rec.when);
+        const then = coerceStringArray(rec.then);
+        if (!statementOnly && (given.length === 0 || when.length === 0 || then.length === 0)) {
+            const missing = [
+                given.length === 0 ? 'given' : null,
+                when.length === 0 ? 'when' : null,
+                then.length === 0 ? 'then' : null,
+            ].filter((x) => x !== null);
+            issues.push({
+                id,
+                field: 'given/when/then',
+                message: `AC ${id} is missing non-empty: ${missing.join(', ')} (or set statement_only: true)`,
+            });
+        }
+        if (rec.status !== undefined && !isValidStatus(rec.status)) {
+            issues.push({
+                id,
+                field: 'status',
+                message: `AC ${id} has invalid status "${String(rec.status)}" (planned|verified|hand_closed|deferred)`,
+            });
+        }
+        acs.push({
+            id,
+            userStory: typeof rec.user_story === 'string' ? rec.user_story : undefined,
+            status: toStatus(rec.status),
+            given,
+            when,
+            then,
+            statementOnly,
+        });
+    });
+    return { acs, issues };
+}
+export function normalizeUserStories(raw) {
+    const issues = [];
+    if (raw === undefined)
+        return { uss: [], issues };
+    if (!Array.isArray(raw))
+        return { uss: [], issues: [{ field: 'user_stories', message: 'must be a list' }] };
+    const uss = [];
+    raw.forEach((entry, i) => {
+        if (!entry || typeof entry !== 'object') {
+            issues.push({ field: `user_stories[${i}]`, message: 'entry is not a mapping' });
+            return;
+        }
+        const rec = entry;
+        const id = typeof rec.id === 'string' ? rec.id : undefined;
+        if (!id) {
+            issues.push({ field: `user_stories[${i}]`, message: 'missing string id' });
+            return;
+        }
+        const text = typeof rec.text === 'string' ? rec.text.trim() : '';
+        if (!text)
+            issues.push({ id, field: 'text', message: `US ${id} is missing text` });
+        uss.push({ id, text });
+    });
+    return { uss, issues };
+}
+export function normalizeRequirements(raw) {
+    const issues = [];
+    if (raw === undefined)
+        return { frs: [], issues };
+    if (!Array.isArray(raw))
+        return { frs: [], issues: [{ field: 'requirements', message: 'must be a list' }] };
+    const frs = [];
+    raw.forEach((entry, i) => {
+        if (!entry || typeof entry !== 'object') {
+            issues.push({ field: `requirements[${i}]`, message: 'entry is not a mapping' });
+            return;
+        }
+        const rec = entry;
+        const id = typeof rec.id === 'string' ? rec.id : undefined;
+        if (!id) {
+            issues.push({ field: `requirements[${i}]`, message: 'missing string id' });
+            return;
+        }
+        const text = typeof rec.text === 'string' ? rec.text.trim() : '';
+        if (!text)
+            issues.push({ id, field: 'text', message: `FR ${id} is missing text` });
+        frs.push({ id, text, status: toStatus(rec.status) });
+    });
+    return { frs, issues };
+}
+/** Per-AC status tally for the pipeline status reader (consumed by the P3 audit).
+ *  `hand_closed` and `deferred` are terminal-but-not-`planned` statuses the audit
+ *  treats as closed (issue #174); they are counted separately so the audit can
+ *  still apply the Verification-backlink guard to `hand_closed`. */
+export function acStatusCounts(raw) {
+    const { acs } = normalizeAcceptanceCriteria(raw);
+    const counts = { planned: 0, verified: 0, handClosed: 0, deferred: 0 };
+    for (const ac of acs) {
+        if (ac.status === 'verified')
+            counts.verified += 1;
+        else if (ac.status === 'hand_closed')
+            counts.handClosed += 1;
+        else if (ac.status === 'deferred')
+            counts.deferred += 1;
+        else
+            counts.planned += 1;
+    }
+    return counts;
+}
+/**
+ * True when a spec has ≥1 acceptance criterion and EVERY (well-formed) AC is in a
+ * terminal status (`verified` | `hand_closed` | `deferred`) — i.e. none remain
+ * `planned`. This is the typed, ADR-0015-aware replacement for the legacy
+ * `status === 'verified'` check `specs.ts` used to hand-roll: a `hand_closed`
+ * (proven by a CI suite the src-lane prover can't reach) or `deferred` AC
+ * terminally resolves the generate-tests gate exactly as a `verified` one does
+ * (issue #174). Malformed (id-less) AC entries are dropped by
+ * `normalizeAcceptanceCriteria` — and `validate` flags them — so they are not
+ * counted here; an empty / non-array value is `false`.
+ */
+export function allAcceptanceCriteriaTerminal(raw) {
+    const c = acStatusCounts(raw);
+    const total = c.planned + c.verified + c.handClosed + c.deferred;
+    return total > 0 && c.planned === 0;
+}
+//# sourceMappingURL=requirements.js.map

package/dist/lib/requirements.js.map

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

package/dist/lib/rollup.d.ts

@@ -0,0 +1,24 @@
+import type { ScorecardReport } from './scorecard.js';
+export type RollupCoreRow = {
+    core: string;
+    total: number;
+    authored: number;
+    claimsComplete: number;
+    claimedCompleteButUnverified: number;
+    withVerifiedRequirements: number;
+    verifiedPct: number;
+    authoredPct: number;
+};
+export type RollupReport = {
+    cores: string[];
+    totals: {
+        specs: number;
+        claimsComplete: number;
+        claimedCompleteButUnverified: number;
+        withVerifiedRequirements: number;
+        verifiedPct: number;
+    };
+    rows: RollupCoreRow[];
+};
+/** Aggregate per-core scorecards into a ranked platform readiness view (most-ready first). */
+export declare function computeRollup(perCore: ScorecardReport[]): RollupReport;

package/dist/lib/rollup.js

@@ -0,0 +1,34 @@
+const pct = (n, d) => (d > 0 ? Math.round((n / d) * 1000) / 10 : 0);
+/** Aggregate per-core scorecards into a ranked platform readiness view (most-ready first). */
+export function computeRollup(perCore) {
+    const rows = perCore.map((r) => {
+        const authored = r.byStage.tasks_generated ?? 0;
+        return {
+            core: r.core,
+            total: r.total,
+            authored,
+            claimsComplete: r.claimsComplete,
+            claimedCompleteButUnverified: r.claimedCompleteButUnverified,
+            withVerifiedRequirements: r.withVerifiedRequirements,
+            verifiedPct: pct(r.withVerifiedRequirements, r.total),
+            authoredPct: pct(authored, r.total),
+        };
+    });
+    rows.sort((a, b) => b.verifiedPct - a.verifiedPct || b.authoredPct - a.authoredPct || a.core.localeCompare(b.core));
+    const specs = rows.reduce((s, r) => s + r.total, 0);
+    const claimsComplete = rows.reduce((s, r) => s + r.claimsComplete, 0);
+    const claimedCompleteButUnverified = rows.reduce((s, r) => s + r.claimedCompleteButUnverified, 0);
+    const withVerifiedRequirements = rows.reduce((s, r) => s + r.withVerifiedRequirements, 0);
+    return {
+        cores: perCore.map((r) => r.core),
+        totals: {
+            specs,
+            claimsComplete,
+            claimedCompleteButUnverified,
+            withVerifiedRequirements,
+            verifiedPct: pct(withVerifiedRequirements, specs),
+        },
+        rows,
+    };
+}
+//# sourceMappingURL=rollup.js.map

package/dist/lib/rollup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollup.js","sourceRoot":"","sources":["../../src/lib/rollup.ts"],"names":[],"mappings":"AAyBA,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE5F,8FAA8F;AAC9F,MAAM,UAAU,aAAa,CAAC,OAA0B;IACtD,MAAM,IAAI,GAAoB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC9C,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO,CAAC,eAAe,IAAI,CAAC,CAAC;QAChD,OAAO;YACL,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,QAAQ;YACR,cAAc,EAAE,CAAC,CAAC,cAAc;YAChC,4BAA4B,EAAE,CAAC,CAAC,4BAA4B;YAC5D,wBAAwB,EAAE,CAAC,CAAC,wBAAwB;YACpD,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,wBAAwB,EAAE,CAAC,CAAC,KAAK,CAAC;YACrD,WAAW,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC;SACpC,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEpH,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACpD,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;IACtE,MAAM,4BAA4B,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,4BAA4B,EAAE,CAAC,CAAC,CAAC;IAClG,MAAM,wBAAwB,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,wBAAwB,EAAE,CAAC,CAAC,CAAC;IAE1F,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACjC,MAAM,EAAE;YACN,KAAK;YACL,cAAc;YACd,4BAA4B;YAC5B,wBAAwB;YACxB,WAAW,EAAE,GAAG,CAAC,wBAAwB,EAAE,KAAK,CAAC;SAClD;QACD,IAAI;KACL,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,6 @@
+import { type ScorecardReport } from './scorecard.js';
+/**
+ * Gather per-spec inputs for one core and compute its scorecard. `verifiedBySpec` is passed in so the
+ * caller can run scanVerifies(repoRoot) ONCE and reuse it across cores (the rollup does this).
+ */
+export declare function buildScorecardForCore(repoRoot: string, core: string | undefined, verifiedBySpec: Map<string, Set<string>>): ScorecardReport;

package/dist/lib/scorecard-run.js

@@ -0,0 +1,48 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readFrontmatter } from './frontmatter.js';
+import { collectRequirementIds, computeScorecard, countRequirements, } from './scorecard.js';
+import { listSpecs } from './specs.js';
+/** True if dir exists and contains at least one entry matching `pred`. */
+function dirHas(dir, pred) {
+    try {
+        return readdirSync(dir).some(pred);
+    }
+    catch {
+        return false;
+    }
+}
+/** Core-level Definition-of-Done signals: a DocShot lane and hand-written E2E (generated scaffolds excluded). */
+function coreSignalsFor(repoRoot, core) {
+    if (!core)
+        return { hasDocshots: false, hasE2E: false };
+    const imagesDir = join(repoRoot, 'docs/images', core);
+    const e2eDir = join(repoRoot, 'tests/e2e', core);
+    const hasDocshots = existsSync(imagesDir) && dirHas(imagesDir, (n) => /\.(png|jpe?g|webp)$/i.test(n));
+    const hasE2E = dirHas(e2eDir, (n) => /\.(spec|test)\.tsx?$/.test(n));
+    return { hasDocshots, hasE2E };
+}
+/**
+ * Gather per-spec inputs for one core and compute its scorecard. `verifiedBySpec` is passed in so the
+ * caller can run scanVerifies(repoRoot) ONCE and reuse it across cores (the rollup does this).
+ */
+export function buildScorecardForCore(repoRoot, core, verifiedBySpec) {
+    const specs = listSpecs(repoRoot, core);
+    const rows = specs.map((spec) => {
+        const text = readFileSync(spec.path, 'utf8');
+        const fm = readFrontmatter(text);
+        const claimedStatus = (typeof fm.status === 'string' ? fm.status : undefined) ?? spec.status;
+        const { acTotal, usTotal, frTotal } = countRequirements(text);
+        return {
+            spec,
+            claimedStatus,
+            acTotal,
+            usTotal,
+            frTotal,
+            declaredIds: collectRequirementIds(text),
+            verifiedIds: verifiedBySpec.get(spec.id) ?? new Set(),
+        };
+    });
+    return computeScorecard({ core: core ?? 'all', rows, coreSignals: coreSignalsFor(repoRoot, core) });
+}
+//# sourceMappingURL=scorecard-run.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scorecard-run.js","sourceRoot":"","sources":["../../src/lib/scorecard-run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,GAGlB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,0EAA0E;AAC1E,SAAS,MAAM,CAAC,GAAW,EAAE,IAA+B;IAC1D,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,iHAAiH;AACjH,SAAS,cAAc,CAAC,QAAgB,EAAE,IAAwB;IAChE,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACxD,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IACjD,MAAM,WAAW,GAAG,UAAU,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACtG,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,IAAwB,EACxB,cAAwC;IAExC,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACxC,MAAM,IAAI,GAAwB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACnD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC;QAC7F,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAC9D,OAAO;YACL,IAAI;YACJ,aAAa;YACb,OAAO;YACP,OAAO;YACP,OAAO;YACP,WAAW,EAAE,qBAAqB,CAAC,IAAI,CAAC;YACxC,WAAW,EAAE,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,GAAG,EAAU;SAC9D,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,gBAAgB,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;AACtG,CAAC"}

package/dist/lib/scorecard.d.ts

@@ -0,0 +1,69 @@
+import type { SpecFile } from './specs.js';
+export type ScorecardRowInput = {
+    spec: SpecFile;
+    /** Claimed status — frontmatter `status` or the body `**Status:**` banner (raw). */
+    claimedStatus?: string;
+    acTotal: number;
+    usTotal: number;
+    /** Functional requirements (body `**FR-N**`) — first-class verifiable. */
+    frTotal?: number;
+    /** AC/US/FR ids backlinked for this spec via @verifies. */
+    verifiedIds: Set<string>;
+    /** Requirement ids the spec DECLARES (AC/US/FR). When provided, verifiedIds is intersected
+     * with this set; backlinks to undeclared ids count as warnings, not evidence. */
+    declaredIds?: Set<string>;
+};
+export type ScorecardRow = {
+    id: string;
+    core: string;
+    title?: string;
+    stage: string;
+    claimedStatus?: string;
+    claimsComplete: boolean;
+    requirementsTotal: number;
+    requirementsVerified: number;
+    /** @verifies backlinks pointing at ids the spec never declared (typo'd AC, stale fixture). */
+    verifiedUndeclared: number;
+    frontmatterAccurate: 'match' | 'overstated' | 'understated';
+    claimedCompleteButUnverified: boolean;
+};
+export type ScorecardReport = {
+    core: string;
+    total: number;
+    byStage: Record<string, number>;
+    claimsComplete: number;
+    claimedCompleteButUnverified: number;
+    withVerifiedRequirements: number;
+    /** Total backlinked-but-undeclared ids across the core — a data-quality warning, not evidence. */
+    verifiedUndeclaredTotal: number;
+    /** Core has a DocShot lane (docs/images/<core>/ with screenshots). */
+    hasDocshots: boolean;
+    /** Core has hand-written E2E (tests/e2e/<core>/). Generated scaffolds don't count. */
+    hasE2E: boolean;
+    rows: ScorecardRow[];
+};
+/** Count acceptance criteria (frontmatter), user stories, and functional requirements (body) declared by a spec.
+ * FR is first-class verifiable (Definition of Done). The `**` anchor means `**NFR-misc-N**` never counts as FR. */
+export declare function countRequirements(specText: string): {
+    acTotal: number;
+    usTotal: number;
+    frTotal: number;
+};
+/** Collect the requirement ids a spec DECLARES: frontmatter acceptance_criteria / user_stories
+ * entry ids plus body `- **US-n**` / `- **FR-n**` items. Used to intersect @verifies backlinks —
+ * a backlink to an undeclared id is a warning, not verification evidence. */
+export declare function collectRequirementIds(specText: string): Set<string>;
+/**
+ * Deterministic readiness scorecard. Per spec it records the computed authoring stage, whether the
+ * spec *claims* completion, how many requirements (ACs + user stories) are `@verifies`-backed, and a
+ * frontmatter-accuracy verdict. The rollup's headline — `claimedCompleteButUnverified` — is the exact
+ * column every completion audit hand-derives: "says complete, zero AC-linked tests".
+ */
+export declare function computeScorecard(input: {
+    core: string;
+    rows: ScorecardRowInput[];
+    coreSignals?: {
+        hasDocshots: boolean;
+        hasE2E: boolean;
+    };
+}): ScorecardReport;

package/dist/lib/scorecard.js

@@ -0,0 +1,113 @@
+import { readFrontmatter } from './frontmatter.js';
+import { computeStage } from './pipeline-map.js';
+const COMPLETE_RE = /\b(complete|completed|done|shipped)\b|✅/i;
+/** Funnel's terminal authoring stage. */
+const TERMINAL_STAGE = 'tasks_generated';
+/** Count acceptance criteria (frontmatter), user stories, and functional requirements (body) declared by a spec.
+ * FR is first-class verifiable (Definition of Done). The `**` anchor means `**NFR-misc-N**` never counts as FR. */
+export function countRequirements(specText) {
+    const fm = readFrontmatter(specText);
+    const acTotal = Array.isArray(fm.acceptance_criteria) ? fm.acceptance_criteria.length : 0;
+    const fmUs = Array.isArray(fm.user_stories) ? fm.user_stories.length : 0;
+    const bodyUs = new Set((specText.match(/(?:^|\n)\s*-\s+\*{0,2}US-\d+/g) ?? []).map((s) => /US-\d+/.exec(s)?.[0] ?? ''));
+    bodyUs.delete('');
+    const bodyFr = new Set((specText.match(/(?:^|\n)\s*-\s+\*{0,2}FR-\d+/g) ?? []).map((s) => /FR-\d+/.exec(s)?.[0] ?? ''));
+    bodyFr.delete('');
+    return { acTotal, usTotal: Math.max(fmUs, bodyUs.size), frTotal: bodyFr.size };
+}
+/** Collect the requirement ids a spec DECLARES: frontmatter acceptance_criteria / user_stories
+ * entry ids plus body `- **US-n**` / `- **FR-n**` items. Used to intersect @verifies backlinks —
+ * a backlink to an undeclared id is a warning, not verification evidence. */
+export function collectRequirementIds(specText) {
+    const fm = readFrontmatter(specText);
+    const ids = new Set();
+    const addFromEntries = (v) => {
+        if (!Array.isArray(v))
+            return;
+        for (const entry of v) {
+            if (typeof entry === 'string') {
+                const id = /^(?:AC|US|FR)-\d+/.exec(entry.trim())?.[0];
+                if (id)
+                    ids.add(id);
+                continue;
+            }
+            const id = entry?.id;
+            if (typeof id === 'string' && /^(?:AC|US|FR)-\d+$/.test(id))
+                ids.add(id);
+        }
+    };
+    addFromEntries(fm.acceptance_criteria);
+    addFromEntries(fm.user_stories);
+    for (const m of specText.match(/(?:^|\n)\s*-\s+\*{0,2}(?:US|FR)-\d+/g) ?? []) {
+        const id = /(?:US|FR)-\d+/.exec(m)?.[0];
+        if (id)
+            ids.add(id);
+    }
+    return ids;
+}
+/**
+ * Deterministic readiness scorecard. Per spec it records the computed authoring stage, whether the
+ * spec *claims* completion, how many requirements (ACs + user stories) are `@verifies`-backed, and a
+ * frontmatter-accuracy verdict. The rollup's headline — `claimedCompleteButUnverified` — is the exact
+ * column every completion audit hand-derives: "says complete, zero AC-linked tests".
+ */
+export function computeScorecard(input) {
+    const byStage = {};
+    let claimsCompleteCount = 0;
+    let claimedCompleteButUnverified = 0;
+    let withVerifiedRequirements = 0;
+    let verifiedUndeclaredTotal = 0;
+    const rows = input.rows.map((r) => {
+        const stage = computeStage(r.spec);
+        byStage[stage] = (byStage[stage] ?? 0) + 1;
+        const claimsComplete = !!r.claimedStatus && COMPLETE_RE.test(r.claimedStatus);
+        const requirementsTotal = r.acTotal + r.usTotal + (r.frTotal ?? 0);
+        // Only backlinks to ids the spec actually declares count as evidence; the rest are warnings.
+        const declared = r.declaredIds;
+        const requirementsVerified = declared
+            ? [...r.verifiedIds].filter((id) => declared.has(id)).length
+            : r.verifiedIds.size;
+        const verifiedUndeclared = r.verifiedIds.size - requirementsVerified;
+        verifiedUndeclaredTotal += verifiedUndeclared;
+        if (claimsComplete)
+            claimsCompleteCount++;
+        if (requirementsVerified > 0)
+            withVerifiedRequirements++;
+        const unverifiedComplete = claimsComplete && requirementsVerified === 0;
+        if (unverifiedComplete)
+            claimedCompleteButUnverified++;
+        let frontmatterAccurate = 'match';
+        if (claimsComplete && stage !== TERMINAL_STAGE && stage !== 'planned') {
+            frontmatterAccurate = 'overstated';
+        }
+        else if (!claimsComplete && stage === TERMINAL_STAGE) {
+            frontmatterAccurate = 'understated';
+        }
+        return {
+            id: r.spec.id,
+            core: r.spec.core,
+            title: r.spec.title,
+            stage,
+            claimedStatus: r.claimedStatus,
+            claimsComplete,
+            requirementsTotal,
+            requirementsVerified,
+            verifiedUndeclared,
+            frontmatterAccurate,
+            claimedCompleteButUnverified: unverifiedComplete,
+        };
+    });
+    return {
+        core: input.core,
+        total: rows.length,
+        hasDocshots: input.coreSignals?.hasDocshots ?? false,
+        hasE2E: input.coreSignals?.hasE2E ?? false,
+        byStage,
+        claimsComplete: claimsCompleteCount,
+        claimedCompleteButUnverified,
+        withVerifiedRequirements,
+        verifiedUndeclaredTotal,
+        rows,
+    };
+}
+//# sourceMappingURL=scorecard.js.map

package/dist/lib/scorecard.js.map

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

package/dist/lib/semantic-search.d.ts

@@ -0,0 +1,36 @@
+import { type EmbeddingsSource } from './embeddings-source.js';
+import { type PrecedentHit } from './precedent-search.js';
+/** Async query embedder: returns a normalized vector, or null when unavailable. */
+export type QueryEmbedder = (query: string) => Promise<Float32Array | null>;
+/**
+ * Semantic precedent search over the committed embedding index. Returns ranked
+ * hits, or null when the index is absent OR the embedder can't produce a query
+ * vector — callers then fall back to the always-on lexical {@link searchSpecs}.
+ *
+ * Validated: qwen3-embedding:0.6b + the query instruction prefix lifts paraphrase
+ * recall to 7/8 (lexical 4/8) while holding exact@5 at 8/8. The lexical layer
+ * stays the zero-dependency baseline (CI / no-Ollama environments).
+ */
+export declare function searchSpecsSemantic(topic: string, opts: {
+    repoRoot: string;
+    limit?: number;
+    embedQuery: QueryEmbedder;
+    includeArchived?: boolean;
+    /** Inject a non-default embedding backend (tests / future pgvector source). */
+    source?: EmbeddingsSource;
+}): Promise<PrecedentHit[] | null>;
+/**
+ * Best-available precedent search: semantic when the index + embedder resolve,
+ * else lexical. Single entry point for callers that want the strongest ranking
+ * without branching on availability themselves.
+ */
+export declare function searchSpecsBest(topic: string, opts: {
+    repoRoot: string;
+    core?: string;
+    limit?: number;
+    embedQuery?: QueryEmbedder;
+    source?: EmbeddingsSource;
+}): Promise<{
+    hits: PrecedentHit[];
+    mode: 'semantic' | 'lexical';
+}>;

package/dist/lib/semantic-search.js

@@ -0,0 +1,56 @@
+import { cosineRank } from './embedding-store.js';
+import { embeddingsSourceFromConfig } from './embeddings-source.js';
+import { searchSpecs } from './precedent-search.js';
+/**
+ * Semantic precedent search over the committed embedding index. Returns ranked
+ * hits, or null when the index is absent OR the embedder can't produce a query
+ * vector — callers then fall back to the always-on lexical {@link searchSpecs}.
+ *
+ * Validated: qwen3-embedding:0.6b + the query instruction prefix lifts paraphrase
+ * recall to 7/8 (lexical 4/8) while holding exact@5 at 8/8. The lexical layer
+ * stays the zero-dependency baseline (CI / no-Ollama environments).
+ */
+export async function searchSpecsSemantic(topic, opts) {
+    const index = (opts.source ?? embeddingsSourceFromConfig(opts.repoRoot)).loadIndex();
+    if (!index)
+        return null;
+    const qv = await opts.embedQuery(topic);
+    if (!qv)
+        return null;
+    const ranked = cosineRank(qv, index);
+    const hits = ranked.map((h) => ({
+        id: h.id,
+        title: h.title,
+        file: h.file,
+        core: h.id.split('-')[0]?.toLowerCase() ?? '',
+        status: 'unknown',
+        score: h.score,
+        matchedFields: ['semantic'],
+    }));
+    return typeof opts.limit === 'number' ? hits.slice(0, opts.limit) : hits;
+}
+/**
+ * Best-available precedent search: semantic when the index + embedder resolve,
+ * else lexical. Single entry point for callers that want the strongest ranking
+ * without branching on availability themselves.
+ */
+export async function searchSpecsBest(topic, opts) {
+    if (opts.embedQuery) {
+        const semantic = await searchSpecsSemantic(topic, {
+            repoRoot: opts.repoRoot,
+            limit: opts.limit,
+            embedQuery: opts.embedQuery,
+            source: opts.source,
+        });
+        // Core filtering on semantic hits (id-prefix based) when a core is requested.
+        if (semantic) {
+            const filtered = opts.core ? semantic.filter((h) => h.core === opts.core.toLowerCase()) : semantic;
+            return { hits: filtered, mode: 'semantic' };
+        }
+    }
+    return {
+        hits: searchSpecs(topic, { repoRoot: opts.repoRoot, core: opts.core, limit: opts.limit }),
+        mode: 'lexical',
+    };
+}
+//# sourceMappingURL=semantic-search.js.map

package/dist/lib/semantic-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-search.js","sourceRoot":"","sources":["../../src/lib/semantic-search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAyB,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAqB,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKvE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAa,EACb,IAOC;IAED,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,0BAA0B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;IACrF,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAErB,MAAM,MAAM,GAAkB,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACpD,MAAM,IAAI,GAAmB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9C,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE;QAC7C,MAAM,EAAE,SAAS;QACjB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,aAAa,EAAE,CAAC,UAAU,CAAC;KAC5B,CAAC,CAAC,CAAC;IACJ,OAAO,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAa,EACb,IAAgH;IAEhH,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE;YAChD,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;QACH,8EAA8E;QAC9E,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;YACpG,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,OAAO;QACL,IAAI,EAAE,WAAW,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACzF,IAAI,EAAE,SAAS;KAChB,CAAC;AACJ,CAAC"}

package/dist/lib/session-state.d.ts

@@ -0,0 +1,8 @@
+export type SessionState = {
+    specId: string;
+    currentTask: string;
+};
+/** Parse STATE.md text into a session pointer, or null if no in-progress task. Never throws. */
+export declare function parseSessionState(text: string): SessionState | null;
+/** Read `.cursor/session/STATE.md` (gitignored, optional). Returns null if absent/unparseable. */
+export declare function readSessionState(repoRoot: string): SessionState | null;

package/dist/lib/session-state.js

@@ -0,0 +1,25 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const SPEC_RE = /\*\*Spec(?:\s*ID)?:\*\*\s*([A-Z]{2,3}-\d+(?:[A-Z0-9-]*)?)/i;
+const TASK_RE = /\*\*Current task:\*\*\s*(T\d+)\b/i;
+/** Parse STATE.md text into a session pointer, or null if no in-progress task. Never throws. */
+export function parseSessionState(text) {
+    const spec = SPEC_RE.exec(text)?.[1];
+    const task = TASK_RE.exec(text)?.[1];
+    if (!spec || !task)
+        return null;
+    return { specId: spec.toUpperCase(), currentTask: task.toUpperCase() };
+}
+/** Read `.cursor/session/STATE.md` (gitignored, optional). Returns null if absent/unparseable. */
+export function readSessionState(repoRoot) {
+    const path = join(repoRoot, '.cursor', 'session', 'STATE.md');
+    if (!existsSync(path))
+        return null;
+    try {
+        return parseSessionState(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=session-state.js.map