docs(phase3): blueprint — drop-a-project autonomy (Steps 8/9/10)

[AVADSA25]

Summary

Phase 3 design doc — drop-a-project autonomy with computer use, plan-and-grant safety model, proactive messaging. Three steps, sequential, sign-off-gated, kill-switched. Mirrors Phase 1+2 cadence.

This is the blueprint (analogous to PHASE2-BLUEPRINT.md). No code, no implementation. Sets the design before writing implementation plans for each step.

Design produced via brainstorming session 2026-05-03

15 questions resolved with the user. Notable choices captured in §8:

• Q1 Qwen-3.6 ALWAYS (no Gemini Flash fallback — user explicit "local always best")
• Q4 Global allowlist tier (~/.codec/agent_global_grants.json) for repeat permissions across agents
• Q5 Resume from last atomic checkpoint after PM2 restart (worst case: one op re-fires; safe via idempotency + strict-consent for destructive)
• Q9 PWA-only notifications via existing notifications.json (no macOS banner / iMessage / Telegram in v1)
• Q12 Proactive intelligence overlay deferred to Phase 3.5 (Step 10 already substantial)

Step breakdown

Step	Scope	New module / service
8	Plan + Permission Contract	codec_agent_plan.py, PWA approval flow, global allowlist tier, plan-hash tamper detection
9	Background Execution + Audit Envelope	codec_agent_runner.py + codec-agent-runner PM2 service, permission gate, 3-concurrent cap, resume-after-restart, heartbeat monitoring
10	Proactive Messaging + Project Mode UI	Agent → user message types, chat thread integration, mode dropdown, status pills, Projects sidebar tab, chat auto-escalation w/ silence

Reuses from Phase 1 + 2 (no rebuilds)

Step 1 audit envelope · Step 2 plugin hooks · Step 3 ask_user + strict-consent + step budget · Step 4 self-recursion guard · Step 5 observer · Step 7 shift_report. Each Phase 1+2 component is leveraged; nothing rebuilt.

Estimated Phase 3 contribution

• 1 new PM2 service (codec-agent-runner) + 1 modified (codec-heartbeat)
• ~14 new audit events
• +85 to +100 passing tests
• 3 PRs (one per step) + closeout doc

Each step deployable independently:

• Step 8 alone: draft + approve plans, no execution. Useful for refining planning UX.
• Step 8+9: end-to-end execution, results in audit log + notifications.json (no UI).
• Step 8+9+10: full feature.

Test plan

• No code changes — docs-only PR, no test impact
• User reviews PHASE3-BLUEPRINT.md, requests changes if needed
• After approval: invoke superpowers:writing-plans to generate per-step implementation plans

Out of scope (explicitly deferred)

• Proactive intelligence overlay → Phase 3.5
• OS-level sandbox (chroot/AppArmor) → Phase 4 only if needed
• Multi-channel notifications (macOS / iMessage / Telegram) → Phase 4 if requested
• Memory / context system overhaul → user said current is good enough
• Marketplace UX overhaul → user said already in place
• Total LLM cap per agent → per-checkpoint budget sufficient for v1
• Full Projects sidebar overhaul → small tab is enough; bigger UX deferred

🤖 Generated with Claude Code