@open-code-review/agents 1.5.0 → 1.6.0

package/README.md

@@ -1,8 +1,34 @@
 # @open-code-review/agents
 
-The skill definitions, reviewer personas, and workflow references that power Open Code Review.
+Skill definitions, reviewer personas, and workflow references that power [Open Code Review](https://github.com/spencermarx/open-code-review).
 
-> Browse review output and map artifacts in the [Dashboard](../dashboard/README.md) or through your AI assistant's slash commands.
+## Getting Started
+
+All OCR workflows require the CLI for session state management. Install it first:
+
+```bash
+# 1. Install the CLI
+npm install -g @open-code-review/cli
+
+# 2. Initialize in your project (copies these assets to .ocr/)
+cd your-project
+ocr init
+```
+
+To update after a package upgrade:
+
+```bash
+ocr update
+```
+
+This updates skills and workflow references while **preserving your `.ocr/config.yaml`** and **all reviewer personas** (both default and custom).
+
+### Via Claude Code Plugin
+
+```bash
+/plugin marketplace add spencermarx/open-code-review
+/plugin install ocr@aclarify
+```
 
 ## What This Package Contains
 
@@ -17,64 +43,46 @@ agents/
 │   │   ├── discourse.md       # Multi-agent debate rules
 │   │   ├── final-template.md  # Final review template
 │   │   └── reviewers/         # Persona definitions (customizable)
-│   │       ├── principal.md # Architecture, design patterns
-│   │       ├── quality.md   # Code style, best practices
-│   │       ├── security.md  # Auth, data handling, vulnerabilities
-│   │       └── testing.md   # Coverage, edge cases
+│   │       ├── principal.md   # Architecture, design patterns
+│   │       ├── quality.md     # Code style, best practices
+│   │       ├── security.md    # Auth, data handling, vulnerabilities
+│   │       └── testing.md     # Coverage, edge cases
 │   └── assets/
-│       ├── config.yaml      # Default configuration
+│       ├── config.yaml        # Default configuration
 │       └── reviewer-template.md
-├── commands/                # Slash command definitions
+├── commands/                  # Slash command definitions
 │   ├── review.md
 │   ├── map.md
 │   ├── doctor.md
 │   ├── history.md
 │   ├── show.md
 │   ├── reviewers.md
-│   └── post.md
-└── .claude-plugin/          # Claude Code plugin manifest
+│   ├── post.md
+│   ├── address.md
+│   └── translate-review-to-single-human.md
+└── .claude-plugin/            # Claude Code plugin manifest
     └── plugin.json
 ```
 
-## Prerequisites
-
-All OCR workflows require the CLI for session state management. Before running any review or map command, ensure the CLI is installed:
-
-```bash
-npm install -g @open-code-review/cli
-ocr init
-```
-
-The CLI provides the `ocr state` commands that track workflow progress through each phase. Without it, reviews will fail at phase transitions.
-
-## Installation
-
-### Via CLI (Recommended)
-
-The CLI copies these assets to your project's `.ocr/` directory:
-
-```bash
-npx @open-code-review/cli init
-```
-
-To update after a package upgrade:
-
-```bash
-ocr update
-```
-
-This updates skills and workflow references while **preserving your `.ocr/config.yaml`** and **all reviewer personas** (both default and custom).
+## Commands
 
-### Via Claude Code Plugin
+| File | Windsurf | Claude Code / Cursor |
+|------|----------|----------------------|
+| `review.md` | `/ocr-review` | `/ocr:review` |
+| `map.md` | `/ocr-map` | `/ocr:map` |
+| `post.md` | `/ocr-post` | `/ocr:post` |
+| `doctor.md` | `/ocr-doctor` | `/ocr:doctor` |
+| `reviewers.md` | `/ocr-reviewers` | `/ocr:reviewers` |
+| `history.md` | `/ocr-history` | `/ocr:history` |
+| `show.md` | `/ocr-show` | `/ocr:show` |
+| `address.md` | `/ocr-address` | `/ocr:address` |
+| `translate-review-to-single-human.md` | `/ocr-translate-review-to-single-human` | `/ocr:translate-review-to-single-human` |
 
-```bash
-/plugin marketplace add spencermarx/open-code-review
-/plugin install ocr@aclarify
-```
+**Why two formats?** Windsurf requires flat command files with a prefix (`/ocr-command`), while Claude Code and Cursor support subdirectories (`/ocr:command`). Both invoke the same underlying functionality.
 
 ## Skill Architecture
 
-The `SKILL.md` file defines the **Tech Lead** role—the orchestrator that:
+The `SKILL.md` file defines the **Tech Lead** role — the orchestrator that:
 
 1. Discovers project context (config, OpenSpec, reference files)
 2. Analyzes changes and identifies risk areas
@@ -82,62 +90,47 @@ The `SKILL.md` file defines the **Tech Lead** role—the orchestrator that:
 4. Facilitates discourse between reviewers
 5. Synthesizes findings into a unified review
 
-Each reviewer in `references/reviewers/` is a specialized persona. You can customize the built-in reviewers or add your own.
+### Reviewer Personas
+
+**Built-in** (customizable):
+- **Principal** — Architecture, design patterns, holistic review
+- **Quality** — Code style, readability, best practices
+- **Security** — Authentication, data handling, vulnerabilities
+- **Testing** — Coverage, edge cases, test strategy
+
+**Custom**: Create your own by adding files to `.ocr/skills/references/reviewers/`. See the [reviewer template](skills/ocr/assets/reviewer-template.md).
 
 ### Map Agent Personas
 
-The `/ocr:map` command uses a separate set of specialized agents defined in `references/map-personas/`:
+The `/ocr:map` command uses specialized agents:
 
 | Persona | Role |
 |---------|------|
-| **Map Architect** | Analyzes change topology, determines optimal section groupings and review ordering |
+| **Map Architect** | Analyzes change topology, determines section groupings and review ordering |
 | **Flow Analyst** | Traces upstream/downstream dependencies, groups related changes by data and control flow |
-| **Requirements Mapper** | Maps changes to requirements/specs when provided, identifies coverage gaps |
+| **Requirements Mapper** | Maps changes to requirements/specs, identifies coverage gaps |
 
-These agents run with configurable redundancy (default: 2) to increase confidence in groupings. See `.ocr/config.yaml` → `code-review-map.agents` for tuning.
+These run with configurable redundancy (default: 2). See `.ocr/config.yaml` → `code-review-map.agents`.
 
 ## Session Structure
 
-OCR uses a **round-first architecture** for session storage:
-
 ```
 .ocr/sessions/{YYYY-MM-DD}-{branch}/
-├── discovered-standards.md # Project context (shared across rounds)
-├── context.md              # Change analysis (shared)
+├── discovered-standards.md  # Project context (shared across rounds)
+├── context.md               # Change analysis (shared)
 └── rounds/
     ├── round-1/
-    │   ├── reviews/        # Individual reviewer outputs
-    │   ├── discourse.md    # Cross-reviewer discussion
-    │   └── final.md        # Synthesized review
-    └── round-2/            # Created on re-review
-        └── ...
+    │   ├── reviews/         # Individual reviewer outputs
+    │   ├── discourse.md     # Cross-reviewer discussion
+    │   └── final.md         # Synthesized review
+    └── round-2/             # Created on re-review
 ├── maps/
-│   ├── run-1/
-│   │   ├── map.md             # Code Review Map output
-│   │   └── flow-analysis.md   # Dependency graph (Mermaid)
-│   └── run-2/                 # Created on re-map
-│       └── ...
+│   └── run-1/
+│       ├── map.md           # Code Review Map
+│       └── flow-analysis.md # Dependency graph (Mermaid)
 ```
 
-**Multi-round reviews**: Running `/ocr-review` again on an existing session creates a new round (`round-2/`, `round-3/`, etc.) if the previous round is complete. This enables iterative "review → fix → re-review" workflows while preserving history.
-
-**Map runs**: Running `/ocr-map` creates map artifacts in `maps/run-{n}/`. Like review rounds, subsequent runs create new directories without modifying previous ones.
-
-See `references/session-files.md` for the complete file manifest.
-
-## Commands
-
-| File | Windsurf | Claude Code / Cursor |
-|------|----------|----------------------|
-| `review.md` | `/ocr-review` | `/ocr:review` |
-| `map.md` | `/ocr-map` | `/ocr:map` |
-| `doctor.md` | `/ocr-doctor` | `/ocr:doctor` |
-| `reviewers.md` | `/ocr-reviewers` | `/ocr:reviewers` |
-| `history.md` | `/ocr-history` | `/ocr:history` |
-| `show.md` | `/ocr-show` | `/ocr:show` |
-| `post.md` | `/ocr-post` | `/ocr:post` |
-
-**Why two formats?** Windsurf requires flat command files with a prefix (`/ocr-command`), while Claude Code and Cursor support subdirectories (`/ocr:command`). Both invoke the same underlying functionality.
+Running `/ocr-review` again on an existing session creates a new round if the previous round is complete. See `references/session-files.md` for the complete file manifest.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-code-review/agents",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "AI-native skills, commands, and reviewer personas for Open Code Review",
   "type": "module",
   "files": [

package/skills/ocr/assets/ocr-gitignore

@@ -1,12 +1,6 @@
-# OCR Session Directory .gitignore
-# Copy this to .ocr/.gitignore to exclude review sessions from git
-
-# Exclude all session data by default
+# OCR:START — managed by open-code-review (do not edit this block)
 sessions/
-
-# Or selectively include/exclude:
-# sessions/*
-# !sessions/important-review/
-
-# Keep the directory structure
-!.gitignore
+data/
+*.db-shm
+*.db-wal
+# OCR:END

package/skills/ocr/references/final-template.md

@@ -23,7 +23,8 @@ This synthesis process is designed to mirror how high-performing engineering tea
 
 - **Preserve all feedback** — Every finding from every reviewer appears, attributed
 - **Identify blockers** — Surface anything that should prevent merge
-- **Present suggestions** — Non-blocking improvements for author consideration
+- **Categorize should-fix items** — Issues that aren't blocking but should be addressed
+- **Present suggestions** — Lower-priority improvements for author consideration
 - **Assess requirements** — Evaluate against provided requirements (if any)
 - **Recommend action** — Clear verdict with rationale
 
@@ -53,11 +54,49 @@ A finding is a **blocker** if ANY of the following are true:
 
 **Any single reviewer can flag a blocker.** This is not subject to consensus—one engineer seeing a security hole is sufficient to block.
 
-### Step 3: Collect Suggestions
+### Step 3: Categorize Non-Blocking Findings
 
-All non-blocking feedback is preserved and attributed:
+All non-blocking feedback is categorized into **Should Fix** or **Suggestions**, then preserved and attributed.
+
+**Should Fix** — Issues that aren't blocking but should be addressed before or shortly after merge:
+
+| Should Fix Criteria | Examples |
+|---------------------|----------|
+| **Code quality issues** | Missing error handling, dead code, untested critical paths |
+| **Potential bugs** | Silent fallthrough, unvalidated input at boundaries, race conditions (non-data-loss) |
+| **Important refactors** | DRY violations with real maintenance cost, tight coupling between modules |
+| **Missing validation** | Input boundaries not enforced, missing null checks on external data |
+| **Functional gaps** | Feature partially implemented, edge case not handled |
+
+**Suggestions** — Low-priority improvements for author consideration:
+
+| Suggestion Criteria | Examples |
+|---------------------|----------|
+| **Style preferences** | Naming, formatting, early returns vs nested ifs |
+| **Minor refactors** | Extract small helper, reorder parameters, simplify expression |
+| **Documentation** | Add JSDoc, clarify comment, update README |
+| **Testing ideas** | Additional edge cases, snapshot tests, performance benchmarks |
+| **Informational** | Alternative approaches, FYI notes, future considerations |
 
 ```markdown
+## Should Fix
+
+### 1. {Title}
+
+**Flagged by**: @principal-1, @quality-1
+**Location**: `path/to/file.ts:42-50`
+
+{Description of the issue and why it should be fixed.}
+
+### 2. {Title}
+
+**Flagged by**: @quality-2
+**Location**: `path/to/other-file.ts:15`
+
+{Description.}
+
+---
+
 ## Suggestions
 
 ### Code Quality
@@ -74,7 +113,7 @@ All non-blocking feedback is preserved and attributed:
 - "Edge case for empty input not covered" — @testing-1
 ```
 
-**No suggestion is lost.** Even if only one reviewer mentions something, it surfaces.
+**No feedback is lost.** Even if only one reviewer mentions something, it surfaces.
 
 ### Step 4: Note Consensus and Dissent
 
@@ -200,15 +239,35 @@ The Tech Lead determines the verdict based on simple rules:
 
 ---
 
+## Should Fix
+
+{Issues that aren't blocking but should be addressed. Use numbered sub-headings.}
+
+### 1. {Title}
+
+**Flagged by**: @principal-1, @quality-1
+**Location**: `path/to/file.ts:42-50`
+
+{Description and why it should be fixed.}
+
+### 2. {Title}
+
+**Flagged by**: @quality-2
+**Location**: `path/to/other-file.ts:15`
+
+{Description.}
+
+---
+
 ## Suggestions
 
-{All non-blocking feedback, preserved and attributed}
+{Lower-priority improvements and informational feedback, preserved and attributed.}
 
 ### Code Quality
 - "Consider extracting the validation logic into a separate function" — @principal-1
 - "The error messages could be more user-friendly" — @quality-1
 
-### Performance  
+### Performance
 - "This query could benefit from an index on `user_id`" — @principal-2
 
 ### Testing
@@ -271,12 +330,12 @@ The Tech Lead determines the verdict based on simple rules:
 
 Full reviews available in session directory:
 
-| Reviewer | Blockers | Suggestions | File |
-|----------|----------|-------------|------|
-| @principal-1 | 0 | 3 | `rounds/round-{n}/reviews/principal-1.md` |
-| @principal-2 | 0 | 2 | `rounds/round-{n}/reviews/principal-2.md` |
-| @quality-1 | 0 | 4 | `rounds/round-{n}/reviews/quality-1.md` |
-| @security-1 | 1 | 2 | `rounds/round-{n}/reviews/security-1.md` |
+| Reviewer | Blockers | Should Fix | Suggestions | File |
+|----------|----------|------------|-------------|------|
+| @principal-1 | 0 | 1 | 3 | `rounds/round-{n}/reviews/principal-1.md` |
+| @principal-2 | 0 | 0 | 2 | `rounds/round-{n}/reviews/principal-2.md` |
+| @quality-1 | 0 | 1 | 4 | `rounds/round-{n}/reviews/quality-1.md` |
+| @security-1 | 1 | 0 | 2 | `rounds/round-{n}/reviews/security-1.md` |
 
 **Session**: `.ocr/sessions/{session-id}/`
 **Discourse**: `rounds/round-{n}/discourse.md`

package/skills/ocr/references/map-workflow.md

@@ -405,10 +405,49 @@ See `references/map-personas/flow-analyst.md` for persona details.
    [ "$EXPECTED" -ne "$MAPPED" ] && echo "ERROR: Missing files!"
    ```
 
-11. **Save final map**:
+11. **Pipe structured map data to CLI**:
+
+    Construct a JSON object with the map's structured data and pipe it to the CLI. The CLI validates, writes `map-meta.json`, and records a `map_completed` orchestration event — all in one command.
+
+    ```bash
+    cat <<'JSON' | ocr state map-complete --stdin
+    {
+      "schema_version": 1,
+      "sections": [
+        {
+          "section_number": 1,
+          "title": "Section Title",
+          "description": "Section description",
+          "files": [
+            {
+              "file_path": "src/example.ts",
+              "role": "Entry point",
+              "lines_added": 10,
+              "lines_deleted": 2
+            }
+          ]
+        }
+      ],
+      "dependencies": [
+        {
+          "from_section": 2,
+          "from_title": "Tests",
+          "to_section": 1,
+          "to_title": "Core Logic",
+          "relationship": "tests"
+        }
+      ]
+    }
+    JSON
+    ```
+
+    > The CLI validates the JSON schema, writes `map-meta.json` to the correct run directory, and records the event in SQLite. The orchestrator MUST NOT write `map-meta.json` directly.
+
+12. **Save final map** (presentation artifact):
     ```
     .ocr/sessions/{id}/map/runs/run-{n}/map.md
     ```
+    > `map.md` is the human-readable presentation artifact. The dashboard uses `map-meta.json` for structured data; `map.md` is stored as raw markdown for display and chat context.
 
 ### Map Output Format
 
@@ -426,6 +465,7 @@ See `references/map-template.md` for the complete template.
 - [ ] Section Dependencies table generated
 - [ ] File Index complete
 - [ ] Completeness validated (all files appear in tables)
+- [ ] `map-meta.json` piped to CLI via `ocr state map-complete --stdin`
 - [ ] `map.md` written
 - [ ] `ocr state transition` called with `--phase "synthesis"`
 

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

@@ -17,7 +17,8 @@ Every OCR session creates files in `.ocr/sessions/{session-id}/`:
 │       │   ├── topology.md         # File categorization and sections
 │       │   ├── flow-analysis.md    # Dependency tracing results
 │       │   ├── requirements-mapping.md  # Coverage matrix (if requirements)
-│       │   └── map.md              # Final map output
+│       │   ├── map-meta.json       # Structured map data (written by CLI via map-complete --stdin)
+│       │   └── map.md              # Final map output (presentation artifact)
 │       └── run-2/          # Subsequent runs (created on re-map)
 │           └── ...         # Same structure as run-1
 └── rounds/                 # All round-specific artifacts
@@ -31,11 +32,13 @@ Every OCR session creates files in `.ocr/sessions/{session-id}/`:
     │   │   ├── testing-1.md    # (if testing reviewer assigned)
     │   │   └── {type}-{n}.md   # (additional assigned custom reviewers)
     │   ├── discourse.md    # Cross-reviewer discussion for round 1
+    │   ├── round-meta.json # Structured review data (written by CLI via round-complete --stdin)
     │   └── final.md        # Synthesized final review for round 1
     └── round-2/            # Subsequent rounds (created on re-review)
         ├── reviews/
         │   └── ...         # Same structure as round-1
         ├── discourse.md
+        ├── round-meta.json
         └── final.md
 ```
 
@@ -80,7 +83,8 @@ OCR uses a **run-based architecture** for maps, parallel to review rounds.
 | `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 |
+| `map-meta.json` | 5 | Structured map data (written by CLI via `map-complete --stdin`) |
+| `map.md` | 5 | Final synthesized Code Review Map (presentation artifact) |
 
 **When to use multiple runs**:
 - Changeset has evolved since last map
@@ -97,6 +101,7 @@ OCR uses a **run-based architecture** for maps, parallel to review rounds.
 | `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 |
 | `rounds/round-{n}/discourse.md` | 6 | Cross-reviewer discussion results | Synthesis |
+| `rounds/round-{n}/round-meta.json` | 7 | Structured review data (written by CLI via `round-complete --stdin`) | Dashboard |
 | `rounds/round-{n}/final.md` | 7 | Synthesized final review | Show, Post commands |
 
 ### Optional Files
@@ -139,7 +144,7 @@ rounds/round-1/reviews/performance-1.md   # Custom reviewer
 | 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` |
+| 7 | Synthesis | Pipe data to `ocr state round-complete --stdin` (writes `round-meta.json`), write `final.md` |
 | 8 | Presentation | Call `ocr state close` |
 
 ## State Transitions and File Validation
@@ -153,7 +158,7 @@ When calling `ocr state transition`, verify the corresponding file exists:
 | `"analysis"` | `context.md` (with Tech Lead guidance) |
 | `"reviews"` | At least 2 files in `rounds/round-{current_round}/reviews/` |
 | `"discourse"` | `rounds/round-{current_round}/discourse.md` |
-| `"synthesis"` | `rounds/round-{current_round}/final.md` |
+| `"synthesis"` | `rounds/round-{current_round}/round-meta.json`, `rounds/round-{current_round}/final.md` |
 
 ## Session ID Format
 

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

@@ -141,6 +141,79 @@ ocr state show
 
 Outputs the current session state from SQLite. Use this to inspect current session state.
 
+### `ocr state round-complete` — Sync structured round metrics
+
+**Recommended: pipe structured data from stdin** (CLI writes the file + event):
+
+```bash
+cat <<'JSON' | ocr state round-complete --stdin
+{ "schema_version": 1, "verdict": "APPROVE", "reviewers": [...] }
+JSON
+```
+
+The `--stdin` flag makes the CLI the **sole writer** of `round-meta.json`. The CLI:
+1. Validates the JSON schema
+2. Writes `round-meta.json` to the correct session round directory
+3. Derives counts from the findings array (never trusts self-reported counts)
+4. Records a `round_completed` orchestration event in SQLite
+
+The dashboard picks this up via `DbSyncWatcher` for real-time updates.
+
+**Alternative: read from existing file** (for manual use or debugging):
+
+```bash
+ocr state round-complete --file "rounds/round-1/round-meta.json"
+```
+
+Optional flags (both modes):
+```bash
+--session-id "{session-id}"   # Auto-detects active session if omitted
+--round 1                     # Auto-detects current round if omitted
+```
+
+### `ocr state map-complete` — Sync structured map metrics
+
+**Recommended: pipe structured data from stdin** (CLI writes the file + event):
+
+```bash
+cat <<'JSON' | ocr state map-complete --stdin
+{
+  "schema_version": 1,
+  "sections": [
+    {
+      "section_number": 1,
+      "title": "Core Logic",
+      "description": "Main business logic",
+      "files": [
+        { "file_path": "src/index.ts", "role": "Entry point", "lines_added": 10, "lines_deleted": 2 }
+      ]
+    }
+  ],
+  "dependencies": []
+}
+JSON
+```
+
+The `--stdin` flag makes the CLI the **sole writer** of `map-meta.json`. The CLI:
+1. Validates the JSON schema
+2. Writes `map-meta.json` to the correct session map run directory
+3. Derives counts from the sections array (never trusts self-reported counts)
+4. Records a `map_completed` orchestration event in SQLite
+
+The dashboard picks this up via `DbSyncWatcher` for real-time updates.
+
+**Alternative: read from existing file** (for manual use or debugging):
+
+```bash
+ocr state map-complete --file "map/runs/run-1/map-meta.json"
+```
+
+Optional flags (both modes):
+```bash
+--session-id "{session-id}"   # Auto-detects active session if omitted
+--map-run 1                   # Auto-detects current map run if omitted
+```
+
 ### `ocr state sync` — Rebuild from filesystem
 
 ```bash

package/skills/ocr/references/workflow.md

@@ -129,7 +129,7 @@ Before proceeding to each phase, verify the required artifacts exist:
 | 4 | `context.md` exists | `rounds/round-{n}/reviews/{type}-{n}.md` for each reviewer; call `ocr state transition` |
 | 5 | ≥2 files in `rounds/round-{n}/reviews/` | Aggregated findings (inline); call `ocr state transition` |
 | 6 | Reviews complete | `rounds/round-{n}/discourse.md`; call `ocr state transition` |
-| 7 | `rounds/round-{n}/discourse.md` exists | `rounds/round-{n}/final.md`; call `ocr state transition` |
+| 7 | `rounds/round-{n}/discourse.md` exists | `rounds/round-{n}/round-meta.json`, `rounds/round-{n}/final.md`; call `ocr state round-complete` |
 | 8 | `rounds/round-{n}/final.md` exists | Present to user; call `ocr state close` |
 
 **NEVER skip directly to `final.md`** — this breaks progress tracking.
@@ -592,11 +592,11 @@ See `references/discourse.md` for detailed instructions.
    - Challenged and defended: +1
    - Challenged and undefended: -1
 
-4. Categorize findings:
-   - **Must Fix**: Critical issues, security vulnerabilities
-   - **Should Fix**: Important improvements
-   - **Consider**: Nice-to-haves, style suggestions
-   - **What's Working Well**: Positive feedback
+4. Categorize findings into three sections (see `references/final-template.md` for criteria):
+   - **Blockers**: Security vulnerabilities, data integrity risks, correctness bugs, breaking changes — must resolve before merge
+   - **Should Fix**: Code quality issues, potential bugs, missing validation, important refactors — address before or shortly after merge
+   - **Suggestions**: Style preferences, minor refactors, documentation, testing ideas — author's discretion
+   - **What's Working Well**: Positive feedback (separate encouragement section, not counted)
 
 5. **If requirements were provided**, include Requirements Assessment:
    - Which requirements are fully met?
@@ -612,7 +612,57 @@ See `references/discourse.md` for detailed instructions.
 
    These go in a prominent "Clarifying Questions" section for stakeholder response.
 
-7. **Write the final review file**:
+7. **Pipe structured round data to the CLI (BEFORE `final.md`)**:
+
+   > The CLI is the **sole writer** of `round-meta.json`. The orchestrator constructs JSON in memory and pipes it to the CLI, which validates the schema, writes the file to the correct session path, and records a `round_completed` orchestration event — all in one command.
+
+   Construct the JSON from synthesis knowledge, then pipe to the CLI:
+
+   ```bash
+   cat <<'JSON' | ocr state round-complete --stdin
+   {
+     "schema_version": 1,
+     "verdict": "REQUEST CHANGES",
+     "reviewers": [
+       {
+         "type": "principal",
+         "instance": 1,
+         "severity_high": 1,
+         "severity_medium": 4,
+         "severity_low": 2,
+         "severity_info": 0,
+         "findings": [
+           {
+             "title": "SQL Injection in query builder",
+             "category": "blocker",
+             "severity": "high",
+             "file_path": "src/db/query.ts",
+             "line_start": 42,
+             "line_end": 45,
+             "summary": "User input passed directly to raw SQL...",
+             "flagged_by": ["@principal-1", "@security-1"]
+           }
+         ]
+       }
+     ]
+   }
+   JSON
+   ```
+
+   The CLI will:
+   1. Validate the JSON schema (schema_version, verdict, reviewers, findings)
+   2. Write `round-meta.json` to `{session_dir}/rounds/round-{n}/round-meta.json`
+   3. Compute derived counts from the findings array (never self-reported)
+   4. Record a `round_completed` orchestration event in SQLite
+
+   **Finding categories**: `"blocker"` | `"should_fix"` | `"suggestion"` | `"style"`
+   **Finding severity**: `"critical"` | `"high"` | `"medium"` | `"low"` | `"info"`
+
+   Optional flags: `--session-id <id>` (auto-detects active session), `--round <number>` (auto-detects current round).
+
+   > **Do NOT write `round-meta.json` directly** — always pipe through the CLI so the schema is validated and the event is recorded atomically.
+
+8. **Write the final review file**:
    ```bash
    # OUTPUT FILE - must be exactly this path:
    FINAL_FILE="$SESSION_DIR/rounds/round-$CURRENT_ROUND/final.md"
@@ -620,7 +670,7 @@ See `references/discourse.md` for detailed instructions.
 
    Save synthesized review to `$FINAL_FILE`.
 
-See `references/final-template.md` for the template format.
+   See `references/final-template.md` for the template format.
 
 ### Phase 7 Checkpoint — MANDATORY VALIDATION
 
@@ -630,9 +680,18 @@ See `references/final-template.md` for the template format.
 # Set these based on your current session
 SESSION_DIR=".ocr/sessions/$(ls -1t .ocr/sessions/ | head -1)"
 CURRENT_ROUND=$(ls -1d "$SESSION_DIR/rounds/round-"* 2>/dev/null | wc -l | tr -d ' ')
+ROUND_META="$SESSION_DIR/rounds/round-$CURRENT_ROUND/round-meta.json"
 FINAL_FILE="$SESSION_DIR/rounds/round-$CURRENT_ROUND/final.md"
 
-# Check file exists
+# Check round-meta.json exists
+if [ -f "$ROUND_META" ]; then
+  echo "OK round-meta.json exists at $ROUND_META"
+else
+  echo "FAIL round-meta.json not found at $ROUND_META"
+  exit 1
+fi
+
+# Check final.md exists
 if [ -f "$FINAL_FILE" ]; then
   echo "OK final.md exists at $FINAL_FILE"
 else
@@ -650,8 +709,9 @@ fi
 ```
 
 **STOP and verify before proceeding:**
+- [ ] `rounds/round-{n}/round-meta.json` exists with valid structured data
 - [ ] `rounds/round-{n}/final.md` exists
-- [ ] Contains prioritized findings (Must Fix, Should Fix, Consider)
+- [ ] Contains categorized findings (Blockers, Should Fix, Suggestions)
 - [ ] Contains Clarifying Questions section (if any)
 - [ ] If requirements provided: Contains Requirements Assessment
 
@@ -670,9 +730,9 @@ fi
    # Code Review: {branch}
 
    ## Summary
-   {X} must-fix, {Y} should-fix, {Z} suggestions
+   {X} blockers, {Y} should-fix, {Z} suggestions
 
-   ## Must Fix
+   ## Blockers
    ...
 
    ## Should Fix
@@ -713,5 +773,5 @@ fi
 | 4 | Spawn reviewer tasks, `ocr state transition` | `rounds/round-{n}/reviews/*.md` |
 | 5 | Compare redundant runs, `ocr state transition` | aggregated findings |
 | 6 | Reviewer discourse, `ocr state transition` | `rounds/round-{n}/discourse.md` |
-| 7 | Synthesize and prioritize, `ocr state transition` | `rounds/round-{n}/final.md` |
+| 7 | Synthesize, pipe data to `ocr state round-complete --stdin`, write `final.md` | `rounds/round-{n}/round-meta.json` (CLI-written), `rounds/round-{n}/final.md` |
 | 8 | Display/post, `ocr state close` | Terminal output, GitHub |