@bigsteele/the-prospect 0.1.1 → 0.3.0

package/README.md

@@ -48,32 +48,55 @@ Step 0 runs offline, reads everything, and writes two files into your repo:
 - **Your industry fingerprint** - the domain vocabulary your own schema and
   routes use, which is what the second half researches against.
 
-Then:
+Step 0 takes seconds, and it is a hypothesis machine: it reads shapes and
+prints them, every one with an id. The read is the second command.
 
 ```
-npx @bigsteele/the-prospect --run
+npx @bigsteele/the-prospect --run        # or --protocol, to paste THE-PROSPECT.md into any agent
 ```
 
-opens Claude Code with the research protocol. It confirms your vertical
-with you, researches the actual vendor and API landscape with sources and
-dates, verifies every stack-cut pair against the kept platform's current
-plan, and fills Lane 2: at most five suggestions, each in a fixed shape -
-*Since you* (a fact from your code, file cited), *Have you considered*
-(always two options, or one vendor against building it yourself), *Because*
-(the industry fact, with a source URL and the year it was checked), *Your
-customer gets* (the benefit in the customer's terms), *First test* (a
-one-week test needing nobody's permission, and the observation that would
-kill the idea).
-
-A suggestion missing any leg is cut, not softened. And:
+This is a large read, not a quick check, and it says so before it starts.
+Claude Code opens with the protocol and the agent, read-only: establishes
+your North Star from the pricing page, the schema and the code before it
+judges anything; takes every Step 0 finding to the code and rules on it,
+CONFIRMED with evidence, REFUTED with the sentence that names the shape
+that lied, ON_RECORD with the deciding line, or UNKNOWN with what would
+settle it; walks the whole tree for the inventories the scan cannot finish
+on its own - every vendor with the job it does and whose money it touches,
+every subsystem built by hand and what keeping it buys, every dependency's
+job, every unreached file's real status, every multiplying call with a
+price where one is public, the database rulings against the grants, and
+the shape of the bill; researches your market in five lanes with sources
+and dates; ranks everything against the North Star; and writes
+**The Prospect - <App Name>.md** at the repository root with the next ten
+actions, the inventories in full, the evidence register, and the math.
+
+Every suggestion keeps the fixed shape - *Since you* (a fact from your
+code, file cited), *Have you considered* (always two options, or one vendor
+against building it yourself), *Because* (the industry fact, with a source
+URL and the year it was checked), *Your customer gets* (the benefit in the
+customer's terms), *First test* (a one-week test needing nobody's
+permission, and the observation that would kill the idea). A suggestion
+missing any leg is cut, not softened. And:
 
 ```
 npx @bigsteele/the-prospect --check
 ```
 
-fails the finished report mechanically if it breaks the law: unsourced
-claims, undated claims, single-vendor pitches, advice verbs, missing legs.
-Exit 0 when it holds, 2 when it does not.
+is the second opinion. It reads the deliverable and
+`.planning/prospect/VERDICTS.json`, fails any finding without a ruling,
+any ruling without evidence, any evidence the report does not show, any
+unsourced or undated claim, any single-vendor pitch, any advice verb, and
+recomputes the score from the verdicts with the math printed: a refuted
+finding costs nothing, a recorded one costs nothing, an unknown one still
+does. Exit 0 when it holds, 2 when it does not.
+
+The scan's Lane 1 is calibrated on real repositories and the calibration
+notes say what it got wrong and when it was fixed: a category is not a job
+(Stripe running Connect beside Square billing the platform is two jobs),
+one `.ilike()` is not a search engine, a socket is not a paid call, a
+`revoke ... from anon, authenticated` in a migration is a caller check, and
+a shadcn component nobody imports is scaffold, weighed a quarter.
 
 ## Standalone
 

package/dist/check.js

@@ -37,8 +37,9 @@ export function checkReport(md) {
         findings.push({ where: "whole report", problem: "no [READ] badge - the repository half is missing or unmarked" });
     }
     // Lane 2: each suggestion block (### heading under the territory section).
-    const lane2Heading = /^## .*territory.*$/im.exec(md)?.[0] ?? "";
-    const lane2 = md.split(/^## .*territory.*$/im)[1]?.split(/^## /m)[0] ?? "";
+    // Step 0 titles the lane "what the territory holds"; the protocol's deliverable titles it "Lane 2, researched".
+    const lane2Heading = /^## .*(territory|lane 2).*$/im.exec(md)?.[0] ?? "";
+    const lane2 = md.split(/^## .*(?:territory|lane 2).*$/im)[1]?.split(/^## /m)[0] ?? "";
     const ranProtocol = !/not yet run/i.test(lane2Heading + lane2);
     if (ranProtocol && lane2.trim()) {
         if (!/\[RESEARCHED\]/.test(lane2Heading + lane2)) {

package/dist/cli.js

@@ -17,7 +17,7 @@ import { mkdir, writeFile, readFile, appendFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
-import { runProspect, toMarkdown, secretShaped, checkReport, VERSION } from "./index.js";
+import { runProspect, toMarkdown, secretShaped, checkReport, checkVerdicts, rescore, showMath, VERSION } from "./index.js";
 const log = (s = "") => process.stdout.write(s + "\n");
 const args = process.argv.slice(2);
 const has = (f) => args.includes(f);
@@ -27,15 +27,17 @@ const valueOf = (f) => {
 };
 const HELP = `The Prospect ${VERSION} - a prospector's read of your codebase and your market.
 
-  npx @bigsteele/the-prospect [dir]        Step 0: scan and report (offline, read-only)
-  npx @bigsteele/the-prospect --run        open Claude Code with the research protocol
-  npx @bigsteele/the-prospect --check      fail a finished report that breaks the law
+  npx @bigsteele/the-prospect [dir]        Step 0: scan and report (offline, read-only, seconds)
+  npx @bigsteele/the-prospect --run        open Claude Code with the protocol (the deep read: long)
+  npx @bigsteele/the-prospect --protocol   drop THE-PROSPECT.md into the repo to paste into any agent
+  npx @bigsteele/the-prospect --check      rule on a finished report: verdicts, evidence, legs, the math
 
-  --repo <dir>     the repository to read (default: here)
-  --out <dir>      where the report goes (default: the repository root)
-  --report <file>  the report --check should measure (default: the newest one here)
-  --stdout         print the report instead of writing it
-  --yes            skip the confirmation on --run
+  --repo <dir>       the repository to read (default: here)
+  --out <dir>        where the report goes (default: the repository root)
+  --report <file>    the report --check should measure (default: the deliverable, else the newest scan)
+  --verdicts <file>  the verdicts --check should re-score from (default: .planning/prospect/VERDICTS.json)
+  --stdout           print the report (or, with --protocol, the protocol) instead of writing it
+  --yes              skip the confirmation on --run
 
 Exit 0 when it passes, 2 when it does not, 1 when it refuses.`;
 const slug = (s) => s.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "app";
@@ -47,46 +49,127 @@ async function main() {
     const flagsWithValue = ["--repo", "--out", "--report"];
     const positional = args.find((a) => !a.startsWith("-") && !flagsWithValue.includes(args[args.indexOf(a) - 1] ?? ""));
     const repoDir = resolve(valueOf("--repo") ?? positional ?? process.cwd());
+    const here = dirname(fileURLToPath(import.meta.url));
+    const protocol = resolve(here, "..", "prompt", "THE-PROSPECT.md");
+    if (has("--protocol")) {
+        // The protocol is a file, and the file is the product: drop it where any
+        // agent can read it, the way The Big Sean does.
+        const text = await readFile(protocol, "utf8");
+        if (has("--stdout")) {
+            log(text);
+            return 0;
+        }
+        await writeFile(join(repoDir, "THE-PROSPECT.md"), text, "utf8");
+        log(`Wrote THE-PROSPECT.md. Open Claude Code in this folder and paste the whole file in, or run --run.`);
+        return 0;
+    }
     if (has("--check")) {
         const file = valueOf("--report");
         let path = file ? resolve(file) : "";
         if (!path) {
-            // The newest prospect report beside us.
+            // The deliverable if the protocol wrote one, else the newest Step 0 report.
             const { readdir } = await import("node:fs/promises");
-            const names = (await readdir(repoDir)).filter((n) => /^the-prospect-.*\.md$/.test(n)).sort();
-            if (names.length === 0) {
+            const all = await readdir(repoDir);
+            const deliverable = all.filter((n) => /^The Prospect - .*\.md$/.test(n)).sort();
+            const step0 = all.filter((n) => /^the-prospect-.*\.md$/.test(n)).sort();
+            const pick = deliverable[deliverable.length - 1] ?? step0[step0.length - 1];
+            if (!pick) {
                 log("No report to check. Run the scan first, then the protocol, then this.");
                 return 2;
             }
-            path = join(repoDir, names[names.length - 1]);
+            path = join(repoDir, pick);
         }
         const md = await readFile(path, "utf8");
         const { pass, findings } = checkReport(md);
-        if (pass) {
-            log(`${path} holds the law: every suggestion stands on three legs, every claim carries a source.`);
-            return 0;
-        }
         for (const f of findings)
             log(`FAIL  ${f.where}: ${f.problem}${f.line ? `  | ${f.line}` : ""}`);
+        // THE VERDICTS, WHEN THE PROTOCOL LEFT THEM (0.3). Every Step 0 finding
+        // ruled on, every ruling with evidence, and the score recomputed from the
+        // rulings with the math printed. Missing verdicts fail the check the moment
+        // a verdicts file exists at all: half a ruling is no ruling.
+        const verdictsPath = resolve(valueOf("--verdicts") ?? join(repoDir, ".planning", "prospect", "VERDICTS.json"));
+        let verdictProblems = 0;
+        let scanPath = "";
+        try {
+            const v = JSON.parse(await readFile(verdictsPath, "utf8"));
+            scanPath = v.scan ? resolve(repoDir, v.scan) : "";
+            if (!scanPath) {
+                const { readdir } = await import("node:fs/promises");
+                const names = (await readdir(repoDir)).filter((n) => /^the-prospect-.*\.json$/.test(n)).sort();
+                scanPath = names.length ? join(repoDir, names[names.length - 1]) : "";
+            }
+            if (!scanPath) {
+                log(`FAIL  verdicts: no scan JSON to rule on (the-prospect-<app>.json)`);
+                verdictProblems++;
+            }
+            else {
+                const scan = JSON.parse(await readFile(scanPath, "utf8"));
+                const c = checkVerdicts(scan, v, md);
+                for (const p of c.problems)
+                    log(`FAIL  verdict: ${p}`);
+                verdictProblems = c.problems.length;
+                const r = rescore(scan, v);
+                log("");
+                log(showMath(scan, v, r, c));
+            }
+        }
+        catch (e) {
+            if (e.code !== "ENOENT") {
+                log(`FAIL  verdicts: ${verdictsPath} could not be read: ${e instanceof Error ? e.message : String(e)}`);
+                verdictProblems++;
+            }
+            else if (/^The Prospect - /.test(path.split("/").pop() ?? "")) {
+                log(`FAIL  verdicts: the protocol's deliverable exists but ${verdictsPath} does not; every finding needs a ruling`);
+                verdictProblems++;
+            }
+        }
+        if (pass && verdictProblems === 0) {
+            log("");
+            log(`${path} holds the law: every finding ruled on with evidence, every suggestion on three legs, every claim sourced.`);
+            return 0;
+        }
         log("");
-        log(`${findings.length} finding(s). A suggestion missing a leg is cut, not softened.`);
+        log(`${findings.length + verdictProblems} finding(s). A suggestion missing a leg is cut, not softened; a finding without a ruling is unchecked.`);
         return 2;
     }
     if (has("--run")) {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const protocol = resolve(here, "..", "prompt", "THE-PROSPECT.md");
         if (!has("--yes")) {
             log("");
-            log("This opens Claude Code and asks it to research your industry against Step 0's facts.");
-            log("It reads the scan output, verifies findings in the repository, and searches the web.");
-            log("It changes no source code. Run the scan first so the facts exist. Ctrl-C to stop.");
+            log("BEFORE YOU RUN THIS, KNOW WHAT IT IS. This is a large scan, not a quick check.");
+            log("It opens Claude Code with the protocol: the agent reads everything in this repository it can");
+            log("reach, takes every Step 0 finding to the code and rules on it with evidence, inventories every");
+            log("vendor, subsystem and dependency, researches your market with sources and dates, and writes a");
+            log("long report. Expect a long session and a lot of tokens. It changes nothing: no edits, no commits,");
+            log("no deploys, no messages, no spending. Run the scan first so the facts exist. Ctrl-C to stop.");
             log("");
         }
-        const child = spawn("claude", [`Follow the protocol in ${protocol}. The repository is ${repoDir}.`], {
+        const child = spawn("claude", [`Follow the protocol in ${protocol}, every step, to the end. The repository is ${repoDir}.`], {
             stdio: "inherit",
             shell: false,
         });
-        return new Promise((res) => child.on("exit", (c) => res(c ?? 0)));
+        // THE SUBPROCESS IS A CONVENIENCE, NOT THE PROTOCOL (0.2). Spawning `claude`
+        // couples this package to whatever version is installed, and on 2026-09-13
+        // that failed outright: "Claude Code 2.1.22 does not support this model;
+        // version 2.1.251 or newer is required". A blank error and no research.
+        //
+        // The protocol is a file. Any agent that can read it and search the web can
+        // run it, so a failure here names the file rather than ending the road.
+        child.on("error", () => {
+            log("");
+            log("Could not start Claude Code. It may not be installed, or may be too old.");
+            log(`The protocol is a file, and nothing here depends on that binary:`);
+            log(`  ${protocol}`);
+            log("Open it in any agent that can read your repository and search the web.");
+        });
+        return new Promise((res) => child.on("exit", (c) => {
+            if (c !== 0) {
+                log("");
+                log(`Research did not complete. The protocol is at ${protocol} and can be run by hand:`);
+                log(`  read the-prospect-<app>.json, then follow its six steps.`);
+                log(`If Claude Code reported a version error, \`claude update\` and try again.`);
+            }
+            res(c ?? 0);
+        }));
     }
     const p = await runProspect(repoDir);
     const leak = secretShaped(p);
@@ -119,11 +202,16 @@ async function main() {
     log(`${p.score.total}/100 (${p.score.grade}) - Level ${p.score.level.n}: ${p.score.level.name}.`);
     if (noRef)
         log(`${noRef} of ${p.totals.runtime_deps} runtime dependencies show no reference anywhere.`);
-    if (p.overlaps.length)
-        log(`${p.overlaps.length} categor${p.overlaps.length > 1 ? "ies" : "y"} of work paid for twice.`);
+    const paidTwice = p.overlaps.filter((o) => !o.distinct).length;
+    const twoJobs = p.overlaps.length - paidTwice;
+    if (paidTwice)
+        log(`${paidTwice} categor${paidTwice > 1 ? "ies" : "y"} of work paid for twice.`);
+    if (twoJobs)
+        log(`${twoJobs} vendor pair${twoJobs > 1 ? "s" : ""} sharing a category but doing different jobs: listed, not charged.`);
     if (p.handrolled.length)
         log(`${p.handrolled.length} subsystem(s) built by hand where the market sells a rail.`);
-    log(`Next: npx @bigsteele/the-prospect --run   (the industry half, researched)`);
+    log(`This was the scan: seconds, shapes, every finding with an id. The read is the next command.`);
+    log(`Next: npx @bigsteele/the-prospect --run   (the deep read: every finding ruled on, every vendor and subsystem inventoried, the market researched)`);
     return 0;
 }
 main().then((code) => process.exit(code), (err) => {

package/dist/decisions.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The decision record: what the repository says it decided, read before the
+ * scan reports what it built.
+ *
+ * WHY THIS EXISTS. The Big Sean reads the decision record and reports the
+ * difference between what a repository says and what it does. The Prospect
+ * read no `.md` at all - the ledger listed 415 of them as unclaimed on the first
+ * real repository, and the reasoning that explains the code sat in every one
+ * of them. So a copy inlined on purpose (decision 8: generated code lives in
+ * the customer's repo and cannot import from ours), a second hosting vendor
+ * kept on purpose (decision 19), and a dependency loaded by name all reported
+ * as drift, and all deducted.
+ *
+ * A subtract finding is a finding only when NO recorded decision explains it.
+ * What the record explains is listed as on record - the reader sees the tool
+ * looked, and the score does not charge for a choice somebody made and wrote
+ * down. That is the same rule The Big Sean applies to its own checks: "record
+ * that in DECISIONS.md and leave the check FAIL honestly".
+ *
+ * WHAT COUNTS AS THE RECORD. Files a person wrote to explain choices:
+ * DECISIONS.md and its variants, CLAUDE.md and AGENTS.md (instructions to an
+ * agent are decisions by another name), ADR trees, a `.planning/` directory,
+ * PITFALLS.md, and a prior Big Sean run under `.planning/launch-audit/`. Not
+ * README.md - that is what the product says to buyers, and the North Star reads
+ * it separately. Not `docs/` wholesale - most of it is reference, and a match in
+ * a runbook proves a term was mentioned, not that a choice was made.
+ */
+import type { Repo } from "./walk.js";
+export interface Citation {
+    file: string;
+    line: number;
+    /** The matching line, trimmed to fit a table cell. */
+    excerpt: string;
+}
+export interface DecisionRecord {
+    /** Files read as the record, repository-relative. */
+    files: string[];
+    /** Entries indexed: one per non-empty line. */
+    entries: number;
+    /**
+     * From a prior Big Sean run, when one exists: the workflows the business dies
+     * without, in its order. Used to say which one a finding touches.
+     */
+    critical_few: string[];
+}
+export declare const DECISION_FILES: RegExp;
+export declare class Decisions {
+    private entries;
+    readonly files: string[];
+    readonly critical_few: string[];
+    static read(repo: Repo): Promise<Decisions>;
+    /**
+     * The Big Sean's "critical few" list, when it left one. It is a numbered list
+     * under that heading; the first clause of each item is the workflow's name.
+     */
+    private readCriticalFew;
+    /**
+     * The entry that DECIDES about a subject, or null. A mention is not a decision.
+     *
+     * The first version returned the first line anywhere in the record containing
+     * the word, and on a repository with 8,000 lines of planning notes that cited
+     * "hand-rolled search" to a line about invoice search, `session.ts` to "the
+     * Session pooler URL" and `shell.tsx` to "shell export". The family's oldest
+     * lesson - a name appearing is not the thing being used - arriving inside the
+     * reader written to apply it.
+     *
+     * Three rules, and an entry needs to clear them, not merely match:
+     *
+     *   - WHERE it is said. A row of DECISIONS.md, an ADR, or a rule in CLAUDE.md
+     *     is a decision by construction. A line in a checkpoint queue or a status
+     *     file is context, and counts only when it also SAYS it is deciding.
+     *   - HOW it is said. Outside a decision file, the entry must carry a decision
+     *     word: decided, keep, on purpose, by design, deliberately, chosen, we use.
+     *   - WHAT it names. A pair (two vendors, a kept-and-questioned platform) is
+     *     decided by an entry naming BOTH. A generic file stem - session, shell,
+     *     route, consent, index - is never matched as a bare word; the caller
+     *     passes a path fragment instead.
+     */
+    explains(subjects: string[], opts?: {
+        all?: boolean;
+    }): Citation | null;
+    toJSON(): DecisionRecord;
+}
+/**
+ * Which workflow a path touches - a HEURISTIC, and named as one in the report.
+ *
+ * The Big Sean derives the critical few from the code and the live system, and
+ * every finding it prints says which one it protects. A static scan cannot
+ * derive them, but it can read the path: a file under `billing/` is on the
+ * money path whatever else is true of it. When a prior Big Sean run left its
+ * list, the names come from there; otherwise these are the generic five.
+ */
+export declare function touches(path: string, criticalFew: string[]): string;

package/dist/decisions.js

@@ -0,0 +1,143 @@
+export const DECISION_FILES = /(^|\/)(DECISIONS?|DECISION-LOG|DECISION-REQUESTS?|CLAUDE|AGENTS|PITFALLS|ARCHITECTURE|CONVENTIONS)\.md$|(^|\/)(adr|adrs|decisions)\/[^/]+\.md$|^\.planning\/[^/]+\.md$|^\.planning\/launch-audit\/[^/]+\.md$|^docs\/adr\/[^/]+\.md$/i;
+/** Files that ARE the decision record, as opposed to planning notes that may hold one. */
+const DECISION_PROPER = /(^|\/)(DECISIONS?|DECISION-LOG|CLAUDE|AGENTS|ARCHITECTURE|CONVENTIONS)\.md$|(^|\/)(adr|adrs|decisions)\/[^/]+\.md$|^docs\/adr\/[^/]+\.md$/i;
+/** The words a line uses when it is deciding rather than describing. */
+const DECISION_WORDS = /\b(decided|decision|we (keep|use|chose|run|host)|keep(s|ing)? (it|this|both)|kept|on purpose|deliberate(ly)?|by design|chosen|default(s)? to|stays?\b|do not remove|never imported|copied from)\b/i;
+/** File stems too common to match as a bare word. The caller passes a path fragment. */
+const GENERIC_STEM = /^(session|shell|route|routes|consent|bridge|index|main|app|utils?|config|types?|client|server|handler|grant|mount|events?|api|lib|core|common|base|helpers?|store|state|auth|user|users|data|model|models|service|services|page|pages|layout|search|report|egress)$/i;
+export class Decisions {
+    entries = [];
+    files = [];
+    critical_few = [];
+    static async read(repo) {
+        const d = new Decisions();
+        for (const f of repo.files.filter((x) => DECISION_FILES.test(x))) {
+            const text = await repo.read(f);
+            if (!text)
+                continue;
+            d.files.push(f);
+            text.split("\n").forEach((raw, i) => {
+                const t = raw.trim();
+                if (t.length < 12)
+                    return;
+                d.entries.push({ file: f, line: i + 1, text: t, lower: t.toLowerCase() });
+            });
+        }
+        d.readCriticalFew();
+        return d;
+    }
+    /**
+     * The Big Sean's "critical few" list, when it left one. It is a numbered list
+     * under that heading; the first clause of each item is the workflow's name.
+     */
+    readCriticalFew() {
+        const inList = { on: false, file: "" };
+        for (const e of this.entries) {
+            if (/^#{1,4}\s+the critical few/i.test(e.text)) {
+                inList.on = true;
+                inList.file = e.file;
+                continue;
+            }
+            if (!inList.on || e.file !== inList.file)
+                continue;
+            if (/^#{1,4}\s/.test(e.text))
+                break;
+            const m = /^\d+\.\s+\*\*([^*]+)\*\*/.exec(e.text);
+            if (m)
+                this.critical_few.push(m[1].trim());
+        }
+    }
+    /**
+     * The entry that DECIDES about a subject, or null. A mention is not a decision.
+     *
+     * The first version returned the first line anywhere in the record containing
+     * the word, and on a repository with 8,000 lines of planning notes that cited
+     * "hand-rolled search" to a line about invoice search, `session.ts` to "the
+     * Session pooler URL" and `shell.tsx` to "shell export". The family's oldest
+     * lesson - a name appearing is not the thing being used - arriving inside the
+     * reader written to apply it.
+     *
+     * Three rules, and an entry needs to clear them, not merely match:
+     *
+     *   - WHERE it is said. A row of DECISIONS.md, an ADR, or a rule in CLAUDE.md
+     *     is a decision by construction. A line in a checkpoint queue or a status
+     *     file is context, and counts only when it also SAYS it is deciding.
+     *   - HOW it is said. Outside a decision file, the entry must carry a decision
+     *     word: decided, keep, on purpose, by design, deliberately, chosen, we use.
+     *   - WHAT it names. A pair (two vendors, a kept-and-questioned platform) is
+     *     decided by an entry naming BOTH. A generic file stem - session, shell,
+     *     route, consent, index - is never matched as a bare word; the caller
+     *     passes a path fragment instead.
+     */
+    explains(subjects, opts = {}) {
+        const terms = subjects
+            .map((s) => s.toLowerCase().trim())
+            .filter((s) => s.length >= 4 && !GENERIC_STEM.test(s))
+            .map((s) => new RegExp(`(^|[^a-z0-9_/-])${s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^a-z0-9_-]|$)`));
+        if (terms.length === 0)
+            return null;
+        const need = opts.all ? terms.length : 1;
+        let best = null;
+        for (const e of this.entries) {
+            const hits = terms.filter((re) => re.test(e.lower)).length;
+            if (hits < need)
+                continue;
+            const inDecisionFile = DECISION_PROPER.test(e.file);
+            const decides = DECISION_WORDS.test(e.lower);
+            // A decision file's table rows and headings are decisions; its prose still
+            // has to say so. Outside a decision file, only a line that says so counts.
+            const structural = /^\|/.test(e.text) || /^#{1,4}\s/.test(e.text) || /^\d+\.\s/.test(e.text) || /^[-*]\s/.test(e.text);
+            let strength = 0;
+            if (inDecisionFile && (structural || decides))
+                strength = 3;
+            else if (decides)
+                strength = 2;
+            if (strength === 0)
+                continue;
+            if (!best || strength > best.strength)
+                best = { e, strength };
+            if (strength === 3)
+                break;
+        }
+        if (!best)
+            return null;
+        const t = best.e.text;
+        return { file: best.e.file, line: best.e.line, excerpt: t.length > 140 ? `${t.slice(0, 137)}...` : t };
+    }
+    toJSON() {
+        return { files: this.files, entries: this.entries.length, critical_few: this.critical_few };
+    }
+}
+/**
+ * Which workflow a path touches - a HEURISTIC, and named as one in the report.
+ *
+ * The Big Sean derives the critical few from the code and the live system, and
+ * every finding it prints says which one it protects. A static scan cannot
+ * derive them, but it can read the path: a file under `billing/` is on the
+ * money path whatever else is true of it. When a prior Big Sean run left its
+ * list, the names come from there; otherwise these are the generic five.
+ */
+export function touches(path, criticalFew) {
+    const p = path.toLowerCase();
+    const pick = (re, generic) => {
+        if (!re.test(p))
+            return null;
+        const named = criticalFew.find((c) => re.test(c.toLowerCase()));
+        return named ?? generic;
+    };
+    // The path regex reads the FILE; the name regex reads the Big Sean's list. They
+    // differ because a workflow is named for what it does ("Turn a repository into
+    // a harness") and a path for where it lives (adapters/, generators/).
+    const pickBy = (pathRe, nameRe, generic) => {
+        if (!pathRe.test(p))
+            return null;
+        return criticalFew.find((c) => nameRe.test(c.toLowerCase())) ?? generic;
+    };
+    return (pickBy(/billing|invoice|charge|checkout|payment|dunning|ledger|meter|subscription/, /charge|bill|invoice|meter|pay|revenue|money/, "the money path") ??
+        pickBy(/session|mint|grant|jwks|token|auth|sign-?in|login/, /session|mint|grant|sign|auth|login/, "sign-in and the session") ??
+        pickBy(/migration|rls|policy|tenant|tenancy|isolation/, /tenant|isolat|data away|rls|leak/, "keeping one tenant's data from another") ??
+        pickBy(/adapters?|templates?|generators?|shells?|ingest|\.tmpl$/, /harness|repositor|ingest|generat|adapter|ship/, "what ships into a customer's repository") ??
+        pickBy(/console|landing|pages?\/|components?\/|\.tsx$/, /console|surface|page|screen|ui\b/, "the surface a person uses") ??
+        pickBy(/ops|guard|health|digest|cron|schedule|alert|monitor/, /alert|page|break|monitor|health|uptime/, "knowing when something breaks") ??
+        "no critical workflow this scan can name");
+}

package/dist/detect/costs.js

@@ -1,18 +1,60 @@
-import { runtimeCode } from "../walk.js";
-const PAID_CALL = /\bfetch\(\s*[`"']https?:\/\/(api\.openai\.com|api\.anthropic\.com|generativelanguage\.googleapis\.com|api\.stripe\.com|api\.twilio\.com|api\.resend\.com|api\.sendgrid\.com|api\.cloudflare\.com|api\.replicate\.com|api\.elevenlabs\.io)|\.(messages|completions|chat|embeddings|images)\.create\(|generateContent|\.send(Email|Mail|Sms)?\(/;
-const LOOP_HEAD = /\bfor(\s+await)?\s*\(|\bwhile\s*\(|\.(map|forEach)\(\s*(async\b|\()/;
+import { scopeFor } from "../walk.js";
+/**
+ * A PAID call, which is the whole point (0.2.1). `\.send\(` on its own matched
+ * `ws.send(...)` to a local Chrome DevTools socket in four build scripts, and
+ * the report billed them as four paid loops. A call is paid when it names a
+ * paid host, a paid SDK method, or a sender object that is plainly a mail or
+ * SMS client. A socket is not a vendor.
+ */
+const PAID_CALL = /\bfetch\(\s*[`"']https?:\/\/(api\.openai\.com|api\.anthropic\.com|generativelanguage\.googleapis\.com|api\.stripe\.com|api\.twilio\.com|api\.resend\.com|api\.sendgrid\.com|api\.cloudflare\.com|api\.replicate\.com|api\.elevenlabs\.io)|\.(messages|completions|chat|embeddings|images|predictions)\.create\(|generateContent|\b(sendEmail|sendMail|sendSms)\(|\b(resend|sendgrid|sgMail|postmark|mailgun|transporter|mailer|twilio|ses|sns)\.\w*[sS]end\w*\(|\.emails\.send\(/;
+const LOOP_HEAD = /\bfor(\s+await)?\s*\(|\bwhile\s*\(|\.(map|forEach|flatMap)\(\s*(async\b|\()/;
 const HANDLER = /(^|\/)(functions|api|routes?|handlers?)\//i;
 const SCHEDULE = /\bsetInterval\s*\(|\bcron\b|schedule/i;
 function hostOrCall(line) {
     const host = /https?:\/\/([a-z0-9.-]+)/i.exec(line)?.[1];
     if (host)
         return host;
-    const call = /\.((?:messages|completions|chat|embeddings|images)\.create|generateContent|send(?:Email|Mail|Sms)?)\(/.exec(line)?.[1];
+    const call = /\.((?:messages|completions|chat|embeddings|images|predictions)\.create|generateContent|emails\.send|\w*[sS]end\w*)\(/.exec(line)?.[1];
     return call ?? "external call";
 }
+const count = (s, re) => (s.match(re) ?? []).length;
+/**
+ * INSIDE the loop, not below it (0.2.1). "A loop head within the twelve lines
+ * above" read `slots.map((s) => s.role).join(', ')` - a prompt being built - as
+ * the loop around the Gemini call three lines later, and reported the call as
+ * per-row twice on the first repository it met. A loop encloses the call only
+ * if the brackets it opened are still open where the call is made.
+ */
+function insideLoop(lines, at) {
+    for (let j = at - 1; j >= Math.max(0, at - 80); j--) {
+        if (!LOOP_HEAD.test(lines[j]))
+            continue;
+        // Walk forward from the loop head until the brackets it opened close. If
+        // they have not closed by the call, the call is inside. Stopping at the
+        // close means the call's OWN `fetch(` on the line above its URL is never
+        // mistaken for the loop still being open.
+        let depth = 0;
+        let opened = false;
+        let closed = false;
+        for (let k = j; k < at && !closed; k++) {
+            const opens = count(lines[k], /[{(]/g);
+            depth += opens - count(lines[k], /[})]/g);
+            // The head line opening and closing on the same line (`.map((x) => x.id).join(', ')`)
+            // is a loop that already closed; without this, the walk ran on past it and
+            // tripped over a prose parenthesis inside a prompt string forty lines later.
+            if ((k === j && opens > 0) || depth > 0)
+                opened = true;
+            if (opened && depth <= 0)
+                closed = true;
+        }
+        if (opened && !closed)
+            return true;
+    }
+    return false;
+}
 export async function detectCosts(repo) {
     const out = [];
-    for (const f of runtimeCode(repo.files)) {
+    for (const f of scopeFor(repo.files, "implementation")) {
         const text = await repo.read(f);
         if (!text || !PAID_CALL.test(text))
             continue;
@@ -23,13 +65,13 @@ export async function detectCosts(repo) {
                 continue;
             const target = hostOrCall(line);
             const evidence = `${i + 1}: ${line.trim().slice(0, 110)}`;
-            // per-row: a loop head within the twelve lines above the call.
-            const above = lines.slice(Math.max(0, i - 12), i).join("\n");
-            if (LOOP_HEAD.test(above)) {
+            // per-row: the call sits inside a loop that has not closed.
+            if (insideLoop(lines, i)) {
                 out.push({ file: f, shape: "per-row", target, line: evidence });
                 continue;
             }
             // per-schedule: the call sits under an interval or a cron marker.
+            const above = lines.slice(Math.max(0, i - 12), i).join("\n");
             if (SCHEDULE.test(above) || (SCHEDULE.test(text.slice(0, 800)) && SCHEDULE.test(f))) {
                 out.push({ file: f, shape: "per-schedule", target, line: evidence });
                 continue;

package/dist/detect/database.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The database, which no question used to claim.
+ *
+ * The coverage ledger's `unclaimed` list is what surfaced this: 146 `.sql` files
+ * on the first real repository the scan met, holding 243 SECURITY DEFINER
+ * functions, 82 policies and 81 tables, analysed by nothing. The absence of a
+ * detector is invisible from inside the detectors, which is why it took a ledger
+ * to notice rather than a reading of the code.
+ *
+ * It matters more than the count suggests. On a Postgres-backed product the
+ * authorisation model does not live in the application - it lives in row-level
+ * security and in who may execute a definer function. A scan that reads every
+ * line of TypeScript and no line of SQL has read the part that asks permission
+ * and skipped the part that grants it.
+ *
+ * WHAT THIS IS NOT. Not a linter, and not a security review: it runs nothing,
+ * connects to nothing, and cannot see a migration that was applied by hand and
+ * never committed. It reads the migrations as text and reports three shapes that
+ * are worth a human minute, each one a question with a subject.
+ *
+ * THE COUNTS ARE PART OF THE FINDING. `tables`, `policies` and `definer_functions`
+ * ride alongside, because "no findings" and "never looked" must not read alike -
+ * a check that reports the same whether it works or not is the failure this
+ * whole version is about.
+ */
+import type { Repo } from "../walk.js";
+import type { DatabaseReading } from "./types.js";
+export declare function detectDatabase(repo: Repo): Promise<DatabaseReading>;