Session-analysis shim dedupe and public-surface import cleanup

Traceability

• Spec ID: session-analysis-shim-dedupe
• Status: Implemented

Intent

scripts/session-analysis.mjs is documented as a thin compatibility shim in docs/adrs/directory-structure.md, but today it carries a full second copy of the SessionAnalyzer base class, the eight-platform loadPlatform() dispatch, createAnalyzer(), and a main() that has already drifted from the copy in scripts/session-analysis/analyzer.mjs (different help routing and a timestampMillis edge-case divergence). Platform adapters import the base class from the root shim while scripts/session-analysis/index.mjs exports the analyzer.mjs copy, so the two class identities can silently fork and every new platform must be registered twice.

Separately, several capabilities import session-analysis capability-private modules (fs.mjs, paths.mjs, cli.mjs, semantic-facets.mjs) instead of the public index.mjs surface, violating the compose-through-public-surfaces rule in docs/ARCHITECTURE.md.

This change makes analyzer.mjs the single owner of the base class, platform registry, and CLI main(), reduces the root file to the thin shim the ADR already describes, and routes all cross-capability imports through scripts/session-analysis/index.mjs.

Acceptance Scenarios

• AC-1: scripts/session-analysis.mjs contains no class, dispatch, or help logic; it only re-exports from scripts/session-analysis/analyzer.mjs and keeps the direct-CLI entry guard. node scripts/session-analysis.mjs --help output stays byte-identical to test/fixtures/scripts-refactor-contract/session-help.txt.
• AC-2: Exactly one SessionAnalyzer class and one loadPlatform() exist under scripts/, both in analyzer.mjs. loadPlatform() resolves platforms through a data registry (platform -> module specifier + analyzer export) instead of an if-else chain, and the unsupported-platform error message is unchanged.
• AC-3: createAnalyzer imported from scripts/session-analysis.mjs and from scripts/session-analysis/index.mjs is the same function, and platform adapters extend the same SessionAnalyzer identity exported by both surfaces. The public main(["help"]) alias continues to return the exported SESSION_ANALYSIS_HELP contract (covered by test/session-analysis-providers.test.mjs).
• AC-4: No module outside scripts/session-analysis/ imports scripts/session-analysis/<private>.mjs directly; external consumers use scripts/session-analysis/index.mjs (or the grandfathered root shim). The public surface additionally exports pathStat, readJson, projectSemanticFacets, validateSemanticFacets, and the current frozen session-population binding helpers to cover existing cross-capability usage.
• AC-5: Duplicate local readJson helpers in scripts/session-analysis/platforms/qoder.mjs and scripts/session-analysis/platforms/cursor.mjs are replaced by a shared readJson in scripts/session-analysis/fs.mjs.
• AC-6: Frozen CLI contracts stay green: npm test passes, including test/scripts-refactor-contract.test.mjs (fixture and sha256-frozen outputs), test/support-declarations.test.mjs, and test/session-analysis-claude-facets.test.mjs.

Non-goals

• No global scripts/lib/ or scripts/core/; the directory-structure ADR forbids generic umbrellas, and capability-scoped helpers stay in place.
• No rewrite of bespoke per-capability parseArgs implementations (cloc, doc-link-graph, validate-canvas, packaging, ...). They are capability-owned CLI contracts with differing unknown-argument semantics; converging them is behavior-changing and out of scope.
• No change to which commands the root better-harness registry exposes, no new CLI options, and no change to any frozen stdout/stderr contract.
• No migration of existing createAnalyzer imports off the grandfathered root shim; the ADR explicitly allows existing compatibility wiring to stay.
• No splitting of oversized files (task-loop-report.mjs, platform adapters); tracked separately.

Plan and Tasks

1. scripts/session-analysis/analyzer.mjs (single owner)
   • Replace its drifted main() with the fixture-frozen behavior currently living in the root file (per-command help sections for facts, show/events, and claude-facets), while preserving the public main(["help"]) alias and the existing dependencies injection seam (stdout, loadPlatform).
   • Replace the if-else loadPlatform() with a frozen PLATFORM_MODULES registry map and derive the supported-platform error message from its keys so the message stays identical.
   • Keep SESSION_ANALYSIS_HELP (frozen by test/support-declarations.test.mjs and rendered by the root CLI facade) unchanged.
2. scripts/session-analysis.mjs (thin shim)
   • Reduce to shebang, AI-facing usage comment, re-exports of SessionAnalyzer, createAnalyzer, main, SESSION_ANALYSIS_HELP, and the direct-CLI guard that calls main() with the existing error channel.
3. Capability-internal imports
   • Point the eight scripts/session-analysis/platforms/*.mjs adapters plus usage-summary.mjs and selection-profile.mjs at analyzer.mjs directly, removing the static import cycle through the root shim.
   • Add readJson to scripts/session-analysis/fs.mjs; delete the local copies in platforms/qoder.mjs and platforms/cursor.mjs.
4. Public surface and cross-capability consumers
   • Extend scripts/session-analysis/index.mjs with pathStat, readJson, projectSemanticFacets, validateSemanticFacets, and any current session-population helpers consumed by Harness analysis.
   • Rewrite private imports to scripts/session-analysis/index.mjs in: coding-agent-practices/checkup/\{sources,apply,cli\}.mjs, agent-customize/core/items.mjs, the eight agent-customize/providers/*.mjs, agent-lint/index.mjs, harness-analysis/evidence-bundle/cli.mjs, harness-analysis/report-source/source.mjs, and harness-analysis/task-loop-report.mjs.
   • Add a scripts-refactor contract test that rejects cross-capability imports of session-analysis private modules regardless of relative path depth.

Decision rationale: the root file's main() is the live contract (the CLI registry dispatches session-analysis.mjs, and the refactor-contract fixture freezes its output), so consolidation keeps the root behavior and discards the drifted analyzer.mjs copy rather than the reverse. The registry map follows the same pattern as better-harness-cli/registry.mjs for command metadata.

Test and Review Evidence

• npm test (full suite) — AC-1..AC-6.
• Targeted: node --test test/scripts-refactor-contract.test.mjs test/session-analysis.test.mjs test/session-analysis-providers.test.mjs test/support-declarations.test.mjs test/session-analysis-claude-facets.test.mjs.
• Structural gates:
  • grep -rn "class SessionAnalyzer" scripts returns one match.
  • grep -rn "loadPlatform" scripts shows a single definition site.
  • test/scripts-refactor-contract.test.mjs scans static and dynamic relative imports and rejects private session-analysis imports outside the capability.
• Risk: consumers that relied on the root shim's private drifted main() help routing; mitigated because the fixture freezes the exact bytes and the full suite runs frozen sha256 contracts. Cross-platform risk is low: import-path and data-structure changes touch no path or spawn logic, and the boundary test resolves specifiers with Node's platform-aware path utilities.