specweave 0.1.7 → 0.1.8

package/README.md

@@ -3,7 +3,7 @@
 > **Spec-Driven Development Framework** - Where specifications and documentation are the source of truth
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-0.1.6-blue.svg)](https://github.com/anton-abyzov/specweave/releases/tag/v0.1.6)
+[![Version](https://img.shields.io/badge/version-0.1.8-blue.svg)](https://github.com/anton-abyzov/specweave/releases/tag/v0.1.8)
 [![Status](https://img.shields.io/badge/status-beta-blue.svg)]()
 [![Website](https://img.shields.io/badge/website-spec--weave.com-green.svg)](https://spec-weave.com)
 
@@ -115,17 +115,18 @@ cd my-app
 
 # Open Claude Code and use slash commands:
 
-User: /pi "Next.js authentication with email and OAuth"
+User: /inc "Next.js authentication with email and OAuth"
     ↓
-SpecWeave: 🔷 SpecWeave Active (/create-increment)
+SpecWeave: 🔷 SpecWeave Active (/increment)
 
            🚀 Creating increment 0001-user-authentication...
            📝 Using nextjs skill (already installed!)
            🤖 PM agent creating requirements...
            🏗️  Architect agent designing system...
+           📋 Auto-generating tasks from plan...
 
 ✅ Increment created: .specweave/increments/0001-user-authentication/
-✅ Files: spec.md, plan.md, tasks.md, tests.md
+✅ Files: spec.md, plan.md, tasks.md (auto-generated!), tests.md
 
 User: "Create C4 context diagram for authentication"  # Regular conversation for implementation
     ↓
@@ -146,12 +147,13 @@ User: /done 0001  # Close increment with slash command
 ✅ Increment 0001 closed successfully
 ```
 
-**How it works**:
+**How it works** (append-only increment workflow: 0001 → 0002 → 0003):
 1. `specweave init` → ALL components pre-installed (10 agents + 35+ skills)
-2. **Use `/pi "feature"`** → Creates increment with specs (spec.md, plan.md, tasks.md, tests.md)
-3. **Regular conversation** → Implement code based on specifications
-4. **Use `/done 0001`** → Close increment when complete
-5. All components ready - no waiting, no installation
+2. **Use `/inc "feature"`** → PM creates specs + plan + auto-generates tasks
+3. **Use `/build 0001`** → Execute implementation (hooks after EVERY task)
+4. **Use `/validate 0001`** → Optional quality check (LLM-as-judge)
+5. **Use `/done 0001`** → PM validates 3 gates (tasks ✅ + tests ✅ + docs ✅)
+6. All components ready - no waiting, no installation
 
 **Why slash commands?** Auto-activation doesn't work reliably - slash commands ensure SpecWeave ALWAYS activates when you want it.
 
@@ -184,7 +186,7 @@ SpecWeave includes **35+ AI skills** that work with slash commands:
 
 ### Core Framework Skills
 - **specweave-detector** - Slash command documentation
-- **increment-planner** - Plan features via `/pi` command
+- **increment-planner** - Plan features via `/inc` or `/increment` command
 - **skill-router** - Route requests to appropriate skills
 - **context-loader** - Load relevant specifications
 - **role-orchestrator** - Coordinate multiple agents
@@ -295,21 +297,26 @@ specweave/
 # Option A: Comprehensive (Enterprise) - 500-600+ pages upfront
 # Option B: Incremental (Startup) - Build as you go
 
-# 2. Create increment with slash command
-/pi "user authentication"
-# Short alias for /create-increment
-# SpecWeave orchestrates: PM → Architect → QA agents
-# Creates: spec.md, plan.md, tasks.md, tests.md
+# 2. Plan increment with slash command (PM-led process)
+/inc "user authentication"
+# Alias for /increment
+# PM-led: Market research → spec.md → plan.md → auto-generate tasks.md
+# Creates: spec.md, plan.md, tasks.md (auto-generated!), tests.md
 
-# 3. Implement with regular conversation (no slash command needed)
-"Implement user authentication based on plan.md"
-# Claude implements based on specifications
+# 3. Build it (hooks run after EVERY task)
+/build 0001
+# Executes tasks sequentially
+# Hooks automatically update CLAUDE.md, README.md, CHANGELOG.md
 
-# 4. Generate diagrams (regular conversation)
-"Create C4 context diagram for authentication"
+# 4. Validate quality (optional)
+/validate 0001 --quality
+# LLM-as-judge quality assessment
 
-# 5. Close increment with slash command
+# 5. Close increment (PM validates 3 gates)
 /done 0001
+# Gate 1: Tasks completed (P1 required)
+# Gate 2: Tests passing (>80% coverage)
+# Gate 3: Documentation updated
 
 # 6. Sync with tools (optional)
 /sync-github  # Sync to GitHub issues
@@ -480,19 +487,19 @@ npm test
 
 ## 🏷️ Project Status
 
-**Version**: 0.1.6
+**Version**: 0.1.8
 **Status**: Public Beta
 **License**: MIT
 **Release Date**: 2025-10-28
 **Website**: [spec-weave.com](https://spec-weave.com)
 
-### ✅ What Works (v0.1.6)
+### ✅ What Works (v0.1.8)
 
 - ✅ **10 Agents** fully implemented and pre-installed
 - ✅ **35+ Skills** fully implemented and pre-installed
 - ✅ **CLI Tool** - `specweave init` with complete component copying
 - ✅ **Ready Out of the Box** - All components installed during init
-- ✅ **Auto-detection** and intelligent routing (fixed in 0.1.6!)
+- ✅ **Command simplification** - 4-command workflow (0.1.8)
 - ✅ **Diagram generation** (C4 Model with validation)
 - ✅ **4-level testing framework** (spec → feature → component → automated)
 - ✅ **JIRA/ADO/GitHub sync** integration

package/SPECWEAVE.md

@@ -21,25 +21,31 @@ This file contains quick reference for developing with SpecWeave:
 
 SpecWeave follows the **spec-kit approach**: You MUST use slash commands explicitly.
 
-**To use SpecWeave**: Type a slash command (e.g., `/pi "Feature description"`)
+**To use SpecWeave**: Type a slash command (e.g., `/inc "Feature description"`)
 
 ### Quick Command Reference
 
+**Core Workflow** (4 commands):
+
 | Alias | Full Command | Purpose | Example |
 |-------|--------------|---------|---------|
-| `/init` | `/create-project` | Initialize SpecWeave project | `/init my-saas` |
-| `/pi` | `/create-increment` | **Plan Product Increment** | `/pi "User auth"` |
-| `/si` | `/start-increment` | Start working on increment | `/si 0001` |
-| `/at` | `/add-tasks` | Add tasks to increment | `/at 0001 "Add tests"` |
-| `/vi` | `/validate-increment` | Validate increment quality | `/vi 0001 --quality` |
-| `/done` | `/close-increment` | Close increment | `/done 0001` |
-| `/ls` | `/list-increments` | List all increments | `/ls` |
-
-**Why Slash Commands?**
-- ✅ **100% reliable** - Always works, no guessing
-- ✅ **Clear intent** - You know exactly when SpecWeave is active
-- ✅ **Fast** - Short aliases like `/pi` save keystrokes
-- ✅ **Memorable** - Domain-specific names (PI = Product Increment from Agile/SAFe)
+| `/inc` | `/increment` | **Plan Product Increment** (PM-led) | `/inc "User auth"` |
+| - | `/build` | Execute implementation (hooks after every task) | `/build 0001` |
+| - | `/validate` | Validate quality (optional LLM judge) | `/validate 0001 --quality` |
+| - | `/done` | Close increment (PM validates 3 gates) | `/done 0001` |
+
+**Supporting Commands**:
+- `/create-project` - Initialize SpecWeave project
+- `/list-increments` - List all increments
+- `/review-docs` - Review docs vs code
+- `/generate-docs` - Generate doc site
+- `/sync-github` - Sync to GitHub
+
+**Why ONE Alias (/inc)?**
+- ✅ `/inc` is THE most used command (every new feature starts here)
+- ✅ Append-only increment workflow: 0001 → 0002 → 0003 → ...
+- ✅ Other commands used once per increment (no aliases needed)
+- ✅ Clear and explicit workflow
 
 ### Typical Workflow
 
@@ -47,24 +53,26 @@ SpecWeave follows the **spec-kit approach**: You MUST use slash commands explici
 # 1. Initialize project
 npx specweave init my-saas
 
-# 2. Plan your first increment (use slash command!)
-/pi "User authentication with JWT and RBAC"
+# 2. Plan your first increment (use /inc - the ONLY alias!)
+/inc "User authentication with JWT and RBAC"
 
-# 3. Validate
-/vi 0001 --quality
+# 3. Review generated docs
+#    spec.md, plan.md, tasks.md (auto-generated!), tests.md
 
-# 4. Start working
-/si 0001
+# 4. Build it (hooks run after EVERY task)
+/build 0001
 
-# 5. Implement (regular conversation, no slash commands needed here)
-User: "Let's implement the backend API"
-Claude: [implements based on plan.md and tasks.md]
+# 5. Validate quality (optional)
+/validate 0001 --quality
 
-# 6. Close when done
+# 6. Close when done (PM validates: tasks ✅ + tests ✅ + docs ✅)
 /done 0001
+
+# 7. Repeat for next feature
+/inc "Payment processing"
 ```
 
-**Remember**: Type `/pi` first, THEN implement! Otherwise you lose all SpecWeave benefits (specs, architecture, test strategy).
+**Remember**: Type `/inc` first, THEN build! Otherwise you lose all SpecWeave benefits (specs, architecture, auto-generated tasks, test strategy).
 
 ---
 
@@ -193,24 +201,22 @@ npx specweave list --installed      # See what's installed
 
 **CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type them to activate the framework!
 
+### Core Workflow (4 Commands)
+
 | Command | Alias | Purpose | Example |
 |---------|-------|---------|---------|
-| `/create-project` | `/init` | Bootstrap new SpecWeave project | `/init my-saas --type python` |
-| `/create-increment` | `/pi` | **Plan Product Increment** (create new feature) | `/pi "user authentication"` |
-| `/start-increment` | `/si` | Start working on an increment | `/si 0001` |
-| `/add-tasks` | `/at` | Add tasks to existing increment | `/at 0001 "implement login"` |
-| `/validate-increment` | `/vi` | Validate with rule-based + optional AI quality | `/vi 0001 --quality` |
-| `/close-increment` | `/done` | Close increment with leftover transfer | `/done 0001` |
-| `/list-increments` | `/ls` | List all increments with status | `/ls --status=in-progress` |
-| `/review-docs` | - | Review strategic docs vs code | `/review-docs --increment=0003` |
-| `/generate-docs` | - | Generate documentation site | `/generate-docs` |
-| `/sync-github` | - | Sync increment to GitHub issues | `/sync-github` |
+| `/increment` | `/inc` | Plan Product Increment (PM-led, auto-generates tasks) | `/inc "user authentication"` |
+| `/build` | - | Execute implementation (hooks after EVERY task) | `/build 0001` |
+| `/validate` | - | Validate quality (optional LLM judge) | `/validate 0001 --quality` |
+| `/done` | - | Close increment (PM validates 3 gates: tasks, tests, docs) | `/done 0001` |
 
-**All commands are framework-agnostic** (adapt to detected tech stack)
+### Supporting Commands
 
-**💡 Pro Tip**: Use short aliases (`/pi`, `/vi`, `/si`, `/done`, `/ls`, `/at`, `/init`) for speed during active development!
-- **PI** = Product Increment (standard Agile terminology)
-- **Why explicit?** Auto-activation doesn't work reliably - slash commands ensure SpecWeave ALWAYS activates
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `/create-project` | Bootstrap new SpecWeave project | `/create-project --type python` |
+| `/list-increments` | List all increments with status | `/list-increments` |
+**All commands are framework-agnostic** (adapt to detected tech stack)
 
 **See**: [Command Reference](.claude/commands/) for all available commands
 
@@ -246,7 +252,7 @@ npx specweave list --installed      # See what's installed
 | Skill | Purpose | Activates When |
 |-------|---------|----------------|
 | `specweave-detector` | Slash command documentation | User asks about SpecWeave commands |
-| `increment-planner` | Plan features with context | `/pi` or `/create-increment` command |
+| `increment-planner` | Plan features with context | `/inc` or `/increment` command |
 | `skill-router` | Route to appropriate skills | Ambiguous requests |
 | `context-loader` | Load context selectively | Working on increments |
 | `diagrams-generator` | Coordinate diagram creation | "create diagram", "draw diagram", C4, sequence, ER |
@@ -302,17 +308,12 @@ backlog → planned → in-progress → completed → closed
 
 **Naming Convention**: 4-digit format (0001-9999), e.g., `0001-feature-name`, `0042-user-auth`, `0123-payment-flow`
 
-**Commands** (MUST USE SLASH COMMANDS!):
+**Commands**:
 ```bash
-# Use short aliases (recommended)
-/pi "feature name"                    # Create new increment (auto-numbered, e.g., 0003-feature-name)
-/at 0001 "task description"           # Add tasks to existing
-/done 0001                             # Close with leftover transfer
-
-# Or full commands
-/create-increment "feature name"      # Same as /pi
-/add-tasks 0001 "task description"    # Same as /at
-/close-increment 0001                 # Same as /done
+/inc "feature name"                    # Plan increment (PM-led, auto-generates tasks)
+/build 0001                            # Execute implementation (hooks after EVERY task)
+/validate 0001 --quality               # Validate quality (optional)
+/done 0001                             # Close increment (PM validates 3 gates)
 ```
 
 **See**: [Increment Lifecycle Guide](.specweave/docs/internal/delivery/guides/increment-lifecycle.md) for complete lifecycle management
@@ -685,24 +686,25 @@ Attempt 2/3: Refining with feedback...
 
 **Quick Start**:
 
-**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type `/pi` to activate!
+**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type `/inc` to activate!
 
 ```bash
 # Initialize project
 npx specweave init my-project
 
-# Create your first feature (use slash command!)
-/pi "feature description"
+# Plan your first increment (use slash command!)
+/inc "feature description"
 
-# Typical workflow
-1. /pi "feature" → SpecWeave creates specs
-2. Regular conversation → Claude implements code
-3. /done 0001 → Close increment
+# Typical workflow (append-only increments: 0001 → 0002 → 0003)
+1. /inc "feature" → PM creates specs + plan + auto-generates tasks
+2. /build 0001 → Execute implementation (hooks after EVERY task)
+3. /validate 0001 --quality → Optional quality check
+4. /done 0001 → PM validates 3 gates (tasks ✅ + tests ✅ + docs ✅)
 ```
 
-**Remember**: Type `/pi` first, THEN implement! Otherwise you lose all SpecWeave benefits (specs, architecture, test strategy).
+**Remember**: Type `/inc` first to plan, THEN `/build` to implement! Otherwise you lose all SpecWeave benefits (specs, architecture, test strategy).
 
-**Need help?**: Type `/pi` to see examples, or ask about specific workflows.
+**Need help?**: Type `/inc` to see examples, or ask about specific workflows.
 
 **SpecWeave Documentation**: https://spec-weave.com
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave",
-  "version": "0.1.7",
-  "description": "Spec-Driven Development framework with AI-powered autonomous agents for building SaaS applications",
+  "version": "0.1.8",
+  "description": "Replace vibe coding with spec-driven development. 4-command workflow (/inc, /build, /validate, /done), PM-led planning, 10 agents, 35+ skills. Visit spec-weave.com",
   "main": "dist/index.js",
   "bin": {
     "specweave": "./bin/specweave.js"

package/src/agents/pm/AGENT.md

@@ -734,6 +734,291 @@ Avoid technical jargon with stakeholders. Focus on:
 
 ---
 
+## 🔥 CRITICAL: Increment Closure Validation (/done Command)
+
+**MANDATORY BEHAVIOR**: When invoked via `/done` command, PM Agent acts as the **final quality gate** before increment closure.
+
+### Role: Product Owner / Release Manager
+
+You are the final approver for increment closure. Your job is to ensure:
+1. ✅ **Business value delivered** (all critical tasks complete)
+2. ✅ **Quality maintained** (tests passing, no regressions)
+3. ✅ **Knowledge preserved** (documentation updated)
+
+**You MUST validate ALL 3 gates before approving closure.**
+
+---
+
+### Validation Workflow
+
+When user runs `/done <increment-id>`, follow these steps:
+
+#### Step 1: Load Increment Context
+
+```bash
+# Load all documents
+Read: .specweave/increments/{id}/spec.md
+Read: .specweave/increments/{id}/plan.md
+Read: .specweave/increments/{id}/tasks.md
+Read: .specweave/increments/{id}/tests.md
+```
+
+#### Step 2: Validate Gate 1 - Tasks Completed ✅
+
+**Check**:
+- [ ] All P1 (critical) tasks completed
+- [ ] All P2 (important) tasks completed OR deferred with reason
+- [ ] P3 (nice-to-have) tasks completed, deferred, or moved to backlog
+- [ ] No tasks in "blocked" state
+- [ ] Acceptance criteria for each task met
+
+**Example Pass**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GATE 1: Tasks Completion ✅ PASS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Priority P1 (Critical): 12/12 completed (100%)
+Priority P2 (Important): 16/18 completed (89%) - 2 deferred with reason
+Priority P3 (Nice-to-have): 8/12 completed (67%) - 4 moved to backlog
+
+Status: ✅ PASS
+```
+
+**Example Fail**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GATE 1: Tasks Completion ❌ FAIL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Priority P1 (Critical): 10/12 completed (83%)
+
+Incomplete P1 tasks:
+  ❌ T005: Add password hashing (CRITICAL - security requirement)
+  ❌ T008: Implement JWT validation (CRITICAL - auth won't work)
+
+Recommendation: ❌ CANNOT close increment
+  • Complete T005 and T008 (security critical)
+  • Estimated effort: 4-6 hours
+```
+
+#### Step 3: Validate Gate 2 - Tests Passing ✅
+
+**Check**:
+- [ ] All test suites passing (no failures)
+- [ ] Test coverage meets requirements (>80% for critical paths)
+- [ ] E2E tests passing (if UI exists)
+- [ ] No skipped tests without documentation
+- [ ] Test cases align with acceptance criteria in spec.md
+
+**Ask user to run tests**:
+```
+Please run the test suite and share results:
+  npm test           # Run all tests
+  npm run test:coverage  # Check coverage
+```
+
+**Example Pass**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GATE 2: Tests Passing ✅ PASS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Unit Tests: 47/47 passing ✅
+Integration Tests: 15/15 passing ✅
+E2E Tests: 8/8 passing ✅
+Coverage: 89% (above 80% target) ✅
+
+Status: ✅ PASS
+```
+
+**Example Fail**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GATE 2: Tests Passing ❌ FAIL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Unit Tests: 45/47 passing (96%) - 2 failures
+E2E Tests: 7/8 passing (88%) - 1 failure
+
+Failures:
+  ❌ test/auth/jwt.test.ts: Token expiry validation
+  ❌ test/e2e/login.spec.ts: Rate limiting test
+
+Recommendation: ❌ CANNOT close increment
+  • Fix JWT expiry configuration (security issue)
+  • Fix rate limiting (prevents brute force attacks)
+  • Estimated effort: 2-3 hours
+```
+
+#### Step 4: Validate Gate 3 - Documentation Updated ✅
+
+**Check**:
+- [ ] CLAUDE.md updated with new features
+- [ ] README.md updated with usage examples
+- [ ] CHANGELOG.md updated (if public API changed)
+- [ ] API documentation regenerated (if applicable)
+- [ ] Inline code documentation complete
+- [ ] No stale references to old code
+
+**Scan files**:
+```bash
+Read: CLAUDE.md
+Read: README.md
+Read: CHANGELOG.md
+Grep: Search for references to new features
+```
+
+**Example Pass**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GATE 3: Documentation Updated ✅ PASS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CLAUDE.md: ✅ Updated with new features
+README.md: ✅ Updated with examples
+CHANGELOG.md: ✅ v0.1.8 entry added
+Inline Docs: ✅ All functions documented
+
+Status: ✅ PASS
+```
+
+**Example Fail**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GATE 3: Documentation Updated ❌ FAIL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+CLAUDE.md: ❌ Missing authentication section
+README.md: ❌ No authentication examples
+CHANGELOG.md: ❌ v0.1.8 entry missing
+
+Recommendation: ❌ CANNOT close increment
+  • Update CLAUDE.md with authentication section
+  • Add examples to README.md
+  • Create CHANGELOG.md entry
+  • Estimated effort: 1-2 hours
+```
+
+#### Step 5: PM Decision
+
+**If ALL 3 gates pass**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PM VALIDATION RESULT: ✅ READY TO CLOSE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Gate 1: Tasks Completed (100% P1, 89% P2)
+✅ Gate 2: Tests Passing (70/70, 89% coverage)
+✅ Gate 3: Documentation Updated (all current)
+
+Business Value Delivered:
+  • [List key deliverables from spec.md]
+
+PM Approval: ✅ APPROVED for closure
+
+Next steps:
+  1. Update status: in-progress → completed
+  2. Set completion date
+  3. Generate completion report
+  4. Update backlog with deferred tasks
+```
+
+**If ANY gate fails**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PM VALIDATION RESULT: ❌ NOT READY TO CLOSE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Gate status summary]
+
+PM Decision: ❌ CANNOT close increment
+
+Blockers:
+  1. [List all blockers with estimated effort]
+  2. [...]
+
+Total estimated effort to fix: X hours
+
+Action Plan:
+  1. [Step-by-step plan to address blockers]
+  2. [...]
+  3. Re-run /done {id} for validation
+
+Increment remains: in-progress
+```
+
+---
+
+### Scope Creep Detection
+
+**If tasks.md has significantly more tasks than originally planned**:
+
+```
+🤔 PM Analysis: Scope creep detected
+
+Original plan: 42 tasks (estimated 3-4 weeks)
+Current state: 55 tasks (3 weeks elapsed)
+Reason: 13 tasks added during implementation
+
+Options:
+  A) Complete all 55 tasks (1 more week)
+  B) Move 13 new tasks to next increment (close now)
+  C) Re-plan as 2 increments (recommended)
+
+Recommendation: Option C - Split into two increments
+  • Increment {id}: Core features (42 tasks) - Close now
+  • Increment {id+1}: Enhancements (13 tasks) - New increment
+
+Create new increment for extra scope? [Y/n]
+```
+
+---
+
+### Configuration
+
+```yaml
+# .specweave/config.yaml
+increment_closure:
+  pm_validation:
+    enabled: true           # MUST be true
+    strict_mode: true       # Require all 3 gates
+
+  gates:
+    tasks:
+      require_p1_complete: true
+      require_p2_complete: false
+      allow_scope_transfer: true
+
+    tests:
+      require_all_passing: true
+      min_coverage: 80
+      allow_skipped: false
+
+    documentation:
+      require_claude_md: true
+      require_readme: true
+      require_changelog: true
+      allow_inline_only: false
+
+  scope_creep:
+    detect: true
+    max_additional_tasks: 10
+    auto_transfer: true
+```
+
+---
+
+### Best Practices
+
+1. **Never bypass validation** - All 3 gates must pass
+2. **Be specific in feedback** - Tell user exactly what's missing
+3. **Estimate effort** - Help user understand time to fix
+4. **Detect scope creep early** - Offer to transfer extra tasks
+5. **Document business value** - Summarize what was delivered
+
+---
+
 ## Summary
 
 The **PM Agent** is your AI Product Manager that:
@@ -745,6 +1030,7 @@ The **PM Agent** is your AI Product Manager that:
 ✅ Creates product roadmaps with timelines
 ✅ Translates technical decisions for stakeholders
 ✅ Defines measurable success metrics
+✅ **Validates increment closure with 3-gate check** (tasks, tests, docs)
 
 **User benefit**: Get expert product management guidance without hiring a PM. Make data-driven decisions about what to build, when, and why.