boocode/openspec/changes/audit-harness-integration/tasks.md

1. Data Directory Convention (cross-cutting)

• 1.1 Define .boo/runs/ directory structure — runs_dir/buffer/session dirs/.current_session/index.json
• 1.2 Implement .boo/runs/ directory auto-creation with .gitignore
• 1.3 Add AUDIT_DOT_DIR environment variable support for platform-specific directory naming
• 1.4 Implement find_runs_dir() — walk up from CWD looking for {AUDIT_DOT_DIR}/runs

2. Buffer + Flush Pipeline (MCP middleware)

• 2.1 Implement PostToolUse middleware: capture tool_name + summary → append to audit_buffer.jsonl
• 2.2 Implement Stop middleware: read .current_session, flush buffer+pending to session trail
• 2.3 Implement atomic session.json update preserving existing fields
• 2.4 Implement .current_session handshake protocol (create/read/clear)
• 2.5 Add safe input truncation (1MB cap) for large tool payloads
• 2.6 Implement UserPromptSubmit middleware: inject session context + CRITICAL alerts
• 2.7 Register all middleware with opt-in gate (audit.enabled: true)

3. Unified Index Schema

• 3.1 Define INDEX_ENTRY_REQUIRED and INDEX_ENTRY_OPTIONAL field schemas
• 3.2 Implement update_index_entry() with idempotent upsert and atomic .tmp + rename
• 3.3 Implement schema_version=1.1 tracking in index.json
• 3.4 Add CLI entry point for hooks to call update-index --runs-dir X --id Y ...

4. Graded Context Recovery

• 4.1 Implement L0 recovery: read last 5 index.json entries (~200 tokens)
• 4.2 Implement L1 recovery: read session.json + last 3 audit_trail entries (~500 tokens)
• 4.3 Implement L2 recovery: scan all audit trails for user_correction records (~1000 tokens)
• 4.4 Implement L3 recovery: full audit_trail + all pending records (~3000 tokens)
• 4.5 Implement recovery report output format: current task, corrections, conclusions, open issues, recent activity
• 4.6 Implement priority loading: user_correction records always loaded first

5. Session Lifecycle Commands

• 5.1 Implement /start command: generate session ID, write session.json + .current_session, auto-recover L0+L2
• 5.2 Implement /end command: flush buffers, run integrity checks, generate session_summary.md, update index
• 5.3 Implement /recover command: graded context loading (L0-L3), support for specific session IDs
• 5.4 Implement /report-daily command: aggregate index + audit trails, 7-section report with task overview, ops stats, changes, anomalies, feedback, backlog, integrity
• 5.5 Implement /report-daily review mode: add morning self-review with trend analysis
• 5.6 Implement unfinished session detection + continue prompt
• 5.7 Register all commands behind audit.enabled gate

6. Ambient Context via AsyncLocalStorage

• 6.1 Implement AmbientContext class wrapping Node.js AsyncLocalStorage with run()/get()/set()
• 6.2 Define AmbientState interface: sessionId, sessionDir, runsDir, agentId, toolCall
• 6.3 Wire context set at MCP handler/command entry point, clear on session end
• 6.4 Replace explicit parameter threading in audit pipeline with ambient context reads

7. Testing & Verification

• 7.1 Unit tests for buffer write, flush, index update
• 7.2 Unit tests for context recovery at all 4 levels
• 7.3 Integration test: full session lifecycle (/start → tool calls → /end)
• 7.4 Integration test: context recovery after mid-session interruption
• 7.5 Verify zero behavioral change when audit.enabled is false