@bigsteele/the-big-sean 0.1.0 → 0.2.0

package/README.md

@@ -12,7 +12,11 @@ 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. This package ships the
+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
+for the app: **The Big Sean - <App Name>.md** and **.html**. This package ships the
 protocol and the tools around it:
 
 ```
@@ -22,6 +26,16 @@ npx @bigsteele/the-big-sean --check    # after the audit: re-compute the report'
 npx @bigsteele/the-big-sean --stdout   # print the protocol
 ```
 
+## Before you run it
+
+This is a large scan, not a quick check. The agent reads everything in the repository it
+can reach, spawns multiple sub-agents against the codebase, probes the live system
+read-only where your credentials allow, and writes a long report: 140 graded checks with
+evidence. Expect a long session and a lot of tokens. `big-sean --run` says this and asks
+before it starts (`--yes` skips the question); the protocol file says it at the top so
+whoever pastes it sees it too. It changes nothing: no edits, no commits, no deploys, no
+messages, no spending.
+
 ## Prove the number
 
 The protocol makes the auditing agent write its own validator and show its math. `--check`
@@ -47,6 +61,12 @@ or any connected service. No commits, branches, deploys, messages, or spending.
 prints a secret or a customer's personal data, and it never says "production ready" — it
 says what it verified and what it did not.
 
+## After the card
+
+Every report card ends the same way: send it in at **bigsteele.com/scan** and get a written
+read of the three fixes that come first, in order. No call required to get it, and no pitch
+inside it. If the read turns into a build, it is the first mile of that engagement.
+
 ## The name
 
 Big Steele wrote the machine. LaSean Pickens wrote the standard. The Big Sean is what

package/dist/cli.js

@@ -7,27 +7,38 @@
 // --check exits 0 on GATES CLEAR, 2 on LAUNCH BLOCKED or NOT VERIFIED FOR LAUNCH,
 // 1 when the grade.json is rejected. Everything else exits 0 on success.
 import { spawn } from "node:child_process";
-import { readFile, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { runAudit, secretShaped, slug, toMarkdown } from "@bigsteele/ai-audit";
 import { extractRecords, score, showTheMath } from "./check.js";
 import { loadPrompt } from "./index.js";
+const WARNING = `Before you run The Big Sean, know what it is.
+  This is a large scan, not a quick check. Claude will read everything in this repository
+  it can reach, spawn multiple sub-agents against the codebase, probe the live system
+  read-only where your credentials allow, and write a long report: 140 graded checks with
+  evidence. Expect a long session and a lot of tokens. It changes nothing: no edits, no
+  commits, no deploys, no messages, no spending.`;
 const HELP = `The Big Sean — the Launch Report Card. Big Steele × LaSean Pickens.
 
   big-sean [dir]           drop THE-BIG-SEAN.md into the repo (default: here)
   big-sean --stdout        print the protocol
-  big-sean --run [dir]     open claude with the protocol as the opening prompt
+  big-sean --run [dir]     open claude with the protocol as the opening prompt (asks first; --yes skips)
   big-sean --check [file]  re-score a report's grade.json and show the math
                            (default: .planning/launch-audit/grade.json)`;
 export async function main(argv, log = console.log, err = console.error) {
     let dir = ".";
     let mode = "write";
     let checkTarget = null;
+    let yes = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--stdout")
             mode = "stdout";
         else if (a === "--run")
             mode = "run";
+        else if (a === "--yes" || a === "-y")
+            yes = true;
         else if (a === "--check") {
             mode = "check";
             const next = argv[i + 1];
@@ -55,6 +66,11 @@ export async function main(argv, log = console.log, err = console.error) {
         }
         const res = score(extractRecords(raw));
         log(showTheMath(res));
+        const ai = await aiReadinessLine(resolve(file, ".."));
+        if (ai)
+            log(ai);
+        log("");
+        log("Send the card in for a written read of the three fixes that come first: bigsteele.com/scan");
         if (!res.ok)
             return 1;
         return res.gate.status === "GATES CLEAR" ? 0 : 2;
@@ -64,7 +80,24 @@ export async function main(argv, log = console.log, err = console.error) {
         log(prompt);
         return 0;
     }
+    // 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);
     if (mode === "run") {
+        log(WARNING);
+        if (!yes) {
+            if (!process.stdin.isTTY) {
+                err(`No terminal to confirm in. Re-run with --yes when you are ready for a session that size.`);
+                return 1;
+            }
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const answer = (await rl.question("Run it now? [y/N] ")).trim().toLowerCase();
+            rl.close();
+            if (answer !== "y" && answer !== "yes") {
+                log(`Not started. The protocol is unchanged; run big-sean --run when you are ready.`);
+                return 0;
+            }
+        }
         log(`The Big Sean: opening claude with the Launch Report Card. Read-only audit; it changes nothing.`);
         const child = spawn("claude", [prompt], { cwd: root, stdio: "inherit" });
         return await new Promise((resolvePromise) => {
@@ -77,14 +110,53 @@ export async function main(argv, log = console.log, err = console.error) {
     }
     return writeProtocol(root, log);
 }
+async function runAiAudit(root, log, err) {
+    try {
+        const audit = await runAudit(root);
+        const hit = secretShaped(audit);
+        if (hit) {
+            err(`AI Audit not written: its output matched a credential shape (${hit}). 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 = `ai-audit-${slug(audit.app)}`;
+        await writeFile(join(dir, `${base}.md`), toMarkdown(audit), "utf8");
+        await writeFile(join(dir, `${base}.json`), JSON.stringify(audit, null, 2) + "\n", "utf8");
+        const sc = audit.score;
+        log(`AI Audit: ${audit.app}  ${sc.total} / 100  ${sc.grade}  level ${sc.level.n} ${sc.level.name}  → ${join(".planning", "launch-audit", base + ".md")}`);
+    }
+    catch (e) {
+        err(`AI Audit did not run (${e instanceof Error ? e.message : String(e)}). The protocol tells the agent to run it itself.`);
+    }
+}
+/** The AI readiness line for --check, when Step 0's json is beside grade.json. */
+async function aiReadinessLine(reportDir) {
+    try {
+        const { readdir } = await import("node:fs/promises");
+        const files = (await readdir(reportDir)).filter((f) => /^ai-audit-.*\.json$/.test(f));
+        if (files.length === 0)
+            return null;
+        const a = JSON.parse(await readFile(join(reportDir, files[0]), "utf8"));
+        if (!a.score)
+            return null;
+        return `AI readiness (Big Steele AI Audit): ${a.score.total} / 100 (${a.score.grade}, level ${a.score.level?.n} ${a.score.level?.name})`;
+    }
+    catch {
+        return null;
+    }
+}
 async function writeProtocol(root, log) {
     const file = join(root, "THE-BIG-SEAN.md");
     await writeFile(file, await loadPrompt(), "utf8");
     log(`Wrote ${file}`);
     log(``);
+    log(WARNING);
+    log(``);
     log(`Next: open Claude Code in this folder and paste the whole file in (or run big-sean --run).`);
-    log(`When it finishes, the report card opens itself. Then prove the number:`);
-    log(`  big-sean --check`);
+    log(`When it finishes, "The Big Sean - <App Name>.md" and .html are at the repo root and the card opens itself.`);
+    log(`Then prove the number:   big-sean --check`);
+    log(`Then send it in for a written read of the three fixes that come first:   bigsteele.com/scan`);
     return 0;
 }
 const entry = process.argv[1] ?? "";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bigsteele/the-big-sean",
-  "version": "0.1.0",
-  "description": "The Big Sean: the Launch Report Card, by Big Steele and LaSean Pickens. Drops a 140-check launch-readiness and autonomy audit protocol into a repo for Claude Code to run, 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.2.0",
+  "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.",
   "type": "module",
   "license": "UNLICENSED",
   "author": "Big Steele (Together Inc.) and LaSean Pickens",
@@ -35,5 +35,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@bigsteele/ai-audit": "^0.2.2"
   }
 }

package/prompt/THE-BIG-SEAN.md

@@ -2,6 +2,8 @@
 
 A collaboration between Big Steele and LaSean Pickens.
 
+BEFORE YOU RUN THIS, KNOW WHAT IT IS. This is a large scan, not a quick check. The agent will read everything in this repository it can reach, spawn multiple sub-agents against the codebase to inventory routes, tables, functions, crons, and dependencies, probe the live system read-only where credentials on this machine allow it, and then write a long report with one hundred forty graded checks and their evidence. Expect it to run for a long time and to use a lot of context and tokens. It changes nothing: no edits, no commits, no deploys, no messages, no spending. If you are not ready for a session that size, stop here and come back when you are.
+
 Paste this whole thing into Claude Code (or Claude Cowork) inside your app's folder. Type nothing else. When it finishes, your report card opens by itself.
 
 You are a senior software auditor. Grade this app on two things: is it ready for beta launch (reliable, safe, secure, usable, able to take load) and is it autonomous (able to run the business without the owner or the customer's staff after onboarding, inside explicit policies). Both are primary. Neither is optional. Do not fix anything. Do not change anything. Do not ask me questions. Discover everything yourself, grade it, and give me a full report card with a score out of 100, a score for every category, why each category scored what it scored, exactly what to change, and the order to do it in.
@@ -11,6 +13,9 @@ Rules you never break:
 	•	Reading a file is not proof it works. A migration in the repo is not proof it is applied. A cron in a config is not proof it fires. A test file is not proof the test runs. A "done" checkbox in a planning doc is not proof of anything.
 	•	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.
+Step 0. The AI Audit (already run for you, or run it 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.
+
 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.
 	•	Env files (.env, .env.local, .env.production, .env.example) for the names of services in use and any database URL, Supabase URL and keys, provider keys. Use keys only for read operations.
@@ -303,7 +308,7 @@ Score math (compute it, do not eyeball it):
 	•	If any check anywhere is UNKNOWN, the headline shows the verified score with the word INCOMPLETE next to it and the ceiling beside it. Never show a bare number over a report that has unknowns.
 Prove the number. Write score.mjs into the report folder. It reads grade.json, rejects any status outside PASS, FAIL, UNKNOWN, N/A, rejects any PASS or FAIL that has zero evidence entries, rejects any N/A without a reason, rejects any check without a written test, and then computes every number on the page. The HTML reads the computed output; nothing is typed by hand. Run node score.mjs and paste its output into the report under the heading "Show the math": the weight table, the sums, the division, per category and overall. If the validator rejects the file, fix the grade.json, not the validator.
 Step 6. Write the report card
-Create .planning/launch-audit/REPORT-CARD.html (single file, inline CSS and JS, opens from disk, no external requests) and REPORT-CARD.md with identical content. Build both from a grade.json you write first, so every number is computed. Structure, in this order:
+Create .planning/launch-audit/REPORT-CARD.html (single file, inline CSS and JS, opens from disk, no external requests) and REPORT-CARD.md with identical content. Then copy both to the repository root as "The Big Sean - <App Name>.html" and "The Big Sean - <App Name>.md", where <App Name> is the product's real name (the brand a customer would recognize, from the manifest, the README, or the UI; the folder name only if nothing better exists). Those two root files are the deliverable a person shares; the report folder keeps the working artifacts. Build both from a grade.json you write first, so every number is computed. Structure, in this order:
 	•	Headline: verified score and band, ceiling, coverage, gate status (LAUNCH BLOCKED, NOT VERIFIED FOR LAUNCH, or GATES CLEAR), the launch-readiness score and the autonomy score side by side, the unattended verdict with the duty counts, the one-sentence verdict, the date, the commit, the sources reached live and not reached.
 	•	The thirty-five category cards (L01 to L15, then D01 to D20). Each card shows: the category score and band; the four checks with PASS, FAIL, UNKNOWN, or N/A and their weight; Why you scored this (one plain-language paragraph per check that is not PASS, citing the file and line, the query, or the page); What this costs you (what happens to a customer, to your money, or to your reputation if you launch like this); How to fix it (the exact change, where, and the test that proves it); How to verify it yourself (a command or a click path).
 	•	Your path to 100: every check that is not PASS, across all categories, in the order to do them. Blockers first (weight-5 FAILs), then the weight-5 UNKNOWNs to prove, then everything else in dependency order. Each with the change, the location, the test, and a rough effort (hours, one day, multi-day).
@@ -328,17 +333,28 @@ Create .planning/launch-audit/REPORT-CARD.html (single file, inline CSS and JS,
 	•	The full WORKFLOW-COVERAGE table: every duty, plane, trigger, what runs it, status, evidence, and what makes it unattended.
 	•	The simulated day, week, and month logs: every step, who or what performed it, the receipt, and every point a human was needed.
 	•	Every finding, all of them, not the ones that move the needle: ID, category, severity, check ID, file and line or query, expected, observed, impact, fix, retest.
+	•	What to do with this (the last section of both files, verbatim, after everything else):
+## What to do with this
+
+This report card is the diagnosis. The build is the work.
+
+Big Steele and LaSean Pickens wrote this standard because they build what it grades: the tenant isolation, the money paths, the jobs that recover, the autonomy that runs a business inside explicit policies. If you want the people who wrote the rubric to read your card and tell you which three fixes come first, send it in:
+
+**bigsteele.com/scan** Upload this file. You get a written read back. No call required to get it, and no pitch inside it.
+
+If the read turns into a build, it is the first mile of that engagement. The path to 100 above is the plan; the read tells you where to start.
 Minimums, or the report is not done: every one of the one hundred forty checks has a written test and at least one evidence entry or an UNKNOWN reason; every table and every route appears in the inventories; the findings list contains every FAIL and every UNKNOWN as its own row. If the app is large, the report is long. That is correct.
 Make the HTML readable by a non-engineer at the top and complete for an engineer underneath: a score dial, category cards with color by band, filters by category and severity and status, expandable evidence, and a button that downloads grade.json. Put the summary card from Step 7 at the very top of the page so the first screen answers the question.
 Step 7. Hand it to me
 Do not make me look for anything.
-	•	If this session has an artifact tool or a file-presenting tool (Claude Cowork and claude.ai do), present REPORT-CARD.html as an artifact so it renders right here in the conversation with a clickable card.
+	•	If this session has an artifact tool or a file-presenting tool (Claude Cowork and claude.ai do), present "The Big Sean - <App Name>.html" as an artifact so it renders right here in the conversation with a clickable card.
 	•	Whether or not that worked, open the report in the default browser automatically: start "" "<full path>" on Windows, open "<full path>" on macOS, xdg-open "<full path>" on Linux. Then print the clickable link on its own line: file:///<full path to REPORT-CARD.html>.
 	•	Under the link, print the summary card in chat:
 LAUNCH REPORT CARD
 Score: <verified> / 100  (<band>)  <INCOMPLETE if any unknowns>   Ceiling: <ceiling>   Proven either way: <coverage>%
 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>)
 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>
@@ -349,5 +365,7 @@ Top 5 problems:
  4. ...
  5. ...
 Next action: <the first item on the path to 100>
+Your report card: <full path to "The Big Sean - <App Name>.md">
+Send it in for a written read of the three fixes that come first: bigsteele.com/scan
 Nothing else. No offer to fix anything. This run changed nothing.