specweave 0.23.18 → 0.24.0

package/plugins/specweave/commands/specweave-embed-acs.md

@@ -0,0 +1,446 @@
+---
+name: specweave:embed-acs
+description: Auto-embed Acceptance Criteria from living docs into increment spec.md for hook compatibility
+---
+
+# Embed Acceptance Criteria from Living Docs
+
+You are helping the user embed Acceptance Criteria from living documentation into increment spec.md.
+
+## Context
+
+**Problem**: The AC sync hook requires ACs to be in spec.md, but some increments use `structure: user-stories` which references external living docs without embedding ACs inline.
+
+**Solution**: This command auto-embeds ACs from living docs into spec.md, ensuring sync hooks work correctly.
+
+**Architecture**: spec.md is ALWAYS the source of truth for ACs, even when living docs exist as a documentation layer. (See ADR-0062)
+
+## Usage
+
+```bash
+/specweave:embed-acs <increment-id>
+```
+
+## Arguments
+
+- `<increment-id>`: Required. Increment ID (e.g., "0050", "50", "0050-feature-name")
+
+## Workflow
+
+### Step 1: Parse and Validate Arguments
+
+1. **Extract increment ID**:
+   - Parse from command: `/specweave:embed-acs 0050` → "0050"
+   - Normalize to 4-digit format: "0050"
+   - Support formats: "50", "0050", "0050-feature-name"
+
+2. **Validate increment exists**:
+   - List directories in `.specweave/increments/`
+   - Find matching increment (e.g., `0050-external-tool-import-phase-1b-7`)
+   - If not found: Show error with available increments
+
+**Example output if not found**:
+```
+❌ Error: Increment 0050 not found
+
+Available increments:
+  • 0048-external-tool-import-enhancement
+  • 0049-cli-first-init-flow
+
+Usage: /specweave:embed-acs <increment-id>
+```
+
+### Step 2: Validate Increment Structure
+
+1. **Check spec.md exists**:
+   ```bash
+   ls .specweave/increments/0050-*/spec.md
+   ```
+
+2. **Check for `structure: user-stories` in frontmatter**:
+   ```bash
+   grep "structure: user-stories" spec.md
+   ```
+
+3. **If NOT using living docs structure**:
+   ```
+   ℹ️  Info: Increment 0050 does not use 'structure: user-stories'
+
+   This command is intended for increments that reference external living docs.
+   For standard increments, ACs should already be in spec.md.
+
+   Do you want to proceed anyway? [Y/n]:
+   ```
+
+### Step 3: Find Living Docs Path
+
+1. **Extract feature_id from spec.md frontmatter**:
+   ```bash
+   grep "feature_id:" spec.md | cut -d: -f2 | tr -d ' '
+   ```
+
+2. **Construct living docs path**:
+   ```
+   .specweave/docs/internal/specs/specweave/{feature_id}/
+   ```
+
+3. **Validate living docs path exists**:
+   ```bash
+   ls .specweave/docs/internal/specs/specweave/FS-048/
+   ```
+
+4. **If living docs not found**:
+   ```
+   ❌ Error: Living docs not found for feature FS-048
+
+   Expected path: .specweave/docs/internal/specs/specweave/FS-048/
+   Actual path: Not found
+
+   This increment may not have living docs, or they're in a different location.
+
+   Please specify living docs path manually:
+     /specweave:embed-acs 0050 --living-docs-path <path>
+   ```
+
+### Step 4: Extract User Stories from spec.md
+
+1. **Read user_stories from frontmatter**:
+   ```yaml
+   user_stories:
+     - US-001
+     - US-002
+     - US-004
+   ```
+
+2. **Display user stories to embed**:
+   ```
+   Found 7 user stories in spec.md frontmatter:
+     • US-001: Smart Pagination During Init
+     • US-002: CLI-First Defaults
+     • US-004: Smart Caching with TTL
+     • US-005: Dedicated Import Commands
+     • US-006: ADO Area Path Mapping
+     • US-007: Progress Tracking
+     • US-008: Smart Filtering
+   ```
+
+### Step 5: Extract ACs from Living Docs
+
+1. **For each user story**, find corresponding file:
+   ```bash
+   # Try multiple file naming patterns
+   find .specweave/docs/internal/specs/specweave/FS-048/ -name "us-001-*.md"
+   find .specweave/docs/internal/specs/specweave/FS-048/ -name "US-001.md"
+   ```
+
+2. **Extract ACs from each file**:
+   ```bash
+   grep -E "^### AC-US[0-9]+-[0-9]+:" us-001-smart-pagination-during-init.md
+   ```
+
+3. **Display extraction progress**:
+   ```
+   Extracting ACs from living docs...
+     ✓ US-001: Found 5 ACs (AC-US1-01 to AC-US1-05)
+     ✓ US-002: Found 4 ACs (AC-US2-01 to AC-US2-04)
+     ✓ US-004: Found 5 ACs (AC-US4-01 to AC-US4-05)
+     ✓ US-005: Found 7 ACs (AC-US5-01 to AC-US5-07)
+     ✓ US-006: Found 6 ACs (AC-US6-01 to AC-US6-06)
+     ✓ US-007: Found 6 ACs (AC-US7-01 to AC-US7-06)
+     ✓ US-008: Found 6 ACs (AC-US8-01 to AC-US8-06)
+
+   Total: 39 Acceptance Criteria extracted
+   ```
+
+### Step 6: Check for Existing ACs
+
+1. **Check if spec.md already has AC section**:
+   ```bash
+   grep -q "## Acceptance Criteria" spec.md
+   ```
+
+2. **If ACs already exist**:
+   ```
+   ⚠️  Warning: spec.md already contains Acceptance Criteria section
+
+   Found 39 existing ACs in spec.md.
+
+   What would you like to do?
+     [R] Replace existing ACs with freshly embedded ones
+     [M] Merge (keep existing + add missing)
+     [C] Cancel
+
+   Choice:
+   ```
+
+3. **If user chooses "Replace"**: Remove old AC section, add new one
+4. **If user chooses "Merge"**: Smart merge (add only missing ACs)
+5. **If user chooses "Cancel"**: Exit without changes
+
+### Step 7: Format and Embed ACs
+
+1. **Format ACs as markdown**:
+   ```markdown
+   ## Acceptance Criteria
+
+   <!-- Auto-synced from living docs -->
+
+   ### US-001: Smart Pagination During Init
+
+   - [ ] **AC-US1-01**: 50-Project Limit During Init
+   - [ ] **AC-US1-02**: Explicit Choice Prompt
+   - [ ] **AC-US1-03**: Async Fetch for "Import All"
+   - [ ] **AC-US1-04**: Init Completes < 30 Seconds
+   - [ ] **AC-US1-05**: No Timeout Errors
+
+   ### US-002: CLI-First Defaults
+
+   - [ ] **AC-US2-01**: "Import All" as Default Choice
+   - [ ] **AC-US2-02**: All Projects Checked in Checkbox Mode
+   - [ ] **AC-US2-03**: Clear Deselection Instructions
+   - [ ] **AC-US2-04**: Easy Override for "Select None"
+
+   ...
+   ```
+
+2. **Find insertion point in spec.md**:
+   - After "## Implementation Summary" section, OR
+   - Before final line if no summary section
+
+3. **Use Edit tool to insert ACs**:
+   ```typescript
+   Edit({
+     file_path: "spec.md",
+     old_string: "**See**: [plan.md](./plan.md)...",
+     new_string: "**See**: [plan.md](./plan.md)...\n\n---\n\n" + acMarkdown
+   });
+   ```
+
+### Step 8: Update metadata.json
+
+1. **Count total ACs**:
+   ```bash
+   grep -cE "^- \[ \] \*\*AC-US[0-9]+-[0-9]+\*\*:" spec.md
+   ```
+
+2. **Update metadata.json**:
+   ```json
+   {
+     "total_acs": 39,
+     "completed_acs": 0
+   }
+   ```
+
+3. **Use Edit tool to update**:
+   ```typescript
+   Edit({
+     file_path: "metadata.json",
+     old_string: '"total_acs": 32,',
+     new_string: '"total_acs": 39,'
+   });
+   ```
+
+### Step 9: Validate Embedding
+
+1. **Re-count ACs in spec.md**:
+   ```bash
+   grep -cE "^- \[[x ]\] \*\*AC-US[0-9]+-[0-9]+\*\*:" spec.md
+   ```
+
+2. **Validate format**:
+   - All ACs follow pattern: `- [ ] **AC-US1-01**: Title`
+   - No duplicate AC IDs
+   - All user stories represented
+
+3. **Display validation results**:
+   ```
+   ✅ Validation: PASSED
+
+   Embedded 39 Acceptance Criteria into spec.md:
+     • US-001: 5 ACs
+     • US-002: 4 ACs
+     • US-004: 5 ACs
+     • US-005: 7 ACs
+     • US-006: 6 ACs
+     • US-007: 6 ACs
+     • US-008: 6 ACs
+
+   metadata.json updated: total_acs = 39
+
+   Next steps:
+     1. Review embedded ACs in spec.md
+     2. Run: /specweave:validate 0050
+     3. Start work: /specweave:do
+   ```
+
+## Flags (Optional)
+
+### `--living-docs-path <path>`
+
+Manually specify living docs path if auto-detection fails:
+
+```bash
+/specweave:embed-acs 0050 --living-docs-path .specweave/docs/internal/specs/specweave/FS-048
+```
+
+### `--dry-run`
+
+Preview what would be embedded without modifying files:
+
+```bash
+/specweave:embed-acs 0050 --dry-run
+```
+
+**Output**:
+```
+[DRY RUN] Would embed 39 ACs into spec.md
+
+Preview:
+  • US-001: 5 ACs (AC-US1-01 to AC-US1-05)
+  • US-002: 4 ACs (AC-US2-01 to AC-US2-04)
+  ...
+
+No files modified.
+```
+
+### `--force`
+
+Skip confirmation prompts:
+
+```bash
+/specweave:embed-acs 0050 --force
+```
+
+## Error Handling
+
+### Living Docs Not Found
+```
+❌ Error: Living docs not found for feature FS-048
+
+Expected: .specweave/docs/internal/specs/specweave/FS-048/
+Found: Directory does not exist
+
+Possible solutions:
+  1. Check if feature_id in spec.md is correct
+  2. Manually specify path: --living-docs-path <path>
+  3. Create living docs first: /specweave:sync-docs
+```
+
+### No User Stories in spec.md
+```
+❌ Error: No user_stories field in spec.md frontmatter
+
+This command requires user_stories to be listed in spec.md.
+
+Add to spec.md frontmatter:
+  user_stories:
+    - US-001
+    - US-002
+    ...
+```
+
+### User Story File Not Found
+```
+⚠️  Warning: User story file not found for US-003
+
+Expected paths tried:
+  • .specweave/docs/internal/specs/specweave/FS-048/us-003.md
+  • .specweave/docs/internal/specs/specweave/FS-048/US-003.md
+  • .specweave/docs/internal/specs/specweave/FS-048/us-003-*.md
+
+Continuing with remaining user stories...
+```
+
+### No ACs Found in User Story
+```
+⚠️  Warning: No ACs found in US-005 file
+
+File: .specweave/docs/internal/specs/specweave/FS-048/us-005-dedicated-import-commands.md
+
+This file may be incomplete or use a different AC format.
+Skipping US-005 for now.
+```
+
+## Integration with Other Commands
+
+This command is referenced by:
+
+1. **`/specweave:validate`**: Suggests running `/specweave:embed-acs` when ACs are missing
+2. **`/specweave:do`**: Pre-start hook suggests this command if validation fails
+3. **`/specweave:increment`**: Should auto-call this when creating `structure: user-stories` increments
+
+## Examples
+
+### Example 1: Basic Usage
+
+```bash
+/specweave:embed-acs 0050
+```
+
+**Output**:
+```
+Embedding ACs from living docs for increment 0050-external-tool-import-phase-1b-7...
+
+Living docs path: .specweave/docs/internal/specs/specweave/FS-048/
+
+Extracting ACs...
+  ✓ US-001: 5 ACs
+  ✓ US-002: 4 ACs
+  ✓ US-004: 5 ACs
+  ✓ US-005: 7 ACs
+  ✓ US-006: 6 ACs
+  ✓ US-007: 6 ACs
+  ✓ US-008: 6 ACs
+
+✅ Embedded 39 ACs into spec.md
+✅ Updated metadata.json (total_acs: 39)
+```
+
+### Example 2: Dry Run
+
+```bash
+/specweave:embed-acs 0050 --dry-run
+```
+
+**Output**:
+```
+[DRY RUN] Embedding ACs for increment 0050...
+
+Would extract 39 ACs from 7 user stories.
+No files would be modified.
+
+To apply changes, run without --dry-run flag.
+```
+
+### Example 3: Manual Path
+
+```bash
+/specweave:embed-acs 0050 --living-docs-path .specweave/docs/internal/specs/custom/FS-048
+```
+
+**Output**:
+```
+Using custom living docs path: .specweave/docs/internal/specs/custom/FS-048
+
+Extracting ACs...
+  ✓ US-001: 5 ACs
+  ...
+```
+
+## Related Commands
+
+- `/specweave:increment`: Create new increment (should auto-embed ACs)
+- `/specweave:validate`: Validate increment (checks AC presence)
+- `/specweave:do`: Start increment (pre-start hook validates ACs)
+- `/specweave:sync-docs`: Sync living documentation
+
+## Related Documentation
+
+- **ADR-0062**: AC Embedding Architecture
+- **CLAUDE.md**: Rule #X (spec.md AC presence requirement)
+- **src/utils/ac-embedder.ts**: AC embedding utility (implementation)
+- **src/core/validators/ac-presence-validator.ts**: AC presence validation
+
+---
+
+**Important**: This command should NOT be needed in the future if spec generators are updated to auto-embed ACs during increment creation. Consider this a **migration/fix utility** for existing increments.

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

@@ -199,6 +199,32 @@ Increment 0001-user-authentication is complete!
 
 🎉 Increment 0001 closed successfully!
 
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔍 POST-CLOSURE QUALITY ASSESSMENT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Running quality assessment to validate implementation...
+
+/specweave:qa 0001
+
+Overall Score: 87/100 (GOOD) ✓
+
+Dimension Scores:
+  Clarity:         92/100 ✓✓
+  Testability:     85/100 ✓
+  Completeness:    90/100 ✓✓
+  Feasibility:     88/100 ✓✓
+  Maintainability: 85/100 ✓
+  Edge Cases:      78/100 ✓
+  Risk Assessment: 75/100 ✓
+
+Quality Gate Decision: ✅ PASS
+
+📋 Quality report saved:
+   .specweave/increments/0001-user-authentication/reports/qa-post-closure.md
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
 Proceeding to suggest next work...
 ```
 
@@ -237,6 +263,106 @@ What would you like to do? [A/B/C]
 
 **🔥 CRITICAL**: NEVER auto-close with incomplete work! Always give user control.
 
+### Step 3.5: Post-Closure Quality Assessment (NEW - v0.24.0+)
+
+**🎯 MANDATORY**: After successful closure, automatically run quality assessment to validate implementation quality.
+
+**Why This Step Matters**:
+- PM validation (Step 2) checks **structural completion** (tasks done, tests pass, docs updated)
+- Quality assessment checks **implementation quality** (code quality, architecture, risks)
+- Provides retrospective learning and continuous improvement
+- Identifies technical debt and areas for future enhancement
+
+**Implementation**:
+
+1. **Invoke QA command automatically**:
+   ```bash
+   /specweave:qa ${incrementId}
+   ```
+
+2. **Quality assessment evaluates**:
+   - **7 dimensions**: Clarity, Testability, Completeness, Feasibility, Maintainability, Edge Cases, Risk
+   - **BMAD risk scoring**: Probability × Impact (0-10 scale)
+   - **Quality gate decision**: PASS/CONCERNS/FAIL
+   - **Security vulnerabilities**: OWASP-based checks
+   - **Architecture quality**: Design patterns, modularity, scalability
+
+3. **Generate quality report**:
+   - Save to `.specweave/increments/####/reports/qa-post-closure.md`
+   - Include dimension scores, risks identified, recommendations
+   - Link to specific code locations and acceptance criteria
+
+4. **Display results**:
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   🔍 POST-CLOSURE QUALITY ASSESSMENT
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Overall Score: 87/100 (GOOD) ✓
+
+   Dimension Scores:
+     Clarity:         92/100 ✓✓
+     Testability:     85/100 ✓
+     Completeness:    90/100 ✓✓
+     Feasibility:     88/100 ✓✓
+     Maintainability: 85/100 ✓
+     Edge Cases:      78/100 ✓
+     Risk Assessment: 75/100 ✓
+
+   Quality Gate Decision: ✅ PASS
+
+   📋 Full report: .specweave/increments/####/reports/qa-post-closure.md
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+**Quality Gate Decisions**:
+
+| Decision | Criteria | Action |
+|----------|----------|--------|
+| ✅ PASS | Score ≥80, No critical risks | Proceed to next work |
+| 🟡 CONCERNS | Score 60-79, High risks present | Log concerns, suggest improvements |
+| 🔴 FAIL | Score <60, Critical risks present | Create follow-up increment for fixes |
+
+**If Quality Gate FAILS**:
+```
+🔴 QUALITY GATE: FAIL (Score: 58/100)
+
+Critical Issues Found:
+  • CRITICAL RISK: Password storage implementation (9.0/10)
+  • HIGH RISK: Rate limiting not specified (6.0/10)
+  • Testability: 45/100 (below threshold)
+
+Recommendation: Create follow-up increment 0002-security-fixes
+
+Options:
+  A. Create follow-up increment now (recommended)
+  B. Log as technical debt (track in backlog)
+  C. Continue to next feature (not recommended)
+
+What would you like to do? [A/B/C]
+```
+
+**If Quality Gate CONCERNS**:
+```
+🟡 QUALITY GATE: CONCERNS (Score: 72/100)
+
+Issues to address:
+  • Edge cases coverage: 65/100 (should be 80+)
+  • 2 high-priority risks identified
+  • Recommendations: 5 improvements suggested
+
+📋 Review report: .specweave/increments/####/reports/qa-post-closure.md
+
+These can be addressed in future iterations.
+Proceeding to next work...
+```
+
+**IMPORTANT**: Quality assessment runs AFTER closure to:
+- Not block delivery (increment is already closed and shipped)
+- Provide learning and continuous improvement
+- Identify technical debt for future planning
+- Build quality metrics over time
+
 ### Step 4: Suggest Next Work (After Successful Closure)
 
 **Intelligent suggestions based on project state**:
@@ -340,6 +466,23 @@ Active: 0001-user-authentication
 
 🎉 Increment 0001 closed successfully!
 
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔍 POST-CLOSURE QUALITY ASSESSMENT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Running quality assessment...
+
+Overall Score: 87/100 (GOOD) ✓
+
+Dimension Scores:
+  Clarity:         92/100 ✓✓
+  Testability:     85/100 ✓
+  Risk Assessment: 75/100 ✓
+
+Quality Gate Decision: ✅ PASS
+
+📋 Report: .specweave/increments/0001-user-authentication/reports/qa-post-closure.md
+
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 🎯 Next Work Suggestions
@@ -482,14 +625,16 @@ Your choice? [A/B/C] _
 | `/specweave:do` | Execute tasks in increment | Implementing planned work |
 | `/specweave:progress` | Check status (no action) | Quick status check |
 | `/specweave:done` | Explicitly close increment | Manual closure with validation |
-| `/specweave:next` ⭐ | **Smart transition** (close + suggest next) | **Natural workflow continuation** |
+| `/specweave:qa` | Quality assessment only | Standalone QA check |
+| `/specweave:next` ⭐ | **Smart transition** (close + QA + suggest next) | **Natural workflow continuation** |
 
 **Why `/specweave:next` is special**:
-- ✅ Combines validation + closure + suggestion in one command
-- ✅ No need to remember `/specweave:done` then `/specweave:increment` sequence
+- ✅ Combines validation + closure + **quality assessment** + suggestion in one command
+- ✅ No need to remember `/specweave:done` then `/specweave:qa` then `/specweave:increment` sequence
 - ✅ Intelligent suggestions (backlog, WIP, new work)
 - ✅ User stays in control (never forces actions)
 - ✅ Natural "what's next?" workflow
+- ✅ **NEW (v0.24.0+)**: Automatic post-closure quality assessment
 
 ---
 

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

@@ -12,7 +12,7 @@ description: Run quality assessment on a SpecWeave increment with risk scoring a
 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)
+- ✅ Quantitative risk scoring (Probability × Impact)
 - ✅ Quality gate decisions (PASS/CONCERNS/FAIL)
 
 ## Usage
@@ -93,7 +93,7 @@ The agent evaluates:
   6. Edge Cases (9% weight)
   7. **Risk Assessment (11% weight)**
 
-**Risk Assessment** uses BMAD pattern:
+**Risk Assessment** uses quantitative method:
 - 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)