## Context

boocode currently has no persistent session management for its agents (the persona agents in data/AGENTS.md). When a session is interrupted, there's no recoverable audit trail, no way to detect repeated mistakes, and no mechanism to enforce learned behavioral guidelines across sessions.

audit-harness provides: hooks (PostToolUse buffer→Stop flush→UserPromptSubmit injection), skills (/start→/end→/recover→/report-daily), and a Python core (AuditContext) with unified index schema.

Parlant provides: GuidelineDocumentStore (versioned, tag/label filtered), JourneyStore (graph-based SOPs), and JourneyGuidelineProjection (node→guideline auto-conversion).

This design ports the high-value subset of both into boocode as agent-facing skills and a TypeScript core library.

## Goals / Non-Goals

**Goals:**
- Define `.boo/runs/` directory convention with auto-creation and `.gitignore`
- Port /start, /end, /recover, /report-daily as boocode skills (markdown)
- Port user_correction record format and detection
- Port GuidelineDocumentStore from Parlant as TypeScript service
- Port Journey → guideline auto-projection (node→guideline conversion)
- Implement guideline find_guideline() by content match
- All features opt-in, zero breaking changes

**Non-Goals:**
- AuditContext full Python class port (environment snapshots, anomaly lambdas)
- Hooks implementation (PostToolUse/Stop/UserPromptSubmit) — separate batch
- Parlant's vector DB / embedder infrastructure
- Parlant's relationship resolver (ARQ)
- Web UI for guideline management — CLI/skill-only

## Decisions

### Decision 1: Skill-based commands over CLI tools

**Choice**: Implement /start, /end, /recover, /report-daily as skill markdown files in `data/skills/boocode/`, following the existing `committing-changes` pattern.
**Rationale**: boocode agents already load skills from this path. Adding a new skill is zero code change to the agent runtime — just a new markdown file with YAML frontmatter. CLI tools would require new API routes, dispatch logic, and frontend work.
**Alternatives considered**: Fastify API routes (rejected — too heavy for agent-facing commands), shell scripts (rejected — platform-specific).

### Decision 2: JSONL buffer + index.json

**Choice**: Port audit-harness's file layout exactly: `audit_buffer.jsonl` for live writes, `audit_pending.jsonl` for agent-authored AUDIT blocks, per-session `audit_trail.jsonl` for flushed records, `index.json` for cross-session metadata.
**Rationale**: audit-harness has production-miles with this layout. JSONL is grep-able, append-only, and needs no DB connection.
**Alternatives considered**: Postgres (rejected — agents don't all have DB access), SQLite (rejected — adds a native dep).

### Decision 3: GUID-based session IDs

**Choice**: `adhoc_YYYYMMDD_HHMM` format for session IDs, matching audit-harness pattern.
**Rationale**: Human-readable, sort-able, no collision risk within the same second.

### Decision 4: File-based GuidelineStore

**Choice**: Port GuidelineDocumentStore's abstract interface (create/list/read/update/delete/find) but use filesystem JSON storage instead of Parlant's DocumentDatabase.
**Rationale**: boocode doesn't have Parlant's document DB abstraction. A JSON-file store is simpler and sufficient for single-user operation. The interface stays the same, so a future Postgres backend can be swapped in.
**Alternatives considered**: Postgres backend (rejected — adds coupling), in-memory only (rejected — no persistence).

### Decision 5: Journey → guideline projection as pure function

**Choice**: Port `JourneyGuidelineProjection` as a pure function (not a class). Takes a Journey + its nodes/edges, returns Guideline[].
**Rationale**: The projection logic (DFS traversal, node→guideline conversion, edge metadata grafting) is deterministic and has no side effects. A pure function is simpler to test and compose.
**Alternatives considered**: Class with JourneyStore dependency (rejected — unnecessary indirection for our use case).

## Risks / Trade-offs

- **[Risk]** Skills grow stale if agent runtime doesn't load them → **Mitigation**: Test with existing agent by loading skill explicitly.
- **[Risk]** JSONL file contention from multiple agents → **Mitigation**: Single-user homelab. Acceptable.
- **[Risk]** GuidelineStore JSON files grow unbounded → **Mitigation**: TBD — add compaction/archival in future batch.
- **[Trade-off]** File storage is simple but doesn't scale to multi-user → Acceptable for single-user.

## Migration / Rollout

1. Create openspec spec files (proposal/design/tasks/specs)
2. Create `.boo/runs/` directory structure (service)
3. Create 4 skill files in `data/skills/boocode/`
4. Create core AuditContext TypeScript service
5. Create GuidelineStore + Journey service
6. Create user_correction utilities
7. Update data/AGENTS.md with new agents
8. Test with skill invocation