[suprie]

Summary

Complete prd-role-foundations Phase 5 with focused Rust coverage for charter migration, injection routing, and per-phase assignment, then implement the prd-agent-handoff Phase 1 store model and executor-side artifact emission. Handoffs are opt-in per phase, so plans without a configured topic keep executing unchanged.

What changed

• Added role_foundations_tests.rs: legacy config/plan loading from disk, shared-resolver charter routing, and assignment + handoff persistence with its batching consequence.
• Defined the handoff store contract in handoff.rs: artifact record (topic, author role, phase, type, created, summary, cites, durable path), capped load/save helpers, duplicate-topic refusal, and a separate plain-JSON ledger.json graph of nodes and citation links.
• Added handoff_topic to RunPhase and an optional handoff_topics argument to create_run_plan, validated as unique kebab-case slugs across the plan.
• Wired the run executor to instruct handoff-opted phases where to write their artifact, then validate, normalize, and copy it into .loopdeck/handoffs/ on a passing verdict; a missing/mismatched artifact parks the batch.
• Executor normalizes producer bodies into the contract's schema headings (alias canonicalization, unknown-heading demotion, generated ## Summary) instead of trusting the producer.
• Exposed handoff_topic and PhaseHandoffTopic on the TypeScript IPC surface.

PRD

• docs/epics/role-based-orchestration/prd-role-foundations.md (Phase 5 — Tests/verification)
• docs/epics/role-based-orchestration/prd-agent-handoff.md (Phase 1 — Handoff store)

Decisions

• 2026-10-28 — Opt-in handoff emission: a phase emits an artifact only when a topic is configured, preserving legacy plan execution (ADR-3); a configured phase that cannot produce its artifact parks the batch.
• 2026-10-28 — JSON ledger beside Markdown artifacts: artifacts stay at .loopdeck/handoffs/<topic>.md while graph nodes/links persist separately in ledger.json, per the run's clarification.
• 2026-10-28 — Executor owns schema headings: producer heading drift is normalized mechanically rather than rejected, so schema compliance does not depend on agent obedience.

Test plan

• cargo test — 739 passed, 0 failed, 9 ignored
• npx tsc --noEmit
• cargo clippy --all-targets — changed files clean; remaining warnings are pre-existing in untouched files
• Manual: queue a plan with a handoff_topic, let a phase pass, and confirm .loopdeck/handoffs/<topic>.md plus ledger.json

Verify Verdict

PRD Verification — prd-role-foundations.md + prd-agent-handoff.md (Phase 1)

Scope: all three P0 goals of prd-role-foundations (every phase is complete; Phase 5 adds this run's verification suite), plus the two Phase-1 loop criteria of prd-agent-handoff that this run was queued to implement. prd-agent-handoff Phase 2-4 goals (downstream injection, Waiting, report attribution, its own test phase) are not part of this run and are not evaluated here.

Verdict: PASS

#	Criterion	Status	Evidence
1	Role charter fields (persona prompt, allowed skills, output contract) on roster entries, with migration so existing configs stay valid	PASS	src-tauri/src/config.rs:56 — pub struct RoleCharter { persona_prompt, allowed_skills, output_contract, rules }; config.rs:232-235 flattens it into NamedAgentConfig; src-tauri/src/role_foundations_tests.rs:51 loads a legacy config.yaml from disk, asserts an empty charter, and resaves with no charter key
2	Charter injection into spawned sessions across interactive, run-queue, and multi-agent paths, harness-neutral (Claude and Codex)	PASS	src-tauri/src/claude_session.rs:353 — cmd.args(["--append-system-prompt", &rendered]); src-tauri/src/codex_session.rs:405-408 prepends the same render to the first turn; src-tauri/src/charter_injection_tests.rs:225,240,256,304 capture argv/stdin for all three spawn paths plus Codex
3	Per-phase agent assignment in RunPlan phases, executed by the run queue	PASS	src-tauri/src/runplan.rs:162 — pub assigned_agent_id: Option<String>; src-tauri/src/commands/run_queue.rs:1831-1832 resolves the batch's assigned agent before spawn; run_queue.rs:1327-1330 splits batches on a staffing change; src-tauri/src/role_assignment_tests.rs:79 runs the dev-builds/QA-verifies demo
4	Handoff store layout + artifact record (author role, phase, type, path) with load/save helpers	PASS	src-tauri/src/handoff.rs:65 — ArtifactRecord { artifact, author_role, phase, artifact_type, created, summary, cites, path }; handoff.rs:109 store dir .loopdeck/handoffs; handoff.rs:118,128 ledger load/save; handoff.rs:203 save_artifact validates caps + refuses replacement; handoff.rs:602,631 round-trip tests
5	Executor emits each finished phase's contract artifact into the store	PASS	src-tauri/src/runplan.rs:173 — pub handoff_topic: Option<String>; run_queue.rs:498 validates the configured slug; run_queue.rs:292 emit_phase_artifacts copies each opted-in phase; run_queue.rs:2048 invokes it on a passing verdict and parks on failure; handoff.rs:248,319 copy + mechanical heading normalization; handoff.rs:727 drift-normalization test

Non-goals audit

• prd-role-foundations lists "Any handoff store or inter-agent artifacts" as a non-goal. The handoff store in this diff is intentional cross-PRD scope authorized by the co-queued prd-agent-handoff Phase 1 loops (its own non-goals), not role-foundations creep.
• prd-agent-handoff non-goals: no message bus/socket (files + plain JSON only), no parallel execution, no arbitration, no interactive-session writes — no scope creep detected.

Roll-up: PASS — 0 FAIL, 0 PARTIAL, 5 PASS.

Run metadata

• Phases:
  • role-foundations/tests — "Add Rust tests for charter migration, injection routing, and assignment; pass prd-verifier against this PRD" (role-based-orchestration / prd-role-foundations / Phase 5 — Tests/verification)
  • agent-handoff/store-model — "Define the .loopdeck handoff store layout and artifact record (author role, phase, type, path) with load/save helpers" (role-based-orchestration / prd-agent-handoff / Phase 1 — Handoff store)
  • agent-handoff/artifact-write — "Emit each finished phase's contract artifact into the store from the run executor" (role-based-orchestration / prd-agent-handoff / Phase 1 — Handoff store)
• Budgets: 1500000 tokens total · 16200s wall-clock cap for this turn · 28800s total-run wall-clock cap

🤖 Generated with Claude Code