@zigrivers/scaffold 2.1.2 → 2.28.1

package/knowledge/review/{review-api-contracts.md → review-api-design.md}

@@ -1,5 +1,5 @@
 ---
-name: review-api-contracts
+name: review-api-design
 description: Failure modes and review passes specific to API contract specifications
 topics: [review, api, contracts, rest, graphql]
 ---
@@ -231,3 +231,36 @@ The implementation tasks step needs:
 - P0: "The UX wireframe shows a 'user dashboard' with order count, recent orders, and account balance, but the API has no endpoint that provides this aggregated data. The frontend would need to make 3+ separate calls."
 - P1: "Several endpoints are marked as 'async' (returns 202) but there is no documented polling or webhook mechanism for the frontend to get the result."
 - P2: "API response examples do not include null/empty cases. The UX spec needs to know what an empty order list or a user with no profile photo looks like in API terms."
+
+### Example Review Finding
+
+```markdown
+### Finding: Payment endpoint missing idempotency specification
+
+**Pass:** 6 — Idempotency
+**Priority:** P0
+**Location:** API Contract Section 5.3 "POST /payments/charge"
+
+**Issue:** The POST /payments/charge endpoint accepts a payment method and amount,
+charges the customer, and returns a payment confirmation. The endpoint documents
+only the 201 (success) and 400 (bad request) responses.
+
+No idempotency mechanism is specified. If a client sends a charge request and
+receives a network timeout (no response), it cannot safely retry — the retry
+may charge the customer a second time. This is a financial data integrity issue.
+
+**Impact:** Frontend developers will either (a) not retry on timeout, leaving
+the user unsure if payment succeeded, or (b) retry unconditionally, risking
+double charges. Both outcomes damage user trust and create support burden.
+
+**Recommendation:** Add an Idempotency-Key header requirement:
+- Client must include `Idempotency-Key: <uuid>` on every POST /payments/charge
+- Server stores the key with the payment result for 24 hours
+- Repeated requests with the same key return the original result without
+  re-processing
+- Document the key format (UUIDv4), retention window (24h), and behavior on
+  key reuse (return cached result with 200, not 201)
+
+**Trace:** API Contract 5.3 → PRD Section 3.2 "Payment Processing" →
+ADR-009 "Financial data integrity requirements"
+```

package/knowledge/review/{review-database-schema.md → review-database-design.md}

@@ -1,5 +1,5 @@
 ---
-name: review-database-schema
+name: review-database-design
 description: Failure modes and review passes specific to database schema design artifacts
 topics: [review, database, schema, data-modeling]
 ---
@@ -227,3 +227,29 @@ The API contracts step specifically needs:
 - P0: "API will need 'get all orders for a customer with their line items and product details.' This requires joining orders -> line_items -> products, but line_items has no index on order_id, and the relationship from line_items to products is missing."
 - P1: "The schema supports 'get user by email' but the API will also need 'search users by name.' No index exists on user name columns."
 - P2: "Some tables use soft delete (deleted_at column) and some use hard delete. The API contract needs to know which approach applies to determine whether 'delete' operations return 204 or 200."
+
+### Example Review Finding
+
+```markdown
+### Finding: Missing composite index for primary order query pattern
+
+**Pass:** 4 — Index Coverage
+**Priority:** P0
+**Location:** orders table, schema.sql lines 45-72
+
+**Issue:** Architecture data flow DF-003 ("Customer views order history") describes
+the primary query as "find all orders by customer, sorted by most recent first." This
+query filters on customer_id and sorts on created_at DESC. The orders table has a
+single-column index on customer_id but no composite index on (customer_id, created_at).
+
+**Impact:** Without a composite index, PostgreSQL will use the customer_id index to
+filter, then perform a filesort on the matching rows. At projected volume (50K orders
+per customer for enterprise accounts), this filesort will cause multi-second response
+times on the most frequently executed query.
+
+**Recommendation:** Add composite index: CREATE INDEX idx_orders_customer_date
+ON orders (customer_id, created_at DESC). The DESC matches the sort direction,
+enabling an index-only scan for this query pattern.
+
+**Trace:** Architecture data flow DF-003 → PRD Feature 2.1 "Order History"
+```

package/knowledge/review/review-domain-modeling.md

@@ -286,3 +286,36 @@ Internal inconsistencies within a single domain model erode trust in the artifac
 - P0: "Invariant 'PaymentAmount must not exceed OrderTotal' references PaymentAmount, but the Payment entity has an attribute called 'amount', not 'paymentAmount'."
 - P1: "Relationship diagram shows Order -> Customer as one-to-many, but the Order entity definition says 'each order belongs to one customer' (many-to-one). Direction is inverted."
 - P2: "The Inventory domain model calls the same concept 'stock level' in the overview and 'quantity on hand' in the entity definition."
+
+### Example Review Finding
+
+```markdown
+### Finding: Aggregate boundary cannot enforce cross-aggregate invariant
+
+**Pass:** 4 — Aggregate Boundary Validation
+**Priority:** P0
+**Location:** Order aggregate and Discount aggregate (domain-models.md, Section 3.2)
+
+**Issue:** Domain invariant INV-007 states "discount amount must not exceed order
+subtotal." Enforcing this requires access to both the Order aggregate (to read the
+subtotal, which is the sum of line items) and the Discount aggregate (to read the
+discount amount). These are modeled as separate aggregates with independent
+lifecycles.
+
+Because aggregates are consistency boundaries, there is no transactional guarantee
+that the discount and order subtotal are evaluated atomically. A line item could be
+removed from the Order (reducing subtotal) after a discount was validated against
+the previous subtotal, violating the invariant.
+
+**Impact:** Without resolution, implementing agents will either (a) ignore the
+invariant, allowing invalid discount states, or (b) create tight coupling between
+Order and Discount aggregates, defeating the purpose of the boundary.
+
+**Recommendation:** Move Discount inside the Order aggregate as a value object.
+The discount lifecycle is tied to the order — discounts do not exist independently.
+This allows the Order aggregate root to enforce INV-007 within a single
+consistency boundary.
+
+**Trace:** Invariant INV-007 → Order aggregate + Discount aggregate → PRD
+Feature 3.4 "Apply discount codes at checkout"
+```

package/knowledge/review/review-implementation-tasks.md

@@ -200,3 +200,53 @@ AI agents have limited context windows. If a task does not specify what to read,
 - P0: "Task 'Implement order creation endpoint' lists no context documents. The agent needs the API contract (endpoint spec), database schema (orders table), domain model (Order aggregate invariants), and architecture section (Order Service design)."
 - P1: "Task 'Build user dashboard' references the architecture document but not the UX spec. The agent will build the component structure correctly but not the visual design."
 - P2: "Task context references 'docs/system-architecture.md' without specifying which section. The agent will load the entire 2000-line document instead of the relevant 100-line section."
+
+---
+
+## Common Review Anti-Patterns
+
+### 1. Reviewing Tasks in Isolation
+
+The reviewer checks each task individually (sizing, acceptance criteria, context) but never builds the full dependency graph or traces the critical path. Individual tasks may look fine, but the overall task structure has cycles, missing coverage, or an incorrect critical path. Passes 2, 5, and 6 require looking at the task set as a whole, not one task at a time.
+
+**How to spot it:** The review report has findings only from Passes 3, 4, and 7 (task-level checks) and none from Passes 1, 2, 5, or 6 (structural checks). The reviewer never drew the dependency graph.
+
+### 2. Trusting Dependency Declarations Without Verification
+
+The reviewer reads the declared dependencies for each task and checks for cycles, but never verifies that the declared dependencies are complete. A task that says "depends on: database schema" may also implicitly depend on "auth middleware" (because the endpoint requires authentication), but this dependency is not declared. The reviewer must read the task description and infer actual prerequisites, not just validate declared ones.
+
+**Example finding:**
+
+```markdown
+## Finding: ITR-022
+
+**Priority:** P0
+**Pass:** Missing Dependencies (Pass 2)
+**Document:** docs/implementation-tasks.md, Task 14
+
+**Issue:** Task 14 ("Implement order creation endpoint") declares dependency on Task 3
+("Create database schema") but does not declare dependency on Task 7 ("Implement auth
+middleware"). The task's acceptance criteria include "returns 401 for unauthenticated
+requests," which requires auth middleware to exist. If an agent starts Task 14 before
+Task 7 is complete, they cannot implement or test the auth requirement.
+
+**Recommendation:** Add Task 7 as an explicit dependency for Task 14.
+```
+
+### 3. Accepting "Implement Feature X" as a Valid Task
+
+The reviewer sees a task titled "Implement user management" with acceptance criteria listing 8 endpoints, 3 database tables, 2 background jobs, and role-based access control — and does not flag it as too large. A single task should be completable in one agent session (30-60 minutes). "Implement user management" is a project phase, not a task.
+
+**How to spot it:** Count the acceptance criteria and the distinct concerns. More than 5-7 acceptance criteria or more than 2 distinct concerns (e.g., API + database + auth) means the task needs splitting.
+
+### 4. Ignoring Test Tasks
+
+The reviewer verifies implementation tasks but does not check whether corresponding test tasks exist. The testing strategy says "integration tests for all API endpoints," but there is no task for writing those tests. Tests are not free — they require their own implementation time, and if no task exists for them, they will not be written.
+
+**How to spot it:** For each implementation task, search for a corresponding test task. If implementation tasks outnumber test tasks by more than 3:1, testing is systematically under-tasked.
+
+### 5. No Verification of Parallelization Claims
+
+Tasks are marked as parallelizable, and the reviewer accepts this at face value. But two tasks marked as parallel both modify `src/config/database.ts` or both add routes to the same router file. The reviewer must check for shared file modifications, not just logical independence.
+
+**How to spot it:** The review has no findings from Pass 6 (Parallelization Validity). The reviewer checked for logical dependencies but not for file-level conflicts.

package/knowledge/review/review-operations.md

@@ -210,3 +210,58 @@ Without a backup strategy, data loss is permanent. Without a disaster recovery p
 - P0: "Backups run daily but the RPO is 15 minutes. Up to 24 hours of data could be lost, far exceeding the business tolerance."
 - P1: "Backup restoration procedure says 'restore from backup' with no specifics. What tool? What command? How long does it take? What is the verification step?"
 - P2: "DR strategy exists but has never been tested. The team does not know if recovery actually works within the stated RTO."
+
+---
+
+## Common Review Anti-Patterns
+
+### 1. Reviewing the Runbook as a Standalone Document
+
+The reviewer checks the operations runbook for completeness (are all sections present? are rollback procedures documented?) but never cross-references with the architecture or deployment infrastructure. The runbook may describe a deployment pipeline that does not match the actual CI/CD configuration, or monitoring that covers components that no longer exist. Operations documentation must be validated against the architecture it describes.
+
+**How to spot it:** The review has no findings that reference the architecture document or infrastructure configuration. All findings are about what the runbook says, not whether what it says matches reality.
+
+### 2. "We Use Kubernetes" as a Complete Deployment Strategy
+
+The deployment section names the orchestration platform (Kubernetes, ECS, Heroku) but does not describe the actual deployment process. How are images built? How are they tagged? What triggers a deployment? What is the rollout strategy (rolling update, blue-green, canary)? What happens when a pod fails health checks during rollout? Naming the platform is not a strategy.
+
+**Example finding:**
+
+```markdown
+## Finding: OPS-011
+
+**Priority:** P1
+**Pass:** Deployment Strategy Completeness (Pass 1)
+**Document:** docs/operations-runbook.md, Section 2
+
+**Issue:** Deployment section states: "The application is deployed to Kubernetes using
+Helm charts." No further detail is provided. The following questions are unanswered:
+  - What triggers a deployment? (manual, on PR merge, on tag?)
+  - What is the rollout strategy? (rolling update, blue-green, canary?)
+  - What are the health check endpoints and thresholds?
+  - When do database migrations run relative to the code deployment?
+  - What is the rollback procedure? (Helm rollback? Redeploy previous image?)
+  - How long does a typical deployment take?
+
+**Recommendation:** Expand the deployment section to cover each stage of the pipeline
+from merged PR to verified production deployment, with specific commands, tools,
+and decision points.
+```
+
+### 3. Monitoring Section Lists Tools but Not Metrics
+
+The monitoring section says "we use Datadog for monitoring and PagerDuty for alerting" but does not specify what metrics are collected, what dashboards exist, or what alert thresholds are configured. Tools are not a monitoring strategy. The question is not "do we have Datadog?" but "what does Datadog measure, and when does it wake someone up?"
+
+**How to spot it:** The monitoring section mentions tool names but contains no metric names (error rate, p95 latency, request throughput), no threshold values, and no alert severity definitions.
+
+### 4. Rollback Procedure That Ignores Data
+
+The rollback section describes how to revert code (redeploy previous version, Helm rollback) but does not address database schema changes or data migrations. If the deployment included a migration that added a column and backfilled data, "rollback" is not just reverting the code — it requires a reverse migration, and the reverse migration may be destructive (dropping the new column loses the backfilled data).
+
+**How to spot it:** The rollback section mentions code rollback but not database rollback. Search for "migration," "schema," or "database" in the rollback procedure — if absent, data rollback is unaddressed.
+
+### 5. No Runbook Entries for the Most Likely Failures
+
+The runbook has procedures for exotic failure scenarios (complete region outage, database corruption) but not for the failures that actually happen weekly: a single pod crashing, a dependency timing out, disk filling up from log accumulation, a certificate expiring. The most useful runbook entries cover common, mundane failures — not catastrophic ones.
+
+**How to spot it:** Count runbook entries. If there are fewer than 5, the most likely failure scenarios are probably missing. Check specifically for: service restart, dependency timeout, disk full, certificate expiration, and failed deployment rollback.

package/knowledge/review/review-prd.md

@@ -233,3 +233,36 @@ The PRD's primary consumer is the user stories phase. If features are too vague
 
 - P0: "Feature 'user management' cannot be decomposed into stories — what operations? What user types? What permissions model?"
 - P1: "Business rules for discount application are implied but not stated — story acceptance criteria will have to guess at validation logic."
+
+### Example Review Finding
+
+```markdown
+### Finding: NFRs use qualitative adjectives instead of quantified targets
+
+**Pass:** 5 — NFR Quantification
+**Priority:** P1
+**Location:** PRD Section 6 "Non-Functional Requirements"
+
+**Issue:** Performance requirements state "the system should be fast and responsive."
+No response time targets, percentile thresholds, or load conditions are specified.
+"Fast" is subjective — it means <100ms to a backend engineer and <3s to a product
+manager evaluating full page loads.
+
+Similarly, availability requirement states "high availability" without specifying
+a target uptime percentage, maximum acceptable downtime window, or recovery time
+objective (RTO).
+
+**Impact:** The architecture step cannot make infrastructure decisions (single
+instance vs. load-balanced, database read replicas, CDN) without quantified
+performance targets. The testing step cannot write performance tests without
+thresholds to assert against. Implementing agents will make arbitrary performance
+trade-offs with no shared baseline.
+
+**Recommendation:** Replace with quantified targets:
+- "API response time: p95 < 200ms, p99 < 500ms under 1000 concurrent users"
+- "Page load time: Largest Contentful Paint < 2.5s on 4G connection"
+- "Availability: 99.9% uptime (8.7 hours maximum downtime per year)"
+- "Recovery: RTO < 15 minutes, RPO < 1 hour"
+
+**Trace:** PRD Section 6 → blocks Architecture Phase → blocks Implementation
+```

package/knowledge/review/review-security.md

@@ -211,3 +211,56 @@ Frontend-only validation is a UX convenience, not a security control. Attackers
 - P1: "File upload endpoint validates file extension (.jpg, .png) but does not validate file content. An attacker could upload a malicious script with a .jpg extension."
 - P1: "Webhook receiver accepts payloads from external services with no signature validation. An attacker could forge webhook calls."
 - P2: "Input validation is specified for API endpoints but not for message queue consumers. A malformed message could cause the consumer to crash."
+
+---
+
+## Common Review Anti-Patterns
+
+### 1. Generic OWASP Checklist Without Project Mapping
+
+The security document lists all 10 OWASP categories with textbook mitigations ("use parameterized queries," "encrypt data at rest") but never connects them to the actual project. No component names, no endpoint references, no architecture-specific analysis. The same document could describe any web application.
+
+**How to spot it:** The OWASP section contains zero references to the project's architecture document, API contracts, or database schema. Mitigations are general advice rather than specific implementation plans tied to named components.
+
+### 2. Auth Designed in Isolation from API Contracts
+
+The security document defines roles, permissions, and access control policies, but the reviewer does not cross-reference these with the API contract's endpoint-level auth requirements. The security document says "admin-only" for user management, but the API contract has no auth annotation on DELETE /users/{id}. This gap means the security design exists on paper but may not be enforced.
+
+**Example finding:**
+
+```markdown
+## Finding: SEC-018
+
+**Priority:** P0
+**Pass:** Auth/AuthZ Boundary Alignment (Pass 2)
+**Document:** docs/security-review.md, Section 3 / docs/api-contracts.md, Section 5.2
+
+**Issue:** Security document defines three roles (admin, editor, viewer) with a permission
+matrix. API contract defines 24 endpoints. Cross-referencing reveals:
+  - 6 endpoints have no auth requirement specified in the API contract
+  - 3 endpoints specify "authenticated" but the security document requires "admin" role
+  - Endpoint PATCH /users/{id}/role has no authorization check — any authenticated user
+    could escalate privileges
+
+**Recommendation:** Add auth/authz annotations to all 24 endpoints in the API contract.
+Reconcile the 3 mismatched endpoints with the security document's permission matrix.
+Add explicit admin-only restriction to the role-change endpoint.
+```
+
+### 3. Secrets Strategy Says "Environment Variables" and Stops
+
+The security document addresses secrets management by stating "secrets are stored in environment variables" with no further detail. This leaves critical questions unanswered: how are environment variables populated in production (plain text config file on the server? Kubernetes secrets? A vault?)? How are secrets rotated? What happens when a secret is compromised? "Environment variables" is a mechanism, not a strategy.
+
+**How to spot it:** The secrets management section is shorter than half a page. It mentions environment variables but not rotation, not emergency response, not CI/CD secret injection, and not local development secrets handling.
+
+### 4. Threat Model Without Trust Boundaries
+
+The security document includes a threat model section that lists generic threats (SQL injection, XSS, CSRF) without mapping them to the system's trust boundaries. No data flow analysis, no identification of where untrusted input enters the system, no assessment of service-to-service trust. The threats listed are a vocabulary exercise, not a risk analysis.
+
+**How to spot it:** The threat model section does not reference the architecture diagram. No trust boundaries are drawn. Threats are listed as a flat list rather than organized by boundary (client-to-API, service-to-service, service-to-database).
+
+### 5. Reviewing Security Document Without Cross-Referencing Other Artifacts
+
+The reviewer checks the security document internally (are all sections present? is the OWASP analysis complete?) but never opens the API contracts, architecture document, or operations runbook. Security findings that span multiple documents — auth gaps between the security doc and API contract, secrets handling gaps between the security doc and operations runbook — are invisible to a single-document review.
+
+**How to spot it:** The review report cites only the security document. No findings reference the API contracts (Pass 2), the architecture (Pass 5 trust boundaries), or the operations runbook (Pass 3 secrets in deployment).

package/knowledge/review/review-system-architecture.md

@@ -294,3 +294,31 @@ Architecture documents are long. Inconsistencies between early and late sections
 - P1: "Section 3 describes the system as having five microservices, but the component diagram shows six. The 'Scheduler' component appears in the diagram but not in the prose."
 - P1: "The architecture uses 'API Gateway' in sections 2-4 and 'Reverse Proxy' in section 6 for what appears to be the same component."
 - P2: "Node.js version is stated as 18 in section 1 and 20 in the deployment section."
+
+### Example Review Finding
+
+```markdown
+### Finding: Orphaned component with no data flow connections
+
+**Pass:** 3 — Data Flow Completeness
+**Priority:** P0
+**Location:** Component diagram (architecture.md, Section 2.1)
+
+**Issue:** Component 'AnalyticsEngine' appears in the component diagram as a
+standalone service but is not referenced in any of the 12 documented data flows.
+It has no documented inputs (what data does it consume?), no documented outputs
+(where do analytics results go?), and no documented trigger (what initiates
+analytics processing?).
+
+**Impact:** The database schema step cannot design analytics storage without
+knowing what data the AnalyticsEngine processes. The implementation tasks step
+cannot scope analytics work without knowing the component's interfaces. The UX
+spec step cannot design analytics dashboards without knowing what data is available.
+
+**Recommendation:** Either (a) add data flows showing how AnalyticsEngine receives
+events from other components, what processing it performs, and where results are
+stored/served, or (b) remove AnalyticsEngine from the diagram if analytics is
+out of scope for v1.
+
+**Trace:** Component diagram → missing data flow coverage
+```

package/knowledge/review/review-testing-strategy.md

@@ -174,3 +174,54 @@ A quality gate that exists in documentation but not in CI is not a gate. If the
 - P0: "Testing strategy requires 80% code coverage but the CI pipeline has no coverage reporting or enforcement. The requirement is unverifiable."
 - P1: "Security scanning is listed as a quality requirement but no specific tool or CI pipeline step implements it."
 - P2: "Quality gates run linting, unit tests, and integration tests, but do not validate database migrations. A broken migration would pass all gates and fail in production."
+
+---
+
+## Common Review Anti-Patterns
+
+### 1. Copy-Pasted Generic Strategy
+
+The testing strategy is a boilerplate document that says "we will have unit tests, integration tests, and E2E tests" without connecting to the actual architecture. No mention of specific components, no mapping of test types to architectural layers, no project-specific invariants.
+
+**How to spot it:** The strategy could be copy-pasted into any other project and still read correctly. No component names, no domain terms, no architecture-specific decisions.
+
+### 2. Testing Strategy Disconnected from Architecture
+
+The strategy defines test types and coverage goals but does not reference the system architecture. Tests are organized by test framework (Jest unit tests, Playwright E2E tests) rather than by architectural component. This makes it impossible to verify coverage — you cannot tell which components are tested and which are not.
+
+**How to spot it:** Search for component names from the architecture document. If none appear in the testing strategy, the two documents are disconnected.
+
+### 3. Mock-Everything Mentality
+
+Every external dependency is mocked, including the database. Unit test coverage is high, but no test ever executes a real query, a real HTTP call, or a real message queue interaction. The test suite provides confidence that the mocking layer works, not that the system works.
+
+**Example finding:**
+
+```markdown
+## Finding: TSR-009
+
+**Priority:** P1
+**Pass:** Integration Boundary Coverage (Pass 5)
+**Document:** docs/testing-strategy.md, Section 4.2
+
+**Issue:** All database tests use an in-memory mock repository. The repository interface
+is tested, but no test ever executes SQL against a real PostgreSQL instance. The following
+risks are untested: query syntax errors, constraint violations, transaction isolation
+behavior, migration correctness.
+
+**Recommendation:** Add integration tests using testcontainers or a CI-managed PostgreSQL
+instance for at least the OrderRepository and UserRepository (the two repositories with
+complex queries).
+```
+
+### 4. No Negative Test Scenarios
+
+The strategy defines tests for the happy path but never specifies what happens when things fail. No test scenarios for invalid input, network timeouts, concurrent modification, or resource exhaustion. The system is verified to work when everything goes right — the most uninteresting case.
+
+**How to spot it:** Scan test scenario descriptions for words like "invalid," "timeout," "failure," "error," "reject," "concurrent," "duplicate." If these are absent, negative scenarios are missing.
+
+### 5. Coverage Percentage as the Only Quality Metric
+
+The strategy defines 80% code coverage as the quality gate but specifies no other quality criteria. High coverage with no assertion quality means tests that execute code paths without verifying behavior — "tests" that call functions and ignore the return value. Coverage measures how much code was run, not whether it was tested correctly.
+
+**How to spot it:** The quality gates section mentions only code coverage. No mention of mutation testing, assertion density, test execution time budgets, or flakiness tracking.

package/knowledge/review/review-user-stories.md

@@ -170,3 +170,57 @@ Stories are the primary input to domain discovery in the domain modeling step. I
 - P1: "US-007 ('As a teacher, I want to manage my classes') — acceptance criteria say 'classes are managed correctly.' No mention of what entities are involved (Class, Enrollment, Student?), what state transitions occur, or what business rules apply. Domain modeling will have to guess."
 - P2: "Cross-story entity naming is inconsistent: US-003 uses 'User,' US-008 uses 'Account,' US-015 uses 'Member.' These may be different bounded context terms or may be accidental inconsistency — clarify before domain modeling."
 - P2: "Stories in the 'Payments' epic mention 'processing a payment' but no acceptance criteria describe the payment lifecycle states (pending → processing → completed/failed). Domain events cannot be discovered from these stories."
+
+---
+
+## Common Review Anti-Patterns
+
+### 1. Reviewing Against a Generic Checklist Instead of the PRD
+
+The reviewer checks whether stories have acceptance criteria and follow INVEST principles, but never opens the PRD to verify coverage. The stories could be missing entire PRD features and this review would not catch it. Reviews must cross-reference the PRD — checking story quality without checking story completeness misses the highest-severity failure mode.
+
+**How to spot it:** The review report contains no references to specific PRD sections. Findings are all about story quality (vague criteria, poor sizing) and none about story coverage (missing features, missing flows).
+
+### 2. Accepting Vague Acceptance Criteria as "Good Enough"
+
+The reviewer sees acceptance criteria like "user can manage their profile" and does not flag it because the intent is clear. But intent is not implementation guidance. Two agents reading "manage their profile" will implement different field sets, different validation rules, and different UX flows. Acceptance criteria must be testable — if you cannot write an automated test directly from the criterion, it is too vague.
+
+**Example finding:**
+
+```markdown
+## Finding: USR-014
+
+**Priority:** P1
+**Pass:** Acceptance Criteria Quality (Pass 2)
+**Document:** docs/user-stories.md, US-008
+
+**Issue:** Acceptance criteria for US-008 ("As a user, I want to manage my profile"):
+  - "Given I am logged in, when I update my profile, then my changes are saved"
+
+This criterion does not specify: which fields are editable, what validation rules apply,
+whether partial updates are supported, what happens on validation failure, or whether
+changes require re-authentication (e.g., email change).
+
+**Recommendation:** Replace with specific Given/When/Then scenarios:
+  - Given I am logged in, when I change my display name to a valid name (1-100 chars), then my display name is updated
+  - Given I am logged in, when I change my email, then a verification email is sent to the new address and the email is not changed until verified
+  - Given I am logged in, when I submit a display name longer than 100 characters, then I see a validation error
+```
+
+### 3. Ignoring Story Dependencies
+
+The reviewer checks each story in isolation but never maps dependencies between stories. Stories that secretly depend on each other are not flagged. This creates false parallelization opportunities downstream — the implementation tasks phase will mark these as parallel, and agents will produce conflicting work.
+
+**How to spot it:** The review report has no findings from Pass 3 (Story Independence). Dependencies are only discovered later during implementation tasks or during actual implementation.
+
+### 4. Persona Name Drift Without Flagging
+
+The PRD defines personas as "Teacher," "Student," and "Admin." Stories reference "Instructor," "Learner," and "Administrator." The reviewer does not flag the terminology mismatch because the mapping is obvious to a human. But downstream, the domain model and implementation tasks may use either set of terms inconsistently, creating confusion.
+
+**How to spot it:** Compare persona names in the PRD with persona names in story "As a..." statements. Any mismatch is a finding, even if the intent is obvious.
+
+### 5. Reviewing Only Happy-Path Stories
+
+The reviewer verifies that the main user flows have stories but does not check for error handling, edge cases, or administrative workflows. Stories exist for "user creates an account" and "user places an order" but not for "user enters invalid payment info," "user tries to order an out-of-stock item," or "admin resolves a disputed transaction." These missing stories become missing tasks and missing implementations.
+
+**How to spot it:** Count the ratio of happy-path stories to error/edge-case stories. If the ratio is heavily skewed (e.g., 20 happy-path stories and 2 error stories), error handling is systematically under-specified.

package/knowledge/review/{review-ux-spec.md → review-ux-specification.md}

@@ -1,5 +1,5 @@
 ---
-name: review-ux-spec
+name: review-ux-specification
 description: Failure modes and review passes specific to UI/UX specification artifacts
 topics: [review, ux, design, accessibility, responsive]
 ---
@@ -206,3 +206,39 @@ When the UX spec designs components that do not match the architecture's compone
 - P1: "The UX spec designs an 'OrderSummaryWidget' that combines order details, customer info, and payment status. The architecture separates these into three independent components (OrderComponent, CustomerComponent, PaymentComponent) with separate data sources."
 - P1: "The UX spec assumes global state for user preferences (accessible from any component), but the architecture specifies component-local state with prop drilling."
 - P2: "The UX spec's 'ProductCard' component bundles product image, price, and add-to-cart button. The architecture models 'ProductDisplay' and 'CartAction' as separate concerns."
+
+### Example Review Finding
+
+```markdown
+### Finding: Dashboard has no empty state or loading state design
+
+**Pass:** 3 — Interaction State Completeness
+**Priority:** P0
+**Location:** UX Spec Section 4.1 "User Dashboard"
+
+**Issue:** The dashboard screen shows charts (order volume, revenue trend) and
+summary metrics (total orders, account balance, recent activity). The spec provides
+only the populated state — what the screen looks like with data.
+
+Missing states:
+- **Empty state:** A new user with zero orders sees empty chart containers with
+  no axes, no labels, and no guidance. The metrics show "$0" and "0 orders" with
+  no context.
+- **Loading state:** When dashboard data is being fetched (3 separate API calls
+  per the API contract), what does the user see? No skeleton, spinner, or
+  progressive loading is specified.
+- **Partial error state:** If the revenue chart API fails but the orders API
+  succeeds, does the entire dashboard show an error, or just the revenue widget?
+
+**Impact:** Implementing agents will either show blank containers (confusing for
+new users), a full-page spinner (poor perceived performance), or nothing at all
+while loading. The first-time user experience — which is critical for activation
+metrics in the PRD — is completely undesigned.
+
+**Recommendation:** Design three additional states:
+1. Empty state with onboarding CTA ("Create your first order to see analytics here")
+2. Skeleton loading state with placeholder shapes matching the populated layout
+3. Per-widget error state with retry button, so partial failures are isolated
+
+**Trace:** UX Spec 4.1 → PRD Success Metric "70% user activation within 7 days"
+```

package/methodology/custom-defaults.yml

@@ -5,32 +5,60 @@ default_depth: 3
 
 # All steps enabled by default at depth 3 — user overrides individual steps
 steps:
+  # Phase 1 — Product Definition (pre)
   create-prd: { enabled: true }
   review-prd: { enabled: true }
   innovate-prd: { enabled: false }
   user-stories: { enabled: true }
   review-user-stories: { enabled: true }
   innovate-user-stories: { enabled: false }
+  # Phase 2 — Project Foundation (foundation)
+  beads: { enabled: true, conditional: "if-needed" }
+  tech-stack: { enabled: true }
+  coding-standards: { enabled: true }
+  tdd: { enabled: true }
+  project-structure: { enabled: true }
+  # Phase 3 — Development Environment (environment)
+  dev-env-setup: { enabled: true }
+  design-system: { enabled: true, conditional: "if-needed" }
+  git-workflow: { enabled: true }
+  automated-pr-review: { enabled: false }
+  ai-memory-setup: { enabled: true }
+  # Phase 4 — Testing Integration (integration)
+  add-e2e-testing: { enabled: true, conditional: "if-needed" }
+  # Phase 5 — Domain Modeling (modeling)
   domain-modeling: { enabled: true }
   review-domain-modeling: { enabled: true }
+  # Phase 6 — Architecture Decisions (decisions)
   adrs: { enabled: true }
   review-adrs: { enabled: true }
+  # Phase 7 — System Architecture (architecture)
   system-architecture: { enabled: true }
   review-architecture: { enabled: true }
+  # Phase 8 — Specifications (specification)
   database-schema: { enabled: true, conditional: "if-needed" }
   review-database: { enabled: true, conditional: "if-needed" }
   api-contracts: { enabled: true, conditional: "if-needed" }
   review-api: { enabled: true, conditional: "if-needed" }
   ux-spec: { enabled: true, conditional: "if-needed" }
   review-ux: { enabled: true, conditional: "if-needed" }
-  testing-strategy: { enabled: true }
+  # Phase 9 — Quality Gates (quality)
   review-testing: { enabled: true }
+  story-tests: { enabled: true }
+  create-evals: { enabled: true }
   operations: { enabled: true }
   review-operations: { enabled: true }
   security: { enabled: true }
   review-security: { enabled: true }
-  implementation-tasks: { enabled: true }
-  review-tasks: { enabled: true }
+  # Phase 10 — Platform Parity (parity)
+  platform-parity-review: { enabled: true, conditional: "if-needed" }
+  # Phase 11 — Consolidation (consolidation)
+  claude-md-optimization: { enabled: true }
+  workflow-audit: { enabled: true }
+  # Phase 12 — Planning (planning)
+  implementation-plan: { enabled: true }
+  implementation-plan-review: { enabled: true }
+  # Phase 13 — Validation (validation)
   cross-phase-consistency: { enabled: true }
   traceability-matrix: { enabled: true }
   decision-completeness: { enabled: true }
@@ -38,6 +66,7 @@ steps:
   implementability-dry-run: { enabled: true }
   dependency-graph-validation: { enabled: true }
   scope-creep-check: { enabled: true }
+  # Phase 14 — Finalization (finalization)
   apply-fixes-and-freeze: { enabled: true }
   developer-onboarding-guide: { enabled: true }
   implementation-playbook: { enabled: true }