|
| 1 | +--- |
| 2 | +description: Validate plan alignment with architecture (READ-ONLY) |
| 3 | +--- |
| 4 | + |
| 5 | + |
| 6 | +<!-- Extension: architect --> |
| 7 | +<!-- Config: .specify/extensions/architect/ --> |
| 8 | +# adlc.architect.validate |
| 9 | + |
| 10 | +Validate that the plan aligns with the architecture and identify any blocking issues. |
| 11 | + |
| 12 | +## Usage |
| 13 | + |
| 14 | +```text |
| 15 | +/architect.validate --for-plan |
| 16 | +/architect.validate --json |
| 17 | +/architect.validate --system-only |
| 18 | +/architect.validate --check-only PILLAR_3 |
| 19 | +``` |
| 20 | + |
| 21 | +## Flags |
| 22 | + |
| 23 | +| Flag | Description | |
| 24 | +|------|-------------| |
| 25 | +| `--for-plan` | Validate against the generated plan (default behavior) | |
| 26 | +| `--json` | Output findings in JSON format for easier parsing | |
| 27 | +| `--system-only` | Check only system-level ADRs, ignore feature-level | |
| 28 | +| `--check-only [check]` | Run only specific checks: PILLAR_1, PILLAR_2, PILLAR_3, or DIAGRAMS | |
| 29 | + |
| 30 | +## Behavior |
| 31 | + |
| 32 | +This is a **READ-ONLY** validation command. It does not modify any files. |
| 33 | + |
| 34 | +### When Architecture Exists |
| 35 | + |
| 36 | +If ADRs exist in any location (check all three): |
| 37 | + |
| 38 | +1. Load ADRs from all locations (priority order): |
| 39 | + - `{REPO_ROOT}/.specify/memory/adr.md` (canonical - Accepted ADRs) |
| 40 | + - `{TEAM_DIRECTIVES}/context_modules/adr.md` (team canonical - if configured) |
| 41 | + - `{REPO_ROOT}/.specify/drafts/adr.md` (working copy - Proposed/Discovered) |
| 42 | +2. Load architecture description from `AD.md` (if present) |
| 43 | +3. Load the generated plan from `{REPO_ROOT}/.specify/memory/plan.md` |
| 44 | +4. Execute 7 PILLAR 3 checks: |
| 45 | + - **PILLAR_1**: Component-level ADR alignment with plan |
| 46 | + - **PILLAR_2**: Interface contracts match between plan and ADRs |
| 47 | + - **PILLAR_3**: Data model consistency between plan and architecture |
| 48 | + - **PILLAR_4**: Consistency between plan's Q1 user flows and architecture's System Context |
| 49 | + - **PILLAR_5**: Consistency between plan's interactions and architecture's Functional View |
| 50 | + - **PILLAR_6**: Consistency between plan's data model and architecture's Information View |
| 51 | + - **PILLAR_7**: Consistency between plan's dependencies and architecture's Development View |
| 52 | +5. Check diagram consistency (system boundary matches, data flows valid) |
| 53 | +6. Return findings with severity: |
| 54 | + - **blocking**: Must be fixed before proceeding |
| 55 | + - **high-severity**: Should be fixed before proceeding |
| 56 | + - **warnings**: Recommendations |
| 57 | + |
| 58 | +### When Architecture Doesn't Exist |
| 59 | + |
| 60 | +If no ADRs exist in any location: |
| 61 | + |
| 62 | +- Skip validation gracefully |
| 63 | +- Return `{"status":"skipped","reason":"architecture_not_found"}` if `--json` flag used |
| 64 | + |
| 65 | +### Escalation Detection |
| 66 | + |
| 67 | +This command also detects when architectural decisions in the plan **require new ADRs** that don't exist: |
| 68 | + |
| 69 | +1. Analyze plan for architectural keywords: |
| 70 | + - "new database", "new service", "new API", "new infrastructure" |
| 71 | + - "change authentication", "change storage", "change deployment" |
| 72 | +2. Compare against existing ADRs |
| 73 | +3. If new patterns detected without ADR backing → signal escalation |
| 74 | + |
| 75 | +**Escalation Output:** |
| 76 | + |
| 77 | +```text |
| 78 | +⚠️ Escalation Required |
| 79 | + New architectural decisions detected without ADR backing: |
| 80 | + - "Caching layer (Redis)" - No ADR covers caching decisions |
| 81 | + - "Message queue (RabbitMQ)" - No ADR covers async communication |
| 82 | +
|
| 83 | + Run /architect.clarify to document these decisions before proceeding. |
| 84 | +``` |
| 85 | + |
| 86 | +```json |
| 87 | +{ |
| 88 | + "escalation": { |
| 89 | + "needed": true, |
| 90 | + "reason": "new_architectural_decision", |
| 91 | + "decisions": [ |
| 92 | + { |
| 93 | + "topic": "Caching layer", |
| 94 | + "evidence": "Plan references Redis but no ADR covers caching", |
| 95 | + "suggested_action": "Run /architect.clarify to create ADR" |
| 96 | + }, |
| 97 | + { |
| 98 | + "topic": "Async communication", |
| 99 | + "evidence": "Plan references RabbitMQ but no ADR covers message queuing", |
| 100 | + "suggested_action": "Run /architect.clarify to create ADR" |
| 101 | + } |
| 102 | + ] |
| 103 | + } |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +**This enables the `before_plan` hook to signal when new architectural decisions are needed.** |
| 108 | + |
| 109 | +Example output: |
| 110 | + |
| 111 | +```text |
| 112 | +⏭️ Architecture not found (no ADRs in drafts/memory/team) |
| 113 | + Skipping validation gracefully |
| 114 | +``` |
| 115 | + |
| 116 | +## Output Format |
| 117 | + |
| 118 | +### Console Output (default) |
| 119 | + |
| 120 | +```text |
| 121 | +🔍 Architecture Validation Mode (READ-ONLY) |
| 122 | +
|
| 123 | +📋 ADR files found: N |
| 124 | + - memory: X ADR(s) |
| 125 | + - team: Y ADR(s) [if configured] |
| 126 | + - drafts: Z ADR(s) |
| 127 | +
|
| 128 | +Executing validation checks... |
| 129 | + ✓ PILLAR_1: Component alignment (0 issues) |
| 130 | + ✗ PILLAR_2: Interface contracts (2 high-severity) |
| 131 | + ✓ PILLAR_3: Data model consistency (0 issues) |
| 132 | + ✓ PILLAR_4: System context (0 issues) |
| 133 | + ⚠️ PILLAR_5: Functional consistency (3 warnings) |
| 134 | + ✓ PILLAR_6: Information view (0 issues) |
| 135 | + ✓ PILLAR_7: Development view (0 issues) |
| 136 | + ⚠️ Diagram consistency (2 warnings) |
| 137 | +
|
| 138 | +Blockers: 0 |
| 139 | +High-severity: 2 |
| 140 | +Warnings: 5 |
| 141 | +``` |
| 142 | + |
| 143 | +### JSON Output (`--json`) |
| 144 | + |
| 145 | +```json |
| 146 | +{ |
| 147 | + "status": "success", |
| 148 | + "action": "validate", |
| 149 | + "adr_locations": { |
| 150 | + "memory": "{REPO_ROOT}/.specify/memory/adr.md", |
| 151 | + "team": "{TEAM_DIRECTIVES}/context_modules/adr.md", |
| 152 | + "drafts": "{REPO_ROOT}/.specify/drafts/adr.md" |
| 153 | + }, |
| 154 | + "adr_count": 12, |
| 155 | + "findings": { |
| 156 | + "blocking": [], |
| 157 | + "high_severity": [ |
| 158 | + { |
| 159 | + "check": "PILLAR_2", |
| 160 | + "component": "UserAuthService", |
| 161 | + "issue": "Interface contract missing from plan", |
| 162 | + "description": "Plan references UserAuthService.login() but ADR doesn't define this method" |
| 163 | + }, |
| 164 | + { |
| 165 | + "check": "PILLAR_2", |
| 166 | + "component": "OrderService", |
| 167 | + "issue": "Parameters don't match ADR specification", |
| 168 | + "description": "ADR expects createOrder(userId, items) but plan uses createOrder(items) without userId" |
| 169 | + } |
| 170 | + ], |
| 171 | + "warnings": [ |
| 172 | + { |
| 173 | + "check": "PILLAR_5", |
| 174 | + "component": "Functional view", |
| 175 | + "issue": "Missing interaction in AD.md", |
| 176 | + "description": "Plan describes user registration flow but AD.md Functional View doesn't include AuthService.register()" |
| 177 | + } |
| 178 | + ], |
| 179 | + "diagrams": { |
| 180 | + "consistency": "warning", |
| 181 | + "issues": [ |
| 182 | + { |
| 183 | + "diagram": "Context View", |
| 184 | + "issue": "External system not shown", |
| 185 | + "description": "Plan references PaymentGateway but Context View doesn't include this external system" |
| 186 | + } |
| 187 | + ] |
| 188 | + } |
| 189 | + }, |
| 190 | + "summary": { |
| 191 | + "total_checks": 8, |
| 192 | + "passed": 5, |
| 193 | + "warnings": 3 |
| 194 | + } |
| 195 | +} |
| 196 | +``` |
| 197 | + |
| 198 | +## Integration |
| 199 | + |
| 200 | +This command is automatically called by the `after_plan` hook: |
| 201 | + |
| 202 | +- Validates plan alignment with architecture |
| 203 | +- The command itself checks for architecture existence and skips gracefully |
| 204 | +- Returns `{"status":"skipped","reason":"architecture_not_found"}` if no architecture exists |
| 205 | + |
| 206 | +## Exit Codes |
| 207 | + |
| 208 | +| Code | Meaning | |
| 209 | +|------|---------| |
| 210 | +| 0 | Success or skipped gracefully | |
| 211 | +| 1 | Validation failed with blocking issues | |
0 commit comments