{ "schema_version": "0.1", "artifact_type": "implementation_plan", "canonical": true, "artifact_id": "IMP-016", "agent_summary": { "title": "Host-specific multi-session Reason Guard parity", "status": "complete", "summary": "Add bounded per-host ledgers, durable session history, safe legacy migration, and an offline Claude visible-assistant history adapter while retaining one deterministic Reason Guard kernel.", "last_reviewed_at": "2026-07-25", "load_notes": "The user explicitly authorized implementation through a goal and prohibited live Claude testing until limits are available after 13:00. Existing old Claude transcripts may be used offline through the allowlisted parser." }, "source_ids": [ "REQ-176", "DBR-002", "PRD-011", "ARCH-011", "WFR-445" ], "approval_gate": { "status": "approved", "implementation_authorized": true, "approved_at": "2026-07-25", "approved_by": "user" }, "scope": { "included": [ "Claude, Codex, and OpenCode local host ledgers", "Bounded per-session retention and active-session projection", "Trusted Claude assistant/text-only history ingestion", "Consistent live, recent-X, and full history semantics", "Legacy single-report migration", "Status, UI, template, installer, docs, wiki, and release parity", "Provider, Desktop/CLI surface, latest model, effort level, and session identity as separate bounded fields", "Offline old-Claude-session reproduction without launching Claude" ], "excluded": [ "Live Claude process or API execution before the user permits it", "Thinking blocks, signatures, prompts, raw transcripts, attachments, or tool payload persistence", "Models, embeddings, RAG, new services, daemons, GPUs, or network calls", "Edits to downstream repositories" ] }, "assumptions": [ "Claude project transcripts store visible assistant output as assistant records with message.role=assistant and content blocks of type=text.", "Codex visible summaries retain the existing response_item reasoning summary_text contract.", "OpenCode may lack a trusted transcript history source, but its host and session state can still be isolated and retained honestly.", "The existing state lock can protect host-ledger migration and writes without another service." ], "phases": [ { "id": "IMP-PHASE-048", "title": "Host ledgers, offline Claude backfill, and release", "complexity": "large", "confidence": "high", "risk": "high", "tasks": [ { "id": "IMP-TASK-117", "summary": "RED: extend existing Reason Guard tests to prove host-specific report selection, multi-session retention, bounded eviction, cross-host isolation, safe legacy migration, and Claude assistant/text-only live/recent/full backfill with privacy, replay, torn-tail, source-integrity, and concurrency coverage. GREEN: add the smallest host-ledger envelope and Claude adapter around the existing session-state kernel.", "status": "complete", "complexity": "large", "confidence": "high", "risk": "high", "requirement_ids": [ "REQ-176", "PRD-REQ-094", "PRD-REQ-095", "PRD-REQ-096" ], "architecture_ids": [ "ARCH-COMP-070", "ARCH-COMP-071", "ARCH-IF-061", "ARCH-DEC-061" ], "validation_ids": [ "IMP-VAL-103" ], "files": [ ".prd_plugin/hooks/prd_reason_guard.py", "tests/test_reason_guard.py", "tests/test_hook_dispatcher.py" ], "red_command": "python -m unittest tests.test_reason_guard tests.test_hook_dispatcher -q", "green_command": "python -m unittest tests.test_reason_guard tests.test_hook_dispatcher -q", "broader_verification": "python -m unittest tests.test_reason_guard tests.test_hook_dispatcher tests.test_reason_guard_benchmark -q", "expected_updates": [ "Focused red and green output", "Offline historical-Claude measurement", "EV-* behavior/privacy evidence" ] }, { "id": "IMP-TASK-118", "summary": "Fold provider/surface/session history through status, UI, downstream skeleton, installer coverage, documentation, wiki, traceability, versioning, and release metadata; run focused, benchmark, full-suite, workflow, state, installer, release, code-review, and repeated CHML verification without live Claude; ship only when gate-green.", "status": "complete", "complexity": "medium", "confidence": "high", "risk": "medium", "requirement_ids": [ "REQ-176", "PRD-REQ-092", "PRD-REQ-093", "PRD-REQ-096" ], "architecture_ids": [ "ARCH-COMP-069", "ARCH-COMP-070", "ARCH-IF-059", "ARCH-IF-061" ], "validation_ids": [ "IMP-VAL-104" ], "files": [ "templates/repo-skeleton/.prd_plugin/hooks/prd_reason_guard.py", "scripts/prd_status.py", "scripts/prd_ui_export.py", "tests/test_prd_ui_export.py", "tests/test_tracking_commands.py", "tests/test_prd_install.py", "docs/REASONING-GUARD.md", "wiki/hooks/reasoning-guard.md", ".codex-plugin/plugin.json", ".opencode/plugin.json", ".claude-plugin/plugin.json", "package.json" ], "red_command": "python -m unittest tests.test_prd_ui_export tests.test_tracking_commands tests.test_prd_install -q", "green_command": "python -m unittest tests.test_reason_guard tests.test_hook_dispatcher tests.test_reason_guard_benchmark tests.test_prd_ui_export tests.test_tracking_commands tests.test_prd_install -q", "broader_verification": "python -m unittest discover -s tests -p \"test_*.py\"", "expected_updates": [ "EV-* review and verification evidence", "CHG-* implementation and release records", "REQ-176 implemented", "TRK-163 complete", "DBR-MERGE-002 promoted" ] }, { "id": "IMP-TASK-119", "summary": "RED: prove Codex originator/turn-context and Claude entrypoint/assistant metadata distinguish Desktop from CLI and retain latest model/effort, with explicit override and honest unknown behavior. GREEN: add bounded session-level surface, model, and effort fields and expose readable values in status, UI, docs, templates, and release evidence.", "status": "complete", "complexity": "small", "confidence": "high", "risk": "medium", "requirement_ids": [ "REQ-176", "PRD-REQ-097" ], "architecture_ids": [ "ARCH-COMP-070", "ARCH-IF-062", "ARCH-DEC-062" ], "validation_ids": [ "IMP-VAL-105" ], "files": [ ".prd_plugin/hooks/prd_reason_guard.py", "templates/repo-skeleton/.prd_plugin/hooks/prd_reason_guard.py", "scripts/prd_status.py", "scripts/prd_ui_export.py", ".opencode/plugins/prd-hooks.js", "templates/repo-skeleton/.opencode/plugins/prd-hooks.js", "tests/test_reason_guard.py", "tests/test_prd_ui_export.py", "tests/test_cross_host_hook_parity.py", "docs/REASONING-GUARD.md", "wiki/hooks/reasoning-guard.md" ], "red_command": "python -m unittest tests.test_reason_guard.ReasonGuardContractTests.test_codex_surface_distinguishes_desktop_cli_and_unknown tests.test_reason_guard.ReasonGuardContractTests.test_claude_surface_distinguishes_desktop_cli_and_explicit_override tests.test_reason_guard.ReasonGuardContractTests.test_opencode_surface_is_named_without_claiming_a_cli_or_desktop tests.test_prd_ui_export.SnapshotTests.test_reasoning_clearance_is_human_readable_in_snapshot_and_page -v", "green_command": "python -m unittest tests.test_reason_guard tests.test_prd_ui_export -q", "broader_verification": "python -m unittest discover -s tests -p \"test_*.py\"", "expected_updates": [ "Focused red and green output", "Surface-marker provenance evidence", "EV-* behavior and UI evidence" ] } ] } ], "dependencies": [ "Existing Reason Guard classifier, state migration, state lock, and atomic write", "Existing Codex trusted-rollout resolver and cursor scanner", "Existing Claude hook transcript_path and session_id fields", "Existing status, UI export, installer, template parity, benchmark, and release workflows" ], "validations": [ { "id": "IMP-VAL-103", "summary": "Host ledgers isolate Claude, Codex, and OpenCode; bounded session records survive session changes; legacy state migrates once; Claude live/recent/full processing accepts only trusted assistant/text records and excludes every prohibited shape; replay, concurrent writes, torn tails, source changes, and retention behave deterministically.", "applies_to": [ "IMP-TASK-117" ], "expected_evidence": [ "Focused failing-test output", "Focused passing-test output", "Offline old-Claude-session counts and latency with no transcript text", "Privacy sentinel assertions" ] }, { "id": "IMP-VAL-104", "summary": "Status and UI expose readable provider/surface/session history with IDs secondary; source and skeleton hooks match; installer and release payloads contain the change; benchmarks, full suite, local workflow, state consistency, feature audits, release hygiene, and repeated CHML audits pass without a live Claude run.", "applies_to": [ "IMP-TASK-118" ], "expected_evidence": [ "Projection and installer test output", "Source/template byte-parity check", "Benchmark and full-suite output", "CHML zero audit", "Code-review receipt", "Publication tag receipt if release-bound" ] }, { "id": "IMP-VAL-105", "summary": "Codex Desktop and CLI plus Claude Desktop and CLI resolve from allowlisted host-owned metadata or bounded explicit override; latest model and effort follow trusted session metadata; unsupported and cross-provider values remain unknown; OpenCode stays distinct; status and UI use readable surface/model/effort values with session IDs secondary.", "applies_to": [ "IMP-TASK-119" ], "expected_evidence": [ "Focused surface test output", "Offline Codex and Claude metadata-shape inspection without message content", "Status and UI projection assertions" ] } ], "evidence_plan": [ "Record EV-* for provider/surface/session behavior, migration, privacy, offline Claude backfill, and focused tests.", "Record EV-* for review, full verification, CHML zero, integration, and publication." ], "risks_and_rollback": [ { "risk": "Per-host session history grows or increases write cost.", "mitigation": "Use a fixed session-retention bound, reuse bounded session state, and measure hook p50/p95." }, { "risk": "Claude transcript parsing crosses the visibility boundary.", "mitigation": "Constrain paths to the Claude projects root, allowlist assistant/text only, reject thinking and unknown blocks, persist no transcript text outside sanitized diagnostic fields, and run privacy sentinels." }, { "risk": "Legacy migration or concurrent hosts lose state.", "mitigation": "Migrate under the existing lock, write atomically, keep migration idempotent, and prove session/host isolation with concurrency tests." }, { "rollback": "Revert the release. The legacy report remains readable during migration and host ledgers are local-only, so rollback has no committed user-data migration." } ], "traceability": { "request_ids": [ "REQ-176" ], "prd_ids": [ "PRD-011" ], "architecture_ids": [ "ARCH-011" ], "tracking_ids": [ "TRK-163" ], "workflow_ids": [ "WFR-443", "WFR-444", "WFR-445", "WFR-447", "WFR-448", "WFR-450", "WFR-451", "WFR-452" ], "evidence_ids": [ "EV-216", "EV-217" ], "change_ids": [ "CHG-141" ] } }