docs(phase3-step8): TDD implementation plan — Plan + Permission Contract

[AVADSA25]

Summary

TDD implementation plan for Phase 3 Step 8 — Plan + Permission Contract. Generated via the superpowers:writing-plans skill from the approved blueprint (docs/PHASE3-BLUEPRINT.md §2). 19 tasks, 89 atomic TDD steps, 2364 lines.

This PR is the PLAN, not the implementation. Once approved, execution happens in a follow-up PR (feat/phase3-step8-implementation).

What Step 8 builds

Drop-a-project planning: user describes a project → Qwen-3.6 drafts structured plan with permission manifest → user approves in PWA → grants persisted with plan_hash for Step 9 tamper detection. No execution yet — Step 9 picks that up.

Plan structure

Task	Purpose
1	Audit event constants (6 events)
2	Plan/Checkpoint/PermissionManifest dataclasses
3	Plan-hash (Q13 tamper detection)
4	Atomic R/W (tmp+rename pattern)
5	Skill-registry validation
6	Qwen-3.6 plan drafter (Q1: local-only)
7	Vague-description clarifying loop (Q3)
8	Global allowlist tier (Q4)
9	State machine (status transitions)
10	create_agent orchestrator
11	approve / reject / revise functions
12	9 PWA endpoints (routes/agents.py)
13	Approve/reject integration tests
14	Global grants endpoints test
15	Auto-approve via global allowlist
16	Pre-approval re-validation
17	End-to-end integration test
18	AGENTS.md documentation update
19	Final verification + push + PR

Estimated implementation outputs

• 1 new module: codec_agent_plan.py (~500 LOC)
• 1 new router: routes/agents.py (~200 LOC, 9 endpoints)
• 25 new passing tests (tests/test_agent_plan.py, ~700 LOC)
• 6 new audit event constants in codec_audit.py
• 1 mount edit in codec_dashboard.py
• AGENTS.md §X.X sub-section + §6 table + §10 don't-touch list

Quality discipline (from writing-plans skill)

• Every step has exact file paths, exact code, exact pytest commands
• Every test has a complete body (no "similar to Task N")
• Every assertion is concrete
• TDD pattern strictly followed: write failing test → run-fail → implement → run-pass → commit
• No placeholders / TBDs / TODOs

Test plan

• No code changes — docs-only PR
• User reviews plan structure + task decomposition
• After approval: execute the plan via superpowers:subagent-driven-development or superpowers:executing-plans

Sequencing

This PR (Step 8 plan) → user merges → execution PR ships → Step 8 sign-off → Step 9 plan → Step 9 execution → Step 9 sign-off → Step 10 plan → Step 10 execution → Phase 3 closeout.

Mirrors the Phase 1+2 cadence.

🤖 Generated with Claude Code