@zigrivers/scaffold 2.28.1 → 2.38.0

package/pipeline/planning/implementation-plan.md

@@ -1,11 +1,12 @@
 ---
 name: implementation-plan
 description: Break architecture into implementable tasks with dependencies
+summary: "Breaks your user stories and architecture into concrete tasks — each scoped to ~150 lines of code and 3 files max, with clear acceptance criteria, no ambiguous decisions, and explicit dependencies."
 phase: "planning"
 order: 1210
 dependencies: [tdd, operations, security, review-architecture, create-evals]
 outputs: [docs/implementation-plan.md]
-reads: [create-prd]
+reads: [create-prd, story-tests, database-schema, api-contracts, ux-spec]
 conditional: null
 knowledge-base: [task-decomposition]
 ---
@@ -17,9 +18,9 @@ have clear inputs/outputs, and be small enough for a single agent session.
 The primary mapping is Story → Task(s), with PRD as the traceability root.
 
 ## Inputs
-- docs/system-architecture.md (required) — components to implement
-- docs/domain-models/ (required) — domain logic to implement
-- docs/adrs/ (required) — technology constraints
+- docs/system-architecture.md (optional — not available in MVP) — components to implement
+- docs/domain-models/ (optional — not available in MVP) — domain logic to implement
+- docs/adrs/ (optional — not available in MVP) — technology constraints
 - docs/plan.md (required) — features to trace tasks back to
 - docs/user-stories.md (required) — stories to derive tasks from
 - docs/tdd-standards.md (required) — testing requirements to incorporate into tasks
@@ -28,31 +29,41 @@ The primary mapping is Story → Task(s), with PRD as the traceability root.
 - docs/database-schema.md (optional) — data layer tasks
 - docs/api-contracts.md (optional) — API implementation tasks
 - docs/ux-spec.md (optional) — frontend tasks
+- tests/acceptance/ (optional) — test skeletons to reference in task descriptions
+- docs/story-tests-map.md (optional) — AC-to-test mapping for task coverage verification
 
 ## Expected Outputs
 - docs/implementation-plan.md — task list with dependencies, sizing, and
   assignment recommendations
 
 ## Quality Criteria
-- Every architecture component has implementation tasks
-- Task dependencies form a valid DAG (no cycles)
-- Each task is scoped for a single agent session (not too large, not too small)
-- Tasks include acceptance criteria (how to know it's done)
-- Tasks incorporate testing requirements from the testing strategy
-- Tasks incorporate security controls from the security review where applicable
-- Tasks incorporate operational requirements (monitoring, deployment) where applicable
-- Critical path is identified
-- Parallelization opportunities are marked with wave plan
-- Every user story maps to at least one task
-- High-risk tasks are flagged with risk type and mitigation
-- Wave summary produced with agent allocation recommendation
+- (mvp) Every architecture component has implementation tasks
+- (mvp) Task dependencies form a valid DAG (no cycles)
+- (mvp) Each task produces ~150 lines of net-new application code (excluding tests and generated files)
+- (mvp) Tasks include acceptance criteria (how to know it's done)
+- (mvp) Tasks incorporate testing requirements from the testing strategy
+- (deep) Tasks reference corresponding test skeletons from tests/acceptance/ where applicable
+- (deep) Tasks incorporate security controls from the security review where applicable
+- (deep) Tasks incorporate operational requirements (monitoring, deployment) where applicable
+- (deep) Critical path is identified
+- (deep) Parallelization opportunities are marked with wave plan
+- (mvp) Every user story maps to at least one task
+- (deep) High-risk tasks are flagged with risk type and mitigation
+- (deep) Wave summary produced with agent allocation recommendation
+- (mvp) No task modifies more than 3 application files (test files excluded; exceptions require justification)
+- (mvp) No task contains unresolved design decisions (agents implement, they don't architect)
+- (mvp) Every code-producing task includes co-located test requirements
+- (deep) Critical path identified with estimated total duration
 
 ## Methodology Scaling
 - **deep**: Detailed task breakdown with story-to-task tracing. Dependency graph.
   Sizing estimates. Parallelization plan. Agent context requirements per task.
   Phased delivery milestones.
-- **mvp**: Ordered task list with brief descriptions. Key dependencies noted.
-  Enough to start working sequentially.
+- **mvp**: Ordered task list derived from PRD features and user stories only
+  (architecture, domain models, and ADRs are not available at this depth).
+  Each task has a brief description, rough size estimate, and key dependency.
+  Enough to start working sequentially. Skip architecture decomposition —
+  work directly from user story acceptance criteria.
 - **custom:depth(1-5)**: Depth 1-2: ordered list. Depth 3: add dependencies
   and sizing. Depth 4-5: full breakdown with parallelization.
 
@@ -68,10 +79,32 @@ that are in-progress or completed.
 - **Detect prior artifact**: docs/implementation-plan.md exists
 - **Preserve**: completed and in-progress task statuses, existing task IDs,
   dependency relationships for stable tasks, wave assignments for tasks
-  already started, agent allocation history
+  already started, agent allocation history, architecture decisions,
+  component boundaries
 - **Triggers for update**: architecture changed (new components need tasks),
   user stories added or changed, security review identified new requirements,
   operations runbook added deployment tasks, specification docs changed
 - **Conflict resolution**: if architecture restructured a component that has
   in-progress tasks, flag for user review rather than silently reassigning;
   re-derive critical path only for unstarted tasks
+
+## Task Size Constraints
+
+Before finalizing the implementation plan, scan every task against the five agent
+executability rules from the task-decomposition knowledge base:
+
+1. **Three-File Rule** — Count application files each task modifies (exclude test files).
+   Any task touching 4+ files must be split by layer or concern.
+2. **150-Line Budget** — Estimate net-new application code lines per task. Any task
+   likely to produce 200+ lines must be split by feature slice or entity.
+3. **Single-Concern Rule** — Check each task description for "and" connecting unrelated
+   work. Split if the task spans multiple architectural layers or feature domains.
+4. **Decision-Free Execution** — Verify all design decisions are resolved in the task
+   description. No "choose", "determine", "decide", or "evaluate options" language.
+   Resolve decisions inline before presenting the plan.
+5. **Test Co-location** — Confirm every code-producing task includes its test
+   requirements. No "write tests later" aggregation tasks.
+
+Tasks that fail any rule should be split inline. If a task genuinely can't be split
+further, annotate with `<!-- agent-size-exception: reason -->`. The implementation
+plan review will flag unjustified exceptions.

package/pipeline/pre/create-prd.md

@@ -1,18 +1,22 @@
 ---
 name: create-prd
 description: Create a product requirements document from a project idea
+summary: "Translates your vision (or idea, if no vision exists) into a product requirements document with problem statement, user personas, prioritized feature list, constraints, non-functional requirements, and measurable success criteria."
 phase: "pre"
 order: 110
 dependencies: []
 outputs: [docs/plan.md]
 conditional: null
 knowledge-base: [prd-craft]
+reads: [create-vision]
 ---
 
 ## Purpose
 Transform a project idea into a structured product requirements document that
 defines the problem, target users, features, constraints, and success criteria.
 This is the foundation document that all subsequent phases reference.
+The PRD drives user stories, architecture decisions, and implementation planning
+throughout the entire pipeline.
 
 ## Inputs
 - Project idea (provided by user verbally or in a brief)
@@ -22,12 +26,13 @@ This is the foundation document that all subsequent phases reference.
 - docs/plan.md — Product requirements document
 
 ## Quality Criteria
-- Problem statement is specific and testable (not vague aspirations)
-- Target users are identified with their needs
-- Features are scoped with clear boundaries (what's in, what's out)
-- Success criteria are measurable
-- Constraints (technical, timeline, budget, team) are documented
-- Non-functional requirements are explicit (performance, security, accessibility)
+- (mvp) Problem statement names a specific user group, a specific pain point, and a falsifiable hypothesis about the solution
+- (mvp) Target users are identified with their needs
+- (mvp) Features are scoped with clear boundaries (what's in, what's out)
+- (mvp) Success criteria are measurable
+- (mvp) Each non-functional requirement has a measurable target or threshold (e.g., 'page load < 2s', 'WCAG AA')
+- (mvp) No two sections contain contradictory statements about the same concept
+- (deep) Constraints (technical, timeline, budget, team) are documented
 
 ## Methodology Scaling
 - **deep**: Comprehensive PRD. Competitive analysis, detailed user personas,
@@ -47,8 +52,18 @@ Preserve existing decisions unless explicitly revisiting them.
 ## Update Mode Specifics
 - **Detect prior artifact**: docs/plan.md exists
 - **Preserve**: problem statement, existing feature definitions, success criteria,
-  user personas, and scope boundaries unless user explicitly requests changes
+  user personas, scope boundaries, and enhancement markers (`<!-- enhancement: ... -->`)
+  unless user explicitly requests changes
 - **Triggers for update**: user provides new requirements, scope adjustment
   requested, constraints changed (timeline, budget, team), new user research
 - **Conflict resolution**: new features are appended to the feature list with
   clear versioning; changed constraints are documented with rationale for change
+
+### Understand the Vision
+
+**If `docs/vision.md` exists**: Read it completely. This is your strategic foundation — the vision document has already established the problem space, target audience, value proposition, competitive landscape, and guiding principles. Skip the vision discovery questions below and use the vision document as the North Star for this PRD. Reference it throughout, ensuring every requirement aligns with the stated vision and guiding principles. Focus your discovery questions on translating the vision into concrete product requirements rather than re-exploring strategic direction.
+
+**If `docs/vision.md` does NOT exist**:
+- What problem does this solve and for whom? Push me to be specific about the target user.
+- What does success look like? How will we know this is working?
+- What's the single most important thing this app must do well?

package/pipeline/pre/innovate-prd.md

@@ -1,12 +1,13 @@
 ---
 name: innovate-prd
 description: Discover feature-level innovation opportunities in the PRD
+summary: "Analyzes the PRD for feature-level gaps — competitive blind spots, UX enhancements, AI-native possibilities — and proposes additions for your approval."
 phase: "pre"
 order: 130
 dependencies: [review-prd]
-outputs: [docs/prd-innovation.md, docs/reviews/prd-innovation/review-summary.md, docs/reviews/prd-innovation/codex-review.json, docs/reviews/prd-innovation/gemini-review.json]
+outputs: [docs/prd-innovation.md, docs/plan.md, docs/reviews/prd-innovation/review-summary.md, docs/reviews/prd-innovation/codex-review.json, docs/reviews/prd-innovation/gemini-review.json]
 conditional: "if-needed"
-knowledge-base: [prd-innovation, prd-craft]
+knowledge-base: [prd-innovation, prd-craft, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -32,12 +33,13 @@ creative opportunities and competitive insights.
 - docs/reviews/prd-innovation/gemini-review.json (depth 4+, if available) — raw Gemini suggestions
 
 ## Quality Criteria
-- Enhancements are feature-level, not UX-level polish
-- Each suggestion has a cost estimate (trivial/moderate/significant)
-- Each suggestion has a clear user benefit and impact assessment
-- Approved innovations are documented to the same standard as existing features
-- PRD scope boundaries are respected — no uncontrolled scope creep
+- (mvp) Enhancements are feature-level, not UX-level polish
+- (mvp) Each suggestion has a cost estimate (trivial/moderate/significant)
+- (mvp) Each suggestion has a clear user benefit and impact assessment
+- (mvp) Each approved innovation includes: problem it solves, target users, scope boundaries, and success criteria
+- (mvp) PRD scope boundaries are respected — no uncontrolled scope creep
 - User approval is obtained before modifying the PRD
+- User approval for each accepted innovation documented as a question-response pair with timestamp (e.g., "Q: Accept feature X? A: Yes — 2025-01-15T14:30Z")
 - (depth 4+) Multi-model suggestions deduplicated and synthesized with unique ideas from each model highlighted
 
 ## Methodology Scaling
@@ -47,7 +49,7 @@ creative opportunities and competitive insights.
   innovation dispatched to Codex and Gemini if available, with graceful
   fallback to Claude-only enhanced brainstorming.
 - **mvp**: Not applicable — this step is conditional and skipped in MVP.
-- **custom:depth(1-5)**: Depth 1-2: not typically enabled. Depth 3: quick scan
+- **custom:depth(1-5)**: Depth 1-2: skip (not enough context for meaningful innovation at this depth). Depth 3: quick scan
   for obvious gaps and missing expected features. Depth 4: full innovation
   pass + one external model (if CLI available). Depth 5: full innovation pass
   + multi-model with deduplication and synthesis.

package/pipeline/pre/innovate-user-stories.md

@@ -1,12 +1,13 @@
 ---
 name: innovate-user-stories
 description: Discover UX-level enhancements and innovation opportunities in user stories
+summary: "Identifies UX enhancement opportunities — progressive disclosure, smart defaults, accessibility improvements — and integrates approved changes into existing stories."
 phase: "pre"
 order: 160
 dependencies: [review-user-stories]
 outputs: [docs/user-stories-innovation.md, docs/reviews/user-stories-innovation/review-summary.md, docs/reviews/user-stories-innovation/codex-review.json, docs/reviews/user-stories-innovation/gemini-review.json]
 conditional: "if-needed"
-knowledge-base: [user-stories, user-story-innovation]
+knowledge-base: [user-stories, user-story-innovation, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -33,11 +34,12 @@ enhancement opportunities.
 - docs/reviews/user-stories-innovation/gemini-review.json (depth 4+, if available) — raw Gemini suggestions
 
 ## Quality Criteria
-- Enhancements are UX-level, not new features
-- Each suggestion has a cost estimate (trivial/moderate/significant)
-- Each suggestion has a clear user benefit
-- Approved enhancements are integrated into existing stories (not new stories)
-- PRD scope boundaries are respected — no scope creep
+- (mvp) Enhancements are UX-level, not new features
+- (mvp) Each suggestion has a cost estimate (trivial/moderate/significant)
+- (mvp) Each suggestion has a clear user benefit
+- (mvp) Approved enhancements are integrated into existing stories (not new stories)
+- (mvp) PRD scope boundaries are respected — no scope creep
+- User approval for each accepted innovation documented as a question-response pair with timestamp (e.g., "Q: Accept enhancement X? A: Yes — 2025-01-15T14:30Z")
 - (depth 4+) Multi-model suggestions deduplicated and synthesized with unique ideas from each model highlighted
 
 ## Methodology Scaling
@@ -47,7 +49,7 @@ enhancement opportunities.
   innovation dispatched to Codex and Gemini if available, with graceful
   fallback to Claude-only enhanced brainstorming.
 - **mvp**: Not applicable — this step is conditional and skipped in MVP.
-- **custom:depth(1-5)**: Depth 1-2: not typically enabled. Depth 3: quick
+- **custom:depth(1-5)**: Depth 1-2: skip (not enough context for meaningful innovation at this depth). Depth 3: quick
   scan for obvious improvements. Depth 4: full innovation pass + one external
   model (if CLI available). Depth 5: full innovation pass + multi-model with
   deduplication and synthesis.

package/pipeline/pre/review-prd.md

@@ -1,12 +1,13 @@
 ---
 name: review-prd
 description: Multi-pass review of the PRD for completeness, clarity, and downstream readiness
+summary: "Reviews the PRD across eight passes — problem rigor, persona coverage, feature scoping, success criteria, internal consistency, constraints, non-functional requirements — and fixes blocking issues."
 phase: "pre"
 order: 120
 dependencies: [create-prd]
 outputs: [docs/reviews/pre-review-prd.md, docs/reviews/prd/review-summary.md, docs/reviews/prd/codex-review.json, docs/reviews/prd/gemini-review.json]
 conditional: null
-knowledge-base: [review-methodology, review-prd, prd-craft, gap-analysis]
+knowledge-base: [review-methodology, review-prd, prd-craft, gap-analysis, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -30,11 +31,12 @@ independent review validation.
 - docs/reviews/prd/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
+- (mvp) Passes 1-2 executed with findings documented
 - All review passes executed with findings documented
 - Every finding categorized by severity (P0-P3)
 - Fix plan created for P0 and P1 findings
 - Fixes applied and re-validated
-- Downstream readiness confirmed (User Stories can proceed)
+- (mvp) Downstream readiness confirmed (User Stories can proceed)
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
@@ -54,3 +56,10 @@ If docs/reviews/pre-review-prd.md exists, this is a re-review. Read previous
 findings, check which were addressed, run review passes again on updated PRD.
 If multi-model review artifacts exist under docs/reviews/prd/, preserve prior
 findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-prd.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/pipeline/pre/review-user-stories.md

@@ -1,12 +1,13 @@
 ---
 name: review-user-stories
 description: Multi-pass review of user stories for PRD coverage, quality, and downstream readiness
+summary: "Verifies every PRD feature maps to at least one story, checks that acceptance criteria are specific enough to test, validates story independence, and builds a requirements traceability index at higher depths."
 phase: "pre"
 order: 150
 dependencies: [user-stories]
 outputs: [docs/reviews/pre-review-user-stories.md, docs/reviews/user-stories/requirements-index.md, docs/reviews/user-stories/coverage.json, docs/reviews/user-stories/review-summary.md]
 conditional: null
-knowledge-base: [review-methodology, review-user-stories]
+knowledge-base: [review-methodology, review-user-stories, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -33,14 +34,15 @@ independent coverage validation.
   synthesis with coverage verification
 
 ## Quality Criteria
+- (mvp) Pass 1 (PRD coverage) executed with findings documented
 - All review passes executed with findings documented
 - Every finding categorized by severity (P0-P3)
 - Fix plan created for P0 and P1 findings
 - Fixes applied and re-validated
-- Downstream readiness confirmed (modeling phase can proceed)
+- (mvp) Every story has at least one testable acceptance criterion, and every PRD feature maps to at least one story
 - (depth 4+) Every atomic PRD requirement has a REQ-xxx ID in the requirements index
 - (depth 4+) Coverage matrix maps every REQ to at least one US (100% coverage target)
-- (depth 5) Multi-model findings synthesized with consensus/disagreement analysis
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
 - **deep**: All 6 review passes from the knowledge base. Full findings report
@@ -58,3 +60,10 @@ If docs/reviews/pre-review-user-stories.md exists, this is a re-review. Read
 previous findings, check which were addressed, run review passes again on
 updated stories. If docs/reviews/user-stories/requirements-index.md exists,
 preserve requirement IDs — never renumber REQ-xxx IDs.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/pre-review-user-stories.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, REQ-xxx IDs, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/pipeline/pre/user-stories.md

@@ -1,10 +1,12 @@
 ---
 name: user-stories
 description: Translate PRD features into user stories with acceptance criteria
+summary: "Breaks every PRD feature into user stories organized by epic, each with testable acceptance criteria in Given/When/Then format."
 phase: "pre"
 order: 140
 dependencies: [review-prd]
 outputs: [docs/user-stories.md]
+reads: [innovate-prd]
 conditional: null
 knowledge-base: [user-stories]
 ---
@@ -25,12 +27,13 @@ task decomposition downstream.
   criteria scaled to the configured depth level
 
 ## Quality Criteria
-- Every PRD feature maps to at least one user story
-- Stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
-- Acceptance criteria are testable — unambiguous pass/fail
-- No story too large to implement in 1-3 focused agent sessions
-- Every PRD persona is represented in at least one story
-- Stories describe user behavior, not implementation details
+- (mvp) Every PRD feature maps to at least one user story
+- (deep) Stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
+- (mvp) Acceptance criteria are testable — unambiguous pass/fail
+- (deep) No story has more than 7 acceptance criteria
+- (mvp) Every PRD persona is represented in at least one story
+- (mvp) Stories describe user behavior, not implementation details
+- (mvp) Each story is independent — reordering stories does not break acceptance criteria
 
 ## Methodology Scaling
 - **deep**: Full story template with IDs, persona journey maps, cross-story
@@ -50,7 +53,9 @@ PRESERVE, get approval before modifying. Preserve existing story IDs.
 ## Update Mode Specifics
 - **Detect prior artifact**: docs/user-stories.md exists
 - **Preserve**: existing story IDs, epic groupings, acceptance criteria that
-  haven't been invalidated, story-to-PRD-feature traceability
+  haven't been invalidated, story-to-PRD-feature traceability, enhancement
+  markers (`<!-- enhancement: ... -->`), priority decisions, story ID format
+  (US-xxx)
 - **Triggers for update**: PRD features added or changed, innovation suggestions
   accepted, user personas expanded, review findings require story adjustments
 - **Conflict resolution**: never reuse a retired story ID; if a story's scope

package/pipeline/quality/create-evals.md

@@ -1,11 +1,12 @@
 ---
 name: create-evals
 description: Generate project-specific eval checks from standards documentation
+summary: "Generates automated checks that verify your code matches your documented standards — file placement, naming conventions, feature-to-test coverage, API contract alignment — using your project's own test framework."
 phase: "quality"
 order: 920
 dependencies: [tdd, story-tests]
 outputs: [tests/evals/, docs/eval-standards.md]
-reads: [story-tests]
+reads: [security, dev-env-setup, api-contracts, database-schema, ux-spec]
 conditional: null
 knowledge-base: [eval-craft, testing-strategy]
 ---
@@ -70,6 +71,8 @@ Supporting:
 - (deep) Adherence, security, and error-handling evals include exclusion mechanisms
 - (deep) docs/eval-standards.md explicitly documents what evals do NOT check
 - (deep) Full eval suite runs in under 30 seconds
+- (mvp) `make eval` (or equivalent) runs and all generated evals pass
+- (deep) Eval false-positive assessment: each eval category documents at least one scenario where valid code might incorrectly fail, with exclusion mechanism
 
 ## Methodology Scaling
 - **deep**: All 13 eval categories (conditional on doc existence). Stack-specific
@@ -83,11 +86,12 @@ Supporting:
   - Depth 5: All 13 categories (Security, API, Database, Accessibility, Performance)
 
 ## Mode Detection
-Update mode if tests/evals/ directory exists. In update mode: regenerate
-consistency, structure, cross-doc, and conditional category evals. Preserve
-adherence, security, and error-handling eval exclusions. Regenerate coverage
-evals only if plan.md or user-stories.md changed. Add/remove conditional
-categories based on whether their source doc exists.
+Update mode if tests/evals/ directory or docs/eval-standards.md exists. In
+update mode: regenerate consistency, structure, cross-doc, and conditional
+category evals. Preserve adherence, security, and error-handling eval
+exclusions. Regenerate coverage evals only if plan.md or user-stories.md
+changed. Add/remove conditional categories based on whether their source doc
+exists.
 
 ## Update Mode Specifics
 - **Detect prior artifact**: tests/evals/ directory exists with eval test files

package/pipeline/quality/operations.md

@@ -1,10 +1,12 @@
 ---
 name: operations
 description: Define deployment pipeline, deployment strategy, monitoring, alerting, and incident response
+summary: "Designs your deployment pipeline (build, test, deploy, verify, rollback), defines monitoring metrics with alert thresholds, and writes incident response procedures with rollback instructions."
 phase: "quality"
 order: 930
 dependencies: [review-testing]
 outputs: [docs/operations-runbook.md]
+reads: [system-architecture, adrs, dev-env-setup, git-workflow]
 conditional: null
 knowledge-base: [operations-runbook]
 ---
@@ -26,19 +28,21 @@ development setup rather than redefining it.
 - docs/operations-runbook.md — production operations and deployment runbook
 
 ## Quality Criteria
-- Deployment pipeline extends existing CI (build, deploy, post-deploy stages)
-- Deployment pipeline has explicit stages (build → test → deploy → verify → rollback-ready)
-- Does not redefine base CI stages (lint, test) from git-workflow
-- Deployment strategy chosen with rollback procedure
-- Rollback procedure tested with specific trigger conditions (e.g., error rate > X%, health check failure)
-- Runbook structured by operational scenario (deployment, rollback, incident, scaling)
-- Monitoring covers key metrics (latency, error rate, saturation)
-- Each monitoring metric has an explicit threshold with rationale
-- Health check endpoints defined with expected response codes and latency bounds
-- Log aggregation strategy specifies retention period and searchable fields
-- Alerting thresholds are justified, not arbitrary
+- (mvp) Deployment pipeline extends existing CI (build, deploy, post-deploy stages)
+- (mvp) Deployment pipeline has explicit stages (build → test → deploy → verify → rollback-ready)
+- (mvp) Does not redefine base CI stages (lint, test) from git-workflow
+- (mvp) Deployment strategy chosen with rollback procedure
+- (deep) Rollback procedure tested with specific trigger conditions (e.g., error rate > X%, health check failure)
+- (deep) Runbook structured by operational scenario (deployment, rollback, incident, scaling)
+- (mvp) Monitoring covers key metrics (latency, error rate, saturation)
+- (deep) Each monitoring metric has an explicit threshold with rationale
+- (deep) Health check endpoints defined with expected response codes and latency bounds
+- (deep) Log aggregation strategy specifies retention period and searchable fields
+- (deep) Each alert threshold documents: the metric, threshold value, business impact if crossed, and mitigation action
 - References docs/dev-setup.md for local dev — does not redefine it
-- Incident response process defined
+- (deep) Incident response process defined
+- (deep) Recovery Time Objective (RTO) and Recovery Point Objective (RPO) documented for each critical service
+- (deep) Secret rotation procedure documented and tested
 
 ## Methodology Scaling
 - **deep**: Full runbook. Deployment topology diagrams. Monitoring dashboard

package/pipeline/quality/review-operations.md

@@ -1,12 +1,13 @@
 ---
 name: review-operations
 description: Review operations runbook for completeness and safety
+summary: "Verifies the full deployment lifecycle is documented, monitoring covers latency/errors/saturation, alert thresholds have rationale, and common failure scenarios have runbook entries."
 phase: "quality"
 order: 940
 dependencies: [operations]
 outputs: [docs/reviews/review-operations.md, docs/reviews/operations/review-summary.md, docs/reviews/operations/codex-review.json, docs/reviews/operations/gemini-review.json]
 conditional: null
-knowledge-base: [review-methodology, review-operations]
+knowledge-base: [review-methodology, review-operations, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -29,21 +30,29 @@ independent review validation.
 - docs/reviews/operations/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Deployment lifecycle fully documented (deploy, verify, rollback)
-- Monitoring covers all critical metrics
-- Alert thresholds have rationale
-- Common failure scenarios have runbook entries
-- Dev environment parity assessed
+- (mvp) Deployment lifecycle fully documented (deploy, verify, rollback)
+- (mvp) Monitoring verified against minimum set: latency, error rate, and saturation
+- (deep) Alert thresholds have rationale
+- (deep) Common failure scenarios have runbook entries
+- (deep) Dev/staging/production environment differences documented in operations runbook
+- Every finding categorized P0-P3 with specific runbook section, metric, and issue
+- Fix plan documented for all P0/P1 findings; fixes applied to operations-runbook.md and re-validated
+- Downstream readiness confirmed — no unresolved P0 or P1 findings remain before security step proceeds
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
 - **deep**: Full multi-pass review. Multi-model review dispatched to Codex and
   Gemini if available, with graceful fallback to Claude-only enhanced review.
-  **mvp**: Deployment coverage only.
-- **custom:depth(1-5)**: Depth 1-3: scale passes with depth. Depth 4: full
-  review + one external model (if CLI available). Depth 5: full review +
-  multi-model with reconciliation.
+- **mvp**: Deployment coverage only.
+- **custom:depth(1-5)**: Depth 1: monitoring and logging pass only. Depth 2: add deployment and rollback pass. Depth 3: add incident response and scaling passes. Depth 4: add external model review. Depth 5: multi-model review with reconciliation.
 
 ## Mode Detection
 Re-review mode if previous review exists. If multi-model review artifacts exist
 under docs/reviews/operations/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-operations.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/pipeline/quality/review-security.md

@@ -1,12 +1,14 @@
 ---
 name: review-security
 description: Review security review for coverage and correctness
+summary: "Verifies OWASP coverage is complete, auth boundaries match API contracts, every secret is accounted for, and the threat model covers all trust boundaries. Highest priority for multi-model review."
 phase: "quality"
 order: 960
 dependencies: [security]
 outputs: [docs/reviews/review-security.md, docs/reviews/security/review-summary.md, docs/reviews/security/codex-review.json, docs/reviews/security/gemini-review.json]
 conditional: null
-knowledge-base: [review-methodology, review-security]
+reads: [api-contracts]
+knowledge-base: [review-methodology, review-security, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -31,22 +33,30 @@ independent review validation.
 - docs/reviews/security/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- OWASP coverage verified for this project
-- Auth boundaries match API contract auth requirements
-- Secrets management is complete (no gaps)
-- Dependency audit scope covers all dependencies
-- Threat model covers all trust boundaries
-- Data classification is complete
+- (mvp) OWASP coverage verified for this project
+- (deep) Auth boundaries match API contract auth requirements
+- (deep) Secrets management covers: all environment variables, API keys, database credentials, and third-party tokens
+- (deep) Dependency audit scope covers all dependencies
+- (deep) Threat model covers all trust boundaries
+- (deep) Data classification covers every entity in the domain model
+- Every finding categorized P0-P3 with specific control, boundary, and issue
+- Fix plan documented for all P0/P1 findings; fixes applied to security-review.md and re-validated
+- Downstream readiness confirmed — no unresolved P0 or P1 findings remain before planning phase proceeds
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
 - **deep**: Full multi-pass review. Multi-model review dispatched to Codex and
   Gemini if available, with graceful fallback to Claude-only enhanced review.
-  **mvp**: OWASP coverage check only.
-- **custom:depth(1-5)**: Depth 1-3: scale passes with depth. Depth 4: full
-  review + one external model (if CLI available). Depth 5: full review +
-  multi-model with reconciliation.
+- **mvp**: OWASP coverage check only.
+- **custom:depth(1-5)**: Depth 1: OWASP top 10 and secrets management pass only. Depth 2: add auth boundary and input validation passes. Depth 3: add dependency audit and data protection passes. Depth 4: add external model security review. Depth 5: multi-model security review with reconciliation.
 
 ## Mode Detection
 Re-review mode if previous review exists. If multi-model review artifacts exist
 under docs/reviews/security/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-security.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate