check-state

/architect:check-state

Validates _state.json for schema compliance, type errors, and per-command write rule violations. Identifies stale fields, missing required sections, and inconsistencies across state.

Trigger

/architect:check-state
/architect:check-state [--fix]     # auto-fix simple issues
/architect:check-state [--strict]  # fail on warnings (not just errors)

Purpose

The _state.json file accumulates output from 50+ commands, each owning specific fields. Over time, inconsistencies emerge:

• Field values that don't match their declared type (e.g., project.stage is array instead of enum)
• Stale fields (set by command A, never updated, contradicts current command B output)
• Missing required fields for the project's stage
• Violations of per-command write rules (command X overwrote field owned by command Y)

This command scans the state file and reports all issues with severity levels.

Input

No required input. Reads architecture-output/_state.json in the current project.

Output Files

1. architecture-output/state-check-report.md (always generated)

# State Validation Report

**Date:** 2026-04-24 14:32:10  
**Project:** my-startup  
**Stage:** growth  

## Summary

✅ **Pass Rate:** 87/92 checks passed (94%)
❌ **Critical Errors:** 2
⚠️  **Warnings:** 3
ℹ️  **Info:** 0

---

## Critical Issues

### 1. Invalid type: `project.stage` (CRITICAL)
**Field:** `project.stage`  
**Expected:** `"concept" | "mvp" | "growth" | "enterprise"`  
**Actual:** `["mvp", "growth"]` (array, not string!)  
**Consequence:** Downstream commands interpret stage as growth only; this breaks cost estimation and roadmap generation.  
**Fix:** `jq '.project.stage = "growth"' _state.json > _state.json.fixed && mv _state.json.fixed _state.json`

### 2. Stale field: `blueprint.deepen_passes` (CRITICAL)
**Field:** `blueprint.deepen_passes`  
**Value:** `0` (set 30 days ago)  
**Problem:** Current blueprint shows `deepen_passes: 3`, but state shows `0`. This contradicts the actual output.  
**Consequence:** Next blueprint run may not deepen correctly.  
**Fix:** Update to `3` or delete (will be regenerated by next blueprint run).  
**Command:** `jq '.blueprint.deepen_passes = 3' _state.json > _state.json.fixed && mv _state.json.fixed _state.json`

---

## Warnings

### 1. Write-rule violation: `design` field (WARNING)
**Field:** `design`  
**Owned by:** `design-system` command  
**Last modified:** 2026-04-20 (blueprint ran on 2026-04-20, may have overwritten design tokens)  
**Consequence:** Design is out of sync with actual design-system output.  
**Suggested fix:** Run `/architect:design-system` to refresh design tokens.

### 2. Missing recommended field: `entities` (WARNING)
**Stage:** growth  
**Recommendation:** growth-stage projects should have `entities` defined (currently absent).  
**Consequence:** Data-model generation will fall back to SDL entities only (may miss business logic).  
**Suggested fix:** Run `/architect:generate-data-model` to populate entities.

### 3. Unused field: `cost_estimate.old_currency_format` (WARNING)
**Field:** `cost_estimate.old_currency_format`  
**Found:** This field is not in the canonical schema and may be stale.  
**Consequence:** Ignored by all commands.  
**Suggested fix:** Delete via `jq 'del(.cost_estimate.old_currency_format)'`

---

## Schema Validation Passed

✅ All top-level fields are correct types  
✅ All project stage requirements met (growth stage)  
✅ All command-owned field write rules respected (no overlaps)  
✅ Design colors are valid hex (6 verified)  
✅ Component types are recognized (8 components)  
✅ Entity schema looks good (12 entities, all with types)

---

## Recommendations

**Priority 1 (run immediately):**
1. Fix `project.stage` type (array → string)
2. Reconcile `blueprint.deepen_passes` (0 → 3)

**Priority 2 (run before next major command):**
3. Run `/architect:design-system` to refresh design tokens
4. Run `/architect:generate-data-model` to populate entities

**Priority 3 (clean-up, can wait):**
5. Remove unused `cost_estimate.old_currency_format` field

---

## Fix Instructions

**Auto-fix (safe issues only):**
```bash
/architect:check-state --fix

This will:

• Correct type mismatches (array → string, etc.)
• Remove unknown fields
• Preserve all data
• Create backup before modifying

Manual fixes: