feat(recipes): unresolved_import_blind_spot; ship deferred complements

SutuSebastian · SutuSebastian · commit 1323b49f41f7 · 2026-06-10T12:42:44.000+03:00
unimported-exports third reason + evidence; alias-blind-spot fixture;
MCP/glossary/rule parity for CRAP and evidence; no-defer convention in
wave + harden-pr.
diff --git a/.agents/skills/harden-pr/SKILL.md b/.agents/skills/harden-pr/SKILL.md
@@ -80,7 +80,9 @@ Reviewers treat the anchor as contract. Findings that would violate it → **rep
 
 **Fix:** bugs, missing tests, docs/changeset drift, lint/type/format, error-handling gaps, edge cases, **behavior-preserving refactors in touched files**, in-scope nits (naming, comment hygiene, cheap lint fixes).
 
-**Report only:** redesign, new capabilities, semantic API changes, nits outside the diff, refactors unrelated to a flagged issue.
+**Report only:** redesign, semantic API changes, nits outside the diff, refactors unrelated to a flagged issue.
+
+**Do not defer complements:** agent-surface parity (rule/skill/MCP), glossary/architecture/golden-queries contracts, script/golden tests for acceptance criteria, and cross-links named in the plan ship in the **same PR** — not "optional v2" or post-merge unless the plan **Out of scope** section explicitly excludes them.
 
 ## Reviewer roster
 
@@ -122,7 +124,7 @@ loop:
   pass += 1
   goto loop
 capped:
-  emit deferred-nits list
+  emit deferred-nits list (each nit must cite plan Out of scope or cross-PR blocker — not "optional")
 done:
   if uncommitted fixes → git commit -m "harden: …"
   emit final report (include babysit one-liner if full mode)
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -151,6 +151,10 @@ Opt-in FTS5 virtual table over file content (`tokenize='porter unicode61'`). Alw
 
 Output mode rendering `{from, to, label?, kind?}` rows as a Mermaid `flowchart LR` diagram. Sibling of `--format sarif` / `--format annotations` in `application/output-formatters.ts`. **Bounded-input contract** (50-edge ceiling; `MERMAID_MAX_EDGES`) — unbounded inputs reject with a scope-suggestion error naming the recipe + count + scoping knobs (`LIMIT` / `--via` / `WHERE`). Auto-truncation explicitly out of scope (would be a verdict masquerading as output mode, violating the predicate-as-API moat). Recipes / ad-hoc SQL must alias columns to the `{from, to}` shape (e.g. `SELECT from_path AS "from", to_path AS "to" FROM dependencies LIMIT 50`).
 
+### CRAP score / `high-crap-score` / `coverage_source` / `effective_coverage_pct`
+
+Change Risk Anti-Patterns score per published formula: `CC² × (1 - effective_coverage/100)³ + CC` where `CC = symbols.complexity`. Bundled recipe **`high-crap-score`** ranks symbols at or above `min_crap` (default 30). **`effective_coverage_pct`** uses ingested **`coverage.coverage_pct`** when a row exists (**`coverage_source: measured`**), else graph-estimated tiers from test reachability (**`coverage_source: estimated`**: 85% direct test reference, 40% file reachable from tests via value-only **`dependencies`**, 0% otherwise). Heuristic only — not execution coverage; prefer **`codemap ingest-coverage`** before CI gates. Complements **`high-complexity-untested`** when coverage is not ingested.
+
 ### `coverage` (table)
 
 Statement coverage ingested from Istanbul JSON, LCOV, or V8 runtime (`NODE_V8_COVERAGE=...` directory via `--runtime`) via `codemap ingest-coverage <path>`. Natural-key PK `(file_path, name, line_start)` — intentionally **not** a FK to `symbols.id` because `symbols` re-creates with fresh AUTOINCREMENT ids on every `--full` reindex; the natural-key approach lets coverage rows survive that churn (`coverage` is also intentionally absent from `dropAll()`, joins the `query_baselines` precedent). Columns: `coverage_pct REAL` (`NULL` when `total_statements = 0` — "untested" and "no testable code" are different signals), `hit_statements`, `total_statements`. Orphan rows (file deleted from project) are cleaned by an explicit `DELETE FROM coverage WHERE file_path NOT IN (SELECT path FROM files)` at the end of every ingest. Three meta keys (`coverage_last_ingested_at` / `_path` / `_format`) record freshness — single ingest at a time, so format is meta-level not per-row.
diff --git a/docs/golden-queries.md b/docs/golden-queries.md
@@ -68,7 +68,7 @@ Scenarios live in **`fixtures/golden/scenarios.json`** (Tier A) or optional **`s
 
 ### Evidence columns (high-judgment recipes)
 
-Some bundled recipes add optional **`reason`** (TEXT) and **`evidence_json`** (TEXT, JSON array) columns on each row — factual detection path for agents, not engine verdicts (Moat A — not pass/fail verdicts). Bounded subqueries cap evidence at three hops; list caps append `{"truncated":true}`. Goldens assert these columns when the recipe ships evidence (`boundary-violations`, `deprecated-symbols`, `unimported-exports`).
+Some bundled recipes add optional **`reason`** (TEXT) and **`evidence_json`** (TEXT, JSON array) columns on each row — factual detection path for agents, not engine verdicts (Moat A — not pass/fail verdicts). Bounded subqueries cap evidence at three hops; list caps append `{"truncated":true}`. `unimported-exports` reasons: `no_direct_import`, `reexport_chain_possible`, `unresolved_import_blind_spot`. Goldens assert these columns when the recipe ships evidence (`boundary-violations`, `deprecated-symbols`, `unimported-exports`).
 
 ### Coverage columns (CRAP / enrichment recipes)
 
diff --git a/docs/plans/agent-enrichment-wave.md b/docs/plans/agent-enrichment-wave.md
@@ -12,15 +12,16 @@
 
 ## Shared conventions (locked)
 
-| Convention                                                                                                                                             | Applies to |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
-| **Moat A** — no `pass`/`fail` engine verdict; extra columns only                                                                                       | All        |
-| **`reason` TEXT** — machine code + short clause where useful                                                                                           | #3         |
-| **`evidence_json` TEXT** — bounded JSON array (≤3 hops)                                                                                                | shipped #1 |
-| **`confidence` / `coverage_source` / `attribution`** — recipe-specific enums                                                                           | #3, #4     |
-| **Golden update per slice** — `fixtures/golden/minimal/*.json` + `scenarios.json`                                                                      | All        |
-| **`/harden-pr lite`** after each tracer commit; **`/harden-pr full`** before PR merge                                                                  | All        |
-| **Retire plan on merge** — delete `docs/plans/<topic>.md` + lift to reference docs/roadmap in the **same PR** (never leave shipped plans as leftovers) | All        |
+| Convention                                                                                                                                                                                            | Applies to |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| **Moat A** — no `pass`/`fail` engine verdict; extra columns only                                                                                                                                      | All        |
+| **`reason` TEXT** — machine code + short clause where useful                                                                                                                                          | #3         |
+| **`evidence_json` TEXT** — bounded JSON array (≤3 hops)                                                                                                                                               | shipped #1 |
+| **`confidence` / `coverage_source` / `attribution`** — recipe-specific enums                                                                                                                          | #3, #4     |
+| **Golden update per slice** — `fixtures/golden/minimal/*.json` + `scenarios.json`                                                                                                                     | All        |
+| **`/harden-pr lite`** after each tracer commit; **`/harden-pr full`** before PR merge                                                                                                                 | All        |
+| **Retire plan on merge** — delete `docs/plans/<topic>.md` + lift to reference docs/roadmap in the **same PR** (never leave shipped plans as leftovers)                                                | All        |
+| **No deferring complements** — agent surfaces (rule/skill/MCP), glossary, golden/script tests, and plan acceptance items ship **in the same PR** unless explicitly listed under plan **Out of scope** | All        |
 
 **Cross-plan synergy:** shipped evidence `reason` complements #4 `attribution` on audit `added` rows. CRAP `coverage_source` (#175) ships before #3 so deletion-confidence can narrow rows with coverage semantics.
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -87,7 +87,7 @@ Long-running MCP / HTTP sessions dominate agent workflows; one-shot CLI keeps th
 Predicate-as-API only — enrich row shape and audit deltas; no standalone pass/fail verdict primitive ([Moat A](./roadmap.md#moats-load-bearing)).
 
 - [ ] **Audit delta attribution** — on `audit --base <ref>` (and matching MCP/HTTP audit), tag each `added` row with **`attribution: introduced | inherited`** via stable finding keys (`requiredColumns` → deterministic key) diffed against the sha-keyed audit-cache index at the merge base. Per-delta `summary` counts (`added_introduced`, `added_inherited`) optional when `summary: true`. Reuses shipped `audit-worktree` / `git archive` cache — no new verdict primitive ([Moat A](./roadmap.md#moats-load-bearing)). Complements deferred **`codemap audit` verdict + thresholds** (consumer filters `introduced` via `jq`). Plan: [`plans/audit-delta-attribution.md`](./plans/audit-delta-attribution.md). Effort: M.
-- [x] **Evidence chains on recipe rows** — v1 shipped on `boundary-violations`, `deprecated-symbols`, `unimported-exports` (`reason` + `evidence_json`; SQL-only). Contract: [golden-queries.md § Evidence columns](./golden-queries.md#evidence-columns-high-judgment-recipes). v2 optional: `unresolved_import_blind_spot` on `unimported-exports`; audit `added` attribution merge ([Moat A](./roadmap.md#moats-load-bearing)).
+- [x] **Evidence chains on recipe rows** — shipped on `boundary-violations`, `deprecated-symbols`, `unimported-exports` (`reason` + `evidence_json`; includes `reexport_chain_possible` and `unresolved_import_blind_spot`). Contract: [golden-queries.md § Evidence columns](./golden-queries.md#evidence-columns-high-judgment-recipes). v2 optional: audit `added` attribution merge ([Moat A](./roadmap.md#moats-load-bearing)).
 - [ ] **Tiered lookup fast paths** — `show` / exact-name recipe paths hit covering indexes first; document latency expectations in MCP tool descriptions. FTS and broad scans remain explicit fallbacks. Effort: S–M.
 - [x] **Graph-estimated CRAP recipe** — bundled `high-crap-score`: CRAP = `CC² × (1 - coverage/100)³ + CC` using `symbols.complexity`; **measured** `coverage` when ingested, else **graph-estimated** tiers (85% / 40% / 0% from test-file reachability over `dependencies` / `calls` / `test_suites`). Rows expose `coverage_source: measured | estimated`. Contract: [golden-queries.md § Coverage columns](./golden-queries.md#coverage-columns-crap--enrichment-recipes). Complements `high-complexity-untested` when no coverage file exists.
 - [ ] **Coverage-confirmed dead recipe** — bundled `coverage-confirmed-dead`: JOIN static dead-code predicate (uncalled exports, suppression-aware) with ingested `coverage` — rows carry `confidence: high` when callers = 0 and `coverage_pct = 0`, `medium` when coverage not ingested. Predicate columns only, no verdict primitive ([Moat A](./roadmap.md#moats-load-bearing)). Plan: [`plans/coverage-deletion-confidence.md`](./plans/coverage-deletion-confidence.md). Effort: L–M.
diff --git a/fixtures/golden/minimal/files-count.json b/fixtures/golden/minimal/files-count.json
@@ -1,5 +1,5 @@
 [
   {
-    "n": 42
+    "n": 43
   }
 ]
diff --git a/fixtures/golden/minimal/files-hashes.json b/fixtures/golden/minimal/files-hashes.json
@@ -149,6 +149,12 @@
     "language": "ts",
     "line_count": 4
   },
+  {
+    "path": "src/lib/alias-blind-spot.ts",
+    "content_hash": "34f2847180126455a500387ae3b2f49f67cc4e13290cc677c3e148827a6564ff",
+    "language": "ts",
+    "line_count": 6
+  },
   {
     "path": "src/lib/cache.ts",
     "content_hash": "964f6d3ddb8a7782b1273a38ed0bbde8cd886eb672c1f20466f0aa88ff49205f",
diff --git a/fixtures/golden/minimal/index-summary.json b/fixtures/golden/minimal/index-summary.json
@@ -1,8 +1,8 @@
 [
   {
-    "files": 42,
+    "files": 43,
     "symbols": 106,
-    "imports": 25,
+    "imports": 26,
     "components": 5,
     "dependencies": 23
   }
diff --git a/fixtures/golden/minimal/index-table-stats.json b/fixtures/golden/minimal/index-table-stats.json
@@ -1,8 +1,8 @@
 [
   {
-    "files": 42,
+    "files": 43,
     "symbols": 106,
-    "imports": 25,
+    "imports": 26,
     "exports": 62,
     "components": 5,
     "dependencies": 23,
@@ -13,17 +13,17 @@
     "css_vars": 2,
     "css_classes": 2,
     "css_keyframes": 1,
-    "scopes": 107,
-    "ref_count": 317,
-    "bindings": 274,
-    "import_specifiers": 30,
+    "scopes": 108,
+    "ref_count": 319,
+    "bindings": 276,
+    "import_specifiers": 31,
     "function_params": 18,
     "runtime_markers": 6,
     "test_suites": 7,
     "re_export_chains": 4,
     "module_cycles": 2,
     "dynamic_imports": 1,
-    "file_metrics": 34,
+    "file_metrics": 35,
     "unresolved_calls": 1,
     "jsx_elements": 10,
     "async_calls": 1,
diff --git a/fixtures/golden/minimal/source-fts-row-count.json b/fixtures/golden/minimal/source-fts-row-count.json
@@ -1,5 +1,5 @@
 [
   {
-    "n": 42
+    "n": 43
   }
 ]
diff --git a/fixtures/golden/minimal/unimported-exports.json b/fixtures/golden/minimal/unimported-exports.json
@@ -212,8 +212,8 @@
     "file_path": "src/orphan.ts",
     "is_default": 0,
     "re_export_source": null,
-    "reason": "no_direct_import",
-    "evidence_json": "[]"
+    "reason": "unresolved_import_blind_spot",
+    "evidence_json": "[{\"kind\":\"unresolved_import\",\"file_path\":\"src/lib/alias-blind-spot.ts\",\"source\":\"@codemap-fixture/unresolved-orphan\",\"specifier\":\"orphanHelper\"}]"
   },
   {
     "name": "ImportedMammal",
diff --git a/fixtures/minimal/src/lib/alias-blind-spot.ts b/fixtures/minimal/src/lib/alias-blind-spot.ts
@@ -0,0 +1,5 @@
+// Unresolved path alias — resolver leaves `imports.resolved_path IS NULL`.
+// Exercises `unimported-exports` `reason=unresolved_import_blind_spot` on `orphanHelper`.
+import { orphanHelper } from "@codemap-fixture/unresolved-orphan";
+
+void orphanHelper;
diff --git a/templates/agent-content/mcp-instructions.md b/templates/agent-content/mcp-instructions.md
diff --git a/templates/agent-content/rule/00-full.md b/templates/agent-content/rule/00-full.md
diff --git a/templates/recipes/unimported-exports.md b/templates/recipes/unimported-exports.md
diff --git a/templates/recipes/unimported-exports.sql b/templates/recipes/unimported-exports.sql

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`[`
`2`	`2`	`{`
`3`		`- "n": 42`
	`3`	`+ "n": 43`
`4`	`4`	`}`
`5`	`5`	`]`
Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,8 @@`
`1`	`1`	`[`
`2`	`2`	`{`
`3`		`- "files": 42,`
	`3`	`+ "files": 43,`
`4`	`4`	`"symbols": 106,`
`5`		`- "imports": 25,`
	`5`	`+ "imports": 26,`
`6`	`6`	`"components": 5,`
`7`	`7`	`"dependencies": 23`
`8`	`8`	`}`