conflict-resolution

# Conflict Resolution Guide Step-by-step remediation procedures for each of the 23 consistency rules. Used by `/architect:validate-consistency --fix` to auto-fix safe conflicts, and by users to manually resolve complex conflicts. ## Quick Reference For each conflict type, this guide provides: 1. **Root cause** — why the conflict happened 2. **Impact** — what goes wrong if not fixed 3. **Auto-fix approach** — if `/architect:validate-consistency --fix` can handle it 4. **Manual fix steps** — for when user judgment is needed --- ## State Conflicts (RULE-S-001 through RULE-S-006) ### RULE-S-001: Invalid design color format **Conflict:** Design color field is not a valid hex code. **Root cause:** Typo when editing _state.json, or pasted from color picker in wrong format. **Impact:** Design token generation fails or produces broken CSS variables. #### Auto-Fix - ✅ If color is "f97316" (missing #), add prefix → "#f97316" - ✅ If color is "rgb(249, 115, 22)", convert to nearest hex - ✅ If color is "#F97316" (wrong case), normalize to lowercase - ✅ If color has alpha like "#f97316ff", strip alpha → "#f97316" #### Manual Fix **If auto-fix rejected the color:** ```bash # 1. Identify which color field is invalid jq '.design | to_entries[] | select(.value | test("^#?[0-9a-fA-F]{6}$") | not)' _state.json # 2. Pick a valid hex color using a color picker: # https://htmlcolorcodes.com # (copy the 6-digit hex, e.g., f97316) # 3. Update the field jq '.design.primary = "#<new-hex>"' _state.json > _state.json.tmp && mv _state.json.tmp _state.json # 4. Verify jq '.design.primary' _state.json # should output "#<new-hex>" # 5. Regenerate design tokens /architect:design-system --regenerate ``` --- ### RULE-S-002: Duplicate or invalid component ports **Conflict:** Two components claim the same port, or port is not numeric. **Root cause:** Copy-pasted component without changing port, or manually edited _state.json with invalid value. **Impact:** Local dev server fails with "EADDRINUSE: port already in use". #### Auto-Fix - ✅ If port is string "3000", convert to number 3000 - ❌ Cannot auto-fix duplicate ports (requires user choice) - ❌ Cannot auto-fix out-of-range ports (1024-65535) without knowing what port to use #### Manual Fix **For duplicate ports:** ```bash # 1. List all component ports jq '.components[] | {name, port}' _state.json | sort # 2. Identify duplicates (same port appears twice) # 3. Reassign one component to an unused port: # Free ports: check what's not in the list # Common ports: 3000 (web), 3001, 5000 (api), 5001, 8000, 8001, 9000 # 4. Update the component jq '.components[] | select(.name=="worker-service").port = 3001' _state.json > _state.json.tmp && mv _state.json.tmp _state.json # 5. Verify no more duplicates jq '.components[].port' _state.json | sort | uniq -d # should output nothing ``` **For out-of-range ports:** ```bash # 1. Identify invalid ports jq '.components[] | select(.port < 1024 or .port > 65535) | {name, port}' _state.json # 2. Reassign to valid range (1024-65535) jq '.components[] | select(.name=="api-server").port = 3000' _state.json > _state.json.tmp && mv _state.json.tmp _state.json # 3. Verify jq '.components[].port' _state.json | awk '$1 < 1024 || $1 > 65535 { print "INVALID:", $0 }' ``` --- ### RULE-S-003: Entity in state but not in schema **Conflict:** `_state.json.entities[]` references entity not defined in data model schema. **Root cause:** Entity added to state manually, but schema wasn't regenerated. **Impact:** Future scaffold code generation will miss this entity's ORM definition. #### Auto-Fix - ❌ Cannot auto-fix (requires investigating: is entity real or mistake?) #### Manual Fix **Option A: Add entity to schema** ```bash # 1. Verify the entity is real (intentional) jq '.entities[] | select(.name=="Order")' _state.json # 2. Run generate-data-model to create schema for this entity /architect:generate-data-model --regenerate # 3. Verify entity is now in schema grep -A 20 "model Order" architecture-output/data-model/schema.prisma # 4. Re-run validate-consistency to confirm fix /architect:validate-consistency ``` **Option B: Remove entity from state** (if it's a mistake) ```bash # 1. Confirm entity should be removed jq '.entities[] | select(.name=="Order")' _state.json # 2. Remove from _state.json jq 'del(.entities[] | select(.name=="Order"))' _state.json > _state.json.tmp && mv _state.json.tmp _state.json # 3. Verify removed jq '.entities[] | select(.name=="Order")' _state.json # should output nothing # 4. Run validate-consistency /architect:validate-consistency ``` --- ### RULE-S-004: Invalid tech stack version format **Conflict:** Version string doesn't parse as valid semver. **Root cause:** Typo like "Node.js v18" or "latest" instead of numeric version. **Impact:** Deployment scripts can't pin versions correctly. #### Auto-Fix - ✅ If version is "v18", remove 'v' → "18" - ✅ If version is "18.2", treat as 18.2.0 - ✅ If version has extra parts like "18.2.1.5", use first 3 parts → "18.2.1" - ❌ Cannot auto-fix non-numeric like "latest" #### Manual Fix ```bash # 1. Find invalid versions jq '.tech_stack | to_entries[]' _state.json | grep -v '[0-9]' # 2. Update to valid semver format jq '.tech_stack.backend[0] = "Node.js 18.2.1"' _state.json > _state.json.tmp && mv _state.json.tmp _state.json # 3. Verify format jq '.tech_stack.backend[0]' _state.json # 4. Re-validate /architect:validate-consistency ``` --- ### RULE-S-005: Duplicate persona or decision IDs **Conflict:** Two personas/decisions share the same ID. **Root cause:** Copy-pasted entry without updating ID. **Impact:** Tracking and decision audit is ambiguous; unclear which entry is meant. #### Auto-Fix - ❌ Cannot auto-fix (would require renumbering, which breaks references) #### Manual Fix ```bash # 1. Find duplicates jq '.personas[].id' _state.json | sort | uniq -d # 2. Assign new IDs to duplicates # Schema: P-NNN for personas, D-NNN for decisions # Pattern: increment from highest existing ID # # Current: P-001, P-002, P-003 # New: P-004 for the duplicate # 3. Update the duplicate entry jq '.personas[] |= if .id == "P-003" and .name == "Secondary Persona" then .id = "P-004" else . end' _state.json > _state.json.tmp && mv _state.json.tmp _state.json # 4. Verify no more duplicates jq '.personas[].id' _state.json | sort | uniq -d # should output nothing # 5. Re-validate /architect:validate-consistency ``` --- ### RULE-S-006: Broken references in state **Conflict:** One field references another field that doesn't exist. **Root cause:** Deleted a field but didn't clean up references, or typo in field name. **Impact:** Downstream commands that expect reference to resolve will fail. #### Auto-Fix - ✅ If reference is null/undefined, remove it - ✅ If reference is typo (close match), suggest correction - ❌ If reference is legitimately broken, requires investigation #### Manual Fix ```bash # 1. Identify broken reference # Example: Entity references skill that doesn't exist jq '.personas[] | select(.skills[]? == "unknown_skill")' _state.json # 2. Fix by either: # A. Add the referenced item: jq '.skills += ["unknown_skill"]' _state.json > _state.json.tmp && mv _state.json.tmp _state.json # B. Remove the broken reference: jq '.personas[] |= .skills |= map(select(. != "unknown_skill"))' _state.json > _state.json.tmp && mv _state.json.tmp _state.json # 3. Verify fixed jq '.personas[].skills[]' _state.json # 4. Re-validate /architect:validate-consistency ``` --- ## Output Conflicts (RULE-O-001 through RULE-O-008) ### RULE-O-001: Design tokens don't match state colors **Conflict:** `_state.json.design.primary` is #f97316, but `design-tokens.json.primary` is #0ea5e9. **Root cause:** Blueprint updated state colors, but design-system command didn't regenerate tokens. **Impact:** New components use one color, old components use another → inconsistent UI. #### Auto-Fix - ✅ If tokens file is older than state file, use state colors - ❌ If both are recent, ask user which source is correct #### Manual Fix **Decide which color is right:** ```bash # 1. Compare the two sources echo "State color:" && jq '.design.primary' _state.json echo "Token color:" && jq '.primary' design-system/design-tokens.json # 2. Check git history to see which is more recent git log --oneline _state.json | head -3 git log --oneline design-system/design-tokens.json | head -3 # 3. Option A: Keep state colors (more recent blueprint) /architect:design-system --regenerate # 4. Option B: Keep token colors (revert blueprint) git show <blueprint-commit>:_state.json | jq '.design.primary' > old_color.txt # then manually update _state.json to this color # 5. Verify match echo "After fix:" && jq '.design.primary' _state.json && jq '.primary' design-system/design-tokens.json ``` --- ### RULE-O-002: Scaffold missing components from state **Conflict:** `_state.json` defines component "auth-service", but no `src/services/auth-service/` folder exists. **Root cause:** Component added to state, but scaffold not regenerated. **Impact:** Incomplete project structure; dev expects service to exist. #### Auto-Fix - ❌ Cannot auto-fix (requires running scaffold or scaffold-component) #### Manual Fix ```bash # 1. List missing components jq '.components[].name' _state.json | while read c; do c_kebab=$(echo "$c" | sed 's/[A-Z]/-\L&/g') if [ ! -d "src/services/$c_kebab" ] && [ ! -d "src/components/$c_kebab" ]; then echo "Missing: $c" fi done # 2. Regenerate entire scaffold /architect:scaffold # OR: Add individual components /architect:scaffold-component --name auth-service # 3. Verify components now exist ls -la src/services/ | grep auth-service ls -la src/components/ | grep auth-service # 4. Re-validate /architect:validate-consistency ``` --- ### RULE-O-003: Cost estimate is stale **Conflict:** Cost estimate was generated 30 days ago with 8 components; state now has 12 components. **Root cause:** Cost estimate wasn't regenerated after architecture changed. **Impact:** Budget projections are 25% undercounted. #### Auto-Fix - ✅ Can detect staleness, but regeneration requires running command #### Manual Fix ```bash # 1. Identify stale estimate ls -la architecture-output/cost-estimate.md # 2. Regenerate /architect:cost-estimate --regenerate # 3. Compare old vs new echo "Old estimate:" && grep -A 5 "monthly" cost-estimate.md.backup echo "New estimate:" && grep -A 5 "monthly" architecture-output/cost-estimate.md # 4. Update budget if needed # Use new numbers for planning # 5. Re-validate /architect:validate-consistency ``` --- ### RULE-O-004: Invalid test coverage percentage **Conflict:** Test coverage is reported as 150% (impossible). **Root cause:** Bug in test command, or manual edit of coverage field. **Impact:** Dashboards break; coverage metrics are nonsensical. #### Auto-Fix - ✅ Clamp to 0-100 range - ✅ If >100, use 100; if <0, use 0 #### Manual Fix ```bash # 1. Identify invalid coverage jq '.test_suite.coverage' architecture-output/_state.json # 2. If >100, set to 100: