@open-code-review/agents 1.3.0 → 1.4.0

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

@@ -12,6 +12,15 @@ Every OCR session creates files in `.ocr/sessions/{session-id}/`:
 ├── discovered-standards.md # Merged project context (shared across rounds)
 ├── requirements.md         # User-provided requirements (if any, shared)
 ├── context.md              # Phase 2+3: Change summary + Tech Lead guidance (shared)
+├── map/                    # Code Review Map artifacts (optional)
+│   └── runs/
+│       ├── run-1/          # First map generation
+│       │   ├── topology.md         # File categorization and sections
+│       │   ├── flow-analysis.md    # Dependency tracing results
+│       │   ├── requirements-mapping.md  # Coverage matrix (if requirements)
+│       │   └── map.md              # Final map output
+│       └── run-2/          # Subsequent runs (created on re-map)
+│           └── ...         # Same structure as run-1
 └── rounds/                 # All round-specific artifacts
     ├── round-1/            # First review round
     │   ├── reviews/        # Individual reviewer outputs
@@ -42,19 +51,43 @@ OCR uses a **round-first architecture** where all round-specific artifacts live
 - 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` | |
+**Shared vs per-round/run artifacts**:
+| Shared (session root) | Per-round (`rounds/round-{n}/`) | Per-run (`map/runs/run-{n}/`) |
+|----------------------|--------------------------------|-------------------------------|
+| `state.json` | `reviews/*.md` | `topology.md` |
+| `discovered-standards.md` | `discourse.md` | `flow-analysis.md` |
+| `requirements.md` | `final.md` | `requirements-mapping.md` |
+| `context.md` | | `map.md` |
 
 **When to use multiple rounds**:
 - Author addresses feedback and requests re-review
 - Scope changes mid-review
 - Different reviewer team composition needed
 
+## Map Runs
+
+OCR uses a **run-based architecture** for maps, parallel to review rounds.
+
+**Run behavior**:
+- First `/ocr-map` creates `map/runs/run-1/` with map artifacts
+- Subsequent `/ocr-map` on same day/branch creates `map/runs/run-{n+1}/`
+- Previous runs are preserved (never overwritten)
+- Each run produces a complete `map.md`
+- `state.json` tracks `current_map_run`; run metadata derived from filesystem
+
+**Map artifacts per run**:
+| File | Phase | Description |
+|------|-------|-------------|
+| `topology.md` | 2 | File categorization and section groupings |
+| `flow-analysis.md` | 3 | Upstream/downstream dependency tracing |
+| `requirements-mapping.md` | 4 | Requirements coverage matrix (if requirements provided) |
+| `map.md` | 5 | Final synthesized Code Review Map |
+
+**When to use multiple runs**:
+- Changeset has evolved since last map
+- Different requirements context needed
+- Fresh analysis desired after code updates
+
 ## File Specifications
 
 ### Required Files
@@ -192,7 +225,7 @@ Must include:
 - Clarifying Questions section
 - Individual Reviews table with file references
 
-See `references/synthesis.md` for complete template.
+See `references/final-template.md` for complete template.
 
 ## CLI Dependencies
 

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

@@ -23,28 +23,38 @@ This means:
 ```json
 {
   "session_id": "{session-id}",
+  "workflow_type": "review",
   "status": "active",
   "current_phase": "reviews",
   "phase_number": 4,
   "current_round": 1,
+  "current_map_run": 1,
   "started_at": "{ISO-8601-TIMESTAMP}",
   "round_started_at": "{ISO-8601-TIMESTAMP}",
+  "map_started_at": "{ISO-8601-TIMESTAMP}",
   "updated_at": "{ISO-8601-TIMESTAMP}"
 }
 ```
 
-**Minimal by design**: Round metadata is derived from the filesystem, not stored in state.json.
+**Minimal by design**: Round and map run metadata is derived from the filesystem, not stored in 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)
+- `workflow_type`: Current workflow type (`"review"` or `"map"`) — enables `ocr progress` to track correct workflow
+- `started_at`: When the session was created (first `/ocr-review` or `/ocr-map`)
+- `round_started_at`: When the current review round began (set when starting round ≥ 1)
+- `map_started_at`: When the current map run began (set when starting a map run)
+- `current_map_run`: Current map run number (only present during map workflow)
 - `updated_at`: Last modification time (updated at every phase transition)
 
+**CRITICAL for timing**: When starting a NEW workflow type in an existing session (e.g., starting `/ocr-map` after `/ocr-review`), you MUST set the workflow-specific start time (`map_started_at` or `round_started_at`) to the current timestamp. This ensures `ocr progress` shows accurate elapsed time for each workflow.
+
 **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
+- Map run count: enumerate `map/runs/run-*/` directories
+- Map run completion: check for `map.md` in run 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.
 
@@ -70,6 +80,8 @@ The `ocr progress` command only auto-detects sessions with `status: "active"`. C
 
 The Tech Lead MUST update `state.json` at each phase boundary:
 
+### Review Phases
+
 | Phase | When to Update | File Created |
 |-------|---------------|--------------|
 | context | After writing project standards | `discovered-standards.md` |
@@ -80,24 +92,42 @@ The Tech Lead MUST update `state.json` at each phase boundary:
 | synthesis | After final review | `rounds/round-{n}/final.md` |
 | complete | After presenting to user | Set `status: "closed"` |
 
+### Map Phases
+
+| Phase | When to Update | File Created |
+|-------|---------------|--------------|
+| map-context | After writing project standards | `discovered-standards.md` (shared) |
+| topology | After topology analysis | `map/runs/run-{n}/topology.md` |
+| flow-analysis | After flow analysis | `map/runs/run-{n}/flow-analysis.md` |
+| requirements-mapping | After requirements mapping | `map/runs/run-{n}/requirements-mapping.md` |
+| synthesis | After map generation | `map/runs/run-{n}/map.md` |
+| complete | After presenting map | Keep `status: "active"` (session continues) |
+
 ## Writing State
 
-**CRITICAL**: Always generate timestamps dynamically using the current UTC time in ISO 8601 format.
+**CRITICAL**: Always generate timestamps using a **tool call** — never construct them manually.
 
 ### Generating Timestamps
 
+> ⚠️ **NEVER** write timestamps manually (e.g., `"2026-01-29T22:00:00Z"`). Always use a tool call to get the current time. Manual timestamps risk timezone errors, typos, and incorrect elapsed time display.
+
+**Required approach**: Use `run_command` tool to execute:
+
 ```bash
-# macOS/Linux
+# macOS/Linux — USE THIS
 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()
+**Example tool call** (do this before writing state.json):
+```
+run_command: date -u +"%Y-%m-%dT%H:%M:%SZ"
 ```
 
+Then use the **exact output** as the timestamp value in state.json.
+
+**Why this matters**: The `ocr progress` command calculates elapsed time from these timestamps. If a timestamp is incorrect (wrong timezone, future time, etc.), the progress display will show wrong/counting-down times.
+
 When creating a new session (Phase 1 start):
 
 ```json
@@ -117,15 +147,35 @@ When transitioning phases (preserve `started_at`, update `updated_at`):
 ```json
 {
   "session_id": "{session-id}",
+  "workflow_type": "review",
   "status": "active",
   "current_phase": "reviews",
   "phase_number": 4,
   "current_round": 1,
   "started_at": "{PRESERVE_ORIGINAL}",
+  "round_started_at": "{PRESERVE_ORIGINAL}",
+  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
+}
+```
+
+When starting a map workflow (new map run or first map in session):
+
+```json
+{
+  "session_id": "{session-id}",
+  "workflow_type": "map",
+  "status": "active",
+  "current_phase": "map-context",
+  "phase_number": 1,
+  "current_map_run": 1,
+  "started_at": "{PRESERVE_ORIGINAL_OR_SET_IF_NEW}",
+  "map_started_at": "{CURRENT_ISO_TIMESTAMP}",
   "updated_at": "{CURRENT_ISO_TIMESTAMP}"
 }
 ```
 
+**CRITICAL**: Always set `map_started_at` to `{CURRENT_ISO_TIMESTAMP}` when starting a new map run. This ensures accurate elapsed time tracking even if the session had a prior review workflow.
+
 When closing a session (Phase 8 complete):
 
 ```json

package/skills/ocr/references/workflow.md

@@ -13,8 +13,9 @@ Before starting ANY work, verify the current session state to avoid duplicating
 ### Step 1: Check for existing session
 
 ```bash
-# Get current branch
-BRANCH=$(git branch --show-current)
+# Get current branch and sanitize for filesystem (replace / with -)
+BRANCH_RAW=$(git branch --show-current)
+BRANCH=$(echo "$BRANCH_RAW" | tr '/' '-')
 DATE=$(date +%Y-%m-%d)
 SESSION_DIR=".ocr/sessions/${DATE}-${BRANCH}"
 
@@ -113,7 +114,13 @@ At **every phase transition**, update `.ocr/sessions/{id}/state.json`:
 
 **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.
+> ⚠️ **TIMESTAMP RULE**: Always use `run_command` tool to get timestamps. **Never construct them manually.**
+> ```bash
+> date -u +"%Y-%m-%dT%H:%M:%SZ"
+> ```
+> Use the **exact output** in state.json. Manual timestamps cause incorrect `ocr progress` display.
+
+**CRITICAL**: 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)
 
@@ -315,18 +322,33 @@ See `references/context-discovery.md` for detailed algorithm.
 
 ### Steps
 
-1. Review requirements (if provided):
+1. **Check for existing map reference** (optional):
+   
+   If user explicitly references an existing map (e.g., "I've already generated a map", "use the map I created", "check the map in this session"):
+   
+   ```bash
+   # Check for existing map artifacts
+   ls .ocr/sessions/{id}/map/runs/*/map.md 2>/dev/null
+   ```
+   
+   - **If found AND user referenced it**: Read the latest `map.md` as supplementary context
+   - **If not found**: Inform user no map exists, proceed with standard review
+   - **If user did NOT reference a map**: Do NOT automatically use map artifacts
+   
+   > **Note**: Maps are orthogonal tools. Only use if explicitly referenced by user.
+
+2. Review requirements (if provided):
    - What is the code SUPPOSED to do?
    - What are the acceptance criteria?
    - What edge cases are implied?
 
-2. Analyze the diff to understand:
+3. Analyze the diff to understand:
    - What functionality is being added/changed/removed?
    - Does this align with requirements?
    - What is the likely intent?
    - What are the potential risk areas?
 
-3. Create dynamic guidance for reviewers:
+4. Create dynamic guidance for reviewers:
    ```markdown
    ## Tech Lead Guidance
    
@@ -360,18 +382,36 @@ See `references/context-discovery.md` for detailed algorithm.
    - Verify rate limiting is implemented
    ```
 
-4. Select reviewers:
+4. **Read reviewer team from config** (REQUIRED):
+
+   ```bash
+   # MUST read default_team from .ocr/config.yaml - do NOT use hardcoded values
+   cat .ocr/config.yaml | grep -A10 'default_team:'
+   ```
    
-   **Default team** (always spawned):
-   - 2× Principal (holistic architecture review)
-   - 2× Quality (code quality review)
+   Parse the `default_team` section to determine reviewer counts:
+   ```yaml
+   # Example config - actual values come from .ocr/config.yaml
+   default_team:
+     principal: 2    # Spawn principal-1, principal-2
+     quality: 2      # Spawn quality-1, quality-2
+     # security: 1   # Commented = not spawned by default
+     testing: 1      # Spawn testing-1
+   ```
+   
+   **Reviewer spawning rules**:
+   - For each uncommented entry in `default_team`, spawn N instances
+   - `principal: 2` → spawn `principal-1`, `principal-2`
+   - `quality: 2` → spawn `quality-1`, `quality-2`  
+   - `testing: 1` → spawn `testing-1`
+   - Commented entries (e.g., `# security: 1`) are NOT spawned unless auto-detected
    
-   **Optional reviewers** (added based on change type or user request):
+   **Auto-detection** (adds reviewers beyond config):
    | Change Type | Additional Reviewers |
    |-------------|---------------------|
    | Auth/Security changes | + 1× Security |
    | API changes | + 1× Security |
-   | Logic changes | + 1× Testing |
+   | Logic changes | + 1× Testing (if not in config) |
    | User says "add security" | + 1× Security |
 
 ---
@@ -380,24 +420,40 @@ See `references/context-discovery.md` for detailed algorithm.
 
 **Goal**: Run each reviewer independently with configured redundancy.
 
+> **⚠️ CRITICAL**: Reviewer counts and types come from `.ocr/config.yaml` `default_team` section.
+> Do NOT use hardcoded defaults. Do NOT skip the `-{n}` suffix in filenames.
+> See `references/session-files.md` for authoritative file naming.
+
 ### Steps
 
 1. Load reviewer personas from `references/reviewers/`.
 
-2. Spawn tasks based on default team + detected needs:
-   ```
-   # Default team (always)
-   Spawn Task: principal-1
-   Spawn Task: principal-2
-   Spawn Task: quality-1
-   Spawn Task: quality-2
+2. **Parse `default_team` from config** (already read in Phase 3):
+   
+   For each reviewer type in config, spawn the specified number of instances:
    
-   # Optional (if auth/API/data changes OR user requested)
-   Spawn Task: security-1
+   ```bash
+   # Example: If config says principal: 2, quality: 2, testing: 1
+   # You MUST spawn exactly these reviewers with numbered suffixes:
+   
+   # From default_team.principal: 2
+   → Create: rounds/round-$CURRENT_ROUND/reviews/principal-1.md
+   → Create: rounds/round-$CURRENT_ROUND/reviews/principal-2.md
+   
+   # From default_team.quality: 2  
+   → Create: rounds/round-$CURRENT_ROUND/reviews/quality-1.md
+   → Create: rounds/round-$CURRENT_ROUND/reviews/quality-2.md
    
-   # Optional (if logic changes OR user requested)
-   Spawn Task: testing-1
+   # From default_team.testing: 1
+   → Create: rounds/round-$CURRENT_ROUND/reviews/testing-1.md
+   
+   # Auto-detected (if applicable)
+   → Create: rounds/round-$CURRENT_ROUND/reviews/security-1.md
    ```
+   
+   **File naming pattern**: `{type}-{n}.md` where n starts at 1.
+   
+   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`)
@@ -411,12 +467,38 @@ See `references/context-discovery.md` for detailed algorithm.
 
 See `references/reviewer-task.md` for the task template.
 
-### ✅ Phase 4 Checkpoint
+### ✅ Phase 4 Checkpoint — MANDATORY VALIDATION
+
+**Run this validation command before proceeding:**
+
+```bash
+# 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 ' ')
+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)
+for f in "$REVIEWS_DIR/"*.md; do
+  if [[ "$(basename "$f")" =~ ^(principal|quality|security|testing)-[0-9]+\.md$ ]]; then
+    echo "✓ $(basename "$f")"
+  else
+    echo "❌ $(basename "$f") does not match {type}-{n}.md pattern"
+    exit 1
+  fi
+done
+
+REVIEWER_COUNT=$(ls -1 "$REVIEWS_DIR/"*.md 2>/dev/null | wc -l | tr -d ' ')
+echo "✓ Found $REVIEWER_COUNT reviewer files"
+```
 
 **STOP and verify before proceeding:**
-- [ ] 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 `{type}-{n}.md` pattern (e.g., `principal-1.md`, `quality-2.md`)
+- [ ] Review files exist for EACH entry in `default_team` config
+- [ ] File count matches sum of all `default_team` values
+- [ ] All files use `{type}-{n}.md` pattern
+- [ ] Each review file contains findings
 
 ---
 
@@ -477,7 +559,11 @@ See `references/discourse.md` for detailed instructions.
 
 ## Phase 7: Synthesis
 
-**Goal**: Produce final prioritized review.
+**Goal**: Produce final prioritized review and save to **`final.md`**.
+
+> **File**: `rounds/round-{n}/final.md`
+> **Template**: See `references/final-template.md` for format
+> **Manifest**: See `references/session-files.md` for authoritative file names
 
 ### Steps
 
@@ -511,14 +597,45 @@ See `references/discourse.md` for detailed instructions.
    
    These go in a prominent "Clarifying Questions" section for stakeholder response.
 
-7. Save to `.ocr/sessions/{id}/rounds/round-{current_round}/final.md`.
+7. **Write the final review file**:
+   ```bash
+   # OUTPUT FILE - must be exactly this path:
+   FINAL_FILE="$SESSION_DIR/rounds/round-$CURRENT_ROUND/final.md"
+   ```
+   
+   Save synthesized review to `$FINAL_FILE`.
+
+See `references/final-template.md` for the template format.
+
+### ✅ Phase 7 Checkpoint — MANDATORY VALIDATION
 
-See `references/synthesis.md` for template.
+**Run this validation command before proceeding:**
+
+```bash
+# 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 ' ')
+FINAL_FILE="$SESSION_DIR/rounds/round-$CURRENT_ROUND/final.md"
+
+# Check file exists
+if [ -f "$FINAL_FILE" ]; then
+  echo "✓ final.md exists at $FINAL_FILE"
+else
+  echo "❌ final.md not found at $FINAL_FILE"
+  exit 1
+fi
 
-### ✅ Phase 7 Checkpoint
+# Check required content
+if grep -q '## Verdict' "$FINAL_FILE"; then
+  echo "✓ Contains Verdict section"
+else
+  echo "❌ Missing '## Verdict' section"
+  exit 1
+fi
+```
 
 **STOP and verify before proceeding:**
-- [ ] `rounds/round-{n}/final.md` written to round directory
+- [ ] `rounds/round-{n}/final.md` exists
 - [ ] Contains prioritized findings (Must Fix, Should Fix, Consider)
 - [ ] Contains Clarifying Questions section (if any)
 - [ ] If requirements provided: Contains Requirements Assessment