specweave 0.26.10 → 0.26.11

package/CLAUDE.md

@@ -2,242 +2,93 @@
 
 **Project**: SpecWeave - Spec-Driven Development Framework
 **Type**: TypeScript CLI (NPM Package)
-**Repository**: https://github.com/anton-abyzov/specweave
 
 For **contributors to SpecWeave itself** (not users).
 
 ---
 
-## 🚨 CRITICAL SAFETY RULES
+## CRITICAL SAFETY RULES
 
-### 0. Think-Then-Act Discipline (META RULE!)
+### 1. Context Management (CRASH PREVENTION!)
 
-**NEVER run commands you know will fail.** Act on reasoning BEFORE execution.
-
-**Context Management**: Active increment with 10+ tasks + editing unrelated 2000+ line file = crash risk (context overflow). Pause first: `/specweave:pause XXXX` → edit → `/specweave:resume XXXX`. See ADR-0133, Section 15.
-
-```bash
-# ❌ WRONG: node -e "require('./dist/file.js')" (before build)
-# ✅ CORRECT: npm run rebuild && node -e "require('./dist/file.js')"
-```
-
----
-
-## 1. Development Setup
-
-**Standard Workflow**:
-```bash
-git clone https://github.com/YOUR_USERNAME/specweave.git
-cd specweave && npm install && npm run rebuild
-
-# Development Cycle
-npm run rebuild && npm test
-git add . && git commit -m "feat: feature" && git push origin develop
-# Wait 5-10s → Claude Code auto-updates marketplace
-```
-
-**Testing Unpushed**: Temp branch → push → test → delete, OR `claude plugin marketplace add github:YOUR_USERNAME/specweave`
-
----
-
-### 1a. Marketplace Refresh
-
-```bash
-bash scripts/refresh-marketplace.sh          # GitHub (default, ALWAYS use)
-bash scripts/refresh-marketplace.sh --local  # Local dev only (filesystem coupling risks)
-```
-
-**Use GitHub mode**: Proper install path, stable source, no hook coupling (~30s)
-**Verify**: `jq -r '.specweave.source' ~/.claude/plugins/known_marketplaces.json` → should be `"github"`
-
-**Note**: GitHub mode shows "AC test validator not available" warning because `dist/` is gitignored. Use `--local` mode when developing hooks/validators to test with built artifacts. Regular users with `npm install specweave` won't see this (validator found in `node_modules/`).
-
----
-
-### 1b. NPM Release
+**Active increment (10+ tasks) + large file edit (2000+ lines) = CRASH**
 
 ```bash
-/specweave-release:npm         # GitHub Actions (2-3 min, recommended)
-/specweave-release:npm --only  # Direct publish (30s, emergencies)
+# Before editing large files outside increment:
+/specweave:pause XXXX → edit → /specweave:resume XXXX
+# OR close completed increments: /specweave:done XXXX
 ```
 
----
-
-## 2. Folder Structure Rules
-
-**At `.specweave/increments/` root - ONLY**:
-1. `####-increment-name/` folders
-2. `_archive/` folder
-3. `README.md` (optional)
-
-**Inside increment folders - ONLY at root**: `spec.md`, `plan.md`, `tasks.md`, `metadata.json`
-
-**Everything else → subfolders**:
-- `reports/` - Completion reports, investigation findings, final summaries
-- `scripts/` - Helper scripts, automation, migration tools
-- `logs/` - Debug logs, performance logs, execution traces
-- `backups/` - Backup files, .backup versions
-- `docs/` - Additional documentation, diagrams, references
-
-**Examples**:
-```
-0055-feature/
-├── spec.md              ✅ Required
-├── plan.md              ✅ Required
-├── tasks.md             ✅ Required
-├── metadata.json        ✅ Required
-├── reports/             ✅ Good organization
-│   ├── completion-summary.md
-│   └── FINAL-REPORT.md
-├── scripts/             ✅ Good organization
-│   └── migration.sh
-└── backups/             ✅ Good organization
-    └── SKILL.md.backup
-```
-
-```bash
-# Validation (should output NOTHING):
-ls -1 .specweave/increments/ | grep -v "^[0-9]" | grep -v "^_archive" | grep -v "^README.md"
-
-# Check for misplaced files in increment roots:
-find .specweave/increments -maxdepth 2 -type f ! -name "spec.md" ! -name "plan.md" ! -name "tasks.md" ! -name "metadata.json" | grep -E "/[0-9]{4}-"
-```
-
----
-
-## 3. Protected Directories
-
-**Never delete**: `.specweave/docs/`, `.specweave/increments/`
-**Pre-commit hook blocks**: 50+ file deletions, `rm -rf` on protected dirs
-**Recovery**: `git restore .specweave/`
-
----
-
-## 4-6. Safety Rules
-
-**4. Test Cleanup**: `pwd` check → dry-run → count → confirm → execute
-**5. NEVER**: `specweave init . --force` (deletes all without backup)
-**6. Completion**: `/specweave:done 0043` (validates), NEVER manual `metadata.json` edit
-
----
-
-## 7. Source of Truth: tasks.md + spec.md (CRITICAL!)
+### 2. Source of Truth
 
-**Internal TODO is ephemeral. tasks.md + spec.md are SOURCE OF TRUTH.**
+**tasks.md + spec.md are SOURCE OF TRUTH** (not internal TODO)
 
-**MANDATORY workflow**:
 ```typescript
-// 1. Complete work → 2. TodoWrite → 3. IMMEDIATELY Edit tasks.md → 4. IMMEDIATELY Edit spec.md
-await work();
+// After completing work - IMMEDIATELY update both:
 TodoWrite([{task: "T-013", status: "completed"}]);
 Edit("tasks.md", "**Status**: [ ] pending", "**Status**: [x] completed");
 Edit("spec.md", "- [ ] **AC-US1-01**", "- [x] **AC-US1-01**");
 ```
 
-**Status Line Sync**: TodoWrite → `post-task-completion.sh` → cache updates
-**GitHub Duplicates**: Use `DuplicateDetector.createWithProtection()`, NEVER `--limit 1` in gh searches
-**Validation**: `/specweave:validate-status`
+### 3. Protected Directories
 
-**Pre-closure check**:
-```bash
-grep "^\*\*Status\*\*:" tasks.md | grep -c "\[x\] completed"  # Must equal total
-grep -c "^- \[x\] \*\*AC-" spec.md                            # Must equal total ACs
-```
-
----
+**NEVER delete**: `.specweave/docs/`, `.specweave/increments/`
+**NEVER run**: `specweave init . --force` (deletes all without backup)
 
-### 7a. AC Presence in spec.md (MANDATORY)
+### 4. Skills Must NOT Spawn Large Agents
 
-**spec.md MUST contain inline ACs** even with external living docs. AC sync hook requires them.
-
-**Required Format**:
-```markdown
-## Acceptance Criteria
-<!-- Auto-synced from living docs -->
-### US-001: Title
-- [ ] **AC-US1-01**: Description
-```
-
-**If missing**: `/specweave:embed-acs 0050` (auto-embeds from living docs)
-**Validation**: `/specweave:do` blocks if ACs missing
-
----
-
-### 7b. AC Sync Parser (v0.25.2)
-
-**Both formats supported**: `- [x] Done` (legacy list) OR `**Status**: [x] completed` (field format)
-
----
-
-## 8. Logger Abstraction
-
-**Rule**: ALL `src/` code uses logger injection, NEVER `console.*`
+**Skills spawning content-generating agents = CRASH** (context explosion)
 
 ```typescript
-import { Logger, consoleLogger } from '../../utils/logger.js';
-constructor(options: { logger?: Logger } = {}) {
-  this.logger = options.logger ?? consoleLogger;
-}
-```
-
-**Exception**: `src/cli/commands/*.ts` may use `console.*` with comment explaining it's user-facing output
-
----
-
-### 8a. Native fs
-
-**Use native Node.js `fs`, NEVER `fs-extra`**
+// ❌ FORBIDDEN in skills:
+Task({ subagent_type: "specweave:architect:architect" }); // 1000-3000 lines output
 
-```typescript
-// ✅ CORRECT
-import { existsSync, readFileSync } from 'fs';
-import { promises as fs } from 'fs';
-import { mkdirpSync, writeJsonSync } from '../utils/fs-native.js';
+// ✅ CORRECT: Skills create templates, guide user to invoke agents in main context
 ```
 
 ---
 
-## 9. Coding Standards
+## Development Setup
 
-**Critical rules (enforced)**:
-1. NEVER `console.*` (use logger)
-2. ALWAYS `.js` extensions in imports
-3. Test files: `.test.ts` (NEVER `.spec.ts`)
-4. Avoid `any` type
-5. Functions < 100 lines
-6. Custom error types
-7. Comment "why" not "what"
-8. No hardcoded secrets
-9. No N+1 queries
-10. Naming: camelCase (vars), PascalCase (classes), UPPER_SNAKE_CASE (constants)
+```bash
+npm install && npm run rebuild
+npm run rebuild && npm test
+git add . && git commit -m "feat: feature" && git push origin develop
+```
 
-**Auto-discovery**: `/specweave:analyze-standards`
+**Marketplace**: `bash scripts/refresh-marketplace.sh` (GitHub mode, always use)
+**NPM Release**: `/specweave-release:npm`
 
 ---
 
-## 10. GitHub Issue Format
-
-**ONLY Correct Format**: `[FS-XXX][US-YYY] User Story Title`
+## Coding Standards
 
-**PROHIBITED**: `[SP-*]`, `[FS-XXX]` alone, `[undefined][US-XXX]`, project suffixes
-
-**Architecture**: Feature → Milestone, User Stories → Issues
-
-**Create**: `/specweave-github:sync FS-048`
+1. **Logger injection**: ALL `src/` code uses `logger`, NEVER `console.*`
+   ```typescript
+   import { Logger, consoleLogger } from '../../utils/logger.js';
+   constructor(options: { logger?: Logger } = {}) {
+     this.logger = options.logger ?? consoleLogger;
+   }
+   ```
+2. **Imports**: ALWAYS `.js` extensions
+3. **Tests**: `.test.ts` files, `vi.fn()` (not jest), `os.tmpdir()` (not cwd)
+4. **Filesystem**: Native `fs` only (NEVER `fs-extra`)
+5. **Code**: Functions < 100 lines, avoid `any`, custom error types
 
 ---
 
-### 10a. NO Increment-to-Increment References (ADR-0061)
+## Folder Structure
 
-**FORBIDDEN**: User stories referencing increments (`increments: [0050-...]`)
-**ONLY ALLOWED**: `INCREMENT → FEATURE → USER STORIES` (forward reference only)
+**At `.specweave/increments/` root - ONLY**: `####-name/` folders, `_archive/`, `README.md`
 
-**Why**: Hooks break, circular dependencies, multi-increment support broken
+**Inside increment folders - ONLY at root**: `spec.md`, `plan.md`, `tasks.md`, `metadata.json`
+**Everything else → subfolders**: `reports/`, `scripts/`, `logs/`, `backups/`, `docs/`
 
 ---
 
-## 11. Task Format with US Linkage
+## Key Formats
 
+### Task Format (MANDATORY)
 ```markdown
 ### T-001: Task Title
 **User Story**: US-001           ← MANDATORY
@@ -245,383 +96,107 @@ import { mkdirpSync, writeJsonSync } from '../utils/fs-native.js';
 **Status**: [x] completed
 ```
 
----
-
-## 12. ADR Naming
-
-**Format**: `XXXX-decision-title.md` (4-digit, kebab-case, NO `adr-` prefix)
-**Header**: `# ADR-XXXX: Decision Title`
-**Location**: `.specweave/docs/internal/architecture/adr/`
-
-**Auto-numbering**:
-```bash
-ls .specweave/docs/internal/architecture/adr/*.md | grep -E '/[0-9]{4}-' | \
-  sed 's/.*\/\([0-9][0-9][0-9][0-9]\)-.*/\1/' | sort -u | tail -1 | \
-  awk '{printf "Next ADR: %04d\n", $1 + 1}'
-```
-
----
-
-## 13. Structured Data Matching
+### GitHub Issue Format
+**ONLY**: `[FS-XXX][US-YYY] User Story Title`
+**PROHIBITED**: `[SP-*]`, `[FS-XXX]` alone, `[undefined][US-XXX]`
 
-**NEVER use string search for frontmatter/IDs**:
-
-```typescript
-// ❌ WRONG: content.includes('FS-039')  // Matches "See FS-039"!
-// ✅ CORRECT: const match = content.match(/^feature_id:\s*["']?([^"'\n]+)["']?$/m);
-```
-
----
-
-## 14. Marketplace Plugin Completeness
-
-**Complete plugin requires**: `agents/`, `commands/`, OR `lib/` (not just `.claude-plugin/` + `skills/`)
-
-**MANDATORY**: `bash scripts/validate-marketplace-plugins.sh`
-
----
-
-## 15. Skills vs Agents
-
-| Aspect | Skills | Agents |
-|--------|--------|--------|
-| **Location** | `plugins/*/skills/name/SKILL.md` | `plugins/*/agents/name/AGENT.md` |
-| **Invocation** | `Skill()` or `/command` | `Task()` with `subagent_type` |
-| **Activation** | Automatic (keywords) | Explicit |
-
-**Agent naming**: `{plugin}:{directory}:{yaml-name}`
-
-### Skills Must NOT Spawn Large Content-Generating Agents (ADR-0133)
-
-**CRITICAL**: Skills spawning agents via `Task()` causes Claude Code crashes due to context explosion.
-
-**Problem**: Skill (1500 lines) + Agent (600 lines) + Agent output (2000+ lines) = 4000+ lines in memory = CRASH 💥
-
-**❌ FORBIDDEN**:
-```typescript
-// In a skill SKILL.md:
-Task({
-  subagent_type: "specweave:architect:architect",  // ❌ Generates 1000-3000 lines
-  subagent_type: "specweave:pm:pm",                // ❌ Generates 500-2000 lines
-  subagent_type: "specweave:test-aware-planner",   // ❌ Generates 500-1500 lines
-});
-```
-
-**✅ CORRECT**:
-```typescript
-// Skills create templates and guide users:
-1. Create basic templates (< 50 lines each)
-2. Output: "Tell Claude: 'Complete the spec for increment 0005-feature'"
-3. Agents activate in MAIN context (not nested) = SAFE
-```
-
-**When to use Task() from skills**:
-- ✅ Small utility agents (output < 200 lines)
-- ✅ Data processing agents (no large generation)
-- ❌ Content generators (specs, ADRs, plans, tasks)
-
-**Main Context Pattern**: Same explosion occurs when editing files outside active increments. Large increment spec (800+ lines) + unrelated file edit (2000+ lines) + tool invocation (AskUserQuestion) = crash. Solution: Pause increment before editing unrelated files (see Section 0).
-
-**Reference**: ADR-0133, Architect crash incident (2025-11-24, Increment 0052); Context explosion incident (2025-11-24, Increment 0058, init.ts edit)
-
----
-
-## 16. YAML Frontmatter
-
-**Required**:
+### YAML Frontmatter (spec.md)
 ```yaml
 ---
-increment: 0001-feature-name  # REQUIRED: 4-digit + kebab-case
+increment: 0001-feature-name  # REQUIRED
 feature_id: FS-001            # OPTIONAL
 ---
 ```
 
-**Validation**: Pre-commit hook, spec parser, `/specweave:validate 0001`
+### ADR Naming
+**Format**: `XXXX-decision-title.md` (4-digit, NO `adr-` prefix)
+**Location**: `.specweave/docs/internal/architecture/adr/`
 
 ---
 
-## 17. Git Provider Abstraction
+## Important Rules
 
-**Interface-driven multi-platform support**:
-- GitHub, GitLab, Bitbucket, Azure DevOps, Local Git
+### NO Increment-to-Increment References
+**FORBIDDEN**: User stories referencing increments (`increments: [0050-...]`)
+**ONLY ALLOWED**: `INCREMENT → FEATURE → USER STORIES` (forward reference only)
 
-**Usage**:
+### Structured Data Matching
 ```typescript
-import { getPlatformRegistry } from './platform-registry.js';
-const provider = registry.getProvider('github');
-const result = await provider.validateRepository('owner', 'repo', token);
+// ❌ WRONG: content.includes('FS-039')  // Matches "See FS-039"!
+// ✅ CORRECT: content.match(/^feature_id:\s*["']?([^"'\n]+)["']?$/m)
 ```
 
-**NEVER**: Hardcode platform names, API endpoints, Git hosts
-
----
-
-### 17a. GitHub Multi-Repo Init Flow (v0.26.3 - ADR-0132)
+### GitHub Duplicates
+Use `DuplicateDetector.createWithProtection()`, NEVER `--limit 1` in gh searches
 
-**Rule**: NEVER early returns in routing code. Use mapping.
+### AC Presence in spec.md
+**MANDATORY** - even with external living docs. Use `/specweave:embed-acs` if missing.
 
-```typescript
-// ❌ if (option === 'advanced') return { type: 'basic' };
-// ✅ let mapped = undefined; if (option === 'advanced') mapped = 'enhanced';
-```
+### Git Provider Abstraction
+Use `getPlatformRegistry().getProvider('github')`. NEVER hardcode platform names/endpoints.
 
 ---
 
-## Sync Orchestration Architecture (v0.26.3+)
-
-### **How GitHub Issue Sync Works**
-
-**3-Phase Sync Flow**:
-```
-TodoWrite → Hook → US Completion Orchestrator → Living Docs Sync → External Tool Sync → GitHub Issues Updated
-```
-
-**Phase 1: Task Completion Detection**
-- User marks task complete via `TodoWrite`
-- `post-task-completion.sh` fires (sets `SKIP_GITHUB_SYNC=true` to prevent duplicate syncs)
-- `consolidated-sync.js` runs 6 operations sequentially
-
-**Phase 2: US Completion Orchestration**
-- `syncCompletedUserStories()` (operation 5 of 6) detects newly completed user stories
-- Checks if all ACs for a US are complete (100% → status: "completed")
-- **Throttle**: 60s window prevents spam (manual override: `/specweave:sync-progress`)
-- If newly completed USs found → triggers Phase 3
-
-**Phase 3: External Tool Sync**
-- `LivingDocsSync.syncIncrement()` called
-- `detectExternalTools()` checks **3 levels** for GitHub config:
-  - **Level 1**: `metadata.json` (increment-cached links)
-  - **Level 2**: `config.json` - **4 detection methods** (ADR-0137):
-    - Method 1: `config.sync.github.enabled` ← **Most common (60% of users)**
-    - Method 2: `config.sync.profiles[activeProfile]` ← Multi-profile setups
-    - Method 3: `config.multiProject.projects[project].externalTools.github` ← Multi-project
-    - Method 4: `config.plugins.settings['specweave-github']` ← Legacy
-  - **Level 3**: Environment variables (`GITHUB_TOKEN` + `GITHUB_OWNER`/`GITHUB_REPOSITORY`)
-- If GitHub detected → `syncToGitHub()` → `GitHubFeatureSync.syncFeatureToGitHub()`
-- Updates GitHub issues with completed AC checkboxes
-
-### **GitHub Configuration (Required)**
-
-**Recommended Setup (Pattern 1 - Simplest)**:
-```json
-// .specweave/config.json
-{
-  "sync": {
-    "github": {
-      "enabled": true,
-      "owner": "your-org",
-      "repo": "your-repo"
-    }
-  }
-}
-```
-
-**Plus `.env`**:
-```bash
-GITHUB_TOKEN=ghp_your_token_here
-GITHUB_OWNER=your-org  # Optional if in config.json
-GITHUB_REPO=your-repo  # Optional if in config.json
-```
-
-**Diagnostic**: Run `node dist/test-github-detection.js` to verify detection (create this file if needed)
+## Configuration
 
-### **Troubleshooting Sync Issues**
-
-**Issue**: GitHub issues not updating after US completion
-**Diagnosis**:
-```bash
-# 1. Check detection
-grep "External tools detected" .specweave/logs/hooks-debug.log | tail -5
-# Should see: "📡 External tools detected: github"
-
-# 2. Check config
-cat .specweave/config.json | jq '.sync.github'
-# Should have: enabled: true, owner: "...", repo: "..."
-
-# 3. Check throttle
-grep "throttled" .specweave/logs/hooks-debug.log | tail -3
-# If throttled → wait 60s OR run: /specweave:sync-progress
-```
-
-**Issue**: Throttle blocking sync
-**Solution**: Manual sync (bypasses throttle):
-```bash
-/specweave:sync-progress 0054  # Sync specific increment
-/specweave-github:sync FS-054   # Sync entire feature
-```
-
-**Issue**: Detection not finding GitHub config
-**Fix**: ADR-0137 enhanced detection (v0.26.3+)
-- Checks 4 config locations + env vars
-- Update to latest version: `npm update specweave`
-
-## Hook Performance & Safety
-
-**Emergency**: `export SPECWEAVE_DISABLE_HOOKS=1` → `rm -f .specweave/state/.hook-*` → `npm run rebuild`
-
-**Mandatory Checklist**: PROJECT_ROOT first, kill switch, circuit breaker, file lock, debounce (5s), `set +e`, `exit 0`, active-only filtering
-**Never**: `set -e`, sync spawns, error propagation
-**Targets**: <100ms, 0-2 processes, 0 breaker trips
-
-**Critical Fixes**:
-- v0.26.3: **Multi-location GitHub config detection!** (ADR-0137) → Checks 4 config patterns + env vars
-- v0.26.1: **Automatic US sync restored!** `SKIP_US_SYNC` removed → Smart throttle (60s window) → fs.writeFile() validated safe
-- v0.25.2: `SKIP_EXTERNAL_SYNC` guard at LivingDocsSync layer → prevents recursion cascade
-- v0.25.1: TodoWrite crash → emergency `SKIP_US_SYNC=true` → manual `/specweave:sync-progress` (temporary fix)
-- v0.25.0: 6→4 hooks (33% reduction)
-- v0.24.4: State-based filtering (95% overhead reduction)
-- v0.26.1: PROJECT_ROOT before RECURSION_GUARD_FILE (order bug fix)
+**Secrets** (`.env`, gitignored): Tokens, PATs, emails
+**Config** (`.specweave/config.json`, committed): Domains, strategies, sync settings
 
 ---
 
-## Development Workflow
+## Commands
 
-**Core commands**:
 ```bash
-/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
-
-# Feature deletion
-specweave delete-feature FS-042 --dry-run  # Preview
-specweave delete-feature FS-042            # Safe delete (requires confirmation)
-specweave delete-feature FS-042 --force    # Force (orphans active increments)
+/specweave:increment "feature"  # Plan new increment
+/specweave:do                   # Execute tasks
+/specweave:done 0002            # Close (validates gates)
+/specweave:progress             # Show status
+/specweave:sync-progress        # Full sync (tasks→docs→GitHub/JIRA/ADO)
+/specweave:validate 0001        # Validate increment
 ```
 
 ---
 
 ## Build & Test
 
-**Build**: `npm run rebuild` (clean + build), `npm run build`
-**Architecture**: `tsc` → `dist/src/`, esbuild → hooks, copy deps → `plugins/*/lib/vendor/`
-**CRITICAL**: Always `.js` extensions in imports
-
-**Test**:
 ```bash
-npm test                 # Smoke
-npm run test:unit        # Unit
-npm run test:integration # Integration
-npm run test:all         # All
-npm run test:coverage    # Coverage (80%+ required)
+npm run rebuild     # Clean + build (tsc → dist/, esbuild → hooks)
+npm test            # Smoke tests
+npm run test:all    # All tests (80%+ coverage required)
 ```
 
-**Test rules**: `vi.fn()` (NOT `jest.fn()`), `os.tmpdir()` (NOT `process.cwd()`), `.test.ts` (NOT `.spec.ts`)
-
----
-
-## Configuration Management
-
-**Secrets** (.env, gitignored) vs **Config** (.specweave/config.json, committed)
-
-| Type | Location | Committed? |
-|------|----------|------------|
-| Tokens/Emails | `.env` | ❌ |
-| Domains/Strategies | `config.json` | ✅ |
-
----
-
-## Cache Management
-
-**Location**: `.specweave/cache/`, **TTL**: 24 hours
-
-**Cached**: JIRA projects, ADO config, boards, components (NOT tokens/PATs)
-
-**Manual**: `/specweave-jira:refresh-cache --all`, `/specweave:cleanup-cache --older-than 7d`
-
----
-
-## Comprehensive Progress Sync
-
-**Command**: `/specweave:sync-progress [increment]`
-
-**Flow**: tasks.md → spec.md ACs → living docs → external tools (GitHub/JIRA/ADO) → status line
-
-**Replaces 4 commands**: `/specweave:sync-acs` + `/specweave:sync-specs` + `/specweave-github:sync` + `/specweave:update-status`
-
-**Flags**: `--dry-run`, `--no-github`, `--no-jira`, `--no-ado`, `--force`
-
-**When to use**: After completing tasks, before closing increment, bulk completion
-
----
-
-## Safe Feature Deletion
-
-**Command**: `specweave delete-feature <feature-id>`
-
-**4-Tier Validation**: Feature detection → active increment check → git status → GitHub scan
-**3-Phase Commit**: Validation → staging (reversible) → commit (irreversible)
-**Multi-Gate Confirmation**: Primary (y/N) → elevated (type "delete" in force mode) → GitHub (separate)
-
-**Deletes**: Living docs FEATURE.md, user stories, README, GitHub issues
-**NOT deleted**: Increments (metadata.json updated if orphaned)
-
-**Modes**: Safe (default, blocks active increments), Force (`--force`, orphans increments), Dry-run (`--dry-run`, preview)
-
-**Audit**: `.specweave/logs/feature-deletions.log` (JSON Lines, includes commit SHA)
+**Plugin validation**: `bash scripts/validate-marketplace-plugins.sh`
 
 ---
 
-## Project Structure
+## Emergency
 
+```bash
+export SPECWEAVE_DISABLE_HOOKS=1
+rm -f .specweave/state/.hook-*
+npm run rebuild
 ```
-src/                    # TypeScript → dist/
-plugins/                # Skills, agents, commands, hooks
-├── specweave/          # Core
-└── specweave-*/        # Optional
-.specweave/             # Increments, docs, logs
-```
-
----
 
-## Plugin Hook Registration
-
-**Valid events** (10): PostToolUse, PreToolUse, PermissionRequest, Notification, UserPromptSubmit, Stop, SubagentStop, PreCompact, SessionStart, SessionEnd
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [{
-      "matcher": "TodoWrite",
-      "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh", "timeout": 10 }]
-    }]
-  }
-}
-```
+**Recovery docs**: `.specweave/docs/internal/emergency-procedures/`
 
 ---
 
 ## Quick Reference
 
-**Commands**: `/specweave:increment`, `/specweave:do`, `/specweave:done`, `/specweave:progress`, `/specweave:validate`, `/specweave:qa`
-
-**Build**: `npm run rebuild`, `npm test`, `npm run test:all`
-
-**Structure**: `src/` (TS), `plugins/` (components), `.specweave/` (data), `tests/` (tests)
-
-**Remember**:
-1. Push → GitHub → auto-updates (5-10s)
-2. **Keep increment roots clean**: Only spec.md, plan.md, tasks.md, metadata.json. Everything else in subfolders (reports/, scripts/, logs/, backups/, docs/)
-3. Test before commit
-4. NEVER delete `.specweave/`
-5. Use `/specweave:done` (not manual edits)
-6. ALWAYS use GitHub mode for marketplace refresh (unless actively developing uncommitted changes)
-7. tasks.md + spec.md are SOURCE OF TRUTH (not internal TODO)
-8. Pause large increments (10+ tasks) before editing unrelated files to prevent crashes
-
-**See**: `.github/CONTRIBUTING.md`, https://spec-weave.com
+| Aspect | Rule |
+|--------|------|
+| Skills vs Agents | Skills = auto-activate (keywords), Agents = explicit `Task()` |
+| Hook events | PostToolUse, PreToolUse, UserPromptSubmit, Stop, SessionStart/End, etc. |
+| Cache location | `.specweave/cache/` (24h TTL) |
+| Pre-commit | Blocks 50+ deletions, `rm -rf` on protected dirs |
 
 ---
 
 ## References
 
-**ADRs**: 0032 (GitHub Hierarchy), 0050 (Config Management), 0051 (Caching), 0060 (Hook Optimization), 0061 (No Increment References), 0064 (AC Presence), 0069 (Git Provider Abstraction), 0070 (Hook Consolidation), 0129 (US Sync Guard Rails), 0132 (No Early Returns)
-
-**Emergency Procedures**: `.specweave/docs/internal/emergency-procedures/HOOK-CRASH-RECOVERY.md`, `TODOWRITE-CRASH-RECOVERY.md`, `AC-SYNC-CONFLICT-FIX-2025-11-24.md`, `CONTEXT-EXPLOSION-PREVENTION.md`
-
-**Incident Reports**: See increment 0044 (TODO desync), 0047 (GitHub sync removal), 0050 (Hook crashes, AC presence, GitHub issues), 0051 (PROJECT_ROOT order), 0053 (Safe deletion, TodoWrite crash, AC parser, GitHub multi-repo), 0058 (Context explosion, init.ts edit crash)
+**Internal Docs**: `.specweave/docs/internal/`
+- `sync-architecture.md` - GitHub sync flow, troubleshooting
+- `architecture/adr/` - Decision records (ADR-0032, 0060, 0129, etc.)
+- `emergency-procedures/` - Crash recovery guides
 
-**Validation Scripts**: `validate-marketplace-plugins.sh`, `validate-plugin-directories.sh`, `validate-hook-variable-order.sh`, `cleanup-duplicate-github-issues.sh`
+**External**: `.github/CONTRIBUTING.md`, https://spec-weave.com