relicario/docs/superpowers/coordination/architecture-review-followup-dev-a-prompt.md

# Dev A Kickoff Prompt — Architecture Review Followup, Stream A (Security & Docs Polish)

> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement the plan task-by-task once it lands.

Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.

---

You are a **senior developer** owning Stream A for the Relicario architecture-review-followup work. Stream A is the small, security-flavored quick-win PR that goes first: SessionHandle Drop semantics, the matching JS-side audit, recovery_qr.rs documentation density, and the relay launcher fix for the dev-c fourth window. Goal is **under-a-day, all-S effort, ships first**.

A PM in another terminal coordinates you with two other senior devs. With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. **Your plan does not exist yet.** The PM is drafting it as their first action. Set up your worktree, post acknowledgement, and wait for the PM's `PROCEED` directive containing the plan path before starting Task 1.

## Setup (do this first)

```bash
cd /home/alee/Sources/relicario
git fetch
git worktree add /home/alee/Sources/relicario.arch-followup-stream-a -b feature/arch-followup-stream-a-security-polish
cd /home/alee/Sources/relicario.arch-followup-stream-a
pwd  # should print /home/alee/Sources/relicario.arch-followup-stream-a
```

**Note on `git pull`:** main has uncommitted polish changes from in-flight post-v0.5.1 work. The setup above branches from local main HEAD without pulling, which is intentional. If `git fetch` reveals new upstream commits, surface them to the PM before incorporating.

**ALL subsequent work happens in `/home/alee/Sources/relicario.arch-followup-stream-a`**. Every subagent prompt MUST begin with `cd /home/alee/Sources/relicario.arch-followup-stream-a` (project memory rule — without the force-cd, subagents may commit to main).

Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalize "Relicario", default to "yes"/recommended, never run git-destructive commands without asking).

## 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, the JS free-swallow fix, P1.7, P1.8 only**)
3. `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` — full DEV-A reviewer notes (Rust core; covers recovery_qr.rs context)
4. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — full DEV-B reviewer notes (covers SessionHandle context on the WASM side)
5. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — full DEV-C reviewer notes (covers the JS free-swallow + start.sh launcher context)
6. **Your plan (will land at):** `docs/superpowers/specs/2026-05-04-security-polish-design.md` — read once the PM directs you to PROCEED

## Execution mode

Use **superpowers:subagent-driven-development**. Fresh subagent per task, two-stage review between tasks. Every subagent prompt MUST start with:
```
cd /home/alee/Sources/relicario.arch-followup-stream-a
```
…before any other instruction. This is non-negotiable per project memory.

## Your scope and boundaries

**In scope:**
- P1.1 — `impl Drop for SessionHandle` in `crates/relicario-wasm/src/lib.rs` (and `session.rs`); `wasm-bindgen-test` for construct → drop → confirm `SESSIONS` registry empty; audit every `.free()` callsite under `extension/src/` to confirm `wasm.lock(handle)` happens first regardless
- JS partner fix at `extension/src/service-worker/session.ts:26` — remove the `try { current.free() }` swallow; let exceptions propagate or log + counter
- P1.7 — `crates/relicario-core/src/recovery_qr.rs` documentation pass to match `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs` density
- P1.8 — `tools/relay/start.sh:80` launcher fix for the dev-c fourth window (the queue.test.ts assertion is already fixed in `061facd`; only the launcher line remains)

**Out of scope (other DEVs own these):**
- P1.2, P1.3, P1.10 + the in-scope CLI P2s — DEV-B (Stream B)
- P1.4, P1.5, P1.6, P1.9 + the in-scope extension P2s — DEV-C (Stream C)
- Any other P2/P3 not listed in your plan
- The 8 "Open architectural decisions" at the bottom of the synthesis — those are user-judgement calls

If you trip over an out-of-scope issue or a new bug while doing your work, file a `## QUESTION TO PM` block and keep moving.

**Hard rules:**
- **P1.1 is defense-in-depth crypto.** The `wasm-bindgen-test` covering construct → drop → registry-empty is a required acceptance gate. Do not skip or weaken it.
- **The `.free()` callsite audit is part of P1.1.** Every callsite under `extension/src/` must be checked to confirm `wasm.lock(handle)` is called before `.free()`. Document the audit results in the PR.
- **Do not remove the JS free-swallow before `impl Drop` lands.** The order matters: Rust fix first (so `.free()` becomes meaningful cleanup), JS swallow removal second (so failures surface).
- **`recovery_qr.rs` docs must match the existing core standard.** Multi-paragraph module-level `//!` rationale, ASCII diagram of the 109-byte layout, doc-comments on the four public functions, comment or `const` for the `production_params()` divergence. Read `crypto.rs` and `backup.rs` first to absorb the tone.
- **Test-only Argon2id params stay fast** (m=256, t=1, p=1) per project convention.
- Synthetic JPEG fixtures only — no binary blobs in the test suite (project rule).
- 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.

## 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"}'
```

## Coordination protocol

You are one of four terminals. Before starting each task, call `read_messages(for="dev-a")` to drain your inbox.

When posting a status update, call `post_message(from="dev-a", to="pm", kind="status", body="...")` with the body:

```
## STATUS UPDATE — DEV-A
Time: <iso8601 like 2026-05-04T14:30:00-07:00>
Branch: feature/arch-followup-stream-a-security-polish
Task: <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:**
```
## QUESTION TO PM — DEV-A
Time: <iso8601>
Context: <what task, what decision point>
Options: <A: ... / B: ... / C: ...>
Recommended: <your pick + one-sentence rationale>
Blocker: yes | no
```

**You'll receive:** `## DIRECTIVE TO DEV-A` blocks from the PM. The first one will say `Action: PROCEED` with the plan path once the PM has drafted it. Acknowledge and start Task 1.

## Authority within the plan

You don't need PM permission to:
- Execute task-to-task per the plan once you have it
- Make implementation decisions consistent with the plan and synthesis
- Write tests, refactor your own code, fix bugs you introduce
- Push commits to your feature branch

You **do** escalate to PM when:
- A scope question outside the plan
- A test you can't make green after honest debugging (don't fudge — debug)
- A discovered bug not in your plan
- Anything destructive (per CLAUDE.md)
- Before opening the PR for review

## Final steps before REVIEW-READY

Run the project's full validation:

```bash
cd /home/alee/Sources/relicario.arch-followup-stream-a
cargo test
cargo build -p relicario-wasm --target wasm32-unknown-unknown
cd extension && bun run test && bun run build && cd ..
cd tools/relay && bun test && cd ../..
```

All four must be green. The wasm-bindgen-test for SessionHandle Drop is the headline acceptance.

Then push and open the PR:

```bash
git push -u origin feature/arch-followup-stream-a-security-polish
gh pr create --base main --head feature/arch-followup-stream-a-security-polish \
  --title "fix(security/docs): SessionHandle Drop + free-swallow + recovery_qr docs + dev-c launcher (Stream A)" \
  --body "$(cat <<'EOF'
## Summary

Stream A of the architecture-review-followup. Small security-flavored polish PR addressing four findings from the 2026-05-04 audit:

- **P1.1** — `impl Drop for SessionHandle` so `.free()` becomes a real cleanup safety net (Rust fix); `wasm-bindgen-test` for construct → drop → registry empty; audit of every `.free()` callsite under `extension/src/`
- **JS free-swallow** — removed `try { current.free() }` at `extension/src/service-worker/session.ts:26` so failures propagate
- **P1.7** — `crates/relicario-core/src/recovery_qr.rs` brought up to the documentation density of `crypto.rs` / `backup.rs` / `tar_safe.rs`
- **P1.8** — `tools/relay/start.sh:80` launcher fix for the dev-c fourth window

## Synthesis references

- `docs/superpowers/reviews/2026-05-04-architecture-review.md` — P1.1, P1.7, P1.8
- `docs/superpowers/specs/2026-05-04-security-polish-design.md` — Plan A

## Test plan

- [x] `cargo test` green
- [x] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` green
- [x] `cd extension && bun run test && bun run build` green
- [x] `cd tools/relay && bun test` green (4-pass after dev-c assertion fix in 061facd)
- [x] New wasm-bindgen-test: SessionHandle construct → drop → SESSIONS registry empty
- [x] `.free()` callsite audit under `extension/src/` — every site preceded by `wasm.lock(handle)`
- [x] `start.sh` opens 4 windows including dev-c
EOF
)"
```

Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.

## First action

After reading the required inputs and setting up the worktree:

1. Call `read_messages(for="dev-a")` to drain any early inbox messages.
2. Emit a `## STATUS UPDATE` confirming setup complete:
   ```
   ## STATUS UPDATE — DEV-A
   Time: <iso8601>
   Branch: feature/arch-followup-stream-a-security-polish
   Task: setup
   Status: DONE
   Last commit: <main HEAD sha + first line>
   Tests: N/A
   Notes: Worktree at /home/alee/Sources/relicario.arch-followup-stream-a. Synthesis + reviewer notes absorbed. Awaiting Plan A at docs/superpowers/specs/2026-05-04-security-polish-design.md.
   ```
3. **Wait** for the PM's `## DIRECTIVE TO DEV-A` with `Action: PROCEED` and the plan path.
4. Read the plan, then start Task 1 using `superpowers:subagent-driven-development`.