speedwave-write-plan

# Write Implementation Plan

`$ARGUMENTS` contains the task description. If `$ARGUMENTS` is empty, use AskUserQuestion to ask what the user wants to plan.

## Step 0 — Enter Plan Mode

If you are not already in plan mode, call `EnterPlanMode` immediately. All research and plan writing happens in plan mode. Do not write any code — this skill produces a plan, not an implementation.

## Step 1 — Follow the Planning Prompt Below

Everything below this line is the planning prompt. Follow it exactly.

---

You are writing an implementation plan for the Speedwave project. This plan will be reviewed by a hostile reviewer who checks 12 verification axes. Your job is to write a plan that passes ALL of them on the first attempt.

Do not write a plan based on assumptions. Read the code first, understand the architecture, then plan.

## Before You Write Anything

The orchestrator has already injected `CLAUDE.md` and every file from `.claude/rules/` into your system prompt under the heading "AUTHORITATIVE PROJECT CONTEXT". Treat that block as already read — do not waste tool calls re-reading those files. Your plan MUST honour every invariant from that block; the reviewer will explicitly score plan-vs-rules compliance per file.

The remaining context still requires tool reads:

1. **Read `docs/architecture/security.md`** — non-negotiable security model, threat model questions, executor sandbox, SSRF protection

2. **Read `docs/architecture/containers.md`** — container topology, compose template, resource limits

3. **Read `docs/architecture/platform-matrix.md`** — macOS and Windows differences

4. **Read `docs/contributing/testing.md`** — test strategy, coverage thresholds, test patterns

5. **Read `RELEASING.md`** — release flow, squash merge rules

6. **Read relevant ADRs** from `docs/adr/` — check ADR `README.md` index for overlapping topics. Pay special attention to ADR-030 (bundle reconcile), ADR-031 (data dir isolation), ADR-040 / ADR-041 (local LLM providers + SSRF policy), and any ADRs related to updates or migration.

7. **Read the actual source code** you plan to modify — the files themselves, their callers, their tests, adjacent modules. Map the dependency graph BEFORE planning changes.

8. **Read the update/reconcile flow** — `updater.rs`, `update_commands.rs`, `bundle-manifest.json` handling, `bundle-state.json` phases, snapshot/rollback logic. Understand what happens when a user updates from version N to version N+1.

9. **Perform external verification NOW, not later.** If the task requires checking sibling repos (e.g. the `speedwave-plugins` sibling repository), existing files, CLI outputs, or any state outside the current code — run the check (`grep`, `gh search code`, `Read`) during planning and record the concrete result in the plan. Do NOT add a step like "verify that X is true" to Implementation Steps — a plan step must be an action the implementer takes, not a fact-check the planner skipped.

## The Task

<task>

$ARGUMENTS

</task>

## Plan Structure

Write the plan using the following structure. Every section is mandatory — a missing section = automatic review failure.

### 1. Context & Goal

- What problem does this solve? Why now?

- Link to GitHub issue if one exists.

- One sentence: what does "done" look like?

### 2. Architecture Analysis

Before proposing changes, demonstrate you understand the current state:

- Which files/modules are affected?

- What is the dependency graph of the affected code? (who calls what, who imports what)

- Which SSOT locations does this touch? (`speedwave-runtime`, `mcp-servers/shared/`, `compose.template.yml`, `build.rs` ↔ `bundle-build-context.sh`, `consts.rs`, `defaults.rs`)

- Which contract surfaces does this touch? (plugin contract table, Tauri ↔ Angular models, `ContainerRuntime` trait)

- Does this touch security boundaries? (token mounts, container hardening, sandbox, SSRF, auth gates)

- Does this affect the update/reconcile pipeline? (bundle manifest, bundle state phases, compose snapshots, image tags)

### 3. Platform Impact

For EVERY change, answer:

- Does this behave differently on macOS vs Windows?

- VM layer: does it need path translation? (Lima `/tmp/lima/` on macOS, WSL `\\wsl$\` on Windows)

- Does it affect mcp-os? (macOS = AppleScript / EventKit, Windows = WinRT / mapi-rs)

- Does it affect installer artifacts? (.dmg, .exe)

- Does this change add or modify a bundled macOS binary? If yes, follow the "Adding a new bundled binary" checklist in [`docs/contributing/release-signing.md`](../../../docs/contributing/release-signing.md#adding-a-new-bundled-binary) — it is the authoritative source for SIGN_TARGETS, entitlements plists, `Info.plist` TCC keys, and ADR-037 updates.

- Filesystem case sensitivity? (host: macOS APFS insensitive; container: ext4 sensitive)

If the change is platform-independent, state WHY it's platform-independent — don't just skip this section.

### 4. Implementation Steps

Numbered steps. For each step:

- **What:** concrete change (file path, function name, what changes)

- **Why:** why this step is needed (not just "implement feature X")

- **Dependencies:** what must be done before this step

- **Security check:** does this step relax any security principle? If yes — find a different approach or justify with ADR.

- **SSOT check:** is this the right place for this logic? (container logic → `speedwave-runtime`, MCP utilities → `mcp-servers/shared/`, container definitions → `compose.template.yml`)

- **Upgrade safety check:** does this step change persisted state, file formats, config schema, CLI output parsed by scripts, container image tags, or compose structure? If yes — describe the upgrade path from version N to N+1.

- **Phase-marker ordering:** if this step writes a persisted phase/state marker (e.g., `BundleReconcilePhase::ImagesBuilt`, `.image_pending` removal, compose snapshot), specify that the marker is written AFTER the operation it represents succeeds — never before. A phase written before its operation lies to crash-recovery. If ordering is not explicitly stated, the implementer will choose arbitrarily, and "write marker first, do work second" is the natural but wrong default.

Order matters — steps must be executable in sequence. If step 3 fails, what happens to steps 1-2?

### 5. Test Plan

For EACH implementation step, specify concrete tests. "Add tests" is not acceptable.

**Required test categories per step:**

- **Happy path:** expected input → expected output

- **Error paths:** network down, file missing, permission denied, invalid input, timeout — what happens?

- **Edge cases:** empty strings, Unicode, max-length values, special characters, concurrent access

- **Boundary conditions:** 0, 1, max, overflow

- **Platform-specific:** UID differences, path separators, case sensitivity (if applicable)

- **Rollback/recovery:** what if this step fails mid-operation? Is the system left in a consistent state?

- **Stale state:** macOS sleep/resume, container restart, VM recreation (if applicable)

- **Upgrade scenarios:** old config + new binary, new config + old containers, partial update interrupted mid-way (if applicable)

- **Idempotency / mock fidelity:** if the system-under-test claims to be idempotent (skip-if-exists, rebuild-only-if-missing), the test must use a mock whose state mutates after create/build calls, and assert exact call counts (`== N`, not `>= N`). A test that passes with `>= 1` cannot distinguish "correctly skipped the second call" from "executed twice". For each new mock, specify which write methods should update the mock's read state (e.g., `build_image` must add the tag so `image_exists` returns `true` on subsequent calls).

**Test placement:**

- Rust: `#[cfg(test)] mod tests` at bottom of source file

- MCP Hub tools: follow pattern from `.claude/rules/mcp-servers.md` (metadata, execute success, parameter validation with missing/empty/null/undefined/falsy, error handling, edge cases)

- Angular: `MockTauriService`, `data-testid` selectors

- entrypoint.sh: bats tests (`make test-entrypoint`)

- log_sanitizer.rs: positive test (redacted) + false-positive test (unchanged)

**Coverage thresholds that must not drop:**

- Rust: 70% lines

- MCP Hub: 50%/50%/40%/50% (lines/functions/branches/statements)

- MCP workers: 60%/60%/50%/60%

- Angular: 40%/40%/30%/40%

### 6. Security Checklist

Answer EVERY question. "N/A" is acceptable only with justification.

- [ ] New container mounts? → Must be `:ro` (only SharePoint `/tokens` and `/workspace` are `:rw`)

- [ ] New ports or endpoints exposed?

- [ ] Token storage or credential flow changed? → Per-project isolation preserved?

- [ ] New environment variables in containers? → Could they leak secrets?

- [ ] `compose.template.yml` modified? → SecurityCheck threat model questions answered?

- [ ] MCP Hub sandbox/executor touched? → Forbidden pattern denylist, restricted context, prototype chain hardening (ADR-029) intact?

- [ ] SSRF protection touched? → Allowlist, port enforcement, redirect blocking intact?

- [ ] OWASP hardening intact? (`cap_drop: ALL`, `no-new-privileges`, `read_only`, `tmpfs: /tmp:noexec,nosuid`)

- [ ] Secrets in logs/serialization/display? → `log_sanitizer.rs` rules applied?

- [ ] Authentication gates preserved? (backend + frontend)

- [ ] `path-validator.ts` denylist intact? (`.git/`, `.env`, `.speedwave/`)

- [ ] New or modified bundled macOS binary? → satisfies the "Adding a new bundled binary" checklist in [`docs/contributing/release-signing.md`](../../../docs/contributing/release-signing.md#adding-a-new-bundled-binary)

### 7. Documentation Plan

- [ ] New feature → which guide in `docs/guides/` to update?

- [ ] Architectural decision → ADR number and title (with footnoted sources)

- [ ] Configuration change → `docs/getting-started/configuration.md` update?

- [ ] CLI change → `docs/guides/cli.md` update?

- [ ] Plugin contract change → CLAUDE.md contract table update?

- [ ] Container topology change → `docs/architecture/containers.md` update?

- [ ] Security model change → `docs/architecture/security.md` update?

- [ ] Platform behavior change → `docs/architecture/platform-matrix.md` update?

- [ ] New doc file → linked from `docs/README.md`?

- [ ] New ADR → `docs/adr/README.md` index updated?

### 8. Git Strategy

- **Do not propose a new branch name or worktree setup.** When this plan runs under `plan-loop.sh`, the worktree and branch are already created before Phase 1 starts — proposing a different branch name only creates confusion. Specify only: commit format, PR target, commit split if any, linked issues.

- PR target: `dev` (NEVER `main`)

- Commit format: conventional commits (`feat(scope):`, `fix(scope):`) — match the commit type to the task (bug fix → `fix`, new capability → `feat`, cleanup/chore → `chore`). Do not default to `feat` when the change is a fix.

- If multiple commits needed: describe the split and order

- Link to GitHub issue(s) if they exist

- Verification before push: `make check` (not just `make test`)

### 9. Upgrade Safety Checklist

This section ensures that after a user updates Speedwave from version N to N+1, everything works correctly without manual intervention. Answer EVERY question. "N/A" is acceptable only with justification.

**Persisted state compatibility:**

- [ ] Does this change the schema or structure of `~/.speedwave/config.json`? → New fields MUST have `#[serde(default)]` so old configs deserialize without error. Removed fields MUST be ignored (`#[serde(deny_unknown_fields)]` must NOT be used). Renamed fields need a migration path or backward-compatible alias.

- [ ] Does this change token paths (`~/.speedwave/tokens/<project>/<service>/`)? → Old tokens must remain valid. New paths must be populated automatically, not require user action.

- [ ] Does this change `compose.template.yml` or `render_compose()` output? → Old running containers will be recreated with new compose on next `update`. Verify the transition is handled by `update_containers()` security gate + snapshot/rollback.

- [ ] Does this change `bundle-manifest.json` or `bundle-state.json` format? → The reconcile pipeline (ADR-030) must handle both old and new format during the transition. A new binary may read an old `bundle-state.json` left by a previous version.

- [ ] Does this add, remove, or rename files in `~/.speedwave/`? → Orphaned files from old version must not cause errors. New required files must be created automatically on first run.

**Container image compatibility:**

- [ ] Does this change container image names or tags? → Images are tagged with `bundle_id`. Old images from previous bundle remain on disk. New containers must use new tags, not assume `:latest`.

- [ ] Does this change Containerfile build context or dependencies? → Image rebuild is handled by reconcile phase 2 (`ImagesBuilt`). Verify the build succeeds with the new context.

- [ ] Does this change environment variables injected into containers? → Running containers from old version won't have new env vars until recreated. Code inside containers must handle missing new env vars gracefully (default values, not crashes).

**CLI and API compatibility:**

- [ ] Does this change CLI subcommand names, flags, or output format? → Scripts or Desktop UI parsing CLI output will break. If changing output format, ensure all consumers are updated in the same release.

- [ ] Does this change Tauri command signatures or return types? → Frontend models (`desktop/src/src/app/models/`) must match. A version mismatch between Tauri backend and Angular frontend causes runtime errors.

- [ ] Does this change MCP Hub tool schemas or worker endpoints? → Claude's cached tool list may reference old schemas. Hub must handle requests for removed/renamed tools gracefully.

**Plugin contract compatibility:**

- [ ] Does this change any element in the plugin contract table (CLAUDE.md)? → Existing installed plugins in `~/.speedwave/plugins/` must continue to work. If breaking — coordinate with `speedwave-plugins` repo or add backward compat.

- [ ] Does this change `entrypoint.sh` plugin loading logic? → Plugins ship `claude-resources/` that are symlinked at container start. Changes must handle both old and new plugin directory structures.

**Interrupted update recovery:**

- [ ] If the update is interrupted mid-way (crash, power loss, kill -9), is the system left in a recoverable state? → Atomic file writes (`.tmp` + rename), persisted reconcile phases, snapshot before compose mutation.

- [ ] Can the user recover by simply running `speedwave update` again? → The update must be idempotent — running it twice produces the same result as running it once.

**Rollback path:**

- [ ] If the new version has a critical bug, can the user downgrade? → Describe what happens if a user installs an older binary. Will it read new-format config/state correctly? Will it fail gracefully or corrupt data?

- [ ] Are compose snapshots preserved so `rollback_containers()` can restore the previous state?

## Rules While Writing

- **No TODO/FIXME/HACK/XXX** — if something can't be done now, say so explicitly, don't leave markers

- **No `#[allow(dead_code)]` or `#[allow(...)]`** — plan the code so it doesn't need suppressions

- **No host `limactl`/`nerdctl`/`docker`** — all through `speedwave-runtime` (`detect_runtime()`)

- **No git hook bypass** — plan must work with hooks enabled

- **No speculative features** — only what the task requires. No "future extensibility", no feature flags, no backward-compatibility shims.

- **KISS** — if >100 lines for something a CLI tool already does, find the tool. Prefer shelling out over reimplementing.

- **DRY** — use existing SSOT locations. Don't duplicate logic from `speedwave-runtime` or `mcp-servers/shared/`.

- **Rule of Three** — don't create abstractions for a pattern seen fewer than three times.

- **Boy Scout Rule** — if you encounter bugs, typos, or inconsistencies in code you're modifying, include fixes in the plan.

- **Upgrade safety** — every change to persisted state, file formats, or inter-component contracts must work when a user updates from any previous release. Assume zero manual intervention by the end user.

---

## Step 2 — Present for Review

When the plan is complete, present it to the user in plan mode. The user will review, ask questions, or request changes. Iterate until approved.

Only call `ExitPlanMode` when the user explicitly approves the plan and you are ready to begin implementation.