specweave 0.24.13 → 0.26.2

package/CLAUDE.md

@@ -61,13 +61,31 @@ git push origin develop
 **Solution**: Use the automated refresh script!
 
 ```bash
-# LOCAL DEVELOPMENT (default) - Uses your local changes
+# FROM GITHUB (default, recommended) - Pulls latest from GitHub
 bash scripts/refresh-marketplace.sh
 
-# FROM GITHUB - Pulls latest from GitHub
-bash scripts/refresh-marketplace.sh --github
+# LOCAL DEVELOPMENT - Uses your local changes (ONLY for active development!)
+bash scripts/refresh-marketplace.sh --local
 ```
 
+**🚨 CRITICAL: Always Use GitHub Mode Unless Actively Developing!**
+
+**Why GitHub mode is mandatory:**
+- ✅ **Separate Installation**: Creates proper copy at `~/.claude/plugins/marketplaces/specweave/`
+- ✅ **Stable Source**: Pulls from committed GitHub code, not unstable local changes
+- ✅ **No Path Coupling**: Clear separation between source and runtime
+- ✅ **Production-Ready**: What end users will experience
+
+**Why local mode is dangerous:**
+- ❌ **Filesystem Coupling**: `installLocation` = source directory (no separate copy!)
+- ❌ **Stale Hook Risk**: Any git operations, file deletions, or uncommitted changes affect "installed" plugins
+- ❌ **Path Confusion**: Claude Code expects hooks at `~/.claude/plugins/marketplaces/` but they're in your working directory
+- ❌ **Instability**: Leads to "hook not found" errors like you just experienced
+
+**Rule of thumb:**
+- **Development workflow**: Commit → Push → `bash scripts/refresh-marketplace.sh` (GitHub mode) → Test
+- **Emergency local testing**: Use `--local` ONLY when you need to test uncommitted changes, then immediately switch back to GitHub mode
+
 **What it does**:
 1. ✅ Removes existing marketplace
 2. ✅ Clears all plugin caches
@@ -78,22 +96,22 @@ bash scripts/refresh-marketplace.sh --github
 **Output Example**:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  SpecWeave Marketplace Refresh (local mode)
+  SpecWeave Marketplace Refresh (github mode)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 📦 Step 1: Removing existing marketplace...
 ✓ Marketplace removed
 
 🧹 Step 2: Clearing plugin caches...
-✓ Marketplace cache cleared
 ✓ Installed plugins cache backed up
 
 📥 Step 3: Adding marketplace...
-Using local development version: /Users/antonabyzov/Projects/github/specweave
-✓ Local marketplace added
+Pulling latest from GitHub: anton-abyzov/specweave
+Cloning via SSH: git@github.com:anton-abyzov/specweave.git
+✓ GitHub marketplace added
 
 📋 Step 4: Reading plugin list...
-✓ Found 19 plugins
+✓ Found 27 plugins
 
 ⚙️  Step 5: Installing all plugins...
   Installing specweave...
@@ -120,14 +138,23 @@ Next steps:
 ```
 
 **When to use**:
-- ✅ After adding new plugins
-- ✅ After modifying plugin commands/agents/skills
-- ✅ After pulling latest from GitHub
-- ✅ When plugins aren't loading correctly
-- ✅ To test local changes before pushing
+- ✅ After pushing changes to GitHub (GitHub mode - default)
+- ✅ After pulling latest from GitHub (GitHub mode)
+- ✅ When plugins aren't loading correctly (GitHub mode)
+- ✅ After adding new plugins (commit → push → refresh with GitHub mode)
+- ⚠️  To test uncommitted local changes (local mode - use sparingly!)
 
 **Time**: ~30 seconds (vs 5-10 minutes manual)
 
+**Verification after refresh**:
+```bash
+# Check marketplace source (should be "github")
+cat ~/.claude/plugins/known_marketplaces.json | jq -r '.specweave.source'
+
+# Should output: {"source": "github", "repo": "anton-abyzov/specweave"}
+# NOT: {"source": "directory", "path": "/Users/..."}
+```
+
 **Requirements**: `jq` installed (`brew install jq`)
 
 ---
@@ -204,15 +231,34 @@ Note: Published via direct push (bypassed GitHub Actions)
 
 ### 2. Increment Folder Structure
 
-**ONLY 4 files in `.specweave/increments/####/` root**: `spec.md`, `plan.md`, `tasks.md`, `metadata.json`
+**CRITICAL RULES**:
+
+**At `.specweave/increments/` root - ONLY 3 things allowed**:
+1. Numbered increment folders: `####-increment-name/` (e.g., `0053-safe-feature-deletion/`)
+2. Archive folder: `_archive/`
+3. README.md (optional documentation)
+
+**❌ NOT ALLOWED at root**: `_working/`, `reports/`, `logs/`, `scripts/`, or ANY other folders/files
+
+**Inside each increment folder - ONLY 4 files at root**: `spec.md`, `plan.md`, `tasks.md`, `metadata.json`
 
 **Everything else → subfolders**: `reports/`, `scripts/`, `logs/`
 
 ```bash
+# ❌ WRONG: .specweave/increments/_working/fix/
+# ❌ WRONG: .specweave/increments/reports/
 # ❌ WRONG: .specweave/increments/0046/analysis-report.md
 # ✅ CORRECT: .specweave/increments/0046/reports/analysis-report.md
 ```
 
+**Validation**:
+```bash
+# Check for violations at root (should output NOTHING)
+ls -1 .specweave/increments/ | grep -v "^[0-9]" | grep -v "^_archive" | grep -v "^README.md"
+```
+
+**See**: `.specweave/docs/internal/governance/increment-folder-structure.md` (complete standard)
+
 ---
 
 ### 3. Protected Directories
@@ -351,6 +397,109 @@ Edit("spec.md", "...", "...\n\n## Acceptance Criteria\n\n...")
 
 ---
 
+### 7b. AC Sync Parser - Task Status Format (CRITICAL - v0.25.2+) 🔥
+
+**CRITICAL BUG FIXED 2025-11-24**: AC sync hook was only detecting list format checkboxes, missing field format entirely!
+
+**The Bug**: Parser in `ac-status-manager.ts` only looked for `- [x]` list items, completely missing `**Status**: [x] completed` field format introduced in v0.23.0. This caused ALL 70 ACs in increment 0053 to show false "0% tasks complete" even though tasks.md showed 37/37 completed!
+
+**Impact**:
+- ❌ Data integrity violation (metadata.json polluted with false conflicts)
+- ❌ Violated Source of Truth principle (tasks.md said "done", hook said "0%")
+- ❌ Potential for closing increments with incomplete work (hook gave false positives)
+
+**Root Cause** (before fix):
+```typescript
+// ac-status-manager.ts:137 (BROKEN - only detected list format!)
+if (currentTaskId && line.includes('- [')) {  // ❌ MISSED FIELD FORMAT!
+  if (line.includes('- [ ]')) {
+    hasUncheckedBoxes = true;
+  } else if (line.includes('- [x]')) {
+    hasCheckedBoxes = true;
+  }
+}
+```
+
+**The Fix** (v0.25.2):
+```typescript
+// Now supports BOTH formats!
+if (currentTaskId) {
+  // 1. List format: - [x] or - [ ]
+  if (line.includes('- [')) {
+    if (line.includes('- [ ]')) {
+      hasUncheckedBoxes = true;
+    } else if (line.includes('- [x]')) {
+      hasCheckedBoxes = true;
+    }
+  }
+  // 2. Field format: **Status**: [x] completed (NEW!)
+  else if (line.match(/\*\*Status\*\*:\s*\[x\]/i)) {
+    hasCheckedBoxes = true;
+  }
+  // 3. Field format: **Status**: [ ] pending (NEW!)
+  else if (line.match(/\*\*Status\*\*:\s*\[\s\]/i)) {
+    hasUncheckedBoxes = true;
+  }
+}
+```
+
+**Supported Task Formats** (both work now):
+
+**Format 1: List items** (legacy, still supported):
+```markdown
+### T-001: Task Title
+**Satisfies ACs**: AC-US1-01
+- [x] Completed
+- [x] Done
+```
+
+**Format 2: Field format** (v0.23.0+, NOW WORKS!):
+```markdown
+### T-001: Task Title
+**User Story**: US-001
+**Satisfies ACs**: AC-US1-01
+**Priority**: P1
+**Status**: [x] completed  ← THIS NOW WORKS!
+```
+
+**Validation** (ensure fix is present):
+```bash
+# Check parser supports field format
+grep -A 5 "Check for field format" src/core/increment/ac-status-manager.ts
+
+# Should see: line.match(/\*\*Status\*\*:\s*\[x\]/i)
+```
+
+**Regression Tests** (5 new tests added):
+```bash
+npm test -- ac-status-manager.test.ts -t "Task status field format"
+
+# Tests:
+# 1. Field format detection (completed)
+# 2. Field format detection (incomplete)
+# 3. Mixed format support (field + list)
+# 4. Case-insensitive matching
+# 5. Real-world increment 0053 format
+```
+
+**Incident** (2025-11-24, Increment 0053):
+- All 70 ACs showed "AC-USXX-YY: [x] but only 0/1 tasks complete (0%)"
+- tasks.md clearly showed 37/37 tasks with `**Status**: [x] completed`
+- Hook logged 280 conflict messages (4 acSyncEvents × 70 conflicts each)
+- Fix: Updated parser → rebuilt → verified 0 conflicts
+
+**Prevention**:
+- ✅ 5 comprehensive regression tests (tests/unit/ac-status-manager.test.ts:855-1051)
+- ✅ Tests include real-world increment 0053 format
+- ✅ CI/CD runs all 43 AC status manager tests on every commit
+- ✅ Emergency recovery guide: `.specweave/docs/internal/emergency-procedures/AC-SYNC-CONFLICT-FIX-2025-11-24.md`
+
+**CRITICAL**: When introducing new task formats, ALWAYS update ALL parsers and add regression tests!
+
+**See**: Emergency fix report (AC-SYNC-CONFLICT-FIX-2025-11-24.md), increment 0053 metadata.json (acSyncEvents)
+
+---
+
 ### 8. Logger Abstraction (NEVER `console.*`)
 
 **Rule**: ALL `src/` code uses logger injection, NEVER `console.log/error/warn`
@@ -711,8 +860,10 @@ await provider.createRepository({ owner, name, description, visibility }, token)
 
 **Platform Support**:
 - ✅ GitHub (fully supported): `github-provider.ts`
-- ⏳ GitLab (stub): `gitlab-provider.ts` (throws "coming soon" error)
-- ⏳ Bitbucket (stub): `bitbucket-provider.ts` (throws "coming soon" error)
+- ✅ GitLab (fully supported): `gitlab-provider.ts`
+- ✅ Bitbucket (fully supported): `bitbucket-provider.ts`
+- ✅ Azure DevOps (fully supported): `azure-devops-provider.ts`
+- ✅ Local Git (fully supported): `local-provider.ts`
 
 **Adding new platform**:
 1. Create `src/core/repo-structure/providers/{platform}-provider.ts`
@@ -776,9 +927,12 @@ plugins/                # Skills, agents, commands, hooks
 **Critical incidents**:
 - 2025-11-22 - Multiple Claude Code crashes due to hook overhead
 - 2025-11-23 - Hook process storm (6 hooks per Edit/Write → 300 processes/min)
-- 2025-11-24 - PROJECT_ROOT order bug (recursion guard at wrong path → crashes)
+- 2025-11-24 (AM) - PROJECT_ROOT order bug (recursion guard at wrong path → crashes)
+- **2025-11-24 (PM) - TodoWrite crash: US sync triggers unguarded external tool cascade → infinite recursion** ⚠️
 
-**Root cause**: Process exhaustion from spawning 6 bash processes per Edit/Write operation
+**Root cause**:
+- **Original**: Process exhaustion from spawning 6 bash processes per Edit/Write operation
+- **NEW (v0.25.1)**: US completion orchestrator triggers `livingDocsSync.syncIncrement()` which calls `syncToExternalTools()` without checking `SKIP_GITHUB_SYNC` → Edit/Write operations → new hook chains → infinite recursion → crash
 
 **LONG-TERM FIX (v0.25.0)**: Hook Consolidation
 - **Reduced from 6 → 4 hooks per Edit/Write** (33% reduction)
@@ -981,6 +1135,93 @@ echo "RECURSION_GUARD_FILE: line $guard_line"
 
 ---
 
+### TodoWrite Crash (v0.25.1 - EMERGENCY FIX) ⚠️
+
+**CRITICAL BUG**: Marking tasks complete via TodoWrite crashes Claude Code due to unguarded external tool sync cascade.
+
+**Incident** (2025-11-24 PM): User reported Claude Code crash when marking tasks complete in increment 0053-safe-feature-deletion.
+
+**Root Cause**:
+1. US completion orchestrator (`us-completion-orchestrator.js`) detects all 6 USs as "newly complete" (perfect storm when last task marked)
+2. Calls `livingDocsSync.syncIncrement()` without checking `SKIP_US_SYNC` flag
+3. Living docs sync calls `syncToExternalTools()` without checking `SKIP_GITHUB_SYNC` flag
+4. External tool sync creates/updates GitHub issues (Edit/Write operations)
+5. Edit/Write hooks trigger NEW hook chains (recursion guard doesn't protect Edit/Write events)
+6. **Infinite recursion** → Process exhaustion → Claude Code crash
+
+**Crash Flow**:
+```
+TodoWrite → post-task-completion.sh
+  → consolidated-sync.js (operation 5/6)
+    → us-completion-orchestrator.js
+      → livingDocsSync.syncIncrement()
+        → syncToExternalTools() ← NO GUARD!
+          → syncToGitHub()
+            → Edit/Write operations
+              → NEW HOOK CHAIN
+                → INFINITE RECURSION
+                  → 💥 CRASH
+```
+
+**Emergency Hotfix** (v0.25.1 - ✅ DEPLOYED):
+```bash
+# File: plugins/specweave/hooks/post-task-completion.sh (line 463)
+export SKIP_US_SYNC=true
+```
+
+**Impact**:
+- ✅ **NO MORE CRASHES**: TodoWrite is now safe
+- ⚠️  **Manual sync required**: Must run `/specweave:sync-progress` after completing tasks
+- ✅ **Living docs still work**: AC sync, tasks.md updates, status line all function
+
+**Verification**:
+```bash
+# 1. Check hotfix applied
+grep "SKIP_US_SYNC=true" plugins/specweave/hooks/post-task-completion.sh
+
+# 2. Test task completion
+TodoWrite([{ content: "T-001", status: "completed" }])
+
+# 3. Verify no crash
+tail -50 .specweave/logs/hooks-debug.log | grep "SKIP_US_SYNC"
+# Expected: ℹ️  User story sync skipped (SKIP_US_SYNC=true)
+
+# 4. Manual sync when ready
+/specweave:sync-progress 0053
+```
+
+**Long-Term Fix** (v0.26.0 - PLANNED):
+- **Tier 1**: Add `SKIP_EXTERNAL_SYNC` check in `LivingDocsSync.syncIncrement()`
+- **Tier 2**: Universal recursion guard (ALL hooks check same guard file)
+- **Tier 3**: Smart throttling (60-second window for US sync)
+- **Result**: Restore automatic US sync (now safe with guard rails!)
+
+**Recovery** (If crash occurs):
+```bash
+# 1. Kill stuck processes
+ps aux | grep -E "consolidated-sync|us-completion" | awk '{print $2}' | xargs kill -9
+
+# 2. Disable hooks
+export SPECWEAVE_DISABLE_HOOKS=1
+
+# 3. Clean locks
+rm -rf .specweave/state/.hook-*.lock
+rm -f .specweave/state/.hook-recursion-guard
+
+# 4. Apply hotfix (see above)
+
+# 5. Re-enable hooks
+unset SPECWEAVE_DISABLE_HOOKS
+```
+
+**See**:
+- `.specweave/increments/0053-safe-feature-deletion/reports/EXECUTIVE-SUMMARY-CRASH-FIX-2025-11-24.md` (Executive summary)
+- `.specweave/increments/0053-safe-feature-deletion/reports/ROOT-CAUSE-ANALYSIS-TODOWRITE-CRASH-2025-11-24.md` (Detailed analysis)
+- `.specweave/docs/internal/emergency-procedures/TODOWRITE-CRASH-RECOVERY.md` (Recovery guide)
+- `.specweave/docs/internal/architecture/adr/0129-us-sync-guard-rails.md` (ADR-0129)
+
+---
+
 ## Development Workflow
 
 **Core commands**:
@@ -988,10 +1229,19 @@ echo "RECURSION_GUARD_FILE: line $guard_line"
 /specweave:increment "feature"  # Plan
 /specweave:do                   # Execute
 /specweave:progress             # Status
+/specweave:sync-progress        # Comprehensive sync (tasks → docs → external tools)
 /specweave:done 0002            # Close (validates)
 /specweave:validate 0001        # Validate
 /specweave:qa 0001              # Quality check
 /specweave:pause/resume/abandon # State management
+
+# Feature deletion
+specweave delete-feature FS-042 --dry-run    # Preview deletion
+specweave delete-feature FS-042              # Safe deletion (requires confirmation)
+specweave delete-feature FS-042 --force      # Force delete (orphans active increments)
+specweave delete-feature FS-042 --no-git     # Skip git operations
+specweave delete-feature FS-042 --no-github  # Skip GitHub issue cleanup
+specweave delete-feature FS-042 --yes        # Skip confirmations (except elevated)
 ```
 
 **Local setup**:
@@ -1131,6 +1381,324 @@ await configManager.update({ issueTracker: { provider: 'jira', domain: 'example.
 
 ---
 
+## Comprehensive Progress Sync (v0.25.0+)
+
+**Command**: `/specweave:sync-progress`
+
+**Purpose**: Single-button multi-system synchronization. Orchestrates complete flow from task completion → living docs → external tools (GitHub/JIRA/ADO).
+
+### What It Does
+
+**Comprehensive Sync Flow**:
+```
+tasks.md (source of truth)
+  ↓
+spec.md ACs (marked complete)
+  ↓
+Living docs (user stories updated)
+  ↓
+External tools (GitHub/JIRA/ADO synced)
+  ↓
+Status line cache (updated display)
+```
+
+**One command replaces 4 manual steps**:
+```bash
+# OLD: Manual multi-step sync (error-prone)
+/specweave:sync-acs 0053
+/specweave:sync-specs 0053
+/specweave-github:sync 0053
+/specweave:update-status
+
+# NEW: Single comprehensive sync ✅
+/specweave:sync-progress 0053
+```
+
+### Usage
+
+```bash
+# Auto-detect active increment
+/specweave:sync-progress
+
+# Explicit increment ID
+/specweave:sync-progress 0053
+
+# Dry-run mode (preview without executing)
+/specweave:sync-progress 0053 --dry-run
+
+# Skip external tools (local-only sync)
+/specweave:sync-progress 0053 --no-github --no-jira --no-ado
+```
+
+### When to Use
+
+**✅ Use /specweave:sync-progress when**:
+1. After completing tasks in tasks.md
+2. Before closing increment (`/specweave:done`)
+3. Want to update status line with latest progress
+4. Need to sync to external tools (GitHub/JIRA/ADO)
+5. After bulk task completion
+
+**❌ Don't use when**:
+1. Only need to sync ACs → Use `/specweave:sync-acs`
+2. Only need to sync docs → Use `/specweave:sync-specs`
+3. Only need to sync GitHub → Use `/specweave-github:sync`
+
+### Multi-Phase Orchestration
+
+**Phase 1: Tasks → ACs (spec.md)**
+- Reads completed tasks from tasks.md
+- Finds linked ACs via `**Satisfies ACs**` field
+- Marks ACs as complete: `[ ]` → `[x]`
+- Updates metadata.json with AC count
+
+**Phase 2: Spec → Living Docs**
+- Syncs spec.md to living docs structure
+- Updates user story completion status
+- Generates/updates feature ID if needed
+
+**Phase 3: Living Docs → External Tools**
+- **GitHub**: Closes completed user story issues, updates epic checklist
+- **JIRA**: Updates story status, transitions workflow
+- **Azure DevOps**: Updates work item state, adds comments
+
+**Phase 4: Status Line Cache**
+- Updates status line with latest completion %
+
+### Flags
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `--dry-run` | Preview without executing | `--dry-run` |
+| `--no-github` | Skip GitHub sync | `--no-github` |
+| `--no-jira` | Skip JIRA sync | `--no-jira` |
+| `--no-ado` | Skip Azure DevOps sync | `--no-ado` |
+| `--force` | Force sync even if validation fails | `--force` |
+
+### Error Handling
+
+**Graceful Degradation**:
+- **Critical errors** (AC sync, docs sync): Abort entire sync
+- **Non-critical errors** (GitHub, JIRA, ADO): Log warning, continue
+
+**Philosophy**: Core sync (tasks → docs) must succeed. External tool sync is best-effort.
+
+### Example Workflow
+
+**Typical increment workflow with progress sync**:
+
+```bash
+# 1. Plan increment
+/specweave:increment "Safe feature deletion"
+
+# 2. Execute tasks
+/specweave:do
+
+# [Complete 5 tasks...]
+
+# 3. Sync progress after batch
+/specweave:sync-progress
+
+# [Complete remaining 32 tasks...]
+
+# 4. Final sync before closure
+/specweave:sync-progress 0053
+
+# 5. Validate quality
+/specweave:validate 0053 --quality
+
+# 6. Close increment
+/specweave:done 0053
+```
+
+### External Tool Auto-Detection
+
+**Automatic detection** from `.specweave/config.json`:
+- GitHub: `"provider": "github"`
+- JIRA: `"provider": "jira"`
+- Azure DevOps: `"provider": "azure-devops"`
+
+**Only configured tools are synced**:
+```
+✅ GitHub integration detected → Will sync
+ℹ️  No JIRA integration → Skip
+ℹ️  No ADO integration → Skip
+```
+
+### Troubleshooting
+
+**"No active increment found"**:
+```bash
+# Provide increment ID explicitly
+/specweave:sync-progress 0053
+```
+
+**"AC sync had warnings: 5 ACs not found"**:
+```bash
+# Embed ACs from living docs into spec.md
+/specweave:embed-acs 0053
+
+# Then retry sync
+/specweave:sync-progress 0053
+```
+
+**"GitHub rate limit exceeded"** (non-critical):
+- Docs are synced successfully
+- Retry GitHub sync later when rate limit resets:
+  ```bash
+  /specweave-github:sync 0053
+  ```
+
+**See**:
+- Skill: `progress-sync` (comprehensive guide)
+- Increment 0053 (added in this increment)
+
+---
+
+## Safe Feature Deletion (v0.25.0+)
+
+**Command**: `specweave delete-feature <feature-id>`
+
+Safe deletion of features with multi-gate validation, automatic cleanup, and audit logging.
+
+### Usage
+
+```bash
+# Preview deletion (recommended first step)
+specweave delete-feature FS-042 --dry-run
+
+# Safe deletion (requires confirmation)
+specweave delete-feature FS-042
+
+# Force deletion (bypasses active increment validation)
+specweave delete-feature FS-042 --force
+
+# Skip git operations
+specweave delete-feature FS-042 --no-git
+
+# Skip GitHub issue cleanup
+specweave delete-feature FS-042 --no-github
+
+# Skip confirmations (except elevated confirmation in force mode)
+specweave delete-feature FS-042 --yes
+```
+
+### Safety Features
+
+**4-Tier Validation**:
+1. **Feature Detection**: Scans living docs and user stories
+2. **Active Increment Check**: Blocks deletion if active increments reference feature (safe mode)
+3. **Git Status Check**: Ensures clean working directory
+4. **GitHub Issue Scan**: Finds related issues for cleanup
+
+**3-Phase Commit Pattern**:
+1. **Validation Phase**: All safety checks
+2. **Staging Phase**: Reversible (file backup, git staging)
+3. **Commit Phase**: Irreversible (git commit, GitHub cleanup, audit log)
+
+**Multi-Gate Confirmation**:
+- Primary Confirmation: y/N prompt for all deletions
+- Elevated Confirmation: Type "delete" for force mode (orphans active increments)
+- GitHub Confirmation: Separate prompt for closing GitHub issues
+
+### What Gets Deleted
+
+✅ Living docs: `.specweave/docs/internal/specs/_features/FS-XXX/FEATURE.md`
+✅ User stories: `.specweave/docs/internal/specs/{project}/FS-XXX/us-*.md`
+✅ README files: `.specweave/docs/internal/specs/{project}/FS-XXX/README.md`
+✅ GitHub issues: Issues matching `[FS-XXX][US-YYY]` pattern (optional)
+
+❌ NOT deleted: Increments (only metadata.json updated if orphaned)
+
+### Modes
+
+**Safe Mode (default)**:
+- Blocks deletion if active increments reference feature
+- Requires clean git working directory
+- Requires explicit confirmation
+
+**Force Mode (`--force`)**:
+- Allows deletion with active increments
+- Updates orphaned increment metadata.json (removes feature_id)
+- Requires elevated confirmation (type "delete")
+
+**Dry-Run Mode (`--dry-run`)**:
+- Preview deletion without executing
+- Shows all files to be deleted
+- Shows git operations
+- Shows GitHub issues to be closed
+
+### Audit Logging
+
+All deletions logged to `.specweave/logs/feature-deletions.log` (JSON Lines format):
+
+```json
+{
+  "featureId": "FS-042",
+  "timestamp": "2025-11-24T01:45:00.000Z",
+  "user": "john-doe",
+  "mode": "safe",
+  "filesDeleted": 6,
+  "commitSha": "abc123def",
+  "githubIssuesClosed": 3,
+  "orphanedIncrements": [],
+  "status": "success"
+}
+```
+
+**Log rotation**: Automatically rotates at 10MB threshold.
+
+### Error Handling
+
+**Non-blocking errors** (logged as warnings):
+- GitHub API rate limits (exponential backoff retry)
+- GitHub issue cleanup failures
+- Audit log write failures
+
+**Blocking errors** (prevent deletion):
+- Feature not found
+- Active increments in safe mode
+- Git working directory not clean (without `--no-git`)
+- Invalid feature ID format (must be FS-XXX)
+
+### Examples
+
+```bash
+# Recommended workflow
+specweave delete-feature FS-042 --dry-run    # Preview
+specweave delete-feature FS-042              # Execute (with confirmation)
+
+# Force delete feature with active increment 0050
+specweave delete-feature FS-042 --force      # Requires typing "delete"
+
+# Delete without git commit (manual git workflow)
+specweave delete-feature FS-042 --no-git
+
+# Delete with auto-yes (CI/CD pipelines)
+specweave delete-feature FS-042 --yes --dry-run  # Still shows preview
+```
+
+### Important Notes
+
+**GitHub Integration**:
+- Owner/repo auto-detected from `git remote get-url origin`
+- If no GitHub remote → GitHub cleanup silently skipped (non-blocking)
+- Pattern detection: `https://github.com/owner/repo.git` or `git@github.com:owner/repo.git`
+
+**No Undo**:
+- Deletion is permanent (files deleted from filesystem)
+- Recovery: `git log --all --full-history -- path/to/deleted/file` → `git checkout <commit> -- path`
+- Audit log: `.specweave/logs/feature-deletions.log` (includes commit SHA)
+
+**Force Mode Risk**:
+- Orphaned increments lose `feature_id` in metadata.json
+- Breaking change: `/specweave:sync-specs` won't sync orphaned increments
+- Recovery: Manually restore `feature_id` in metadata.json
+
+**See**: Increment 0053-safe-feature-deletion for implementation details.
+
+---
+
 ## Quick Reference
 
 **Commands**: `/specweave:increment`, `/specweave:do`, `/specweave:done`, `/specweave:progress`, `/specweave:validate`, `/specweave:qa`