From c7c5ad21d92ec3f949b474c4f792324a087df688 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Sat, 4 Apr 2026 23:53:08 -0500 Subject: [PATCH] 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) --- docs/MISSION-MANIFEST.md | 14 ++-- docs/TASKS.md | 44 +++++------ docs/scratchpads/cli-unification-20260404.md | 77 +++++++++++++++++++- 3 files changed, 103 insertions(+), 32 deletions(-) diff --git a/docs/MISSION-MANIFEST.md b/docs/MISSION-MANIFEST.md index 366b954..5b98a99 100644 --- a/docs/MISSION-MANIFEST.md +++ b/docs/MISSION-MANIFEST.md @@ -7,9 +7,9 @@ **ID:** cli-unification-20260404 **Statement:** Transform the Mosaic CLI from a partially-duplicated, manually-assembled experience into a single cohesive entry point that installs, configures, and controls the entire Mosaic system. Every Mosaic package gets first-class CLI surface. The first-run experience works end-to-end with no manual stitching. Gateway token recovery is possible without the web UI. Opt-in telemetry uses the published telemetry clients. -**Phase:** Planning -**Current Milestone:** — -**Progress:** 1 / 8 milestones +**Phase:** Execution +**Current Milestone:** cu-m03 / cu-m04 / cu-m05 (parallel-eligible) +**Progress:** 2 / 8 milestones **Status:** active **Last Updated:** 2026-04-04 @@ -29,7 +29,7 @@ | # | ID | Name | Status | Branch | Issue | Started | Completed | | --- | ------ | ------------------------------------------------------------------------ | ----------- | ---------------------------------- | ----- | ---------- | ---------- | | 1 | cu-m01 | Kill legacy @mosaicstack/cli package | done | chore/remove-cli-package-duplicate | #398 | 2026-04-04 | 2026-04-04 | -| 2 | cu-m02 | Archive stale mission state + scaffold new mission | in-progress | docs/mission-cli-unification | — | 2026-04-04 | — | +| 2 | cu-m02 | Archive stale mission state + scaffold new mission | done | docs/mission-cli-unification | #399 | 2026-04-04 | 2026-04-04 | | 3 | cu-m03 | Fix gateway bootstrap token recovery (server + CLI paths) | not-started | — | — | — | — | | 4 | cu-m04 | Alphabetize + group `mosaic --help` output | not-started | — | — | — | — | | 5 | cu-m05 | Sub-package CLI surface (auth/brain/forge/log/macp/memory/queue/storage) | not-started | — | — | — | — | @@ -61,9 +61,9 @@ ## Session History -| Session | Runtime | Started | Duration | Ended Reason | Last Task | -| ------- | --------------- | ---------- | --------- | ------------ | ---------------------------------------------------- | -| 1 | claude-opus-4-6 | 2026-04-04 | in-flight | — | cu-m01 merged (PR #398); cu-m02 scaffold in progress | +| Session | Runtime | Started | Duration | Ended Reason | Last Task | +| ------- | --------------- | ---------- | --------- | ------------ | ------------------------------------------------------------ | +| 1 | claude-opus-4-6 | 2026-04-04 | in-flight | — | cu-m01 + cu-m02 merged (#398, #399); open questions resolved | ## Scratchpad diff --git a/docs/TASKS.md b/docs/TASKS.md index 3074a9f..54542fc 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -13,34 +13,36 @@ | -------- | ------ | ----------------------------------------------------------------- | ----- | ----- | ---------------------------------- | ---------- | -------- | --------------------------- | | CU-01-01 | done | Delete packages/cli directory; update workspace + docs references | #398 | opus | chore/remove-cli-package-duplicate | — | 5K | Merged c39433c3. 6685 LOC−. | -## Milestone 2 — Archive stale mission + scaffold new mission (in-progress) +## Milestone 2 — Archive stale mission + scaffold new mission (done) -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ----------- | ------------------------------------------------------------------ | ----- | ----- | ---------------------------- | ---------- | -------- | --------------------------------- | -| CU-02-01 | in-progress | Move stale MISSION-MANIFEST / TASKS / PRD-Harness to docs/archive/ | — | opus | docs/mission-cli-unification | CU-01-01 | 3K | Harness + storage missions done. | -| CU-02-02 | in-progress | Scaffold new MISSION-MANIFEST.md, TASKS.md, scratchpad | — | opus | docs/mission-cli-unification | CU-02-01 | 5K | This file + manifest + scratchpad | -| CU-02-03 | not-started | PR review, merge, branch cleanup | — | opus | docs/mission-cli-unification | CU-02-02 | 2K | Must be green CI + merged | +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | ------------------------------------------------------------------ | ----- | ----- | ---------------------------- | ---------- | -------- | --------------------------------- | +| CU-02-01 | done | Move stale MISSION-MANIFEST / TASKS / PRD-Harness to docs/archive/ | #399 | opus | docs/mission-cli-unification | CU-01-01 | 3K | Harness + storage missions done. | +| CU-02-02 | done | Scaffold new MISSION-MANIFEST.md, TASKS.md, scratchpad | #399 | opus | docs/mission-cli-unification | CU-02-01 | 5K | This file + manifest + scratchpad | +| CU-02-03 | done | PR review, merge, branch cleanup | #399 | opus | docs/mission-cli-unification | CU-02-02 | 2K | Merged as 6f15a84c | ## Milestone 3 — Gateway bootstrap token recovery -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ----------- | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- | -| CU-03-01 | not-started | Design recovery flow (filesystem-signed nonce vs authenticated cookie vs rescue CLI flag) | — | opus | — | CU-02-03 | 8K | Spike | -| CU-03-02 | not-started | Server: add recovery/rotate endpoint on apps/gateway/src/admin (gated by design from CU-03-01) | — | sonnet | — | CU-03-01 | 12K | | -| CU-03-03 | not-started | CLI: `mosaic gateway login` — interactive BetterAuth sign-in, persist session | — | sonnet | — | CU-03-02 | 10K | | -| CU-03-04 | not-started | CLI: `mosaic gateway config rotate-token` — mint new admin token via authenticated API | — | sonnet | — | CU-03-03 | 8K | | -| CU-03-05 | not-started | CLI: `mosaic gateway config recover-token` — execute the recovery flow from CU-03-01 | — | sonnet | — | CU-03-03 | 10K | | -| CU-03-06 | not-started | Install UX: fix the "user exists, no token" dead-end in runInstall bootstrapFirstUser path | — | sonnet | — | CU-03-05 | 8K | | -| CU-03-07 | not-started | Tests: integration tests for each recovery path (happy + error) | — | sonnet | — | CU-03-06 | 10K | | -| CU-03-08 | not-started | Code review + remediation | — | haiku | — | CU-03-07 | 4K | | +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ----------- | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----------------------------- | +| CU-03-01 | not-started | Implementation plan for BetterAuth-cookie recovery flow (decision locked 2026-04-04) | — | opus | — | CU-02-03 | 4K | Design locked; plan-only task | +| CU-03-02 | not-started | Server: add recovery/rotate endpoint on apps/gateway/src/admin (gated by design from CU-03-01) | — | sonnet | — | CU-03-01 | 12K | | +| CU-03-03 | not-started | CLI: `mosaic gateway login` — interactive BetterAuth sign-in, persist session | — | sonnet | — | CU-03-02 | 10K | | +| CU-03-04 | not-started | CLI: `mosaic gateway config rotate-token` — mint new admin token via authenticated API | — | sonnet | — | CU-03-03 | 8K | | +| CU-03-05 | not-started | CLI: `mosaic gateway config recover-token` — execute the recovery flow from CU-03-01 | — | sonnet | — | CU-03-03 | 10K | | +| CU-03-06 | not-started | Install UX: fix the "user exists, no token" dead-end in runInstall bootstrapFirstUser path | — | sonnet | — | CU-03-05 | 8K | | +| CU-03-07 | not-started | Tests: integration tests for each recovery path (happy + error) | — | sonnet | — | CU-03-06 | 10K | | +| CU-03-08 | not-started | Code review + remediation | — | haiku | — | CU-03-07 | 4K | | ## Milestone 4 — `mosaic --help` alphabetize + grouping -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ----------- | ----------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- | -| CU-04-01 | not-started | Enable `configureHelp({ sortSubcommands: true })` on root program and each subgroup | — | sonnet | — | CU-02-03 | 3K | | -| CU-04-02 | not-started | Group commands into sections (Runtime, Gateway, Framework, Platform) in help output | — | sonnet | — | CU-04-01 | 5K | | -| CU-04-03 | not-started | Verify help snapshots render readably; update any docs with stale output | — | haiku | — | CU-04-02 | 3K | | +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------------------- | +| CU-04-01 | not-started | Enable `configureHelp({ sortSubcommands: true })` on root program and each subgroup | — | sonnet | — | CU-02-03 | 3K | | +| CU-04-02 | not-started | Group commands into sections (Runtime, Gateway, Framework, Platform) in help output | — | sonnet | — | CU-04-01 | 5K | | +| CU-04-03 | not-started | Verify help snapshots render readably; update any docs with stale output | — | haiku | — | CU-04-02 | 3K | | +| CU-04-04 | not-started | Top-level `mosaic config` command — `show`, `get `, `set `, `edit`, `path` — wraps packages/mosaic/src/config/config-service.ts (framework/agent config; distinct from `mosaic gateway config`) | — | sonnet | — | CU-02-03 | 10K | New scope (decision 2026-04-04) | +| CU-04-05 | not-started | Tests + code review for CU-04-04 | — | haiku | — | CU-04-04 | 4K | | ## Milestone 5 — Sub-package CLI surface diff --git a/docs/scratchpads/cli-unification-20260404.md b/docs/scratchpads/cli-unification-20260404.md index dd618f9..71fd0c2 100644 --- 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 `registerCommand(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 ` 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/"`. +- **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.