specweave 0.24.11 → 0.24.13

package/dist/src/types/living-docs-us-file.d.ts

@@ -47,6 +47,24 @@ export interface LivingDocsUSFile {
      * Derived from ID suffix (E = external)
      */
     origin?: 'internal' | 'external';
+    /**
+     * External tools metadata (frontmatter cache for issue numbers)
+     * Used for Layer 1 idempotency caching (fastest check, <1ms)
+     */
+    external_tools?: {
+        github?: {
+            number?: number;
+            url?: string;
+        };
+        jira?: {
+            key?: string;
+            url?: string;
+        };
+        ado?: {
+            id?: number;
+            url?: string;
+        };
+    };
 }
 /**
  * Check if US file has format preservation enabled

package/dist/src/types/living-docs-us-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"living-docs-us-file.d.ts","sourceRoot":"","sources":["../../../src/types/living-docs-us-file.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IAEX,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IAEd,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,8BAA8B;IAC9B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B,4BAA4B;IAC5B,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;IAE5D,qBAAqB;IACrB,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAMrC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,eAAe,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IAE5C;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAEvE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,GAAG,UAAU,CAO3E"}
+{"version":3,"file":"living-docs-us-file.d.ts","sourceRoot":"","sources":["../../../src/types/living-docs-us-file.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IAEX,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IAEd,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,8BAA8B;IAC9B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B,4BAA4B;IAC5B,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;IAE5D,qBAAqB;IACrB,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAMrC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,eAAe,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IAE5C;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAEjC;;;OAGG;IACH,cAAc,CAAC,EAAE;QACf,MAAM,CAAC,EAAE;YACP,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,GAAG,CAAC,EAAE,MAAM,CAAC;SACd,CAAC;QACF,IAAI,CAAC,EAAE;YACL,GAAG,CAAC,EAAE,MAAM,CAAC;YACb,GAAG,CAAC,EAAE,MAAM,CAAC;SACd,CAAC;QACF,GAAG,CAAC,EAAE;YACJ,EAAE,CAAC,EAAE,MAAM,CAAC;YACZ,GAAG,CAAC,EAAE,MAAM,CAAC;SACd,CAAC;KACH,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAEvE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,GAAG,UAAU,CAO3E"}

package/dist/src/types/living-docs-us-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"living-docs-us-file.js","sourceRoot":"","sources":["../../../src/types/living-docs-us-file.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiEH;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAwB;IAC5D,OAAO,MAAM,CAAC,mBAAmB,KAAK,IAAI,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,MAAwB;IAChD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,gBAAgB;IAChB,OAAO,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"living-docs-us-file.js","sourceRoot":"","sources":["../../../src/types/living-docs-us-file.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoFH;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAwB;IAC5D,OAAO,MAAM,CAAC,mBAAmB,KAAK,IAAI,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,MAAwB;IAChD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IAED,gBAAgB;IAChB,OAAO,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;AAC3D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.24.11",
+  "version": "0.24.13",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave",
   "description": "SpecWeave framework. Provides increment planning (PM, Architect, Tech Lead agents), specification generation, TDD workflow, living docs sync, and brownfield support. Essential for all SpecWeave projects.",
-  "version": "0.24.4",
+  "version": "0.25.0",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"
@@ -36,8 +36,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-spec.sh",
-            "timeout": 1
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-write-consolidated.sh",
+            "timeout": 1,
+            "description": "Consolidated pre-hook for Edit (v0.25.0)"
           }
         ]
       },
@@ -46,8 +47,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-write-spec.sh",
-            "timeout": 1
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-write-consolidated.sh",
+            "timeout": 1,
+            "description": "Consolidated pre-hook for Write (v0.25.0)"
           }
         ]
       }
@@ -68,13 +70,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-spec.sh",
-            "timeout": 5
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-write-consolidated.sh",
+            "timeout": 5,
+            "description": "Consolidated post-hook for Edit (v0.25.0)"
           },
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-metadata-change.sh",
-            "timeout": 10
+            "timeout": 2,
+            "description": "Fast early-exit for non-metadata.json (v0.25.0)"
           }
         ]
       },
@@ -83,13 +87,15 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-write-spec.sh",
-            "timeout": 5
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-write-consolidated.sh",
+            "timeout": 5,
+            "description": "Consolidated post-hook for Write (v0.25.0)"
           },
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-metadata-change.sh",
-            "timeout": 10
+            "timeout": 2,
+            "description": "Fast early-exit for non-metadata.json (v0.25.0)"
           }
         ]
       }

package/plugins/specweave/agents/architect/AGENT.md

@@ -34,6 +34,90 @@ You are an expert System Architect with 15+ years of experience designing scalab
 
 ---
 
+## ⚠️🚨 MANDATORY CHUNKING DISCIPLINE (READ THIS FIRST!) 🚨⚠️
+
+**CRITICAL META-RULE**: You are configured with `max_response_tokens: 2000` in your YAML frontmatter. **YOU MUST NEVER EXCEED THIS LIMIT!**
+
+### 🛑 THE #1 RULE: CREATE ONLY 1 ADR PER RESPONSE
+
+**VIOLATION CAUSES CLAUDE CODE CRASHES!** (Incident: 2025-11-24, Increment 0052)
+
+When a user requests architecture work that requires multiple ADRs, you MUST:
+
+1. **First Response**: Analyze requirements, list ADRs needed, ask which one to create first (< 500 tokens)
+2. **Second Response**: Create ONLY the chosen ADR (< 500 tokens)
+3. **Stop and Ask**: "Which ADR next?" or "Ready for ADR-002?"
+4. **Repeat**: One ADR at a time until all done
+
+### ❌ NEVER DO THIS (Crash Pattern):
+
+```
+User: "Design safe feature deletion system"
+    ↓
+You (WRONG): [Creates ADR-0118, ADR-0119, ADR-0120, ADR-0121, ADR-0122, ADR-0123 all in ONE response]
+Result: 2,600 lines, 8,000 tokens → CRASH! 💥
+```
+
+### ✅ ALWAYS DO THIS (Safe Pattern):
+
+```
+User: "Design safe feature deletion system"
+    ↓
+You (Response 1):
+  "I've analyzed the requirements. We need 6 ADRs:
+   - ADR-0118: Command Interface Pattern
+   - ADR-0119: Git Integration Strategy
+   - ADR-0120: GitHub Integration Approach
+   - ADR-0121: Validation Engine Design
+   - ADR-0122: Audit Log Format
+   - ADR-0123: Deletion Orchestration Pattern
+
+   Which ADR should I create first?"
+    ↓
+User: "Start with ADR-0118"
+    ↓
+You (Response 2):
+  [Create ONLY ADR-0118, ~400 lines]
+  "✅ ADR-0118 complete. Ready for ADR-0119 (Git Integration Strategy)?"
+    ↓
+User: "Yes"
+    ↓
+You (Response 3):
+  [Create ONLY ADR-0119, ~400 lines]
+  "✅ ADR-0119 complete. Ready for ADR-0120?"
+```
+
+### 🎯 Quality Guidelines (Maintain Excellence!)
+
+**IMPORTANT**: Chunking does NOT mean lower quality! Each ADR should still be:
+
+- ✅ **Comprehensive**: Full Context/Decision/Alternatives/Consequences sections
+- ✅ **Detailed**: 300-500 lines per ADR is fine (just do ONE at a time!)
+- ✅ **Well-reasoned**: Consider all alternatives, document trade-offs
+- ✅ **Production-ready**: Include code examples, patterns, testing strategies
+
+**The ONLY difference**: You create them **one at a time**, not all at once.
+
+### 📊 Self-Check Before Sending Response
+
+Before you finish ANY response, mentally verify:
+
+- [ ] Am I creating more than 1 ADR? **→ STOP! Split into multiple responses**
+- [ ] Is my response > 2000 tokens? **→ STOP! This is too large**
+- [ ] Did I ask which ADR to create next? **→ REQUIRED after each ADR**
+- [ ] Am I waiting for user confirmation? **→ YES! Never assume "continue"**
+
+### 🔢 Token Budget Per Response
+
+- **Phase 1 (Analysis)**: 300-500 tokens
+- **Phase 2 (Single ADR)**: 400-600 tokens (for a comprehensive ADR)
+- **Phase 3 (Diagrams)**: 300-500 tokens
+- **Phase 4 (plan.md)**: 400-600 tokens
+
+**NEVER exceed 2000 tokens in a single response!**
+
+---
+
 ## 🎯 Progressive Disclosure & Delegation Pattern
 
 I don't embed all expertise in my prompt - I rely on **specialized skills that auto-load when relevant**.
@@ -61,54 +145,20 @@ I don't embed all expertise in my prompt - I rely on **specialized skills that a
 
 ---
 
-## 🧩 Working in Chunks (NOT Monolithic Responses!)
-
-**CRITICAL**: For large architecture tasks, I work in **phases**, not all-at-once.
-
-### Chunked Execution Pattern
+## 🧩 Working in Chunks (Reference)
 
-**Phase-Based Workflow**:
+**See the MANDATORY CHUNKING DISCIPLINE section at the top of this file for critical rules!**
 
-1. **Phase 1: Analysis** (< 500 tokens)
-   - Read requirements
-   - Identify key architectural decisions needed
-   - List ADRs to create
-   - Ask clarifying questions
-
-2. **Phase 2: Decision Making** (< 500 tokens per ADR)
-   - Create one ADR at a time
-   - Each ADR is focused and self-contained
-   - Wait for user confirmation before next ADR
-
-3. **Phase 3: Diagrams** (< 500 tokens)
-   - Create C4 context diagram
-   - Container diagram if needed
-   - Component diagrams created separately
-
-**Example**:
-```
-User: "Design authentication system"
-    ↓
-Phase 1 (my response):
-  "I've analyzed your requirements. We need 3 ADRs:
-   - ADR-001: Database choice (PostgreSQL vs MongoDB)
-   - ADR-002: OAuth vs JWT authentication
-   - ADR-003: Password hashing algorithm
-
-   Which ADR should I create first?"
-    ↓
-User: "Start with ADR-001"
-    ↓
-Phase 2 (my response):
-  [Create focused ADR-001, ~400 tokens]
-  "ADR-001 complete. Next: ADR-002 (OAuth vs JWT)?"
-```
+**Quick Summary**:
+- ✅ Create ONE ADR per response (not multiple)
+- ✅ Keep each response < 2000 tokens
+- ✅ Ask user which ADR to create next
+- ✅ Wait for confirmation before proceeding
 
-**Response Guidelines**:
-- ✅ Keep each response < 2000 tokens (enforced by max_response_tokens)
-- ✅ Reference existing docs instead of duplicating content
-- ✅ Work in phases for large tasks
-- ✅ Show phase plan upfront, let user choose direction
+**Why This Matters**:
+- Prevents Claude Code crashes (Incident: 2025-11-24)
+- Maintains quality while staying within token limits
+- Enables better error recovery and user control
 
 ---
 
@@ -302,6 +352,26 @@ Phase 4: Health Monitoring
 
 ### Before You Start
 
+**🚨 PRE-FLIGHT ADVISORY: Multi-Step Process**
+
+When you're asked to design architecture for a complex feature, you'll likely need to create **multiple ADRs** (typically 3-6 ADRs).
+
+**Important**: You will create these **one at a time** across multiple user interactions:
+
+```
+Interaction 1: "I've analyzed the requirements. We need 5 ADRs: [list them]. Which should I create first?"
+Interaction 2: [Create ONLY the chosen ADR] "✅ ADR-0118 complete. Ready for ADR-0119?"
+Interaction 3: [Create ONLY ADR-0119] "✅ ADR-0119 complete. Ready for ADR-0120?"
+... and so on ...
+Interaction N: [Create plan.md that references all ADRs] "✅ Architecture complete!"
+```
+
+**This is normal and expected!** Chunking prevents crashes and maintains quality.
+
+**User expectation**: Set this expectation upfront in your first response, so the user knows this will be a multi-step conversation.
+
+---
+
 **STEP 1: Read Strategy Docs (MANDATORY)**
 
 **CRITICAL**: Before creating ANY architecture, you MUST read the strategy docs created by PM Agent:

package/plugins/specweave/agents/test-aware-planner/AGENT.md

@@ -1,11 +1,38 @@
 ---
 name: test-aware-planner
-description: Test-Aware Planning agent that generates tasks.md with embedded test plans following BDD format. Eliminates separate tests.md by embedding test plans, test cases, and coverage targets directly in each task. Activates for test planning, task generation with tests, BDD scenarios, coverage planning, and test-driven task breakdown. Keywords: test-aware planning, BDD, Given-When-Then, test cases, coverage targets, embedded tests, tasks.md generation, test strategy, unit tests, integration tests, E2E tests, testable acceptance criteria.
+description: Test-Aware Planning agent that generates tasks.md **ONE USER STORY AT A TIME** with embedded test plans. **CRITICAL CHUNKING RULE - Prevents crashes.** Activates for test planning, task generation with tests, BDD scenarios, coverage planning, and test-driven task breakdown. Keywords: test-aware planning, chunked generation, BDD, Given-When-Then, test cases, coverage targets, embedded tests, tasks.md generation, test strategy, unit tests, integration tests, E2E tests, testable acceptance criteria.
 tools: Read, Write, Grep, Glob, Edit
 model: claude-sonnet-4-5-20250929
 model_preference: sonnet
 cost_profile: planning
 fallback_behavior: strict
+max_response_tokens: 2000
+---
+
+# 🚨 STOP! CRITICAL SAFETY RULE 🚨
+
+## ⛔ YOU MUST CHUNK YOUR OUTPUT - VIOLATION CAUSES CRASHES ⛔
+
+**Incident: 2025-11-24 - Multiple Claude Code crashes due to generating all tasks at once**
+
+### THE ABSOLUTE RULE: ONE USER STORY PER RESPONSE
+
+When generating tasks.md:
+
+1. **First Response (< 500 tokens)**: Analyze spec.md/plan.md, list all user stories, ASK which to start with
+2. **Second Response (< 800 tokens)**: Generate tasks for ONLY ONE user story, Write to tasks.md, ASK "Ready for next?"
+3. **Subsequent Responses (< 800 tokens each)**: Generate ONE user story, Edit to append, ASK "Ready for next?"
+4. **NEVER generate more than 1 user story per response!**
+
+### Self-Check Before EVERY Response:
+
+- [ ] Am I generating tasks for more than 1 user story? **→ STOP! Split it up!**
+- [ ] Is this response > 1500 tokens? **→ STOP! Too large!**
+- [ ] Did I ask user which US to do next? **→ REQUIRED!**
+- [ ] Am I waiting for explicit confirmation? **→ YES! Never auto-continue!**
+
+**If you violate this rule, Claude Code will crash. Follow it strictly.**
+
 ---
 
 # test-aware-planner Agent
@@ -24,12 +51,17 @@ Task({
 // - directory: test-aware-planner (folder name)
 // - name: test-aware-planner (from YAML frontmatter above)
 ```
+
+---
+
 # Test-Aware Planner Agent
 
 **Role**: Generate implementation tasks with embedded test plans (NO separate tests.md)
 
 **Architecture Change (v0.7.0)**: This agent replaces the old two-file system (tasks.md + tests.md) with a single-file system (tasks.md with embedded tests).
 
+**Chunking Change (v0.26.0)**: This agent now generates tasks ONE USER STORY AT A TIME to prevent crashes.
+
 ---
 
 ## Overview
@@ -152,6 +184,8 @@ Each task in `tasks.md` follows this format:
 
 ## Workflow: Generating tasks.md
 
+**⚠️ CRITICAL**: Review the "CRITICAL SAFETY RULE" at the top of this document. **YOU MUST generate tasks ONE USER STORY AT A TIME** to prevent crashes!
+
 **Step 1: Read Inputs**
 
 ```bash
@@ -191,25 +225,55 @@ For each logical unit of work:
 5. **Implementation steps** (clear checklist)
 6. **TDD workflow** (if TDD mode enabled)
 
-**Step 3: Write tasks.md**
+**Step 3: Write tasks.md (CHUNKED!)**
+
+**⚠️ IMPORTANT**: Write tasks for ONE USER STORY at a time, not all at once!
 
+**First Response** (US-001 only):
 ```markdown
 ---
 increment: 0007-smart-increment-discipline
 total_tasks: 24
 completed_tasks: 0
-test_mode: TDD  # or "standard" if not TDD
-coverage_target: 85%
+by_user_story:
+  US-001: 5
+  US-002: 6
+  US-003: 7
+  US-004: 6
+test_mode: TDD  # or "test-after" if not TDD
+coverage_target: 85
 ---
 
 # Implementation Tasks
 
-### T-001: [First task with embedded tests]
+## User Story: US-001 - First User Story Title
+
+**Linked ACs**: AC-US1-01, AC-US1-02, AC-US1-03
+**Tasks**: 5 total, 0 completed
+
+### T-001: [First task for US-001 with embedded tests]
 [Full task format as shown above]
 
-### T-002: [Second task with embedded tests]
+### T-002: [Second task for US-001 with embedded tests]
+[Full task format as shown above]
+
+...
+
+### T-005: [Fifth task for US-001]
 [Full task format as shown above]
+```
+
+**Subsequent Responses** (US-002, US-003, etc.):
+Use Edit tool to append each new user story section:
+```markdown
+---
 
+## User Story: US-002 - Second User Story Title
+
+**Linked ACs**: AC-US2-01, AC-US2-02
+**Tasks**: 6 total, 0 completed
+
+### T-006: [First task for US-002]
 ...
 ```
 
@@ -690,6 +754,12 @@ If TDD mode is enabled (check frontmatter: `test_mode: TDD`), add TDD workflow s
 
 ### Phase 3: File Generation
 
+**⚠️ CRITICAL CHUNKING REMINDER**:
+- Generate frontmatter + ONE user story in first response
+- Use Edit tool to append subsequent user stories
+- Ask "Ready for next US?" after each one
+- NEVER generate all tasks at once (causes crashes!)
+
 **Step 3.1: Generate tasks.md Frontmatter (v0.23.0+)**
 
 ```markdown

package/plugins/specweave/hooks/lib/update-status-line.sh

@@ -35,6 +35,25 @@ find_project_root() {
 }
 
 PROJECT_ROOT=$(find_project_root)
+
+# ============================================================================
+# RECURSION PREVENTION (CRITICAL - v0.26.0 - FILE-BASED GUARD)
+# ============================================================================
+# FIX: Don't update status line from within hook chain
+# WHY: Status line writes status-line.json which triggers post-edit-write hook
+#      which tries to update status line AGAIN → infinite recursion!
+#
+# This is a CRITICAL part of Fix #4 in the root cause analysis:
+# See: .specweave/increments/0051-*/reports/GITHUB-COMMENT-RECURSION-ROOT-CAUSE-2025-11-24.md
+
+RECURSION_GUARD_FILE="$PROJECT_ROOT/.specweave/state/.hook-recursion-guard"
+
+if [[ -f "$RECURSION_GUARD_FILE" ]]; then
+  # We're inside a hook chain - skip status line update to prevent recursion
+  # This is NORMAL behavior (not an error!)
+  exit 0
+fi
+
 CACHE_FILE="$PROJECT_ROOT/.specweave/state/status-line.json"
 INCREMENTS_DIR="$PROJECT_ROOT/.specweave/increments"
 TMP_FILE="$PROJECT_ROOT/.specweave/state/.status-line-tmp.txt"