specweave 0.32.0 → 0.32.3

package/CLAUDE.md

@@ -111,6 +111,63 @@ const config = detectStructureLevel(projectRoot);
 
 **Pre-tool-use hook `spec-project-validator.sh` BLOCKS spec.md without required fields (2-level).**
 
+### 2d. NEVER Create Files in _features/ Folder (OBSOLETE v5.0.0+)
+
+**The `_features/` folder is OBSOLETE!** Features MUST live in project folders:
+
+```
+❌ FORBIDDEN (Bug pattern from 2025-12-06):
+.specweave/docs/internal/specs/_features/FS-116/FEATURE.md
+
+✅ CORRECT:
+.specweave/docs/internal/specs/{project}/FS-116/FEATURE.md
+```
+
+**Where `{project}` comes from:**
+1. spec.md YAML frontmatter `project:` field (MANDATORY)
+2. Example: `project: specweave` → `.specweave/docs/internal/specs/specweave/FS-116/`
+
+**Pre-tool-use hook `features-folder-guard.sh` BLOCKS writes to `_features/` (v0.33.0+).**
+
+### 2e. NEVER Create Duplicate Increment IDs (v0.33.0+)
+
+**Increment numbers MUST be unique across ALL directories!**
+
+```
+❌ FORBIDDEN (Bug pattern from 2025-12-07):
+0121-ado-jira-feature-parity-p2-p3/  ← exists
+0121-intelligent-living-docs-content/ ← DUPLICATE!
+
+❌ ALSO FORBIDDEN (0001 and 0001E share SAME base number):
+0001-internal-feature/
+0001E-external-fix/  ← COLLISION! Same base number!
+```
+
+**VALIDATION RULES:**
+```
+✅ ALWAYS use IncrementNumberManager.generateUniqueIncrementId()
+✅ ALWAYS use IncrementNumberManager.validateUnique() before creating
+✅ Check ALL directories: active, _archive, _abandoned, _paused
+```
+
+**API (v0.33.0+):**
+```typescript
+import { IncrementNumberManager } from './core/increment/increment-utils.js';
+
+// Safe generation with validation:
+const id = IncrementNumberManager.generateUniqueIncrementId('feature-name');
+// → "0122-feature-name" (guaranteed unique)
+
+// Manual validation:
+IncrementNumberManager.validateUnique('0121-new-name'); // throws if duplicate!
+
+// Find duplicates:
+IncrementNumberManager.findDuplicates('0121');
+// → ["0121-ado-jira-feature (active)", "0121-intelligent-living-docs (active)"]
+```
+
+**Pre-tool-use hook `increment-duplicate-guard.sh` BLOCKS duplicate increment creation (v0.33.0+).**
+
 ### 3. Protected Directories
 
 **NEVER delete**: `.specweave/docs/`, `.specweave/increments/`
@@ -188,6 +245,79 @@ find .specweave/docs -name "*.md" -exec sed -i '' 's/target=_blank/target="_blan
 find .specweave/docs -name "*.md" -exec sed -i '' 's/dir=auto/dir="auto"/g' {} \;
 ```
 
+### 9. NEVER Use Bash for File Creation (INFINITE HANG PREVENTION!)
+
+**Bash + heredoc/echo for files = SESSION FREEZE** (shell waits forever for EOF)
+
+```
+❌ FORBIDDEN (Crash pattern from 2025-12-06 - 2 HOUR HANG!):
+Bash("cat > file.md << 'EOF'\nContent here\nEOF")
+Bash("echo 'content' > file.md")
+Bash("printf 'content' > file.md")
+
+→ If heredoc is truncated mid-content, shell waits FOREVER for EOF terminator!
+→ Claude Code session stuck "Marinating..." for hours with no recovery!
+
+✅ MANDATORY - Use Write tool:
+Write({ file_path: "/path/to/file.md", content: "Content here" })
+
+✅ MANDATORY - Use Edit tool for modifications:
+Edit({ file_path: "/path/to/file.md", old_string: "old", new_string: "new" })
+```
+
+**Why heredocs are catastrophically dangerous:**
+1. **Truncation = infinite wait**: Token limits can cut off EOF terminator
+2. **No timeout**: Shell waits forever, bypasses Claude Code's 2-min limit
+3. **No recovery**: Session becomes completely unresponsive
+4. **Silent failure**: No error message, just endless "Waiting..."
+
+**Tool selection rules:**
+| Operation | CORRECT Tool | FORBIDDEN |
+|-----------|--------------|-----------|
+| Create file | `Write` | `Bash cat/echo/printf >` |
+| Edit file | `Edit` | `Bash sed/awk` |
+| Append to file | `Read` + `Write` | `Bash echo >>` |
+| Create directory | `Bash mkdir -p` | ✅ OK |
+
+**Pre-tool-use hook `bash-file-guard.sh` BLOCKS dangerous Bash file patterns (v0.32.1+).**
+This hook automatically blocks: heredoc, echo >, printf >, cat > patterns.
+
+**If session gets stuck ("Marinating..." / "Waiting..."):**
+```bash
+# 1. Kill Claude Code (Ctrl+C or close terminal)
+# 2. Kill zombie shell processes:
+pkill -f "cat.*EOF"
+pkill -f "bash.*heredoc"
+# 3. Clean state:
+rm -f .specweave/state/.processor.lock
+rm -f .specweave/state/.dedup-cache/*.lock
+# 4. Restart Claude Code
+```
+
+### 10. Bash Tool - Terminal Operations ONLY
+
+**Bash is for system commands, NOT file manipulation:**
+
+```
+✅ ALLOWED Bash operations:
+- git commands (status, add, commit, push, diff)
+- npm/pnpm/yarn commands (install, build, test)
+- Directory operations (mkdir, ls, pwd)
+- Process management (ps, kill, pkill)
+- Network tools (curl, wget for APIs)
+- Build tools (make, cmake, cargo)
+
+❌ FORBIDDEN - Use dedicated tools instead:
+- File reading → Read tool
+- File writing → Write tool
+- File editing → Edit tool
+- File searching → Glob tool
+- Content searching → Grep tool
+- Communication → Direct text output
+```
+
+**Mental model**: Bash = "run a program". Write/Edit/Read = "modify files".
+
 ---
 
 ## Development Setup
@@ -227,11 +357,37 @@ git add . && git commit -m "feat: feature" && git push origin develop
 
 ## Folder Structure
 
-**At `.specweave/increments/` root - ONLY**: `####-name/` folders, `_archive/`, `README.md`
+**At `.specweave/increments/` root - ONLY**: `####-name/` or `####E-name/` folders, `_archive/`, `README.md`
 
 **Inside increment folders - ONLY at root**: `spec.md`, `plan.md`, `tasks.md`, `metadata.json`
 **Everything else → subfolders**: `reports/`, `scripts/`, `logs/`, `backups/`, `docs/`
 
+### External Increment E-Suffix (v0.32.0+)
+
+**Increments for external items MUST use E suffix** to match FS-XXXE, US-XXXE conventions:
+
+```
+✅ CORRECT: 0111E-dora-metrics-fix (external GitHub issue #779)
+❌ WRONG:   0111-dora-metrics-fix  (missing E suffix)
+```
+
+**When to use E suffix:**
+- Increment works on imported GitHub/JIRA/ADO issue
+- spec.md has `origin: external` or `external_ref:`
+- Feature folder is FS-XXXE (ends with E)
+
+**API (v0.32.0+):**
+```typescript
+import { IncrementNumberManager } from './core/increment/increment-utils.js';
+
+// For external items:
+const id = IncrementNumberManager.generateIncrementId('fix-name', { isExternal: true });
+// → "0112E-fix-name"
+
+// Check if external:
+IncrementNumberManager.isExternalIncrement('0111E-fix'); // true
+```
+
 ### CLI Command Structure (ADR-0138)
 
 **Init command** is modular - DO NOT add logic to main file:
@@ -345,7 +501,60 @@ npm run test:all    # All tests (80%+ coverage required)
 
 ## Emergency
 
-**Crash loop / prompt duplication? Disable hooks FIRST:**
+### Session Stuck ("Marinating..." for hours)
+
+**Cause**: Heredoc command truncated, shell waiting forever for EOF.
+
+```bash
+# 1. Force quit Claude Code (Ctrl+C multiple times, or close terminal)
+
+# 2. Kill zombie processes:
+pkill -f "cat.*EOF"
+pkill -9 -f "bash.*specweave"
+
+# 3. Clean locks:
+rm -f .specweave/state/.processor.lock
+rm -f .specweave/state/*.lock
+rm -rf .specweave/state/.dedup-cache/*.lock
+
+# 4. Restart Claude Code
+```
+
+**Prevention**: NEVER use `Bash("cat > file << EOF")` - use `Write` tool instead!
+
+### MCP IDE Connection Drops (v0.32.1+)
+
+**Symptoms**: Session hangs, commands not responding, "Waiting..." forever, UI frozen
+**Root Cause**: VSCode MCP server WebSocket connection drops after ~2 seconds
+
+**Detection** (check `~/.claude/debug/latest`):
+```
+MCP server "ide": WS-IDE connection dropped after 2s uptime
+MCP server "ide": Connection error: Received a response for an unknown message ID
+```
+
+**Quick Fix:**
+```bash
+# 1. Restart VS Code Extension Host:
+#    Cmd+Shift+P → "Developer: Restart Extension Host"
+
+# 2. Reduce diagnostics payload (close extra tabs/files in VS Code)
+
+# 3. If persists, run Claude Code in plain terminal (not VS Code integrated):
+cd /path/to/project && claude
+
+# 4. Run cleanup script:
+bash plugins/specweave/scripts/cleanup-state.sh
+```
+
+**Prevention:**
+- Keep VS Code file count low (large diagnostics payloads cause drops)
+- Update Claude Code VS Code extension regularly
+- Use terminal mode for long-running sessions
+
+### Crash loop / prompt duplication
+
+**Disable hooks FIRST:**
 ```bash
 export SPECWEAVE_DISABLE_HOOKS=1   # In terminal before starting Claude
 # OR rename hooks.json:
@@ -367,10 +576,14 @@ npm run rebuild
 
 | Aspect | Rule |
 |--------|------|
+| **File ops** | Write/Edit/Read tools ONLY. NEVER Bash heredoc/echo! |
+| **Bash guard** | Hook `bash-file-guard.sh` BLOCKS dangerous patterns (v0.32.1+) |
 | 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 |
+| Stuck session | Kill + `pkill -f "cat.*EOF"` + clean locks + restart |
+| MCP drops | Restart Extension Host OR use terminal mode |
 
 ---
 

package/README.md

@@ -217,6 +217,28 @@ As a user, I want to toggle dark mode so that I can reduce eye strain at night.
 
 ---
 
+## When to Use Increments
+
+Not every change needs an increment. **The rule of thumb:**
+
+| Change Type | Use Increment? | Why |
+|-------------|----------------|-----|
+| **Typo fix, version bump** | No | Zero learning, purely mechanical |
+| **Bug fix that taught you something** | **Yes** | Capture the knowledge for future devs |
+| **Any user-facing change** | **Yes** | Track delivery, enable DORA metrics |
+| **Architecture decision** | **Yes** | Needs ADR for future understanding |
+
+**The principle**: *If you'd explain this change to a colleague, document it in an increment.*
+
+Increments capture **knowledge**. Ad-hoc work is **ephemeral**. When teams routinely do meaningful work without increments, they lose:
+- **Traceability** — Why was this decision made?
+- **Knowledge transfer** — How does this system work?
+- **Metrics accuracy** — DORA metrics reflect reality
+
+**Quick check before ad-hoc work**: "Will I remember why I made this change in 6 months?" If no → increment.
+
+---
+
 ## Key Features
 
 ### Works With ANY AI Tool

package/bin/specweave.js

@@ -108,13 +108,14 @@ program
 // Archive command - Archive completed increments and sync living docs
 program
   .command('archive [increments...]')
-  .description('Archive completed increments and sync living docs (_features/ + project-specific)')
+  .description('Archive completed increments and sync living docs (project-specific folders)')
   .option('--keep-last <n>', 'Keep last N increments, archive the rest', '5')
   .option('--last <n>', 'STRICT: Keep exactly last N increments by number, ignoring all protections')
   .option('--older-than <days>', 'Archive increments older than N days')
   .option('--pattern <pattern>', 'Archive increments matching pattern (regex)')
   .option('--archive-completed', 'Archive all completed increments')
   .option('--no-preserve-active', 'Allow archiving active/paused increments (dangerous!)')
+  .option('--external', 'Archive external living docs (FS-XXXE features imported from ADO/JIRA/GitHub)')
   .option('--dry-run', 'Preview what would be archived without moving files')
   .action(async (incrementIds, options) => {
     const { archiveCommand } = await import('../dist/src/cli/commands/archive.js');
@@ -321,6 +322,20 @@ program
     await livingDocsCommand(options);
   });
 
+// Cache command - Dashboard cache management
+program
+  .command('cache')
+  .description('Manage dashboard cache for instant status commands')
+  .option('--rebuild', 'Rebuild cache from increments')
+  .option('--status', 'Show cache status (default)')
+  .option('--clear', 'Clear cache')
+  .option('--quiet', 'Minimal output')
+  .option('--debug', 'Show debug information')
+  .action(async (options) => {
+    const { cacheCommand } = await import('../dist/src/cli/commands/cache.js');
+    await cacheCommand(options);
+  });
+
 // Commits command - Display last 2 git commits
 program
   .command('commits')
@@ -344,6 +359,36 @@ program
     await syncCmd.parseAsync(['node', 'sync-scheduled', ...process.argv.slice(3)], { from: 'user' });
   });
 
+// Context command - Get project/board context for increment planning
+const contextCmd = program
+  .command('context')
+  .description('Get project/board context for increment planning');
+
+contextCmd
+  .command('projects')
+  .description('List available projects and structure level')
+  .action(async () => {
+    const { contextProjectsCommand } = await import('../dist/src/cli/commands/context.js');
+    await contextProjectsCommand();
+  });
+
+contextCmd
+  .command('boards')
+  .description('List available boards for a project (2-level structures)')
+  .option('-p, --project <id>', 'Project ID to filter boards')
+  .action(async (options) => {
+    const { contextBoardsCommand } = await import('../dist/src/cli/commands/context.js');
+    await contextBoardsCommand(options);
+  });
+
+contextCmd
+  .command('select')
+  .description('Interactive project/board selection (auto-selects if single option)')
+  .action(async () => {
+    const { contextSelectCommand } = await import('../dist/src/cli/commands/context.js');
+    await contextSelectCommand();
+  });
+
 // Help text
 program.on('--help', () => {
   console.log('');
@@ -378,7 +423,13 @@ program.on('--help', () => {
   console.log('  $ specweave living-docs --resume <jobId>    # Resume orphaned job');
   console.log('  $ specweave sync-scheduled                  # Execute due sync jobs');
   console.log('  $ specweave sync-scheduled --force          # Force sync all jobs');
+  console.log('  $ specweave cache                           # Show cache status');
+  console.log('  $ specweave cache --rebuild                 # Rebuild dashboard cache');
+  console.log('  $ specweave cache --debug                   # Show cache debug info');
   console.log('  $ specweave validate-jira --env .env.prod   # Validate with custom .env file');
+  console.log('  $ specweave context projects                # Get available projects as JSON');
+  console.log('  $ specweave context boards --project myapp  # Get boards for a project');
+  console.log('  $ specweave context select                  # Interactive project/board selection');
   console.log('');
   console.log('Supported AI Tools:');
   console.log('  - Claude Code (full automation) - Native skills, agents, hooks');

package/dist/plugins/specweave-ado/lib/ado-duplicate-detector.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Azure DevOps Duplicate Detector (v0.33.0)
+ *
+ * Implements 3-phase duplicate protection for ADO work items:
+ * 1. Detection: Check before create
+ * 2. Verification: Count check after create
+ * 3. Reflection: Auto-close duplicates
+ *
+ * Mirrors the GitHub DuplicateDetector pattern for consistency.
+ */
+import { Logger } from '../../../src/utils/logger.js';
+export interface AdoWorkItem {
+    id: number;
+    title: string;
+    state: string;
+    createdDate: string;
+    url?: string;
+}
+export interface DuplicateGroup {
+    title: string;
+    items: AdoWorkItem[];
+    keepItem: AdoWorkItem;
+    duplicates: AdoWorkItem[];
+}
+export interface DetectionResult {
+    found: boolean;
+    existingItem?: AdoWorkItem;
+    count: number;
+}
+export interface VerificationResult {
+    success: boolean;
+    expectedCount: number;
+    actualCount: number;
+    duplicates: AdoWorkItem[];
+}
+export interface CleanupResult {
+    closedCount: number;
+    keptCount: number;
+    errors: string[];
+}
+export declare class AdoDuplicateDetector {
+    private org;
+    private project;
+    private pat;
+    private logger;
+    constructor(options?: {
+        org?: string;
+        project?: string;
+        pat?: string;
+        logger?: Logger;
+    });
+    /**
+     * Phase 1: Check if work item exists before creating
+     */
+    checkBeforeCreate(titlePattern: string, incrementId?: string): Promise<DetectionResult>;
+    /**
+     * Phase 2: Verify count after creation
+     */
+    verifyAfterCreate(titlePattern: string, expectedCount?: number): Promise<VerificationResult>;
+    /**
+     * Phase 3: Auto-close duplicates
+     */
+    closeDuplicates(duplicates: AdoWorkItem[], keepItemId: number): Promise<CleanupResult>;
+    /**
+     * Full cleanup: Find and close all duplicates for a feature
+     */
+    cleanupFeatureDuplicates(featureId: string, dryRun?: boolean): Promise<{
+        groups: DuplicateGroup[];
+        totalItems: number;
+        duplicateCount: number;
+        closedCount: number;
+    }>;
+    /**
+     * Group work items by title
+     */
+    private groupByTitle;
+    /**
+     * Search for work items using WIQL
+     */
+    private searchWorkItems;
+    /**
+     * Get work item details by IDs
+     */
+    private getWorkItemDetails;
+    /**
+     * Close a work item with duplicate comment
+     */
+    private closeWorkItem;
+}
+/**
+ * Convenience function for quick duplicate cleanup
+ */
+export declare function cleanupAdoDuplicates(featureId: string, dryRun?: boolean): Promise<{
+    groups: DuplicateGroup[];
+    totalItems: number;
+    duplicateCount: number;
+    closedCount: number;
+}>;
+export default AdoDuplicateDetector;
+//# sourceMappingURL=ado-duplicate-detector.d.ts.map

package/dist/plugins/specweave-ado/lib/ado-duplicate-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ado-duplicate-detector.d.ts","sourceRoot":"","sources":["../../../../plugins/specweave-ado/lib/ado-duplicate-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAiB,MAAM,8BAA8B,CAAC;AAErE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE;QACnB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ;IAON;;OAEG;IACG,iBAAiB,CACrB,YAAY,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,eAAe,CAAC;IAoB3B;;OAEG;IACG,iBAAiB,CACrB,YAAY,EAAE,MAAM,EACpB,aAAa,GAAE,MAAU,GACxB,OAAO,CAAC,kBAAkB,CAAC;IAmC9B;;OAEG;IACG,eAAe,CACnB,UAAU,EAAE,WAAW,EAAE,EACzB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC;IAqBzB;;OAEG;IACG,wBAAwB,CAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,OAAe,GACtB,OAAO,CAAC;QACT,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IAyEF;;OAEG;IACH,OAAO,CAAC,YAAY;IA0BpB;;OAEG;YACW,eAAe;IAwC7B;;OAEG;YACW,kBAAkB;IA2BhC;;OAEG;YACW,aAAa;CAwC5B;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,OAAe,GACtB,OAAO,CAAC;IACT,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAGD;AAED,eAAe,oBAAoB,CAAC"}