codeblast 0.3.1 → 0.3.3

package/README.md

@@ -1,4 +1,4 @@
-**codeblast** is a deterministic code-graph CLI for TypeScript and Python repositories that tells developers and AI agents what breaks before a change is merged.
+**codeblast** is the pre-merge blast-radius check for TypeScript monorepos and AI coding agents. It tells you what to review, which tests to run, and when the graph is incomplete — with a source line for every reported edge.
 
 <p align="center">
   <img src="assets/readme/hero.svg" width="100%" alt="codeblast — deterministic code graph: know what breaks before you merge"/>
@@ -15,6 +15,29 @@
   <img src="https://img.shields.io/badge/license-MIT-8b949e?style=flat-square" alt="MIT"/>
 </p>
 
+## Get value in one pull request
+
+Copy this workflow into `.github/workflows/codeblast.yml`:
+
+```yaml
+name: codeblast
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  codeblast:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: alloevil/codeblast@v0.3.3
+```
+
+On a structural PR, codeblast posts a bounded review decision, affected tests, `file:line` evidence,
+and explicit blind-spot warnings. On a docs-only or otherwise irrelevant PR, it stays silent. It runs
+locally in the runner; source is not uploaded to a codeblast service.
+
 ## What it is
 
 **codeblast parses your repository into a deterministic code graph and answers the three most expensive questions around any code change:**
@@ -49,7 +72,7 @@ Built for humans (CLI / interactive HTML / PR comments) and for AI agents ([SKIL
 ```bash
 npx codeblast demo            # build a graph of the current repo, run one impact query, emit the map
 npm i -g codeblast            # or install globally; needs Node ≥ 22.13 (built-in sqlite) or Bun
-                              # npm serves 0.3.0; this checkout is 0.3.1 (unpublished)
+                              # npm serves 0.3.3
 
 # Install as an agent skill (Claude Code, Codex, Cursor, and 14 more harnesses)
 npx skills add alloevil/codeblast
@@ -57,28 +80,28 @@ npx skills add alloevil/codeblast
 
 ### As a GitHub Action (one line)
 
+The smallest useful installation is a PR workflow. Pin the release tag, or pin the commit when your
+repository requires immutable third-party actions:
+
 ```yaml
-# .github/workflows/codeblast.yml
 name: codeblast
 on: pull_request
 permissions:
   contents: read
   pull-requests: write
 jobs:
-  analyze:
+  codeblast:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }      # the analyzer compares base and head commits
-      - uses: alloevil/codeblast@v0.3.1
+        with: { fetch-depth: 0 }
+      - uses: alloevil/codeblast@v0.3.3
 ```
 
-The action builds the analyzer from the ref you pinned (not from npm, which can lag),
-posts one sticky comment per PR and updates it in place, and stays silent when the diff
-has no structural change. Inputs: `base`, `head`, `repo-url`, `comment` (set to `false`
-to only produce the file); outputs: `has_comment`, `comment_path`. If you prefer to own
-the commenting step, copy [`.github/workflows-template/codeblast.yml`](.github/workflows-template/codeblast.yml)
-instead — it runs the same command with `npx`.
+The action builds the analyzer from the ref you pinned, posts one sticky comment per PR, and stays
+silent when the diff has no structural change. For the full input/output contract, use the
+[workflow template](.github/workflows-template/codeblast.yml).
+
 
 ## Why not yet another LLM diagram tool
 
@@ -113,7 +136,8 @@ codeblast change <repo> main~5 main --json
 
 # ③ Architecture Map — interactive HTML: module → file → symbol drill-down,
 #    symbols link to source lines
-codeblast archmap graph.db --out arch.html --repo-url <github-url>
+codeblast archmap graph.db --out arch.html --repo-url <github-url> \
+  --site-url https://example.github.io/repo --og-image <share-image-url>
 
 # Optional: mine git co-change coupling (protocol pairs, config + consumers —
 # edges static analysis can't see)
@@ -121,6 +145,19 @@ codeblast cochange <repo> graph.db
 ```
 
 ### PR bot (runs in CI, stays quiet by default)
+### Reproducible PR cases
+
+These are not synthetic diagrams; each case is a committed replay or pilot artifact:
+
+| Case | Run it | Reviewer takeaway |
+|---|---|---|
+| Function-body behavior change | `codeblast pr-comment <repo> <base> <head>` | A symbol can keep the same shape while its callers still need review. |
+| Exported signature change | `codeblast check-change <repo> <base> <head> --json` | API contraction or signature changes route to targeted review or review. |
+| Incomplete static graph | `codeblast impact <db> <symbol> --json` | `warnings` and `blind_spot_count` prevent an apparently complete answer. |
+
+The self-pilot record is [`eval/pilot-2026-09-24.json`](eval/pilot-2026-09-24.json): the published
+package indexed this repository with 0 extraction failures and returned separate review-first and test
+guidance. It is evidence that the workflow runs, not a claim of universal accuracy.
 
 Copy [`.github/workflows-template/codeblast.yml`](.github/workflows-template/codeblast.yml) into your repo (it runs `npx codeblast pr-comment`, no other setup):
 every PR gets an automatic comment with structural changes + blast radius + new symbols with no test coverage; **PRs with no structural change get zero comments**.
@@ -128,6 +165,48 @@ Replayed against 50 real commits: 42 correctly stayed silent. Comment usefulness
 four review rounds — rounds 1–3 independent blind review, round 4 by the current model — scored 25% / 75% / 57% / 20% useful, against 7/8 = 87.5% when the
 authoring agent rated its own comments; both numbers and the fixes that followed each round are logged in
 [intent.md](intent.md).
+## Evidence you can rerun
+
+The headline promise is bounded: TypeScript, within the statically analyzable scope, and measured by
+mutation testing against the real test suite. The committed runs are inspectable under [`eval/`](eval/)
+and every published figure has a machine-readable receipt in [`docs/claims.json`](docs/claims.json).
+
+| Scenario | Evidence | What it proves |
+|---|---|---|
+| tRPC, 30 injected mutations | [`mutation-2026-08-28-trpc-n30.json`](eval/mutation-2026-08-28-trpc-n30.json) | 28/28 killed mutants recalled; 2 were not killed by the suite |
+| graphql-tools, Jest | [`mutation-2026-09-07-graphql-tools-n10.json`](eval/mutation-2026-09-07-graphql-tools-n10.json) | 10/10 killed mutants recalled across a second workspace layout |
+| Real package pilot | [`pilot-2026-09-24.json`](eval/pilot-2026-09-24.json) | 32 files indexed, 0 extraction failures, guidance separated from repository-wide blind spots |
+
+The pilot is not a benchmark and does not establish a universal accuracy rate. It is a reproducible
+smoke run of the published package against this repository.
+
+### A reviewer's decision, not a diagram
+
+For agents and CI, `check-change --json` returns a routing decision plus evidence:
+
+```json
+{
+  "decision": "targeted-review",
+  "risk": "medium",
+  "affected_test_files": 3,
+  "blind_spot_count": 0,
+  "graph_health": {"warnings": []}
+}
+```
+
+### What the numbers do and do not mean
+
+The 28/28 and 10/10 figures are mutation-testing recall on two pinned repositories. They mean every
+test file that failed for each killed mutation was present in the predicted set **within the measured
+static-analysis boundary**. They do not mean codeblast catches every production regression, understands
+dynamic runtime behavior, or provides function-level guarantees for Python.
+
+The conservative import/file channel is deliberately retained: a controlled call-only ablation reached
+better precision but recalled only 2/14 killed mutations. Treat `call` items as the first reading list,
+the complete result as the test safety net, and every blind spot as an explicit limit.
+`review` means inspect before merge; it does not mean the tool has proven the change unsafe. A nonzero
+graph failure or an incomplete impact result is a reason to stop and inspect, not a reason to hide the
+uncertainty.
 
 ## The precision promise (bounded, and evidence-backed)
 
@@ -157,15 +236,38 @@ authoring agent rated its own comments; both numbers and the fixes that followed
 - **You want cross-service / cross-repo edges, or Java.** The graph model reserves the node types, v1 does not fill those edges, and Java is explicitly not implemented ([intent.md](intent.md)).
 - **You want the PR bot to replace a reviewer.** It is a structural-change signal whose usefulness measured between 20% and 75% depending on the review round.
 
-## For AI agents
 
+### Unified change safety check
+
+For agents and CI that need one decision instead of composing `change` and `impact`, run:
+
+```bash
+codeblast check-change <repo> <base-sha> <head-sha> --json
 ```
+
+The output contains `decision` (`safe-to-review`, `targeted-review`, or `review`), `risk`, reasons,
+recommended actions, structural facts, predicted affected-test count, blind-spot count, truncation,
+and the complete graph diff. It is a conservative routing decision, not a claim that the change is
+safe to merge. `review` is required when API surface contracts, removed symbols, or incomplete impact
+results are detected.
+## For AI agents
+
+```text
 before editing:  impact "symbol" --json    → callsite list into context, so nothing gets missed
-after editing:   change HEAD~1 HEAD --json → self-check for scope creep and accidental deletions
+after editing:   check-change repo base head --json → risk, graph health, affected tests and warnings
 ```
 
-The full contract and interpretation discipline (including "never pretend the blind-spot list is complete") is in [SKILL.md](SKILL.md).
-Agent conventions: [AGENTS.md](AGENTS.md).
+The full contract and interpretation discipline (including “never pretend the impact list is complete”)
+is in [SKILL.md](SKILL.md). Agent conventions: [AGENTS.md](AGENTS.md).
+
+## Help improve the reviewer
+
+Found a false positive, missed impact, noisy comment, or wrong silence decision? Open a
+[privacy-safe bot feedback issue](https://github.com/alloevil/codeblast/issues/new?template=bot-feedback.yml).
+Share the public PR URL and a redacted explanation; never paste source code, secrets, private diffs,
+or full repository contents. Reproducible benchmark results and pilot evidence belong in [`eval/`](eval/),
+not in issue comments.
+
 
 ## FAQ
 
@@ -179,14 +281,16 @@ Agent conventions: [AGENTS.md](AGENTS.md).
 
 **Where are the numbers I can check?** Machine-readable claims with metric, method, repro command and evidence path are published at [claims.json](https://alloevil.github.io/codeblast/claims.json); the raw mutation and PR-replay runs are archived under [`eval/`](eval/) as records of runs that were made (the harness writes to `/tmp`, so the files are manual copies with no commit or version pin, and `mutation_check.py` picks candidates with `ORDER BY RANDOM()` — read them as archived runs, not as one-command regenerations), and the acceptance log with every downgrade and rejected optimization is [intent.md](intent.md).
 
+### PR bot feedback
+
+Feedback is intentionally issue-based and privacy-safe. Report only the public PR URL, the affected
+decision category, and a redacted explanation. Do not include source code, secrets, proprietary diffs,
+or full repository contents. The useful labels are false positive, missed impact, noise, incorrect
+silence, or incorrect recommendation. Feedback is qualitative calibration data; it is not telemetry
+and codeblast does not require access to customer repositories.
+
 ## Status & roadmap
 
 M0 graph engine → M1 Impact → M3 architecture map → M4 graph diff + PR bot → M5 precision extensions — **all shipped**; two acceptance steps were downgraded rather than passed (M2's verification method, and M3's original "10 minutes, 5 questions" test which was never run — ⚠️ in [intent.md](intent.md)), and the SemArc alignment check was dropped. Single source of truth for design and acceptance criteria: [intent.md](intent.md).
 
 MIT © 2026
-
----
-
-<p align="center">
-  <a href="https://github.com/oil-oil/beautify-github-readme"><img src="./assets/readme/made-with-beautify.svg" width="300" alt="README made with beautify-github-readme"></a>
-</p>

package/README.zh-CN.md

@@ -33,7 +33,7 @@
 ```bash
 npx codeblast demo            # 给当前仓库建图、跑一次 impact 查询、导出架构图
 npm i -g codeblast            # 或全局安装；需要 Node ≥ 22.13（内置 sqlite）或 Bun
-                              # npm 上的版本是 0.3.0；本仓库是 0.3.1（尚未发布）
+                              # npm 上的版本是 0.3.3，与本仓库一致
 
 # 作为 agent skill 安装（Claude Code、Codex、Cursor 等）
 npx skills add alloevil/codeblast
@@ -132,9 +132,3 @@ Agent 规范另见 [AGENTS.md](AGENTS.md)。
 M0 图谱引擎 → M1 Impact → M3 架构图 → M4 图 diff + PR bot → M5 精度扩展，**全部交付**；其中两项验收是降级而非通过（M2 的验证方式、M3 原定的"陌生工程师 10 分钟 5 问"从未执行——见 intent.md 的 ⚠️），SemArc 对齐检查已作废。方案与验收标准的单一事实源：[intent.md](intent.md)。
 
 MIT © 2026
-
----
-
-<p align="center">
-  <a href="https://github.com/oil-oil/beautify-github-readme"><img src="./assets/readme/made-with-beautify.svg" width="300" alt="README made with beautify-github-readme"></a>
-</p>

package/SKILL.md

@@ -9,18 +9,79 @@ Three deterministic queries over a graph built by `tsc` (TypeScript, function-le
 Python AST (file-level with typed-call upgrades). Every result carries the `file:line` where the
 dependency actually occurs. The graph comes from the code, not from a model's reading of it.
 
-## When to run it
-
 | Situation | Command | What you get back |
 |---|---|---|
-| About to edit an exported symbol | `codeblast impact <db> "<symbol>" --json` | The callsites you must review and the tests you must run |
+| About to edit an exported symbol | `codeblast impact <db> "<symbol>" --json` | `guidance.review_first`, `guidance.run_tests`, conservative items and warnings |
 | Finished a multi-file change; verifying scope | `codeblast change <repo> HEAD~1 HEAD --json` | Symbols and dependency edges added / removed / renamed |
+| Need one merge-safety decision | `codeblast check-change <repo> <base> <head> --json` | Risk, decision, graph health, affected tests and recommended actions |
 | Need to understand an unfamiliar repo | `codeblast archmap <db> --out arch.html` | Module → file → symbol map with cycle detection |
 | Reviewing a PR | `codeblast pr-comment <repo> <base> <head>` | Markdown review comment; empty output when nothing structural changed |
 
 Prerequisites: Node ≥ 22.13 or Bun ≥ 1.0 (`npx codeblast` works with no install); `python3` for Python
 repos; the target repo's dependencies installed (missing `node_modules` turns external calls into blind spots).
 
+
+Recommended agent loop:
+
+```text
+1. index the repository and check `failures == 0`
+2. before editing: read `impact --json` and start with `guidance.review_first`
+3. make the change
+4. run `check-change --json` against base and head
+5. run distinct files from `guidance.run_tests` / `affected_test_files`
+6. report `warnings`, blind spots, and every `via_file:via_line` evidence location
+```
+
+Never turn a `safe-to-review` routing result into “safe to merge”; the command routes attention and
+
+`check-change --json` has `schema_version: "1"` and `engine_version`. Its exit codes are stable:
+
+- `0`: analysis completed with no high-risk or graph-health warning;
+- `1`: analysis completed but routes the change to review (`high` risk or incomplete graph);
+- `2`: command, repository, worktree, or graph construction error.
+
+`impact --json` also has `schema_version: "1"`; every guidance array is de-duplicated and sorted for
+stable agent diffs. Treat the schema version as a compatibility boundary, not as a prose suggestion.
+
+Machine-readable compatibility contract:
+
+```text
+impact --json: schema_version=1, guidance arrays sorted and de-duplicated
+check-change --json: schema_version=1, engine_version, decision, risk, graph_health
+exit 0: result complete and no high-risk routing
+exit 1: result complete but review routing is required
+exit 2: analysis or repository error; do not consume the result as evidence
+```
+
+When a future schema version appears, stop and read its contract before making decisions from fields
+that are not explicitly understood. Do not silently fall back to prose parsing.
+
+The formal schemas are committed at [`eval/check-change.schema.json`](eval/check-change.schema.json)
+and [`eval/impact.schema.json`](eval/impact.schema.json). Version policy: within schema version `1`,
+new optional fields may be added, but existing field meanings, enum values, array ordering, and exit
+codes remain stable. A breaking field removal, type change, or enum change requires a new schema
+version and an explicit migration note. Consumers must reject unknown schema versions rather than
+guessing.
+
+The supported agent-facing artifacts are the two version-one JSON contracts and the smoke command:
+`bun run agent-smoke` (or `node eval/agent-workflow-smoke.mjs` after building). A consumer integration
+should fail closed when the schema version is unknown, and should preserve the complete JSON artifact
+alongside its human summary for later review.
+
+Continuous evolution outputs:
+
+```bash
+bun run release-smoke          # package install and executable surface
+bun run agent-smoke            # end-to-end safety JSON contract
+bun run pilot-summary          # committed pilot graph/impact summary
+bun run guidance-stability     # deterministic guidance sample
+bun run validate-compatibility # compatibility sample boundary check
+```
+
+Each command should either produce a small machine-readable result or fail. Keep the result with the
+release or compatibility evidence; a green test suite without a current evidence sample is not a
+complete evolution cycle.
+tests. The graph health and warning fields are part of the contract.
 ## Interpretation rules — read before running
 
 These are the mistakes an agent makes with this tool. Each one has produced a wrong answer in practice.
@@ -53,8 +114,7 @@ codeblast index <repo-root> --db /tmp/graph.db
 
 Auto-discovers every package `tsconfig.json` in a monorepo and ingests Python via AST. Re-running only
 processes files whose content hash changed. Stdout is one JSON object — this is a real run of
-`codeblast index` against [tRPC](https://github.com/trpc/trpc) at commit `66d0544` with codeblast 0.3.0
-(timing is machine-dependent; the counts are not):
+`codeblast index` against [tRPC](https://github.com/trpc/trpc) at commit `66d0544` with the historical codeblast 0.3.0 benchmark
 
 ```json
 { "db": "/tmp/graph.db", "seconds": 5.2, "tsconfigs": 34, "files_indexed": 957, "files_skipped": 0,
@@ -93,9 +153,21 @@ Output (`--json`):
     via_file: string; via_line: number;       // where the dependency occurs (rule 6)
   }>;
   co_change_hints: Array<{ file: string; co_commits: number; evidence: string }>;  // rule 5
+  guidance: {
+    review_first: string[];  // call-channel non-test nodes
+    run_tests: string[];     // test file paths, de-duplicate before running
+    conservative: string[];  // non-test file-channel nodes; never discard
+    warnings: string[];      // truncation and blind-spot warnings
+  };
 }
 ```
 
+The `guidance` object is a convenience projection of `items`; it does not add analysis results.
+Use `review_first` for the initial callsite checklist, `run_tests` for the affected test files,
+and `conservative` as the import/re-export safety net. `warnings` is non-empty when the result is
+incomplete or the target file contains unresolved analysis. Always retain `via_file` and `via_line`
+when reporting a dependency.
+
 How to use it: `items.filter(level === "direct")` is the callsite checklist. `items.filter(level ===
 "tests")` de-duplicated by `file` is the test set to run. Test-directory fixtures are included
 conservatively; estimate test cost by distinct files, not item count.

package/dist/bin.js

@@ -238,15 +238,30 @@ class Extractor {
   rel(fileName) {
     return path.relative(this.rootDir, fileName);
   }
+  safeSymbolAt(node) {
+    try {
+      return this.checker.getSymbolAtLocation(node);
+    } catch {
+      return;
+    }
+  }
+  safeAliased(symbol) {
+    if (!(symbol.flags & ts.SymbolFlags.Alias))
+      return symbol;
+    try {
+      return this.checker.getAliasedSymbol(symbol);
+    } catch {
+      return symbol;
+    }
+  }
   collectImplementers() {
     for (const sf of this.sourceFiles()) {
       const visit = (node) => {
         if (ts.isClassDeclaration(node) && node.heritageClauses) {
           for (const clause of node.heritageClauses) {
             for (const typeNode of clause.types) {
-              let sym = this.checker.getSymbolAtLocation(typeNode.expression);
-              if (sym && sym.flags & ts.SymbolFlags.Alias)
-                sym = this.checker.getAliasedSymbol(sym);
+              const raw = this.safeSymbolAt(typeNode.expression);
+              const sym = raw ? this.safeAliased(raw) : undefined;
               const decl = sym?.declarations?.[0];
               if (!decl)
                 continue;
@@ -289,18 +304,27 @@ class Extractor {
       if (ts.isImportDeclaration(stmt) || ts.isExportDeclaration(stmt)) {
         const spec = stmt.moduleSpecifier;
         if (spec && ts.isStringLiteral(spec)) {
-          const resolved = this.resolveModule(spec.text, sf.fileName);
+          let resolved;
+          try {
+            resolved = this.resolveModule(spec.text, sf.fileName);
+          } catch {
+            blindSpots.push({ file: relPath, line: lineOf(stmt), reason: `module resolution failed: ${spec.text}`, src_file: relPath });
+          }
           if (!resolved) {
-            for (const entry of this.externalReentry(spec.text, sf.fileName)) {
-              edges.push({
-                src: relPath,
-                dst: this.rel(entry),
-                kind: "imports",
-                file: relPath,
-                line: lineOf(stmt),
-                confidence: "conservative",
-                src_file: relPath
-              });
+            try {
+              for (const entry of this.externalReentry(spec.text, sf.fileName)) {
+                edges.push({
+                  src: relPath,
+                  dst: this.rel(entry),
+                  kind: "imports",
+                  file: relPath,
+                  line: lineOf(stmt),
+                  confidence: "conservative",
+                  src_file: relPath
+                });
+              }
+            } catch {
+              blindSpots.push({ file: relPath, line: lineOf(stmt), reason: `external reentry resolution failed: ${spec.text}`, src_file: relPath });
             }
           } else {
             edges.push({
@@ -429,9 +453,8 @@ class Extractor {
           for (const clause of node.heritageClauses) {
             const ek = clause.token === ts.SyntaxKind.ImplementsKeyword ? "implements" : "extends";
             for (const t of clause.types) {
-              let sym = this.checker.getSymbolAtLocation(t.expression);
-              if (sym && sym.flags & ts.SymbolFlags.Alias)
-                sym = this.checker.getAliasedSymbol(sym);
+              const raw = this.safeSymbolAt(t.expression);
+              const sym = raw ? this.safeAliased(raw) : undefined;
               const decl = sym?.declarations?.[0];
               const dst = decl ? this.nodeIdOfDecl(decl) : undefined;
               if (dst)
@@ -489,9 +512,8 @@ class Extractor {
   }
   resolveCall(call, caller, relPath, line, edges, blindSpots) {
     const expr = call.expression;
-    let sym = this.checker.getSymbolAtLocation(expr);
-    if (sym && sym.flags & ts.SymbolFlags.Alias)
-      sym = this.checker.getAliasedSymbol(sym);
+    const raw = this.safeSymbolAt(expr);
+    const sym = raw ? this.safeAliased(raw) : undefined;
     const decl = sym?.valueDeclaration ?? sym?.declarations?.[0];
     if (!decl) {
       const structural = ts.isElementAccessExpression(expr) || ts.isPropertyAccessExpression(expr) && ["call", "apply", "bind"].includes(expr.name.text);
@@ -709,7 +731,11 @@ function indexProgram(extractor) {
     } catch (err) {
       failures++;
       seenFiles.delete(relPath);
-      console.error(`EXTRACT FAILED ${relPath}: ${err instanceof Error ? err.message : err}`);
+      const detail = err instanceof Error ? `${err.name}: ${err.message}${err.stack ? `
+${err.stack.split(`
+`).slice(1, 12).join(`
+`)}` : ""}` : String(err);
+      console.error(`EXTRACT FAILED ${relPath}: ${detail}`);
     }
   }
 }
@@ -1131,7 +1157,17 @@ var init_impact_cli = __esm(() => {
   result = impact(db2, targetId, maxNodes);
   ms = (performance.now() - t02).toFixed(0);
   if (process.argv.includes("--json")) {
-    process.stdout.write(JSON.stringify(result) + `
+    const uniqueSorted = (values) => [...new Set(values)].sort((a, b) => a.localeCompare(b));
+    const guidance = {
+      review_first: uniqueSorted(result.items.filter((it) => it.channel === "call" && it.level !== "tests").map((it) => it.id)),
+      run_tests: uniqueSorted(result.items.filter((it) => it.level === "tests").map((it) => it.file)),
+      conservative: uniqueSorted(result.items.filter((it) => it.channel === "file" && it.level !== "tests").map((it) => it.id)),
+      warnings: [
+        ...result.truncated ? ["impact_truncated_run_full_test_suite"] : [],
+        ...result.blind_spot_count > 0 ? ["blind_spots_may_underestimate_impact"] : []
+      ]
+    };
+    process.stdout.write(JSON.stringify({ schema_version: "1", ...result, guidance }) + `
 `);
     db2.close();
     process.exitCode = 0;
@@ -1436,7 +1472,7 @@ async function layoutGraph(nodes, edges) {
     }))
   };
 }
-var CLIENT_JS, dbPath3, outFlag2, outPath2, overlayFlag, overlayPath, repoFlag, repoUrl, impactFlag, impactTarget, diffFlag, diffBase, db3, overlay, TEST_RE, moduleOf = (file) => {
+var CLIENT_JS, dbPath3, outFlag2, outPath2, overlayFlag, overlayPath, repoFlag, repoUrl, impactFlag, impactTarget, diffFlag, diffBase, siteFlag, siteUrl, ogImageFlag, ogImage, repoLabel, pageUrl, pageKind, pageTitle, pageDesc, escAttr = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;"), headMeta, db3, overlay, TEST_RE, moduleOf = (file) => {
   if (TEST_RE.test(file))
     return "tests";
   const ix = file.indexOf("/");
@@ -1460,6 +1496,51 @@ var init_archmap_html = __esm(async () => {
   impactTarget = impactFlag >= 0 ? process.argv[impactFlag + 1] : undefined;
   diffFlag = process.argv.indexOf("--diff");
   diffBase = diffFlag >= 0 ? process.argv[diffFlag + 1] : undefined;
+  siteFlag = process.argv.indexOf("--site-url");
+  siteUrl = siteFlag >= 0 ? process.argv[siteFlag + 1].replace(/\/+$/, "") : undefined;
+  ogImageFlag = process.argv.indexOf("--og-image");
+  ogImage = ogImageFlag >= 0 ? process.argv[ogImageFlag + 1] : undefined;
+  repoLabel = (() => {
+    const m = repoUrl?.match(/github\.com\/([^/]+\/[^/]+)/);
+    if (m)
+      return m[1].replace(/\.git$/, "");
+    const base = outPath2.split("/").pop() ?? outPath2;
+    return base.replace(/\.html$/, "");
+  })();
+  pageUrl = siteUrl ? `${siteUrl}/${outPath2.split("/").pop()}` : undefined;
+  pageKind = impactTarget ? "blast-radius map" : diffBase ? "change map" : "architecture map";
+  pageTitle = `${repoLabel} — ${pageKind}`;
+  pageDesc = `Interactive architecture map of ${repoLabel} generated by codeblast: a module-level` + ` dependency graph where hovering a node lights up its fan-in and clicking it shows its files,` + ` symbols and import edges.` + (impactTarget ? ` Includes the blast-radius overlay for ${impactTarget}.` : "") + (overlayPath ? " Includes the change overlay." : "");
+  headMeta = [
+    `<title>${escAttr(pageTitle)}</title>`,
+    `<meta name="description" content="${escAttr(pageDesc)}">`,
+    ...pageUrl ? [`<link rel="canonical" href="${escAttr(pageUrl)}">`] : [],
+    `<meta property="og:type" content="website">`,
+    `<meta property="og:title" content="${escAttr(pageTitle)}">`,
+    `<meta property="og:description" content="${escAttr(pageDesc)}">`,
+    ...pageUrl ? [`<meta property="og:url" content="${escAttr(pageUrl)}">`] : [],
+    `<meta property="og:site_name" content="codeblast">`,
+    ...ogImage ? [`<meta property="og:image" content="${escAttr(ogImage)}">`] : [],
+    `<meta name="twitter:card" content="${ogImage ? "summary_large_image" : "summary"}">`,
+    `<meta name="twitter:title" content="${escAttr(pageTitle)}">`,
+    `<meta name="twitter:description" content="${escAttr(pageDesc)}">`,
+    ...ogImage ? [`<meta name="twitter:image" content="${escAttr(ogImage)}">`] : [],
+    `<script type="application/ld+json">`,
+    JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "WebPage",
+      name: pageTitle,
+      description: pageDesc,
+      inLanguage: "zh-CN",
+      ...pageUrl ? { url: pageUrl } : {},
+      ...repoUrl ? {
+        isBasedOn: repoUrl,
+        about: { "@type": "SoftwareSourceCode", name: repoLabel, codeRepository: repoUrl }
+      } : {}
+    }, null, 2),
+    `</script>`
+  ].join(`
+`);
   if (!dbPath3) {
     console.error("usage: codeblast archmap <graph.db> --out arch.html");
     process.exit(1);
@@ -1629,10 +1710,10 @@ var init_archmap_html = __esm(async () => {
     fileEdges: importRows
   };
   html = `<!DOCTYPE html>
-<html lang="zh">
+<html lang="zh-CN">
 <head>
 <meta charset="utf-8">
-<title>codeblast · Architecture Map</title>
+${headMeta}
 <style>
   :root { --bg:#0d1117; --panel:#161b22; --border:#30363d; --fg:#e6edf3; --dim:#8b949e;
           --accent:#58a6ff; --warn:#f85149; --ok:#3fb950; }
@@ -1671,6 +1752,11 @@ var init_archmap_html = __esm(async () => {
   .edge.cyclic { stroke: var(--warn); stroke-dasharray: 5 3; stroke-width: 2;
     animation: cycflow 1.2s linear infinite; }
   @keyframes cycflow { to { stroke-dashoffset: -16; } }
+  /* 循环依赖用虚线静止表示即可 —— 虚线与颜色承载信息，流动只是让它更显眼。
+     reduced-motion 下停掉动画，而不是去掉虚线。 */
+  @media (prefers-reduced-motion: reduce) {
+    .edge.cyclic { animation: none; }
+  }
   .edge.hi { stroke: #d29922 !important; stroke-width: 2.6; stroke-opacity: 1; }
   .edge.dim { stroke-opacity: 0.1; }
   .edge.faint { stroke-opacity: 0.06; }
@@ -1947,7 +2033,7 @@ function bodySignalCount(bodyChanged, diffLineCount, hasCallImpact) {
   return n;
 }
 function coreNamedCount(diff, prodNodesAdded) {
-  return diff.edgesAdded.filter((e) => !AUX_RE.test(e.file)).length + prodNodesAdded.filter((n) => !AUX_RE.test(n.file)).length + diff.renamed.filter((r) => !AUX_RE.test(r.file)).length + diff.visibilityChanged.filter((v) => !AUX_RE.test(v.file)).length + diff.signatureChanged.filter((s) => !AUX_RE.test(s.file)).length;
+  return diff.edgesAdded.filter((e) => !AUX_RE.test(e.file)).length + diff.edgesRemoved.filter((e) => !AUX_RE.test(e.file)).length + prodNodesAdded.filter((n) => !AUX_RE.test(n.file)).length + diff.nodesRemoved.filter((n) => !AUX_RE.test(n.file) && !TEST_RE3.test(n.file)).length + diff.renamed.filter((r) => !AUX_RE.test(r.file)).length + diff.visibilityChanged.filter((v) => !AUX_RE.test(v.file)).length + diff.signatureChanged.filter((s) => !AUX_RE.test(s.file)).length;
 }
 var TEST_RE3, AUX_RE, BIG_DIFF_LINES = 40;
 var init_pr_silence = __esm(() => {
@@ -1955,6 +2041,54 @@ var init_pr_silence = __esm(() => {
   AUX_RE = /^(www|docs|examples)\//;
 });
 
+// src/pr-decision.ts
+function reviewDecision(input) {
+  const { diff, prodNodesAdded, bodyChanged, affectedTests, truncated, blindSpotCount } = input;
+  const apiContractions = diff.visibilityChanged.filter((v) => !v.nowExported).length;
+  const apiChanges = apiContractions + diff.signatureChanged.length;
+  const removals = diff.nodesRemoved.length;
+  const behaviorChanges = bodyChanged.length;
+  const reasons = [];
+  const recommendedActions = [];
+  let risk = "low";
+  if (apiContractions > 0 || removals > 0 || truncated)
+    risk = "high";
+  else if (apiChanges > 0 || behaviorChanges > 0 || affectedTests > 0 || blindSpotCount > 0)
+    risk = "medium";
+  if (apiContractions > 0)
+    reasons.push(`${apiContractions} exported symbol${apiContractions === 1 ? " is" : "s are"} no longer public`);
+  if (removals > 0)
+    reasons.push(`${removals} symbol${removals === 1 ? " was" : "s were"} removed`);
+  if (diff.signatureChanged.length > 0)
+    reasons.push(`${diff.signatureChanged.length} exported signature${diff.signatureChanged.length === 1 ? " changed" : "s changed"}`);
+  if (behaviorChanges > 0)
+    reasons.push(`${behaviorChanges} function bod${behaviorChanges === 1 ? "y" : "ies"} changed`);
+  if (affectedTests > 0)
+    reasons.push(`${affectedTests} test file${affectedTests === 1 ? " is" : "s are"} in the predicted impact set`);
+  if (truncated)
+    reasons.push("the impact set exceeded the reporting limit");
+  if (blindSpotCount > 0)
+    reasons.push(`${blindSpotCount} static-analysis blind spot${blindSpotCount === 1 ? "" : "s"} may hide impact`);
+  if (reasons.length === 0 && prodNodesAdded.length > 0)
+    reasons.push(`${prodNodesAdded.length} production symbol${prodNodesAdded.length === 1 ? " was" : "s were"} added`);
+  if (reasons.length === 0)
+    reasons.push("only low-risk structural additions were found");
+  if (apiChanges > 0 || removals > 0)
+    recommendedActions.push("Review the public API changes and migration impact.");
+  if (truncated)
+    recommendedActions.push("Run the full test suite; the reported impact list is truncated.");
+  else if (affectedTests > 0)
+    recommendedActions.push(`Run the ${affectedTests} predicted affected test file${affectedTests === 1 ? "" : "s"}.`);
+  if (blindSpotCount > 0)
+    recommendedActions.push("Inspect the reported blind spots before treating the impact set as complete.");
+  if (behaviorChanges > 0)
+    recommendedActions.push("Review the changed function bodies even where the exported shape is unchanged.");
+  if (recommendedActions.length === 0)
+    recommendedActions.push("Review the named structural additions; no existing API contraction was detected.");
+  const summary = risk === "high" ? "Review before merge: the change removes API surface, deletes symbols, or has an incomplete impact set." : risk === "medium" ? "Targeted review recommended: behavior, API shape, tests, or blind spots changed." : "Low structural risk: only additive changes with no predicted affected tests were found.";
+  return { risk, summary, reasons, recommendedActions };
+}
+
 // src/pr-comment.ts
 var exports_pr_comment = {};
 import fs7 from "node:fs";
@@ -1993,7 +2127,7 @@ var args3, repo2, baseSha, headSha, urlFlag, repoUrl2, dbPathA = "/tmp/codeblast
   const wrap = s.kind === "interface" || s.kind === "const" ? (t) => t : (t) => `(${t})`;
   const what = s.kind === "interface" ? "成员变化" : s.kind === "const" ? "类型变化" : "";
   return `- \`${s.name}\`${what ? ` ${what}` : ""}: \`${wrap(clip(s.from))}\` → \`${wrap(clip(s.to))}\` （${link(s.file, s.line)}）`;
-}, apiSig, testSig, uncovered, impactRows, prodNodesAdded, diffLineCount, bodySignal, coreNamed;
+}, apiSig, testSig, uncovered, impactRows, affectedTestCount = 0, anyImpactTruncated = false, totalBlindSpots = 0, prodNodesAdded, diffLineCount, bodySignal, coreNamed, changedFiles, changedTests, testedBodySignal, decision;
 var init_pr_comment = __esm(async () => {
   init_db();
   init_proc();
@@ -2106,6 +2240,9 @@ var init_pr_comment = __esm(async () => {
       const r = impact(dbB2, n.id, 2000);
       const callItems = r.items.filter((i) => i.channel === "call");
       const tests = callItems.filter((i) => i.level === "tests").length;
+      affectedTestCount += tests;
+      anyImpactTruncated ||= r.truncated;
+      totalBlindSpots += r.blind_spot_count;
       impactRows.push(`| \`${n.name}\` | ${n.kind} | ${callItems.length} | ${tests} | ${link(n.file, n.line)} |`);
       const blind = r.blind_spot_count > 0;
       if (tests === 0 && n.kind !== "interface" && n.kind !== "const") {
@@ -2132,7 +2269,11 @@ var init_pr_comment = __esm(async () => {
     }
   });
   coreNamed = coreNamedCount(diff2, prodNodesAdded);
-  if (coreNamed + bodySignal === 0)
+  changedFiles = spawnSync(["git", "diff", "--name-only", baseSha, headSha], { cwd: repo2 }).stdout.split(`
+`).filter(Boolean);
+  changedTests = changedFiles.some((file) => TEST_RE3.test(file));
+  testedBodySignal = bodyChanged.length > 0 && changedTests ? 1 : 0;
+  if (coreNamed + bodySignal + testedBodySignal === 0)
     process.exit(0);
   if (bodyChanged.length > 0) {
     const rows = [];
@@ -2153,16 +2294,153 @@ var init_pr_comment = __esm(async () => {
   if (total2 === 0 && bodyChanged.length > 0) {
     lines3[2] = `**无结构变更**,但有 ${bodyChanged.length} 个函数体内改动（见下）`;
   }
+  decision = reviewDecision({
+    diff: diff2,
+    prodNodesAdded,
+    bodyChanged,
+    affectedTests: affectedTestCount,
+    truncated: anyImpactTruncated,
+    blindSpotCount: totalBlindSpots
+  });
+  lines3.splice(3, 0, `> **Review decision · ${decision.risk.toUpperCase()}** — ${decision.summary}`, `> ${decision.reasons.join("; ")}.`, ``, `### Recommended checks`, ``, ...decision.recommendedActions.map((action) => `- ${action}`), ``);
   lines3.push(`<sub>由 [codeblast](https://github.com/alloevil/codeblast) 生成 · 每条结论基于静态分析,含证据链接 · 动态调用盲区不在本报告内 · 评论不准?[30 秒反馈](https://github.com/alloevil/codeblast/issues/new?template=bot-feedback.yml&title=${encodeURIComponent(`[feedback] ${baseSha.slice(0, 7)}..${headSha.slice(0, 7)}`)})</sub>`);
   console.log(lines3.join(`
 `));
 });
 
-// src/demo.ts
-var exports_demo = {};
+// src/check-change.ts
+var exports_check_change = {};
 import fs8 from "node:fs";
 import path3 from "node:path";
-var repo3, db6 = "/tmp/codeblast-demo.db", out = "/tmp/codeblast-demo-arch.html", run = (label, args) => {
+function buildGraphAt3(ref, db) {
+  const wt = `/tmp/codeblast-check-${ref.replace(/[^\w]/g, "_")}`;
+  spawnSync(["git", "worktree", "remove", "--force", wt], { cwd: repo3 });
+  const add = spawnSync(["git", "worktree", "add", "--detach", wt, ref], { cwd: repo3 });
+  if (add.exitCode !== 0)
+    throw new Error(add.stderr.slice(0, 300));
+  try {
+    const built = spawnSync(selfCommand("index", wt, "--db", db));
+    if (built.exitCode !== 0)
+      throw new Error(built.stderr.slice(0, 500));
+  } finally {
+    spawnSync(["git", "worktree", "remove", "--force", wt], { cwd: repo3 });
+  }
+}
+var SCHEMA_VERSION = "1", EXIT_OK = 0, EXIT_REVIEW = 1, EXIT_ERROR = 2, readVersion = () => {
+  try {
+    const parsed = JSON.parse(fs8.readFileSync(path3.join(import.meta.dirname, "..", "package.json"), "utf8"));
+    if (parsed && typeof parsed === "object" && "version" in parsed && typeof parsed.version === "string")
+      return parsed.version;
+  } catch {}
+  return "unknown";
+}, ENGINE_VERSION, repo3, baseSha2, headSha2, dbAPath = "/tmp/codeblast-check-base.db", dbBPath = "/tmp/codeblast-check-head.db", dbA3, dbB3, graphHealth = (db) => ({
+  files: Number(db.prepare("SELECT COUNT(*) c FROM files").get().c),
+  nodes: Number(db.prepare("SELECT COUNT(*) c FROM nodes").get().c),
+  edges: Number(db.prepare("SELECT COUNT(*) c FROM edges").get().c),
+  blind_spots: Number(db.prepare("SELECT COUNT(*) c FROM blind_spots").get().c)
+}), healthBase, healthHead, diff3, healthWarnings, prodNodesAdded2, total3, affectedTests = 0, truncated = false, blindSpots = 0, bodyChanged2, diffText, currentFile = "", diffLineCount2, decision2, output;
+var init_check_change = __esm(() => {
+  init_db();
+  init_proc();
+  init_impact();
+  init_pr_silence();
+  ENGINE_VERSION = readVersion();
+  process.on("uncaughtException", (error) => {
+    console.error(`check-change analysis error: ${error instanceof Error ? error.message : error}`);
+    process.exitCode = EXIT_ERROR;
+  });
+  process.on("unhandledRejection", (reason) => {
+    console.error(`check-change analysis error: ${reason instanceof Error ? reason.message : reason}`);
+    process.exitCode = EXIT_ERROR;
+  });
+  [repo3, baseSha2, headSha2] = process.argv.slice(2);
+  if (!repo3 || !baseSha2 || !headSha2) {
+    console.error("usage: codeblast check-change <repo> <base-sha> <head-sha> --json");
+    process.exit(1);
+  }
+  for (const f of [dbAPath, dbBPath])
+    for (const suffix of ["", "-wal", "-shm"])
+      fs8.rmSync(f + suffix, { force: true });
+  buildGraphAt3(baseSha2, dbAPath);
+  buildGraphAt3(headSha2, dbBPath);
+  dbA3 = openDatabase(dbAPath, { readonly: true });
+  dbB3 = openDatabase(dbBPath, { readonly: true });
+  healthBase = graphHealth(dbA3);
+  healthHead = graphHealth(dbB3);
+  diff3 = graphDiff(dbA3, dbB3);
+  healthWarnings = [
+    ...healthHead.files === 0 || healthHead.nodes === 0 ? ["graph_empty"] : [],
+    ...healthHead.nodes < healthBase.nodes / 2 ? ["graph_node_count_dropped_sharply"] : []
+  ];
+  prodNodesAdded2 = diff3.nodesAdded.filter((n) => !TEST_RE3.test(n.file));
+  total3 = structuralTotal(diff3);
+  for (const node of [...diff3.nodesAdded, ...diff3.renamed.map((r) => ({ id: `${r.file}#${r.to}`, kind: r.kind, name: r.to, file: r.file, line: 0 }))].slice(0, 15)) {
+    try {
+      const result = impact(dbB3, node.id, 2000);
+      affectedTests += new Set(result.items.filter((item) => item.level === "tests").map((item) => item.file)).size;
+      truncated ||= result.truncated;
+      blindSpots += result.blind_spot_count;
+    } catch {}
+  }
+  bodyChanged2 = [];
+  diffText = spawnSync(["git", "diff", "--unified=0", baseSha2, headSha2, "--", "*.ts", "*.tsx"], { cwd: repo3 }).stdout;
+  for (const line of diffText.split(`
+`)) {
+    const file = line.match(/^\+\+\+ b\/(.+)$/);
+    if (file) {
+      currentFile = file[1];
+      continue;
+    }
+    const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)/);
+    if (!hunk || !currentFile || TEST_RE3.test(currentFile))
+      continue;
+    const row = dbB3.prepare("SELECT id, name, kind, file, line FROM nodes WHERE file = ? AND kind IN ('function','method') AND line <= ? AND end_line >= ? ORDER BY (end_line - line) ASC LIMIT 1").get(currentFile, Number(hunk[1]), Number(hunk[1]));
+    if (row && !bodyChanged2.some((item) => item.id === row.id))
+      bodyChanged2.push(row);
+  }
+  diffLineCount2 = spawnSync(["git", "diff", "--numstat", baseSha2, headSha2], { cwd: repo3 }).stdout.split(`
+`).reduce((sum, line) => {
+    const match = line.match(/^(\d+)\t(\d+)\t/);
+    return sum + (match ? Number(match[1]) + Number(match[2]) : 0);
+  }, 0);
+  decision2 = reviewDecision({ diff: diff3, prodNodesAdded: prodNodesAdded2, bodyChanged: bodyChanged2, affectedTests, truncated, blindSpotCount: blindSpots });
+  if (healthWarnings.length > 0) {
+    decision2.risk = "high";
+    decision2.reasons.push(...healthWarnings);
+    decision2.recommendedActions.unshift("Rebuild or inspect the graph before relying on this decision.");
+  }
+  output = {
+    schema_version: SCHEMA_VERSION,
+    engine_version: ENGINE_VERSION,
+    range: `${baseSha2}..${headSha2}`,
+    decision: decision2.risk === "high" ? "review" : decision2.risk === "medium" ? "targeted-review" : "safe-to-review",
+    risk: decision2.risk,
+    summary: decision2.summary,
+    reasons: decision2.reasons,
+    recommended_actions: decision2.recommendedActions,
+    structural_changes: total3,
+    affected_test_files: affectedTests,
+    blind_spot_count: blindSpots,
+    graph_health: { base: healthBase, head: healthHead, warnings: healthWarnings },
+    truncated,
+    signals: {
+      core_named: coreNamedCount(diff3, prodNodesAdded2),
+      body: bodySignalCount(bodyChanged2, diffLineCount2, () => false),
+      aux_only: total3 > 0 && coreNamedCount(diff3, prodNodesAdded2) === 0 && bodyChanged2.length === 0
+    },
+    diff: diff3
+  };
+  console.log(JSON.stringify(output));
+  dbA3.close();
+  dbB3.close();
+  process.exitCode = healthWarnings.length > 0 || decision2.risk === "high" ? EXIT_REVIEW : EXIT_OK;
+});
+
+// src/demo.ts
+var exports_demo = {};
+import fs9 from "node:fs";
+import path4 from "node:path";
+var repo4, db6 = "/tmp/codeblast-demo.db", out = "/tmp/codeblast-demo-arch.html", run = (label, args) => {
   console.log(`
 \x1B[36m▸ ${label}\x1B[0m`);
   console.log(`  $ codeblast ${args.slice(2).join(" ")}`);
@@ -2182,12 +2460,12 @@ var repo3, db6 = "/tmp/codeblast-demo.db", out = "/tmp/codeblast-demo-arch.html"
 var init_demo = __esm(() => {
   init_db();
   init_proc();
-  repo3 = path3.resolve(process.argv[2] ?? path3.join(import.meta.dirname, ".."));
-  console.log(`codeblast demo — target: ${repo3}`);
+  repo4 = path4.resolve(process.argv[2] ?? path4.join(import.meta.dirname, ".."));
+  console.log(`codeblast demo — target: ${repo4}`);
   for (const s of ["", "-wal", "-shm"])
-    fs8.rmSync(db6 + s, { force: true });
-  run("1/4 build graph", selfCommand("index", repo3, "--db", db6));
-  run("2/4 incremental rerun (should skip everything)", selfCommand("index", repo3, "--db", db6));
+    fs9.rmSync(db6 + s, { force: true });
+  run("1/4 build graph", selfCommand("index", repo4, "--db", db6));
+  run("2/4 incremental rerun (should skip everything)", selfCommand("index", repo4, "--db", db6));
   conn = openDatabase(db6, { readonly: true });
   pick = conn.prepare(`SELECT n.id, COUNT(DISTINCT e.src) c FROM nodes n
    JOIN edges e ON e.dst = n.id AND e.kind = 'calls'
@@ -2212,7 +2490,7 @@ var init_demo = __esm(() => {
 
 // src/name-modules.ts
 var exports_name_modules = {};
-import fs9 from "node:fs";
+import fs10 from "node:fs";
 var dbPath6, overlayFlag2, overlayPath2, db7, TEST_RE4, files3, byModule, symStmt, evidence, prompt, cmd;
 var init_name_modules = __esm(async () => {
   init_db();
@@ -2250,7 +2528,7 @@ ${JSON.stringify(evidence, null, 1)}`;
   if (!cmd) {
     const applyFlag = process.argv.indexOf("--apply");
     if (applyFlag >= 0) {
-      const namesJson = JSON.parse(fs9.readFileSync(process.argv[applyFlag + 1], "utf8"));
+      const namesJson = JSON.parse(fs10.readFileSync(process.argv[applyFlag + 1], "utf8"));
       const overlay = await loadOverlay(overlayPath2);
       for (const [mod, v] of Object.entries(namesJson)) {
         const existing = overlay.modules[mod];
@@ -2259,7 +2537,7 @@ ${JSON.stringify(evidence, null, 1)}`;
         overlay.modules[mod] = { ...existing, name: `${v.name}`, ...v.desc ? {} : {} };
         overlay.modules[mod].desc = v.desc;
       }
-      fs9.writeFileSync(overlayPath2, JSON.stringify(overlay, null, 2));
+      fs10.writeFileSync(overlayPath2, JSON.stringify(overlay, null, 2));
       console.error(`overlay written: ${overlayPath2}`);
     } else {
       console.log(prompt);
@@ -2276,7 +2554,7 @@ ${JSON.stringify(evidence, null, 1)}`;
       overlay.modules[mod] = { ...overlay.modules[mod], name: v.name };
       overlay.modules[mod].desc = v.desc;
     }
-    fs9.writeFileSync(overlayPath2, JSON.stringify(overlay, null, 2));
+    fs10.writeFileSync(overlayPath2, JSON.stringify(overlay, null, 2));
     console.error(`overlay written: ${overlayPath2}`);
   }
 });
@@ -2290,6 +2568,7 @@ var ROUTES = {
   mermaid: () => Promise.resolve().then(() => (init_archmap(), exports_archmap)),
   cochange: () => Promise.resolve().then(() => (init_cochange(), exports_cochange)),
   "pr-comment": () => init_pr_comment().then(() => exports_pr_comment),
+  "check-change": () => Promise.resolve().then(() => (init_check_change(), exports_check_change)),
   demo: () => Promise.resolve().then(() => (init_demo(), exports_demo)),
   "name-modules": () => init_name_modules().then(() => exports_name_modules)
 };
@@ -2304,13 +2583,13 @@ usage: codeblast <command> [args]
   change    <repo> <ref-a> <ref-b> [--json]     structural diff between two refs
   archmap   <graph.db> --out arch.html          interactive architecture map
             [--impact <sym>] [--diff <base.db>]   ...with impact / change overlay
-  mermaid   <graph.db>                          module map as mermaid
-  cochange  <repo> <graph.db>                   mine git history coupling
+            [--repo-url <url>]                    names the page and its JSON-LD (already used above)
   pr-comment <repo> <base-sha> <head-sha>       PR review comment (silent if no change)
+  check-change <repo> <base-sha> <head-sha>     machine-readable merge safety decision
   demo      [repo]                              build + query + map in one shot
 
 docs: https://github.com/alloevil/codeblast · demos: https://alloevil.github.io/codeblast/`);
-  process.exit(cmd2 && !ROUTES[cmd2] ? 1 : 0);
+  process.exit(cmd2 === "--help" || cmd2 === "-h" || !cmd2 ? 0 : 1);
 }
 process.argv.splice(2, 1);
 await ROUTES[cmd2]();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeblast",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Know what breaks before you merge — mutation-tested code graph with architecture, change & impact maps. Evidence on every edge. For humans and AI agents.",
   "keywords": [
     "impact-analysis",
@@ -26,7 +26,7 @@
   },
   "type": "module",
   "bin": {
-    "codeblast": "./dist/bin.js"
+    "codeblast": "dist/bin.js"
   },
   "files": [
     "dist",
@@ -38,8 +38,13 @@
     "build": "bun build src/bin.ts --target=node --outdir=dist --entry-naming=bin.js --external typescript --external @dagrejs/dagre && cp src/archmap-client.js src/py_extract.py dist/",
     "prepack": "bun run build",
     "typecheck": "tsc -p .",
-    "test": "bun test",
-    "demo": "bun src/bin.ts demo",
+    "agent-smoke": "bun run build && node eval/agent-workflow-smoke.mjs",
+    "guidance-stability": "node eval/guidance-stability.mjs",
+    "offline-replay": "bun run build && node eval/offline-replay.mjs",
+    "pilot-summary": "node eval/pilot-summary.mjs",
+    "release-smoke": "node eval/release-smoke.mjs",
+    "validate-compatibility": "node eval/validate-compatibility.mjs",
+    "validate-safety": "node eval/validate-safety.mjs",
     "verify": "python3 eval/mutation_check.py"
   },
   "engines": {
@@ -52,5 +57,11 @@
   "devDependencies": {
     "@types/node": "^26.4.0",
     "bun-types": "^1.4.0"
-  }
+  },
+  "main": "index.js",
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
+  "author": ""
 }