@open-code-review/agents 1.3.1 → 1.5.0

package/skills/ocr/references/session-files.md

@@ -8,10 +8,18 @@ Every OCR session creates files in `.ocr/sessions/{session-id}/`:
 
 ```
 .ocr/sessions/{YYYY-MM-DD}-{branch}/
-├── state.json              # Session state (REQUIRED)
 ├── discovered-standards.md # Merged project context (shared across rounds)
 ├── requirements.md         # User-provided requirements (if any, shared)
 ├── context.md              # Phase 2+3: Change summary + Tech Lead guidance (shared)
+├── map/                    # Code Review Map artifacts (optional)
+│   └── runs/
+│       ├── run-1/          # First map generation
+│       │   ├── topology.md         # File categorization and sections
+│       │   ├── flow-analysis.md    # Dependency tracing results
+│       │   ├── requirements-mapping.md  # Coverage matrix (if requirements)
+│       │   └── map.md              # Final map output
+│       └── run-2/          # Subsequent runs (created on re-map)
+│           └── ...         # Same structure as run-1
 └── rounds/                 # All round-specific artifacts
     ├── round-1/            # First review round
     │   ├── reviews/        # Individual reviewer outputs
@@ -40,28 +48,51 @@ OCR uses a **round-first architecture** where all round-specific artifacts live
 - Subsequent `/ocr-review` on same day/branch creates `rounds/round-{n+1}/`
 - Previous rounds are preserved (never overwritten)
 - Each round has its own `discourse.md` and `final.md`
-- `state.json` tracks `current_round`; round metadata derived from filesystem
+- SQLite tracks `current_round` via `ocr state show`; round metadata derived from filesystem
 
-**Shared vs per-round artifacts**:
-| Shared (session root) | Per-round (`rounds/round-{n}/`) |
-|----------------------|--------------------------------|
-| `state.json` | `reviews/*.md` |
-| `discovered-standards.md` | `discourse.md` |
-| `requirements.md` | `final.md` |
-| `context.md` | |
+**Shared vs per-round/run artifacts**:
+| Shared (session root) | Per-round (`rounds/round-{n}/`) | Per-run (`map/runs/run-{n}/`) |
+|----------------------|--------------------------------|-------------------------------|
+| `discovered-standards.md` | `reviews/*.md` | `topology.md` |
+| `requirements.md` | `discourse.md` | `flow-analysis.md` |
+| `context.md` | `final.md` | `requirements-mapping.md` |
+| | | `map.md` |
 
 **When to use multiple rounds**:
 - Author addresses feedback and requests re-review
 - Scope changes mid-review
 - Different reviewer team composition needed
 
+## Map Runs
+
+OCR uses a **run-based architecture** for maps, parallel to review rounds.
+
+**Run behavior**:
+- First `/ocr-map` creates `map/runs/run-1/` with map artifacts
+- Subsequent `/ocr-map` on same day/branch creates `map/runs/run-{n+1}/`
+- Previous runs are preserved (never overwritten)
+- Each run produces a complete `map.md`
+- SQLite tracks `current_map_run` via `ocr state show`; run metadata derived from filesystem
+
+**Map artifacts per run**:
+| File | Phase | Description |
+|------|-------|-------------|
+| `topology.md` | 2 | File categorization and section groupings |
+| `flow-analysis.md` | 3 | Upstream/downstream dependency tracing |
+| `requirements-mapping.md` | 4 | Requirements coverage matrix (if requirements provided) |
+| `map.md` | 5 | Final synthesized Code Review Map |
+
+**When to use multiple runs**:
+- Changeset has evolved since last map
+- Different requirements context needed
+- Fresh analysis desired after code updates
+
 ## File Specifications
 
 ### Required Files
 
 | File | Phase | Description | Used By |
 |------|-------|-------------|---------|
-| `state.json` | 1 | Session state for progress tracking | CLI, resume logic |
 | `discovered-standards.md` | 1 | Merged project context from config + references | All reviewers |
 | `context.md` | 2 | Change summary, diff analysis, Tech Lead guidance | All reviewers |
 | `rounds/round-{n}/reviews/{type}-{n}.md` | 4 | Individual reviewer outputs | Discourse, Synthesis |
@@ -102,18 +133,18 @@ rounds/round-1/reviews/performance-1.md   # Custom reviewer
 
 | Phase | Phase Name | Files to Create/Update |
 |-------|------------|------------------------|
-| 1 | Context Discovery | `state.json`, `discovered-standards.md`, `requirements.md` (if provided) |
-| 2 | Change Analysis | `context.md`, update `state.json` |
-| 3 | Tech Lead Analysis | Update `context.md` with guidance, update `state.json` |
-| 4 | Parallel Reviews | `rounds/round-{n}/reviews/{type}-{n}.md` for each reviewer, update `state.json` |
-| 5 | Aggregation | (Inline analysis), update `state.json` |
-| 6 | Discourse | `rounds/round-{n}/discourse.md`, update `state.json` |
-| 7 | Synthesis | `rounds/round-{n}/final.md`, update `state.json` |
-| 8 | Presentation | Set `state.json` status to `"closed"` |
+| 1 | Context Discovery | `discovered-standards.md`, `requirements.md` (if provided) |
+| 2 | Change Analysis | `context.md`, call `ocr state transition` |
+| 3 | Tech Lead Analysis | Update `context.md` with guidance, call `ocr state transition` |
+| 4 | Parallel Reviews | `rounds/round-{n}/reviews/{type}-{n}.md` for each reviewer, call `ocr state transition` |
+| 5 | Aggregation | (Inline analysis), call `ocr state transition` |
+| 6 | Discourse | `rounds/round-{n}/discourse.md`, call `ocr state transition` |
+| 7 | Synthesis | `rounds/round-{n}/final.md`, call `ocr state transition` |
+| 8 | Presentation | Call `ocr state close` |
 
 ## State Transitions and File Validation
 
-When updating `state.json`, verify the corresponding file exists:
+When calling `ocr state transition`, verify the corresponding file exists:
 
 | Phase | Verify file exists |
 |---------------------------|-------------------|
@@ -147,30 +178,9 @@ SESSION_ID="$(date +%Y-%m-%d)-$(git branch --show-current | tr '/' '-')"
 
 ## File Content Requirements
 
-### state.json (Minimal Schema)
-
-```json
-{
-  "session_id": "{session-id}",
-  "status": "active",
-  "current_phase": "{phase-name}",
-  "phase_number": 4,
-  "current_round": 1,
-  "started_at": "{ISO-8601-timestamp}",
-  "round_started_at": "{ISO-8601-timestamp}",
-  "updated_at": "{ISO-8601-timestamp}"
-}
-```
-
-> **Note**: `round_started_at` is set when starting a new round (> 1) for accurate per-round timing display.
-
-**Derived from filesystem** (not stored in state.json):
-- Round count: enumerate `rounds/round-*/` directories
-- Round completion: check for `final.md` in round directory
-- Reviewers in round: list files in `rounds/round-{n}/reviews/`
-- Discourse complete: check for `discourse.md` in round directory
+### Session State
 
-See `references/session-state.md` for complete state management details.
+Session state is stored in SQLite at `.ocr/data/ocr.db`. Use `ocr state show` to inspect current state. See `session-state.md` for the full data model.
 
 ### Reviewer Files
 
@@ -200,14 +210,14 @@ The `ocr progress` CLI depends on these exact file names:
 
 | CLI Feature | Files Read |
 |-------------|-----------|
-| Session detection | `state.json` |
-| Phase tracking | `state.json` → `current_phase` |
-| Current round | `state.json` → `current_round` (reconciled with filesystem) |
+| Session detection | `ocr state show` / SQLite |
+| Phase tracking | SQLite → `current_phase` |
+| Current round | SQLite → `current_round` (reconciled with filesystem) |
 | Reviewer progress | `rounds/round-{n}/reviews/*.md` file existence |
 | Round completion | `rounds/round-{n}/final.md` existence |
-| Elapsed time | `state.json` → `started_at` |
+| Elapsed time | SQLite → `started_at` |
 
-**Filesystem as truth**: The CLI derives round metadata from the filesystem, using `state.json` as a hint. If state.json is missing or inconsistent, the CLI reconstructs state by:
+**Filesystem as truth**: The CLI derives round metadata from the filesystem, using SQLite as the primary state store. Round-level details are always reconciled against the filesystem by:
 1. Enumerating `rounds/round-*/` to count rounds
 2. Checking `final.md` presence to determine completion
 3. Listing `reviews/*.md` to identify reviewers

package/skills/ocr/references/session-state.md

@@ -2,42 +2,50 @@
 
 ## Overview
 
-OCR uses a **state file** approach for reliable progress tracking. The orchestrating agent writes to `.ocr/sessions/{id}/state.json` at each phase transition.
+OCR uses **SQLite** as the primary state store for reliable progress tracking. The database is located at `.ocr/data/ocr.db` and is managed through the `ocr state` CLI commands. Agents use these CLI commands at each phase transition instead of writing state files directly.
 
 ## Cross-Mode Compatibility
 
-Sessions are **always** stored in the project's `.ocr/sessions/` directory, regardless of installation mode:
+Sessions are **always** stored in the project's `.ocr/data/ocr.db` database and mirrored to `.ocr/sessions/`, regardless of installation mode:
 
-| Mode | Skills Location | Sessions Location |
-|------|-----------------|-------------------|
-| **CLI** | `.ocr/skills/` | `.ocr/sessions/` |
-| **Plugin** | Plugin cache | `.ocr/sessions/` |
+| Mode | Skills Location | State Store | Sessions Mirror |
+|------|-----------------|-------------|-----------------|
+| **CLI** | `.ocr/skills/` | `.ocr/data/ocr.db` | `.ocr/sessions/` |
+| **Plugin** | Plugin cache | `.ocr/data/ocr.db` | `.ocr/sessions/` |
 
 This means:
 - The `ocr progress` CLI works identically in both modes
 - Running `npx @open-code-review/cli progress` from any project picks up the session state
-- No configuration needed — the CLI always looks in `.ocr/sessions/`
+- No configuration needed — the CLI always reads from `.ocr/data/ocr.db`
 
-## State File Format (Minimal Schema)
+## State Data Model
+
+The following fields are tracked per session in SQLite:
 
 ```json
 {
   "session_id": "{session-id}",
+  "workflow_type": "review",
   "status": "active",
   "current_phase": "reviews",
   "phase_number": 4,
   "current_round": 1,
+  "current_map_run": 1,
   "started_at": "{ISO-8601-TIMESTAMP}",
   "round_started_at": "{ISO-8601-TIMESTAMP}",
+  "map_started_at": "{ISO-8601-TIMESTAMP}",
   "updated_at": "{ISO-8601-TIMESTAMP}"
 }
 ```
 
-**Minimal by design**: Round metadata is derived from the filesystem, not stored in state.json.
+**Minimal by design**: Round and map run metadata is derived from the filesystem, not stored in the database.
 
 **Field descriptions**:
-- `started_at`: When the session was created (first `/ocr-review`)
-- `round_started_at`: When the current round began (updated when starting round > 1)
+- `workflow_type`: Current workflow type (`"review"` or `"map"`) — enables `ocr progress` to track correct workflow
+- `started_at`: When the session was created (first `/ocr-review` or `/ocr-map`)
+- `round_started_at`: When the current review round began (set when starting round ≥ 1)
+- `map_started_at`: When the current map run began (set when starting a map run)
+- `current_map_run`: Current map run number (only present during map workflow)
 - `updated_at`: Last modification time (updated at every phase transition)
 
 **Derived from filesystem** (not stored):
@@ -45,8 +53,17 @@ This means:
 - Round completion: check for `final.md` in round directory
 - Reviewers in round: list files in `rounds/round-{n}/reviews/`
 - Discourse complete: check for `discourse.md` in round directory
+- Map run count: enumerate `map/runs/run-*/` directories
+- Map run completion: check for `map.md` in run directory
+
+## Orchestration Events Table
+
+In addition to the session state, SQLite tracks an **orchestration events timeline** in the `orchestration_events` table. Each `ocr state transition` call automatically logs an event, providing a complete history of phase transitions with timestamps. This enables:
+- Post-session analytics (time spent per phase)
+- Debugging stalled reviews
+- Progress timeline reconstruction
 
-**IMPORTANT**: Timestamps MUST be generated dynamically using the current time in ISO 8601 format (e.g., `new Date().toISOString()` → `"2026-01-27T09:45:00.000Z"`). Do NOT copy example timestamps.
+Events are stored with the session ID, phase name, phase number, and timestamp.
 
 ## Session Status
 
@@ -58,105 +75,158 @@ The `status` field controls session visibility:
 | `closed` | Complete and dismissed | Skipped | Cannot resume |
 
 **Lifecycle:**
-1. Session created → `status: "active"`
-2. Review in progress → `status: "active"`, `current_phase` updates
-3. Phase 8 complete → `status: "closed"`, `current_phase: "complete"`
+1. Session created via `ocr state init` → `status: "active"`
+2. Review in progress → `status: "active"`, `current_phase` updates via `ocr state transition`
+3. Phase 8 complete → `ocr state close` sets `status: "closed"`, `current_phase: "complete"`
 
 The `ocr progress` command only auto-detects sessions with `status: "active"`. Closed sessions are accessible via `/ocr-history` and `/ocr-show`.
 
+## CLI Commands for State Management
+
+Agents MUST use these CLI commands to manage session state. **Do NOT write state files directly.**
+
+> **Note**: These commands require the OCR CLI. Install globally with `npm install -g @open-code-review/cli` or prefix with `npx @open-code-review/cli`.
+
+### `ocr state init` — Create a new session
+
+```bash
+ocr state init \
+  --session-id "{session-id}" \
+  --branch "{branch}" \
+  --workflow-type review \
+  --session-dir ".ocr/sessions/{session-id}"
+```
+
+Creates the session record in SQLite.
+
+### `ocr state transition` — Update phase at each boundary
+
+```bash
+ocr state transition \
+  --phase "{phase-name}" \
+  --phase-number {N}
+```
+
+For review workflows with multiple rounds:
+```bash
+ocr state transition \
+  --phase "{phase-name}" \
+  --phase-number {N} \
+  --current-round {round-number}
+```
+
+For map workflows:
+```bash
+ocr state transition \
+  --phase "{phase-name}" \
+  --phase-number {N} \
+  --current-map-run {run-number}
+```
+
+Updates the session in SQLite and logs an orchestration event.
+
+### `ocr state close` — Close the session
+
+```bash
+ocr state close
+```
+
+Sets `status: "closed"` and `current_phase: "complete"` in SQLite.
+
+### `ocr state show` — Read current session state
+
+```bash
+ocr state show
+```
+
+Outputs the current session state from SQLite. Use this to inspect current session state.
+
+### `ocr state sync` — Rebuild from filesystem
+
+```bash
+ocr state sync
+```
+
+Scans filesystem session directories and backfills any missing sessions into SQLite.
+
 ## Phase Transitions
 
 > **See `references/session-files.md` for the authoritative file manifest.**
 
-The Tech Lead MUST update `state.json` at each phase boundary:
+The Tech Lead MUST call `ocr state transition` at each phase boundary:
 
-| Phase | When to Update | File Created |
-|-------|---------------|--------------|
+### Review Phases
+
+| Phase | When to Transition | File Created |
+|-------|-------------------|--------------|
 | context | After writing project standards | `discovered-standards.md` |
 | change-context | After writing change summary | `context.md`, `requirements.md` (if provided) |
 | analysis | After adding Tech Lead guidance | Update `context.md` |
 | reviews | After each reviewer completes | `rounds/round-{n}/reviews/{type}-{n}.md` |
 | discourse | After cross-reviewer discussion | `rounds/round-{n}/discourse.md` |
 | synthesis | After final review | `rounds/round-{n}/final.md` |
-| complete | After presenting to user | Set `status: "closed"` |
+| complete | After presenting to user | Call `ocr state close` |
 
-## Writing State
+### Map Phases
 
-**CRITICAL**: Always generate timestamps dynamically using the current UTC time in ISO 8601 format.
+| Phase | When to Transition | File Created |
+|-------|-------------------|--------------|
+| map-context | After writing project standards | `discovered-standards.md` (shared) |
+| topology | After topology analysis | `map/runs/run-{n}/topology.md` |
+| flow-analysis | After flow analysis | `map/runs/run-{n}/flow-analysis.md` |
+| requirements-mapping | After requirements mapping | `map/runs/run-{n}/requirements-mapping.md` |
+| synthesis | After map generation | `map/runs/run-{n}/map.md` |
+| complete | After presenting map | Keep `status: "active"` (session continues) |
 
-### Generating Timestamps
+## State Transition Examples
 
-```bash
-# macOS/Linux
-date -u +"%Y-%m-%dT%H:%M:%SZ"
-# Output: 2026-01-27T09:45:00Z
-
-# Windows (PowerShell)
-Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ" -AsUTC
+When creating a new session (Phase 1 start):
 
-# Node.js / JavaScript
-new Date().toISOString()
+```bash
+ocr state init \
+  --session-id "{session-id}" \
+  --branch "{branch}" \
+  --workflow-type review \
+  --session-dir ".ocr/sessions/{session-id}"
 ```
 
-When creating a new session (Phase 1 start):
+When transitioning phases:
 
-```json
-{
-  "session_id": "{session-id}",
-  "status": "active",
-  "current_phase": "context",
-  "phase_number": 1,
-  "current_round": 1,
-  "started_at": "{CURRENT_ISO_TIMESTAMP}",
-  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
-}
+```bash
+ocr state transition --phase "reviews" --phase-number 4 --current-round 1
 ```
 
-When transitioning phases (preserve `started_at`, update `updated_at`):
+When starting a map workflow:
 
-```json
-{
-  "session_id": "{session-id}",
-  "status": "active",
-  "current_phase": "reviews",
-  "phase_number": 4,
-  "current_round": 1,
-  "started_at": "{PRESERVE_ORIGINAL}",
-  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
-}
+```bash
+ocr state init \
+  --session-id "{session-id}" \
+  --branch "{branch}" \
+  --workflow-type map \
+  --session-dir ".ocr/sessions/{session-id}"
+
+ocr state transition --phase "map-context" --phase-number 1 --current-map-run 1
 ```
 
 When closing a session (Phase 8 complete):
 
-```json
-{
-  "session_id": "{session-id}",
-  "status": "closed",
-  "current_phase": "complete",
-  "phase_number": 8,
-  "current_round": 1,
-  "started_at": "{PRESERVE_ORIGINAL}",
-  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
-}
+```bash
+ocr state close
 ```
 
 ## Benefits
 
 1. **Explicit state** — No inference required
-2. **Atomic updates** — Single file write
-3. **Rich metadata** — Reviewer assignments, timestamps
-4. **Debuggable** — Human-readable JSON
-5. **CLI-friendly** — Easy to parse programmatically
+2. **Atomic updates** — SQLite transactions ensure consistency
+3. **Rich metadata** — Reviewer assignments, timestamps, orchestration events
+4. **Debuggable** — `ocr state show` for human-readable output
+5. **CLI-friendly** — All state operations via `ocr state` commands
+6. **Timeline tracking** — Orchestration events table records full phase history
 
 ## Important
 
-The `state.json` file is the **primary** source for workflow progress. However, with the round-first architecture:
+SQLite (`.ocr/data/ocr.db`) is the **sole** source for workflow progress. With the round-first architecture:
 
+- **SQLite is truth for workflow state**: `current_phase`, `phase_number`, `status`, timestamps
 - **Filesystem is truth for round data**: Round count, completion, and reviewers are derived from `rounds/` directory structure
-- **state.json is truth for workflow state**: `current_phase`, `phase_number`, `status`, timestamps
-- **Reconciliation**: If state.json and filesystem disagree, the CLI reconciles by trusting the filesystem for round data
-
-If `state.json` is missing entirely, the CLI will show "Waiting for session..." until the orchestrating agent creates `state.json`. Future versions may implement filesystem reconstruction to derive:
-1. Round count from `rounds/round-*/` directories
-2. Round completion from `final.md` presence
-3. Approximate phase from file existence
+- **Reconciliation**: If SQLite and filesystem disagree, the CLI reconciles by trusting the filesystem for round data

package/skills/ocr/references/setup-guard.md

@@ -128,6 +128,26 @@ mkdir -p .ocr/sessions
 
 This is safe to do automatically since it's just an empty directory for storing review sessions.
 
+### 5. Verify CLI is Reachable (CLI Mode Only)
+
+The review and map workflows require `ocr state` commands at every phase transition. Verify the CLI is available:
+
+```bash
+ocr --version 2>/dev/null || npx @open-code-review/cli --version 2>/dev/null
+```
+
+**If neither works:**
+```
+⚠ OCR CLI not found in PATH.
+
+The review workflow requires the CLI for state management (ocr state).
+Install it globally or use npx:
+
+  npm install -g @open-code-review/cli
+  # or prefix commands with: npx @open-code-review/cli
+```
+**Then WARN** (do not stop — the user may have the CLI installed elsewhere).
+
 ## Success Response
 
 If all checks pass, respond briefly and proceed: