specweave 1.0.261 → 1.0.263

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

@@ -1,342 +0,0 @@
----
-description: Manually synchronize acceptance criteria (AC) checkbox status in spec.md based on task completion
-disable-model-invocation: true
----
-
-# Sync Acceptance Criteria Status
-
-**Purpose**: Manually trigger AC checkbox synchronization to ensure spec.md acceptance criteria accurately reflect task completion status.
-
-**Use When**:
-- AC checkboxes in spec.md are out of sync with completed tasks
-- After manually completing tasks without running the hook
-- To verify AC status before closing an increment
-- To resolve conflicts between manual AC edits and task completion
-
----
-
-## How It Works
-
-1. **Detect Active Increment**
-   - Find increment in-progress
-   - Check if spec.md and tasks.md exist
-
-2. **Parse Task Completion**
-   - Extract all tasks from tasks.md
-   - Map AC-IDs to completion status
-   - Calculate percentage complete per AC (# complete tasks / # total tasks)
-
-3. **Parse AC Definitions**
-   - Extract all ACs from spec.md
-   - Track current checkbox state ([ ] or [x])
-   - Map line numbers for atomic updates
-
-4. **Intelligent Sync Logic**
-   - **100% Complete**: Update [ ] → [x]
-   - **< 100% Complete**: Keep [ ] (partial work)
-   - **Conflict Detection**: AC is [x] but tasks incomplete → WARN
-   - **Orphaned ACs**: AC has no implementing tasks → WARN
-
-5. **Atomic File Update**
-   - Update spec.md only if changes needed
-   - Preserve manual overrides (conflicts)
-   - Log all changes to metadata.json
-
----
-
-## Usage
-
-```bash
-# Auto-detect and sync active increment
-/sw:sync-acs
-
-# Sync specific increment
-/sw:sync-acs 0039
-
-# Show what would change (dry run)
-/sw:sync-acs --dry-run
-
-# Force sync (ignore conflicts)
-/sw:sync-acs --force
-
-# Validate only (check for mismatches)
-/sw:sync-acs --validate
-```
-
----
-
-## Implementation
-
-The command uses **ACStatusManager** for sophisticated synchronization:
-
-```typescript
-import { ACStatusManager } from '../../../../../src/core/increment/ac-status-manager';
-
-const manager = new ACStatusManager(process.cwd());
-const result = await manager.syncACStatus(incrementId);
-
-// result.synced: true if sync was performed
-// result.updated: string[] - AC-IDs updated to [x]
-// result.conflicts: string[] - Conflicts detected
-// result.warnings: string[] - Orphaned ACs, missing files
-// result.changes: string[] - Human-readable diff
-```
-
-### Step 1: Find Active Increment
-
-```bash
-# Auto-detect active increment
-ACTIVE_INCREMENT=$(ls -t .specweave/increments/ 2>/dev/null | grep -v "_backlog\|_archive" | head -1)
-
-if [[ -z "$ACTIVE_INCREMENT" ]]; then
-    echo "❌ No active increment found"
-    exit 1
-fi
-
-echo "🔄 Syncing AC status for $ACTIVE_INCREMENT..."
-```
-
-### Step 2: Call ACStatusManager
-
-```bash
-# Use the update-ac-status.js hook script (already integrated)
-node plugins/specweave/lib/hooks/update-ac-status.js "$ACTIVE_INCREMENT"
-```
-
-Or invoke directly:
-
-```typescript
-const result = await manager.syncACStatus(incrementId);
-```
-
-### Step 3: Display Results
-
-```bash
-# Updated ACs
-if [[ -n "${result.updated}" ]]; then
-    echo "✅ Updated AC checkboxes:"
-    for acId in "${result.updated[@]}"; do
-        echo "   $acId → [x]"
-    done
-fi
-
-# Conflicts
-if [[ -n "${result.conflicts}" ]]; then
-    echo "⚠️  Conflicts detected:"
-    for conflict in "${result.conflicts[@]}"; do
-        echo "   $conflict"
-    done
-fi
-
-# Warnings
-if [[ -n "${result.warnings}" ]]; then
-    echo "⚠️  Warnings:"
-    for warning in "${result.warnings[@]}"; do
-        echo "   $warning"
-    done
-fi
-```
-
----
-
-## Example Scenarios
-
-### Scenario 1: Normal Sync (100% Complete AC)
-
-**Before**:
-```markdown
-# spec.md
-- [ ] AC-US1-01: User can login
-- [ ] AC-US1-02: Session persists
-
-# tasks.md
-#### T-001: Implement login API
-**AC**: AC-US1-01
-**Status**: [x] (100% - Completed)
-
-#### T-002: Add session storage
-**AC**: AC-US1-01
-**Status**: [x] (100% - Completed)
-```
-
-**After**:
-```markdown
-# spec.md
-- [x] AC-US1-01: User can login  ✓ UPDATED
-- [ ] AC-US1-02: Session persists
-```
-
-**Output**:
-```
-🔄 Syncing AC status for increment 0039...
-
-✅ Updated AC checkboxes:
-   AC-US1-01 → [x]
-
-📝 Changes:
-   AC-US1-01: [ ] → [x] (2/2 tasks complete - 100%)
-```
-
----
-
-### Scenario 2: Partial Completion (No Update)
-
-**Before**:
-```markdown
-# spec.md
-- [ ] AC-US1-02: Session persists
-
-# tasks.md
-#### T-003: Add Redis session store
-**AC**: AC-US1-02
-**Status**: [x] (100% - Completed)
-
-#### T-004: Test session expiry
-**AC**: AC-US1-02
-**Status**: [ ] (0% - Not started)
-```
-
-**After**:
-```markdown
-# spec.md
-- [ ] AC-US1-02: Session persists  (NO CHANGE - 50% complete)
-```
-
-**Output**:
-```
-🔄 Syncing AC status for increment 0039...
-
-ℹ️  No AC updates needed
-
-📊 Completion Status:
-   AC-US1-02: 1/2 tasks complete (50%) - threshold not met
-```
-
----
-
-### Scenario 3: Conflict Detection
-
-**Before**:
-```markdown
-# spec.md
-- [x] AC-US1-03: Data validated (manually checked)
-
-# tasks.md
-#### T-005: Add validation rules
-**AC**: AC-US1-03
-**Status**: [x] (100% - Completed)
-
-#### T-006: Add error handling
-**AC**: AC-US1-03
-**Status**: [ ] (0% - Not started)
-```
-
-**After**:
-```markdown
-# spec.md
-- [x] AC-US1-03: Data validated (PRESERVED - conflict detected)
-```
-
-**Output**:
-```
-🔄 Syncing AC status for increment 0039...
-
-⚠️  Conflicts detected:
-   AC-US1-03: Marked [x] but only 1/2 tasks complete (50%)
-   → Manual override preserved (no change made)
-
-💡 Tip: Review tasks for AC-US1-03 or uncheck manually if premature
-```
-
----
-
-### Scenario 4: Orphaned AC Warning
-
-**Before**:
-```markdown
-# spec.md
-- [ ] AC-US1-04: Performance optimized
-- [ ] AC-US1-05: Security hardened
-
-# tasks.md
-#### T-007: Implement caching
-**AC**: AC-US1-04
-**Status**: [x] (100% - Completed)
-
-(No tasks reference AC-US1-05)
-```
-
-**Output**:
-```
-🔄 Syncing AC status for increment 0039...
-
-✅ Updated AC checkboxes:
-   AC-US1-04 → [x]
-
-⚠️  Warnings:
-   AC-US1-05: No implementing tasks found (orphaned AC)
-   → Add tasks or remove AC from spec.md
-```
-
----
-
-## Integration with Hooks
-
-### Automatic Sync (Post-Task-Completion Hook)
-
-The hook automatically calls `ACStatusManager.syncACStatus()` after every task completion:
-
-```bash
-# plugins/specweave/hooks/post-task-completion.sh (lines 232-269)
-if [ -n "$CURRENT_INCREMENT" ]; then
-    node plugins/specweave/lib/hooks/update-ac-status.js "$CURRENT_INCREMENT"
-fi
-```
-
-**Disable automatic sync**:
-```bash
-export SKIP_AC_SYNC=true
-# Now hooks won't sync ACs (useful for batch work)
-```
-
----
-
-## Integration with Other Commands
-
-### /sw:validate
-```bash
-# Validate ACs before closing increment
-/sw:sync-acs --validate
-# Warns if ACs out of sync
-```
-
-### /sw:done
-```bash
-# Auto-sync ACs before closing
-/sw:sync-acs
-# Then proceed with increment closure
-```
-
-### /sw:progress
-```bash
-# Show AC completion alongside task progress
-/sw:sync-acs --status
-# Display: 8/10 ACs complete (80%)
-```
-
----
-
-## Success Criteria
-
-- ✅ Syncs AC checkboxes based on task completion (100% threshold)
-- ✅ Detects and preserves manual overrides (conflicts)
-- ✅ Warns about orphaned ACs (no implementing tasks)
-- ✅ Shows clear diff of changes before/after
-- ✅ Atomic file writes (no corruption risk)
-- ✅ Integrates with post-task-completion hook
-- ✅ Supports dry-run mode
-- ✅ Logs all changes to metadata.json
-
----
-
-**This command ensures acceptance criteria accurately reflect implementation progress!**

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

@@ -1,339 +0,0 @@
----
-description: Sync ALL increment specifications to living docs structure by default. Creates FS-XXX folders for each increment. Use with increment ID to sync single increment.
----
-
-# Sync Increment Specifications to Living Docs
-
-**DEFAULT BEHAVIOR**: Syncs ALL increments to living docs (not just one!)
-
----
-
-## STEP 1: Parse Arguments & Determine Mode
-
-```
-Arguments provided: $ARGUMENTS
-```
-
-**Parse the input to determine sync mode**:
-
-| Input | Mode | Action |
-|-------|------|--------|
-| `/sw:sync-specs` | **ALL** (default) | Sync ALL increments |
-| `/sw:sync-specs --all` | **ALL** (explicit) | Sync ALL increments |
-| `/sw:sync-specs 0106` | **SINGLE** | Sync only increment 0106 |
-| `/sw:sync-specs 0106 --dry-run` | **SINGLE + DRY** | Preview sync for 0106 |
-| `/sw:sync-specs --dry-run` | **ALL + DRY** | Preview sync for ALL |
-
-**CRITICAL**: No increment ID = sync ALL increments (this is the DEFAULT!)
-
----
-
-## STEP 2: Execute Sync Based on Mode
-
-### MODE A: Sync ALL Increments (Default)
-
-**This is the DEFAULT when no increment ID is provided!**
-
-```bash
-# List ALL syncable increments (with spec.md)
-ls -1 .specweave/increments/ | grep -E '^[0-9]{4}E?-' | sort
-```
-
-**Execute sync for EACH increment**:
-
-```
-🔄 Syncing ALL increments to living docs...
-
-Found {N} increments with spec.md files.
-```
-
-**For each increment**, call the sync logic:
-
-```typescript
-import { LivingDocsSync } from './src/core/living-docs/living-docs-sync.js';
-
-const sync = new LivingDocsSync(projectRoot);
-
-// Get all increment folders
-const incrementsDir = '.specweave/increments';
-const entries = fs.readdirSync(incrementsDir);
-const increments = entries.filter(e => /^\d{4}E?-/.test(e));
-
-let successCount = 0;
-let failCount = 0;
-const results = [];
-
-for (const incrementId of increments.sort()) {
-  // Check if spec.md exists
-  const specPath = path.join(incrementsDir, incrementId, 'spec.md');
-  if (!fs.existsSync(specPath)) {
-    console.log(`   ⚠️  Skipping ${incrementId} (no spec.md)`);
-    continue;
-  }
-
-  try {
-    const result = await sync.syncIncrement(incrementId, { dryRun, force });
-    if (result.success) {
-      successCount++;
-      results.push({ id: incrementId, featureId: result.featureId, status: '✅' });
-    } else {
-      failCount++;
-      results.push({ id: incrementId, featureId: '', status: '❌', error: result.errors[0] });
-    }
-  } catch (error) {
-    failCount++;
-    results.push({ id: incrementId, featureId: '', status: '❌', error: error.message });
-  }
-}
-```
-
-**Output summary table**:
-
-```
-═══════════════════════════════════════════════════════
-✅ BULK SYNC COMPLETE
-═══════════════════════════════════════════════════════
-
-| Increment | Feature ID | Status |
-|-----------|------------|--------|
-| 0093-ado-permission-profile-fixes | FS-093 | ✅ |
-| 0094-unit-test-alignment | FS-094 | ✅ |
-| 0095-per-project-epic-hierarchy | FS-095 | ✅ |
-| ... | ... | ... |
-
-───────────────────────────────────────────────────────
-📊 SUMMARY
-───────────────────────────────────────────────────────
-
-Total increments: {N}
-✅ Succeeded: {successCount}
-❌ Failed: {failCount}
-⏭️  Skipped: {skippedCount} (no spec.md)
-
-═══════════════════════════════════════════════════════
-```
-
-### MODE B: Sync SINGLE Increment
-
-**Only when a specific increment ID is provided**:
-
-```
-🎯 Target increment: {increment_id}
-📁 Increment path: .specweave/increments/{increment_id}
-🔄 Mode: Single increment sync
-```
-
-**Execute single sync**:
-
-```typescript
-const result = await sync.syncIncrement(incrementId, { dryRun, force });
-```
-
-**Output**:
-```
-═══════════════════════════════════════════════════════
-✅ SINGLE INCREMENT SYNC COMPLETE
-═══════════════════════════════════════════════════════
-
-Increment: {increment_id}
-Feature ID: FS-{XXX} (derived from increment number)
-Project: {project}
-
-Files created:
-  • {project}/FS-{XXX}/FEATURE.md
-  • {project}/FS-{XXX}/us-001-*.md
-  • {project}/FS-{XXX}/us-002-*.md
-  ...
-
-═══════════════════════════════════════════════════════
-```
-
----
-
-## STEP 3: Identify Missing/New Specs
-
-After sync, compare increments vs specs:
-
-```bash
-# Get all increment numbers
-INCREMENT_NUMS=$(ls -1 .specweave/increments/ | grep -E '^[0-9]{4}E?-' | sed 's/^\([0-9]*E\?\).*/\1/')
-
-# Get all FS-XXX folders in specs
-SPEC_NUMS=$(ls -1 .specweave/docs/internal/specs/*/FS-* 2>/dev/null | grep -oE 'FS-[0-9]+E?' | sed 's/FS-//')
-
-# Find missing (increments without corresponding FS-XXX)
-echo "Checking for gaps..."
-```
-
-**Report gaps** (increments without corresponding specs):
-
-```
-📊 GAP ANALYSIS
-───────────────────────────────────────────────────────
-
-{if gaps found}
-⚠️  Found {N} increments without corresponding specs:
-   • 0106-ci-health-improvements → FS-106 missing
-   • 0113-enhanced-living-docs-architecture → FS-113 missing
-
-These were synced in this run.
-{else}
-✅ All increments have corresponding spec folders!
-{/if}
-```
-
----
-
-## STEP 4: Feature ID Derivation Rules
-
-**CRITICAL**: Feature ID is ALWAYS derived from increment number:
-
-| Increment ID | Feature ID |
-|--------------|------------|
-| 0002-user-authentication | FS-002 |
-| 0040-some-feature | FS-040 |
-| 0106-ci-health | FS-106 |
-| 0111E-dora-metrics-fix | FS-111E |
-
-**Rules**:
-- Increment `XXXX-name` → Feature `FS-XXX` (3-digit minimum)
-- Increment `XXXXE-name` (external) → Feature `FS-XXXE`
-- NO date-based patterns (FS-YY-MM-DD-name is WRONG)
-- See ADR-0187 for rationale
-
----
-
-## OPTIONS
-
-### --dry-run
-Preview what would be synced without making changes:
-
-```bash
-/sw:sync-specs --dry-run        # Preview ALL
-/sw:sync-specs 0106 --dry-run   # Preview single
-```
-
-### --force
-Overwrite existing files without prompting:
-
-```bash
-/sw:sync-specs --force          # Force ALL
-/sw:sync-specs 0106 --force     # Force single
-```
-
----
-
-## EXAMPLES
-
-### Example 1: Sync ALL (Default - Most Common)
-```
-User: /sw:sync-specs
-
-Output:
-🔄 Syncing ALL increments to living docs...
-
-Found 25 increments with spec.md files.
-
-| Increment | Feature ID | Status |
-|-----------|------------|--------|
-| 0093-ado-permission-profile-fixes | FS-093 | ✅ |
-| 0094-unit-test-alignment | FS-094 | ✅ |
-| 0095-per-project-epic-hierarchy | FS-095 | ✅ |
-| 0096-ado-import-fixes | FS-096 | ✅ |
-| 0097-umbrella-module-detection | FS-097 | ✅ |
-| ... | ... | ... |
-| 0116-livingspec-universal-standard | FS-116 | ✅ |
-
-📊 SUMMARY: 25 succeeded, 0 failed
-```
-
-### Example 2: Sync Single Increment
-```
-User: /sw:sync-specs 0106
-
-Output:
-🎯 Target increment: 0106-ci-health-improvements
-📁 Increment path: .specweave/increments/0106-ci-health-improvements
-🔄 Mode: Single increment sync
-
-✅ Synced 0106-ci-health-improvements → FS-106
-   Created: specweave/FS-106/FEATURE.md
-   Created: specweave/FS-106/us-001-*.md
-```
-
-### Example 3: Dry Run ALL
-```
-User: /sw:sync-specs --dry-run
-
-Output:
-🔍 DRY RUN MODE - No files will be modified
-
-Would sync 25 increments:
-  • 0093 → FS-093 (exists, would update)
-  • 0094 → FS-094 (exists, would update)
-  • 0106 → FS-106 (NEW - would create)
-  • 0113 → FS-113 (NEW - would create)
-  ...
-
-No changes made (dry run mode)
-```
-
----
-
-## ERROR HANDLING
-
-### Error: No Increments Found
-```
-❌ Error: No increments found in .specweave/increments/
-
-Create an increment first:
-  /sw:increment "feature name"
-```
-
-### Error: Specific Increment Not Found
-```
-❌ Error: Increment '0999' not found
-
-Available increments:
-  0093-ado-permission-profile-fixes
-  0094-unit-test-alignment
-  ...
-
-Usage: /sw:sync-specs [increment_id]
-```
-
-### Error: Missing spec.md
-```
-⚠️  Skipping 0107-incomplete-feature (no spec.md)
-
-Increment must have a spec.md file to sync.
-```
-
----
-
-## IMPORTANT NOTES
-
-1. **DEFAULT = ALL**: Running without arguments syncs ALL increments
-2. **Idempotent**: Safe to run multiple times (updates existing, creates missing)
-3. **Feature ID derivation**: Always from increment number (not stored in metadata)
-4. **Project detection**: Reads `project:` from spec.md YAML frontmatter
-5. **External sync**: Triggers GitHub/JIRA/ADO sync if configured
-
----
-
-## WHEN TO USE THIS COMMAND
-
-✅ **Use `/sw:sync-specs` (no args) when**:
-- You want to ensure ALL increments are in living docs
-- After creating multiple increments
-- To fix gaps in specs folder
-- Regular maintenance sync
-
-✅ **Use `/sw:sync-specs <id>` when**:
-- You only want to sync one specific increment
-- After updating a single spec.md
-- Debugging sync issues for one increment
-
----
-
-**Execute this command now. Default = sync ALL increments.**