feat: Define review-state.json schema and provide validation/write commands #187

Merged

mprihoda merged 22 commits from IW-136 into main

2026-01-29 21:06:32 +00:00

mprihoda commented

2026-01-28 20:03:09 +00:00

(Migrated from github.com)

Summary

Formalizes the review-state.json contract by making iw-cli the schema owner, providing validation and write commands for workflow tools to reliably produce valid state files.

JSON Schema (Draft-07) at schemas/review-state.schema.json defines all fields, types, and constraints
iw validate-review-state validates files against the schema with clear error messages
iw write-review-state constructs valid state from CLI flags with auto-populated git context

Changes

Phase 1: JSON Schema formally defines contract

schemas/review-state.schema.json - Formal JSON Schema Draft-07
schemas/README.md - Versioning policy documentation
Test fixtures for valid and invalid cases
6 BATS E2E tests

Phase 2: Validation command

ReviewStateValidator - Pure validation logic (35 unit tests)
validate-review-state CLI command (file + stdin modes)
10 BATS E2E tests

Phase 3: Write command

ReviewStateBuilder - Pure JSON construction from typed inputs
write-review-state CLI command (flags + stdin modes)
Auto-populates issue_id, git_sha, last_updated from git context
Validates before writing
11 unit tests + 9 BATS E2E tests

Refactoring R1: Separate display from workflow semantics

After initial implementation, we refactored the schema to properly separate concerns:

Removed fields (workflow-specific or redundant):

phase, step, branch, batch_mode

Made optional:

status (now machine identifier only, not for display)

Added fields:

display object: {text, subtext, type} - workflow tells dashboard what to render
badges array: contextual indicators like {label: "Batch", type: "info"}
task_lists array: file paths for progress computation
needs_attention boolean: attention-grabbing indicator

Key principle: Dashboard renders what it's told without interpreting workflow-specific vocabulary. Workflow owns semantics, dashboard owns structure.

Phase PRs

Phase 1: https://github.com/iterative-works/iw-cli/pull/184
Phase 2: https://github.com/iterative-works/iw-cli/pull/185
Phase 3: https://github.com/iterative-works/iw-cli/pull/186

Testing

Unit tests: 57 tests added
E2E tests: 25 BATS tests added
All tests passing

Release Notes

Release notes (Czech)

Closes IW-136

🤖 Generated with Claude Code

## Summary Formalizes the review-state.json contract by making iw-cli the schema owner, providing validation and write commands for workflow tools to reliably produce valid state files. - **JSON Schema** (Draft-07) at `schemas/review-state.schema.json` defines all fields, types, and constraints - **`iw validate-review-state`** validates files against the schema with clear error messages - **`iw write-review-state`** constructs valid state from CLI flags with auto-populated git context ## Changes ### Phase 1: JSON Schema formally defines contract - `schemas/review-state.schema.json` - Formal JSON Schema Draft-07 - `schemas/README.md` - Versioning policy documentation - Test fixtures for valid and invalid cases - 6 BATS E2E tests ### Phase 2: Validation command - `ReviewStateValidator` - Pure validation logic (35 unit tests) - `validate-review-state` CLI command (file + stdin modes) - 10 BATS E2E tests ### Phase 3: Write command - `ReviewStateBuilder` - Pure JSON construction from typed inputs - `write-review-state` CLI command (flags + stdin modes) - Auto-populates issue_id, git_sha, last_updated from git context - Validates before writing - 11 unit tests + 9 BATS E2E tests ### Refactoring R1: Separate display from workflow semantics After initial implementation, we refactored the schema to properly separate concerns: **Removed fields** (workflow-specific or redundant): - `phase`, `step`, `branch`, `batch_mode` **Made optional:** - `status` (now machine identifier only, not for display) **Added fields:** - `display` object: `{text, subtext, type}` - workflow tells dashboard what to render - `badges` array: contextual indicators like `{label: "Batch", type: "info"}` - `task_lists` array: file paths for progress computation - `needs_attention` boolean: attention-grabbing indicator **Key principle:** Dashboard renders what it's told without interpreting workflow-specific vocabulary. Workflow owns semantics, dashboard owns structure. ## Phase PRs - Phase 1: https://github.com/iterative-works/iw-cli/pull/184 - Phase 2: https://github.com/iterative-works/iw-cli/pull/185 - Phase 3: https://github.com/iterative-works/iw-cli/pull/186 ## Testing - Unit tests: 57 tests added - E2E tests: 25 BATS tests added - All tests passing ## Release Notes [Release notes (Czech)](https://github.com/iterative-works/iw-cli/blob/IW-136/project-management/issues/IW-136/release-notes.md) Closes IW-136 🤖 Generated with [Claude Code](https://claude.com/claude-code)