feat: Define review-state.json schema and provide workflow integration commands #192

Merged

mprihoda merged 6 commits from IW-136 into main

2026-02-03 16:18:37 +00:00

mprihoda commented

2026-02-03 15:01:18 +00:00

(Migrated from github.com)

Summary

This PR establishes a formal contract for review-state.json files used by workflows to communicate with the iw-cli dashboard. Previously, the schema was implicit, leading to fragile integration. Now workflows have clear, authoritative guidance and validation tools.

Changes

Phase 1: JSON Schema formally defines contract

Created schemas/review-state.schema.json - JSON Schema Draft-07 definition
Documented versioning policy in schemas/README.md
Added test fixtures for validation testing

Phase 2: Validation command for review state

Implemented ReviewStateValidator with pure validation logic
Created validation command (now iw review-state validate)
35 unit tests, 10 E2E tests

Phase 3: Write command for review state

Implemented ReviewStateBuilder for JSON construction from typed inputs
Created write command (now iw review-state write)
Auto-populates issue_id, git_sha, last_updated
Validates before writing to prevent invalid files

Refactoring R1: Separate display from workflow semantics

Upgraded schema to v1 with clear separation of concerns
Removed workflow-specific fields (phase, step, branch, batch_mode)
Added display object for dashboard rendering instructions
Added badges array for contextual indicators
Added task_lists array for progress tracking
Dashboard now renders what workflows provide, no interpretation

Refactoring R2: Add update command and restructure as subcommands

Restructured commands as subcommands: iw review-state {validate|write|update}
Implemented ReviewStateUpdater with merge logic
Added update command for partial state modification
Array merge modes: replace (default), append, clear
Documented public API in docs/commands/review-state.md
Backward compatibility guarantees

Testing

Unit tests: 54 tests (builder, validator, updater, git adapter)
E2E tests: 27 BATS tests (validate, write, update commands)
All scenarios verified
All tests passing

Release Notes

User-facing release notes (Czech)

Documentation

Closes IW-136

🤖 Generated with Claude Code

## Summary This PR establishes a formal contract for `review-state.json` files used by workflows to communicate with the iw-cli dashboard. Previously, the schema was implicit, leading to fragile integration. Now workflows have clear, authoritative guidance and validation tools. ## Changes ### Phase 1: JSON Schema formally defines contract - Created `schemas/review-state.schema.json` - JSON Schema Draft-07 definition - Documented versioning policy in `schemas/README.md` - Added test fixtures for validation testing ### Phase 2: Validation command for review state - Implemented `ReviewStateValidator` with pure validation logic - Created validation command (now `iw review-state validate`) - 35 unit tests, 10 E2E tests ### Phase 3: Write command for review state - Implemented `ReviewStateBuilder` for JSON construction from typed inputs - Created write command (now `iw review-state write`) - Auto-populates issue_id, git_sha, last_updated - Validates before writing to prevent invalid files ### Refactoring R1: Separate display from workflow semantics - Upgraded schema to v1 with clear separation of concerns - Removed workflow-specific fields (phase, step, branch, batch_mode) - Added `display` object for dashboard rendering instructions - Added `badges` array for contextual indicators - Added `task_lists` array for progress tracking - Dashboard now renders what workflows provide, no interpretation ### Refactoring R2: Add update command and restructure as subcommands - Restructured commands as subcommands: `iw review-state {validate|write|update}` - Implemented `ReviewStateUpdater` with merge logic - Added `update` command for partial state modification - Array merge modes: replace (default), append, clear - Documented public API in `docs/commands/review-state.md` - Backward compatibility guarantees ## Testing - Unit tests: 54 tests (builder, validator, updater, git adapter) - E2E tests: 27 BATS tests (validate, write, update commands) - All scenarios verified - All tests passing ## Release Notes [User-facing release notes (Czech)](https://github.com/iterative-works/iw-cli/blob/IW-136/project-management/issues/IW-136/release-notes.md) ## Documentation - [Public API Reference](https://github.com/iterative-works/iw-cli/blob/IW-136/docs/commands/review-state.md) - [Schema Documentation](https://github.com/iterative-works/iw-cli/blob/IW-136/schemas/README.md) - [Implementation Log](https://github.com/iterative-works/iw-cli/blob/IW-136/project-management/issues/IW-136/implementation-log.md) Closes IW-136 🤖 Generated with [Claude Code](https://claude.com/claude-code)