Scan root/scope is a hypothesis: detect topology, judge it, recover (assess where first-party code actually lives)

[maudlin]

Thesis

The scan root is a hypothesis, not a fact: checkup models the target as a single package rooted at the scan dir, but on inherited/low-quality codebases the root is often a thin orchestrator with the real work one level down. Two jobs: judge the topology (it is itself a finding) and recover (descend and actually measure), so a "looks clean" read can't come from having looked in the wrong place.

Status — most of this is DONE; the remainder is Phase 2b

• ✅ Phase 1 — judge the topology. classify_topology (lib/detect-topology.sh) distinguishes single-package / declared-workspace (healthy) / undeclared fan-out (smell) / orphan-root; surfaced as a macro-alarm on the headline; recorded in detection.json.topology. Tests in test/topology.test.sh. (Project-built checks report fail (not skip) when a manifest exists but the toolchain is absent #80)
• ✅ Phase 2a — recover the package-script checks. Clusters A (typecheck, tests, format, lint, type-aware lint, build) and B (npm-audit, dependency-freshness) iterate over the detected assessment roots, run in each sub-package, and emit per-package-labelled records via SLUG_NS (bin/checkup.sh:599, :1093; lib/run-tool.sh:197).
• ✅ Repro B — vendored/generated skew. Fixed by plan 0002 (feat(scc): route the scc-based engines through the first-party inventory (#109) #110/feat(scc): generated-marker exclusion — banner-shaped, opt-in (#114) #115/feat(scc): the honest banner — coverage-by-category + foreign-language concentration caveat (#117) #118): the scc-based detection/identity/stats now filter + re-aggregate one scc --by-file walk against the first-party inventory, so committed vendored bundles no longer misroute the primary stack.
• ✅ Blocker Absence/failure leaking as pass/fail: npm-audit (ENOLOCK), deps-freshness (empty), duplication (missing-script) #85 (absence/failure leaking as pass/fail) — closed.

Phase 2b — the remaining recovery (this issue)

The checks that still run once over the whole tree, so on an undeclared fan-out they are neither measured in-package nor labelled per package:

1. Package-script stragglers — circular-deps, unused-code, coverage are run_profiled (npm/script-based, exactly like clusters A/B) but currently run only at the root. On a fan-out the root has no such script → they skip, and the sub-packages' results are lost. Fold them into the recover pass (absorb circular-deps into cluster B; a new cluster C for unused + coverage). Low-risk — same proven pattern; byte-identical on a single-package repo. ← first increment.
2. The scc/lizard measurement arms — codebase-stats, complexity, and the duplication lizard arm measure the whole tree (sub-package code is counted, but mushed into one record and routed by whole-tree dominance). Make them per-package: filter the existing single scc --by-file walk to each assessment root's subtree (reuse, don't re-walk), and route the complexity engine per package. Surface labelled (backend: 12 hotspots · frontend: clean). The harder half (per-package engine routing) — second increment.

Guardrails (unchanged)

• Honesty survives recovery — a child that won't resolve is skip with a precise reason, never green-by-default (Absence/failure leaking as pass/fail: npm-audit (ENOLOCK), deps-freshness (empty), duplication (missing-script) #85, landed).
• Don't cry wolf on declared workspaces / single-package repos — byte-identical, no false alarm (the acceptance gate).
• Bounded + deterministic — shallow, lockfile-anchored, prune vendored, cap the fan-out (CHECKUP_MAX_ASSESSMENT_ROOTS).

Done when

• circular-deps / unused / coverage recover per sub-package, labelled (increment 1).
• complexity / duplication / codebase-stats measured + labelled per sub-package off the single scc walk (increment 2).
• Single-package + declared-workspace repos unchanged (byte-identical).

Refs #7, #75; supersedes the original Repro B (now fixed).

[maudlin]

Phase 1 (detect + judge) shipped in #87 (commit 0dd51e3): lib/detect-topology.sh, detection.json topology block (schemaVersion 1.4) with assessmentRoots, the headline macro-alarm + coverage-line signal, and test/topology.test.sh. Verified on the fan-out repro.

Reopening — Phase 2 (recover) remains: run the project-built checks once per assessmentRoot (subshell cwd + slug namespace), aggregated/labelled per package; re-prefix child-relative finding paths to keep the by-file/focus join intact; the #85 honesty floor is already in so a child that won't resolve skips rather than green-by-defaults. See the Plan's §1/§7 traps (cwd-relative artifact paths, slug-as-filename, MAX_SCORE accumulation).

(Auto-closed by a "close #78" keyword match in #87's body despite the negation — Phase 1 was never meant to close this.)

[maudlin]

Phase 2 (recover) shipped in #88 (commit dd36e91): the project-built checks now run per assessment root — the dependency-health (npm-audit, deps-freshness) and correctness/lint (typecheck, unit-tests, code-quality, type-aware-lint, build) clusters, namespaced per package with finding paths re-prefixed for the by-file/focus join. Verified on the fan-out repro: per-package CVEs (backend/frontend) now surface as headline alarms instead of a root false-pass.

Reopening — Phase 2b remains: per-package complexity / duplication / coverage. These are engine-routed / artifact-based / whole-tree (each needs its own engine re-routing inside the child, e.g. eslint_flat_config_root "$child", plus per-child artifact paths), so they stay root-scoped for now. On the repro this is the gap between "we measured deps + correctness per package" and "we also measured complexity hotspots per package" (backend/frontend each have a flat ESLint config, so 2b would light up AST complexity).

(Auto-closed again by a "close #78" keyword match in #88's body — the negation doesn't stop GitHub's matcher. Phase 2 was never meant to close the umbrella.)