diff --git a/docs/superpowers/coordination/2026-05-04-arch-followup-dev-a-prompt.md b/docs/superpowers/coordination/2026-05-04-arch-followup-dev-a-prompt.md new file mode 100644 index 0000000..a0aec27 --- /dev/null +++ b/docs/superpowers/coordination/2026-05-04-arch-followup-dev-a-prompt.md @@ -0,0 +1,194 @@ +# Dev A Kickoff Prompt — arch-followup Plan A + +Paste everything below the `---` line into a fresh Claude Code terminal as the first user message. + +--- + +You are a **senior developer** owning Plan A for the arch-followup "architecture-review followups" release train. + +Plan A is the **security & docs polish PR** — the small one that ships first, in under a day, with no dependencies on Plans B or C. It closes the only defense-in-depth crypto gap the architecture review flagged (`SessionHandle` has no `impl Drop`, so wasm-bindgen's `.free()` is a cleanup no-op while the master key sits in WASM linear memory), removes the JS-side error swallow that was masking that fact, brings `recovery_qr.rs` documentation up to the density of `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs`, and finishes the relay-launcher dev-c expansion. Four phases, all S-effort. + +A PM in another terminal coordinates you with Dev-B (CLI restructure) and Dev-C (extension restructure). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below). + +## Setup (do this first) + +```bash +cd /home/alee/Sources/relicario +git fetch +git checkout main +git pull +git worktree add ../relicario-plan-a -b feature/2026-05-04-a-security-polish +cd ../relicario-plan-a +pwd # should print /home/alee/Sources/relicario-plan-a (or similar absolute path) +``` + +**ALL subsequent work happens in `/home/alee/Sources/relicario-plan-a`**. Force-cd subagents into this directory — the project's `CLAUDE.md` memory rule explicitly requires that subagent prompts MUST start with `cd /home/alee/Sources/relicario-plan-a` so subagents don't accidentally commit to main. This is non-negotiable. + +Today: 2026-05-04. Project rules in `CLAUDE.md` apply. + +## Relay server + +A message-bus MCP server is running on `localhost:7331`. You have three native tools: + +- `post_message(from, to, kind, body)` — push a message; your `from` is always `"dev-a"` +- `read_messages(for)` — drain your inbox; call with `for="dev-a"` before each task +- `list_pending(for)` — check inbox count without consuming + +Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-a")`. After emitting any status/question block: `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")`. + +**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim: + +```bash +cd /home/alee/Sources/relicario/tools/relay +python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}' +python3 call.py read_messages '{"for":"dev-a"}' +``` + +## Required reading (in order) + +1. `CLAUDE.md` — project rules +2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.1, P1.7, P1.8 + the partner JS-side fix at `service-worker/session.ts:26` + the `start.sh` launcher follow-up only**) +3. `docs/superpowers/specs/2026-05-04-security-polish-design.md` — your plan, execute phase by phase + +You do NOT need to read Plan B or Plan C in detail. Skim Plan B's "WASM/extension parity seam" paragraph (Phase 8) and Plan C's "Risks → `.free()` callsite policy" paragraph only if a coordination question arises — they're the points where Plans B/C reference your work. + +## Execution mode + +Use **subagent-driven-development** (per project memory's default for any multi-task plan). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review between phases. + +**Every subagent prompt MUST start with**: +``` +cd /home/alee/Sources/relicario-plan-a +``` +…before any other instruction. This is non-negotiable per project memory. + +## Your scope and boundaries + +**In scope:** Phase 1 (Rust `impl Drop for SessionHandle` + wasm-bindgen-test + native fallback test), Phase 2 (JS `.free()` audit + remove the `try { current.free() }` swallow at `extension/src/service-worker/session.ts:26`), Phase 3 (`recovery_qr.rs` documentation pass — module-level `//!`, ASCII layout diagram, doc-comments on the four public items, `production_params` rationale or `const`), Phase 4 (`tools/relay/start.sh` dev-c expansion + verification that `queue.test.ts:54` is already fixed). + +**Out of scope:** anything in Plan B (CLI restructure — `cli/main.rs` split, `git_run` helper, parser migration to core, etc.) or Plan C (extension restructure — `setup.ts` SW migration, `vault.ts` split, `StateHost` typing, SW router dedup). The other P2 WASM cleanups (double-lookup, Vec clone, naming inconsistency, concurrency primitive split). DEV-C's other relay P2s (queue TTL, `call.py`/`call.ts` tracking decision). The 8 "Open architectural decisions". If you trip over an out-of-scope issue or a new bug while doing your work, file it via a `## QUESTION TO PM` block and keep moving. + +**Hard rules:** +- This is a defense-in-depth crypto fix. Do NOT skip Phase 1's `wasm-bindgen-test` AND the native `#[test]` fallback — both are required by the plan's Done criteria. +- Do NOT remove the `try { current.free() }` swallow (Phase 2) until Phase 1's `impl Drop` has landed in the same branch — Phase 2 explicitly depends on Phase 1. +- Phase 3 must produce documentation density that visibly matches `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs`. If your doc-block is shorter than `crypto.rs`'s top comment, it's not done. +- Phase 4: confirm `queue.test.ts:54` is already fixed in commit `061facd` (read the file; assert the line is `assert.ok(isRole("dev-c"));`). If it isn't, escalate via `## QUESTION TO PM` — the plan was drafted assuming it was fixed. +- The plan's Done criteria includes recording the `grep -rn "\.free\b" extension/src/` output in the PR description as the audit deliverable. Do NOT merge the PR without that grep recorded. +- Do not merge your branch to main. The PM owns merges. +- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first. + +## Coordination protocol + +You are one of multiple terminals. The relay routes messages between them. + +**At every phase boundary** (complete, blocked, or question): call `read_messages(for="dev-a")` first, then post your update via `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")` and also print it here. Use this format: + +``` +## STATUS UPDATE — DEV-A +Time: +Branch: feature/2026-05-04-a-security-polish +Task: +Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY +Last commit: +Tests: +Notes: +``` + +**When you need PM input mid-task**: post via `post_message(kind="question")` with format: + +``` +## QUESTION TO PM — DEV-A +Time: +Context: +Options: +Recommended: +Blocker: yes | no (does work stop without an answer?) +``` + +**You'll receive**: `## DIRECTIVE TO DEV-A` blocks from the PM via relay (or relayed by user if relay is down). Acknowledge and act. + +## Authority within the plan + +You don't need PM permission to: +- Execute phase-to-phase per the plan +- Make implementation decisions consistent with the plan and synthesis +- Choose between the plan's optional micro-cleanups in Phase 3 (the named-constant slice ranges, the `recovery_kdf_input` length-prefix comment) — proceed if they make the code clearer +- Decide whether to add `wasm.lock(handle)` before `.free()` in `clearCurrent()` (Phase 2 leaves this to your judgment; the plan recommends just `free()` post-Phase-1) +- Write tests, refactor your own code, fix bugs you introduce +- Push commits to your feature branch + +You **do** escalate to PM when: +- You discover the Rust toolchain is older than 1.79 (Phase 3 falls back to a runtime `#[test]` for the layout assertion — confirm with PM before switching) +- You discover the `.free()` audit grep returns more than one match (the plan was drafted expecting one; investigate and report) +- You discover `queue.test.ts:54` is NOT actually fixed (Phase 4 falls back to a real code change) +- You discover the `start.sh` launcher requires deeper changes than the four locations the plan describes +- A test you can't make green after honest debugging (don't fudge — debug) +- A discovered bug not in your plan +- Anything destructive (per project rules) +- Before opening the PR for review + +## Final steps before REVIEW-READY + +Run the project's full validation: + +```bash +# From the worktree root (/home/alee/Sources/relicario-plan-a): +cargo test -p relicario-core +cargo test -p relicario-wasm +cd extension && npm test && cd .. + +# Audit deliverable (record output in PR description): +grep -rn "\.free\b" extension/src/ + +# Optional but recommended for the wasm-bindgen-test (requires wasm-pack): +# wasm-pack test --node crates/relicario-wasm + +# Manual launcher checks (Phase 4): +bash tools/relay/start.sh --manual # confirm "Open 4 new terminals" + Dev-C prompt path +# bash tools/relay/start.sh --kitty # if on a kitty terminal: confirm 4 tabs open +``` + +Then push and open the PR: + +```bash +git push -u origin feature/2026-05-04-a-security-polish +gh pr create --base main --head feature/2026-05-04-a-security-polish --title "docs+fix(arch-followup): Drop impl + recovery_qr docs + relay launcher (Plan A)" --body "$(cat <<'EOF' +## Summary + +Architecture-review followup Plan A (security & docs polish). Source: `docs/superpowers/specs/2026-05-04-security-polish-design.md`. + +- **P1.1** — `SessionHandle` now has `impl Drop` so wasm-bindgen's `.free()` actually clears the master key from WASM linear memory. Native + wasm-bindgen tests cover construct → drop → registry-empty. +- **JS partner fix** — removed the `try { current.free() }` swallow at `extension/src/service-worker/session.ts:26`. Crypto-state-transition errors now propagate. +- **P1.7** — `crates/relicario-core/src/recovery_qr.rs` documentation pass: module-level `//!`, ASCII layout diagram, doc-comments on the four public items, `production_params` parameter-pinning rationale. +- **P1.8** — confirmed `tools/relay/queue.test.ts:54` already matches the new role union (committed in `061facd`); `tools/relay/start.sh` extended to discover and launch a fourth Dev-C window in `--manual`, `--tmux`, `--kitty` modes. + +## Audit deliverables + +`.free()` callsites under `extension/src/` (recorded for future regression baseline): + +``` + +``` + +## Test plan + +- [ ] `cargo test -p relicario-core` passes (recovery_qr tests still green; layout static assertion compiles) +- [ ] `cargo test -p relicario-wasm` passes including new `Drop` test +- [ ] `cd extension && npm test` passes including new `clearCurrent()` test +- [ ] `grep -rn "\.free\b" extension/src/` returns exactly one match (the SW callsite) +- [ ] `bash tools/relay/start.sh --manual` shows "Open 4 new terminals" and lists the Dev-C prompt path + +## Done criteria + +Per `docs/superpowers/specs/2026-05-04-security-polish-design.md` Done criteria — every checkbox. + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL (post via `post_message`). + +## First action + +After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created at `/home/alee/Sources/relicario-plan-a`, plan absorbed, on `feature/2026-05-04-a-security-polish`). Post it via `post_message(from="dev-a", to="pm", kind="status", body="...")`. Then start Phase 1 of your plan (Rust `impl Drop for SessionHandle` + tests). diff --git a/docs/superpowers/coordination/2026-05-04-arch-followup-dev-b-prompt.md b/docs/superpowers/coordination/2026-05-04-arch-followup-dev-b-prompt.md new file mode 100644 index 0000000..466f96a --- /dev/null +++ b/docs/superpowers/coordination/2026-05-04-arch-followup-dev-b-prompt.md @@ -0,0 +1,207 @@ +# Dev B Kickoff Prompt — arch-followup Plan B + +Paste everything below the `---` line into a fresh Claude Code terminal as the first user message. + +--- + +You are a **senior developer** owning Plan B for the arch-followup "architecture-review followups" release train. + +Plan B is the **CLI restructure** — the "single biggest readability lift" per the synthesis. M-L effort, multi-day. It splits `crates/relicario-cli/src/main.rs` (2641 LOC) into a `commands/` folder + `prompt.rs` + `parse.rs`, then layers on the duplicated git-error UX consolidation, manifest-after-mutation cache discipline, `ParamsFile` dedup, batched purge, and the migration of pure parsers (and a third copy of base32) into `relicario-core` with WASM re-exports. Eight phases. + +A PM in another terminal coordinates you with Dev-A (security & docs polish) and Dev-C (extension restructure). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below). + +## Setup (do this first) + +```bash +cd /home/alee/Sources/relicario +git fetch +git checkout main +git pull +git worktree add ../relicario-plan-b -b feature/2026-05-04-b-cli-restructure +cd ../relicario-plan-b +pwd # should print /home/alee/Sources/relicario-plan-b (or similar absolute path) +``` + +**ALL subsequent work happens in `/home/alee/Sources/relicario-plan-b`**. Force-cd subagents into this directory — the project's `CLAUDE.md` memory rule explicitly requires that subagent prompts MUST start with `cd /home/alee/Sources/relicario-plan-b` so subagents don't accidentally commit to main. This is non-negotiable. + +Today: 2026-05-04. Project rules in `CLAUDE.md` apply. + +## Relay server + +A message-bus MCP server is running on `localhost:7331`. You have three native tools: + +- `post_message(from, to, kind, body)` — push a message; your `from` is always `"dev-b"` +- `read_messages(for)` — drain your inbox; call with `for="dev-b"` before each task +- `list_pending(for)` — check inbox count without consuming + +Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-b")`. After emitting any status/question block: `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")`. + +**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim: + +```bash +cd /home/alee/Sources/relicario/tools/relay +python3 call.py post_message '{"from":"dev-b","to":"pm","kind":"status","body":"..."}' +python3 call.py read_messages '{"for":"dev-b"}' +``` + +## Required reading (in order) + +1. `CLAUDE.md` — project rules (Spanish flourish in chat replies only, capitalization, autonomy defaults, CLI/extension parity philosophy) +2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.2, P1.3, P1.10 + the in-scope CLI P2s only**) +3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — your plan, execute phase by phase +4. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's full notes (your primary source for line-level context — the synthesis abbreviates) +5. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — read **only** the "Boundary notes for DEV-B" section near the end (cross-boundary contracts you must respect when designing the WASM exports for Phase 8) + +You do NOT need to read Plan A or Plan C in detail. If a coordination question arises, skim Plan C's "Risks → WASM boundary coordination" paragraph (it cites your Phase 8 explicitly). + +## Execution mode + +Use **subagent-driven-development** (per project memory's default for any multi-task plan). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review between phases. + +**Every subagent prompt MUST start with**: +``` +cd /home/alee/Sources/relicario-plan-b +``` +…before any other instruction. This is non-negotiable per project memory. + +**Sequencing matters.** Phase 1 (the mechanical `main.rs` split) is the precondition for every other phase — phases 2-6 touch files that don't exist yet until phase 1 lands. Do NOT start phase 2 until phase 1's `cargo test --workspace` is green and a checkpoint commit is in place. + +## Your scope and boundaries + +**In scope:** +- Phase 1 — Mechanical split of `main.rs` into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr,init,generate,rate}.rs` + `prompt.rs` + `parse.rs` +- Phase 2 — `helpers::git_run` + sweep of the 16 `bail!("git X failed")` sites +- Phase 3 — `prompt_or_flag` and `build_*_item` compression +- Phase 4 — `Vault::after_manifest_change` + sweep of the 7 `refresh_groups_cache` sites +- Phase 5 — Single canonical `ParamsFile` (one definition shared between init writer and unlock reader) +- Phase 6 — Batched purge in `cmd_purge` and `cmd_trash_empty` (3 git invocations for an N-item purge instead of 3N) +- Phase 7 — Migrate `parse_month_year` / `base32_decode_lenient` / `guess_mime` to `relicario-core` + `pub(crate) mod base32` (closes DEV-A's three-base32-impls finding) +- Phase 8 — WASM exports for the migrated parsers + `extension/src/wasm.d.ts` mirror + +**Out of scope:** anything in Plan A (security/docs polish — Drop impl, recovery_qr docs, relay launcher) or Plan C (extension restructure — setup.ts SW migration, vault.ts split, StateHost typing, SW router dedup). The CLI P3 nits (let _ = entry pattern, Lock subcommand visibility, Display for ItemType, helpers::relicario_dir adoption sweep, gitea Client per-call construction, edit_and_history.rs scripted prompts, dead test variable, three-test-env-var macro, cmd_recovery_qr_unwrap empty input check, Task 12 cleanup). Server findings (P2/P3 in DEV-B's relicario-server section). WASM findings beyond the parser exports needed for P1.10 (DEV-B's WASM P2 list — double-lookup, Vec clone, naming, concurrency primitive split). The 8 "Open architectural decisions". The WASM JS-naming snake_case → camelCase decision (deferred to a separate plan). If you trip over an out-of-scope issue or a new bug, file it via a `## QUESTION TO PM` block and keep moving. + +**Hard rules:** +- Phase 1 is **mechanical** — no logic changes, no signature changes, no error-message reword. Run `cargo check -p relicario-cli` between every file extraction; existing CLI integration tests at `crates/relicario-cli/tests/*` must stay green throughout. They are the regression budget. +- Phase 2's `git_run` switches from `.status()` (inherited stderr to TTY) to `.output()` (captured); the captured stderr MUST be printed to the user's stderr unmodified on failure. Do not silently swallow. +- Phase 5's `ParamsFile` migration is on-disk-format-sensitive. Field names and types MUST match the existing `params.json` shape exactly; the round-trip test against a fixture string is required by the plan's Done criteria. +- Phase 7 — `MonthYear::new` currently returns `Result<_, &'static str>` (DEV-A's P3 nit). The plan recommends re-wrapping the error in `MonthYear::parse` rather than migrating `new` to `RelicarioError`. If you'd rather migrate `new` for consistency, escalate to PM first — this is a cross-plan coordination concern. +- Phase 8 keeps **snake_case** JS names (consistent with every existing export). Do not introduce camelCase for the three new exports. The snake_case → camelCase decision is deferred to a separate plan. +- Phase 8 updates `extension/src/wasm.d.ts` and the new `#[wasm_bindgen]` exports in the same commit. Per DEV-C's boundary note, `wasm.d.ts` is hand-maintained — do not let the two surfaces drift even temporarily. +- The Steam alphabet at `crates/relicario-core/src/item_types/totp.rs:13` is **intentionally non-RFC-4648** and must NOT move into the new `pub(crate) mod base32`. Add a neighbour comment per the plan. +- Do not merge your branch to main. The PM owns merges. +- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first. + +## Coordination protocol + +You are one of multiple terminals. The relay routes messages between them. + +**At every phase boundary** (complete, blocked, or question): call `read_messages(for="dev-b")` first, then post your update via `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")` and also print it here. Use this format: + +``` +## STATUS UPDATE — DEV-B +Time: +Branch: feature/2026-05-04-b-cli-restructure +Task: +Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY +Last commit: +Tests: +Notes: +``` + +**When you need PM input mid-task**: post via `post_message(kind="question")` with format: + +``` +## QUESTION TO PM — DEV-B +Time: +Context: +Options: +Recommended: +Blocker: yes | no (does work stop without an answer?) +``` + +**You'll receive**: `## DIRECTIVE TO DEV-B` blocks from the PM via relay (or relayed by user if relay is down). Acknowledge and act. + +## Cross-plan coordination + +- **Plan C consumes your Phase 8 WASM exports** (`parse_month_year` / `base32_decode_lenient` / `guess_mime`) — but only as a deferred follow-up, NOT in Plan C's current execution. You ship the seam; Plan C does not wire the SW handlers in this train. Sequence Phase 8 to land before Plan C touches `wasm.d.ts` if both must touch it. +- **`extension/src/wasm.d.ts` shared touchpoint with Plan C.** Plan C says it likely does NOT need to touch this file (its `create_vault`/`attach_vault` handlers reuse already-declared WASM entries). If Plan C does end up touching it, sequence Plan B's edits first and ask Plan C to rebase. +- **Plan A's `impl Drop for SessionHandle`** is independent of you. Your `git_run` and parser-migration work doesn't touch the WASM crate's session module. No conflict. + +## Authority within the plan + +You don't need PM permission to: +- Execute phase-to-phase per the plan +- Make implementation decisions consistent with the plan and synthesis +- Add new tests, refactor your own code, fix bugs you introduce +- Choose between optional approaches the plan calls out (e.g. whether `Vault::after_manifest_change` calls `save_manifest` internally vs renaming the existing method to `save_manifest_raw`) +- Push commits to your feature branch + +You **do** escalate to PM when: +- You discover the grep at the top of Phase 7 returns non-CLI consumers of `parse_month_year` / `base32_decode_lenient` / `guess_mime` / `base32_encode` / `decode_base32_totp` (the plan was drafted assuming zero non-CLI consumers; investigate) +- A `cargo test --workspace` failure you can't reproduce locally +- You want to deviate on the `MonthYear::new` consistency point (see Hard Rules) +- You discover the `ParamsFile` round-trip is not field-compatible with the current on-disk format (rename, type change, etc.) +- A test you can't make green after honest debugging (don't fudge — debug) +- A discovered bug not in your plan +- Anything destructive (per project rules) +- Before opening the PR for review + +## Final steps before REVIEW-READY + +Run the project's full validation: + +```bash +# From the worktree root (/home/alee/Sources/relicario-plan-b): +cargo test --workspace +cargo clippy --workspace --all-targets --no-deps +cargo build -p relicario-wasm --target wasm32-unknown-unknown + +# Done-criteria sanity greps (all should return zero matches): +grep -n 'bail!("git ' crates/relicario-cli/src/ +grep -n 'refresh_groups_cache' crates/relicario-cli/src/ | grep -v 'session\.rs' +# These should each return one match: +grep -n 'struct ParamsFile' crates/relicario-cli/src/ + +# CLI smoke (post-split, end-to-end): +cargo run -p relicario-cli -- --help +``` + +Then push and open the PR: + +```bash +git push -u origin feature/2026-05-04-b-cli-restructure +gh pr create --base main --head feature/2026-05-04-b-cli-restructure --title "refactor(cli): split main.rs + git_run helper + parsers→core (Plan B)" --body "$(cat <<'EOF' +## Summary + +Architecture-review followup Plan B (CLI restructure — single biggest readability lift). Source: `docs/superpowers/specs/2026-05-04-cli-restructure-design.md`. + +- **P1.2** — `cli/main.rs` split from 2641 LOC into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr,init,generate,rate}.rs` + `prompt.rs` + `parse.rs`. `main.rs` retains clap + dispatch only (~470 lines). +- **P1.3** — `helpers::git_run(repo, args, context)` captures stderr; 16 duplicated bail sites collapsed. +- **P1.10** — `parse_month_year` / `base32_decode_lenient` / `guess_mime` migrated to `relicario-core` (`MonthYear::parse`, `pub(crate) mod base32::{encode_rfc4648,decode_rfc4648_lenient}`, `mime::guess_for_extension`); also closes DEV-A's three-base32-impls finding by extracting the shared module. WASM exports added; `extension/src/wasm.d.ts` mirrored. +- **CLI P2 cluster** — `prompt_or_flag` compression of `build_*_item`; `Vault::after_manifest_change` centralizes the `refresh_groups_cache` discipline (7 sites collapsed); single canonical `ParamsFile` shared between init writer and unlock reader; batched purge — a 50-item `trash empty` is now 3 git invocations instead of 150. + +## Test plan + +- [ ] `cargo test --workspace` passes +- [ ] `cargo clippy --workspace` silent +- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` clean +- [ ] `grep -n 'bail!("git ' crates/relicario-cli/src/` returns zero matches +- [ ] `grep -n 'refresh_groups_cache' crates/relicario-cli/src/` returns zero matches outside `session.rs` +- [ ] `grep -n 'struct ParamsFile' crates/relicario-cli/src/` returns one match +- [ ] New test asserts a multi-item `trash empty` produces exactly one new git commit +- [ ] All existing CLI integration tests at `crates/relicario-cli/tests/*` still pass without modification + +## Done criteria + +Per `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Done criteria — every checkbox. + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL (post via `post_message`). + +## First action + +After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created at `/home/alee/Sources/relicario-plan-b`, plan absorbed, on `feature/2026-05-04-b-cli-restructure`). Post it via `post_message(from="dev-b", to="pm", kind="status", body="...")`. Then start Phase 1 of your plan (mechanical split of `cli/main.rs`). Remember: phase 1 is mechanical — `cargo check` between every file extraction. diff --git a/docs/superpowers/coordination/2026-05-04-arch-followup-dev-c-prompt.md b/docs/superpowers/coordination/2026-05-04-arch-followup-dev-c-prompt.md new file mode 100644 index 0000000..c6980cd --- /dev/null +++ b/docs/superpowers/coordination/2026-05-04-arch-followup-dev-c-prompt.md @@ -0,0 +1,218 @@ +# Dev C Kickoff Prompt — arch-followup Plan C + +Paste everything below the `---` line into a fresh Claude Code terminal as the first user message. + +--- + +You are a **senior developer** owning Plan C for the arch-followup "architecture-review followups" release train. + +Plan C is the **extension restructure** — the largest of the three (multi-day to multi-week). It eliminates the two steepest learning cliffs in the extension. After this plan ships, `setup.ts` no longer imports `relicario-wasm` directly (it isn't the pattern; it was the exception); `vault.ts` shrinks from 1027 LOC to ~200 of routing + state; `shared/state.ts` becomes type-checked end-to-end; the duplicated SW router helpers consolidate into one home each; and the extension closes its last CLI-parity gap (`relicario status` → vault-sidebar status indicator). Six phases. + +A PM in another terminal coordinates you with Dev-A (security & docs polish) and Dev-B (CLI restructure). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below). + +## Setup (do this first) + +```bash +cd /home/alee/Sources/relicario +git fetch +git checkout main +git pull +git worktree add ../relicario-plan-c -b feature/2026-05-04-c-extension-restructure +cd ../relicario-plan-c +pwd # should print /home/alee/Sources/relicario-plan-c (or similar absolute path) +``` + +**ALL subsequent work happens in `/home/alee/Sources/relicario-plan-c`**. Force-cd subagents into this directory — the project's `CLAUDE.md` memory rule explicitly requires that subagent prompts MUST start with `cd /home/alee/Sources/relicario-plan-c` so subagents don't accidentally commit to main. This is non-negotiable. + +Today: 2026-05-04. Project rules in `CLAUDE.md` apply. + +## Relay server + +A message-bus MCP server is running on `localhost:7331`. You have three native tools: + +- `post_message(from, to, kind, body)` — push a message; your `from` is always `"dev-c"` +- `read_messages(for)` — drain your inbox; call with `for="dev-c"` before each task +- `list_pending(for)` — check inbox count without consuming + +Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-c")`. After emitting any status/question block: `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")`. + +**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim: + +```bash +cd /home/alee/Sources/relicario/tools/relay +python3 call.py post_message '{"from":"dev-c","to":"pm","kind":"status","body":"..."}' +python3 call.py read_messages '{"for":"dev-c"}' +``` + +## Required reading (in order) + +1. `CLAUDE.md` — project rules (Spanish flourish in chat replies only, capitalization, autonomy defaults, CLI/extension parity philosophy, security defense-in-depth) +2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.4, P1.5, P1.6, P1.9 + the in-scope extension P2s + the `relicario status` parity gap only**) +3. `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — your plan, execute phase by phase +4. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — DEV-C's full notes (your primary source — the synthesis abbreviates) +5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — read **only** the "Boundary notes for DEV-C" section near the end (14 numbered contracts the JS side must respect when interacting with WASM; several inform your scope) + +You do NOT need to read Plan A or Plan B in detail. Skim Plan A's Phase 2 (the `service-worker/session.ts:26` swallow removal) and Plan B's Phase 8 (WASM parser exports) only if a coordination question arises. + +## Execution mode + +Use **subagent-driven-development** (per project memory's default for any multi-task plan). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review between phases. + +**Every subagent prompt MUST start with**: +``` +cd /home/alee/Sources/relicario-plan-c +``` +…before any other instruction. This is non-negotiable per project memory. + +**Sequencing matters.** Phase 1 (typed `StateHost`) is the precondition for phases 3 and 4. Phase 2 (SW storage extraction) is independent and can ship in parallel. Phases 3 and 4 both depend on phase 1. Phase 5 (P2 cluster) and phase 6 (`get_vault_status`) are independent of 3 and 4 — they can run in parallel. + +## Your scope and boundaries + +**In scope:** +- Phase 1 — Typed `StateHost` interface in `extension/src/shared/state.ts` (no `any` in public surface) + generic `getState`/`setState` over `keyof PopupState` + double-registration guard + `__resetHostForTests` helper. Includes migration of `View` and `PopupState` from `extension/src/popup/popup.ts` to `extension/src/shared/types.ts` (or a new `shared/popup-state.ts`) to avoid a `popup → shared → popup` circular import. +- Phase 2 — Extract `extension/src/service-worker/storage.ts` (`loadDeviceSettings`, `loadBlacklist`, `saveBlacklist` from both router files) + move `itemToManifestEntry` to `extension/src/service-worker/vault.ts`. +- Phase 3 — Setup wizard SW migration: add `create_vault` and `attach_vault` SW messages; rewrite `setup.ts` as UI-only that posts those messages; convert the 6-step procedural wizard to a step-registry pattern; add `clearWizardState()` on `beforeunload` + step-0 reset. +- Phase 4 — Split `vault.ts` into `vault-shell.ts` / `vault-sidebar.ts` / `vault-list.ts` / `vault-drawer.ts` / `vault-form-wrapper.ts`. Lift `vault_locked` RPC intercept into `shared/state.ts`. Reset `state.drawerOpen` on non-list `renderPane`. Debounce sidebar search (50-100ms). +- Phase 5 — P2 cluster: inactivity-timer reset on content-callable messages (with documented exclusion set); `state.gitHost` clear on session expiry; teardown helper extraction (`teardownSettingsCommon`); `Promise.allSettled` in devices/trash; MutationObserver debounce in `content/detector.ts`. +- Phase 6 — `get_vault_status` SW message + vault-sidebar status indicator (closes the `relicario status` parity gap). + +**Out of scope:** anything in Plan A (security/docs polish — `impl Drop`, `service-worker/session.ts:26` swallow removal, `.free()` audit, `recovery_qr.rs` docs, server hardening, env-var audit) or Plan B (CLI restructure — `cli/main.rs` split, `git_run`, parser migration to core; you only **consume** the WASM exports as a deferred follow-up). Extension P3s (form-header `isInTab()` redundancy, popup.ts `isInTab()` heuristic, item-form.ts `renderComingSoon` dead code, `types/login.ts` size, `vault.ts:18-26` backup-panel comment, capture/detector/fill username-finder dedup, capture submit-button hook scope, setup.ts passphrase-score `-1` sentinel, `setup.ts:1056-1062` chrome.storage bypass, `setup.ts:1-7` "5-step" header, glyphs.ts partial adoption, `types.ts` TotpKind flat-union, `totp-tools.ts:39-46` swallowed rejections, generator-panel cleanup guard, `item-list.ts` popover listeners, popup `popup.ts:178-181` unconditional teardowns). Other parity items (per-attachment `delete_attachment` SW message, `list --tag` filter doc note). Cross-cutting items not explicitly listed (chrome.storage.local direct reads outside the setup migration, bun test runner doc note, manifest version sync). The 8 "Open architectural decisions". WASM JS-naming snake_case → camelCase (deferred to a separate plan). Anything touching the in-flight uncommitted v0.5.x work. If you trip over an out-of-scope issue or a new bug, file it via a `## QUESTION TO PM` block and keep moving. + +**Hard rules:** +- **Phase 1 first.** Do NOT start phases 3 or 4 until phase 1 is green and committed. The typed `StateHost` is the contract phases 3 and 4 build against. +- **`View` / `PopupState` migration is part of phase 1**, not phase 4. Doing it later creates circular imports that surface mid-refactor and waste a day. +- **Do NOT redo Plan A's `.free()` swallow removal** at `extension/src/service-worker/session.ts:26`. That's Dev-A's. But wherever your refactor *moves* a `.free()` callsite — most notably during phase 3 when `setup.ts`'s `verifiedHandle` retires and the new `create_vault`/`attach_vault` SW handlers acquire their own handles — the new location MUST call `wasm.lock(handle)` first regardless of whether Plan A's Rust-side `impl Drop` has landed yet. Cite Plan A as the source of the policy in your phase 3 commit message. +- **`extension/src/wasm.d.ts` coordination with Plan B.** Plan B Phase 8 will touch this file for new parser exports. Verify by reading `extension/src/service-worker/vault.ts` whether your `create_vault`/`attach_vault` SW handlers need new WASM entry points — they likely don't (the SW already orchestrates `unlock`/`embed_image_secret`/`register_device`/`manifest_encrypt`). If you DO need new entries, escalate via `## QUESTION TO PM` so the touch order with Plan B can be sequenced. +- **`create_vault` and `attach_vault` SW handlers must be transactional** — they hold their own internal session reference for the duration of the operation and do NOT consult or reset the user-facing inactivity timer until they return successfully. Document this contract in the handler header comments. +- **Phase 4 `vault_locked` channel unification** keeps both signals (the SW's `session_expired` event AND the new `shared/state.ts` wrapper's intercept) firing during the migration window. Collapse only after both surfaces are verified consuming from `shared/state.ts`. Add a regression test asserting popup lock screen renders on `session_expired` and vault tab lock screen renders on the SW response intercept. +- **Round out the WASM stub at `extension/src/__stubs__/relicario_wasm.stub.ts`** as part of phase 3. DEV-C noted only 7 of ~25 exports are stubbed; phase 3's vitest tests for `create_vault`/`attach_vault` need stubs for `embed_image_secret`, `register_device`, `manifest_encrypt`. Add them rather than file a separate ticket. +- The `recovery_qr_generated_at` direct chrome.storage.local write at `setup.ts:1056-1062` is **out of scope** — leave it as-is; defer to a P3 cleanup. +- Do not merge your branch to main. The PM owns merges. +- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first. + +## Coordination protocol + +You are one of multiple terminals. The relay routes messages between them. + +**At every phase boundary** (complete, blocked, or question): call `read_messages(for="dev-c")` first, then post your update via `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")` and also print it here. Use this format: + +``` +## STATUS UPDATE — DEV-C +Time: +Branch: feature/2026-05-04-c-extension-restructure +Task: +Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY +Last commit: +Tests: +Notes: +``` + +**When you need PM input mid-task**: post via `post_message(kind="question")` with format: + +``` +## QUESTION TO PM — DEV-C +Time: +Context: +Options: +Recommended: +Blocker: yes | no (does work stop without an answer?) +``` + +**You'll receive**: `## DIRECTIVE TO DEV-C` blocks from the PM via relay (or relayed by user if relay is down). Acknowledge and act. + +## Cross-plan coordination + +- **Plan A owns the `.free()` swallow removal** (`service-worker/session.ts:26`) and the Rust `impl Drop for SessionHandle`. Do not redo that work. Do honor the policy where you move callsites (see Hard Rules). +- **Plan B Phase 8 ships WASM parser exports** (`parse_month_year` / `base32_decode_lenient` / `guess_mime`) that the extension can eventually consume. Consumption (SW message handlers wrapping the new exports) is **explicitly deferred to a future plan** — do NOT design those handlers in this train. The seam exists; nobody is wiring it yet. +- **`extension/src/wasm.d.ts` shared touchpoint with Plan B.** See Hard Rules — you likely don't need to touch it. If you do, escalate to PM for sequencing. + +## Authority within the plan + +You don't need PM permission to: +- Execute phase-to-phase per the plan +- Make implementation decisions consistent with the plan and synthesis +- Choose how the typed `StateHost` exposes `setState` (the plan suggests `setState`; pick the variant that gives the cleanest call-site ergonomics) +- Pick which file `View` and `PopupState` migrate to (`shared/types.ts` vs new `shared/popup-state.ts`) — the plan accepts either +- Add new tests, refactor your own code, fix bugs you introduce +- Push commits to your feature branch + +You **do** escalate to PM when: +- You discover phase 3's setup-to-SW migration needs new WASM entry points (would touch `wasm.d.ts` and conflict with Plan B Phase 8) +- You discover the `view`/`PopupState` migration in phase 1 surfaces more TS errors than the plan estimated (~15-30); if you hit 100+ errors, the surface area is bigger than the plan accounts for +- You discover a real bug in the existing `vault_locked` channels (e.g. popup currently doesn't actually receive `session_expired` despite the plan's premise) +- A vitest test you can't make green after honest debugging (don't fudge — debug) +- A discovered bug not in your plan +- Anything destructive (per project rules) +- Before opening the PR for review + +## Final steps before REVIEW-READY + +Run the project's full validation: + +```bash +# From the worktree root (/home/alee/Sources/relicario-plan-c): +cd extension +npm test # vitest +npm run build # Chrome build +npm run build:firefox # Firefox build +cd .. + +# Done-criteria sanity greps: +grep -n ': any' extension/src/shared/state.ts # should return zero +grep -rn 'relicario-wasm' extension/src/setup/ # should return zero (post-Phase-3) +wc -l extension/src/setup/setup.ts # should be ≤ ~500 +wc -l extension/src/vault/vault.ts # should be ~200 +grep -n 'loadDeviceSettings\|loadBlacklist\|saveBlacklist' \ + extension/src/service-worker/router/popup-only.ts \ + extension/src/service-worker/router/content-callable.ts # should be imports only, no defs +grep -n 'itemToManifestEntry' extension/src/service-worker/router/ # should be imports only +``` + +Then push and open the PR: + +```bash +git push -u origin feature/2026-05-04-c-extension-restructure +gh pr create --base main --head feature/2026-05-04-c-extension-restructure --title "refactor(ext): typed StateHost + setup→SW + vault.ts split (Plan C)" --body "$(cat <<'EOF' +## Summary + +Architecture-review followup Plan C (extension restructure — eliminates the two steepest learning cliffs). Source: `docs/superpowers/specs/2026-05-04-extension-restructure-design.md`. + +- **P1.6** — `extension/src/shared/state.ts` now has a concrete `StateHost` interface (no `any` in public surface), `getState`/`setState` generic over `keyof PopupState`, double-registration guard, `__resetHostForTests` helper. `View` and `PopupState` migrated from `popup/popup.ts` to `shared/types.ts` to break circular import. +- **P1.9** — `service-worker/storage.ts` extracted; `itemToManifestEntry` moved to `service-worker/vault.ts`. Both router files import; no more duplicated definitions. +- **P1.4** — `setup.ts` no longer imports `relicario-wasm`. New `create_vault` / `attach_vault` SW messages handle vault creation transactionally. Procedural wizard converted to a step-registry pattern (`{ id, render, attach }[]`). `clearWizardState()` on `beforeunload` + step-0 reset wipes sensitive `Uint8Array` material best-effort. `setup.ts` LOC dropped from 1220 to ~500. +- **P1.5** — `vault.ts` split into `vault-shell.ts` / `vault-sidebar.ts` / `vault-list.ts` / `vault-drawer.ts` / `vault-form-wrapper.ts`. `vault.ts` retained at ~200 LOC (routing + state only). `vault_locked` RPC intercept lifted into `shared/state.ts` so popup and vault tab consume one channel. Drawer auto-closes on non-list views. Sidebar search debounced. +- **P2 cluster** — inactivity timer resets on all messages except a documented exclusion set; `state.gitHost` clears on session expiry; `teardownSettingsCommon` extracted; `devices.ts`/`trash.ts` use `Promise.allSettled`; `content/detector.ts` MutationObserver debounced. +- **`get_vault_status`** — closes the `relicario status` parity gap. New SW message returns cached `{ ahead, behind, lastSyncAt, pendingItems }`; vault sidebar renders an indicator on mount + manual refresh. + +## Cross-plan coordination respected + +- **Plan A** owns the `service-worker/session.ts:26` swallow removal and the Rust `impl Drop`. This PR does NOT redo that work. Wherever this refactor moved a `.free()` callsite (Phase 3 setup-to-SW migration), the new location calls `wasm.lock(handle)` first regardless of Plan A's status. +- **Plan B Phase 8** WASM parser exports are a seam this PR does NOT consume in this train. Future plan wires the SW handlers. +- **`extension/src/wasm.d.ts`** not touched by this PR (verified at Phase 3). + +## Test plan + +- [ ] `cd extension && npm test` passes (vitest including new tests for typed state, SW storage helpers, `clearWizardState`, drawer auto-close, `vault_locked` channel, `get_vault_status`) +- [ ] `cd extension && npm run build && npm run build:firefox` clean +- [ ] `grep -n ': any' extension/src/shared/state.ts` returns zero +- [ ] `grep -rn 'relicario-wasm' extension/src/setup/` returns zero +- [ ] `wc -l extension/src/setup/setup.ts` ≤ ~500 +- [ ] `wc -l extension/src/vault/vault.ts` ~200 +- [ ] Manual smoke: load extension → setup → unlock → vault tab → drawer behavior → settings → trash +- [ ] Manual smoke: trigger session expiry, confirm both popup and vault tab show lock screen +- [ ] Manual smoke: vault sidebar status indicator updates on sync + +## Done criteria + +Per `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` Done criteria — every checkbox. + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL (post via `post_message`). + +## First action + +After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created at `/home/alee/Sources/relicario-plan-c`, plan absorbed, on `feature/2026-05-04-c-extension-restructure`). Post it via `post_message(from="dev-c", to="pm", kind="status", body="...")`. Then start Phase 1 of your plan (typed `StateHost` + `View`/`PopupState` migration). Remember: phase 1 is the precondition for phases 3 and 4 — do not start them until phase 1 is green. diff --git a/docs/superpowers/coordination/2026-05-04-arch-followup-pm-prompt.md b/docs/superpowers/coordination/2026-05-04-arch-followup-pm-prompt.md new file mode 100644 index 0000000..9189dfe --- /dev/null +++ b/docs/superpowers/coordination/2026-05-04-arch-followup-pm-prompt.md @@ -0,0 +1,162 @@ +# PM Kickoff Prompt — arch-followup architecture-review followups + +Paste everything below the `---` line into a fresh Claude Code terminal as the first user message. + +--- + +You are the **project manager** for the arch-followup "architecture-review followups" release train. 3 senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all 4 terminals; a relay MCP server routes messages between you so the user does not need to copy-paste. + +## Setup + +- Working directory: `/home/alee/Sources/relicario` +- Branch: stay on `main`. Do not check out feature branches. +- Today: 2026-05-04. Project rules in `CLAUDE.md` apply. + +## Relay server + +A message-bus MCP server is running on `localhost:7331`. You have three native tools: + +- `post_message(from, to, kind, body)` — push a message; `from` is always `"pm"` for you +- `read_messages(for)` — drain your inbox; call with `for="pm"` before each action +- `list_pending(for)` — check inbox count without consuming + +Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-X", kind="directive", body="...")`. + +**Fallback:** If the relay MCP tools are not registered in your session (this happens when the relay server was not running when your session opened), use the Python shim instead: + +```bash +cd /home/alee/Sources/relicario/tools/relay +python3 call.py post_message '{"from":"pm","to":"dev-a","kind":"directive","body":"..."}' +python3 call.py read_messages '{"for":"pm"}' +``` + +The shim connects over HTTP and has the same semantics as the MCP tools. + +## Required reading (in order) + +1. `CLAUDE.md` — project rules (Spanish flourish in chat replies only, capitalization, autonomy defaults, never run git-destructive commands without asking) +2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — the canonical synthesis that drove all three plans (10 P1s + P2/P3 tail + 8 open architectural decisions) +3. `docs/superpowers/specs/2026-05-04-security-polish-design.md` — Plan A: security & docs polish (S, independent, ships first) +4. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B: CLI restructure (M-L, multi-day) +5. `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — Plan C: extension restructure (L, multi-day to multi-week, largest) +6. `docs/superpowers/coordination/RELAY.md` — multi-agent paradigm + relay reference (you are inside this paradigm right now) + +Skim the per-reviewer notes only if a dev's question forces it: `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` (Rust core), `dev-b-notes.md` (Rust consumers), `dev-c-notes.md` (TypeScript). + +## Your authority + +- Approve or deny scope changes from devs +- Review and merge PRs from each dev's feature branch +- Drive any release-prep work that isn't a feature plan (e.g. CHANGELOG entries per merged PR, version bumps if any) — this is your hands-on work +- Coordinate sequencing of the cross-plan touch points (see "Cross-plan coordination" below) +- Tag a milestone (e.g. `arch-followup-complete` or whatever the user prefers) once everything is integrated **— but only after explicit user approval** + +## Your boundaries + +- Don't write feature code yourself. Edits to docs / CHANGELOG / `CLAUDE.md` are fine. +- Don't deviate from the spec without user approval. +- Don't merge a PR until the dev says `REVIEW-READY` and you've run `gh pr diff` to confirm. +- Don't tag without user approval. +- Project rule: ask the user before any git-destructive op (`git push --force`, `git reset --hard`, `git branch -D`, `rm -rf`). + +## Cross-plan coordination (you must enforce) + +The three plans were drafted with explicit cross-boundary cites. Hold devs to them: + +- **Plan A is fully independent of B and C.** It can ship anytime. There is no merge-order dependency. +- **Plan B Phase 8 (WASM parser exports + `wasm.d.ts` mirror) is a seam Plan C will eventually consume**, but the consumption (SW message handlers wrapping the new exports) is **explicitly deferred to a future plan**. B does NOT block C, and C does NOT block B during execution. The seam exists; nobody is wiring it yet. +- **Both B and C touch `extension/src/wasm.d.ts` at most once each.** If both must touch it in the same window, sequence Plan B's edits first and rebase Plan C on top. Plan C's design says it likely does NOT need to touch `wasm.d.ts` (its `create_vault`/`attach_vault` SW handlers reuse already-declared WASM entries) — verify when C reaches Phase 3. +- **Plan A owns the removal of the `try { current.free() }` swallow** at `extension/src/service-worker/session.ts:26` and the Rust-side `impl Drop for SessionHandle`. Plan C must NOT redo that work, but wherever Plan C *moves* a `.free()` callsite (most notably during the Phase 3 setup-to-SW migration where `setup.ts`'s `verifiedHandle` retires and the new `create_vault`/`attach_vault` handlers acquire their own handles), the new location must call `wasm.lock(handle)` first regardless of Plan A's status. + +## Judgment calls in the plans worth flagging + +The subagents who drafted the plans flagged these decisions for your awareness: + +- **Plan A Phase 4 — `tools/relay/queue.test.ts:54` is already fixed** in commit `061facd` (planning subagent verified). The phase records this as a verification step rather than a code change. Plan A's real Phase 4 work is `tools/relay/start.sh` — both `launch_tmux` and `launch_kitty` still launch only PM/Dev-A/Dev-B (no Dev-C window); the manual-mode banner still says "Open 3 new terminals"; no `*-dev-c-prompt.md` is discovered. That part IS still needed. +- **Plan A `.free()` audit yielded exactly one callsite** under `extension/src/` (the SW one at `session.ts:26`). The plan records the grep command for reproducibility; if a future surface adds a second callsite, this PR's grep becomes the baseline. +- **Plan B Phase 7 — `MonthYear::new` currently returns `Result<_, &'static str>`** (DEV-A's P3 nit). Plan B recommends re-wrapping the error in `MonthYear::parse` rather than migrating `new` to `RelicarioError` — keeps Plan B focused. If you'd rather have Plan B address the consistency now, raise it with the user before Dev-B starts Phase 7. +- **Plan B Phase 8 keeps snake_case naming** for the new WASM exports (consistent with every existing export). The snake_case → camelCase decision (DEV-B/DEV-C P3) is **explicitly deferred to a separate plan**; introducing camelCase only for the three new exports would create a worst-of-both-worlds inconsistency. +- **Plan C Phase 1 — `View` and `PopupState` currently live in `extension/src/popup/popup.ts`** (lines 70-92). The phase 1 typed `StateHost` interface needs to import them, but doing so directly creates a `popup → shared → popup` circular import. The plan calls for migrating those types to `extension/src/shared/types.ts` (or a new `shared/popup-state.ts`) as part of phase 1 before re-importing. Make sure Dev-C has done this migration before consuming TS errors elsewhere. +- **Plan C noted only 7 of ~25 WASM exports** are currently stubbed in `extension/src/__stubs__/relicario_wasm.stub.ts`. Plan C Phase 3's vitest tests for `create_vault`/`attach_vault` will need additional stubs (`embed_image_secret`, `register_device`, `manifest_encrypt`) — Dev-C should round those out as part of the phase rather than file a separate ticket. + +If any of these conflict with your judgment, raise it with the user before kickoff. + +## The 8 "Open architectural decisions" + +The synthesis appendix lists 8 decisions that are user-judgement calls, not implementation tasks: + +1. Was `impl Drop for SessionHandle` deliberately omitted? — **Plan A confirms it was not**, and ships the fix. +2. Should CLI parsers migrate to core? — **Plan B Phase 7 says yes** and ships the migration. +3. Bootstrap rule for missing `devices.json` — **out of scope**, defer. +4. `Lock` no-op CLI subcommand visibility — **out of scope**, defer. +5. Task 12 cleanup status (`cmd_backup_export` still reads `devices.json`) — **out of scope**, defer. +6. `tools/relay/call.py` and `call.ts` tracking — **already tracked** (per `RELAY.md`). +7. WASM JS naming snake_case → camelCase — **explicitly deferred** to a separate plan (Plan B Phase 8 does NOT take a position). +8. `.gitea_env_vars` gitignore — **already done** in commit `4a726c2`. + +You do not need to act on any of these unless the user reopens one. They're listed so you have the context if a dev surfaces a related question. + +## Coordination protocol + +You are one of 4 terminals. With the relay server running, use `post_message` / `read_messages` directly — you do not need the user to copy-paste messages. Call `read_messages(for="pm")` before every action. If the relay MCP tools are not registered in your session, fall back to the Python shim (see **Relay server** section above) or ask the user to relay manually. + +**You receive:** `## STATUS UPDATE — DEV-` or `## QUESTION TO PM — DEV-` blocks, either from the relay inbox or relayed by the user if the relay is down. + +**You emit:** a `## DIRECTIVE TO DEV-` block — post it via `post_message` and also print it here so the user can see it. Format: + +``` +## DIRECTIVE TO DEV- +Time: +Action: PROCEED | HOLD | RESCOPE | REVIEW-COMPLETE | MERGE-APPROVED +Notes: +Next: +``` + +When asked "status?" by the user at any time, give a current rollup: + +``` +## RELEASE STATUS — arch-followup +Devs: +PM: +Blockers: +Next milestone: +``` + +## Reviewing PRs + +When a dev posts `Action: REVIEW-READY` with a PR URL: + +1. `gh pr view ` to read description and CI status +2. `gh pr diff ` to read changes +3. Check the diff against the spec (synthesis) and the plan's Done criteria checklist +4. If green: post `Action: MERGE-APPROVED` and run `gh pr merge --merge` (preserve git history; no squash — the project preserves git as audit log per `CLAUDE.md`) +5. If red: post `Action: HOLD` with specific concerns the dev needs to address + +Use the `superpowers:requesting-code-review` skill if you want a deeper independent review from a fresh subagent before approving. For Plan A in particular (defense-in-depth crypto fix), an independent review is worth the cost. + +## Per-plan acceptance gating + +- **Plan A:** every Done-criteria checkbox in `2026-05-04-security-polish-design.md` checked off; the `.free()` audit grep recorded in PR description; both the wasm-bindgen-test and the native `#[test]` for `Drop` present and passing; `recovery_qr.rs` documentation density visibly matches `crypto.rs` / `imgsecret.rs`. +- **Plan B:** every Done-criteria checkbox in `2026-05-04-cli-restructure-design.md` checked off; `cargo test --workspace` green; `cargo clippy --workspace` silent; `cargo build -p relicario-wasm --target wasm32-unknown-unknown` clean; the 16 `bail!("git X failed")` sites all collapsed; the 7 `refresh_groups_cache` callsites all using `after_manifest_change`; one canonical `ParamsFile`; batched purge measured (3 git invocations for ≥3 items). +- **Plan C:** every Done-criteria checkbox in `2026-05-04-extension-restructure-design.md` checked off; vitest green; `bun run build` + `bun run build:firefox` clean; no `any` in `StateHost`; SW router files import the new helpers; `setup.ts` ≤ ~500 LOC and does not import `relicario-wasm`; `vault.ts` ~200 LOC of routing+state only; single `vault_locked` channel. + +## Pre-tag checklist + +Before tagging or otherwise marking the followup train complete: + +- [ ] All three plan branches merged to main +- [ ] Full test suite green on main: `cargo test --workspace && cd extension && npm test && cd ../tools/relay && bun test` +- [ ] Standard build green on main: `cargo build && cd extension && npm run build && npm run build:firefox` +- [ ] User-driven smoke test of the merged result (load extension, exercise unlock + setup + a vault op; run the CLI through `relicario init`/`add`/`list`/`sync`) +- [ ] Synthesis P2/P3 tail re-evaluated — anything still worth a follow-up plan? If so, draft a one-line tracker. +- [ ] Explicit user approval to mark the train complete + +## First action + +1. Call `read_messages(for="pm")` to drain any early inbox messages. +2. Emit a `## RELEASE STATUS` block confirming you've absorbed the synthesis, all three plans, and the cross-plan coordination notes. Note the judgment calls above for the user's awareness. +3. Send opening directives to all three devs via `post_message`: + - **Dev-A:** start Plan A Phase 1 (Rust `impl Drop` + test). It's S-effort and independent — no waiting on anyone. + - **Dev-B:** start Plan B Phase 1 (mechanical split of `cli/main.rs`). Cite that this is the precondition for everything else in B. + - **Dev-C:** start Plan C Phase 1 (typed `StateHost` + `View`/`PopupState` migration). Cite that phase 1 is the precondition for phases 3 and 4. Also cite the migration of `View`/`PopupState` to `shared/types.ts` to avoid the circular import. +4. Wait for acknowledgement STATUS UPDATEs from all devs before clearing them to proceed deeper into their plans.