@bigsteele/the-prospect 0.1.1 → 0.2.0

package/dist/detect/types.d.ts

@@ -27,6 +27,16 @@ export interface DepFact {
     required_by?: string;
     /** True when no import, config mention, script, or package requiring it was found. */
     no_reference_found: boolean;
+    /** A recorded decision that explains it, when one does. On record is not a deduction. */
+    on_record?: OnRecord;
+    /** Which workflow this touches, by path. A heuristic, named as one. */
+    touches?: string;
+}
+/** Where the decision record explains a finding. */
+export interface OnRecord {
+    file: string;
+    line: number;
+    excerpt: string;
 }
 export type VendorCategory = "ai" | "email" | "sms" | "payments" | "database" | "auth" | "storage" | "crm" | "analytics" | "monitoring" | "render" | "search" | "queue" | "maps" | "calendar" | "hosting" | "ci" | "other";
 /** One external service the code talks to, with the evidence. */
@@ -46,6 +56,7 @@ export interface OverlapFact {
     category: VendorCategory;
     services: string[];
     call_sites: number;
+    on_record?: OnRecord;
 }
 export type RailCategory = "pdf" | "rate-limiting" | "email-templating" | "auth-session" | "queue-scheduler" | "search" | "payments-logic" | "webhook-plumbing" | "parsing-ocr";
 /** A subsystem built by hand where the market sells a rail. */
@@ -60,6 +71,8 @@ export interface HandrolledFact {
         file: string;
         line: string;
     };
+    on_record?: OnRecord;
+    touches?: string;
 }
 /** A cluster of near-identical code living in more than one file. */
 export interface DuplicateFact {
@@ -70,6 +83,15 @@ export interface DuplicateFact {
     deliberate: boolean;
     /** First normalized line of the block, so a reader can find it. */
     opens_with: string;
+    /**
+     * The files sit at the same relative path under sibling directories of an
+     * adapters/templates tree: parallel implementations for different stacks,
+     * which duplicate by design because a generated file cannot import from the
+     * generator. Reported, never deducted.
+     */
+    parallel?: boolean;
+    on_record?: OnRecord;
+    touches?: string;
 }
 /** A runtime file no entrypoint reaches. */
 export interface DeadFact {
@@ -77,6 +99,8 @@ export interface DeadFact {
     loc: number;
     /** Why the detector believes nothing reaches it. */
     note: string;
+    on_record?: OnRecord;
+    touches?: string;
 }
 /** A call whose cost multiplies: per request, per row, or on a clock. */
 export interface CostFact {
@@ -104,3 +128,22 @@ export interface NorthStar {
     confidence: "high" | "low" | "unknown";
     note: string;
 }
+/** A shape in the migrations worth a human minute. Never a verdict. */
+export interface DatabaseFinding {
+    kind: "table_without_rls" | "rls_not_forced" | "definer_without_check" | "policy_reaches_anon";
+    /** The table, function or policy, schema-qualified where it has one. */
+    subject: string;
+    file: string;
+    note: string;
+}
+/**
+ * What the migrations hold. The counts ride with the findings on purpose: an
+ * empty finding list and a scan that never opened a file must not read alike.
+ */
+export interface DatabaseReading {
+    files: number;
+    tables: number;
+    policies: number;
+    definer_functions: number;
+    findings: DatabaseFinding[];
+}

package/dist/detect/vendors.js

@@ -1,4 +1,4 @@
-import { runtimeCode } from "../walk.js";
+import { scopeFor, isCode } from "../walk.js";
 /** The map earns a row when a vendor is common enough that a founder would
  *  recognise the name. Everything else lands in "unrecognised outbound". */
 const KNOWN = [
@@ -56,7 +56,7 @@ const KNOWN = [
 /** Hosts that are content, not services: fonts, CDNs of the app's own assets, social links. */
 const NOISE_HOST = /(^|\.)(esm\.sh|cdn\.jsdelivr\.net|unpkg\.com|fonts\.(googleapis|gstatic)\.com|githubusercontent\.com|github\.com|linkedin\.com|x\.com|twitter\.com|instagram\.com|facebook\.com|youtube\.com|tiktok\.com|schema\.org|w3\.org|localhost)$/i;
 export async function detectVendors(repo) {
-    const files = runtimeCode(repo.files);
+    const files = scopeFor(repo.files, "vendor-presence").filter(isCode);
     const byService = new Map();
     const touch = (k, kind, what, file) => {
         const v = byService.get(k.service) ?? { service: k.service, category: k.category, evidence: [], call_sites: 0 };
@@ -71,8 +71,13 @@ export async function detectVendors(repo) {
         const text = await repo.read(f);
         if (!text)
             continue;
-        for (const m of text.matchAll(/\bfrom\s+["']([^"'\n]+)["']|\brequire\(\s*["']([^"'\n]+)["']\s*\)/g)) {
-            const spec = (m[1] ?? m[2]);
+        // LANGUAGE-NEUTRAL IMPORTS (0.2). The vendor table is already neutral - an
+        // SDK name, a host, an env var - and only the extraction was JavaScript, so
+        // a Python service importing `stripe` read as using no payment vendor at
+        // all. Python `import x` / `from x import y`, Go's quoted import paths and
+        // Ruby's `require` all name the package the same way npm does.
+        for (const m of text.matchAll(/\bfrom\s+["']([^"'\n]+)["']|\brequire\(\s*["']([^"'\n]+)["']\s*\)|^\s*import\s+([a-z0-9_.]+)|^\s*from\s+([a-z0-9_.]+)\s+import\b|^\s*require\s+["']([^"'\n]+)["']/gim)) {
+            const spec = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5]);
             if (spec.startsWith("."))
                 continue;
             const pkg = spec.replace(/^npm:/, "").split("/").slice(0, spec.startsWith("@") || spec.startsWith("npm:@") ? 2 : 1).join("/");
@@ -93,8 +98,10 @@ export async function detectVendors(repo) {
                 unknownHosts.set(host, set);
             }
         }
-        for (const m of text.matchAll(/process\.env\.([A-Z][A-Z0-9_]{2,})|Deno\.env\.get\(\s*["']([A-Z][A-Z0-9_]{2,})["']\s*\)/g)) {
-            const name = (m[1] ?? m[2]);
+        // Same reasoning for environment variables: `os.environ["STRIPE_SECRET_KEY"]`
+        // and `os.getenv(...)` name a vendor exactly as `process.env.` does.
+        for (const m of text.matchAll(/process\.env\.([A-Z][A-Z0-9_]{2,})|Deno\.env\.get\(\s*["']([A-Z][A-Z0-9_]{2,})["']\s*\)|os\.(?:environ(?:\.get)?\(?\[?|getenv\()\s*["']([A-Z][A-Z0-9_]{2,})["']|ENV\[["']([A-Z][A-Z0-9_]{2,})["']\]|os\.Getenv\(\s*["']([A-Z][A-Z0-9_]{2,})["']/g)) {
+            const name = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5]);
             for (const k of KNOWN)
                 if (k.env?.test(name))
                     touch(k, "env", name, f);

package/dist/index.d.ts

@@ -1,6 +1,9 @@
+import { type Coverage } from "./walk.js";
 import { type StackReading } from "./detect/stack.js";
+import { type RepoProfile } from "./profile.js";
+import { type DecisionRecord } from "./decisions.js";
 import { type ProspectScore } from "./score.js";
-import type { CostFact, DeadFact, DepFact, DuplicateFact, Fingerprint, HandrolledFact, NorthStar, OverlapFact, VendorFact } from "./detect/types.js";
+import type { CostFact, DeadFact, DepFact, DatabaseReading, DuplicateFact, Fingerprint, HandrolledFact, NorthStar, OverlapFact, VendorFact } from "./detect/types.js";
 export { toMarkdown, secretShaped } from "./report.js";
 export { checkReport } from "./check.js";
 export type { ProspectScore } from "./score.js";
@@ -24,6 +27,14 @@ export interface Prospect {
     dead: DeadFact[];
     cost_surfaces: CostFact[];
     fingerprint: Fingerprint;
+    /** What the migrations hold, and the shapes in them worth a minute. */
+    database: DatabaseReading;
+    /** What kind of repository this is, and which questions it could answer. */
+    profile: RepoProfile;
+    /** The decision record that was read, so "on record" can be checked. */
+    decisions: DecisionRecord;
+    /** Every file walked, in exactly one bucket, each with the rule that put it there. */
+    coverage: Coverage;
     score: ProspectScore;
     totals: {
         files: number;
@@ -32,5 +43,5 @@ export interface Prospect {
         entrypoints: number;
     };
 }
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.2.0";
 export declare function runProspect(root: string): Promise<Prospect>;

package/dist/index.js

@@ -20,7 +20,7 @@
  * run, or required.
  */
 import { openRepo } from "./walk.js";
-import { runtimeCode } from "./walk.js";
+import { runtimeCode, coverageOf } from "./walk.js";
 import { detectDeps } from "./detect/deps.js";
 import { detectVendors } from "./detect/vendors.js";
 import { detectHandrolled } from "./detect/handrolled.js";
@@ -29,11 +29,14 @@ import { detectDeadweight } from "./detect/deadweight.js";
 import { detectCosts } from "./detect/costs.js";
 import { detectFingerprint } from "./detect/fingerprint.js";
 import { detectStack } from "./detect/stack.js";
+import { detectDatabase } from "./detect/database.js";
 import { readNorthStar } from "./northstar.js";
+import { profileRepo } from "./profile.js";
+import { Decisions, touches } from "./decisions.js";
 import { scoreProspect } from "./score.js";
 export { toMarkdown, secretShaped } from "./report.js";
 export { checkReport } from "./check.js";
-export const VERSION = "0.1.1";
+export const VERSION = "0.2.0";
 export async function runProspect(root) {
     const repo = await openRepo(root);
     const runtime = runtimeCode(repo.files);
@@ -48,13 +51,69 @@ export async function runProspect(root) {
         readNorthStar(repo),
         detectStack(repo),
     ]);
+    const database = await detectDatabase(repo);
+    // READ WHAT WAS DECIDED BEFORE REPORTING WHAT WAS BUILT (0.2). Every Lane 1
+    // finding is checked against the record; one the record explains is marked
+    // on record with the citation, listed so the reader sees the tool looked, and
+    // not deducted. A dependency loaded by name, a copy inlined on purpose, a
+    // second vendor kept on purpose: each was reported as drift before this.
+    const record = await Decisions.read(repo);
+    const few = record.critical_few;
+    // A file is named to the record by its path fragment, never its bare stem:
+    // `session` matches half the record, `shell-templates/react/src/session` does not.
+    const frag = (f) => {
+        const parts = f.replace(/\.tmpl$/, "").split("/");
+        const stem = parts.pop().replace(/\.[^.]+$/, "");
+        const dir = parts.pop();
+        return dir ? [`${dir}/${stem}`, f] : [stem, f];
+    };
+    for (const d of deps) {
+        if (!d.no_reference_found)
+            continue;
+        d.on_record = record.explains([d.name]) ?? undefined;
+        d.touches = touches(d.manifest, few);
+    }
+    // A pair is decided by an entry naming BOTH sides: "Vercel's nameservers"
+    // alone is not a decision to run Vercel beside Cloudflare.
+    for (const o of vendorsReading.overlaps)
+        o.on_record = record.explains(o.services, { all: true }) ?? undefined;
+    for (const o of stack.overlaps)
+        o.on_record = record.explains(o.services, { all: true }) ?? undefined;
+    for (const c of stack.consolidations)
+        c.on_record = record.explains([c.candidate, c.keep], { all: true }) ?? undefined;
+    for (const h of handrolled) {
+        h.on_record = record.explains(h.files.flatMap(frag)) ?? undefined;
+        h.touches = touches(h.files[0] ?? "", few);
+    }
+    for (const d of duplicates) {
+        // Parallel adapters are explained structurally; the record is not consulted.
+        d.on_record = d.parallel ? undefined : record.explains(d.files.flatMap(frag)) ?? undefined;
+        d.touches = touches(d.files[0] ?? "", few);
+    }
+    for (const d of deadReading.dead) {
+        d.on_record = record.explains(frag(d.file)) ?? undefined;
+        d.touches = touches(d.file, few);
+    }
+    // Last, and after every detector, so the ledger describes the run that just
+    // happened rather than a plan for one.
+    const coverage = await coverageOf(repo);
     // A vendor SDK that is DECLARED but never referenced is a bill with no
     // work behind it - the score's hardest floor.
     const vendorSdkNames = new Set(vendorsReading.vendors.flatMap((v) => v.evidence.filter((e) => e.kind === "sdk").map((e) => e.what)));
     const unusedPaid = deps.find((d) => !d.dev && d.no_reference_found && /^(openai|stripe|twilio|resend|@sendgrid\/|@anthropic-ai\/|@clerk\/|algoliasearch|cloudinary)/.test(d.name))?.name ?? null;
     void vendorSdkNames;
+    // The profile reads the repository's SHAPE, and it runs after the detectors
+    // because it needs to know what they found ground for: a question with no
+    // ground is recorded as not applicable rather than answered "nothing found",
+    // which is how a six-file scraper scored 96 out of 100.
+    const profile = profileRepo(repo, {
+        sqlFiles: database.files,
+        manifestDeps: deps.length,
+        analysed: coverage.analysed,
+    });
     const allOverlaps = [...vendorsReading.overlaps, ...stack.overlaps];
     const score = scoreProspect({
+        not_asked: profile.not_applicable.map((n) => n.question),
         deps,
         overlaps: allOverlaps,
         consolidations: stack.consolidations,
@@ -82,6 +141,10 @@ export async function runProspect(root) {
         dead: deadReading.dead,
         cost_surfaces: costs,
         fingerprint,
+        database,
+        profile,
+        decisions: record.toJSON(),
+        coverage,
         score,
         totals: {
             files: repo.files.length,

package/dist/northstar.js

@@ -3,17 +3,30 @@
 // this package's own lean fixture as the host's North Star, which is the
 // exact self-contamination bug the family review caught in wiremap.
 const UNKNOWN_NOTE = "No North Star found. The protocol derives one with the operator before any suggestion is written; without it, neither lane can tell overbuilt from essential.";
+/**
+ * The FIRST PARAGRAPH under the heading, not the whole section. The section is
+ * the sentence plus everything written to explain it, and joining the lot
+ * printed "Read it from the README's fir" - the sentence, the provenance note,
+ * and a truncation mid-word. The sentence is the first paragraph; the rest is
+ * for a person.
+ */
 function section(md, heading) {
     const lines = md.split("\n");
     const at = lines.findIndex((l) => /^#{1,4}\s/.test(l) && heading.test(l));
     if (at < 0)
         return null;
     const body = [];
+    let started = false;
     for (const l of lines.slice(at + 1)) {
         if (/^#{1,4}\s/.test(l))
             break;
-        if (l.trim())
-            body.push(l.trim());
+        if (!l.trim()) {
+            if (started)
+                break;
+            continue;
+        }
+        started = true;
+        body.push(l.trim());
     }
     return body.length ? body.join(" ") : null;
 }

package/dist/profile.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What kind of repository is this, and which questions can honestly be asked of it.
+ *
+ * THE DEFECT THIS EXISTS FOR. The detectors encoded one repository's
+ * assumptions - npm manifests, Postgres migrations, a `caller-check:` marker
+ * convention - and then applied them everywhere. Run across five repositories of
+ * different shapes, coverage swung from 38% to 79% and a six-file scraper scored
+ * **96 out of 100**, because a question that could not be asked returned nothing
+ * found, and nothing found scored as healthy.
+ *
+ * That is the same failure the rest of this version is about, one level up. A
+ * check that reports the same whether it works or not is worthless; a SCAN that
+ * reports the same whether it looked or not is worse, because it carries a
+ * number. "No dependencies with no reference found" means one thing after
+ * reading a 68-package manifest and something else entirely when no manifest was
+ * found at all, and the report said it identically both ways.
+ *
+ * SO: profile first, then ask only what the ground supports, and say out loud
+ * which questions were not asked and why. A question skipped honestly costs
+ * nothing. A question skipped silently becomes a score.
+ */
+import type { Repo } from "./walk.js";
+export interface NotApplicable {
+    question: string;
+    why: string;
+}
+export interface RepoProfile {
+    /** Languages by weight of code files, most first. */
+    languages: string[];
+    /** Dependency manifests found, by filename. */
+    manifests: string[];
+    /** Shapes recognised: monorepo, migrations, containers, workflows, and so on. */
+    traits: string[];
+    /** Questions the repository can actually answer. */
+    questions_asked: string[];
+    /** Questions with no ground to stand on, each with the reason. */
+    not_applicable: NotApplicable[];
+    /**
+     * How much of a reading this is. A six-file scraper examined completely and a
+     * 4,000-file monorepo examined completely are both "complete" and are not the
+     * same evidence, so the report says which it is holding.
+     */
+    depth: {
+        code_files: number;
+        analysed_share: number;
+        /** thin | partial | substantial - the weight a reader should give the result. */
+        reading: "thin" | "partial" | "substantial";
+        why: string;
+    };
+}
+export declare function profileRepo(repo: Repo, seen: {
+    sqlFiles: number;
+    manifestDeps: number;
+    analysed: number;
+}): RepoProfile;

package/dist/profile.js

@@ -0,0 +1,106 @@
+import { baseName, isCode } from "./walk.js";
+const MANIFESTS = [
+    { file: /(^|\/)package\.json$/, lang: "javascript", name: "package.json" },
+    { file: /(^|\/)requirements\.txt$/, lang: "python", name: "requirements.txt" },
+    { file: /(^|\/)pyproject\.toml$/, lang: "python", name: "pyproject.toml" },
+    { file: /(^|\/)Pipfile$/, lang: "python", name: "Pipfile" },
+    { file: /(^|\/)go\.mod$/, lang: "go", name: "go.mod" },
+    { file: /(^|\/)Cargo\.toml$/, lang: "rust", name: "Cargo.toml" },
+    { file: /(^|\/)Gemfile$/, lang: "ruby", name: "Gemfile" },
+    { file: /(^|\/)composer\.json$/, lang: "php", name: "composer.json" },
+    { file: /(^|\/)pubspec\.yaml$/, lang: "dart", name: "pubspec.yaml" },
+    { file: /(^|\/)(pom\.xml|build\.gradle(\.kts)?)$/, lang: "java", name: "pom.xml / build.gradle" },
+];
+const EXT_LANG = [
+    [/\.(ts|tsx|js|jsx|mjs|cjs)$/i, "javascript"],
+    [/\.py$/i, "python"],
+    [/\.go$/i, "go"],
+    [/\.rs$/i, "rust"],
+    [/\.rb$/i, "ruby"],
+    [/\.php$/i, "php"],
+    [/\.(java|kt)$/i, "java"],
+    [/\.swift$/i, "swift"],
+    [/\.(vue|svelte|astro)$/i, "javascript"],
+];
+export function profileRepo(repo, seen) {
+    const code = repo.files.filter(isCode);
+    const weight = new Map();
+    for (const f of code) {
+        for (const [re, lang] of EXT_LANG) {
+            if (re.test(baseName(f))) {
+                weight.set(lang, (weight.get(lang) ?? 0) + 1);
+                break;
+            }
+        }
+    }
+    const languages = [...weight.entries()].sort((a, b) => b[1] - a[1]).map(([l]) => l);
+    const manifests = [];
+    for (const m of MANIFESTS) {
+        if (repo.files.some((f) => m.file.test(f) && !/node_modules/.test(f)))
+            manifests.push(m.name);
+    }
+    const traits = [];
+    if (repo.files.some((f) => /(^|\/)(packages|apps)\//.test(f)))
+        traits.push("monorepo");
+    if (seen.sqlFiles > 0)
+        traits.push("sql-migrations");
+    if (repo.files.some((f) => /(^|\/)Dockerfile$/.test(f)))
+        traits.push("containers");
+    if (repo.files.some((f) => /^\.github\/workflows\//.test(f)))
+        traits.push("ci-workflows");
+    if (repo.files.some((f) => /(^|\/)(terraform|\.tf)$|\.tf$/.test(f)))
+        traits.push("infra-as-code");
+    // A question is asked when the repository holds the thing it asks about.
+    // Anything else is recorded as not applicable, with the reason, and does not
+    // reach the score.
+    const asked = [];
+    const na = [];
+    const hasManifest = manifests.length > 0;
+    if (hasManifest && seen.manifestDeps > 0)
+        asked.push("dependencies");
+    else {
+        na.push({
+            question: "dependencies",
+            why: hasManifest
+                ? "a manifest was found and declares no runtime dependencies, so there is nothing to find unreferenced"
+                : "no dependency manifest of any recognised kind, so 'a package nothing references' has no ground to stand on",
+        });
+    }
+    if (seen.sqlFiles > 0)
+        asked.push("database");
+    else {
+        na.push({
+            question: "database",
+            why: "no SQL migrations, so row-level security and definer functions cannot be read from this repository. The database may still exist and be managed elsewhere.",
+        });
+    }
+    if (code.length >= 12)
+        asked.push("duplication", "reachability");
+    else {
+        na.push({
+            question: "duplication and reachability",
+            why: `only ${code.length} code file(s): too few for a duplicate block or an unreached module to mean anything`,
+        });
+    }
+    if (code.length > 0)
+        asked.push("vendors", "implementation");
+    const share = repo.files.length ? seen.analysed / repo.files.length : 0;
+    const reading = code.length < 15 ? "thin" : code.length < 150 || share < 0.4 ? "partial" : "substantial";
+    return {
+        languages,
+        manifests,
+        traits,
+        questions_asked: asked,
+        not_applicable: na,
+        depth: {
+            code_files: code.length,
+            analysed_share: Math.round(share * 100) / 100,
+            reading,
+            why: reading === "thin"
+                ? `${code.length} code files. A clean result here means there was little to examine, not that a large system was examined and found clean.`
+                : reading === "partial"
+                    ? `${code.length} code files, ${Math.round(share * 100)}% of the repository analysed. Enough to be worth reading, not enough to be exhaustive.`
+                    : `${code.length} code files, ${Math.round(share * 100)}% of the repository analysed.`,
+        },
+    };
+}

package/dist/report.js

@@ -38,29 +38,113 @@ export function toMarkdown(p) {
     else {
         L.push(claims.slice(0, 2).join(", and ") + ".", "");
     }
-    L.push(`## Today / After`, "");
-    L.push(`| Today | After |`);
-    L.push(`| --- | --- |`);
-    if (noRef.length)
-        L.push(`| ${noRef.length} packages installed, updated and audited that nothing imports | They are gone, and every install, update and security audit is smaller |`);
-    if (p.overlaps.length) {
-        const o = p.overlaps[0];
-        L.push(`| ${prose(o.services)} ${o.services.length > 2 ? "all" : "both"} do ${label(o.category)} work | One vendor does it, one invoice, one integration to maintain |`);
+    // NEXT ACTIONS, NOT TODAY/AFTER (0.2). The Big Sean ends every finding with
+    // the workflow it protects, who does it, and how long; the Today/After table
+    // ended with "Suggestions arrive as opinions". A reader acts on the first
+    // shape and skims the second. Only what is NOT on record reaches this list.
+    const actions = [];
+    for (const d of noRef.filter((x) => !x.on_record).slice(0, 3)) {
+        actions.push({
+            what: `\`${d.name}\` is declared in \`${d.manifest}\` and nothing references it`,
+            touches: d.touches ?? "",
+            task: `grep the repository for its name outside \`${d.manifest}\`; if nothing loads it by name at runtime, remove it`,
+            retest: "install, build and run the test suite with it gone",
+        });
     }
-    if (highHand.length) {
-        const h = highHand[0];
-        L.push(`| ${h.loc} lines of hand-rolled ${h.rail} code you maintain alone | A decision on record: keep it on purpose, or a rail carries it |`);
+    for (const o of p.overlaps.filter((x) => !x.on_record)) {
+        actions.push({
+            what: `${prose(o.services)} both do ${label(o.category)} work`,
+            touches: "one bill and one failure surface per vendor",
+            task: `name which one carries this job, or record in DECISIONS.md why both stay`,
+            retest: "the next scan lists the pair under On record",
+        });
     }
-    if (cuts.length) {
-        const c = cuts[0];
-        L.push(`| ${c.candidate} runs beside ${c.keep}, which already covers ${c.covers.split(" (")[0]} | One platform, one bill, one place a deploy can fail |`);
+    for (const h of highHand.filter((x) => !x.on_record)) {
+        actions.push({
+            what: `${h.loc} lines of hand-rolled ${h.rail} in \`${h.signal.file}\``,
+            touches: h.touches ?? "",
+            task: "decide once: keep it on purpose and record why, or let a rail carry it (Lane 2 names the rails)",
+            retest: "the decision appears in the record, or the subsystem is gone",
+        });
+    }
+    const bigAccidental = accidental.filter((d) => !d.parallel && !d.on_record).slice(0, 2);
+    for (const d of bigAccidental) {
+        actions.push({
+            what: `${d.lines} lines repeated across ${d.files.length} files, opening \`${d.opens_with.slice(0, 60)}\``,
+            touches: d.touches ?? "",
+            task: "lift to one place, or mark the copy deliberate in its header",
+            retest: "the cluster is gone from the next scan",
+        });
+    }
+    if (actions.length) {
+        L.push(`## Your next actions`, "");
+        L.push(`Only what no recorded decision explains. Each names the workflow it touches - by path, a heuristic - and how to know it is done.`, "");
+        actions.forEach((a, i) => {
+            L.push(`### ${i + 1}. ${a.what}`);
+            L.push(`**Touches.** ${a.touches}`);
+            L.push(`**Task.** ${a.task}`);
+            L.push(`**Retest.** ${a.retest}`, "");
+        });
+    }
+    // ON RECORD. What the scan found and the record already explains. Listed so
+    // the reader sees the tool looked, and charged nothing.
+    const onRecord = [];
+    for (const d of noRef.filter((x) => x.on_record))
+        onRecord.push({ what: `\`${d.name}\` shows no reference`, where: `${d.on_record.file}:${d.on_record.line} - ${d.on_record.excerpt}` });
+    for (const o of p.overlaps.filter((x) => x.on_record))
+        onRecord.push({ what: `${prose(o.services)} both do ${label(o.category)} work`, where: `${o.on_record.file}:${o.on_record.line} - ${o.on_record.excerpt}` });
+    for (const c of cuts.filter((x) => x.on_record))
+        onRecord.push({ what: `${c.candidate} beside ${c.keep}`, where: `${c.on_record.file}:${c.on_record.line} - ${c.on_record.excerpt}` });
+    for (const h of highHand.filter((x) => x.on_record))
+        onRecord.push({ what: `hand-rolled ${h.rail}`, where: `${h.on_record.file}:${h.on_record.line} - ${h.on_record.excerpt}` });
+    for (const d of accidental.filter((x) => x.on_record))
+        onRecord.push({ what: `${d.lines} lines shared by ${d.files.map((f) => f.split("/").pop()).join(", ")}`, where: `${d.on_record.file}:${d.on_record.line} - ${d.on_record.excerpt}` });
+    const parallels = p.duplicates.filter((d) => d.parallel);
+    if (onRecord.length || parallels.length) {
+        L.push(`## On record`, "");
+        // Say what the record EXPLAINED, not what was read. An empty table under "already
+        // explained by CHECKPOINT-QUEUE.md" told the owner their notes covered the findings
+        // when they did not - and the gap between what a record holds and what the scan
+        // found is itself the useful fact here.
+        const explainedBy = [...new Set(onRecord.map((r) => r.where.split(":")[0]))];
+        L.push(onRecord.length
+            ? `Found, and already explained by ${explainedBy.slice(0, 3).map((f) => `\`${f}\``).join(", ")}. Nothing here costs points.`
+            : `${p.decisions.files.length} decision file(s) read, ${p.decisions.entries} lines. None explains a finding above: what the scan found is not yet on the record, which is the case for a line in DECISIONS.md rather than a fix.`, "");
+        if (onRecord.length) {
+            L.push(`| Finding | Where it is decided |`, `| --- | --- |`);
+            for (const r of onRecord)
+                L.push(`| ${r.what} | ${r.where.replace(/\|/g, "\\|")} |`);
+            L.push("");
+        }
+        if (parallels.length) {
+            const total = parallels.reduce((t, d) => t + d.lines * (d.files.length - 1), 0);
+            L.push(`${parallels.length} parallel adapter block(s), ${total} lines in total, at the same relative path under sibling adapter directories. A generated file cannot import from the generator, so these duplicate by design; the one question is whether the generator could render them from a single partial.`, "");
+        }
+    }
+    // UNKNOWN. What the scan could not settle, stated rather than scored.
+    const unknowns = [];
+    if (p.north_star.confidence !== "high")
+        unknowns.push(`the North Star: ${p.north_star.note}`);
+    if (!p.decisions.files.length)
+        unknowns.push("whether any of the above is on purpose: no decision record was found (DECISIONS.md, ADRs, CLAUDE.md), so nothing could be marked on record");
+    for (const n of p.profile.not_applicable)
+        unknowns.push(`${n.question}: ${n.why}`);
+    if (unknowns.length) {
+        L.push(`## Unknown`, "");
+        for (const u of unknowns)
+            L.push(`- ${u}`);
+        L.push("");
     }
-    if (p.dead.length)
-        L.push(`| ${p.dead.length} files everyone reads, searches and ships but nothing runs | Deleted, with this report as the receipt |`);
-    L.push(`| Suggestions arrive as opinions | Every suggestion stands on a fact in your code, a sourced fact from your market, and your North Star |`);
-    L.push("");
     L.push(`## Score`, "");
     L.push(`**${p.score.total}/100 (${p.score.grade})** - Level ${p.score.level.n}: **${p.score.level.name}**. ${p.score.level.meaning}`, "");
+    // THE NUMBER NEVER TRAVELS ALONE (0.2). 96/100 on a six-file scraper and
+    // 96/100 on a four-thousand-file monorepo are not the same claim, and the
+    // report used to print them identically.
+    L.push(`_${p.profile.depth.why}_`, "");
+    if (p.score.not_asked.length) {
+        L.push(`**Not asked of this repository:** ${p.score.not_asked.join(", ")}. ` +
+            `Neither credited nor penalised - see What was read.`, "");
+    }
     for (const f of p.score.floors)
         L.push(`- ${f}`);
     if (p.score.floors.length)
@@ -72,6 +156,62 @@ export function toMarkdown(p) {
             L.push(`| ${d.what} | ${d.points} | ${d.evidence} |`);
         L.push("");
     }
+    // THE LEDGER GOES BEFORE THE FINDINGS (0.2). A reader deciding how much to
+    // trust a list of findings needs to know what was looked at to produce it, and
+    // the honest answer used to be unavailable: the scan read 473 of 2,077 files
+    // on the first repository it met and had no way to say so.
+    const c = p.coverage;
+    L.push(`## What was read`, "");
+    const pr = p.profile;
+    L.push(`A ${pr.languages[0] ?? "mixed"} repository` +
+        (pr.languages.length > 1 ? ` (also ${pr.languages.slice(1, 3).join(", ")})` : "") +
+        (pr.manifests.length ? `, declaring dependencies in ${pr.manifests.join(" and ")}` : `, with no dependency manifest found`) +
+        (pr.traits.length ? `. Shapes recognised: ${pr.traits.join(", ")}.` : "."), "");
+    if (pr.not_applicable.length) {
+        L.push(`Questions with no ground to stand on here:`, "");
+        for (const n of pr.not_applicable)
+            L.push(`- **${n.question}** - ${n.why}`);
+        L.push("");
+    }
+    L.push(`**${c.analysed} of ${c.walked} files analysed.** ` +
+        `${c.unreadable} unreadable (binaries and files over the size cap), ` +
+        `${c.walked - c.analysed - c.unreadable} excluded by a named rule, ` +
+        `${c.unaccounted} unaccounted for.`, "");
+    if (c.excluded.length) {
+        L.push(`| Excluded | Files | Why |`);
+        L.push(`| --- | --- | --- |`);
+        for (const e of c.excluded)
+            L.push(`| \`${e.rule}\` | ${e.files} | ${e.why} |`);
+        L.push("");
+    }
+    if (c.unclaimed.length) {
+        L.push(`Readable file classes no question claims. Some of these are right to ignore; ` +
+            `the list is here so the choice is visible rather than assumed.`, "");
+        for (const u of c.unclaimed) {
+            L.push(`- \`${u.ext}\` - ${u.files} files, none analysed (e.g. \`${u.examples[0] ?? ""}\`)`);
+        }
+        L.push("");
+    }
+    const db = p.database;
+    if (db.files > 0) {
+        L.push(`### The database`, "");
+        L.push(`${db.files} migration file(s): ${db.tables} table(s), ${db.policies} policy/policies, ` +
+            `${db.definer_functions} function(s) running as definer. ` +
+            (db.findings.length === 0
+                ? `Nothing below stood out.`
+                : `${db.findings.length} shape(s) worth a minute.`), "");
+        if (db.findings.length) {
+            L.push(`| Shape | Subject | Where |`);
+            L.push(`| --- | --- | --- |`);
+            for (const x of db.findings.slice(0, 15)) {
+                L.push(`| ${x.kind.replace(/_/g, " ")} | \`${x.subject}\` | \`${x.file}\` |`);
+            }
+            if (db.findings.length > 15)
+                L.push(`| ...and ${db.findings.length - 15} more | | in the JSON |`);
+            L.push("");
+            L.push(db.findings[0].note, "");
+        }
+    }
     L.push(`## North Star`, "");
     if (p.north_star.sentence) {
         L.push(`> ${p.north_star.sentence}`, "");