@zigrivers/scaffold 2.1.2 → 2.38.0

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]
 ---
@@ -10,6 +10,19 @@ API contracts define the system's external and internal interfaces. They must co
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Operation Coverage**: Every domain operation crossing a component boundary has a corresponding API endpoint; no missing CRUD or query operations.
+- **Pass 2 — Error Contract Completeness**: Every endpoint has explicit error responses with status codes, body structure, and triggering conditions.
+- **Pass 3 — Auth/AuthZ Coverage**: Every endpoint specifies authentication and authorization requirements; no ambiguous access control.
+- **Pass 4 — Versioning Consistency**: API versioning strategy is consistent across all endpoints and aligns with the ADR.
+- **Pass 5 — Payload Shape vs Domain Entities**: Request/response payloads align with domain model entities in naming, types, and structure.
+- **Pass 6 — Idempotency**: Mutating operations document idempotency behavior; operations with side effects specify the mechanism.
+- **Pass 7 — Pagination/Filtering**: List endpoints have pagination, filter, and sort parameters documented with response metadata.
+- **Pass 8 — Downstream Readiness**: API provides everything needed for UX spec (screen data, error states) and implementation tasks (complexity, dependencies).
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Operation Coverage
@@ -231,3 +244,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]
 ---
@@ -10,6 +10,19 @@ The database schema translates domain entities and their relationships into pers
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Entity Coverage**: Every domain entity requiring persistence maps to a table; no domain concept is missing from the schema.
+- **Pass 2 — Relationship Fidelity**: Schema relationships accurately reflect domain model cardinality and direction; no missing or fabricated foreign keys.
+- **Pass 3 — Normalization Justification**: Normalization level of each table is justified; deliberate denormalization has documented rationale tied to access patterns.
+- **Pass 4 — Index Coverage**: Indexes cover known query patterns from architecture data flows; no critical query requires a full table scan.
+- **Pass 5 — Constraint Enforcement**: Database constraints (NOT NULL, UNIQUE, CHECK, FK) enforce domain invariants where possible.
+- **Pass 6 — Migration Safety**: Migration plan handles rollbacks and data preservation; destructive operations identified; data migrations separated from schema migrations.
+- **Pass 7 — Cross-Schema Consistency**: Multi-database naming conventions, shared identifiers, and cross-database references are consistent.
+- **Pass 8 — Downstream Readiness**: Schema supports efficient CRUD, list/search queries, relationship traversal, and aggregates needed by API contracts.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Entity Coverage
@@ -227,3 +240,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

@@ -6,10 +6,14 @@ topics: [review, domain-modeling, ddd, bounded-contexts]
 
 # Review: Domain Modeling
 
-Domain models are the foundation of the entire pipeline. Every subsequent phase builds on them. A gap or error here compounds through ADRs, architecture, database schema, API contracts, and implementation tasks. This review uses 10 passes targeting the specific ways domain models fail.
+## Summary
+
+Domain models are the foundation of the entire pipeline. Every subsequent phase builds on them. A gap or error here compounds through ADRs, architecture, database schema, API contracts, and implementation tasks. This review uses 10 passes targeting the specific ways domain models fail: (1) PRD coverage audit, (2) bounded context integrity, (3) entity vs value object classification, (4) aggregate boundary validation, (5) domain event completeness, (6) invariant specification, (7) ubiquitous language consistency, (8) cross-domain relationship clarity, (9) downstream readiness, and (10) internal consistency.
 
 Follows the review process defined in `review-methodology.md`.
 
+## Deep Guidance
+
 ---
 
 ## Pass 1: PRD Coverage Audit
@@ -286,3 +290,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

@@ -6,10 +6,23 @@ topics: [review, tasks, planning, decomposition, agents]
 
 # Review: Implementation Tasks
 
-The implementation tasks document translates the architecture into discrete, actionable work items that AI agents can execute. Each task must be self-contained enough for a single agent session, correctly ordered by dependency, and clear enough to implement without asking questions. This review uses 7 passes targeting the specific ways implementation tasks fail.
+The implementation tasks document translates the architecture into discrete, actionable work items that AI agents can execute. Each task must be self-contained enough for a single agent session, correctly ordered by dependency, and clear enough to implement without asking questions. This review uses 8 passes targeting the specific ways implementation tasks fail.
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Architecture Coverage**: Every architectural component, module, and integration point has corresponding tasks; cross-cutting concerns and infrastructure included.
+- **Pass 2 — Missing Dependencies**: Task dependencies are complete and correct; no circular dependencies; no implicit prerequisites left undeclared.
+- **Pass 3 — Task Sizing**: No task too large for a single agent session (30-60 min) or too small to be meaningful; clear scope boundaries.
+- **Pass 4 — Acceptance Criteria**: Every task has clear, testable criteria covering happy path and at least one error/edge case.
+- **Pass 5 — Critical Path Accuracy**: The identified critical path is actually the longest dependency chain; near-critical paths identified.
+- **Pass 6 — Parallelization Validity**: Tasks marked as parallel are truly independent; no shared state, files, or undeclared dependencies.
+- **Pass 7 — Agent Context**: Each task specifies which documents/sections the implementing agent should read; context is sufficient and minimal.
+- **Pass 8 — Agent Executability**: Every task complies with the 5 agent sizing rules (three-file, 150-line, single-concern, decision-free, test co-location); exceptions are justified.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Architecture Coverage
@@ -200,3 +213,97 @@ 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."
+
+---
+
+## Pass 8: Agent Executability
+
+### What to Check
+
+Every task complies with the five agent executability rules. Tasks exceeding limits without justification must be split.
+
+- **Three-File Rule**: Count application files each task modifies (test files excluded). Flag any task touching 4+ files. Check for `<!-- agent-size-exception -->` annotations on flagged tasks.
+- **150-Line Budget**: Estimate net-new lines per task based on the task description scope. Flag tasks likely to produce 200+ lines. Signals: "implement X with Y and Z", multiple acceptance criteria spanning different modules, multi-layer work.
+- **Single-Concern Rule**: Check each task description for "and" connecting unrelated work. Flag tasks spanning multiple architectural layers or feature domains.
+- **Decision-Free Execution**: Scan for unresolved design decisions. Red flags: "choose", "determine", "decide", "evaluate options", "select the best approach", "pick the right", "figure out". Every design choice must be resolved in the task description.
+- **Test Co-location**: Verify every task that produces application code also includes test requirements. Flag any "write tests for tasks X-Y" aggregation pattern. Flag tasks with no test mention.
+
+### Why This Matters
+
+Large tasks are the #1 cause of AI agent failure during implementation. When a task requires reading 5+ files, holding multiple abstractions in context, and writing 300+ lines — agents lose coherence, make inconsistent changes, or run out of context window. Tasks with unresolved design decisions cause agents to make architectural choices they shouldn't, producing inconsistent implementations across tasks. Deferred testing produces untestable code and violates TDD.
+
+### How to Check
+
+1. For each task, count the application files it modifies (exclude test files). Flag 4+ files.
+2. Estimate net-new application code lines from the task scope. Flag 200+ estimated lines.
+3. Read the task description. Does it contain "and" connecting distinct concerns? Flag it.
+4. Scan for decision language: "choose", "determine", "decide", "evaluate", "select", "figure out". Flag any unresolved decisions.
+5. Check test requirements. Does every code-producing task specify what to test? Flag tasks with no test mention or deferred testing.
+6. For flagged tasks, check for `<!-- agent-size-exception: reason -->`. Accept justified exceptions; flag unjustified ones.
+7. For each P0/P1 finding, provide a specific split recommendation: name the sub-tasks, list files each owns, specify dependencies between them.
+
+### Severity
+
+- P0: Task exceeds 6+ files or 300+ estimated lines — must split immediately, no exceptions
+- P1: Task violates three-file rule without justification — must split or add exception annotation
+- P1: Task violates 150-line budget without justification — must split or justify
+- P1: Task contains unresolved design decisions — must resolve in task description
+- P2: Task has "and" connecting concerns but stays within limits — recommend split
+- P2: Test requirements vague ("add appropriate tests") or deferred — strengthen with specifics
+- P3: Task near limits (3 files, ~150 lines) — note as borderline, no action required
+
+### What a Finding Looks Like
+
+- P1: "Task BD-15 'Implement order management API' modifies 5 files (routes, controller, service, validator, model). Violates three-file rule. Split into: BD-15a 'Create order model and migration' (1 file + migration), BD-15b 'Implement order service with validation' (2 files), BD-15c 'Add order routes and controller' (2 files, depends on BD-15a, BD-15b)."
+- P1: "Task BD-22 'Build settings page' says 'determine whether to use tabs or accordion for organizing preferences.' This is an unresolved design decision. The task description must specify the layout pattern."
+- P2: "Task BD-08 'Set up error handling AND configure logging' connects two concerns with 'and'. Recommend splitting into error handling task and logging task."
+
+---
+
+## 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-methodology.md

@@ -8,6 +8,17 @@ topics: [review, methodology, quality-assurance, multi-pass]
 
 This document defines the shared process for reviewing pipeline artifacts. It covers HOW to review, not WHAT to check — each artifact type has its own review knowledge base document with domain-specific passes and failure modes. Every review phase (1a through 10a) follows this process.
 
+## Summary
+
+- **Multi-pass review**: Each pass has a single focus (coverage, consistency, structure, downstream readiness). Passes are ordered broadest-to-most-specific.
+- **Finding severity**: P0 blocks next phase (must fix), P1 is a significant gap (should fix), P2 is an improvement opportunity (fix if time permits), P3 is nice-to-have (skip).
+- **Fix planning**: Group findings by root cause, same section, and same severity. Fix all P0s first, then P1s. Never fix ad hoc.
+- **Re-validation**: After applying fixes, re-run the specific passes that produced the findings. Stop when no new P0/P1 findings appear.
+- **Downstream readiness gate**: Final check verifies the next phase can proceed with these artifacts. Outcomes: pass, conditional pass, or fail.
+- **Review report**: Structured output with executive summary, findings by pass, fix plan, fix log, re-validation results, and downstream readiness assessment.
+
+## Deep Guidance
+
 ## Multi-Pass Review Structure
 
 ### Why Multiple Passes

package/knowledge/review/review-operations.md

@@ -10,6 +10,18 @@ The operations runbook defines how the system is deployed, monitored, and mainta
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Deployment Strategy Completeness**: Full deploy lifecycle documented from merged PR to running production, including build, test, stage, deploy, verify, and rollback stages.
+- **Pass 2 — Rollback Procedures**: Every deployment type has a corresponding rollback procedure; database rollbacks addressed separately from code rollbacks.
+- **Pass 3 — Monitoring Coverage**: Infrastructure, application, and business metrics identified with dashboards defined for all critical system components.
+- **Pass 4 — Alerting Thresholds**: Alerts have justified thresholds based on baselines, severity levels map to response expectations, and alert fatigue is considered.
+- **Pass 5 — Runbook Scenarios**: Common failure scenarios have step-by-step runbook entries covering symptoms, diagnosis, resolution, verification, and escalation.
+- **Pass 6 — Dev Environment Parity**: Local development environment reasonably matches production behavior; documented deviations with implications.
+- **Pass 7 — DR/Backup Coverage**: Disaster recovery approach documented with RTO/RPO targets; backup strategy covers all persistent data stores.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Deployment Strategy Completeness
@@ -210,3 +222,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

@@ -10,6 +10,19 @@ The PRD is the foundation of the entire pipeline. Every subsequent phase builds
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — Problem Statement Rigor**: Verify the problem is specific, testable, grounded in evidence, and names a specific user group without prescribing solutions.
+- **Pass 2 — Persona & Stakeholder Coverage**: Ensure personas are goal-driven with constraints and context; 2-4 meaningful personas covering all stakeholder groups.
+- **Pass 3 — Feature Scoping Completeness**: Confirm in-scope, out-of-scope, and deferred lists exist; features are specific enough to estimate with prioritization applied.
+- **Pass 4 — Success Criteria Measurability**: Every criterion needs a target value, measurement method, and tie-back to the problem statement.
+- **Pass 5 — NFR Quantification**: All NFR categories addressed with quantified targets and conditions, not adjectives.
+- **Pass 6 — Constraint & Dependency Documentation**: Technical, timeline, budget, team, and regulatory constraints present with traceable downstream impact.
+- **Pass 7 — Error & Edge Case Coverage**: Sad paths for every feature with user input or external dependencies; failure modes for third-party integrations.
+- **Pass 8 — Downstream Readiness for User Stories**: Features specific enough to map to stories, personas specific enough to be actors, business rules explicit enough for acceptance criteria.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: Problem Statement Rigor
@@ -233,3 +246,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

@@ -10,6 +10,18 @@ The security review document assesses the system's security posture across authe
 
 Follows the review process defined in `review-methodology.md`.
 
+## Summary
+
+- **Pass 1 — OWASP Coverage**: Every OWASP Top 10 category addressed with project-specific analysis, not generic checklist advice.
+- **Pass 2 — Auth/AuthZ Boundary Alignment**: Security boundaries align with API contract auth requirements; no access control gaps between security review and API enforcement.
+- **Pass 3 — Secrets Management**: No secrets in code or version control; rotation strategy exists; vault/secrets manager integration specified for all secret categories.
+- **Pass 4 — Dependency Audit Coverage**: Vulnerability scanning integrated into CI covering direct and transitive dependencies; response policy for discovered vulnerabilities.
+- **Pass 5 — Threat Model Scenarios**: Structured threat model (STRIDE/PASTA) covering all trust boundaries with specific, project-relevant threat scenarios and mapped mitigations.
+- **Pass 6 — Data Classification**: Data categorized by sensitivity level with handling requirements per category; regulatory compliance addressed.
+- **Pass 7 — Input Validation**: Validation at all system boundaries (not just frontend) covering type, format, range, and business rules.
+
+## Deep Guidance
+
 ---
 
 ## Pass 1: OWASP Coverage
@@ -211,3 +223,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

@@ -6,12 +6,14 @@ topics: [review, architecture, components, data-flow, modules]
 
 # Review: System Architecture
 
-The system architecture document translates domain models and ADR decisions into a concrete component structure, data flows, and module organization. It is the primary reference for all subsequent phases — database schema, API contracts, UX spec, and implementation tasks all derive from it. Errors here propagate everywhere.
+## Summary
 
-This review uses 10 passes targeting the specific ways architecture documents fail.
+The system architecture document translates domain models and ADR decisions into a concrete component structure, data flows, and module organization. It is the primary reference for all subsequent phases — database schema, API contracts, UX spec, and implementation tasks all derive from it. Errors here propagate everywhere. This review uses 10 passes targeting the specific ways architecture documents fail: (1) domain model coverage, (2) ADR constraint compliance, (3) data flow completeness, (4) module structure integrity, (5) state consistency, (6) diagram/prose consistency, (7) extension point integrity, (8) invariant verification, (9) downstream readiness, and (10) internal consistency.
 
 Follows the review process defined in `review-methodology.md`.
 
+## Deep Guidance
+
 ---
 
 ## Pass 1: Domain Model Coverage
@@ -294,3 +296,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
+```