# Scripts Directory Cleanup

Consolidate `scripts/` layout so capability boundaries match the architecture
rules in `docs/ARCHITECTURE.md`: compose through public surfaces, keep root
entrypoints thin, and use business-named capability directories.

## Traceability

- Spec ID: 2026-07-20-scripts-directory-cleanup
- Status: Implemented

## Intent

A structure review of `scripts/` found rule violations that grow maintenance
cost:

1. Ten files across `agent-customize`, `agent-lint`, and
   `coding-agent-practices` import `session-analysis` private helpers
   (`fs.mjs`, `paths.mjs`, `cli.mjs`) directly, and
   `harness-analysis/task-loop-source.mjs` imports six more deep
   `session-analysis` modules.
2. Root `scripts/session-analysis.mjs` owns the real CLI and `SessionAnalyzer`
   while `scripts/session-analysis/` modules import the root file back —
   a reverse-layering cycle.
3. `scripts/findings-recommend.mjs` + `.json` and `scripts/doc-link-graph.mjs`
   are loose root files consumed by multiple capabilities, against the
   `scripts/<capability>/` convention.
4. `scripts/package/` and `scripts/packaging/` are near-identical names with
   different owners (npm bundle/verify vs host-plugin assembly).
5. `scripts/coding-agent-practices/checkup.mjs` is a re-export shim over
   `checkup/cli.mjs` with no external import consumers.

## Acceptance Scenarios

- AC-1: `scripts/session-analysis/index.mjs` is the only import path other
  capabilities use for session-analysis helpers; no file outside
  `scripts/session-analysis/` imports `session-analysis/<private>.mjs`
  modules directly.
- AC-2: `scripts/session-analysis.mjs` stays a thin compatibility shim
  (re-export + CLI dispatch) so documented `node scripts/session-analysis.mjs`
  commands keep working; the class/dispatch logic lives in
  `scripts/session-analysis/analyzer.mjs` and no module inside
  `scripts/session-analysis/` imports the root file.
- AC-3: `findings-recommend` moves to `scripts/findings-recommend/`
  (`index.mjs` + `findings-recommend.json`); `agent-lint`, `review-trigger`,
  and tests import the new path; behavior is unchanged.
- AC-4: `doc-link-graph` moves to `scripts/doc-link-graph/cli.mjs`;
  `AGENTS.md` and `test/doc-link-graph.test.mjs` reference the new path and
  the generated `docs/harness-doc-links.mmd` stays fresh.
- AC-5: `scripts/package/` is renamed to `scripts/npm-package/`;
  `package.json` scripts, tests, and directory-ownership docs reference the
  new name; `npm run pack:verify` passes.
- AC-6: `scripts/coding-agent-practices/checkup.mjs` is removed; the
  `harness checkup` registry entry dispatches to
  `coding-agent-practices/checkup/cli.mjs`, which owns its own CLI gate.
- AC-7: `npm test` passes with no behavioral output change from any CLI.

## Non-Goals

- No split or refactor of `scripts/harness-analysis/` internals (tracked as a
  future spec; it needs its own evidence review).
- No command renames, flag changes, or output-format changes.
- No changes to `hooks/`, `skills/`, or host plugin shells beyond path
  references.
- Historical `docs/specs/*.md` files keep their original command strings.

## Plan

1. Move root `session-analysis.mjs` logic into
   `scripts/session-analysis/analyzer.mjs`; keep the root file as shim.
2. Add `scripts/session-analysis/index.mjs` exporting the cross-capability
   surface: `parseArgs`, `parseBooleanFlag`, `pathExists`, `walkFiles`,
   `isDirectory`, `expandHome`, `normalizeWorkspace`, semantic-facet,
   episode-contract, observation-manifest, privacy-safe-text, session-ref,
   selection, selection-plan exports, `SessionAnalyzer`, `createAnalyzer`.
3. Rewrite external importers to use `session-analysis/index.mjs`.
4. Relocate `findings-recommend` and `doc-link-graph`; update importers,
   tests, and `AGENTS.md`.
5. Rename `scripts/package/` to `scripts/npm-package/`; update
   `package.json`, tests, `docs/community.md`,
   `docs/adrs/directory-structure.md`.
6. Remove the checkup shim and repoint the registry.

## Test / Review Evidence

- `npm run pack:verify` passed: npm pack and runtime zip entries include the renamed `scripts/npm-package/` and `scripts/findings-recommend/` paths.
- `NO_COLOR=1 node --test test/better-harness-cli.test.mjs test/doc-link-graph.test.mjs test/findings-recommend.test.mjs test/agent-lint.test.mjs test/plugin-manifests.test.mjs test/host-plugin-artifact.test.mjs` passed.
- `NO_COLOR=1 node --test test/session-analysis.test.mjs test/session-analysis-claude-facets.test.mjs test/coding-agent-practices-inventory.test.mjs test/harness-report-quality.test.mjs test/task-loop-repository-evidence.test.mjs` passed.
- `node scripts/better-harness.mjs --help`, `node scripts/session-analysis.mjs --help`, and `node scripts/better-harness.mjs harness checkup --help` passed.
- `npm test` currently reports 762 pass / 1 fail; the failing `test/legacy-product-names.test.mjs` reproduces on clean `HEAD` and is unrelated to this directory cleanup.