docs: capture planning decisions + session 1 handoff

Lock in the four open questions resolved during session 1: - Gateway recovery uses BetterAuth cookie (not nonce file or rescue flag) - Sub-package command surface scope is acceptable as-is for this mission - Telemetry upload ships in dry-run mode until mosaicstack.dev server exists - Top-level mosaic config command is required (added as CU-04-04) Also: - Mark CU-02-01/02/03 done; milestone cu-m02 complete - Mission progress 2/8, phase -> Execution - CU-03-01 compressed from spike to plan-only (design locked) - Added CU-04-04 mosaic config and CU-04-05 tests - Full handoff block in scratchpad: state, decisions, gotchas, suggested starting tasks for session 2 No code changes. Docs-only. Session 1 closes clean for handoff. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-04 23:53:08 -05:00
parent 6f15a84ccf
commit c7c5ad21d9
3 changed files with 103 additions and 32 deletions
--- a/docs/scratchpads/cli-unification-20260404.md
+++ b/docs/scratchpads/cli-unification-20260404.md
@@ -67,17 +67,86 @@ Current lean: option 2 (BetterAuth cookie) because it reuses existing auth and g
  - Remote disabled by default; opt-in requires explicit consent
  - `test`/`upload` ship with dry-run mode until the server endpoint is live

+### 2026-04-04 — Open-question decisions (session 1)
+
+Jason answered the four planning questions:
+
+1. **Recovery endpoint design (CU-03-01):** BetterAuth cookie. `mosaic gateway login` becomes the recovery entry point. The spike in CU-03-01 can be compressed — design is locked; task becomes implementation planning rather than evaluation.
+2. **Sub-package command surface (M5):** The current CU-05-01..08 scope is acceptable for this mission. Deeper command surfaces can be follow-up work.
+3. **Telemetry server:** Ship `mosaic telemetry upload` and `mosaic telemetry test` in dry-run-only mode until the mosaicstack.dev server endpoint is live. Capture intended payload shape and print/log instead of POSTing. Real upload path gets wired in as follow-up once the server is ready.
+4. **Top-level `mosaic config`:** Required. Add to M4 (CLI structure milestone) since it lives alongside help-shape work and uses the existing `packages/mosaic/src/config/config-service.ts` machinery. Separate concern from `mosaic gateway config` (which manages gateway .env + meta.json).
+
 ## Session Log

-| Session | Date       | Milestone                 | Tasks Done                     | Outcome                                                                                            |
-| ------- | ---------- | ------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------- |
-| 1       | 2026-04-04 | cu-m01 Kill legacy CLI    | CU-01-01                       | PR #398 merged to main as `c39433c3`. 48 files deleted, 6685 LOC removed. CI green (pipeline 702). |
-| 1       | 2026-04-04 | cu-m02 Archive + scaffold | CU-02-01, CU-02-02 (this file) | In progress — this PR.                                                                             |
+| Session | Date       | Milestone                 | Tasks Done                   | Outcome                                                                                            |
+| ------- | ---------- | ------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
+| 1       | 2026-04-04 | cu-m01 Kill legacy CLI    | CU-01-01                     | PR #398 merged to main as `c39433c3`. 48 files deleted, 6685 LOC removed. CI green (pipeline 702). |
+| 1       | 2026-04-04 | cu-m02 Archive + scaffold | CU-02-01, CU-02-02, CU-02-03 | PR #399 merged to main as `6f15a84c`. Mission manifest + TASKS.md + scratchpad live.               |
+| 1       | 2026-04-04 | Planning                  | 4 open questions resolved    | See decisions block above. Ready to start M3/M4/M5.                                                |

 ## Corrections / Course Changes

 _(append here as they happen)_

+## Handoff — end of Session 1 (2026-04-04)
+
+**Session 1 agent:** claude-opus-4-6[1m]
+**Reason for handoff:** context budget (~80% used after bootstrap + two PRs + decision capture). Main is clean, no in-flight branches, no dirty state.
+
+### What Session 2 should read first
+
+1. `docs/MISSION-MANIFEST.md` — phase, progress, milestone table
+2. `docs/TASKS.md` — task state, dependencies, agent assignments
+3. This scratchpad — decisions, bug analysis, open risks, gotchas
+4. `git log --oneline -5` — confirm #398 and #399 are on main
+
+### State of the world
+
+- **Main branch HEAD:** `6f15a84c docs: archive stale mission, scaffold CLI unification mission (#399)`
+- **Working tree:** clean (no uncommitted changes after this handoff PR merges)
+- **Open PRs:** none (both M1 and M2 PRs merged)
+- **Deleted branches:** `chore/remove-cli-package-duplicate`, `docs/mission-cli-unification` (both local + remote)
+- **Milestones done:** cu-m01, cu-m02 (2 / 8)
+- **Milestones unblocked for parallel start:** cu-m03, cu-m04, cu-m05 (everything except M5.CU-05-06 which waits on M3.CU-03-03 for gateway login)
+
+### Decisions locked (do not re-debate)
+
+1. `@mosaicstack/cli` is dead; `@mosaicstack/mosaic` is the sole CLI package
+2. Sub-package CLI pattern: each package exports `register<Name>Command(parent: Command)`, wired into `packages/mosaic/src/cli.ts` (copy the `registerQualityRails` pattern)
+3. Gateway recovery uses **BetterAuth cookie** — `mosaic gateway login` + `mosaic gateway config rotate-token` via authenticated `POST /api/admin/tokens`
+4. Telemetry: `mosaic telemetry` wraps `@mosaicstack/telemetry-client-js`; remote upload is dry-run only until the mosaicstack.dev server endpoint is live
+5. Top-level `mosaic config` command is required (separate from `mosaic gateway config`) — wraps `packages/mosaic/src/config/config-service.ts`; added as CU-04-04
+
+### Known gotchas for Session 2
+
+- **pr-create.sh eval bug:** `~/.config/mosaic/tools/git/pr-create.sh` line 158 uses `eval "$CMD"`. Backticks and `$()` in PR bodies get shell-evaluated. **Workaround:** strip backticks from PR bodies OR use `tea pr create --repo mosaicstack/mosaic-stack --login mosaicstack --title ... --description ... --head <branch>` directly. Captured in openbrain.
+- **ci-queue-wait.sh unknown state:** The wrapper reports `state=unknown` and returns immediately instead of waiting. Poll the PR pipeline manually with `~/.config/mosaic/tools/woodpecker/pipeline-list.sh` and grep for the PR branch.
+- **pr-merge.sh branch delete:** `-d` flag is accepted but warns "branch deletion may need to be done separately". Delete via the Gitea API: `curl -X DELETE -H "Authorization: token $TOKEN" "https://git.mosaicstack.dev/api/v1/repos/mosaicstack/mosaic-stack/branches/<url-encoded-branch>"`.
+- **Tea login not default:** `tea login list` shows `mosaicstack` with DEFAULT=false. Pass `--login mosaicstack` explicitly on every `tea` call.
+- **`.mosaic/orchestrator/session.lock`:** auto-rewritten on every session launch. Shows up as dirty working tree on branch switch. Safe to `git checkout` the file before branching.
+- **Dual install.ts files no longer exist:** M1 removed `packages/cli/src/commands/gateway/install.ts`. The canonical (and only) one is `packages/mosaic/src/commands/gateway/install.ts`. The "user exists, no token" bug (CU-03-06) is in this file around lines 388-394 (`bootstrapFirstUser`). The server-side gate is in `apps/gateway/src/admin/bootstrap.controller.ts` lines 28 and 35.
+
+### Suggested starting task for Session 2
+
+Pick based on what the user wants shipped first:
+
+- **Highest user-impact:** M3 — fixes the install bug that made the user "off the reservation" in the first place. Start with CU-03-01 (implementation plan, opus-tier, 4K) → CU-03-02 (server endpoint, sonnet).
+- **Quickest win:** M4.CU-04-01 — one-line `configureHelp({ sortSubcommands: true })`. 3K estimate. Good warm-up.
+- **User priority stated in session 1:** M5.CU-05-01 — `mosaic forge`. Larger scope (18K), but user flagged Forge specifically as part of "E2E install to functional, with Mosaic Forge working".
+
+Session 2 orchestrator should pick one, update TASKS.md status to `in-progress`, follow the standard cycle: plan → code → test → review → remediate → commit → push → PR → queue guard → merge. Mosaic hard gates apply.
+
+### Files added / modified in Session 1
+
+Session 1 touched only these files across PRs #398 and #399 plus this handoff PR:
+
+- Deleted: `packages/cli/` (entire directory, 48 files)
+- Archived: `docs/archive/missions/harness-20260321/MISSION-MANIFEST.md`, `docs/archive/missions/harness-20260321/PRD.md`, `docs/archive/missions/storage-abstraction/TASKS.md`
+- Modified: `pnpm-workspace.yaml`, `tools/install.sh`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `docs/guides/user-guide.md`, `packages/mosaic/framework/defaults/README.md`
+- Created: `docs/MISSION-MANIFEST.md`, `docs/TASKS.md`, `docs/scratchpads/cli-unification-20260404.md` (this file)
+
+No code changes to `apps/`, `packages/mosaic/`, or any other runtime package. Session 2 starts fresh on the runtime code.
+
 ## Open Risks

 - **Telemetry server not live:** CU-06-03 (`mosaic telemetry upload`) may need a dry-run stub until the server endpoint exists on mosaicstack.dev. Not blocking for this mission, but ships with reduced validation until then.