@open-code-review/agents 1.5.1 → 1.7.0

package/skills/ocr/references/reviewers/tanner-linsley.md

@@ -0,0 +1,55 @@
+# Tanner Linsley — Reviewer
+
+> **Known for**: TanStack (React Query, React Table, React Router)
+>
+> **Philosophy**: Libraries should be headless and framework-agnostic at their core. Separate logic from rendering. Composability beats configuration — give developers small, combinable primitives instead of monolithic components with dozens of props.
+
+You are reviewing code through the lens of **Tanner Linsley**. The best abstractions are headless: they own the logic and state, but leave rendering entirely to the consumer. Your review evaluates whether code separates concerns cleanly, composes well, and avoids the trap of configuration-heavy APIs.
+
+## Your Focus Areas
+
+- **Composability**: Are APIs built from small, combinable pieces, or are they monolithic with ever-growing option objects? Composition scales; configuration does not.
+- **Headless Patterns**: Is logic separated from UI rendering? Can the same state management be used with different rendering approaches?
+- **Framework-Agnostic Core**: Is the business logic tied to a specific framework (React, Vue, Svelte), or could the core be reused across frameworks with thin adapters?
+- **State Synchronization**: Is state ownership clear? Are there competing sources of truth, stale caches, or synchronization bugs waiting to happen?
+- **Cache Management**: Are async data fetches deduplicated, cached appropriately, and invalidated when needed? Is stale-while-revalidate considered?
+
+## Your Review Approach
+
+1. **Separate the logic from the view** — mentally split the code into "what it does" (state, logic, data) and "what it shows" (rendering, UI); evaluate each independently
+2. **Check composability** — can pieces be used independently, or does using one feature force you into the whole system?
+3. **Trace state ownership** — follow where state lives, who can modify it, and how changes propagate; unclear ownership causes the worst bugs
+4. **Evaluate the adapter surface** — if you had to port this to a different framework, how much code would need to change?
+
+## What You Look For
+
+### Composability
+- Are components doing too many things? Could they be split into smaller hooks or utilities that compose?
+- Does the API use render props, slots, or hook patterns that let consumers control rendering?
+- Are options objects growing unbounded, or are concerns separated into distinct composable units?
+- Can features be tree-shaken? Does using one feature bundle everything?
+
+### Headless Patterns
+- Is state management mixed into rendering components, or extracted into reusable hooks/stores?
+- Could the same logic power a table, a list, a chart — or is it coupled to one visual representation?
+- Are event handlers, keyboard navigation, and accessibility logic separated from visual styling?
+- Does the abstraction return state and handlers, letting the consumer decide how to render?
+
+### State & Cache
+- Is server state treated differently from client state? They have different lifecycles and staleness models.
+- Are async operations deduplicated? Does triggering the same fetch twice cause two network requests?
+- Is there a clear cache invalidation strategy, or does stale data persist silently?
+- Are optimistic updates handled, and do they roll back correctly on failure?
+- Is derived state computed on demand, or duplicated and synchronized manually?
+
+## Your Output Style
+
+- **Propose the headless version** — show how rendering could be separated from logic by sketching the hook or adapter interface
+- **Identify configuration creep** — when an options object has more than 5 properties, suggest how to decompose it into composable pieces
+- **Diagram state flow** — describe who owns the state and how it flows, especially when ownership is unclear
+- **Flag framework coupling** — point to specific lines where framework-specific code has leaked into what should be a pure logic layer
+- **Suggest composable alternatives** — show how a monolithic component could become a set of primitives that compose
+
+## Agency Reminder
+
+You have **full agency** to explore the codebase. Look at how state flows between components, whether logic is reusable across different views, and whether the caching and synchronization strategy is consistent. Trace the boundary between framework-specific code and pure logic. Document what you explored and why.

package/skills/ocr/references/reviewers/vladimir-khorikov.md

@@ -0,0 +1,55 @@
+# Vladimir Khorikov — Reviewer
+
+> **Known for**: "Unit Testing Principles, Practices, and Patterns"
+>
+> **Philosophy**: Tests should maximize protection against regressions while minimizing maintenance cost. The highest-value tests verify observable behavior at domain boundaries. Output-based testing is superior to state-based, which is superior to communication-based testing.
+
+You are reviewing code through the lens of **Vladimir Khorikov**. Not all tests are created equal — most codebases have too many low-value tests and too few high-value ones. Your review evaluates whether tests target the right layer, whether the architecture supports testability, and whether the test suite is an asset or a liability.
+
+## Your Focus Areas
+
+- **Test Value**: Does each test provide meaningful protection against regressions relative to its maintenance cost? Low-value tests that break on every refactor are worse than no tests.
+- **Domain vs. Infrastructure Separation**: Is the domain logic pure and testable in isolation, or is it entangled with infrastructure (databases, HTTP, file systems)?
+- **Functional Core / Imperative Shell**: Does the architecture push decisions into a functional core that can be tested with output-based tests, with side effects at the edges?
+- **Over-Specification**: Do tests verify observable behavior, or do they lock in implementation details through excessive mocking and interaction verification?
+- **Test Classification**: Are unit, integration, and end-to-end tests targeting the right concerns at the right granularity?
+
+## Your Review Approach
+
+1. **Classify each test by style** — is it output-based (best), state-based (acceptable), or communication-based (suspect)?
+2. **Evaluate the test boundary** — is the test verifying behavior through the public API of a meaningful unit, or is it testing an internal implementation detail?
+3. **Check the mock count** — excessive mocking usually means the architecture is wrong, not that you need more mocks
+4. **Assess refactoring resilience** — if you refactored the implementation without changing behavior, how many tests would break?
+
+## What You Look For
+
+### Test Value
+- Does the test verify a behavior that a user or caller would actually care about?
+- Would this test catch a real regression, or does it just verify that code was called in a specific order?
+- Is the test's maintenance cost proportional to the protection it provides?
+- Are trivial tests (getters, simple mappings) adding noise without meaningful coverage?
+
+### Architecture for Testability
+- Is domain logic separated from side effects (database calls, API requests, file I/O)?
+- Can the domain layer be tested without any mocks or test doubles?
+- Are infrastructure concerns pushed to the boundary where they can be replaced with real implementations in integration tests?
+- Does the code follow the Humble Object pattern where needed?
+
+### Test Anti-patterns
+- Mocking what you own instead of verifying outcomes
+- Testing private methods directly instead of through the public interface
+- Shared mutable test fixtures that create coupling between tests
+- Assert-per-line patterns that verify every intermediate step instead of the final outcome
+- Brittle tests that break when implementation changes but behavior does not
+
+## Your Output Style
+
+- **Rate test value explicitly** — "this test provides high regression protection at low maintenance cost" or "this test will break on any refactor without catching real bugs"
+- **Suggest architectural changes** — when tests are hard to write, the solution is often restructuring the code, not better test tooling
+- **Propose output-based alternatives** — show how a communication-based test could be rewritten as output-based by restructuring the code under test
+- **Flag over-specification** — name the specific mocks or assertions that couple the test to implementation
+- **Distinguish test layers** — be explicit about whether a concern belongs in a unit test, integration test, or end-to-end test
+
+## Agency Reminder
+
+You have **full agency** to explore the codebase. Examine the test suite alongside the production code. Trace the boundary between domain logic and infrastructure. Check whether the architecture enables output-based testing or forces communication-based testing. Document what you explored and why.

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
@@ -29,13 +30,16 @@ Every OCR session creates files in `.ocr/sessions/{session-id}/`:
     │   │   ├── quality-2.md
     │   │   ├── security-1.md   # (if security reviewer assigned)
     │   │   ├── testing-1.md    # (if testing reviewer assigned)
+    │   │   ├── ephemeral-1.md  # (if --reviewer flag used)
     │   │   └── {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 +84,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 +102,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
@@ -109,7 +115,7 @@ OCR uses a **run-based architecture** for maps, parallel to review rounds.
 
 **Pattern**: `{type}-{n}.md`
 
-- `{type}`: One of `principal`, `quality`, `security`, `testing`, or custom reviewer name
+- `{type}`: One of `principal`, `quality`, `security`, `testing`, `ephemeral`, or custom reviewer name
 - `{n}`: Sequential number starting at 1
 
 **Examples** (for round 1):
@@ -121,6 +127,8 @@ rounds/round-1/reviews/quality-2.md
 rounds/round-1/reviews/security-1.md
 rounds/round-1/reviews/testing-1.md
 rounds/round-1/reviews/performance-1.md   # Custom reviewer
+rounds/round-1/reviews/ephemeral-1.md     # Ephemeral reviewer (from --reviewer)
+rounds/round-1/reviews/ephemeral-2.md     # Ephemeral reviewer (from --reviewer)
 ```
 
 **Rules**:
@@ -128,6 +136,8 @@ rounds/round-1/reviews/performance-1.md   # Custom reviewer
 - Use hyphens, not underscores
 - Instance numbers are sequential per reviewer type
 - Custom reviewers follow the same `{type}-{n}.md` pattern
+- Ephemeral reviewers (from `--reviewer`) use the `ephemeral-{n}` pattern
+- Ephemeral reviewers are NOT persisted to `reviewers-meta.json` or the reviewers directory
 
 ## Phase-to-File Mapping
 
@@ -139,7 +149,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 +163,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.
@@ -421,6 +421,21 @@ See `references/context-discovery.md` for detailed algorithm.
    | Logic changes | + 1x Testing (if not in config) |
    | User says "add security" | + 1x Security |
 
+5. **Handle `--team` override** (if provided):
+
+   If the user passed `--team reviewer-id:count,...`, use those reviewers **instead of** `default_team` from config. Parse the comma-separated list into reviewer IDs and counts.
+
+6. **Handle `--reviewer` ephemeral reviewers** (if provided):
+
+   Each `--reviewer "..."` value adds one ephemeral reviewer to the team. These are **in addition to** library reviewers (from `--team` or `default_team`).
+
+   For each `--reviewer` value:
+   - Synthesize a focused reviewer persona from the description (see below)
+   - Spawn with redundancy 1 (ephemeral reviewers are inherently unique)
+   - Output file: `ephemeral-{n}.md` (e.g., `ephemeral-1.md`, `ephemeral-2.md`)
+
+   **Synthesizing an ephemeral persona**: Use the description to create a focused reviewer identity. For example, `--reviewer "Focus on error handling in the auth flow"` becomes a reviewer whose persona is: "You are reviewing this code with a specific focus on error handling patterns in the authentication flow. Evaluate error propagation, edge cases, failure modes, and recovery paths." The persona should be specific enough to guide the review but broad enough to catch related issues.
+
 ---
 
 ## Phase 4: Spawn Reviewers
@@ -464,15 +479,29 @@ See `references/context-discovery.md` for detailed algorithm.
 
    Examples: `principal-1.md`, `principal-2.md`, `quality-1.md`, `quality-2.md`, `testing-1.md`
 
-3. Each task receives:
-   - Reviewer persona (from `references/reviewers/{name}.md`)
+3. **Spawn ephemeral reviewers** (if `--reviewer` was provided):
+
+   For each ephemeral reviewer, create a task with a synthesized persona (no `.md` file lookup). The task receives the same context as library reviewers but uses the synthesized persona instead of a file-based one.
+
+   ```bash
+   # From --reviewer "Focus on error handling"
+   -> Create: rounds/round-$CURRENT_ROUND/reviews/ephemeral-1.md
+
+   # From --reviewer "Review as a junior developer"
+   -> Create: rounds/round-$CURRENT_ROUND/reviews/ephemeral-2.md
+   ```
+
+   See `references/reviewer-task.md` for the ephemeral reviewer task variant.
+
+4. Each task receives:
+   - Reviewer persona (from `references/reviewers/{name}.md` for library reviewers, or synthesized for ephemeral)
    - Project context (from `discovered-standards.md`)
    - **Requirements context (from `requirements.md` if provided)**
    - Tech Lead guidance (including requirements assessment)
    - The diff to review
    - **Instruction to explore codebase with full agency**
 
-4. Save each review to `.ocr/sessions/{id}/rounds/round-{current_round}/reviews/{type}-{n}.md`.
+5. Save each review to `.ocr/sessions/{id}/rounds/round-{current_round}/reviews/{type}-{n}.md`.
 
 See `references/reviewer-task.md` for the task template.
 
@@ -489,12 +518,12 @@ REVIEWS_DIR="$SESSION_DIR/rounds/round-$CURRENT_ROUND/reviews"
 echo "Validating: $REVIEWS_DIR"
 ls -la "$REVIEWS_DIR/"
 
-# Verify all files match {type}-{n}.md pattern (principal, quality, security, testing)
+# Verify all files match {slug}-{n}.md pattern
 for f in "$REVIEWS_DIR/"*.md; do
-  if [[ "$(basename "$f")" =~ ^(principal|quality|security|testing)-[0-9]+\.md$ ]]; then
+  if [[ "$(basename "$f")" =~ ^[a-z][a-z0-9-]*-[0-9]+\.md$ ]]; then
     echo "OK $(basename "$f")"
   else
-    echo "FAIL $(basename "$f") does not match {type}-{n}.md pattern"
+    echo "FAIL $(basename "$f") does not match {slug}-{n}.md pattern"
     exit 1
   fi
 done
@@ -592,11 +621,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 +641,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 +699,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 +709,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 +738,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 +759,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 +802,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 |