@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/core/review-step-template.md

@@ -0,0 +1,247 @@
+---
+name: review-step-template
+description: Shared template pattern for review pipeline steps including multi-model dispatch, finding severity, and resolution workflow
+topics: [review, template, multi-model, quality-gates, methodology]
+---
+
+# Review Step Template
+
+## Summary
+
+This entry documents the common structure shared by all 15+ review pipeline steps. Individual review steps customize this structure with artifact-specific failure modes and review passes, but the scaffolding is consistent across all reviews.
+
+**Purpose pattern**: Every review step targets domain-specific failure modes for a given artifact — not generic quality checks. Each pass has a specific focus, concrete checking instructions, and example findings.
+
+**Standard inputs**: Primary artifact being reviewed, upstream artifacts for cross-reference validation, `review-methodology` knowledge + artifact-specific review knowledge entry.
+
+**Standard outputs**: Review document (`docs/reviews/review-{artifact}.md`), updated primary artifact with P0/P1 fixes applied, and at depth 4+: multi-model artifacts (`codex-review.json`, `gemini-review.json`, `review-summary.md`) under `docs/reviews/{artifact}/`.
+
+**Finding severity**: P0 (blocking — must fix), P1 (significant — fix before implementation), P2 (improvement — fix if time permits), P3 (nitpick — log for later).
+
+**Methodology scaling**: Depth 1-2 runs top passes only (P0 focus). Depth 3 runs all passes. Depth 4-5 adds multi-model dispatch to Codex/Gemini with finding synthesis.
+
+**Mode detection**: First review runs all passes from scratch. Re-review preserves prior findings, marks resolved ones, and reports NEW/EXISTING/RESOLVED status.
+
+**Frontmatter conventions**: Reviews are order = creation step + 10, always include `review-methodology` in knowledge-base, and are never conditional.
+
+## Deep Guidance
+
+### Purpose Pattern
+
+Every review step follows the pattern:
+
+> Review **[artifact]** targeting **[domain]**-specific failure modes.
+
+The review does not check generic quality ("is this document complete?"). Instead, it runs artifact-specific passes that target the known ways that artifact type fails. Each pass has a specific focus, concrete checking instructions, and example findings.
+
+### Standard Inputs
+
+Every review step reads:
+- **Primary artifact**: The document being reviewed (e.g., `docs/domain-models.md`, `docs/api-contracts.md`)
+- **Upstream artifacts**: Documents the primary artifact was built from (e.g., PRD, domain models, ADRs) -- used for cross-reference validation
+- **Knowledge base entries**: `review-methodology` (shared process) + artifact-specific review knowledge (e.g., `review-api-design`, `review-database-design`)
+
+### Standard Outputs
+
+Every review step produces:
+- **Review document**: `docs/reviews/review-{artifact}.md` -- findings organized by pass, with severity and trace information
+- **Updated artifact**: The primary artifact with fixes applied for P0/P1 findings
+- **Depth 4+ multi-model artifacts** (when methodology depth >= 4):
+  - `docs/reviews/{artifact}/codex-review.json` -- Codex independent review findings
+  - `docs/reviews/{artifact}/gemini-review.json` -- Gemini independent review findings
+  - `docs/reviews/{artifact}/review-summary.md` -- Synthesized findings from all models
+
+### Finding Severity Levels
+
+All review steps use the same four-level severity scale:
+
+| Level | Name | Meaning | Action |
+|-------|------|---------|--------|
+| P0 | Blocking | Cannot proceed to downstream steps without fixing | Must fix before moving on |
+| P1 | Significant | Downstream steps can proceed but will encounter problems | Fix before implementation |
+| P2 | Improvement | Artifact works but could be better | Fix if time permits |
+| P3 | Nitpick | Style or preference | Log for future cleanup |
+
+### Finding Format
+
+Each finding includes:
+- **Pass**: Which review pass discovered it (e.g., "Pass 3 -- Auth/AuthZ Coverage")
+- **Priority**: P0-P3
+- **Location**: Specific section, line, or element in the artifact
+- **Issue**: What is wrong, with concrete details
+- **Impact**: What goes wrong downstream if this is not fixed
+- **Recommendation**: Specific fix, not just "fix this"
+- **Trace**: Link back to upstream artifact that establishes the requirement (e.g., "PRD Section 3.2 -> Architecture DF-005")
+
+### Example Finding
+
+```markdown
+### Finding F-003 (P1)
+- **Pass**: Pass 2 — Entity Coverage
+- **Location**: docs/domain-models/order.md, Section "Order Aggregate"
+- **Issue**: Order aggregate does not include a `cancellationReason` field, but PRD
+  Section 4.1 requires cancellation reason tracking for analytics.
+- **Impact**: Implementation will lack cancellation reason; analytics pipeline will
+  receive null values, causing dashboard gaps.
+- **Recommendation**: Add `cancellationReason: CancellationReason` value object to
+  Order aggregate with enum values: USER_REQUEST, PAYMENT_FAILED, OUT_OF_STOCK,
+  ADMIN_ACTION.
+- **Trace**: PRD §4.1 → User Story US-014 → Domain Model: Order Aggregate
+```
+
+### Review Document Structure
+
+Every review output document follows a consistent structure:
+
+```markdown
+  # Review: [Artifact Name]
+
+  **Date**: YYYY-MM-DD
+  **Methodology**: deep | mvp | custom:depth(N)
+  **Status**: INITIAL | RE-REVIEW
+  **Models**: Claude | Claude + Codex | Claude + Codex + Gemini
+
+  ## Findings Summary
+  - Total findings: N (P0: X, P1: Y, P2: Z, P3: W)
+  - Passes run: N of M
+  - Artifacts checked: [list]
+
+  ## Findings by Pass
+
+  ### Pass 1 — [Pass Name]
+  [Findings listed by severity, highest first]
+
+  ### Pass 2 — [Pass Name]
+  ...
+
+  ## Resolution Log
+  | Finding | Severity | Status | Resolution |
+  |---------|----------|--------|------------|
+  | F-001   | P0       | RESOLVED | Fixed in commit abc123 |
+  | F-002   | P1       | EXISTING | Deferred — tracked in ADR-015 |
+
+  ## Multi-Model Synthesis (depth 4+)
+  ### Convergent Findings
+  [Issues found by 2+ models — high confidence]
+
+  ### Divergent Findings
+  [Issues found by only one model — requires manual triage]
+```
+
+### Methodology Scaling Pattern
+
+Review steps scale their thoroughness based on the methodology depth setting:
+
+### Depth 1-2 (MVP/Minimal)
+- Run only the highest-impact passes (typically passes 1-3)
+- Single-model review only
+- Focus on P0 findings; skip P2/P3
+- Abbreviated finding descriptions
+
+### Depth 3 (Standard)
+- Run all review passes
+- Single-model review
+- Report all severity levels
+- Full finding descriptions with trace information
+
+### Depth 4-5 (Comprehensive)
+- Run all review passes
+- Multi-model dispatch: send the artifact to Codex and Gemini for independent analysis
+- Synthesize findings from all models, flagging convergent findings (multiple models found the same issue) as higher confidence
+- Cross-artifact consistency checks against all upstream documents
+- Full finding descriptions with detailed trace and impact analysis
+
+### Depth Scaling Example
+
+At depth 2 (MVP), a domain model review might produce:
+
+```markdown
+  # Review: Domain Models (MVP)
+  ## Findings Summary
+  - Total findings: 3 (P0: 1, P1: 2)
+  - Passes run: 3 of 10
+  ## Findings
+  ### F-001 (P0) — Missing aggregate root for Payment bounded context
+  ### F-002 (P1) — Order entity lacks status field referenced in user stories
+  ### F-003 (P1) — No domain event defined for order completion
+```
+
+At depth 5 (comprehensive), the same review would run all 10 passes, dispatch to
+Codex and Gemini, and produce a full synthesis with 15-30 findings across all
+severity levels.
+
+### Mode Detection Pattern
+
+Every review step checks whether this is a first review or a re-review:
+
+**First review**: No prior review document exists. Run all passes from scratch.
+
+**Re-review**: A prior review document exists (`docs/reviews/review-{artifact}.md`). The step:
+1. Reads the prior review findings
+2. Checks which findings were addressed (fixed in the artifact)
+3. Marks resolved findings as "RESOLVED" rather than removing them
+4. Runs all passes again looking for new issues or regressions
+5. Reports findings as "NEW", "EXISTING" (still unfixed), or "RESOLVED"
+
+This preserves review history and makes progress visible.
+
+### Resolution Workflow
+
+The standard workflow from review to resolution:
+
+1. **Review**: Run the review step, producing findings
+2. **Triage**: Categorize findings by severity; confirm P0s are genuine blockers
+3. **Fix**: Update the primary artifact to address P0 and P1 findings
+4. **Re-review**: Run the review step again in re-review mode
+5. **Verify**: Confirm all P0 findings are resolved; P1 findings are resolved or have documented justification for deferral
+6. **Proceed**: Move to the next pipeline phase
+
+For depth 4+ reviews, the multi-model dispatch happens in both the initial review and the re-review, ensuring fixes do not introduce new issues visible to other models.
+
+### Frontmatter Pattern
+
+Review steps follow a consistent frontmatter structure:
+
+```yaml
+---
+name: review-{artifact}
+description: "Review {artifact} for completeness, consistency, and downstream readiness"
+phase: "{phase-slug}"
+order: {N}20  # Reviews are always 10 after their creation step
+dependencies: [{creation-step}]
+outputs: [docs/reviews/review-{artifact}.md, docs/reviews/{artifact}/review-summary.md, docs/reviews/{artifact}/codex-review.json, docs/reviews/{artifact}/gemini-review.json]
+conditional: null
+knowledge-base: [review-methodology, review-{artifact-domain}]
+---
+```
+
+Key conventions:
+- Review steps always have order = creation step order + 10
+- Primary output uses `review-` prefix; multi-model directory uses bare artifact name
+- Knowledge base always includes `review-methodology` plus a domain-specific entry
+- Reviews are never conditional — if the creation step ran, the review runs
+
+### Common Anti-Patterns
+
+### Reviewing Without Upstream Context
+Running a review without loading the upstream artifacts that define requirements.
+The review cannot verify traceability if it does not have the PRD, domain models,
+or ADRs that establish what the artifact should contain.
+
+### Severity Inflation
+Marking everything as P0 to force immediate action. This undermines the severity
+system and causes triage fatigue. Reserve P0 for genuine blockers where downstream
+steps will fail or produce incorrect output.
+
+### Fix Without Re-Review
+Applying fixes to findings without re-running the review. Fixes can introduce new
+issues or incompletely address the original finding. Always re-review after fixes.
+
+### Ignoring Convergent Multi-Model Findings
+When multiple models independently find the same issue, it has high confidence.
+Dismissing convergent findings without strong justification undermines the value
+of multi-model review.
+
+### Removing Prior Findings
+Deleting findings from a re-review output instead of marking them RESOLVED. This
+loses review history and makes it impossible to track what was caught and fixed.

package/knowledge/core/{security-review.md → security-best-practices.md}

@@ -1,9 +1,11 @@
 ---
-name: security-review
+name: security-best-practices
 description: OWASP Top 10, authentication, authorization, data protection, and threat modeling
 topics: [security, owasp, authentication, authorization, threat-modeling, secrets-management, dependency-auditing]
 ---
 
+## Summary
+
 ## OWASP Top 10
 
 The OWASP Top 10 represents the most critical security risks to web applications. Every project should evaluate each risk and implement appropriate mitigations.
@@ -55,6 +57,8 @@ Sensitive data exposed due to weak or missing encryption.
 - Hash passwords with bcrypt, scrypt, or Argon2 (NEVER MD5 or SHA-256 for passwords)
 - Don't store sensitive data you don't need — the safest data is data you don't have
 
+## Deep Guidance
+
 ### A03: Injection
 
 Untrusted data sent to an interpreter as part of a command or query, causing unintended execution.
@@ -521,3 +525,7 @@ Protect against compromised dependencies:
 **No rate limiting.** Login endpoints with unlimited attempts allow brute-force password attacks. API endpoints with no rate limits allow denial of service. Fix: implement rate limiting on all public endpoints. Start with conservative limits. Use exponential backoff for authentication failures.
 
 **Ignoring dependency vulnerabilities.** Running `npm audit` shows 47 vulnerabilities but nobody addresses them because "they're all low severity." Fix: set a policy and enforce it in CI. Critical and high vulnerabilities block deployment. Medium vulnerabilities have a SLA for resolution.
+
+## See Also
+
+- [operations-runbook](../core/operations-runbook.md) — Logging and monitoring sensitive data

package/knowledge/core/system-architecture.md

@@ -1,9 +1,11 @@
 ---
 name: system-architecture
 description: Architecture patterns, component design, and project structure
-topics: [architecture, components, modules, data-flows, project-structure, state-management]
+topics: [architecture, components, modules, data-flow, project-structure, state-management]
 ---
 
+## Summary
+
 ## Architecture Patterns
 
 ### Layered Architecture
@@ -81,6 +83,8 @@ For most scaffold pipeline projects:
 4. Use **microservices** only if you have multiple teams that need independent deployment, or specific services with dramatically different scaling needs.
 5. Avoid **layered** unless the application is genuinely simple (CRUD with minimal business logic).
 
+## Deep Guidance
+
 ## Component Design
 
 ### Identifying Components from Domain Models

package/knowledge/core/task-decomposition.md

@@ -4,11 +4,52 @@ description: Breaking architecture into implementable tasks with dependency anal
 topics: [tasks, decomposition, dependencies, user-stories, parallelization, sizing, critical-path]
 ---
 
-## User Stories to Tasks
+# Task Decomposition
 
-> **Note:** User stories are created as an upstream artifact in the pre-pipeline phase and available at `docs/user-stories.md`. This section covers how to consume stories and derive implementation tasks from them.
+Expert knowledge for breaking user stories into implementable tasks with dependency analysis, sizing, parallelization, and agent context requirements.
+
+## Summary
+
+### Story-to-Task Mapping
+
+User stories bridge PRD features and implementation tasks. Each story decomposes into tasks following the technical layers needed. Every task must trace back to a user story, and every story to a PRD feature (PRD Feature → US-xxx → Task BD-xxx).
+
+### Task Sizing
+
+Each task should be completable in a single AI agent session (30-90 minutes of agent time). A well-sized task has a clear title (usable as commit message), touches 1-3 application files (hard limit; justify exceptions), produces ~150 lines of net-new application code (excluding tests and generated files), and has no ambiguity about "done."
+
+Five rules govern agent-friendly task sizing:
+1. **Three-File Rule** — Max 3 application files modified (test files excluded)
+2. **150-Line Budget** — Max ~150 lines of net-new application code per task
+3. **Single-Concern Rule** — One task does one thing (no "and" connecting unrelated work)
+4. **Decision-Free Execution** — All design decisions resolved in the task description; agents implement, they don't architect
+5. **Test Co-location** — Tests live in the same task as the code they test; no deferred testing
+
+Split large tasks by layer (API, UI, DB, tests), by feature slice (happy path, validation, edge cases), or by entity. Combine tiny tasks that touch the same file and have no independent value.
+
+### Dependency Types
+
+- **Logical** — Task B requires Task A's output (endpoint needs DB schema)
+- **File contention** — Two tasks modify the same file (merge conflict risk)
+- **Infrastructure** — Task requires setup that must exist first (DB, auth, CI)
+- **Knowledge** — Task benefits from understanding gained in another task
+
+Only logical, file contention, and infrastructure dependencies should be formal constraints.
+
+### Definition of Done
+
+1. Acceptance criteria from the user story are met
+2. Unit tests pass (for new logic)
+3. Integration tests pass (for API endpoints or component interactions)
+4. No linting or type errors
+5. Code follows project coding standards
+6. Changes committed with proper message format
+
+## Deep Guidance
+
+### From Stories to Tasks — Extended
 
-### From Stories to Tasks
+> **Note:** User stories are created as an upstream artifact in the pre-pipeline phase and available at `docs/user-stories.md`. This section covers how to consume stories and derive implementation tasks from them.
 
 User stories bridge the gap between what the business wants (PRD features) and what developers build (implementation tasks). Every PRD feature maps to one or more user stories (created in the pre-pipeline), and every user story should map to one or more implementation tasks.
 
@@ -115,16 +156,19 @@ This traceability ensures:
 - No orphan tasks exist (every task serves a purpose)
 - Impact analysis is possible (changing a PRD feature reveals which tasks are affected)
 
-## Task Sizing
+### Task Sizing — Extended
 
-### Right-Sizing for Agent Sessions
+#### Right-Sizing for Agent Sessions
 
 Each task should be completable in a single AI agent session (typically 30-90 minutes of agent time). Tasks that are too large overflow the context window; tasks that are too small create unnecessary coordination overhead.
 
 **A well-sized task:**
 - Has a clear, specific title that could be a commit message
-- Touches 1-5 files (not counting test files)
-- Produces a testable, verifiable result
+- Touches 1-3 application files (hard limit; test files excluded from count)
+- Produces ~150 lines of net-new application code (excluding tests and generated files)
+- Does exactly one thing (passes the single-concern test: describable without "and")
+- Requires no design decisions from the agent (all choices resolved in the description)
+- Includes co-located tests (the task isn't done until tests pass)
 - Has no ambiguity about what "done" means
 - Can be code-reviewed independently
 
@@ -136,7 +180,7 @@ Each task should be completable in a single AI agent session (typically 30-90 mi
 | "Create Button component" | "Build form components (Input, Select, Textarea) with validation states" | "Create the full design system" |
 | "Add index to users table" | "Create database schema for user management with migration" | "Set up the entire database" |
 
-### Splitting Large Tasks
+#### Splitting Large Tasks
 
 When a task is too large, split along these axes:
 
@@ -163,7 +207,7 @@ When a task is too large, split along these axes:
 - The task involves more than 2 architectural boundaries (e.g., database + API + frontend + auth)
 - You can't describe what "done" looks like in 2-3 sentences
 
-### Combining Small Tasks
+#### Combining Small Tasks
 
 If multiple tiny tasks touch the same file and have no independent value, combine them:
 
@@ -172,20 +216,9 @@ If multiple tiny tasks touch the same file and have no independent value, combin
 
 The test: would the small task result in a useful commit on its own? If not, combine.
 
-### Definition of Done
-
-Every task needs a clear definition of done. Standard criteria:
-
-1. All acceptance criteria from the user story are met
-2. Unit tests pass (for new logic)
-3. Integration tests pass (for API endpoints or component interactions)
-4. No linting or type errors
-5. Code follows project coding standards
-6. Changes are committed with proper message format
+### Dependency Analysis — Extended
 
-## Dependency Analysis
-
-### Types of Dependencies
+#### Types of Dependencies
 
 **Logical dependencies:** Task B requires Task A's output. The API endpoint task depends on the database schema task because the endpoint queries tables that must exist first.
 
@@ -195,7 +228,7 @@ Every task needs a clear definition of done. Standard criteria:
 
 **Knowledge dependencies:** A task requires understanding gained from completing another task. The developer who builds the auth system understands the auth patterns needed by other features.
 
-### Building Dependency Graphs (DAGs)
+#### Building Dependency Graphs (DAGs)
 
 A dependency graph is a directed acyclic graph (DAG) where:
 - Nodes are tasks
@@ -210,7 +243,7 @@ A dependency graph is a directed acyclic graph (DAG) where:
 4. Draw an edge from producer to consumer
 5. Check for cycles (if A depends on B and B depends on A, something is wrong — split or reorganize)
 
-### Detecting Cycles
+#### Detecting Cycles
 
 Cycles indicate a modeling problem. Common causes and fixes:
 
@@ -218,7 +251,7 @@ Cycles indicate a modeling problem. Common causes and fixes:
 - **Feature interaction:** Feature X needs Feature Y's component, and Feature Y needs Feature X's component. Fix: extract the shared component into its own task.
 - **Testing dependency:** "Can't test A without B, can't test B without A." Fix: use mocks/stubs to break the cycle during testing. The integration test that tests both together becomes a separate task.
 
-### Finding Critical Path
+#### Finding Critical Path
 
 The critical path is the longest chain of dependent tasks from start to finish. It determines the minimum project duration.
 
@@ -235,7 +268,7 @@ The critical path is the longest chain of dependent tasks from start to finish.
 - To shorten the project, focus on splitting or accelerating critical-path tasks
 - Non-critical-path tasks have "float" — they can be delayed without affecting the project end date
 
-### Dependency Documentation
+#### Dependency Documentation
 
 For each dependency, document:
 
@@ -245,9 +278,9 @@ For each dependency, document:
 | BD-12 -> BD-13 | File contention | Both modify src/routes/index.ts | Medium — merge conflict risk |
 | BD-01 -> BD-* | Infrastructure | BD-01 sets up the database; everything needs it | High — blocks all work |
 
-## Parallelization
+### Parallelization and Wave Planning
 
-### Identifying Independent Tasks
+#### Identifying Independent Tasks
 
 Tasks are safe to run in parallel when:
 - They have no shared dependencies (no common prerequisite still in progress)
@@ -267,7 +300,7 @@ Tasks are safe to run in parallel when:
 - Tasks that modify the same shared utility file
 - Tasks where one produces test fixtures the other consumes
 
-### Managing Shared-State Tasks
+#### Managing Shared-State Tasks
 
 When tasks must share state (database, shared configuration, route registry):
 
@@ -277,7 +310,7 @@ When tasks must share state (database, shared configuration, route registry):
 
 **Feature flags:** Both tasks can merge independently. A feature flag controls which one is active. Integrate them in a separate task after both complete.
 
-### Merge Strategies for Parallel Work
+#### Merge Strategies for Parallel Work
 
 When parallel tasks produce branches that must be merged to main:
 
@@ -285,7 +318,7 @@ When parallel tasks produce branches that must be merged to main:
 - **First-in wins:** The first task to merge gets a clean merge. Subsequent tasks must rebase and resolve conflicts.
 - **Minimize shared files:** Design the task decomposition to minimize file overlap. Feature-based directory structure helps enormously.
 
-### Wave Planning
+#### Wave Planning
 
 Organize tasks into waves based on the dependency graph:
 
@@ -298,9 +331,9 @@ Wave 4 (depends on Wave 3): End-to-end tests, performance optimization, polish
 
 Each wave's tasks can run in parallel. Wave N+1 starts only when all its dependencies in Wave N are complete. The number of parallel agents should match the number of independent tasks in the current wave.
 
-## Agent Context
+### Agent Context Requirements
 
-### What Context Each Task Needs
+#### What Context Each Task Needs
 
 Every task description should specify what documents and code the implementing agent needs to read:
 
@@ -321,7 +354,7 @@ Produces:
 - tests/features/auth/register.integration.test.ts
 ```
 
-### Handoff Information
+#### Handoff Information
 
 When a task produces output that another task consumes, specify the handoff:
 
@@ -338,7 +371,7 @@ Consuming tasks:
   BD-30 (onboarding flow) expects the response shape above
 ```
 
-### Assumed Prior Work
+#### Assumed Prior Work
 
 Explicitly state what the agent can assume exists:
 
@@ -353,7 +386,112 @@ Does NOT assume:
 - Any auth endpoints exist (this is the first)
 ```
 
-## Common Pitfalls
+### Agent Executability Heuristics
+
+Five formalized rules for ensuring tasks are the right size for AI agent execution. These are hard rules with an escape hatch — tasks exceeding limits must be split unless the author provides explicit justification via `<!-- agent-size-exception: reason -->`.
+
+#### Rule 1: Three-File Rule
+
+A task modifies at most 3 application files (test files don't count toward this limit). If it would touch more, split by layer or concern.
+
+**Why 3:** Reading 3 files plus their context (imports, types, interfaces) consumes roughly 40-60% of a standard agent context window, leaving room for the task description, test code, and reasoning. At 5+ files, context pressure causes agents to lose track of cross-file consistency.
+
+**Splitting when exceeded:**
+- 4 files across 2 layers → split into one task per layer
+- 5 files in the same layer → split by entity or concern within the layer
+- Config files touched alongside application files → separate config task if non-trivial
+
+#### Rule 2: 150-Line Budget
+
+A task produces at most ~150 lines of net-new application code (excluding tests, generated files, and config). This keeps the entire change reviewable in one screen and within agent context budgets.
+
+**Why 150:** Agent output quality degrades measurably after ~200 lines of new code in a single session. At 150 lines, the agent can hold the entire change in context while writing tests and verifying correctness.
+
+**Estimating line count from task descriptions:**
+- A CRUD endpoint with validation: ~80-120 lines
+- A UI component with state management: ~100-150 lines
+- A database migration with seed data: ~50-80 lines
+- A full feature slice (API + UI + tests): ~300+ lines — MUST split
+
+#### Rule 3: Single-Concern Rule
+
+A task does exactly one thing. The test: can you describe what this task does in one sentence without "and"?
+
+**Passes the test:**
+- "Implement the user registration endpoint with input validation" (validation is part of the endpoint)
+- "Create the order model with database migration" (migration is part of model creation)
+
+**Fails the test:**
+- "Add the API endpoint AND update the dashboard" — two tasks
+- "Implement authentication AND set up the database" — two tasks
+- "Build the payment form AND integrate with Stripe AND add webhook handling" — three tasks
+
+**Splitting signals:**
+- Task description contains "and" connecting unrelated work
+- Task spans multiple architectural layers (API + frontend + database in one task)
+- Task affects multiple bounded contexts or feature domains
+- Task has acceptance criteria for two distinct user-facing behaviors
+
+#### Rule 4: Decision-Free Execution
+
+The task description must resolve all design decisions upfront. The agent implements, it doesn't architect. No task should require the agent to:
+
+- Choose between patterns (repository vs active record, REST vs GraphQL)
+- Select libraries or tools
+- Decide module structure or file organization
+- Determine API contract shapes (these come from upstream specs)
+
+**Red flags in task descriptions:**
+- "Choose the best approach for..."
+- "Determine whether to use X or Y"
+- "Decide how to structure..."
+- "Evaluate options for..."
+- "Select the most appropriate..."
+- "Figure out the best way to..."
+
+If a task contains any of these, the decision belongs in the task description — resolved by the plan author — not left to agent judgment. Local implementation choices (variable names, loop style, internal helper structure) are fine.
+
+#### Rule 5: Test Co-location
+
+Tests live in the same task as the code they test. The task follows TDD: write the failing test, then the implementation, then verify. The task isn't done until tests pass.
+
+**Anti-pattern:** "Tasks 1-8: implement features. Task 9: write tests for everything." This produces untestable code, violates TDD, and creates a single massive testing task that exceeds all size limits.
+
+**What co-location looks like:**
+```
+Task: Implement user registration endpoint
+  1. Write failing integration test (POST /register with valid data → 201)
+  2. Implement endpoint to make test pass
+  3. Write failing validation test (invalid email → 400)
+  4. Add validation to make test pass
+  5. Commit
+```
+
+#### Escape Hatch
+
+If a task genuinely can't be split further without creating tasks that have no independent value, add an explicit annotation in the task description: `<!-- agent-size-exception: [reason] -->`. The review pass flags unjustified exceptions but accepts reasoned ones.
+
+**Valid exception reasons:**
+- "Migration task touches 4 files but they're all trivial one-line renames"
+- "Config file changes across 4 files are mechanical and identical in structure"
+- "Test setup file is large but generated from a template"
+
+**Invalid exception reasons:**
+- "It's easier to do it all at once" (convenience is not a justification)
+- "The files are related" (related files can still be separate tasks)
+- "It would create too many tasks" (more small tasks > fewer large tasks)
+
+#### Concrete "Too Big" Examples
+
+| Task (Too Big) | Violations | Split Into |
+|---------------|-----------|------------|
+| "Implement user authentication" (8+ files, registration + login + reset + middleware) | Three-File, Single-Concern | 4 tasks: registration endpoint, login endpoint, password reset flow, auth middleware |
+| "Build the settings page with all preferences" (6 files, multiple forms + APIs) | Three-File, 150-Line, Single-Concern | Per-group: profile settings, notification settings, security settings |
+| "Set up database with all migrations and seed data" (10+ files, every entity) | Three-File, 150-Line | Per-entity: users table, orders table, products table, then seed data task |
+| "Create API client with retry, caching, and auth" (4 concerns in one module) | Single-Concern, Decision-Free | 3 tasks: base client with auth, retry middleware, cache layer |
+| "Implement the dashboard with charts, filters, and real-time updates" (5+ files, 300+ lines) | All five rules | 4 tasks: dashboard layout + routing, chart components, filter system, WebSocket integration |
+
+### Common Pitfalls
 
 **Tasks too vague.** "Implement backend" or "Set up auth" with no acceptance criteria, no file paths, and no test requirements. An agent receiving this task will guess wrong about scope, structure, and conventions. Fix: every task must specify exact files to create/modify, acceptance criteria, and test requirements.