@bigsteele/the-big-sean 0.4.4 → 0.5.0

package/README.md

@@ -12,10 +12,13 @@ band, a ceiling, gate status, category cards, the path to 100, and every finding
 a file and line, a query, or a page.
 
 The audit itself is run by Claude Code against your repo and, where reachable, your live
-system — read-only, no edits, no questions, nothing spent. Step 0 is the **Big Steele AI
-Audit**: `big-sean` runs it for you first (deterministic, file-by-file, never opens an env
-file) and the protocol uses its findings as evidence for the autonomy side, with its score
-on the summary card as the AI readiness line. The deliverable lands at the repo root, named
+system — read-only, no edits, no questions, nothing spent. Step 0 is two deterministic scans, run for you before the
+agent starts: the **Big Steele AI Audit** (what the software automates, and how much of it
+an agent could operate) and **Wiremap** (how far it is from one change in one place, and
+whether a capability map exists for the agent to read before it searches). Their findings
+are evidence the protocol cites, their scores appear on the summary card as the AI
+readiness and Wiring lines, and Wiremap's block map is what the agent uses to navigate the
+codebase instead of searching it. The deliverable lands at the repo root, named
 for the app: **The Big Sean - <App Name>.md** and **.html**. This package ships the
 protocol and the tools around it:
 

package/dist/cli.js

@@ -69,6 +69,9 @@ export async function main(argv, log = console.log, err = console.error) {
         const ai = await aiReadinessLine(resolve(file, ".."));
         if (ai)
             log(ai);
+        const wiring = await wiringLine(resolve(file, ".."));
+        if (wiring)
+            log(wiring);
         log("");
         log("Send the card in for a written read of the three fixes that come first: bigsteele.com/scan");
         if (!res.ok)
@@ -83,6 +86,7 @@ export async function main(argv, log = console.log, err = console.error) {
     // Step 0 of the protocol: the AI Audit runs here, deterministically, so the
     // agent starts with its files as evidence. Read-only; never opens an env file.
     await runAiAudit(root, log, err);
+    await runWiremapScan(root, log, err);
     if (mode === "run") {
         log(WARNING);
         if (!yes) {
@@ -110,6 +114,33 @@ export async function main(argv, log = console.log, err = console.error) {
     }
     return writeProtocol(root, log);
 }
+/**
+ * Wiremap: how far the codebase is from one change in one place, and whether a capability
+ * map exists for the agent to read before it searches. Loaded dynamically and skipped on
+ * failure, because a missing scanner must not stop the audit that needs it least.
+ */
+async function runWiremapScan(root, log, err) {
+    try {
+        const wm = await import("@bigsteele/wiremap");
+        const w = await wm.runWiremap(root);
+        if (wm.secretShaped(w)) {
+            err(`Wiremap not written: its output matched a credential shape. A secret is committed in this repository; that is the first finding.`);
+            return;
+        }
+        const dir = join(root, ".planning", "launch-audit");
+        await mkdir(dir, { recursive: true });
+        const base = `wiremap-${wm.slug(w.app)}`;
+        await writeFile(join(dir, `${base}.md`), wm.toMarkdown(w), "utf8");
+        await writeFile(join(dir, `${base}.json`), `${JSON.stringify(w, null, 2)}\n`, "utf8");
+        const top = w.blast[0];
+        log(`Wiremap:  ${w.app}  ${w.score.total} / 100  ${w.score.grade}  level ${w.score.level.n} ${w.score.level.name}  -> ${join(".planning", "launch-audit", `${base}.md`)}`);
+        if (top)
+            log(`          worst blast radius: ${top.what} - ${top.files_today} files today, 1 once wired`);
+    }
+    catch (e) {
+        err(`Wiremap did not run (${e instanceof Error ? e.message : String(e)}). The protocol tells the agent to run it itself.`);
+    }
+}
 async function runAiAudit(root, log, err) {
     try {
         const audit = await runAudit(root);
@@ -130,6 +161,22 @@ async function runAiAudit(root, log, err) {
         err(`AI Audit did not run (${e instanceof Error ? e.message : String(e)}). The protocol tells the agent to run it itself.`);
     }
 }
+/** The wiring line for --check, when Step 0's wiremap json is beside grade.json. */
+async function wiringLine(reportDir) {
+    try {
+        const { readdir } = await import("node:fs/promises");
+        const files = (await readdir(reportDir)).filter((f) => /^wiremap-.*\.json$/.test(f));
+        if (files.length === 0)
+            return null;
+        const w = JSON.parse(await readFile(join(reportDir, files[0]), "utf8"));
+        if (!w.score)
+            return null;
+        return `Wiring (Wiremap): ${w.score.total} / 100 (${w.score.grade}, level ${w.score.level?.n} ${w.score.level?.name})`;
+    }
+    catch {
+        return null;
+    }
+}
 /** The AI readiness line for --check, when Step 0's json is beside grade.json. */
 async function aiReadinessLine(reportDir) {
     try {
@@ -183,7 +230,7 @@ async function writeProtocol(root, log) {
     log(WARNING);
     log(``);
     log(``);
-    log(`What just ran is the AI Audit: a deterministic file scan, seconds, no model involved.`);
+    log(`What just ran is the AI Audit and Wiremap: deterministic file scans, seconds, no model involved.`);
     log(`The report card is the other half, and it is a long agent session, not a scan.`);
     log(`Next: open Claude Code in this folder and paste the whole file in (or run big-sean --run).`);
     log(`When it finishes, "The Big Sean - <App Name>.md" and .html are at the repo root and the card opens itself.`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bigsteele/the-big-sean",
-  "version": "0.4.4",
-  "description": "The Big Sean: the Launch Report Card, by Big Steele and LaSean Pickens. Runs the Big Steele AI Audit, drops a 140-check launch-readiness and autonomy audit protocol into a repo for Claude Code to run, names the deliverable after the app, and independently re-computes any report's math from its grade.json so the number on the card can be proven, not trusted.",
+  "version": "0.5.0",
+  "description": "The Big Sean: the Launch Report Card, by Big Steele and LaSean Pickens. Runs the Big Steele AI Audit and Wiremap, drops a 140-check launch-readiness and autonomy audit protocol into a repo for Claude Code to run, names the deliverable after the app, and independently re-computes any report's math from its grade.json so the number on the card can be proven, not trusted.",
   "type": "module",
   "license": "UNLICENSED",
   "author": "Big Steele (Together Inc.) and LaSean Pickens",
@@ -37,6 +37,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@bigsteele/ai-audit": "^0.2.3"
+    "@bigsteele/ai-audit": "^0.2.3",
+    "@bigsteele/wiremap": "^0.1.0"
   }
 }

package/prompt/THE-BIG-SEAN.md

@@ -14,9 +14,10 @@ Rules you never break:
 	•	Never print a secret, a token, a password, or a customer's personal data anywhere.
 	•	Never say "100% bug-free" or "production ready." Say what you verified and what you did not.
 	•	IDENTIFY THE TARGET BEFORE YOU READ IT. Every live system you touch must be proven to belong to THIS repository before you run a single query against it, and the proof goes in SOURCES.md. See Step 1's identity gate. Reading a database that belongs to someone else is not made acceptable by being read-only.
-Step 0. The AI Audit (already run for you, or run it now)
+Step 0. The two deterministic scans (already run for you, or run them now)
 If .planning/launch-audit/ai-audit-<app>.md and ai-audit-<app>.json exist, big-sean ran the Big Steele AI Audit before handing you this protocol. Read both. They are evidence, cited like any other: use their findings for the checks about surfaces, model calls, tools, loops, reach, and failure visibility in Part B, and cite the file and the criterion. If they are missing, run `npx @bigsteele/ai-audit --repo . --out .planning/launch-audit` yourself (it is read-only, writes only those two files, and never opens an env file), then read them. The AI Audit's score, grade, and level go on the summary card as the AI readiness line. It replaces no check: an agent-runnable architecture still has to pass every gate.
-The AI Audit is deterministic: it reads files and counts patterns, and it can miss an agent surface that lives outside the main app (Deno edge functions, workers, a separate service, a hand-written MCP server with no SDK). Never accept its zeros on faith. If it reports zero or near zero for the MCP server, tool definitions, or memory between runs, go read supabase/functions, workers, api, and any folder named mcp, tools, agents, or intelligence yourself before grading. Where you find a surface the scanner missed, grade the capability as present with your own evidence, and record a separate finding: the surface is not discoverable (no SDK declaration, no server card or mcp.json, no mention in README, AGENTS.md, or llms.txt). Claude, Cursor, and ChatGPT discover software the way the scanner did. An agent surface a scanner cannot find is one an agent cannot find either, and that is the real finding, not the zero.
+Wiremap ran beside it, and its files are in the same folder: .planning/launch-audit/wiremap-<app>.md and .json. It answers two questions this protocol otherwise has no way to measure: is every value referenced by name from one source of truth (so one change is one edit), and is every file claimed by exactly one named capability (so one question is one file). Read it before Step 2, and use it three ways. Its score, grade and level go on the summary card as the Wiring line. Its BLOCK MAP is your index to the codebase: where the repository has a manifest, read that map first and go straight to the block that owns a feature instead of searching, exactly as the repository's own agent instructions say to; where it has none, Wiremap's DRAFT blocks are the next best index, and you may use them to navigate but never cite them as the repository's own map. Its BLAST-RADIUS table is evidence for any finding about the cost of change: a value in nine files is nine edits and nine chances to disagree, and that is a maintainability finding with a number attached rather than an opinion. If Wiremap did not run, run it yourself: `npx @bigsteele/wiremap --out .planning/launch-audit` (read-only, writes only those two files).
+Both scans are deterministic: they read files and count patterns, and the AI Audit can miss an agent surface that lives outside the main app (Deno edge functions, workers, a separate service, a hand-written MCP server with no SDK). Never accept its zeros on faith. If it reports zero or near zero for the MCP server, tool definitions, or memory between runs, go read supabase/functions, workers, api, and any folder named mcp, tools, agents, or intelligence yourself before grading. Where you find a surface the scanner missed, grade the capability as present with your own evidence, and record a separate finding: the surface is not discoverable (no SDK declaration, no server card or mcp.json, no mention in README, AGENTS.md, or llms.txt). Claude, Cursor, and ChatGPT discover software the way the scanner did. An agent surface a scanner cannot find is one an agent cannot find either, and that is the real finding, not the zero.
 
 Step 1. Find out what you can reach (no setup from me)
 Look for what is already on this machine and use it read-only. Do not ask me for anything.
@@ -61,7 +62,7 @@ Write NORTH-STAR.md, and keep every line traceable:
 	•	Anything you could not determine. Write UNKNOWN and say what would settle it. Never invent a mission.
 If the evidence contradicts itself, that is a finding, not a puzzle to resolve quietly: a README promising one thing while the code and the money path serve another means the team does not agree on what it is building, and it goes in the report as its own finding with both citations.
 THE DRIFT RULE, which governs the rest of this audit. Every FAIL, every UNKNOWN, and every recommendation must connect to the North Star. In the action plan and the path to 100, each item carries one line, "why this matters here", that names the workflow, the money path, or the critical few it protects. An item that cannot make that connection is not dropped and not silently downgraded: it is grouped under "Rubric items that do not serve your North Star" with a one-line reason, so the owner sees you considered it and why it waits. Ordering follows the North Star, not the rubric's numbering: two weight-5 failures are not equal when one breaks the money path and the other breaks a surface nobody has shipped yet. Never recommend building a capability the North Star does not need just because a check exists for it. If the audit's honest conclusion is that the app should do less, say that.
-Now learn the app. Read the planning docs, README, specs, and any state files first. Then read the real code: every route, page, API handler, server action, edge or serverless function, worker, cron, webhook, database migration, policy, trigger, function, storage rule, and integration. Trace the main user journeys end to end: sign up, first value, the core workflow of this product, pay, cancel, delete account, get support. Trace the owner's journeys: onboarding a customer, seeing what happened, handling a failure, getting paid. Write WHAT-THIS-APP-DOES.md: what it is, who uses it, the money flows, the external services, the background jobs, and the workflows that must work for a customer to pay and stay. Where it disagrees with NORTH-STAR.md, the code wins for what the app DOES and the North Star governs what it is FOR; note the gap.
+Now learn the app. Start from the block map (the repository's own, or Wiremap's draft): it tells you what the product does and which files implement it, so you can read the blocks that matter instead of walking the tree. Then read the planning docs, README, specs, and any state files. Then read the real code: every route, page, API handler, server action, edge or serverless function, worker, cron, webhook, database migration, policy, trigger, function, storage rule, and integration. Trace the main user journeys end to end: sign up, first value, the core workflow of this product, pay, cancel, delete account, get support. Trace the owner's journeys: onboarding a customer, seeing what happened, handling a failure, getting paid. Write WHAT-THIS-APP-DOES.md: what it is, who uses it, the money flows, the external services, the background jobs, and the workflows that must work for a customer to pay and stay. Where it disagrees with NORTH-STAR.md, the code wins for what the app DOES and the North Star governs what it is FOR; note the gap.
 Step 3. Check the live system where you can (all read-only)
 Where the database is reachable:
 	•	Every table with its row count. Flag tables that are empty but should have content (an academy with no lessons, a pricing table with no rows, a policies table with no current version).
@@ -395,6 +396,7 @@ Score: <verified> / 100  (<band>)  <INCOMPLETE if any unknowns>   Ceiling: <ceil
 Checks: <n> PASS, <n> FAIL, <n> UNKNOWN, <n> N/A of 140   Findings: <count>   Evidence entries: <count>
 Launch readiness (L01 to L15): <score>   Autonomy (D01 to D20): <score>   Combined: <score>
 AI readiness (Big Steele AI Audit): <score> / 100 (<grade>, level <n> <name>)
+Wiring (Wiremap): <score> / 100 (<grade>, level <n> <name>)   Worst blast radius: <what> in <n> files
 Gates: <LAUNCH BLOCKED by ... | NOT VERIFIED FOR LAUNCH: ... | GATES CLEAR>
 Runs unattended today: <YES | NO | UNKNOWN>   Duties automated: <n> of <total> (<n> of <software-executable>)   Human touches per week: <n> (<removable> removable, <partial> partial, <by design> by design)
 Live sources reached: <list>   Not reached: <list>