@open-code-review/agents 1.4.0 → 1.5.0

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

@@ -2,7 +2,9 @@
 
 Complete 6-phase process for generating a Code Review Map.
 
-> ⚠️ **CRITICAL**: You MUST update `state.json` **BEFORE starting work** on each phase. Update the `current_phase` and `phase_number` immediately when transitioning.
+> **CRITICAL**: You MUST call `ocr state transition` **BEFORE starting work** on each phase. Transition the `current_phase` and `phase_number` immediately when entering a new phase.
+
+> **PREREQUISITE**: The `ocr` CLI must be installed (`npm install -g @open-code-review/cli`) or accessible via `npx`. Every phase transition calls `ocr state transition`, which requires the CLI.
 
 ---
 
@@ -57,7 +59,7 @@ if [ ! -d "$MAP_DIR" ]; then
 else
   HIGHEST=$(ls -1 "$MAP_DIR" | grep -E '^run-[0-9]+$' | sed 's/run-//' | sort -n | tail -1)
   HIGHEST=${HIGHEST:-0}
-  
+
   if [ -f "$MAP_DIR/run-$HIGHEST/map.md" ]; then
     CURRENT_RUN=$((HIGHEST + 1))
     mkdir -p "$MAP_DIR/run-$CURRENT_RUN"
@@ -67,82 +69,60 @@ else
 fi
 ```
 
-### Step 4: Initialize state.json for map workflow
-
-**CRITICAL**: Before proceeding, you MUST update state.json to indicate a map workflow is starting.
+### Step 4: Initialize session state for map workflow
 
-> ⚠️ **TIMESTAMP RULE**: Always use `run_command` tool to get the current timestamp. **Never construct timestamps manually** — this causes incorrect elapsed time display in `ocr progress`.
+**CRITICAL**: Before proceeding, you MUST initialize the session in SQLite using `ocr state` commands.
 
-**First, get the current timestamp** (run this command):
+If this is a **new session** (no prior review or map in this session):
 ```bash
-date -u +"%Y-%m-%dT%H:%M:%SZ"
+ocr state init \
+  --session-id "$SESSION_ID" \
+  --branch "$BRANCH" \
+  --workflow-type map \
+  --session-dir "$SESSION_DIR"
 ```
 
-Use the **exact output** (e.g., `2026-01-29T13:45:22Z`) in the state.json below.
-
+Then transition to the first map phase:
 ```bash
-STATE_FILE="$SESSION_DIR/state.json"
-CURRENT_TIME="{OUTPUT_FROM_DATE_COMMAND}"  # Use actual output, not a placeholder
-
-# Read existing state if present, or create new
-if [ -f "$STATE_FILE" ]; then
-  # Preserve started_at from existing session
-  STARTED_AT=$(jq -r '.started_at // empty' "$STATE_FILE")
-  STARTED_AT=${STARTED_AT:-$CURRENT_TIME}
-else
-  STARTED_AT=$CURRENT_TIME
-fi
+ocr state transition \
+  --phase "map-context" \
+  --phase-number 1 \
+  --current-map-run $CURRENT_RUN
+```
 
-# Write updated state with map workflow fields
-cat > "$STATE_FILE" << EOF
-{
-  "session_id": "{session_id}",
-  "workflow_type": "map",
-  "status": "active",
-  "current_phase": "map-context",
-  "phase_number": 1,
-  "current_map_run": $CURRENT_RUN,
-  "started_at": "$STARTED_AT",
-  "map_started_at": "$CURRENT_TIME",
-  "updated_at": "$CURRENT_TIME"
-}
-EOF
+If this is an **existing session** (e.g., a map after a prior review), the session already exists in SQLite — just call `ocr state transition` to switch to the map workflow:
+```bash
+ocr state transition \
+  --phase "map-context" \
+  --phase-number 1 \
+  --current-map-run $CURRENT_RUN
 ```
 
-**Why `map_started_at` is required**: If this session previously had a review workflow, `started_at` will reflect when the review started, not the map. Setting `map_started_at` ensures `ocr progress` shows accurate elapsed time for the map workflow.
+The CLI commands handle timestamp management automatically — `map_started_at` is set when transitioning to a map phase, ensuring `ocr progress` shows accurate elapsed time even if the session had a prior review workflow.
 
 ### Step 5: Report to user
 
 ```
-📍 Session: {session_id}
-🗺️ Map run: {current_run}
-📊 Current phase: {current_phase}
-🔄 Action: [Starting fresh | Resuming from Phase X]
+Session: {session_id}
+Map run: {current_run}
+Current phase: {current_phase}
+Action: [Starting fresh | Resuming from Phase X]
 ```
 
 ---
 
 ## State Tracking
 
-At **every phase transition**, update `.ocr/sessions/{id}/state.json`:
-
-```json
-{
-  "session_id": "{id}",
-  "workflow_type": "map",
-  "status": "active",
-  "current_phase": "flow-analysis",
-  "phase_number": 3,
-  "current_map_run": 1,
-  "started_at": "{PRESERVE_ORIGINAL}",
-  "map_started_at": "{SET_ONCE_ON_MAP_START}",
-  "updated_at": "{CURRENT_ISO_TIMESTAMP}"
-}
+At **every phase transition**, call `ocr state transition` with the `--current-map-run` flag:
+
+```bash
+ocr state transition \
+  --phase "flow-analysis" \
+  --phase-number 3 \
+  --current-map-run $CURRENT_RUN
 ```
 
-**CRITICAL**:
-- Always include `"workflow_type": "map"` — this enables `ocr progress` to track map workflows.
-- Set `"map_started_at"` ONCE when starting a new map run — this ensures accurate elapsed time tracking even if the session had a prior review workflow.
+This updates the session in SQLite and logs an orchestration event.
 
 **Map phase values**: `map-context`, `topology`, `flow-analysis`, `requirements-mapping`, `synthesis`, `complete`
 
@@ -152,6 +132,8 @@ At **every phase transition**, update `.ocr/sessions/{id}/state.json`:
 
 **Goal**: Build context from config + discovered files + user requirements.
 
+**State**: Call `ocr state transition --phase "map-context" --phase-number 1 --current-map-run $CURRENT_RUN`
+
 This phase is **identical** to the review workflow's context discovery. See `references/context-discovery.md` for the complete algorithm.
 
 ### Steps
@@ -182,12 +164,12 @@ code-review-map:
 
 **Use these values** when spawning agents in Phase 3 and Phase 4.
 
-### ✅ Phase 1 Checkpoint
+### Phase 1 Checkpoint
 
 - [ ] `discovered-standards.md` written (or reused from existing session)
 - [ ] If requirements provided: `requirements.md` written
 - [ ] Agent redundancy config loaded
-- [ ] `state.json` updated: `current_phase: "map-context"`
+- [ ] `ocr state transition` called with `--phase "map-context"`
 
 ---
 
@@ -195,6 +177,8 @@ code-review-map:
 
 **Goal**: Enumerate changed files and identify logical structure.
 
+**State**: Call `ocr state transition --phase "topology" --phase-number 2 --current-map-run $CURRENT_RUN`
+
 ### Steps
 
 1. **Get the changeset** (determine target from user request):
@@ -211,11 +195,11 @@ code-review-map:
    ```bash
    # Default: staged changes
    git diff --cached --name-only
-   
+
    # Store canonical file list for completeness validation
    git diff --cached --name-only > /tmp/ocr-canonical-files.txt
    ```
-   
+
    **CRITICAL**: Store this canonical file list. It's used for completeness validation in Phase 5.
 
 2. **Categorize each file**:
@@ -242,13 +226,13 @@ code-review-map:
    .ocr/sessions/{id}/map/runs/run-{n}/topology.md
    ```
 
-### ✅ Phase 2 Checkpoint
+### Phase 2 Checkpoint
 
 - [ ] All changed files enumerated
 - [ ] Files categorized by type
 - [ ] Logical sections identified
 - [ ] `topology.md` written
-- [ ] `state.json` updated: `current_phase: "topology"`
+- [ ] `ocr state transition` called with `--phase "topology"`
 
 ---
 
@@ -256,6 +240,8 @@ code-review-map:
 
 **Goal**: Trace upstream/downstream dependencies for each changed file.
 
+**State**: Call `ocr state transition --phase "flow-analysis" --phase-number 3 --current-map-run $CURRENT_RUN`
+
 ### Steps
 
 1. **Spawn Flow Analysts** — spawn `FLOW_ANALYST_COUNT` agents (from config, default: 2)
@@ -288,13 +274,13 @@ For each analyst, provide:
 
 See `references/map-personas/flow-analyst.md` for persona details.
 
-### ✅ Phase 3 Checkpoint
+### Phase 3 Checkpoint
 
 - [ ] Flow Analysts spawned (`FLOW_ANALYST_COUNT` from config)
 - [ ] All changed files have flow context
 - [ ] Findings aggregated
 - [ ] `flow-analysis.md` written
-- [ ] `state.json` updated: `current_phase: "flow-analysis"`
+- [ ] `ocr state transition` called with `--phase "flow-analysis"`
 
 ---
 
@@ -302,6 +288,8 @@ See `references/map-personas/flow-analyst.md` for persona details.
 
 **Goal**: Map changes to requirements and identify coverage.
 
+**State**: Call `ocr state transition --phase "requirements-mapping" --phase-number 4 --current-map-run $CURRENT_RUN`
+
 **Skip this phase** if no requirements were provided.
 
 ### Steps
@@ -328,13 +316,13 @@ See `references/map-personas/flow-analyst.md` for persona details.
    .ocr/sessions/{id}/map/runs/run-{n}/requirements-mapping.md
    ```
 
-### ✅ Phase 4 Checkpoint
+### Phase 4 Checkpoint
 
 - [ ] Requirements Mappers spawned (if requirements exist)
 - [ ] Coverage matrix created
 - [ ] Gaps identified
 - [ ] `requirements-mapping.md` written
-- [ ] `state.json` updated: `current_phase: "requirements-mapping"`
+- [ ] `ocr state transition` called with `--phase "requirements-mapping"`
 
 ---
 
@@ -342,6 +330,8 @@ See `references/map-personas/flow-analyst.md` for persona details.
 
 **Goal**: Combine all findings into the final Code Review Map optimized for reviewer workflow.
 
+**State**: Call `ocr state transition --phase "synthesis" --phase-number 5 --current-map-run $CURRENT_RUN`
+
 ### Template Structure (in order)
 
 1. **Executive Summary** — Context first
@@ -350,8 +340,9 @@ See `references/map-personas/flow-analyst.md` for persona details.
 4. **Critical Review Focus** — High-value areas for human judgment
 5. **Manual Verification** — Tests to run before/during review
 6. **File Review** — Per-section file tracking (main tracking area)
-7. **File Index** — Alphabetical reference
-8. **Map Metadata** — Run info
+7. **Section Dependencies** — Cross-section dependency graph data
+8. **File Index** — Alphabetical reference
+9. **Map Metadata** — Run info
 
 ### Steps
 
@@ -396,18 +387,25 @@ See `references/map-personas/flow-analyst.md` for persona details.
      - Specific areas mapped to requirements/concerns
      - Do NOT do code review — just flag for reviewer attention
 
-8. **Create File Index**:
+8. **Generate Section Dependencies**:
+   - Review flow analysis cross-file flows to identify section-to-section call chains
+   - For each pair of sections with meaningful dependencies, add a table row
+   - Direction: caller section → callee section
+   - Relationship should be a 3-8 word description (e.g., "Auth middleware protects routes")
+   - If sections are independent, leave the table body empty (headers only)
+
+9. **Create File Index**:
    - Alphabetical list of ALL changed files
    - Section reference for each
 
-9. **Validate completeness**:
+10. **Validate completeness**:
    ```bash
    EXPECTED=$(git diff --cached --name-only | wc -l)
    MAPPED=$(grep -oE '\| `[^`]+` \|' map.md | wc -l)
    [ "$EXPECTED" -ne "$MAPPED" ] && echo "ERROR: Missing files!"
    ```
 
-10. **Save final map**:
+11. **Save final map**:
     ```
     .ocr/sessions/{id}/map/runs/run-{n}/map.md
     ```
@@ -416,7 +414,7 @@ See `references/map-personas/flow-analyst.md` for persona details.
 
 See `references/map-template.md` for the complete template.
 
-### ✅ Phase 5 Checkpoint
+### Phase 5 Checkpoint
 
 - [ ] Executive Summary with hypothesis
 - [ ] Questions & Clarifications populated
@@ -425,10 +423,11 @@ See `references/map-template.md` for the complete template.
 - [ ] Manual Verification tests generated (or omitted if docs-only)
 - [ ] All File Review sections with file tables
 - [ ] Review Suggestions per section (only where key things to flag)
+- [ ] Section Dependencies table generated
 - [ ] File Index complete
 - [ ] Completeness validated (all files appear in tables)
 - [ ] `map.md` written
-- [ ] `state.json` updated: `current_phase: "synthesis"`
+- [ ] `ocr state transition` called with `--phase "synthesis"`
 
 ---
 
@@ -436,6 +435,8 @@ See `references/map-template.md` for the complete template.
 
 **Goal**: Display the map to the user.
 
+**State**: Call `ocr state transition --phase "complete" --phase-number 6 --current-map-run $CURRENT_RUN` after presenting.
+
 ### Steps
 
 1. **Read the final map**:
@@ -445,29 +446,31 @@ See `references/map-template.md` for the complete template.
 
 2. **Present to user** with summary:
    ```
-   🗺️ Code Review Map Generated
-   
-   📍 Session: {session_id}
-   📁 Files mapped: {count}
-   📑 Sections: {section_count}
-   
+   Code Review Map Generated
+
+   Session: {session_id}
+   Files mapped: {count}
+   Sections: {section_count}
+
    The map is saved at: .ocr/sessions/{id}/map/runs/run-{n}/map.md
-   
+
    [Display map content]
    ```
 
 3. **Update state**:
-   ```json
-   {
-     "current_phase": "map-complete",
-     "phase_number": 6
-   }
+   ```bash
+   ocr state transition \
+     --phase "complete" \
+     --phase-number 6 \
+     --current-map-run $CURRENT_RUN
    ```
 
-### ✅ Phase 6 Checkpoint
+   > **Note**: Map completion does NOT close the session — the session stays `active` so further reviews or maps can be run.
+
+### Phase 6 Checkpoint
 
 - [ ] Map presented to user
-- [ ] `state.json` updated: `current_phase: "complete"`
+- [ ] `ocr state transition` called with `--phase "complete"`
 
 ---
 
@@ -534,7 +537,7 @@ See `references/map-template.md` for the complete template.
 - **Purpose**: {what this section covers}
 - **Files**: `file1.ts`, `file2.ts`, `file3.ts`
 - **Entry Point**: `file1.ts`
-- **Review Order**: file1 → file2 → file3
+- **Review Order**: file1 -> file2 -> file3
 
 ### Section 2: {Name}
 ...
@@ -586,7 +589,7 @@ Files that don't fit into logical sections:
 
 ### Flow 1: Authentication Request
 ```
-api/auth.ts → services/auth.service.ts → utils/token.ts → db/users.ts
+api/auth.ts -> services/auth.service.ts -> utils/token.ts -> db/users.ts
 ```
 
 ### Flow 2: ...
@@ -595,7 +598,7 @@ api/auth.ts → services/auth.service.ts → utils/token.ts → db/users.ts
 
 | File | Analyst 1 Section | Analyst 2 Section | Final |
 |------|-------------------|-------------------|-------|
-| `file1.ts` | Auth Flow | Auth Flow | Auth Flow ✓ |
+| `file1.ts` | Auth Flow | Auth Flow | Auth Flow |
 | `file2.ts` | Auth Flow | API Layer | Auth Flow (majority) |
 ```
 
@@ -619,18 +622,18 @@ api/auth.ts → services/auth.service.ts → utils/token.ts → db/users.ts
 
 | Requirement | Status | Files | Confidence |
 |-------------|--------|-------|------------|
-| REQ-1 | ✅ Full | `auth.ts`, `oauth.ts` | High (2/2) |
-| REQ-2 | ⚠️ Partial | `session.ts` | Medium (1/2) |
-| REQ-3 | ❌ None | — | High (2/2) |
+| REQ-1 | Full | `auth.ts`, `oauth.ts` | High (2/2) |
+| REQ-2 | Partial | `session.ts` | Medium (1/2) |
+| REQ-3 | None | — | High (2/2) |
 
 ## Per-Section Coverage
 
 ### Section 1: Authentication Flow
-- REQ-1: ✅ Full
-- REQ-2: ⚠️ Partial (missing cleanup)
+- REQ-1: Full
+- REQ-2: Partial (missing cleanup)
 
 ### Section 2: API Endpoints
-- REQ-3: ❌ Not addressed
+- REQ-3: Not addressed
 
 ## Gaps
 
@@ -644,7 +647,7 @@ api/auth.ts → services/auth.service.ts → utils/token.ts → db/users.ts
 
 | Requirement | Mapper 1 | Mapper 2 | Final |
 |-------------|----------|----------|-------|
-| REQ-1 | Full | Full | Full ✓ |
+| REQ-1 | Full | Full | Full |
 | REQ-2 | Partial | None | Partial (conservative) |
 ```
 
@@ -693,21 +696,21 @@ When multiple agents produce findings, aggregate as follows:
 
 If `git diff` returns empty:
 ```
-⚠️ No changes detected. Please stage changes or specify a target.
+WARNING: No changes detected. Please stage changes or specify a target.
 ```
 
 ### Missing Config
 
 If `.ocr/config.yaml` doesn't exist:
 ```
-⚠️ OCR not configured. Run `ocr doctor` to check setup.
+WARNING: OCR not configured. Run `ocr doctor` to check setup.
 ```
 
 ### Completeness Failure
 
 If map doesn't include all files:
 ```
-❌ Map incomplete: {missing_count} files not mapped.
+ERROR: Map incomplete: {missing_count} files not mapped.
 Missing: [list files]
 
 Re-running synthesis to include missing files...

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

@@ -8,7 +8,6 @@ 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)
@@ -49,15 +48,15 @@ OCR uses a **round-first architecture** where all round-specific artifacts live
 - 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
+- SQLite tracks `current_round` via `ocr state show`; round metadata derived from filesystem
 
 **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` |
+| `discovered-standards.md` | `reviews/*.md` | `topology.md` |
+| `requirements.md` | `discourse.md` | `flow-analysis.md` |
+| `context.md` | `final.md` | `requirements-mapping.md` |
+| | | `map.md` |
 
 **When to use multiple rounds**:
 - Author addresses feedback and requests re-review
@@ -73,7 +72,7 @@ OCR uses a **run-based architecture** for maps, parallel to review rounds.
 - 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
+- SQLite tracks `current_map_run` via `ocr state show`; run metadata derived from filesystem
 
 **Map artifacts per run**:
 | File | Phase | Description |
@@ -94,7 +93,6 @@ OCR uses a **run-based architecture** for maps, parallel to review rounds.
 
 | 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 |
@@ -135,18 +133,18 @@ rounds/round-1/reviews/performance-1.md   # Custom reviewer
 
 | 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"` |
+| 1 | Context Discovery | `discovered-standards.md`, `requirements.md` (if provided) |
+| 2 | Change Analysis | `context.md`, call `ocr state transition` |
+| 3 | Tech Lead Analysis | Update `context.md` with guidance, call `ocr state transition` |
+| 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` |
+| 8 | Presentation | Call `ocr state close` |
 
 ## State Transitions and File Validation
 
-When updating `state.json`, verify the corresponding file exists:
+When calling `ocr state transition`, verify the corresponding file exists:
 
 | Phase | Verify file exists |
 |---------------------------|-------------------|
@@ -180,30 +178,9 @@ 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
+### Session State
 
-See `references/session-state.md` for complete state management details.
+Session state is stored in SQLite at `.ocr/data/ocr.db`. Use `ocr state show` to inspect current state. See `session-state.md` for the full data model.
 
 ### Reviewer Files
 
@@ -233,14 +210,14 @@ 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) |
+| Session detection | `ocr state show` / SQLite |
+| Phase tracking | SQLite → `current_phase` |
+| Current round | SQLite → `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` |
+| Elapsed time | SQLite → `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:
+**Filesystem as truth**: The CLI derives round metadata from the filesystem, using SQLite as the primary state store. Round-level details are always reconciled against the filesystem by:
 1. Enumerating `rounds/round-*/` to count rounds
 2. Checking `final.md` presence to determine completion
 3. Listing `reviews/*.md` to identify reviewers