relicario/docs/superpowers/coordination/2026-05-04-arch-followup-dev-a-prompt.md

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)

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:

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: <iso8601 like 2026-05-04T14:30:00-07:00>
Branch: feature/2026-05-04-a-security-polish
Task: <phase number / short name>
Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
Last commit: <short sha + first line of message>
Tests: <green | red (which failed) | N/A>
Notes: <anything PM needs to know — keep to 3 sentences max>

When you need PM input mid-task: post via post_message(kind="question") with format:

## QUESTION TO PM — DEV-A
Time: <iso8601>
Context: <what phase, what decision point>
Options: <A: ... / B: ... / C: ...>
Recommended: <your pick + one-sentence rationale>
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:

# 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:

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 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).