@enwithai/product-check 0.1.0-alpha.0 → 0.2.0

package/dist/reporting/spec-markdown.js

@@ -0,0 +1,144 @@
+import { code, md } from "./escape.js";
+const TAG = {
+    observed: "observed",
+    inferred: "inferred",
+    hypothesis: "needs confirmation",
+};
+/** Renders the as-built spec. */
+export function renderAsBuiltSpec(spec) {
+    const byId = new Map(spec.surface.map((s) => [s.id, s]));
+    const loc = (s) => code(`${s.location.path}${s.location.line ? `:${s.location.line}` : ""}`);
+    const sources = (r) => {
+        const items = r.surface_ids.map((id) => byId.get(id)).filter((s) => s !== undefined);
+        if (items.length === 0)
+            return r.evidence_ids.length ? ` Evidence: ${r.evidence_ids.join(", ")}.` : "";
+        const shown = items.slice(0, 3).map(loc).join(", ");
+        return ` Source: ${shown}${items.length > 3 ? ` and ${items.length - 3} more` : ""}.`;
+    };
+    // Statements are escaped where they are built (src/spec/build.ts), so they are printed as they are.
+    const text = (r) => r.statement;
+    const line = (r) => `- **${r.id}**: ${text(r)} _(${TAG[r.certainty]})_${sources(r)}`;
+    const date = spec.generated_at.slice(0, 10);
+    const out = [
+        `# Feature Specification: ${md(spec.target.name)} (as built)`,
+        "",
+        "**Feature Branch**: `000-as-built`",
+        "",
+        `**Created**: ${date}`,
+        "",
+        "**Status**: Draft (reverse-engineered)",
+        "",
+        `**Input**: Repository ${code(spec.target.repository)}${spec.target.commit ? ` at commit ${code(spec.target.commit.slice(0, 12))}` : " (no git commit recorded)"}, read by Product Check ${code(spec.tool.version)}`,
+        "",
+        "> **Reverse-engineered, not authored.** Product Check derived this specification from the repository's structure",
+        "> without running it. _observed_ statements point at a file and line; _inferred_ ones interpret what was found;",
+        "> anything the code cannot tell us is marked `NEEDS CLARIFICATION`. Confirm or correct each statement before",
+        "> treating this as the product's specification.",
+        "",
+        "## User Scenarios & Testing _(mandatory)_",
+        "",
+    ];
+    if (spec.stories.length === 0)
+        out.push("No pages or endpoints were recognised, so no user stories could be derived.", "");
+    for (const s of spec.stories) {
+        out.push(`### User Story ${s.id.slice(3)} - ${md(s.title)} (Priority: ${s.critical_journey ? "P1" : "P2"})`, "", `**Purpose**: [NEEDS CLARIFICATION: who uses the ${md(s.title)} area, and what outcome must it deliver?]`, "");
+        if (s.critical_journey)
+            out.push(`Declared critical journey: ${md(s.critical_journey)}.`, "");
+        out.push(`Covers ${s.requirement_ids.join(", ")}.`, "");
+        if (s.test_behaviours.length > 0) {
+            out.push("**Behaviour described by tests** _(inferred; convert to Given/When/Then once confirmed)_:", "");
+            for (const t of s.test_behaviours.slice(0, 15))
+                out.push(`- ${md(t)}`);
+            if (s.test_behaviours.length > 15)
+                out.push(`- … and ${s.test_behaviours.length - 15} more`);
+            out.push("");
+        }
+    }
+    const storyTests = new Set(spec.stories.flatMap((s) => s.surface_ids));
+    const loose = spec.surface.filter((x) => x.kind === "test" && !storyTests.has(x.id));
+    if (loose.length > 0) {
+        out.push("### Other behaviour described by tests _(inferred)_", "");
+        for (const t of loose.slice(0, 40))
+            out.push(`- ${md(t.name)} (${loc(t)})`);
+        if (loose.length > 40)
+            out.push(`- … and ${loose.length - 40} more`);
+        out.push("");
+    }
+    out.push("### Edge Cases", "");
+    if (spec.edge_cases.length === 0)
+        out.push("- [NEEDS CLARIFICATION: no edge or error cases could be found in the repository]");
+    for (const e of spec.edge_cases)
+        out.push(`- ${text(e)} _(${TAG[e.certainty]})_`);
+    out.push("", "## Requirements _(mandatory)_", "", "### Functional Requirements", "");
+    if (spec.requirements.length === 0)
+        out.push("- [NEEDS CLARIFICATION: no functional surface was recognised]");
+    for (const r of spec.requirements)
+        out.push(line(r));
+    out.push("", "### Non-Functional Requirements", "");
+    for (const r of spec.non_functional)
+        out.push(line(r));
+    const entities = new Map();
+    for (const e of spec.surface.filter((s) => s.kind === "entity"))
+        entities.set(e.name.toLowerCase(), [...(entities.get(e.name.toLowerCase()) ?? []), e]);
+    if (entities.size > 0) {
+        out.push("", "### Key Entities", "");
+        for (const group of entities.values()) {
+            const best = group.find((g) => g.detail.startsWith("fields:")) ?? group[0];
+            out.push(`- **${md(best.name)}**: ${md(best.detail)} (${group.map(loc).join(", ")})`);
+        }
+    }
+    out.push("", "## Success Criteria _(mandatory)_", "");
+    for (const r of spec.success_criteria)
+        out.push(line(r));
+    out.push("", "## Clarifications needed", "");
+    for (const c of spec.clarifications)
+        out.push(`- ${md(c)}`);
+    out.push("", "## Uncertainties", "");
+    for (const u of spec.uncertainties)
+        out.push(`- ${md(u)}`);
+    out.push("", "## Appendix: as-built surface", "");
+    const table = (title, kind, cols, head) => {
+        const rows = spec.surface.filter((s) => s.kind === kind);
+        if (rows.length === 0)
+            return;
+        out.push(`### ${title}`, "", `| ${head.join(" | ")} |`, `|${head.map(() => "---").join("|")}|`);
+        for (const r of rows)
+            out.push(`| ${cols(r).join(" | ")} |`);
+        out.push("");
+    };
+    table("Pages", "page", (s) => [code(s.name), md(s.detail), loc(s), s.auth_hint ? "yes (inferred)" : "—"], [
+        "Route",
+        "Kind",
+        "Source",
+        "Auth helper",
+    ]);
+    table("Endpoints", "endpoint", (s) => [
+        code(s.method ?? "ANY"),
+        code(s.name),
+        md(s.detail),
+        loc(s),
+        s.auth_hint ? "yes (inferred)" : "—",
+    ], ["Method", "Path", "Kind", "Source", "Auth helper"]);
+    table("Data entities", "entity", (s) => [code(s.name), md(s.detail), loc(s)], [
+        "Entity",
+        "Detail",
+        "Source",
+    ]);
+    table("Integrations", "integration", (s) => [code(s.name), md(s.detail), loc(s)], [
+        "Package",
+        "Category",
+        "Declared in",
+    ]);
+    table("Configuration (names only)", "config", (s) => [code(s.name), md(s.detail), loc(s)], [
+        "Variable",
+        "Use",
+        "First reference",
+    ]);
+    table("Authentication boundaries", "auth-boundary", (s) => [code(s.name), md(s.detail), loc(s)], [
+        "Boundary",
+        "Detail",
+        "Source",
+    ]);
+    out.push(`Generated ${spec.generated_at} · ${spec.surface.length} surface item(s) · ${spec.evidence.length} evidence item(s) in as-built-spec.json`, "");
+    return out.join("\n");
+}

package/dist/run.d.ts

@@ -20,5 +20,7 @@ export interface RunOutput {
     results: Results;
     observations: ObservationSet | null;
 }
+/** Run ID: UTC timestamp plus a short hash of the contract and start time. */
+export declare function makeRunId(started: Date, contract: ScanContract): string;
 /** Runs one assessment. */
 export declare function runAssessment(options: RunOptions): Promise<RunOutput>;

package/dist/run.js

@@ -10,13 +10,17 @@ import { isAbsolute, relative, sep } from "node:path";
 import { snapshotRepo } from "./discovery/repo.js";
 import { buildPops, popCoverage } from "./discovery/pops.js";
 import { inputError } from "./errors.js";
+import { readYaml } from "./parse/yaml.js";
 import { EvidenceCollector } from "./evidence/collector.js";
 import { harToObservations } from "./importers/har.js";
-import { parseImpactCheck, parseNpmAudit, parseOutcomeCheck, parseSpecCheck } from "./importers/reports.js";
+import { parseAlertRules, parseOpenSlo, parseServiceGraph } from "./importers/operational.js";
+import { parseArchitectureCheck, parseImpactCheck, parseNpmAudit, parseOutcomeCheck, parseSpecCheck, } from "./importers/reports.js";
 import { parseTestResults } from "./importers/tests.js";
 import { probe } from "./inspectors/http/fetch.js";
 import { deriveFacts } from "./inspectors/source/facts.js";
+import { deriveSurface } from "./inspectors/source/surface.js";
 import { buildBlueprint } from "./blueprint/build.js";
+import { buildAsBuiltSpec } from "./spec/build.js";
 import { formatErrors, validateAgainst } from "./schema/registry.js";
 import { computeScorecard, isOpen } from "./scoring/score.js";
 import { computeVerdict } from "./scoring/verdict.js";
@@ -57,8 +61,25 @@ function importReport(path, label, parse) {
     const { data, sha } = readJson(path);
     return { data: parse(data, label(path)), source: label(path), sha256: sha };
 }
+/**
+ * Imports a set of YAML/JSON files through one parser. The source lists every file; the checksum covers all of them
+ * in order.
+ */
+function importYamlSet(paths, label, parse) {
+    if (paths.length === 0)
+        return null;
+    const files = paths.map((path) => {
+        const { text, sha } = readInput(path);
+        return { source: label(path), docs: readYaml(text, label(path)), sha };
+    });
+    return {
+        data: parse(files),
+        source: files.map((f) => f.source).join(", "),
+        sha256: files.length === 1 ? (files[0]?.sha ?? "") : sha256(files.map((f) => f.sha).join("\n")),
+    };
+}
 /** Run ID: UTC timestamp plus a short hash of the contract and start time. */
-function makeRunId(started, contract) {
+export function makeRunId(started, contract) {
     const stamp = started
         .toISOString()
         .replace(/[-:]/g, "")
@@ -193,6 +214,14 @@ export async function runAssessment(options) {
     const spec = aborted ? null : importReport(contract.imports.spec_check, label, parseSpecCheck);
     const impact = aborted ? null : importReport(contract.imports.impact_check, label, parseImpactCheck);
     const outcome = aborted ? null : importReport(contract.imports.outcome_check, label, parseOutcomeCheck);
+    const architecture = aborted
+        ? null
+        : importReport(contract.imports.architecture_check, label, parseArchitectureCheck);
+    const openslo = aborted ? null : importYamlSet(contract.imports.openslo, label, parseOpenSlo);
+    const alertRules = aborted ? null : importYamlSet(contract.imports.alert_rules, label, parseAlertRules);
+    const serviceGraph = aborted
+        ? null
+        : importReport(contract.imports.service_graph, label, parseServiceGraph);
     phases.push({
         phase: "TEST",
         status: aborted ? "SKIPPED" : "COMPLETED",
@@ -204,6 +233,10 @@ export async function runAssessment(options) {
                 spec && "Spec Check report imported",
                 impact && "Impact Check report imported",
                 outcome && "Outcome Check report imported",
+                architecture && "Architecture Check report imported",
+                openslo && `OpenSLO imported (${openslo.data.slos.length} SLO(s))`,
+                alertRules && `alert rules imported (${alertRules.data.alerting.length} alerting rule(s))`,
+                serviceGraph && `service graph imported (${serviceGraph.data.edges.length} edge(s))`,
             ].filter((x) => typeof x === "string"),
         ],
     });
@@ -220,6 +253,7 @@ export async function runAssessment(options) {
         auditImported: audit !== null,
         specImported: spec !== null,
         outcomeImported: outcome !== null,
+        operationalImported: openslo !== null || alertRules !== null || serviceGraph !== null,
         aiInScope,
         tier,
         now: startedIso,
@@ -237,6 +271,10 @@ export async function runAssessment(options) {
         spec,
         impact,
         outcome,
+        architecture,
+        openslo,
+        alertRules,
+        serviceGraph,
         baseline: options.baseline?.results ?? null,
         aiInScope,
     };
@@ -294,6 +332,17 @@ export async function runAssessment(options) {
     }
     findings.sort((a, b) => ["P0", "P1", "P2", "P3"].indexOf(a.severity) - ["P0", "P1", "P2", "P3"].indexOf(b.severity) ||
         (a.id < b.id ? -1 : 1));
+    // ------------------------------------------------------------------ AS-BUILT SPEC (same snapshot, same evidence)
+    const asBuilt = repo && contract.target.repository
+        ? buildAsBuiltSpec({
+            contract,
+            facts: repo,
+            surface: deriveSurface(repo),
+            ev,
+            repository: label(contract.target.repository.path),
+            generatedAt: startedIso,
+        })
+        : null;
     // ------------------------------------------------------------------ BLUEPRINT
     const blueprint = buildBlueprint({
         contract,
@@ -307,6 +356,7 @@ export async function runAssessment(options) {
         hasBaseline: options.baseline !== null,
         testsImported: tests.length > 0,
         aiInScope,
+        asBuilt,
     });
     const previous = options.baseline?.results.history.at(-1) ?? null;
     const scorecard = computeScorecard(validations, findings, contract.scoring, previous);

package/dist/schema/registry.js

@@ -16,6 +16,7 @@ export const KIND_SCHEMA = {
     blueprint: "blueprint.schema.json",
     "release-verdict": "release-verdict.schema.json",
     observations: "observations.schema.json",
+    "as-built-spec": "as-built-spec.schema.json",
 };
 let cached = null;
 /** Lazily loads the bundled schemas. */

package/dist/scoring/score.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: 2026 EnWithAI Technologies
 /**
- * Scorecard computation (rubric pc-rubric-0.1). Pure and deterministic, so `product-check validate` can recompute
+ * Scorecard computation (rubric pc-rubric-0.2). Pure and deterministic, so `product-check validate` can recompute
  * it from validations and findings and detect hand-edited figures.
  *
  * - Customer, Technology and Trust are scored separately; there is no composite score.

package/dist/spec/build.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Builds an as-built specification from the discovered product surface. The spec states what the repository
+ * structurally provides (pages, endpoints, entities, integrations, configuration) with evidence for each statement,
+ * marks interpretations as inferred, and leaves everything the code cannot tell us (purpose, users, priorities,
+ * measurable targets) as explicit `[NEEDS CLARIFICATION: …]` markers for a person to resolve. No intent is invented.
+ *
+ * Statements are Markdown: every repository-derived string inside them is escaped here (`code` or `md`), so the
+ * renderer can print them as they are.
+ */
+import type { EvidenceCollector } from "../evidence/collector.js";
+import type { RepoFacts } from "../inspectors/source/facts.js";
+import type { ProductSurface } from "../inspectors/source/surface.js";
+import type { AsBuiltBody, AsBuiltSpec, Results, ScanContract } from "../types.js";
+/** Inputs for the as-built spec. */
+export interface SpecInput {
+    contract: ScanContract;
+    facts: RepoFacts;
+    surface: ProductSurface;
+    ev: EvidenceCollector;
+    repository: string;
+    generatedAt: string;
+}
+/** Builds the as-built specification. */
+export declare function buildAsBuiltSpec(input: SpecInput): AsBuiltSpec;
+/** The part of a spec that is embedded in the blueprint. */
+export declare function asBuiltBody(spec: AsBuiltSpec): AsBuiltBody;
+/** Rebuilds the standalone as-built spec from a results document (null when source was not inspected). */
+export declare function specFromResults(r: Results): AsBuiltSpec | null;

package/dist/spec/build.js

@@ -0,0 +1,278 @@
+import { SCHEMA_VERSION } from "../types.js";
+import { code, md } from "../reporting/escape.js";
+import { stableId } from "../util/hash.js";
+import { TOOL_VERSION } from "../version.js";
+const EDGE_HINT = /\b(invalid|reject|error|unauthori[sz]ed|forbidden|denied|expired|missing|empty|fail|not found|duplicate|limit|isolat)/i;
+const RATE_LIMIT = /^(express-rate-limit|@upstash\/ratelimit|rate-limiter-flexible|@fastify\/rate-limit|slowapi)$/;
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const where = (s) => code(`${s.location.path}${s.location.line ? `:${s.location.line}` : ""}`);
+/** Builds the as-built specification. */
+export function buildAsBuiltSpec(input) {
+    const { facts, surface, ev, contract } = input;
+    const revision = facts.snapshot.git.commit;
+    // ------------------------------------------------------------- surface with evidence
+    const entryOf = (item) => {
+        const integration = item.kind === "integration";
+        const evidenceId = ev.add({
+            kind: integration ? "manifest-field" : "source-location",
+            pop: integration ? "dependency-manifests" : item.kind === "test" ? "automated-tests" : "repository",
+            strength: item.certainty === "observed" ? "static" : "inferred",
+            provenance: item.certainty,
+            locator: item.path,
+            line: item.line,
+            revision,
+            summary: `${item.kind} ${item.method ? `${item.method} ` : ""}${item.name}: ${item.detail}`,
+            excerpt: item.excerpt,
+            checksum: facts.snapshot.byPath.get(item.path)?.sha256 ?? null,
+        });
+        return {
+            id: stableId("SRF", [item.kind, item.method, item.name, item.path], 10),
+            kind: item.kind,
+            name: item.name,
+            method: item.method,
+            area: item.area,
+            detail: item.detail,
+            location: { path: item.path, line: item.line },
+            certainty: item.certainty,
+            auth_hint: item.auth_hint,
+            evidence_ids: [evidenceId],
+        };
+    };
+    const entries = surface.items.map(entryOf);
+    const ofKind = (k) => entries.filter((e) => e.kind === k);
+    const locEv = (path, line, summary, pop = "repository") => ev.add({
+        kind: "source-location",
+        pop,
+        strength: "static",
+        provenance: "observed",
+        locator: path,
+        line,
+        revision,
+        summary,
+        checksum: facts.snapshot.byPath.get(path)?.sha256 ?? null,
+    });
+    const requirements = [];
+    const clarifications = [];
+    const fr = (statement, certainty, items) => {
+        const id = `FR-${String(requirements.length + 1).padStart(3, "0")}`;
+        requirements.push({
+            id,
+            statement,
+            certainty,
+            surface_ids: items.map((i) => i.id),
+            evidence_ids: [...new Set(items.flatMap((i) => i.evidence_ids))].sort(),
+        });
+        return id;
+    };
+    // ------------------------------------------------------------- stories per route area
+    const routes = [...ofKind("page"), ...ofKind("endpoint")];
+    const areas = [...new Set(routes.map((r) => r.area))].sort((a, b) => a === "home" ? -1 : b === "home" ? 1 : cmp(a, b));
+    const tests = ofKind("test");
+    const usedTests = new Set();
+    const journeys = contract.critical_journeys;
+    const matchedJourneys = new Set();
+    const stories = [];
+    for (const area of areas) {
+        const members = routes
+            .filter((r) => r.area === area)
+            .sort((a, b) => (a.kind === b.kind ? 0 : a.kind === "page" ? -1 : 1) || cmp(a.name, b.name));
+        const ids = [];
+        for (const r of members) {
+            if (r.kind === "page")
+                ids.push(fr(`The system MUST serve the page ${code(r.name)}.${r.auth_hint ? " Its source references an authentication helper, so access is likely limited to signed-in users." : ""}`, r.auth_hint ? "inferred" : r.certainty, [r]));
+            else
+                ids.push(fr(`The system MUST handle ${r.method === "ANY" ? "requests of any method" : `${code(r.method ?? "ANY")} requests`} to ${code(r.name)}.${r.auth_hint ? " The handler references an authentication helper, so access is likely limited to signed-in users." : ""}`, r.auth_hint ? "inferred" : r.certainty, [r]));
+        }
+        // Match on a crude stem ("notes" → "note") so singular and plural mentions both count.
+        const stem = area.replace(/[^a-z0-9]/gi, "").replace(/(?<=.{3})s$/i, "");
+        const word = new RegExp(`\\b${stem}`, "i");
+        const matchable = area !== "home" && stem.length >= 3;
+        const behaviours = tests
+            .filter((t) => matchable && (word.test(t.name) || word.test(t.location.path)))
+            .map((t) => {
+            usedTests.add(t.id);
+            return t;
+        });
+        const journey = matchable ? (journeys.find((j) => word.test(j)) ?? null) : null;
+        if (journey)
+            matchedJourneys.add(journey);
+        const label = area === "home" ? "Home and top-level pages" : `${area.charAt(0).toUpperCase()}${area.slice(1)}`;
+        stories.push({
+            id: `US-${stories.length + 1}`,
+            area,
+            title: label,
+            critical_journey: journey,
+            surface_ids: [...members, ...behaviours].map((m) => m.id),
+            requirement_ids: ids,
+            test_behaviours: behaviours.map((b) => b.name),
+        });
+        clarifications.push(`Purpose of the ${label} area: who uses it, and what outcome it must deliver.`);
+    }
+    for (const j of journeys)
+        if (!matchedJourneys.has(j))
+            clarifications.push(`Critical journey "${j}" is declared in the scan contract but no discovered route matches it.`);
+    // ------------------------------------------------------------- entities, integrations, configuration, auth
+    const entities = new Map();
+    for (const e of ofKind("entity"))
+        entities.set(e.name.toLowerCase(), [...(entities.get(e.name.toLowerCase()) ?? []), e]);
+    for (const group of entities.values()) {
+        const first = group[0];
+        const fields = group.find((g) => g.detail.startsWith("fields:"));
+        fr(`The system MUST persist ${code(first.name)} records${fields || group.length > 1
+            ? ` (${[fields ? md(fields.detail) : "", group.length > 1 ? `defined in ${group.length} places` : ""].filter(Boolean).join("; ")})`
+            : ""}.`, "observed", group);
+    }
+    for (const i of ofKind("integration"))
+        fr(`The system MUST integrate with ${code(i.name)} (${md(i.detail)}).`, "observed", [i]);
+    const config = ofKind("config");
+    if (config.length > 0) {
+        const browser = config.filter((c) => c.detail.startsWith("exposed"));
+        fr(`The system MUST be configured through ${config.length} environment variable(s): ${config.map((c) => code(c.name)).join(", ")}.${browser.length > 0 ? ` ${browser.map((c) => code(c.name)).join(", ")} ${browser.length === 1 ? "is" : "are"} exposed to the browser bundle and MUST NOT hold secrets.` : ""}`, "observed", config);
+    }
+    for (const a of ofKind("auth-boundary"))
+        fr(`Requests MUST pass through ${code(a.name)} before reaching application routes (${code(a.detail)}).`, "inferred", [a]);
+    // ------------------------------------------------------------- non-functional (observed only) + gaps
+    const nfr = [];
+    const addNfr = (statement, certainty, evidence) => {
+        nfr.push({
+            id: `NFR-${String(nfr.length + 1).padStart(3, "0")}`,
+            statement,
+            certainty,
+            surface_ids: [],
+            evidence_ids: evidence,
+        });
+    };
+    for (const r of facts.runtimeDecl)
+        addNfr(`The system MUST run on the declared runtime (${code(r.detail)}).`, "observed", [
+            locEv(r.path, r.line, `runtime declaration: ${r.detail}`),
+        ]);
+    for (const h of facts.headerConfig)
+        addNfr(`Responses MUST carry the HTTP headers configured in ${code(h.path)} (${md(h.detail)}).`, "observed", [locEv(h.path, h.line, `header configuration: ${h.detail}`)]);
+    const rateLimit = [...facts.deps.keys()].filter((d) => RATE_LIMIT.test(d)).sort();
+    for (const d of rateLimit) {
+        const m = facts.deps.get(d);
+        addNfr(`Requests MUST be rate-limited (${code(d)}).`, "inferred", [
+            locEv(m?.manifest ?? "package.json", null, `dependency ${d}`, "dependency-manifests"),
+        ]);
+    }
+    for (const gap of [
+        "response-time and throughput targets for the main pages and endpoints",
+        "availability target and acceptable downtime",
+        "how long personal and business data is kept, and how it is deleted",
+    ])
+        addNfr(`[NEEDS CLARIFICATION: ${gap}]`, "hypothesis", []);
+    // ------------------------------------------------------------- edge cases
+    const edges = [];
+    const addEdge = (statement, certainty, items, evidence = []) => {
+        edges.push({
+            id: `EC-${String(edges.length + 1).padStart(3, "0")}`,
+            statement,
+            certainty,
+            surface_ids: items.map((i) => i.id),
+            evidence_ids: [...new Set([...evidence, ...items.flatMap((i) => i.evidence_ids)])].sort(),
+        });
+    };
+    for (const p of facts.notFoundPages)
+        addEdge("Requests for unknown routes show a dedicated not-found page.", "observed", [], [locEv(p, 1, "not-found page", "repository")]);
+    for (const t of tests.filter((x) => EDGE_HINT.test(x.name)))
+        addEdge(`A test describes this case: ${md(t.name)} (${where(t)}).`, "inferred", [t]);
+    // ------------------------------------------------------------- success criteria
+    const success = [
+        {
+            id: "SC-001",
+            statement: "[NEEDS CLARIFICATION: measurable outcomes cannot be derived from source code; state the targets this product must meet]",
+            certainty: "hypothesis",
+            surface_ids: [],
+            evidence_ids: [],
+        },
+    ];
+    if (facts.e2eFiles.length > 0)
+        success.push({
+            id: "SC-002",
+            statement: `The ${facts.e2eFiles.length} end-to-end test file(s) pass on every release candidate (for example ${code(facts.e2eFiles[0] ?? "")}).`,
+            certainty: "inferred",
+            surface_ids: [],
+            evidence_ids: [locEv(facts.e2eFiles[0], null, "end-to-end test file", "automated-tests")],
+        });
+    // ------------------------------------------------------------- uncertainties
+    const uncertainties = [
+        "Purpose, users, priorities and business rules are not derivable from code; every story carries a clarification for them.",
+        "Nothing was executed: requirements describe what the code declares, not verified behaviour.",
+        ...(tests.length > 0 && usedTests.size < tests.length
+            ? [
+                `${tests.length - usedTests.size} test title(s) could not be matched to a route area and are listed separately.`,
+            ]
+            : []),
+        ...surface.notes,
+    ];
+    const limitations = facts.snapshot.limitations;
+    return {
+        schema_version: SCHEMA_VERSION,
+        kind: "as-built-spec",
+        generated_at: input.generatedAt,
+        tool: { name: "product-check", version: TOOL_VERSION },
+        target: {
+            name: contract.target.name,
+            repository: input.repository,
+            commit: revision,
+            ref: facts.snapshot.git.ref ?? null,
+        },
+        surface: entries,
+        stories,
+        requirements,
+        non_functional: nfr,
+        success_criteria: success,
+        edge_cases: edges,
+        clarifications,
+        uncertainties,
+        evidence: referencedEvidence(ev.all(), {
+            surface: entries,
+            requirements,
+            non_functional: nfr,
+            success_criteria: success,
+            edge_cases: edges,
+        }),
+        limitations,
+    };
+}
+/** The evidence items a spec references (a shared collector may hold others, for example during `run`). */
+function referencedEvidence(all, parts) {
+    const ids = new Set([
+        parts.surface,
+        parts.requirements,
+        parts.non_functional,
+        parts.success_criteria,
+        parts.edge_cases,
+    ].flatMap((list) => list.flatMap((x) => x.evidence_ids)));
+    return all.filter((e) => ids.has(e.id));
+}
+/** The part of a spec that is embedded in the blueprint. */
+export function asBuiltBody(spec) {
+    return {
+        surface: spec.surface,
+        stories: spec.stories,
+        requirements: spec.requirements,
+        non_functional: spec.non_functional,
+        success_criteria: spec.success_criteria,
+        edge_cases: spec.edge_cases,
+        clarifications: spec.clarifications,
+        uncertainties: spec.uncertainties,
+    };
+}
+/** Rebuilds the standalone as-built spec from a results document (null when source was not inspected). */
+export function specFromResults(r) {
+    const body = r.blueprint.as_is.as_built;
+    const repo = r.run.target_revision.repository;
+    if (!body || !repo)
+        return null;
+    return {
+        schema_version: SCHEMA_VERSION,
+        kind: "as-built-spec",
+        generated_at: r.run.started_at,
+        tool: { name: "product-check", version: r.run.tool_version },
+        target: { name: r.contract.target.name, repository: repo.label, commit: repo.commit, ref: repo.ref },
+        ...body,
+        evidence: referencedEvidence(r.evidence, body),
+        limitations: r.limitations,
+    };
+}