FR: Add check-design command — evaluate designs against architectural beliefs

[benthomasson]

Summary

Add a check-design command that evaluates a proposed change against the project's accumulated architectural beliefs before implementation begins. This enables a pre-implementation design gate in SDLC workflows.

Motivation

Architectural violations are cheapest to fix before code is written. Today, code-expert builds a rich belief store of architectural invariants (dependency rules, data ownership, API contracts), but these are only surfaced reactively — via nightly updates or manual queries. check-design would make these beliefs available as an active gate at design time.

Proposed Behavior

code-expert check-design --story "Add direct DB query in API handler for user metrics"
code-expert check-design --file design-doc.md
code-expert check-design --jira PROJ-1234

Input

• Story description (text, file, or Jira issue key)
• Target repo (defaults to current project)

Processing

1. Load project beliefs filtered to architecture/dependency/contract types
2. Optionally load SDP constraints if linked
3. LLM evaluates the proposed design against relevant beliefs
4. Flag violations with specific belief references

Output

Structured verdict:

• PASS — no architectural violations detected
• CONCERN — potential issues worth discussing (e.g., touching a module boundary)
• BLOCK — clear violation of established invariants (e.g., circular dependency, wrong data ownership)

Each finding references the specific belief(s) violated and explains why.

Edge Cases

• No belief store: Run in RECOMMENDED mode — warn that no beliefs exist, suggest running code-expert scan + explore first
• Thin belief store: Note low confidence in the verdict, list which areas have coverage vs gaps
• Belief store conflicts: If beliefs contradict each other, surface the contradiction rather than silently picking one

Example

Given beliefs:

• "Core never imports plugins; plugins import core"
• "Dataverse mart is the single source of truth for metrics"
• "All HTTP handlers go through middleware before route logic"

And a story: "Add a direct database query in the API handler to fetch user metrics"

Output:

Verdict: BLOCK

Findings:
1. BLOCK: Violates "All data access goes through the service layer"
   - Story proposes direct DB query in API handler
   - Belief: core.data_access (belief #42)

2. BLOCK: Violates "Dataverse mart is the single source of truth for metrics"
   - Story proposes fetching metrics directly from database
   - Belief: core.data_ownership (belief #67)

Context

Part of the AAP SDLC Quality Enhancement Roadmap (Story 1.2). Would be invoked by the harness story-implementation-workflow skill as a gate before coding begins.