Split CLI into behavior-owned modules and close out cycle 0007

docs/design/0007-cli-module-split/cli-module-split.md

@@ -0,0 +1,141 @@
+# CLI Module Split
+
+Source backlog item: `docs/method/backlog/asap/PROCESS_cli-module-split.md`
+Legend: PROCESS
+
+## Sponsors
+
+- Human: I can inspect the CLI and find command parsing, workspace
+  mutations, drift logic, and file-collection behavior in separate,
+  named modules instead of spelunking a 1,000-line monolith.
+- Agent: I can change one CLI behavior with a narrow edit scope because
+  the code is split by owned behavior, not piled into a single entry
+  file or dissolved into vague utility soup.
+
+## Hill
+
+METHOD keeps the current CLI command surface and behavior, but
+reorganizes the implementation so `src/cli.ts` becomes a thin entry
+point and runtime-owned modules carry argument parsing/help, workspace
+operations, and drift detection in separate homes while workspace-local
+document scaffolding stays with the workspace module unless it becomes
+independently meaningful.
+
+## Playback Questions
+
+### Human
+
+- [ ] Can I open the CLI code and identify where argument parsing ends
+      and workspace behavior begins without reading the whole command
+      stack top to bottom?
+- [ ] If I need to review or change only drift behavior, can I find that
+      logic in one small module instead of tracing through unrelated
+      `init`, `pull`, `close`, and `status` code?
+
+### Agent
+
+- [ ] Does `src/cli.ts` stay a thin entry point that wires command
+      parsing and execution together rather than owning most of the
+      runtime behavior itself?
+- [ ] Are the resulting modules named by owned behavior, with stable
+      tests proving that the CLI still preserves its existing contract?
+
+## Accessibility and Assistive Reading
+
+- Linear truth / reduced-complexity posture: the module layout should be
+  readable in a terminal or plain editor. File names should describe the
+  behavior they own so a reviewer can follow the CLI flow without IDE
+  indexing.
+- Non-visual or alternate-reading expectations: this cycle should reduce
+  navigation burden for screen-reader users, terminal-only operators,
+  and agents by shortening files and making the seams more explicit in
+  committed paths and test names.
+
+## Localization and Directionality
+
+- Locale / wording / formatting assumptions: internal symbol and module
+  names may remain English. No localization work is part of this cycle.
+- Logical direction / layout assumptions: the split should improve code
+  navigation through textual structure, not left/right editor panes or
+  IDE-specific affordances.
+
+## Agent Inspectability and Explainability
+
+- What must be explicit and deterministic for agents: the module
+  boundaries and moved responsibilities must be committed in the repo.
+  A reviewer should be able to point to a concrete file for CLI entry,
+  arg parsing/help text, workspace operations, drift behavior, and the
+  workspace-local scaffolding those behaviors still depend on.
+- What must be attributable, evidenced, or governed: tests must prove
+  the CLI contract still holds after the split. This cycle should not
+  hide behavioral changes inside a refactor. If outputs or command
+  semantics change, that change needs an explicit test and design note.
+
+## Non-goals
+
+- [ ] Adding new CLI commands or changing the current command surface.
+- [ ] Introducing a large public library API for the internal modules.
+- [ ] Converting the repo away from TypeScript or rewriting the CLI in
+      plain JavaScript as part of this cycle.
+- [ ] Sneaking in drift-feature expansion such as near-miss hints,
+      witness packaging, or broader test discovery.
+- [ ] Splitting the file into generic `utils` buckets that weaken
+      ownership instead of clarifying it.
+
+## Decisions To Make
+
+- Which module boundaries are real enough to earn first-class files in
+  this cycle.
+  Final direction: split by owned behavior, not by syntactic category.
+  The first cut should likely separate:
+  - `src/cli.ts` as entry point plus exported `runCli`
+  - `src/cli-args.ts` for parse/help behavior
+  - `src/workspace.ts` for workspace mutation/query behavior
+  - `src/drift.ts` for playback-question extraction and drift matching
+  - `src/fs-helpers.ts` and/or `src/text-helpers.ts` only where a helper
+    is genuinely shared and still semantically coherent
+- Whether `Workspace` should remain the primary runtime object.
+  Current bias: yes. Keep a real runtime-backed workspace type, but make
+  it smaller by moving drift-only logic out of the class first.
+  Workspace-local document scaffolding and markdown traversal may remain
+  in `src/workspace.ts` during this cycle if they stay internal to
+  workspace behavior.
+- How far to take the split in one cycle.
+  Current bias: enough to remove the monolith risk now, not a full
+  architectural rewrite.
+
+## Backlog Context
+
+`src/cli.ts` is carrying too many concerns at once: command parsing,
+workspace logic, file discovery, markdown extraction, normalization,
+and the drift algorithm all live together. Split the CLI into smaller
+runtime-owned modules so the code shape matches the repo's own doctrine
+about traceability and single responsibility.
+
+Session context:
+
+- The `method drift` PR shipped a useful feature, but review surfaced a
+  real structural problem: the CLI entry point is becoming a monolith.
+- Current `src/cli.ts` is 1,056 lines and mixes:
+  - top-level command execution
+  - arg parsing and usage text
+  - workspace mutation/query behavior
+  - drift extraction and matching
+  - recursive file collection
+  - markdown parsing and text normalization helpers
+- The repo's newer system-style JavaScript doctrine pushes toward
+  runtime-owned modules with clear responsibilities. A successful split
+  should make the code more honest, not just more fragmented.
+
+What this surfaced:
+
+- `cli.ts` should become a thin entry point that preserves the exported
+  CLI contract.
+- `Workspace` is still probably the right runtime object, but it should
+  stop owning drift-only logic and helper grab-bags.
+- The split should be behavior-centered. Replacing one monolith with a
+  handful of ambiguous helper files would be a lateral move, not an
+  improvement.
+- Existing CLI tests give this cycle a strong safety rail: the refactor
+  can stay honest by preserving those contracts while tightening file
+  boundaries.

docs/method/backlog/cool-ideas/SYNTH_cycle-witness-command.md

@@ -0,0 +1,23 @@
+# Cycle Witness Command
+
+Explore a `method witness` command that can package the rerunnable
+proof for a cycle close: commands run, artifacts produced, playback
+answers, and file references.
+
+Session context:
+
+- External repos using METHOD are starting to want a cleaner way to
+  package what counted as the witness for a completed cycle.
+- The need is broader than any one repo's local tooling. If METHOD
+  thinks witness packaging is a real pattern, it belongs here instead
+  of being rediscovered downstream.
+
+What this surfaced:
+
+- A witness command could reduce ad hoc closeout work while staying
+  faithful to METHOD's requirement that done-claims be reproducible.
+- The command should package evidence, not invent it. It would point to
+  rerunnable proof rather than becoming a substitute for that proof.
+- This still feels like a cool idea, not core doctrine, until METHOD
+  has clearer boundaries around artifact history, closeout flow, and
+  any future API surface.

docs/method/backlog/inbox/PROCESS_release-shaping-and-user-migration-docs.md

@@ -0,0 +1,44 @@
+# Release shaping and user migration docs
+
+METHOD needs a clearer way to shape releases, not just cycles. Alongside
+`CHANGELOG.md`, the repo should have a structured, user-facing release
+surface that explains what is new in a release, why it matters, and how
+to migrate from previous versions when migration is required.
+
+Session context:
+
+- The current release doctrine is intentionally light: `release.md`
+  says releases happen when externally meaningful behavior changes and
+  points at `CHANGELOG.md` plus `README.md`.
+- That is enough for honesty, but it is not enough for user-facing
+  release communication. Changelogs are ledger-like. Users often need a
+  more guided document: what changed, what to look at first, what might
+  break, and what to do next.
+- The gap is especially visible for infrastructure repositories where a
+  release may change doctrine, CLI behavior, file layout, or expected
+  workflow. A terse changelog entry is not always the right surface for
+  helping a user adopt that release.
+
+Questions this should answer:
+
+- What makes a release “shaped” rather than just tagged and logged?
+- What artifact should accompany a real release besides
+  `CHANGELOG.md`?
+- Should METHOD define a user-facing release note format such as:
+  summary, what changed, why it matters, breaking changes,
+  migration/upgrade steps, and links to deeper docs?
+- When should a release include explicit migration guidance versus “no
+  migration required”?
+- Where should these artifacts live: `docs/releases/`, a generated
+  release page, versioned markdown files, or something else?
+- How should release shaping relate to cycle closeout and post-merge
+  ship sync?
+
+What this surfaced:
+
+- METHOD currently knows how to close cycles honestly, but not yet how
+  to present releases coherently to users.
+- `CHANGELOG.md` is necessary, but not always sufficient as the primary
+  user-facing release document.
+- A structured release note / migration surface could become part of the
+  release method without turning every cycle into release theater.

docs/method/retro/0007-cli-module-split/cli-module-split.md

@@ -0,0 +1,51 @@
+# CLI Module Split Retro
+
+Design: `docs/design/0007-cli-module-split/cli-module-split.md`
+Outcome: hill-met
+Drift check: yes
+
+## Summary
+
+This cycle split the CLI monolith into behavior-owned modules without
+changing the command surface. `src/cli.ts` is now a thin 97-line entry
+point that wires command execution together, while `src/cli-args.ts`,
+`src/workspace.ts`, `src/drift.ts`, and `src/errors.ts` carry the
+owned runtime behavior. This first cut moved argument parsing and
+drift-specific behavior into dedicated modules while leaving
+workspace-local document scaffolding inside `src/workspace.ts`. The
+existing CLI contract stayed intact:
+`npm test`, `npm run build`, and `npm run method -- status` all still
+pass after the split.
+
+## Playback Witness
+
+- [Witness Index](./witness/README.md)
+- [Playback Witness](./witness/playback.md)
+- [Verification Witness](./witness/verification.md)
+
+## Drift
+
+- None recorded.
+
+## New Debt
+
+- None recorded.
+
+## Cool Ideas
+
+- None recorded.
+
+## Backlog Maintenance
+
+- [x] Inbox processed during cycle closeout
+- [x] Priorities reviewed
+- [x] Dead work buried or merged
+- Moved `PROCESS_retro-conversational-closeout` from `inbox/` to
+  `cool-ideas/`.
+- Left `SYNTH_generated-signpost-provenance` as the sole `asap/` item.
+- Left `PROCESS_git-branch-workflow-policy`,
+  `PROCESS_library-api-surface`, and
+  `PROCESS_system-style-javascript-adoption` in `up-next/` for later
+  cycle planning.
+- Branch tip now also carries the later backlog capture
+  `PROCESS_release-shaping-and-user-migration-docs` in `inbox/`.

docs/method/retro/0007-cli-module-split/witness/README.md

@@ -0,0 +1,24 @@
+# Witness Index
+
+This cycle claims a structural refactor, not a new feature. The proof
+rests on committed module boundaries plus rerunnable commands that show
+the CLI contract still behaves the same after the split.
+
+## Artifacts
+
+- [playback.md](./playback.md)
+  Human and agent playback answers for the CLI-module-split cycle.
+- [verification.md](./verification.md)
+  Reproducible commands showing the new `src/` layout, the thinner
+  entry point, and the unchanged build/test/status truth surfaces.
+
+## Review Notes
+
+- The done-claim is carried by committed source files and rerunnable
+  commands, not by review prose.
+- This witness proves the split happened and that the current CLI
+  contract still holds. It does not claim a new public API or new CLI
+  behavior.
+- The refactor stays aligned with the repo's system-style JavaScript
+  direction by keeping a real `Workspace` runtime object instead of
+  flattening everything into utility functions.

docs/method/retro/0007-cli-module-split/witness/playback.md

@@ -0,0 +1,64 @@
+# Playback Witness
+
+Date: 2026-04-03
+
+This was a structural refactor cycle. The deliverable is a thinner CLI
+entry point and clearer behavior-owned modules, with the existing
+command surface preserved.
+
+## Human Playback
+
+### Can I open the CLI code and identify where argument parsing ends and workspace behavior begins without reading the whole command stack top to bottom?
+
+Yes.
+
+The boundaries are now visible from committed file names and grep-able
+exports:
+
+- `src/cli.ts` wires execution together
+- `src/cli-args.ts` owns parse/help behavior
+- `src/workspace.ts` owns workspace mutations and status rendering
+- `src/drift.ts` owns playback-question extraction and matching
+
+The human no longer has to scan a 1,000-line single file to answer
+basic ownership questions.
+
+### If I need to review or change only drift behavior, can I find that logic in one small module instead of tracing through unrelated `init`, `pull`, `close`, and `status` code?
+
+Yes.
+
+`src/drift.ts` now holds the drift-specific behavior directly, and
+`Workspace.detectDrift()` delegates to it. The refactor did not hide
+drift behind generic helpers or mixed command code.
+
+## Agent Playback
+
+### Does `src/cli.ts` stay a thin entry point that wires command parsing and execution together rather than owning most of the runtime behavior itself?
+
+Yes.
+
+`src/cli.ts` is now 97 lines and contains:
+
+- the exported `runCli`
+- the exported `main`
+- the entry-point bootstrap
+
+It no longer defines `Workspace`, drift extraction, or generic file
+collection behavior.
+
+### Are the resulting modules named by owned behavior, with stable tests proving that the CLI still preserves its existing contract?
+
+Yes.
+
+The module names describe owned behavior directly, and the existing CLI
+tests still pass after the split. Two added structural tests also prove
+that:
+
+- the behavior-owned files exist
+- `src/cli.ts` no longer contains the old monolith seams
+
+## Outcome
+
+The hill is met. The CLI is structurally clearer, the entry point is
+thin again, and the command behavior stayed stable under rerunnable
+test/build/status verification.