@open-code-review/agents 1.3.1 → 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

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