specweave 0.6.8 → 0.7.1

package/plugins/specweave/commands/{increment.md → specweave-increment.md}

@@ -157,6 +157,234 @@ This step remains for auto-closing "in-progress" increments that ARE complete.
 - ✅ Enforces quality awareness (can't ignore incomplete work)
 - ✅ No manual `/done` needed when gates pass
 
+### Step 0C: Simplified WIP Enforcement (v0.7.0+ Redesigned)
+
+**NEW PHILOSOPHY: Default to 1 active increment (maximum focus), allow 2 only for emergencies.**
+
+After passing pre-flight checks (Step 0A, 0B), enforce WIP limits based on simplified config.
+
+**Implementation**:
+```typescript
+import { MetadataManager } from '../core/metadata-manager';
+import { ConfigManager } from '../core/config-manager';
+import { IncrementType } from '../core/types';
+
+// 1. Load config (defaults: maxActiveIncrements=1, hardCap=2, allowEmergencyInterrupt=true)
+const config = ConfigManager.load();
+const limits = config.limits || {
+  maxActiveIncrements: 1,
+  hardCap: 2,
+  allowEmergencyInterrupt: true,
+  typeBehaviors: {
+    canInterrupt: ['hotfix', 'bug']
+  }
+};
+
+// 2. Count active increments (NOT paused/completed/abandoned)
+const active = MetadataManager.getAllActive();
+const activeCount = active.length;
+
+// 3. Ask user for increment type (or detect from title)
+const incrementType = await promptForType(); // hotfix, feature, bug, change-request, refactor, experiment
+
+// 4. HARD CAP ENFORCEMENT (never >2 active)
+if (activeCount >= limits.hardCap) {
+  console.log(chalk.red.bold('\n❌ HARD CAP REACHED\n'));
+  console.log(chalk.red(`You have ${activeCount} active increments (absolute maximum: ${limits.hardCap})\n`));
+
+  console.log(chalk.yellow('Active increments:'));
+  active.forEach(inc => {
+    console.log(chalk.dim(`  • ${inc.id} [${inc.type}]`));
+  });
+
+  console.log(chalk.blue('\n💡 You MUST complete or pause existing work first:\n'));
+  console.log(chalk.white('1️⃣  Complete an increment:'));
+  console.log(chalk.dim('   /done <id>\n'));
+  console.log(chalk.white('2️⃣  Pause an increment:'));
+  console.log(chalk.dim('   /pause <id> --reason="..."\n'));
+  console.log(chalk.white('3️⃣  Check status:'));
+  console.log(chalk.dim('   /status\n'));
+
+  console.log(chalk.yellow('📝 Multiple hotfixes? Combine them into ONE increment!'));
+  console.log(chalk.dim('   Example: 0009-security-fixes (SQL + XSS + CSRF)\n'));
+
+  console.log(chalk.red.bold('⛔ This limit is enforced for your productivity.'));
+  console.log(chalk.dim('Research: 3+ concurrent tasks = 40% slower + more bugs\n'));
+
+  // NO force override at hard cap - absolute maximum
+  process.exit(1);
+}
+
+// 5. SOFT ENFORCEMENT (activeCount >= maxActiveIncrements)
+if (activeCount >= limits.maxActiveIncrements) {
+  const canInterrupt = limits.typeBehaviors?.canInterrupt || ['hotfix', 'bug'];
+  const isEmergency = canInterrupt.includes(incrementType);
+
+  if (isEmergency && limits.allowEmergencyInterrupt) {
+    // ✅ ALLOW - Emergency interrupt
+    console.log(chalk.yellow.bold('\n⚠️  EMERGENCY INTERRUPT\n'));
+    console.log(chalk.yellow(`Starting ${incrementType} increment (emergency exception allowed)\n`));
+    console.log(chalk.dim('You have 1 active increment. This will be your 2nd (emergency ceiling).\n'));
+
+    console.log(chalk.blue('📋 Active increments:'));
+    active.forEach(inc => {
+      console.log(chalk.dim(`  • ${inc.id} [${inc.type}]`));
+    });
+
+    console.log(chalk.yellow('\n💡 Recommendation: After emergency, complete or pause it before resuming normal work.\n'));
+
+    // Continue to Step 1
+  } else {
+    // ❌ SOFT BLOCK - Warn and offer options
+    console.log(chalk.yellow.bold('\n⚠️  WIP LIMIT REACHED\n'));
+    console.log(chalk.yellow(`You have ${activeCount} active increment(s) (recommended limit: ${limits.maxActiveIncrements})\n`));
+
+    console.log(chalk.yellow('Active increments:'));
+    active.forEach(inc => {
+      console.log(chalk.dim(`  • ${inc.id} [${inc.type}]`));
+    });
+
+    console.log(chalk.dim('\n🧠 Focus Principle: ONE active increment = maximum productivity'));
+    console.log(chalk.dim('Starting a 2nd increment reduces focus and velocity.\n'));
+
+    console.log(chalk.blue('💡 What would you like to do?\n'));
+    console.log(chalk.white('1️⃣  Complete current work (recommended)'));
+    console.log(chalk.dim('   Finish active increment before starting new\n'));
+    console.log(chalk.white('2️⃣  Pause current work'));
+    console.log(chalk.dim('   Pause active increment to focus on new work\n'));
+    console.log(chalk.white('3️⃣  Start 2nd increment anyway'));
+    console.log(chalk.dim('   Accept productivity cost (20% slower)\n'));
+
+    const choice = await prompt({
+      type: 'list',
+      message: 'Choose an option:',
+      choices: [
+        { name: 'Complete current work', value: 'complete' },
+        { name: 'Pause current work', value: 'pause' },
+        { name: 'Start 2nd increment anyway', value: 'continue' }
+      ]
+    });
+
+    if (choice === 'complete') {
+      console.log(chalk.green('\n✅ Smart choice! Finish current work first.\n'));
+      console.log(chalk.dim('Use /do to continue work\n'));
+      process.exit(0);
+    } else if (choice === 'pause') {
+      console.log(chalk.blue('\n⏸️  Pausing current increment...\n'));
+      const pauseReason = await prompt({
+        type: 'input',
+        message: 'Reason for pausing:',
+        default: 'Paused to start new work'
+      });
+
+      for (const inc of active) {
+        await MetadataManager.pause(inc.id, pauseReason);
+        console.log(chalk.green(`✅ Paused ${inc.id}`));
+      }
+      console.log(chalk.green('\n✅ Proceeding with new increment...\n'));
+    } else {
+      // choice === 'continue'
+      console.log(chalk.yellow('\n⚠️  Starting 2nd increment (20% productivity cost)\n'));
+      console.log(chalk.dim('Research: Context switching reduces velocity significantly.\n'));
+    }
+  }
+}
+
+// 6. If activeCount < maxActiveIncrements, no warnings - proceed directly
+if (activeCount === 0) {
+  console.log(chalk.green('✅ No active increments. Starting fresh!\n'));
+}
+
+// Proceed to Step 1 (find next increment number)
+```
+
+**Example Output - Hard Cap (2 active)**:
+```
+❌ HARD CAP REACHED
+
+You have 2 active increments (absolute maximum: 2)
+
+Active increments:
+  • 0005-authentication [feature]
+  • 0006-security-hotfix [hotfix]
+
+💡 You MUST complete or pause existing work first:
+
+1️⃣  Complete an increment:
+   /done <id>
+
+2️⃣  Pause an increment:
+   /pause <id> --reason="..."
+
+3️⃣  Check status:
+   /status
+
+📝 Multiple hotfixes? Combine them into ONE increment!
+   Example: 0009-security-fixes (SQL + XSS + CSRF)
+
+⛔ This limit is enforced for your productivity.
+Research: 3+ concurrent tasks = 40% slower + more bugs
+```
+
+**Example Output - Soft Warning (1 active, starting 2nd)**:
+```
+⚠️  WIP LIMIT REACHED
+
+You have 1 active increment(s) (recommended limit: 1)
+
+Active increments:
+  • 0005-authentication [feature]
+
+🧠 Focus Principle: ONE active increment = maximum productivity
+Starting a 2nd increment reduces focus and velocity.
+
+💡 What would you like to do?
+
+1️⃣  Complete current work (recommended)
+   Finish active increment before starting new
+
+2️⃣  Pause current work
+   Pause active increment to focus on new work
+
+3️⃣  Start 2nd increment anyway
+   Accept productivity cost (20% slower)
+
+Choose an option: 1
+
+✅ Smart choice! Finish current work first.
+
+Use /do to continue work
+```
+
+**Example Output - Emergency Interrupt (hotfix)**:
+```
+⚠️  EMERGENCY INTERRUPT
+
+Starting hotfix increment (emergency exception allowed)
+
+You have 1 active increment. This will be your 2nd (emergency ceiling).
+
+📋 Active increments:
+  • 0005-authentication [feature]
+
+💡 Recommendation: After emergency, complete or pause it before resuming normal work.
+
+Proceeding with hotfix 0006...
+```
+
+**Type-Based Limits** (from `TYPE_LIMITS` in `increment-metadata.ts`):
+- **Hotfix**: Unlimited (critical production fixes)
+- **Bug**: Unlimited (production bugs need immediate attention)
+- **Feature**: Max 2 active (standard development)
+- **Change Request**: Max 2 active (stakeholder requests)
+- **Refactor**: Max 1 active (requires focus)
+- **Experiment**: Unlimited (POCs, spikes)
+
+**Bypassing Warnings** (not recommended):
+- Users can answer "yes" to continue anyway
+- Hotfixes and bugs bypass context switching warnings (emergency work)
+- Use sparingly - discipline exists for a reason!
+
 ### Step 1: Find next increment number
 
 - Scan `.specweave/increments/` directory
@@ -317,10 +545,9 @@ After the increment-planner skill completes, verify:
    - `.specweave/docs/internal/architecture/adr/` has ADRs
 
 2. **Increment files created:**
-   - `.specweave/increments/####-name/spec.md` (references strategy docs)
-   - `.specweave/increments/####-name/plan.md` (references architecture docs)
-   - `.specweave/increments/####-name/tasks.md` (auto-generated from plan)
-   - `.specweave/increments/####-name/tests.md` (test strategy)
+   - `.specweave/increments/####-name/spec.md` (references strategy docs, AC-IDs)
+   - `.specweave/increments/####-name/plan.md` (references architecture docs, test strategy)
+   - `.specweave/increments/####-name/tasks.md` (implementation + embedded tests in BDD format, v0.7.0+)
    - `.specweave/increments/####-name/context-manifest.yaml`
 
 3. **Hooks executed:**

package/plugins/specweave/commands/specweave-pause.md

@@ -0,0 +1,189 @@
+---
+name: pause
+description: Pause an active increment (blocked by external dependency, deprioritized)
+usage: /specweave:pause <increment-id> --reason="<reason>"
+---
+
+# Pause Increment Command
+
+**Usage**: `/specweave:pause <increment-id> --reason="<reason>"`
+
+---
+
+## Purpose
+
+Pause an active increment when:
+- **Blocked** by external dependency (API keys, approvals, reviews)
+- **Waiting** for another increment to complete
+- **Deprioritized** (will return to later)
+- **Needs discussion** before continuing
+
+---
+
+## Behavior
+
+1. **Validates** increment exists and is "active"
+2. **Prompts** for reason if not provided via --reason flag
+3. **Updates** metadata.json:
+   - `status`: "active" → "paused"
+   - `pausedReason`: User-provided reason
+   - `pausedAt`: Current timestamp
+4. **Displays** confirmation message
+5. **Suggests** next actions (/resume to continue)
+
+---
+
+## Examples
+
+### Pause with reason
+```bash
+/pause 0006 --reason="Waiting for Stripe API keys"
+
+✅ Increment 0006 paused
+📝 Reason: Waiting for Stripe API keys
+⏸️  No longer counts toward active limit
+💡 Resume with: /resume 0006
+```
+
+### Pause without reason (prompts)
+```bash
+/pause 0006
+
+❓ Why are you pausing this increment?
+   1. Blocked by external dependency
+   2. Waiting for code review
+   3. Deprioritized
+   4. Other (type reason)
+
+> 1
+
+✅ Increment 0006 paused
+📝 Reason: Blocked by external dependency
+💡 Resume with: /resume 0006
+```
+
+---
+
+## Edge Cases
+
+### Already Paused
+```bash
+/pause 0006 --reason="Different reason"
+
+⚠️  Increment 0006 is already paused
+   Previous reason: Waiting for Stripe API keys
+   New reason: Different reason
+
+Update reason? [Y/n]: y
+
+✅ Reason updated
+📝 New reason: Different reason
+```
+
+### Cannot Pause Completed
+```bash
+/pause 0005
+
+❌ Cannot pause increment 0005
+   Status: completed
+   Completed increments cannot be paused
+```
+
+### Cannot Pause Abandoned
+```bash
+/pause 0008
+
+❌ Cannot pause increment 0008
+   Status: abandoned
+   Resume it first: /resume 0008
+```
+
+### Increment Not Found
+```bash
+/pause 9999
+
+❌ Increment not found: 9999
+💡 Check available increments: /status
+```
+
+---
+
+## Implementation
+
+This command uses the MetadataManager to update increment status:
+
+```typescript
+import { MetadataManager, IncrementStatus } from '../src/core/increment/metadata-manager';
+
+// Read current metadata
+const metadata = MetadataManager.read(incrementId);
+
+// Validate can pause
+if (metadata.status !== IncrementStatus.ACTIVE) {
+  throw new Error(`Cannot pause increment with status: ${metadata.status}`);
+}
+
+// Update status
+MetadataManager.updateStatus(incrementId, IncrementStatus.PAUSED, reason);
+```
+
+---
+
+## Status Flow
+
+```
+active ──pause──> paused
+   │
+   └──resume──> active
+```
+
+---
+
+## Related Commands
+
+- `/resume <id>` - Resume paused increment
+- `/abandon <id>` - Abandon increment (permanent)
+- `/status` - Show all increment statuses
+
+---
+
+## Best Practices
+
+✅ **Always provide a reason** - Helps future you remember context
+
+✅ **Review paused increments weekly** - Don't let them pile up
+
+✅ **Set calendar reminder** - For external blockers (API keys, approvals)
+
+✅ **Resume or abandon** - After 7+ days paused
+
+❌ **Don't pause as procrastination** - Address scope/motivation issues instead
+
+❌ **Don't pause to start new work** - Finish current work first (focus)
+
+---
+
+## Warning: Stale Paused Increments
+
+Increments paused for **7+ days** trigger warnings in `/status`:
+
+```bash
+/status
+
+⏸️  Paused (1):
+  🔄 0007-stripe-integration [feature]
+     Paused: 10 days ago
+     Reason: Waiting for Stripe API keys
+     ⚠️  STALE! Review or abandon?
+
+💡 Actions:
+   /resume 0007  # If unblocked
+   /abandon 0007 # If no longer needed
+```
+
+---
+
+**Command**: `/specweave:pause` (or `/pause`)
+**Plugin**: specweave (core)
+**Version**: v0.7.0+
+**Part of**: Increment 0007 - Smart Status Management

package/plugins/specweave/commands/specweave-qa.md

@@ -0,0 +1,245 @@
+---
+name: qa
+description: Run quality assessment on a SpecWeave increment with risk scoring and quality gate decisions
+---
+
+# /qa - Quality Assessment Command
+
+**IMPORTANT**: You MUST invoke the CLI `specweave qa` command using the Bash tool. The slash command provides guidance and orchestration only.
+
+## Purpose
+
+Run comprehensive quality assessment on an increment using:
+- ✅ Rule-based validation (120 checks)
+- ✅ AI quality assessment (7 dimensions including risk)
+- ✅ BMAD risk scoring (Probability × Impact)
+- ✅ Quality gate decisions (PASS/CONCERNS/FAIL)
+
+## Usage
+
+```bash
+/qa <increment-id> [options]
+```
+
+### Examples
+
+```bash
+# Quick mode (default)
+/qa 0008
+
+# Pre-implementation check
+/qa 0008 --pre
+
+# Quality gate check (comprehensive)
+/qa 0008 --gate
+
+# Export blockers to tasks.md
+/qa 0008 --export
+
+# CI mode (exit 1 on FAIL)
+/qa 0008 --ci
+
+# Skip AI assessment (rule-based only)
+/qa 0008 --no-ai
+
+# Force run even if rule-based fails
+/qa 0008 --force
+```
+
+### Options
+
+- `--quick` - Quick mode (default) - Fast assessment with core checks
+- `--pre` - Pre-implementation mode - Check before starting work
+- `--gate` - Quality gate mode - Comprehensive check before closing
+- `--full` - Full multi-agent mode (Phase 3, v0.9.0+)
+- `--ci` - CI mode - Exit 1 on FAIL (for automation)
+- `--no-ai` - Skip AI assessment - Rule-based validation only (free, fast)
+- `--export` - Export blockers/concerns to tasks.md
+- `--force` - Force run even if rule-based validation fails
+- `-v, --verbose` - Show recommendations in addition to blockers/concerns
+
+## What It Does
+
+### Step 1: Rule-Based Validation (Always First, Always Free)
+
+The command runs 120+ validation checks on increment files:
+- ✅ File existence (spec.md, plan.md, tasks.md)
+- ✅ YAML frontmatter structure
+- ✅ AC-ID traceability (spec.md → tasks.md)
+- ✅ Link integrity
+- ✅ Format consistency
+
+**If rule-based fails** → Stop (don't waste AI tokens) unless `--force` flag used
+
+### Step 2: AI Quality Assessment (Optional, skip with `--no-ai`)
+
+Invoke the `increment-quality-judge-v2` skill to evaluate:
+- **7 Dimensions**:
+  1. Clarity (18% weight)
+  2. Testability (22% weight)
+  3. Completeness (18% weight)
+  4. Feasibility (13% weight)
+  5. Maintainability (9% weight)
+  6. Edge Cases (9% weight)
+  7. **Risk Assessment (11% weight)**
+
+**Risk Assessment** uses BMAD pattern:
+- Probability (0.0-1.0) × Impact (1-10) = Risk Score (0.0-10.0)
+- 4 categories: Security, Technical, Implementation, Operational
+- Severity: CRITICAL (≥9.0), HIGH (6.0-8.9), MEDIUM (3.0-5.9), LOW (<3.0)
+
+### Step 3: Quality Gate Decision
+
+Based on thresholds:
+
+**FAIL** if any:
+- Risk score ≥ 9.0 (CRITICAL)
+- Test coverage < 60%
+- Spec quality < 50
+- Critical security vulnerabilities ≥ 1
+
+**CONCERNS** if any:
+- Risk score 6.0-8.9 (HIGH)
+- Test coverage < 80%
+- Spec quality < 70
+- High security vulnerabilities ≥ 1
+
+**PASS** otherwise
+
+### Step 4: Display Report
+
+Show results with:
+- 🟢 PASS / 🟡 CONCERNS / 🔴 FAIL decision
+- Blockers (MUST fix)
+- Concerns (SHOULD fix)
+- Recommendations (NICE to fix, with `--verbose`)
+- Spec quality scores (7 dimensions)
+- Summary (duration, tokens, cost)
+
+### Step 5: Export (Optional)
+
+If `--export` flag provided:
+- Append blockers/concerns to tasks.md
+- Add priority (P0 for blockers, P1 for concerns)
+- Include mitigation strategies
+
+## Implementation
+
+**When user runs `/qa <increment-id>`**:
+
+1. **Parse arguments**
+   ```typescript
+   const incrementId = args[0]; // e.g., "0008"
+   const options = parseOptions(args.slice(1));
+   ```
+
+2. **Invoke CLI command via Bash tool**
+   ```bash
+   specweave qa 0008 --pre --export
+   ```
+
+3. **CLI handles everything**:
+   - Rule-based validation
+   - AI assessment invocation
+   - Quality gate decision
+   - Report display
+   - Export to tasks.md
+
+4. **Return result to user**
+   - Show CLI output (already formatted)
+   - Suggest next steps based on decision
+
+## Modes Explained
+
+### Quick Mode (Default)
+
+**Use when**: Quick check during development
+**Checks**: Rule-based + AI spec quality + risk assessment
+**Time**: ~30 seconds
+**Cost**: ~$0.025-$0.050
+
+### Pre-Implementation Mode (`--pre`)
+
+**Use when**: Before starting increment work
+**Checks**: All quick mode checks + architecture review
+**Time**: ~1 minute
+**Cost**: ~$0.05-$0.10
+
+### Quality Gate Mode (`--gate`)
+
+**Use when**: Before closing increment (via `/specweave:done`)
+**Checks**: All pre-implementation checks + test coverage + security audit
+**Time**: ~2-3 minutes
+**Cost**: ~$0.10-$0.20
+
+### Full Multi-Agent Mode (`--full`, Phase 3)
+
+**Use when**: Comprehensive audit for critical increments
+**Checks**: 6 specialized subagents in parallel
+**Time**: ~5 minutes
+**Cost**: ~$0.50-$1.00
+
+## Cost Breakdown
+
+| Mode | Tokens | Cost (USD) | Time |
+|------|--------|------------|------|
+| Quick | ~2,500 | ~$0.025 | 30s |
+| Pre | ~5,000 | ~$0.050 | 1m |
+| Gate | ~10,000 | ~$0.100 | 2-3m |
+| Full | ~50,000 | ~$0.500 | 5m |
+
+**Optimization**: Use Haiku model by default (cheapest, fastest)
+
+## Exit Codes (for CI)
+
+When `--ci` flag used:
+- **Exit 0**: PASS or CONCERNS (warning, but not blocking)
+- **Exit 1**: FAIL (blocking issues found)
+
+**CI Integration Example**:
+```yaml
+# .github/workflows/qa-check.yml
+- name: Run QA Check
+  run: specweave qa ${{ env.INCREMENT_ID }} --gate --ci
+```
+
+## Error Handling
+
+**Common errors**:
+- ❌ Increment not found → Check ID format (4 digits: 0001, 0008)
+- ❌ Missing files → Run `/specweave:inc` to create increment first
+- ❌ Rule-based fails → Fix validation errors before AI assessment
+- ❌ AI timeout → Retry with `--quick` mode or `--no-ai`
+
+## Integration Points
+
+**Auto-invoked by**:
+- `/specweave:done` - Runs `--gate` mode before closing increment
+- Post-task-completion hook (optional) - Runs `--quick` mode after tasks complete
+
+**Manual invocation**:
+- During development - `/qa 0008` for quick checks
+- Before commit - `/qa 0008 --pre` to catch issues early
+- Before PR - `/qa 0008 --gate --export` for comprehensive check
+
+## Best Practices
+
+1. **Run early and often** - Use `--quick` during development
+2. **Fix blockers immediately** - Don't proceed with FAIL decision
+3. **Address concerns before release** - CONCERNS = should fix
+4. **Use risk scores to prioritize** - Fix CRITICAL (≥9.0) risks first
+5. **Export to tasks.md** - Convert blockers/concerns to actionable tasks
+6. **CI integration** - Block PRs with FAIL decision
+
+## Related
+
+- **Skill**: `increment-quality-judge-v2` (7 dimensions with risk assessment)
+- **Command**: `/specweave:done` (auto-runs QA gate)
+- **CLI**: `specweave qa` (direct invocation)
+- **Types**: `src/core/qa/types.ts` (TypeScript definitions)
+- **Tests**: `tests/unit/qa/` (58 test cases, 100% passing)
+
+## Example Session
+
+```
+User: /qa 0008