specweave 1.0.261 → 1.0.263

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

@@ -1,255 +0,0 @@
----
-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
-/sw:sync-tasks
-
-# Sync specific increment
-/sw:sync-tasks 0007
-
-# Force sync from GitHub (skip git check)
-/sw:sync-tasks --source=github
-
-# Dry run (show what would change)
-/sw: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 /sw:progress to verify
-```
-
----
-
-## Integration with Other Commands
-
-### /sw:progress
-```bash
-# Check sync status before showing progress
-/sw:sync-tasks --validate
-# If out of sync, warn user
-```
-
-### /sw:validate
-```bash
-# Validate tasks.md is in sync
-/sw:sync-tasks --validate
-# Fail validation if mismatch detected
-```
-
-### /sw:done
-```bash
-# Ensure tasks.md is current before closing
-/sw: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 /sw:progress, /sw:validate, /sw:done
-
----
-
-**This command ensures `/progress` and `/done` always show accurate status!**

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

@@ -1,351 +0,0 @@
----
-description: Update living completion report with scope changes during increment execution
-disable-model-invocation: true
----
-
-# 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
-/sw:update-scope "Added dark mode toggle (stakeholder request from CMO, +16 hours)"
-```
-
-### Detailed Log
-
-```bash
-/sw: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 /sw:status to check increment status');
-  process.exit(1);
-}
-
-if (active.length > 1) {
-  // Multiple active - ask which one
-  const choice = await prompt({
-    type: 'select',
-    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 /sw:increment 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: 'select',
-  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
-
-- `/sw:increment "feature"` - Creates increment with initial completion report
-- `/sw:done <id>` - Finalizes report and marks increment complete
-- `/sw: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.