@open-code-review/agents 1.1.0 → 1.2.0

package/README.md

@@ -1,35 +1,33 @@
 # @open-code-review/agents
 
-The core skill definitions, reviewer personas, and workflow references for Open Code Review.
+The skill definitions, reviewer personas, and workflow references that power Open Code Review.
 
 ## What This Package Contains
 
-This package provides the AI-readable assets that power multi-agent code review:
-
 ```
 agents/
-├── skills/ocr/           # The OCR skill
-│   ├── SKILL.md          # Tech Lead orchestration logic
+├── skills/ocr/              # The OCR skill
+│   ├── SKILL.md             # Tech Lead orchestration logic
 │   ├── references/
-│   │   ├── workflow.md   # 8-phase review workflow
-│   │   ├── discourse.md  # Multi-agent debate rules
-│   │   ├── synthesis.md  # Finding aggregation guide
-│   │   └── reviewers/    # Persona definitions
-│   │       ├── principal.md
-│   │       ├── quality.md
-│   │       ├── security.md
-│   │       └── testing.md
+│   │   ├── workflow.md      # 8-phase review workflow
+│   │   ├── discourse.md     # Multi-agent debate rules
+│   │   ├── synthesis.md     # Finding aggregation guide
+│   │   └── 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
 │   └── assets/
-│       ├── config.yaml   # Default configuration
+│       ├── config.yaml      # Default configuration
 │       └── reviewer-template.md
-├── commands/             # Slash command definitions
+├── commands/                # Slash command definitions
 │   ├── review.md
 │   ├── doctor.md
 │   ├── history.md
 │   ├── show.md
 │   ├── reviewers.md
 │   └── post.md
-└── .claude-plugin/       # Claude Code plugin manifest
+└── .claude-plugin/          # Claude Code plugin manifest
     └── plugin.json
 ```
 
@@ -37,7 +35,7 @@ agents/
 
 ### Via CLI (Recommended)
 
-The CLI copies these assets to your project's `.ocr/` directory and configures your AI tools:
+The CLI copies these assets to your project's `.ocr/` directory:
 
 ```bash
 npx @open-code-review/cli init
@@ -45,46 +43,57 @@ npx @open-code-review/cli init
 
 ### Via Claude Code Plugin
 
-For Claude Code users who prefer plugin-based installation:
-
 ```bash
-# Add the marketplace
 /plugin marketplace add spencermarx/open-code-review
-
-# Install the plugin
-/plugin install open-code-review@spencermarx-open-code-review
-```
-
-### Local Development
-
-Test the plugin locally with Claude Code:
-
-```bash
-claude --plugin-dir ./packages/agents
+/plugin install ocr@aclarify
 ```
 
 ## Skill Architecture
 
-The `skills/ocr/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
-3. Selects and spawns reviewer personas
+3. Selects and spawns reviewer personas based on your team configuration
 4. Facilitates discourse between reviewers
 5. Synthesizes findings into a unified review
 
-Each reviewer in `references/reviewers/` is a specialized persona with distinct focus areas and anti-patterns to flag.
+Each reviewer in `references/reviewers/` is a specialized persona. You can customize the built-in reviewers or add your own.
+
+## Session Structure
+
+OCR uses a **round-first architecture** for session storage:
+
+```
+.ocr/sessions/{YYYY-MM-DD}-{branch}/
+├── state.json              # Workflow state (current_round, phase)
+├── 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
+        └── ...
+```
+
+**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.
+
+See `references/session-files.md` for the complete file manifest.
 
 ## Commands
 
-| File | CLI Command | Plugin Command |
-|------|-------------|----------------|
-| `review.md` | `/ocr-review` | `/open-code-review:review` |
-| `doctor.md` | `/ocr-doctor` | `/open-code-review:doctor` |
-| `reviewers.md` | `/ocr-reviewers` | `/open-code-review:reviewers` |
-| `history.md` | `/ocr-history` | `/open-code-review:history` |
-| `show.md` | `/ocr-show` | `/open-code-review:show` |
-| `post.md` | `/ocr-post` | `/open-code-review:post` |
+| File | Windsurf | Claude Code / Cursor |
+|------|----------|----------------------|
+| `review.md` | `/ocr-review` | `/ocr:review` |
+| `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.
 
 ## License
 

package/commands/post.md

@@ -21,8 +21,9 @@ tags: [ocr, github, pr]
 
 1. Verify `gh` is available and authenticated
 2. Find the PR for current branch
-3. Read the session's `final.md`
-4. Post as PR comment via `gh pr comment`
+3. Determine current round from `state.json` → `current_round` (or enumerate `rounds/` directory)
+4. Read the session's `rounds/round-{current_round}/final.md`
+5. Post as PR comment via `gh pr comment`
 
 **Reference**
 - Run `/ocr-doctor` to check GitHub CLI status

package/commands/review.md

@@ -45,15 +45,18 @@ ls -la .ocr/sessions/$(date +%Y-%m-%d)-* 2>/dev/null
 
 ### Step 2: If session exists, verify state
 
-Read `state.json` AND verify actual files match:
+Read `state.json` AND verify actual files match (see `references/session-files.md` for authoritative names):
 
-| Phase | state.json says | Verify file exists |
-|-------|-----------------|-------------------|
-| context | `completed_phases` includes "context" | `.ocr/sessions/{id}/context.md` |
-| requirements | `completed_phases` includes "requirements" | `.ocr/sessions/{id}/discovered-standards.md` |
-| reviews | `completed_phases` includes "reviews" | At least 2 files in `.ocr/sessions/{id}/reviews/` |
-| discourse | `completed_phases` includes "discourse" | `.ocr/sessions/{id}/discourse.md` |
-| synthesis | `completed_phases` includes "synthesis" | `.ocr/sessions/{id}/final.md` |
+| Phase | Verify file exists |
+|-------|-------------------|
+| context | `.ocr/sessions/{id}/discovered-standards.md` |
+| change-context | `.ocr/sessions/{id}/context.md` |
+| analysis | `.ocr/sessions/{id}/context.md` (with Tech Lead guidance section) |
+| reviews | At least 2 files in `.ocr/sessions/{id}/rounds/round-{n}/reviews/` |
+| discourse | `.ocr/sessions/{id}/rounds/round-{n}/discourse.md` |
+| synthesis | `.ocr/sessions/{id}/rounds/round-{n}/final.md` |
+
+> **Note**: Phase completion is derived from filesystem (file existence), not from `state.json`. The `current_phase` field indicates which phase is active.
 
 ### Step 3: Determine action
 
@@ -67,27 +70,34 @@ Read `state.json` AND verify actual files match:
 
 ## ⚠️ CRITICAL: Required Artifacts (Must Create In Order)
 
+> **See `references/session-files.md` for the authoritative file manifest.**
+
 You MUST create these files sequentially. **Do NOT skip to `final.md`.**
 
 ```
-.ocr/sessions/{id}/
-├── context.md              # Phase 2: WRITE FIRST - change summary
+.ocr/sessions/{YYYY-MM-DD}-{branch}/
+├── state.json              # Phase 1: session state (REQUIRED)
 ├── discovered-standards.md # Phase 1: merged project standards  
-├── reviews/
-│   ├── principal-1.md      # Phase 4: individual reviewer output
-│   ├── principal-2.md      # Phase 4: individual reviewer output
-│   ├── quality-1.md        # Phase 4: individual reviewer output
-│   └── {reviewer}-{n}.md    # Phase 4: individual reviewer output
-├── discourse.md            # Phase 6: reviewer cross-discussion
-└── final.md                # Phase 7: ONLY after all above exist
+├── requirements.md         # Phase 1: user requirements (if provided)
+├── context.md              # Phase 2+3: change summary + Tech Lead guidance
+└── rounds/
+    └── round-1/            # Review round (increments on re-review)
+        ├── reviews/
+        │   ├── principal-1.md  # Phase 4: reviewer output
+        │   ├── principal-2.md  # Phase 4: reviewer output
+        │   ├── quality-1.md    # Phase 4: reviewer output
+        │   └── quality-2.md    # Phase 4: reviewer output
+        ├── discourse.md        # Phase 6: reviewer cross-discussion
+        └── final.md            # Phase 7: ONLY after all above exist
 ```
 
 ### Checkpoint Rules
 
-1. **Before Phase 4** (Spawn Reviewers): `context.md` MUST exist
-2. **Before Phase 6** (Discourse): At least 2 files in `reviews/` MUST exist
-3. **Before Phase 7** (Synthesis): `discourse.md` MUST exist
-4. **NEVER** write `final.md` without completing Phases 1-6
+1. **Before Phase 2** (Change Analysis): `discovered-standards.md` MUST exist
+2. **Before Phase 4** (Spawn Reviewers): `context.md` MUST exist
+3. **Before Phase 6** (Discourse): At least 2 files in `rounds/round-{n}/reviews/` MUST exist
+4. **Before Phase 7** (Synthesis): `rounds/round-{n}/discourse.md` MUST exist
+5. **NEVER** write `rounds/round-{n}/final.md` without completing Phases 1-6
 
 ### Why This Matters
 

package/commands/show.md

@@ -16,8 +16,9 @@ tags: [ocr, history, sessions]
 **Steps**
 
 1. If no session specified, find most recent in `.ocr/sessions/`
-2. Read and display `final.md` (synthesized review)
-3. Optionally show individual reviewer files if requested
+2. Determine current round from `state.json` → `current_round` (or enumerate `rounds/` directory)
+3. Read and display `rounds/round-{current_round}/final.md` (synthesized review)
+4. Optionally show individual reviewer files from `rounds/round-{n}/reviews/` if requested
 
 **Reference**
 - Use `/ocr-history` to list all sessions

package/package.json

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

package/skills/ocr/AGENTS.md

@@ -36,6 +36,8 @@ When asked to perform a code review:
 
 - `SKILL.md` - Core skill definition and Tech Lead role
 - `references/workflow.md` - Complete 8-phase workflow
+- `references/session-files.md` - **Authoritative session file manifest**
+- `references/session-state.md` - State management and progress tracking
 - `references/synthesis.md` - How to synthesize findings
 - `references/discourse.md` - Multi-agent discourse rules
 - `references/reviewers/` - Reviewer persona definitions

package/skills/ocr/SKILL.md

@@ -135,13 +135,19 @@ For complete workflow details, see `references/workflow.md`.
 
 ## Session Storage
 
-All review artifacts are stored in `.ocr/sessions/{date}-{branch}/`:
-- `context.md` - Change summary
-- `requirements.md` - User-provided requirements/specs (if any)
-- `discovered-standards.md` - Merged project context
-- `reviews/{reviewer}-{n}.md` - Individual reviews
-- `discourse.md` - Discourse results
-- `final.md` - Synthesized final review
+> **See `references/session-files.md` for the authoritative file manifest.**
+
+All review artifacts are stored in `.ocr/sessions/{YYYY-MM-DD}-{branch}/`:
+
+| File | Description |
+|------|-------------|
+| `state.json` | Session state for progress tracking |
+| `discovered-standards.md` | Merged project context (shared) |
+| `requirements.md` | User-provided requirements (shared, if any) |
+| `context.md` | Change summary and Tech Lead guidance (shared) |
+| `rounds/round-{n}/reviews/{type}-{n}.md` | Individual reviewer outputs (per-round) |
+| `rounds/round-{n}/discourse.md` | Cross-reviewer discussion (per-round) |
+| `rounds/round-{n}/final.md` | Synthesized final review (per-round) |
 
 ## Commands
 

package/skills/ocr/references/context-discovery.md

@@ -145,10 +145,10 @@ done
 
 ## Output Format
 
-Save discovered context to session directory:
+Save discovered context to session directory (see `references/session-files.md` for authoritative file names):
 
 ```
-.ocr/sessions/{id}/discovered-standards.md
+.ocr/sessions/{YYYY-MM-DD}-{branch}/discovered-standards.md
 ```
 
 ### Example Output

package/skills/ocr/references/discourse.md

@@ -29,14 +29,14 @@ Reviewers use these fixed response types (not user-configurable):
 
 ### Step 1: Compile Individual Reviews
 
-Gather all individual review outputs:
+Gather all individual review outputs from the current round (see `references/session-files.md` for naming convention):
 ```
-reviews/principal-1.md
-reviews/principal-2.md
-reviews/quality-1.md
-reviews/quality-2.md
-reviews/security-1.md (if included)
-reviews/testing-1.md (if included)
+rounds/round-{n}/reviews/principal-1.md
+rounds/round-{n}/reviews/principal-2.md
+rounds/round-{n}/reviews/quality-1.md
+rounds/round-{n}/reviews/quality-2.md
+rounds/round-{n}/reviews/security-1.md (if assigned)
+rounds/round-{n}/reviews/testing-1.md (if assigned)
 ```
 
 ### Step 2: Present All Findings
@@ -110,7 +110,7 @@ SURFACE
 
 ### Step 5: Compile Discourse Results
 
-Save to `discourse.md`:
+Save to `rounds/round-{n}/discourse.md`:
 
 ```markdown
 # Discourse Results

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

@@ -0,0 +1,215 @@
+# Session File Manifest
+
+> **This is the authoritative reference for session file naming.** All other documentation should reference this file for file names and structure.
+
+## Session Directory Structure
+
+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)
+└── rounds/                 # All round-specific artifacts
+    ├── round-1/            # First review round
+    │   ├── reviews/        # Individual reviewer outputs
+    │   │   ├── principal-1.md
+    │   │   ├── principal-2.md
+    │   │   ├── quality-1.md
+    │   │   ├── quality-2.md
+    │   │   ├── security-1.md   # (if security reviewer assigned)
+    │   │   ├── testing-1.md    # (if testing reviewer assigned)
+    │   │   └── {type}-{n}.md   # (additional assigned custom reviewers)
+    │   ├── discourse.md    # Cross-reviewer discussion for round 1
+    │   └── final.md        # Synthesized final review for round 1
+    └── round-2/            # Subsequent rounds (created on re-review)
+        ├── reviews/
+        │   └── ...         # Same structure as round-1
+        ├── discourse.md
+        └── final.md
+```
+
+## Review Rounds
+
+OCR uses a **round-first architecture** where all round-specific artifacts live under `rounds/round-{n}/`. This makes multi-round reviews a first-class concept.
+
+**Round behavior**:
+- First `/ocr-review` creates `rounds/round-1/` with `reviews/`, `discourse.md`, `final.md`
+- 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
+
+**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` | |
+
+**When to use multiple rounds**:
+- Author addresses feedback and requests re-review
+- Scope changes mid-review
+- Different reviewer team composition needed
+
+## 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 |
+| `rounds/round-{n}/discourse.md` | 6 | Cross-reviewer discussion results | Synthesis |
+| `rounds/round-{n}/final.md` | 7 | Synthesized final review | Show, Post commands |
+
+### Optional Files
+
+| File | When Created | Description |
+|------|--------------|-------------|
+| `requirements.md` | Phase 1 | User-provided requirements, specs, or acceptance criteria |
+
+## Reviewer File Naming
+
+**Pattern**: `{type}-{n}.md`
+
+- `{type}`: One of `principal`, `quality`, `security`, `testing`, or custom reviewer name
+- `{n}`: Sequential number starting at 1
+
+**Examples** (for round 1):
+```
+rounds/round-1/reviews/principal-1.md
+rounds/round-1/reviews/principal-2.md
+rounds/round-1/reviews/quality-1.md
+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
+```
+
+**Rules**:
+- Always lowercase
+- Use hyphens, not underscores
+- Instance numbers are sequential per reviewer type
+- Custom reviewers follow the same `{type}-{n}.md` pattern
+
+## Phase-to-File Mapping
+
+| 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"` |
+
+## State Transitions and File Validation
+
+When updating `state.json`, verify the corresponding file exists:
+
+| Phase | Verify file exists |
+|---------------------------|-------------------|
+| `"context"` | `discovered-standards.md` |
+| `"change-context"` | `context.md` |
+| `"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` |
+
+## Session ID Format
+
+**Pattern**: `{YYYY-MM-DD}-{branch-name}`
+
+> **Shorthand**: In documentation, `{id}` and `{session-id}` are aliases for the full `{YYYY-MM-DD}-{branch-name}` format.
+
+- Date in ISO format (YYYY-MM-DD)
+- Branch name with `/` replaced by `-`
+
+**Examples**:
+```
+2026-01-27-main
+2026-01-27-feat-add-auth
+2026-01-27-fix-bug-123
+```
+
+**Generation**:
+```bash
+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
+
+See `references/session-state.md` for complete state management details.
+
+### Reviewer Files
+
+Each `rounds/round-{n}/reviews/{type}-{n}.md` must include:
+- Summary section
+- Findings with severity, location, and suggestions
+- What's Working Well section
+- Questions for Other Reviewers section
+
+See `references/reviewer-task.md` for complete output format.
+
+### final.md
+
+Must include:
+- Verdict (APPROVE / REQUEST CHANGES / NEEDS DISCUSSION)
+- Blockers section (if any)
+- Suggestions section
+- Requirements Assessment (if requirements provided)
+- Clarifying Questions section
+- Individual Reviews table with file references
+
+See `references/synthesis.md` for complete template.
+
+## CLI Dependencies
+
+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) |
+| Reviewer progress | `rounds/round-{n}/reviews/*.md` file existence |
+| Round completion | `rounds/round-{n}/final.md` existence |
+| Elapsed time | `state.json` → `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:
+1. Enumerating `rounds/round-*/` to count rounds
+2. Checking `final.md` presence to determine completion
+3. Listing `reviews/*.md` to identify reviewers
+
+**IMPORTANT**: Non-standard file names will break progress tracking.

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

@@ -18,25 +18,36 @@ This means:
 - 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/`
 
-## State File Format
+## State File Format (Minimal Schema)
 
 ```json
 {
-  "session_id": "2026-01-26-main",
-  "branch": "main",
+  "session_id": "{session-id}",
   "status": "active",
-  "started_at": "2026-01-26T17:00:00Z",
   "current_phase": "reviews",
   "phase_number": 4,
-  "completed_phases": ["context", "requirements", "analysis"],
-  "reviewers": {
-    "assigned": ["principal-1", "principal-2", "quality-1", "quality-2"],
-    "complete": ["principal-1"]
-  },
-  "updated_at": "2026-01-26T17:05:00Z"
+  "current_round": 1,
+  "started_at": "{ISO-8601-TIMESTAMP}",
+  "round_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.
+
+**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)
+- `updated_at`: Last modification time (updated at every phase transition)
+
+**Derived from filesystem** (not stored):
+- 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
+
+**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.
+
 ## Session Status
 
 The `status` field controls session visibility:
@@ -55,54 +66,78 @@ The `ocr progress` command only auto-detects sessions with `status: "active"`. C
 
 ## Phase Transitions
 
+> **See `references/session-files.md` for the authoritative file manifest.**
+
 The Tech Lead MUST update `state.json` at each phase boundary:
 
-| Phase | When to Update |
-|-------|---------------|
-| context | After writing `discovered-standards.md` |
-| requirements | After writing `requirements.md` (if any) |
-| analysis | After writing `context.md` with guidance |
-| reviews | After spawning each reviewer (update `reviewers.complete`) |
-| discourse | After writing `discourse.md` |
-| synthesis | After writing `final.md` |
-| complete | After presenting to user, set `status: "closed"` |
+| Phase | When to Update | 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"` |
 
 ## Writing State
 
-When transitioning phases:
+**CRITICAL**: Always generate timestamps dynamically using the current UTC time in ISO 8601 format.
+
+### Generating Timestamps
 
 ```bash
-# Create or update state.json
-cat > .ocr/sessions/{id}/state.json << 'EOF'
+# 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
+
+# Node.js / JavaScript
+new Date().toISOString()
+```
+
+When creating a new session (Phase 1 start):
+
+```json
 {
-  "session_id": "{id}",
+  "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}"
+}
+```
+
+When transitioning phases (preserve `started_at`, update `updated_at`):
+
+```json
+{
+  "session_id": "{session-id}",
   "status": "active",
   "current_phase": "reviews",
   "phase_number": 4,
-  "completed_phases": ["context", "requirements", "analysis"],
-  "reviewers": {
-    "assigned": ["principal-1", "principal-2", "quality-1", "quality-2"],
-    "complete": []
-  },
-  "updated_at": "2026-01-26T17:05:00Z"
+  "current_round": 1,
+  "started_at": "{PRESERVE_ORIGINAL}",
+  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
 }
-EOF
 ```
 
 When closing a session (Phase 8 complete):
 
-```bash
-# Update state.json to close the session
-cat > .ocr/sessions/{id}/state.json << 'EOF'
+```json
 {
-  "session_id": "{id}",
+  "session_id": "{session-id}",
   "status": "closed",
   "current_phase": "complete",
   "phase_number": 8,
-  "completed_phases": ["context", "requirements", "analysis", "reviews", "aggregation", "discourse", "synthesis"],
-  "updated_at": "2026-01-26T17:30:00Z"
+  "current_round": 1,
+  "started_at": "{PRESERVE_ORIGINAL}",
+  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
 }
-EOF
 ```
 
 ## Benefits
@@ -115,6 +150,13 @@ EOF
 
 ## Important
 
-The `state.json` file is **required** for progress tracking. The CLI does NOT fall back to file existence checks. If `state.json` is missing or invalid, the progress command will show "Waiting for session..."
+The `state.json` file is the **primary** source for workflow progress. However, with the round-first architecture:
+
+- **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
 
-This ensures a single, dependable source of truth for session state.
+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

package/skills/ocr/references/synthesis.md

@@ -28,11 +28,11 @@ This synthesis process is designed to mirror how high-performing engineering tea
 
 ### Step 1: Gather All Feedback
 
-Collect without filtering:
-- All individual reviews (`reviews/*.md`)
-- Discourse results (`discourse.md`) if available
+Collect without filtering (see `references/session-files.md` for file names):
+- All individual reviews from current round (`rounds/round-{n}/reviews/{type}-{n}.md`)
+- Discourse results (`rounds/round-{n}/discourse.md`) if available
 - Requirements context (`requirements.md`) if provided
-- Tech Lead's original analysis
+- Tech Lead's original analysis from `context.md`
 
 **Critical**: Do not discard or "deduplicate away" any reviewer feedback at this stage.
 
@@ -270,13 +270,13 @@ Full reviews available in session directory:
 
 | Reviewer | Blockers | Suggestions | File |
 |----------|----------|-------------|------|
-| @principal-1 | 0 | 3 | `reviews/principal-1.md` |
-| @principal-2 | 0 | 2 | `reviews/principal-2.md` |
-| @quality-1 | 0 | 4 | `reviews/quality-1.md` |
-| @security-1 | 1 | 2 | `reviews/security-1.md` |
+| @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` |
 
 **Session**: `.ocr/sessions/{session-id}/`
-**Discourse**: `discourse.md`
+**Discourse**: `rounds/round-{n}/discourse.md`
 ```
 
 ---

package/skills/ocr/references/workflow.md

@@ -2,7 +2,7 @@
 
 Complete 8-phase process for multi-agent code review.
 
-> ⚠️ **CRITICAL**: You MUST update `state.json` at each phase transition. The `ocr progress` CLI reads this file for accurate tracking.
+> ⚠️ **CRITICAL**: You MUST update `state.json` **BEFORE starting work** on each phase. The `ocr progress` CLI reads this file for real-time tracking. Update the `current_phase` and `phase_number` immediately when transitioning—do not wait until the phase is complete.
 
 ---
 
@@ -27,21 +27,54 @@ ls -la "$SESSION_DIR" 2>/dev/null
 Delete the existing session and start from scratch:
 ```bash
 rm -rf "$SESSION_DIR"
-mkdir -p "$SESSION_DIR/reviews"
+mkdir -p "$SESSION_DIR/rounds/round-1/reviews"
 ```
 Then proceed to Phase 1.
 
 ### Step 3: If session exists, verify state matches files
 
-Read `state.json` and verify actual files exist:
+Read `state.json` and verify actual files exist (see `references/session-files.md` for authoritative names):
 
-| Phase Complete? | state.json check | File check |
-|-----------------|------------------|------------|
-| context | `"context"` in `completed_phases` | `context.md` exists |
-| requirements | `"requirements"` in `completed_phases` | `discovered-standards.md` exists |
-| reviews | `"reviews"` in `completed_phases` | ≥2 files in `reviews/` |
-| discourse | `"discourse"` in `completed_phases` | `discourse.md` exists |
-| synthesis | `"synthesis"` in `completed_phases` | `final.md` exists |
+| Phase Complete? | File check |
+|-----------------|------------|
+| context | `discovered-standards.md` exists |
+| change-context | `context.md` exists |
+| analysis | `context.md` has Tech Lead guidance section |
+| reviews | ≥2 files in `rounds/round-{current_round}/reviews/` |
+| discourse | `rounds/round-{current_round}/discourse.md` exists |
+| synthesis | `rounds/round-{current_round}/final.md` exists |
+
+> **Note**: Phase completion is derived from filesystem (file existence). The `current_phase` field in `state.json` indicates which phase is active, not what's complete.
+
+### Step 3b: Round Resolution Algorithm
+
+Determine which round to use:
+
+```bash
+ROUNDS_DIR="$SESSION_DIR/rounds"
+
+# Count existing rounds
+if [ ! -d "$ROUNDS_DIR" ]; then
+  CURRENT_ROUND=1
+  mkdir -p "$ROUNDS_DIR/round-1/reviews"
+else
+  # Find highest round number
+  HIGHEST=$(ls -1 "$ROUNDS_DIR" | grep -E '^round-[0-9]+$' | sed 's/round-//' | sort -n | tail -1)
+  HIGHEST=${HIGHEST:-0}
+  
+  # Check if highest round is complete (has final.md)
+  if [ -f "$ROUNDS_DIR/round-$HIGHEST/final.md" ]; then
+    # Start new round
+    CURRENT_ROUND=$((HIGHEST + 1))
+    mkdir -p "$ROUNDS_DIR/round-$CURRENT_ROUND/reviews"
+  else
+    # Resume existing round
+    CURRENT_ROUND=$HIGHEST
+  fi
+fi
+```
+
+Update `state.json` with `current_round` value. **When starting a new round (CURRENT_ROUND > 1), also set `round_started_at` to the current timestamp** so the CLI progress timer shows elapsed time for the current round, not the entire session.
 
 ### Step 4: Determine resume point
 
@@ -56,7 +89,6 @@ Before proceeding, tell the user:
 ```
 📍 Session: {session_id}
 📊 Current phase: {current_phase} (Phase {phase_number}/8)
-✅ Completed: {completed_phases}
 🔄 Action: [Starting fresh | Resuming from Phase X]
 ```
 
@@ -72,30 +104,37 @@ At **every phase transition**, update `.ocr/sessions/{id}/state.json`:
   "status": "active",
   "current_phase": "reviews",
   "phase_number": 4,
-  "completed_phases": ["context", "requirements", "analysis"],
-  "started_at": "2026-01-26T17:00:00Z",
-  "updated_at": "2026-01-26T17:05:00Z"
+  "current_round": 1,
+  "started_at": "{PRESERVE_ORIGINAL}",
+  "round_started_at": "{CURRENT_ISO_TIMESTAMP}",
+  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
 }
 ```
 
+**Minimal schema** — round metadata is derived from filesystem, not stored in state.json.
+
+**CRITICAL**: Generate timestamps dynamically (e.g., `date -u +"%Y-%m-%dT%H:%M:%SZ"` on macOS/Linux). Preserve `started_at` from session creation; set `round_started_at` when starting a new round (> 1); always update `updated_at` with current time.
+
 **Status values**: `active` (in progress), `closed` (complete and dismissed)
 
-**Phase values**: `context`, `requirements`, `analysis`, `reviews`, `aggregation`, `discourse`, `synthesis`, `complete`
+**Phase values**: `context`, `change-context`, `analysis`, `reviews`, `aggregation`, `discourse`, `synthesis`, `complete`
 
 ## Artifact Checklist
 
+> **See `references/session-files.md` for the authoritative file manifest.**
+
 Before proceeding to each phase, verify the required artifacts exist:
 
 | Phase | Required Before Starting | Artifact to Create |
 |-------|-------------------------|-------------------|
-| 1 | Session directory created | `discovered-standards.md`, `state.json` |
-| 2 | — | `context.md`, update `state.json` |
-| 3 | `context.md` exists | Tech Lead guidance (inline), update `state.json` |
-| 4 | `context.md` exists | `reviews/{reviewer}-{n}.md`, update `state.json` |
-| 5 | ≥2 files in `reviews/` | Aggregated findings (inline), update `state.json` |
-| 6 | Reviews complete | `discourse.md`, update `state.json` |
-| 7 | `discourse.md` exists | `final.md`, update `state.json` |
-| 8 | `final.md` exists | Present to user, set `status: "closed"` and `current_phase: "complete"` |
+| 1 | Session directory created | `state.json`, `discovered-standards.md`, `requirements.md` (if provided) |
+| 2 | `discovered-standards.md` exists | `context.md`, `rounds/round-1/reviews/` directory, update `state.json` |
+| 3 | `context.md` exists | Update `context.md` with Tech Lead guidance, update `state.json` |
+| 4 | `context.md` exists | `rounds/round-{n}/reviews/{type}-{n}.md` for each reviewer, update `state.json` |
+| 5 | ≥2 files in `rounds/round-{n}/reviews/` | Aggregated findings (inline), update `state.json` |
+| 6 | Reviews complete | `rounds/round-{n}/discourse.md`, update `state.json` |
+| 7 | `rounds/round-{n}/discourse.md` exists | `rounds/round-{n}/final.md`, update `state.json` |
+| 8 | `rounds/round-{n}/final.md` exists | Present to user, set `status: "closed"` and `current_phase: "complete"` |
 
 **NEVER skip directly to `final.md`** — this breaks progress tracking.
 
@@ -241,7 +280,7 @@ See `references/context-discovery.md` for detailed algorithm.
 3. Create session directory:
    ```bash
    SESSION_ID="$(date +%Y-%m-%d)-$(git branch --show-current | tr '/' '-')"
-   mkdir -p .ocr/sessions/$SESSION_ID/reviews
+   mkdir -p .ocr/sessions/$SESSION_ID/rounds/round-1/reviews
    ```
 
 4. Save context to `context.md`:
@@ -265,7 +304,7 @@ See `references/context-discovery.md` for detailed algorithm.
 
 **STOP and verify before proceeding:**
 - [ ] Session directory created: `.ocr/sessions/{id}/`
-- [ ] `reviews/` subdirectory created
+- [ ] `rounds/round-1/reviews/` subdirectory created
 - [ ] `context.md` written with change summary
 
 ---
@@ -368,16 +407,16 @@ See `references/context-discovery.md` for detailed algorithm.
    - The diff to review
    - **Instruction to explore codebase with full agency**
 
-4. Save each review to `.ocr/sessions/{id}/reviews/{reviewer}-{n}.md`.
+4. Save each review to `.ocr/sessions/{id}/rounds/round-{current_round}/reviews/{type}-{n}.md`.
 
 See `references/reviewer-task.md` for the task template.
 
 ### ✅ Phase 4 Checkpoint
 
 **STOP and verify before proceeding:**
-- [ ] At least 4 review files exist in `reviews/` directory
+- [ ] At least 4 review files exist in `rounds/round-{n}/reviews/` directory
 - [ ] Each review file contains findings (even if "no issues found")
-- [ ] File naming follows `{reviewer}-{n}.md` pattern
+- [ ] File naming follows `{type}-{n}.md` pattern (e.g., `principal-1.md`, `quality-2.md`)
 
 ---
 
@@ -423,14 +462,14 @@ See `references/reviewer-task.md` for the task template.
    - **CONNECT**: "This relates to my maintainability concern..."
    - **SURFACE**: "Based on this discussion, I notice..."
 
-3. Save discourse to `.ocr/sessions/{id}/discourse.md`.
+3. Save discourse to `.ocr/sessions/{id}/rounds/round-{current_round}/discourse.md`.
 
 See `references/discourse.md` for detailed instructions.
 
 ### ✅ Phase 6 Checkpoint
 
 **STOP and verify before proceeding:**
-- [ ] `discourse.md` written to session directory
+- [ ] `rounds/round-{n}/discourse.md` written to round directory
 - [ ] Contains AGREE/CHALLENGE/CONNECT/SURFACE responses
 - [ ] (Or if `--quick` flag: skip this phase, proceed to synthesis)
 
@@ -472,14 +511,14 @@ See `references/discourse.md` for detailed instructions.
    
    These go in a prominent "Clarifying Questions" section for stakeholder response.
 
-7. Save to `.ocr/sessions/{id}/final.md`.
+7. Save to `.ocr/sessions/{id}/rounds/round-{current_round}/final.md`.
 
 See `references/synthesis.md` for template.
 
 ### ✅ Phase 7 Checkpoint
 
 **STOP and verify before proceeding:**
-- [ ] `final.md` written to session directory
+- [ ] `rounds/round-{n}/final.md` written to round directory
 - [ ] Contains prioritized findings (Must Fix, Should Fix, Consider)
 - [ ] Contains Clarifying Questions section (if any)
 - [ ] If requirements provided: Contains Requirements Assessment
@@ -517,7 +556,7 @@ See `references/synthesis.md` for template.
      "status": "closed",
      "current_phase": "complete",
      "phase_number": 8,
-     "completed_phases": ["context", "requirements", "analysis", "reviews", "aggregation", "discourse", "synthesis"],
+     "current_round": 1,
      "updated_at": "{now}"
    }
    ```
@@ -530,7 +569,7 @@ See `references/synthesis.md` for template.
 4. Confirm session saved:
    ```
    ✓ Review complete
-   → .ocr/sessions/{id}/final.md
+   → .ocr/sessions/{id}/rounds/round-{n}/final.md
    ```
 
 ---
@@ -539,11 +578,11 @@ See `references/synthesis.md` for template.
 
 | Phase | Command/Action | Output |
 |-------|---------------|--------|
-| 1 | Search for context files | discovered-standards.md |
-| 2 | git diff, create session | context.md |
-| 3 | Analyze, select reviewers | guidance in context.md |
-| 4 | Spawn reviewer tasks | reviews/*.md |
+| 1 | Search for context files | `discovered-standards.md` |
+| 2 | git diff, create session | `context.md`, `rounds/round-1/reviews/` |
+| 3 | Analyze, select reviewers | guidance in `context.md` |
+| 4 | Spawn reviewer tasks | `rounds/round-{n}/reviews/*.md` |
 | 5 | Compare redundant runs | aggregated findings |
-| 6 | Reviewer discourse | discourse.md |
-| 7 | Synthesize and prioritize | final.md |
+| 6 | Reviewer discourse | `rounds/round-{n}/discourse.md` |
+| 7 | Synthesize and prioritize | `rounds/round-{n}/final.md` |
 | 8 | Display/post | Terminal output, GitHub |