specweave 0.1.6 → 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)
 
@@ -101,6 +101,8 @@ specweave --help                   # Show help
 
 ## 🚀 Quick Example
 
+**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type them to activate the framework!
+
 ```bash
 # Initialize project - ALL components pre-installed!
 npx specweave init my-app
@@ -111,48 +113,55 @@ cd my-app
 # ✅ 35+ skills in .claude/skills/
 # ✅ 10 slash commands in .claude/commands/
 
-# Open Claude Code and start building:
+# Open Claude Code and use slash commands:
 
-User: "Create Next.js authentication with email and OAuth"
+User: /inc "Next.js authentication with email and OAuth"
     ↓
-SpecWeave: 🔷 SpecWeave Active
+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"
+User: "Create C4 context diagram for authentication"  # Regular conversation for implementation
     ↓
 SpecWeave: 🎨 Using diagrams-generator skill
            🤖 Coordinating with diagrams-architect agent
 
 ✅ Diagram saved: .specweave/docs/internal/architecture/diagrams/auth.c4-context.mmd
 
-User: "Implement authentication"
+User: "Implement authentication based on plan.md"  # Regular conversation
     ↓
-SpecWeave: 🤖 Orchestrating: PM → Architect → Backend → QA → Docs
+SpecWeave: 🤖 Implementing based on specifications
 
 ✅ Code: src/auth/
 ✅ Tests: tests/auth/
 ✅ Docs: Updated automatically
+
+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. `.specweave/` detected → `specweave-detector` activates automatically
-3. User request parsed → routed to appropriate pre-installed skills
-4. Skills coordinate agents → artifacts generated
-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.
 
 ---
 
 ## 🤖 Agents (10 Total - All Pre-Installed!)
 
-SpecWeave includes **10 specialized AI agents** that activate automatically based on your request:
+SpecWeave includes **10 specialized AI agents** that work with slash commands and during implementation:
 
 | Agent | Role | When It Activates |
 |-------|------|-------------------|
@@ -173,11 +182,11 @@ SpecWeave includes **10 specialized AI agents** that activate automatically base
 
 ## 🎯 Skills (35+ Total - All Pre-Installed!)
 
-SpecWeave includes **35+ AI skills** that activate automatically based on your request:
+SpecWeave includes **35+ AI skills** that work with slash commands:
 
 ### Core Framework Skills
-- **specweave-detector** - Auto-detect SpecWeave projects
-- **increment-planner** - Plan features and create specifications
+- **specweave-detector** - Slash command documentation
+- **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
@@ -281,22 +290,35 @@ specweave/
 
 ### For Greenfield Projects
 
+**IMPORTANT**: Use slash commands to activate SpecWeave!
+
 ```bash
 # 1. Create specifications (optional: comprehensive upfront or incremental)
 # Option A: Comprehensive (Enterprise) - 500-600+ pages upfront
 # Option B: Incremental (Startup) - Build as you go
 
-# 2. Create increment
-/create-increment "user authentication"
+# 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 auto-role routing
-"Implement user authentication"
-# SpecWeave orchestrates: PM → Architect → Backend → QA → Docs
+# 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
-"Create C4 context diagram for authentication"
+# 4. Validate quality (optional)
+/validate 0001 --quality
+# LLM-as-judge quality assessment
+
+# 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
 
-# 5. Sync with tools (optional)
+# 6. Sync with tools (optional)
 /sync-github  # Sync to GitHub issues
 ```
 
@@ -465,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

@@ -13,46 +13,66 @@ This file contains quick reference for developing with SpecWeave:
 
 ---
 
-## SpecWeave Auto-Routing (CRITICAL)
+## Using SpecWeave with Slash Commands (CRITICAL)
 
-**MANDATORY BEHAVIOR**: This project has SpecWeave installed (`.specweave/` directory exists).
+**IMPORTANT**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - no auto-activation, no proactive detection!
 
-### Auto-Detection & Routing Rules
+### How SpecWeave Works
 
-1. **ALWAYS check for SpecWeave FIRST** before responding to ANY user request
-2. **ROUTE ALL development-related questions** through `specweave-detector` skill
-3. **EVEN GENERIC questions** may need SpecWeave context (e.g., "Analyze BTC/USD" → suggest creating trading analysis feature)
+SpecWeave follows the **spec-kit approach**: You MUST use slash commands explicitly.
 
-### Detection Logic
+**To use SpecWeave**: Type a slash command (e.g., `/inc "Feature description"`)
 
-```javascript
-if (directoryExists('.specweave/config.yaml')) {
-  // SpecWeave is installed
-  // Route through specweave-detector for ALL development requests
-  activateSpecWeaveMode();
-}
-```
+### Quick Command Reference
+
+**Core Workflow** (4 commands):
+
+| Alias | Full Command | Purpose | Example |
+|-------|--------------|---------|---------|
+| `/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
 
-### Routing Examples
+```bash
+# 1. Initialize project
+npx specweave init my-saas
+
+# 2. Plan your first increment (use /inc - the ONLY alias!)
+/inc "User authentication with JWT and RBAC"
+
+# 3. Review generated docs
+#    spec.md, plan.md, tasks.md (auto-generated!), tests.md
 
-| User Request | Detection | Action |
-|-------------|-----------|--------|
-| "Create authentication" | Development request | ✅ Route to `specweave-detector` → `increment-planner` |
-| "Analyze BTC/USD prices" | Could be feature request | ✅ Route to `specweave-detector` → Suggest: "Create BTC analysis feature?" |
-| "Add payment processing" | Development request | ✅ Route to `specweave-detector` → `increment-planner` |
-| "Fix bug in login" | Development request | ✅ Route to `specweave-detector` → Load context → Implement |
-| "What's for lunch?" | Non-development | ❌ Respond normally (out of domain) |
+# 4. Build it (hooks run after EVERY task)
+/build 0001
 
-### Activation Behavior
+# 5. Validate quality (optional)
+/validate 0001 --quality
 
-**When SpecWeave is detected**:
-- ✅ Show indicator: `🔷 SpecWeave Active`
-- ✅ Route development requests automatically
-- ✅ Load context via `context-loader` when needed
-- ✅ Use appropriate agents (PM, Architect, DevOps, etc.)
-- ✅ Adapt to detected tech stack (TypeScript, Python, Go, etc.)
+# 6. Close when done (PM validates: tasks ✅ + tests ✅ + docs ✅)
+/done 0001
 
-**Rule**: When in doubt, route through SpecWeave. Let `specweave-detector` decide if it's a valid development request.
+# 7. Repeat for next feature
+/inc "Payment processing"
+```
+
+**Remember**: Type `/inc` first, THEN build! Otherwise you lose all SpecWeave benefits (specs, architecture, auto-generated tasks, test strategy).
 
 ---
 
@@ -177,24 +197,26 @@ npx specweave list --installed      # See what's installed
 
 ---
 
-## Quick Reference: Slash Commands
+## Quick Reference: Slash Commands (MUST USE!)
+
+**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` | `/ci` | Create new feature/increment | `/ci "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 (`/ci`, `/vi`, `/si`, `/done`, `/ls`, `/at`, `/init`) for speed during active development!
+| 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
 
@@ -229,8 +251,8 @@ npx specweave list --installed      # See what's installed
 
 | Skill | Purpose | Activates When |
 |-------|---------|----------------|
-| `specweave-detector` | Auto-detect SpecWeave projects | Any request in SpecWeave project |
-| `increment-planner` | Plan features with context | Creating/planning features |
+| `specweave-detector` | Slash command documentation | User asks about SpecWeave commands |
+| `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 |
@@ -288,9 +310,10 @@ backlog → planned → in-progress → completed → closed
 
 **Commands**:
 ```bash
-/create-increment "feature name"      # Create new increment (auto-numbered, e.g., 0003-feature-name)
-/add-tasks 0001 "task description"    # Add tasks to existing
-/close-increment 0001                 # Close with leftover transfer
+/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
@@ -661,8 +684,28 @@ Attempt 2/3: Refining with feedback...
 
 ---
 
-**Quick Start**: Run `/create-project` to initialize a new SpecWeave project
+**Quick Start**:
+
+**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS** - type `/inc` to activate!
+
+```bash
+# Initialize project
+npx specweave init my-project
+
+# Plan your first increment (use slash command!)
+/inc "feature description"
+
+# 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 `/inc` first to plan, THEN `/build` to implement! Otherwise you lose all SpecWeave benefits (specs, architecture, test strategy).
+
+**Need help?**: Type `/inc` to see examples, or ask about specific workflows.
 
-**Need help?**: Ask Claude to load the relevant guide from `.specweave/docs/internal/delivery/guides/`
+**SpecWeave Documentation**: https://spec-weave.com
 
 **Last Updated**: Auto-updated via `post-task-completion` hook

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave",
-  "version": "0.1.6",
-  "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.