# Remaining Cleanup Refactor Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Finish the remaining organization cleanup called out after the v2 refactor assessment.

**Architecture:** Keep behavior unchanged and split by responsibility, not by framework. The current command APIs stay stable; new modules should expose small helpers used by the existing command entrypoints.

**Tech Stack:** TypeScript, Commander, Vitest, better-sqlite3, fast-glob.

---

## Scope

Must-fix:
- Split `src/commands/topics.ts` so read formatting, mutation workspace, and page rewrites are no longer buried in one file.
- Add lightweight regression coverage for the CLI command surface so future registration splits cannot silently drop commands or options.
- Organize `setup` and `hook` responsibilities on top of the current working-tree behavior without reverting existing local edits.

Out of scope:
- Changing CLI behavior, command names, option semantics, output text, or topic DAG rules.
- Introducing a GUI architecture framework into the CLI.
- Rewriting setup/hook behavior beyond extracting named helpers.

## Task 1: Topics Module Split

Files:
- Modify: `src/commands/topics.ts`
- Create: `src/commands/topics/read.ts`
- Create: `src/commands/topics/workspace.ts`
- Create: `src/commands/topics/page-rewrite.ts`

Steps:
1. Move `TopicsShowRecord`, `pagesDirectlyTagged`, `pagesForSubtree`, and `formatShow` into `topics/read.ts`.
2. Move `TopicsWorkspace`, `resolveTopicsRepo`, `openFreshTopicsWorkspace`, `closeWorkspace`, and `topicExists` into `topics/workspace.ts`.
3. Move `rewriteTopicOnPages` into `topics/page-rewrite.ts`.
4. Update imports in `topics.ts` and keep all exported command functions in `topics.ts`.
5. Run `npm test -- test/topics.test.ts test/tag.test.ts` and `npm run lint`.
6. Commit as `refactor(v2): split topics helpers`.

## Task 2: CLI Command Surface Regression Test

Files:
- Modify: `test/cli.test.ts`

Steps:
1. Add a test that instantiates `program` through `run()` with `--help` or imports the registration shape indirectly.
2. Verify the expected command names remain present: query commands, edit commands, wiki lifecycle commands, setup commands, and hook subcommands.
3. Verify representative options for renamed risk areas: `setup --yes`, `doctor --json`, `topics show --descendants`, `search --mentions`, `list --drop`.
4. Keep the test broad but not brittle to help text wording.
5. Run `npm test -- test/cli.test.ts` and `npm run lint`.
6. Commit as `test(v2): cover CLI command surface`.

## Task 3: Setup And Hook Responsibility Split

Files:
- Modify: `src/commands/setup.ts`
- Modify: `src/commands/hook.ts`
- Create supporting files under `src/commands/setup/` and/or `src/commands/hook/` only if the split clearly reduces the main file size.
- Modify tests only if imports need updating or coverage catches a refactor regression.

Steps:
1. Preserve the current working-tree behavior exactly, including stable hook copy, ephemeral install detection, ABI guard integration, and updated next steps.
2. Extract setup install-path detection and global install spawning into a setup helper module.
3. Extract setup next-step rendering/repo page counting into a setup helper module.
4. Extract hook script resolution/stable copy into a hook helper module if it reduces `hook.ts` without scattering schema logic.
5. Keep settings JSON classification and mutation together unless a cleaner boundary emerges.
6. Run `npm test -- test/setup.test.ts test/hook.test.ts test/init-helper.test.ts` and `npm run lint`.
7. Commit as `refactor(v2): split setup and hook helpers`.

## Final Verification

Run:
- `npm test`
- `npm run build`
- `npm run lint`

Then request one review pass over the new commits. Fix and commit any must-fix or should-fix findings before final handoff.
