feat(coder,server): audit engine — session audit, guideline compliance, user correction tracking

Implements audit-harness-inspired session lifecycle: audit session
creation/end/recover/report-daily with JSONL buffer and graded context
recovery (L0-L4). Guideline service for behavioral compliance rules
(condition/action model with criticality). Correction service for
persistent user correction tracking across agent sessions.

8 supporting skills: audit-start/end/report-daily/recover + command
variants for slash-command integration.
This commit is contained in:
2026-06-07 22:16:35 +00:00
parent c132215064
commit 876c9bcd02
18 changed files with 3397 additions and 0 deletions

View File

@@ -0,0 +1,104 @@
---
name: audit-end
description: End an audit session with integrity checks and summary. Use when the user says "/end", "done", "pause", or when the current task is complete.
---
# /end — Audit Session End + Integrity Check
## Trigger
```
/end
```
## Steps
### 1. Determine current session
Read `.boo/runs/.current_session` for session_id.
If missing:
- Check for `auto_` sessions (hook-created)
- If none, report "No active session"
### 2. Collect audit data
Sources:
- `.boo/runs/audit_buffer.jsonl` — hook-recorded Write/Edit/Bash ops
- `.boo/runs/audit_pending.jsonl` — agent [AUDIT] blocks
- `.boo/runs/{session_id}/audit_trail.jsonl` — previously flushed records
Steps:
1. Read buffer + pending remaining data
2. Append to `audit_trail.jsonl`
3. Clear buffer + pending files
### 3. Extract user corrections
Scan audit_trail for `user_correction` records:
```json
{
"record_type": "conversation",
"action_type": "user_correction",
"priority": "critical_for_recovery",
"timestamp": "<ISO 8601>",
"original_claim": "<what agent said>",
"correction": "<what user corrected>",
"principle_extracted": "<general principle>",
"persisted_to": ["CLAUDE.md", ".boo/guidelines/..."]
}
```
### 4. Integrity checks
| Check | Condition | Fail |
|-------|-----------|------|
| Has records | audit_trail lines > 0 | ⚠️ "Zero audit records" |
| Files covered | Write/Edit entries exist for modified files | ⚠️ List uncovered files |
| Corrections persisted | persisted_to is non-empty for each correction | ⚠️ Remind to persist |
Output:
```
=== Session Audit Check ===
Session: <id>
Task: <task>
Duration: <start → end>
[✅] Records: N
[⚠️] Files not in audit: <list>
[✅] Corrections persisted: M
```
### 5. Generate session summary
Write `.boo/runs/{session_id}/session_summary.md`:
```
# Session Summary | <id>
## Task: <description>
## Time: <start → end>
## Status: completed
## Completed
- <action list>
## User Corrections
- <correction records>
## Stats
- Records: N
- Corrections: M
```
### 6. Update state
- Set `session.json status = "completed", end_time = now()`
- Update `index.json` entry
- Clear `.current_session`
## Notes
- Save even if checks find problems — recording > perfection
- ⚠️ = don't block save; ❌ = warn user, still save
- /end itself may trigger one more Stop hook flush — normal

View File

@@ -0,0 +1,84 @@
---
name: audit-recover
description: Restore lost context from audit trail. Use when unsure of prior decisions, can't remember what was discussed, or the user says "/recover". Do not guess — check the records.
---
# /recover — Context Recovery
## Trigger
```
/recover # L0+L1+L2 (current session)
/recover full # L3 (full trail)
/recover {session_id} # specific session
```
## Core principle
**When uncertain, check the audit trail. Do not work from memory.**
Recovering from records is the only reliable way to avoid repeating corrected mistakes.
## When to trigger
| Signal | What to do |
|--------|-----------|
| Can't recall session details | Run /recover |
| Unsure about current task | Run /recover |
| About to propose something possibly corrected | Run /recover, check corrections |
| Answer is vague, missing specifics | Run /recover full |
## Steps
### Graded loading
**Level 0 — Index (~200t)**
Read `.boo/runs/index.json` → last 5 entries (id, task, status)
**Level 1 — Task state (~500t)**
Read `.current_session` → session_id
Read `session.json` → task, start_time
Read last 3 `audit_trail.jsonl` entries → "where am I"
**Level 2 — User corrections (~1000t) ⚠️ HIGHEST PRIORITY**
Scan all audit_trail files for `user_correction` records
Scan for `conclusion` entries
Read latest daily report §4 (anomalies) + §6 (backlog)
**Level 3 — Full context (~3000t, /recover full only)**
Full `audit_trail.jsonl`
Full `audit_pending.jsonl`
### Output
```
=== Context Recovery Report ===
Source: .boo/runs/<session_id>/
Level: L2
Task: <session.task>
Status: <last action>
⚠️ User corrections (must follow):
1. <timestamp> Original: "..."
Correction: "..."
Principle: <principle>
Key conclusions:
- <...>
Open issues:
- <...>
⚠️ Recovered from audit trail, not memory.
```
## Notes
- Corrections have highest priority — don't contradict them
- If current plan contradicts corrections, correct the plan
- Keep output concise — don't copy entire trail into context
- Recover "why" and "don't" before "what was done"

View File

@@ -0,0 +1,100 @@
---
name: audit-report-daily
description: Generate a daily work report from audit data. Every number traces to a source file. Use when user says "/report-daily", "daily report", "what did I do today".
---
# /report-daily — Audit-Driven Daily Report
## Trigger
```
/report-daily # today
/report-daily 20260319 # specific date
/report-daily review # with morning self-review
```
## Data Sources
| Section | Source |
|---------|--------|
| Task overview | `.boo/runs/index.json` |
| Operation stats | `*/audit_trail.jsonl` tool records |
| Changes | trail entries with edit/create/delete |
| User feedback | `user_correction` entries in trail |
| Anomalies | `*/anomalies.json` |
| Backlog | previous day's daily report §6 |
Every number must trace to a file. Do not fill from memory.
## Steps
### 1. Collect data
1. Read index.json, filter sessions for target date
2. Read each session's audit_trail.jsonl
3. Read pending (unflushed data)
4. Read previous day's report §6 (backlog) if exists
### 2. Generate report
Write to `.boo/runs/daily/{YYYYMMDD}_daily.md`:
```
# Daily Report | <DATE>
> Source: .boo/runs/index.json + audit_trails
## 1. Task Overview
| # | Type | Session | Task | Status | Records |
## 2. Operation Stats
| Metric | Count |
|--------|-------|
| Write/Edit | N |
| Bash | N |
| AUDIT blocks | N |
## 3. Changes
| Time | File | Change |
## 4. User Feedback & Corrections
| Feedback | Persisted To |
## 5. Anomaly Alerts
- <alerts from anomalies.json>
## 6. Backlog
- previous day's todos
- current status
## 7. Integrity
- All sessions have records: ✅/❌
- Corrections persisted: ✅/❌
```
### 3. If /report-daily review
After report, additionally:
1. Check: yesterday's anomalies all addressed?
2. Check: user feedback converted to improvements?
3. Check: backlog items completed?
4. Write `.boo/runs/daily/{YYYYMMDD}_morning_review.md`
5. Output recommended priorities for today
```
=== Morning Self-Review ===
Trend: <up/down/flat compared to last 3 days>
Anomalies resolved: N/M
Backlog cleared: N/M
Recommended priorities:
1. <...>
2. <...>
```
## Notes
- If no sessions today, generate empty report with "No activity"
- Report itself should write one [AUDIT] block
- Historical reports are append-only — corrections go in new report
- Every number must cite its source file

View File

@@ -0,0 +1,85 @@
---
name: audit-start
description: Create an audit session with context recovery. Use when beginning a new task, before making changes, or when the user says "/start". Ensures all subsequent work is tracked in a recoverable session.
---
# /start — Audit Session + Context Recovery
## Trigger
```
/start "task description"
```
## Why
Every work session should be tracked. Without a session:
- Hooks output to an auto_ session with no task description
- /end can't run integrity checks
- Daily reports lack task context
/start costs one directory + one JSON file. The return is traceability.
## Steps
### 1. Create the session
1. Generate `session_id = adhoc_YYYYMMDD_HHMM`
2. `mkdir -p .boo/runs/{session_id}`
3. Write `session.json`:
```json
{
"session_id": "<id>",
"task": "<user description>",
"start_time": "<ISO 8601>",
"status": "in_progress",
"expected_record_types": ["data", "change", "conversation"]
}
```
4. Write `.boo/runs/.current_session` with session_id (hook handshake)
### 2. Context recovery
**Level 0 — Index**:
- Read `.boo/runs/index.json` → last 5 entries (id, task, status)
**Level 2 — User corrections (critical)**:
- Scan recent `audit_trail.jsonl` files for `user_correction` records
- These must be surfaced first — repeating corrected mistakes wastes effort
**Level 1 — Task state**:
- Read latest `.boo/runs/daily/*_daily.md` if it exists (§4 anomalies, §6 backlog)
- Read latest `*_morning_review.md` if it exists
### 3. Check unfinished sessions
- Scan `.boo/runs/` session dirs for `session.json` with `status: "in_progress"`
- If found, propose: continue existing session or start fresh
### 4. Output recovery summary
```
Audit session: adhoc_20260320_1400
Task: <description>
Context recovery:
Recent activity:
- <last 3 completed tasks>
⚠️ User corrections (must follow):
- <all user_correction records>
Unresolved:
- <unfinished sessions, open alerts>
Today's priorities:
- <recommendations>
```
## Notes
- If `.boo/runs/` doesn't exist, create it
- If no history, start clean — no errors
- session_id stays constant for the whole session; all [AUDIT] blocks share it
- If `.current_session` already points at an active session, ask before replacing

View File

@@ -0,0 +1,61 @@
---
name: command-end
description: End the current audit session, flush remaining buffer data, run integrity checks, and generate a session summary. Use when finishing a task, taking a break, or ending work. Examples: "end", "finish session", "end session", "wrap up", "/end".
allowed-tools:
- Read
- Glob
- Grep
- Bash
- Write
---
# /end — Audit Session End + Integrity Check
## Trigger
```
/end
```
## Steps
### 1. Find current session
Read `.boo/runs/.current_session` for the session_id.
If absent, check for auto-created sessions. If none, report "No active session."
### 2. Collect remaining audit data
Read `.boo/runs/audit_buffer.jsonl` and `audit_pending.jsonl` for any data the Stop hook hasn't flushed yet. Append both to `.boo/runs/{session_id}/audit_trail.jsonl`, then clear the buffer files.
### 3. Extract user corrections
Scan `audit_trail.jsonl` for `user_correction` entries. Each should have a non-empty `persisted_to` array. If any are unpersisted, flag them.
### 4. Integrity checks
| Check | Source | Pass | Fail |
|-------|--------|------|------|
| Has records | trail line count | > 0 | Warn |
| Files tracked | tool=Write/Edit entries | Every changed file has an entry | Warn |
| Corrections persisted | user_correction entries | persisted_to non-empty | Warn |
### 5. Generate summary
Write `.boo/runs/{session_id}/session_summary.md`:
```markdown
# Session Summary | {session_id}
## Task: {description}
## Time: {start} → {end}
## Status: completed
Completed work: {action list}
Key conclusions: {output entries}
User corrections: {correction records}
```
### 6. Close
Update `session.json`: status=completed, end_time=now. Update `index.json`. Delete `.current_session`.

View File

@@ -0,0 +1,61 @@
---
name: command-recover
description: Recover lost context from audit session records. Use when you can't remember earlier discussion, aren't sure about task progress, or need to check what the user has corrected before. Also use when your answers feel vague — don't guess, recover. Examples: "recover", "what was I doing", "recap", "what did we discuss", "/recover".
allowed-tools:
- Read
- Glob
- Grep
---
# /recover — Context Recovery
## Trigger
```
/recover # L0+L1+L2 (current session)
/recover full # L3 (full audit_trail)
/recover {session_id} # Specific session
```
## When to use
**Do not work from memory — query the audit trail when:**
- You can't recall what was decided earlier
- Unsure what phase the task is in
- About to propose something the user may have already corrected
- Answers feel generic (missing file names, specific numbers)
## Graded loading
### L0 — Index (~200t)
Read `.boo/runs/index.json` → last 5 entries (id, task, status)
### L1 — Task state (~500t)
Read `.current_session` → session.json → last 3 audit_trail entries
### L2 — User corrections + decisions (~1000t) ⚠️ MOST IMPORTANT
Scan ALL audit_trails for `user_correction` records + conclusions
Read daily report §4 (anomalies) + §6 (backlog)
### L3 — Full context (~3000t, /recover full only)
Complete audit_trail.jsonl + audit_pending.jsonl
## Output
```
=== Context Recovery Report ===
Level: L2
Source: .boo/runs/{session_id}/
Current task: {description}
Progress: {last action}
USER CORRECTIONS (must follow):
1. [{time}] {original claim} → {correction}
Principle: {principle_extracted}
Key conclusions: ...
Unresolved: ...
Source: audit records (not memory)
```

View File

@@ -0,0 +1,70 @@
---
name: command-report-daily
description: Generate a data-driven daily work report from audit session records. Every number is traceable to `.boo/runs/` files. Use for daily standup, progress tracking, or morning review. Examples: "daily report", "report today", "what did I do today", "generate report", "/report-daily".
allowed-tools:
- Read
- Glob
- Grep
- Bash
- Write
---
# /report-daily — Audit-Driven Work Report
## Trigger
```
/report-daily # Today
/report-daily 20260319 # Specific date
/report-daily review # Report + morning self-review
```
## Data sources (every number must be traceable)
| Section | Source |
|---------|--------|
| Task overview | `.boo/runs/index.json` |
| Operation stats | `*/audit_trail.jsonl` tool records |
| Changes | trail entries with Write/Edit |
| User feedback | user_correction entries |
| Anomalies | `*/anomalies.json` (if any) |
| Backlog | previous day's daily report |
## Sections
### I. Task Overview
Table of today's sessions with status and record count.
### II. Operation Stats
Write/Edit count, Bash count, Audit block count.
### III. Change Records
Timeline of file modifications with timestamps.
### IV. User Feedback & Corrections
User corrections made today, with persistence status.
### V. Anomaly Alerts
Unresolved issues flagged across sessions.
### VI. Backlog Tracking
Carry-over items from yesterday.
### VII. Integrity Summary
Health checks for all sessions.
## Output
Save to `.boo/runs/daily/{YYYYMMDD}_daily.md`.
### Review variant (`review`)
After the report, also generate `.boo/runs/daily/{YYYYMMDD}_morning_review.md` with:
- Self-correction check (anomalies resolved? feedback persisted? backlog handled?)
- Recommended priorities for today
## Notes
- If no sessions for the date, generate an empty report labeled "No activity"
- Reports are append-only — correct errors with a follow-up report, never edit
- Record one [AUDIT] block for report generation itself

View File

@@ -0,0 +1,72 @@
---
name: command-start
description: Create an audit session with context recovery before starting work. Use when beginning a new task, analysis, or code modification — establishes a session for tracking tool usage, user corrections, and decisions. Examples: "start", "begin session", "start work", "/start 'migrate database schema'".
allowed-tools:
- Read
- Glob
- Grep
- Bash
- Write
---
# /start — Audit Session Start + Context Recovery
## Trigger
```
/start "task description"
```
## Why
Every task should run in an audit session. Without one:
- Tool-use data goes to unnamed sessions with no task context
- `/end` can't run integrity checks
- Daily reports miss task descriptions
## Steps
### 1. Create session
Generate `session_id = adhoc_YYYYMMDD_HHMM`, create `.boo/runs/{session_id}/`, write `session.json`:
```json
{
"session_id": "adhoc_20260320_1400",
"task": "task description",
"start_time": "ISO 8601",
"status": "in_progress",
"expected_record_types": ["data", "change", "conversation"]
}
```
Write session_id to `.boo/runs/.current_session` (the Stop hook reads this for buffer archiving).
### 2. Context recovery (L0 + L2)
**L0 — Index summary**: read `.boo/runs/index.json`, last 5 entries.
**L2 — User corrections (critical)**: scan all `audit_trail.jsonl` and `audit_pending.jsonl` for `user_correction` records — these must be restored first to avoid repeating mistakes.
**Check for unfinished sessions**: scan `.boo/runs/adhoc_*/session.json` for `status: "in_progress"`. If found, prompt the user to continue the old session instead.
### 3. Output summary
```
Session created: adhoc_20260320_1400
Task: {description}
Context recovery:
Recent activity: {last 3 completed tasks}
User corrections (must follow): {all user_correction records}
Unresolved issues: {open anomalies/alerts}
Today's priorities: {from morning review}
All [AUDIT] blocks use batch_id = {session_id}
```
### 4. Notes
- If `.boo/runs/` doesn't exist, create it and skip recovery
- If `.current_session` already points to an in_progress session, prompt before creating a new one
- The session_id stays constant for the whole session — all [AUDIT] blocks share it