specweave 0.6.7 → 0.7.0

package/plugins/specweave/commands/specweave-sync-tasks.md

@@ -0,0 +1,256 @@
+---
+name: sync-tasks
+description: Sync tasks.md with actual completion status (GitHub issue or reality check)
+---
+
+# Sync Tasks Status
+
+**Purpose**: Fix tasks.md when it's out of sync with reality (GitHub issue, git history, or actual files).
+
+**Use When**:
+- `/progress` shows wrong completion %
+- GitHub issue says 24/24 but tasks.md says 1/24
+- After manually completing work without updating tasks.md
+
+---
+
+## How It Works
+
+1. **Detect Active Increment**
+   - Find increment in-progress
+   - Check if tasks.md exists
+
+2. **Compare Sources**
+   - **tasks.md**: Current status
+   - **GitHub issue** (if synced): Checklist status
+   - **Git history**: What files were actually changed/created
+   - **File system**: What files exist
+
+3. **Show Diff**
+   ```
+   Sync Status Check:
+
+   tasks.md:       5/24 complete (21%)
+   GitHub #4:      24/24 complete (100%) ✓ TRUTH
+   Git commits:    24 task commits found
+
+   Mismatch detected! tasks.md is stale.
+   ```
+
+4. **Offer Fix**
+   ```
+   Options:
+   1. Auto-sync from GitHub issue (recommended)
+   2. Auto-sync from git history
+   3. Manual review (show each task)
+   4. Cancel
+   ```
+
+5. **Update tasks.md**
+   - Mark completed tasks as [x]
+   - Update progress counters
+   - Commit changes
+
+---
+
+## Usage
+
+```bash
+# Auto-detect and sync
+/specweave:sync-tasks
+
+# Sync specific increment
+/specweave:sync-tasks 0007
+
+# Force sync from GitHub (skip git check)
+/specweave:sync-tasks --source=github
+
+# Dry run (show what would change)
+/specweave:sync-tasks --dry-run
+```
+
+---
+
+## Implementation Steps
+
+### Step 1: Find Active Increment
+
+```bash
+ACTIVE_INCREMENT=$(find .specweave/increments -name "tasks.md" -exec grep -l "Status: In Progress" {} \; | head -1)
+
+if [[ -z "$ACTIVE_INCREMENT" ]]; then
+    echo "No active increment found"
+    exit 0
+fi
+
+INCREMENT_DIR=$(dirname "$ACTIVE_INCREMENT")
+INCREMENT_ID=$(basename "$INCREMENT_DIR" | grep -oE "^[0-9]+")
+```
+
+### Step 2: Get GitHub Issue Status (if exists)
+
+```bash
+# Check if GitHub sync is enabled
+GITHUB_ISSUE=$(grep "github-issue:" "$INCREMENT_DIR/spec.md" | cut -d':' -f2 | tr -d ' ')
+
+if [[ -n "$GITHUB_ISSUE" ]]; then
+    # Fetch issue body
+    ISSUE_BODY=$(gh issue view "$GITHUB_ISSUE" --json body --jq '.body')
+
+    # Count completed checkboxes
+    GH_TOTAL=$(echo "$ISSUE_BODY" | grep -c "^- \[")
+    GH_COMPLETE=$(echo "$ISSUE_BODY" | grep -c "^- \[x\]")
+
+    echo "GitHub Issue #$GITHUB_ISSUE: $GH_COMPLETE/$GH_TOTAL complete"
+else
+    echo "No GitHub issue linked (skipping GitHub sync)"
+fi
+```
+
+### Step 3: Get tasks.md Status
+
+```bash
+TASKS_TOTAL=$(grep -c "^#### T-" "$INCREMENT_DIR/tasks.md")
+TASKS_COMPLETE=$(grep -A1 "^#### T-" "$INCREMENT_DIR/tasks.md" | grep -c "\*\*Status\*\*: \[x\] completed")
+
+echo "tasks.md: $TASKS_COMPLETE/$TASKS_TOTAL complete"
+```
+
+### Step 4: Detect Mismatch
+
+```bash
+if [[ "$GH_COMPLETE" -ne "$TASKS_COMPLETE" ]]; then
+    echo "⚠️ Mismatch detected!"
+    echo "  GitHub:    $GH_COMPLETE/$GH_TOTAL"
+    echo "  tasks.md:  $TASKS_COMPLETE/$TASKS_TOTAL"
+    echo ""
+
+    # Offer to sync
+    read -p "Sync tasks.md from GitHub issue? (y/n): " CONFIRM
+
+    if [[ "$CONFIRM" == "y" ]]; then
+        sync_from_github "$INCREMENT_DIR" "$GITHUB_ISSUE"
+    fi
+else
+    echo "✓ tasks.md is in sync with GitHub issue"
+fi
+```
+
+### Step 5: Sync From GitHub
+
+```bash
+sync_from_github() {
+    local increment_dir="$1"
+    local github_issue="$2"
+
+    # Parse GitHub issue checklist
+    gh issue view "$github_issue" --json body --jq '.body' | while IFS= read -r line; do
+        if [[ "$line" =~ ^\-\ \[x\]\ (T-[0-9]{3}) ]]; then
+            # Task is complete in GitHub, mark in tasks.md
+            TASK_ID="${BASH_REMATCH[1]}"
+            mark_task_complete "$increment_dir" "$TASK_ID"
+        fi
+    done
+
+    # Recalculate progress
+    recalculate_progress "$increment_dir"
+
+    echo "✓ Synced tasks.md from GitHub issue #$github_issue"
+}
+
+mark_task_complete() {
+    local increment_dir="$1"
+    local task_id="$2"
+
+    # Find task and update status
+    sed -i '' "/^#### $task_id:/,/^\*\*Status\*\*:/ s/\*\*Status\*\*: \[ \] pending/\*\*Status\*\*: [x] completed/" "$increment_dir/tasks.md"
+}
+
+recalculate_progress() {
+    local increment_dir="$1"
+
+    local total=$(grep -c "^#### T-" "$increment_dir/tasks.md")
+    local completed=$(grep -A1 "^#### T-" "$increment_dir/tasks.md" | grep -c "\*\*Status\*\*: \[x\] completed")
+    local progress=$((completed * 100 / total))
+
+    # Update header
+    sed -i '' "s/\*\*Completed\*\*: [0-9]*/\*\*Completed\*\*: $completed/" "$increment_dir/tasks.md"
+    sed -i '' "s/\*\*Progress\*\*: [0-9]*%/\*\*Progress\*\*: $progress%/" "$increment_dir/tasks.md"
+
+    echo "✓ Progress updated: $completed/$total ($progress%)"
+}
+```
+
+---
+
+## Example Output
+
+```
+🔄 Syncing tasks.md status...
+
+Active Increment: 0007-smart-increment-discipline
+
+Status Comparison:
+├─ tasks.md:      1/24 complete (4%)
+├─ GitHub #4:     24/24 complete (100%)
+└─ Mismatch:      23 tasks out of sync ⚠️
+
+Sync Source:
+✓ GitHub issue #4 (most reliable)
+
+Updating tasks.md...
+├─ T-001: [ ] → [x] ✓
+├─ T-002: [ ] → [x] ✓
+├─ T-003: [ ] → [x] ✓
+...
+└─ T-024: [ ] → [x] ✓
+
+Progress recalculated:
+├─ Completed: 1 → 24
+├─ Progress: 4% → 100%
+└─ Status: In Progress → Complete
+
+✓ tasks.md synced successfully!
+
+Next: Run /progress to verify
+```
+
+---
+
+## Integration with Other Commands
+
+### /progress
+```bash
+# Check sync status before showing progress
+/sync-tasks --validate
+# If out of sync, warn user
+```
+
+### /validate
+```bash
+# Validate tasks.md is in sync
+/sync-tasks --validate
+# Fail validation if mismatch detected
+```
+
+### /done
+```bash
+# Ensure tasks.md is current before closing
+/sync-tasks --auto
+# Auto-sync if needed, then proceed
+```
+
+---
+
+## Success Criteria
+
+- ✅ Detects when tasks.md is out of sync
+- ✅ Syncs from GitHub issue (if available)
+- ✅ Syncs from git history (fallback)
+- ✅ Updates progress counters accurately
+- ✅ Commits changes with clear message
+- ✅ Integrates with /progress, /validate, /done
+
+---
+
+**This command ensures `/progress` and `/done` always show accurate status!**

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

@@ -257,7 +257,7 @@ If issues found, restore from git:
 - Commands: /specweave:inc, /specweave:do, /specweave:progress, /specweave:sync-docs
 - File paths: .specweave/, src/, .claude/, .cursor/, .github/
 - Technical terms: TypeScript, npm, git, API, CLI, REST, JSON, HTTP
-- SpecWeave keywords: living docs, context-manifest.yaml, PM gate, RFC
+- SpecWeave keywords: living docs, context-manifest.yaml, PM gate, Spec
 - Code blocks (entire blocks stay in English)
 - YAML frontmatter keys (only translate values if applicable)
 
@@ -279,7 +279,7 @@ If issues found, restore from git:
 - `living docs`
 - `PM gate`, `Architect`, `Tech Lead`
 - `context-manifest`
-- `RFC`, `ADR`, `PRD`, `HLD`, `LLD`
+- `Spec`, `ADR`, `PRD`, `HLD`, `LLD`
 
 **Why?** These are framework primitives - translating them would break tooling, scripts, and cross-project consistency.
 
@@ -304,7 +304,7 @@ If issues found, restore from git:
 ```yaml
 # Only translate description values, NOT keys
 ---
-name: increment-planner              # ← Keep as-is
+name: specweave-increment-planner              # ← Keep as-is
 description: Plans new increments    # ← Translate this
 allowed-tools: Read, Write, Edit     # ← Keep tools as-is
 ---

package/plugins/specweave/commands/specweave-update-scope.md

@@ -0,0 +1,351 @@
+---
+name: update-scope
+description: Update living completion report with scope changes during increment execution
+---
+
+# Update Increment Scope (Living Reports)
+
+**Purpose**: Log scope changes in real-time during increment execution for complete traceability.
+
+This command adds entries to the **Scope Evolution** section of the completion report, capturing:
+- What changed (user stories added/removed/modified)
+- Why it changed (business reason, technical blocker, stakeholder request)
+- Who approved it (PM, stakeholder, architect)
+- Impact on timeline and effort
+
+---
+
+## Why Living Reports Matter
+
+**Problem** (traditional approach):
+```
+Start: Plan 10 tasks
+During work: Scope changes 5 times (but not documented)
+End: Report says "Completed 8/10 tasks"
+Future: "Why was Task 5 removed?" → No one remembers
+```
+
+**Solution** (living reports):
+```
+Start: Plan 10 tasks + initialize completion report
+During work:
+  - 2025-11-06: Added US6 (dark mode) → update-scope logged
+  - 2025-11-07: Deferred US3 (CSV export) → update-scope logged
+  - 2025-11-08: WebSockets → Polling pivot → update-scope logged
+End: Report shows complete scope evolution with WHY
+Future: "Why was Task 5 removed?" → Check report, find exact reason
+```
+
+**Value**:
+- ✅ Complete audit trail (why scope changed)
+- ✅ Real-time documentation (not reconstructed later)
+- ✅ Regulatory compliance (explains deviations)
+- ✅ Learning for future increments
+- ✅ Onboarding new team members
+
+---
+
+## Usage
+
+### Quick Log
+
+```bash
+/update-scope "Added dark mode toggle (stakeholder request from CMO, +16 hours)"
+```
+
+### Detailed Log
+
+```bash
+/update-scope
+# Interactive prompts:
+# - What changed? (Added/Removed/Modified user story)
+# - What specifically? (e.g., "US6: Dark mode toggle")
+# - Why changed? (Stakeholder request, technical blocker, etc.)
+# - Impact on effort? (+16 hours, -4 hours, 0)
+# - Who approved? (PM, Architect, CTO, etc.)
+# - Documentation links? (ADR-008, GitHub issue #123, etc.)
+```
+
+---
+
+## How It Works
+
+### Step 1: Detect Current Increment
+
+```typescript
+import { MetadataManager } from '../core/metadata-manager';
+
+// Find active increment
+const active = await MetadataManager.getActive();
+
+if (active.length === 0) {
+  console.error('❌ No active increment found');
+  console.error('   Run /status to check increment status');
+  process.exit(1);
+}
+
+if (active.length > 1) {
+  // Multiple active - ask which one
+  const choice = await prompt({
+    type: 'list',
+    message: 'Which increment to update?',
+    choices: active.map(inc => ({ name: inc.id, value: inc.id }))
+  });
+  increment = choice;
+} else {
+  increment = active[0].id;
+}
+
+console.log(`\n📝 Updating scope for: ${increment}\n`);
+```
+
+### Step 2: Load Existing Report
+
+```typescript
+const reportPath = `.specweave/increments/${increment}/reports/COMPLETION-REPORT.md`;
+
+if (!fs.existsSync(reportPath)) {
+  console.error('❌ Completion report not found');
+  console.error(`   Expected: ${reportPath}`);
+  console.error('   Run /inc to create increment properly');
+  process.exit(1);
+}
+
+const report = fs.readFileSync(reportPath, 'utf-8');
+```
+
+### Step 3: Gather Scope Change Details
+
+**Prompt user** (if not provided in command):
+
+```typescript
+const changeType = await prompt({
+  type: 'list',
+  message: 'What changed?',
+  choices: [
+    'Added user story',
+    'Removed/deferred user story',
+    'Modified user story',
+    'Technical pivot (architecture change)',
+    'Scope reduction',
+    'Scope expansion',
+    'Other'
+  ]
+});
+
+const changeDescription = await prompt({
+  type: 'input',
+  message: 'What specifically changed?',
+  validate: input => input.length > 5 || 'Please provide details'
+});
+
+const changeReason = await prompt({
+  type: 'input',
+  message: 'Why did it change?',
+  validate: input => input.length > 5 || 'Please provide reason'
+});
+
+const impactHours = await prompt({
+  type: 'input',
+  message: 'Impact on effort (hours):',
+  default: '0',
+  validate: input => !isNaN(parseInt(input)) || 'Must be a number'
+});
+
+const approver = await prompt({
+  type: 'input',
+  message: 'Who approved this change?',
+  default: 'PM'
+});
+
+const docLinks = await prompt({
+  type: 'input',
+  message: 'Related documentation (ADR, issue, PR):',
+  default: 'None'
+});
+```
+
+### Step 4: Add Entry to Scope Evolution Section
+
+```typescript
+const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+
+const impactDirection = parseInt(impactHours) > 0 ? '+' : '';
+const impactText = impactHours === '0' ? '0 hours' : `${impactDirection}${impactHours} hours`;
+
+const newEntry = `
+### ${today}: ${changeType}
+
+**Changed**: ${changeDescription}
+**Reason**: ${changeReason}
+**Impact**: ${impactText}
+**Decision**: ${approver}
+**Documentation**: ${docLinks}
+
+---
+`;
+
+// Find "## Scope Evolution" section
+const scopeEvolutionMarker = '## Scope Evolution (Living Updates)';
+const noChangesMarker = '_No scope changes during this increment._';
+
+let updatedReport;
+
+if (report.includes(noChangesMarker)) {
+  // First scope change - replace placeholder
+  updatedReport = report.replace(
+    noChangesMarker,
+    '_This section is updated during the increment whenever scope changes occur._\n\n' + newEntry
+  );
+} else {
+  // Append to existing changes
+  const scopeIndex = report.indexOf(scopeEvolutionMarker);
+  const nextSectionIndex = report.indexOf('\n## ', scopeIndex + scopeEvolutionMarker.length);
+
+  const beforeScope = report.substring(0, nextSectionIndex);
+  const afterScope = report.substring(nextSectionIndex);
+
+  updatedReport = beforeScope + '\n' + newEntry + afterScope;
+}
+
+// Update report version
+const versionRegex = /\*\*Report Version\*\*: v(\d+\.\d+)/;
+const match = updatedReport.match(versionRegex);
+
+if (match) {
+  const currentVersion = parseFloat(match[1]);
+  const newVersion = (currentVersion + 0.1).toFixed(1);
+  updatedReport = updatedReport.replace(versionRegex, `**Report Version**: v${newVersion}`);
+}
+
+// Update last updated timestamp
+const timestampRegex = /\*\*Last Updated\*\*: .*/;
+updatedReport = updatedReport.replace(timestampRegex, `**Last Updated**: ${new Date().toISOString()}`);
+
+fs.writeFileSync(reportPath, updatedReport, 'utf-8');
+
+console.log(chalk.green('\n✅ Scope change logged successfully!\n'));
+console.log(chalk.dim(`   ${reportPath}\n`));
+console.log(chalk.blue('📋 Change summary:'));
+console.log(chalk.white(`   Type: ${changeType}`));
+console.log(chalk.white(`   Impact: ${impactText}`));
+console.log(chalk.white(`   Approved by: ${approver}\n`));
+
+console.log(chalk.dim('💡 View full report:'));
+console.log(chalk.dim(`   cat ${reportPath}\n`));
+```
+
+---
+
+## Example Output
+
+```
+📝 Updating scope for: 0008-user-dashboard
+
+What changed? Added user story
+What specifically changed? US6: Dark mode toggle
+Why did it change? Stakeholder request from CMO (high priority, blocks marketing launch)
+Impact on effort (hours): 16
+Who approved this change? PM + CMO
+Related documentation (ADR, issue, PR): GitHub issue #45
+
+✅ Scope change logged successfully!
+
+   .specweave/increments/0008-user-dashboard/reports/COMPLETION-REPORT.md
+
+📋 Change summary:
+   Type: Added user story
+   Impact: +16 hours
+   Approved by: PM + CMO
+
+💡 View full report:
+   cat .specweave/increments/0008-user-dashboard/reports/COMPLETION-REPORT.md
+```
+
+---
+
+## Completion Report Format
+
+The completion report is initialized when increment is created and updated throughout:
+
+```markdown
+## Scope Evolution (Living Updates)
+
+_This section is updated during the increment whenever scope changes occur._
+
+### 2025-11-06: Added user story
+
+**Changed**: US6: Dark mode toggle
+**Reason**: Stakeholder request from CMO (high priority, blocks marketing launch)
+**Impact**: +16 hours
+**Decision**: PM + CMO
+**Documentation**: GitHub issue #45
+
+---
+
+### 2025-11-07: Removed/deferred user story
+
+**Changed**: US3: Data export to CSV
+**Reason**: Not critical for MVP, can be added later without breaking changes
+**Impact**: -8 hours (deferred to increment 0009)
+**Decision**: PM
+**Documentation**: None
+
+---
+
+### 2025-11-08: Technical pivot (architecture change)
+
+**Changed**: WebSockets → Long-polling
+**Reason**: WebSocket library had critical security vulnerability (CVE-2025-1234)
+**Impact**: -4 hours (simpler implementation)
+**Decision**: Architect + Security Lead
+**Documentation**: ADR-008: Why We Chose Polling Over WebSockets
+
+---
+```
+
+---
+
+## Best Practices
+
+### When to Update
+
+✅ **DO update** when:
+- Adding new user story or task
+- Removing/deferring work
+- Modifying scope of existing story
+- Making architecture pivots
+- Reducing/expanding scope
+- Blocking issues discovered
+
+❌ **DON'T update** for:
+- Bug fixes discovered during implementation (normal)
+- Minor implementation details
+- Code refactoring (unless scope-affecting)
+
+### What to Capture
+
+Always include:
+- **What changed**: Specific user story or task
+- **Why**: Business reason, technical blocker, stakeholder request
+- **Impact**: Hours added/removed
+- **Approval**: Who made the decision
+- **Links**: ADR, GitHub issue, Jira ticket
+
+### Frequency
+
+- Update in **real-time** when change occurs (don't batch)
+- Better to have 10 small entries than 1 large summary
+- Captures decision context while fresh
+
+---
+
+## Related Commands
+
+- `/inc "feature"` - Creates increment with initial completion report
+- `/done <id>` - Finalizes report and marks increment complete
+- `/status` - Check which increment is active
+
+---
+
+**💡 Pro Tip**: Use this command liberally! Living reports are your future self's best friend. When someone asks "Why did we defer feature X?", you'll have the exact answer with full context.

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

@@ -5,6 +5,8 @@ description: Validate SpecWeave increment with rule-based checks and optional AI
 
 # Validate Increment
 
+**⚡ Convenient Short Form**: Use `/validate` for quick access, or `/specweave:validate` for explicit namespace.
+
 You are helping the user validate a SpecWeave increment with optional AI-powered quality assessment.
 
 ## Usage