specweave 0.30.14 → 0.30.17

package/plugins/specweave/commands/specweave-living-docs.md

@@ -0,0 +1,321 @@
+---
+name: specweave:living-docs
+description: Launch or resume Living Docs Builder independently. Generates documentation from codebase analysis with AI-powered insights.
+usage: /specweave:living-docs [--resume <jobId>] [--depth <level>] [--priority <modules>] [--sources <folders>] [--depends-on <jobIds>] [--foreground]
+---
+
+# Living Docs Builder (Standalone)
+
+**Usage**: `/specweave:living-docs [options]`
+
+---
+
+## Purpose
+
+Launch the Living Docs Builder independently of `specweave init`. This is essential for:
+- **Resuming after crash** - Claude Code crashed after init, need to restart living docs
+- **On-demand analysis** - Re-analyze codebase after major changes
+- **Large brownfield projects** - Run targeted analysis on specific modules
+- **CI/CD integration** - Automate documentation generation
+
+---
+
+## Command Options
+
+| Option | Description |
+|--------|-------------|
+| (none) | Interactive mode - prompts for configuration |
+| `--resume <jobId>` | Resume orphaned/paused living-docs job |
+| `--depth <level>` | Analysis depth: `quick`, `standard`, `deep-native`, `deep-api` |
+| `--priority <modules>` | Priority modules (comma-separated): `auth,payments,api` |
+| `--sources <folders>` | Additional doc folders (comma-separated): `docs/,wiki/` |
+| `--depends-on <jobIds>` | Wait for jobs before starting (comma-separated) |
+| `--foreground` | Run in current session instead of background |
+
+---
+
+## Quick Start
+
+### Launch New Analysis (Interactive)
+
+```bash
+/specweave:living-docs
+
+# Prompts for:
+# 1. Analysis depth (quick/standard/deep-native/deep-api)
+# 2. Priority modules to focus on
+# 3. Additional documentation sources
+# 4. Confirmation to launch
+```
+
+### Resume After Crash
+
+```bash
+# Check for orphaned jobs first
+/specweave:jobs
+
+# If you see an orphaned living-docs-builder job:
+/specweave:living-docs --resume abc12345
+
+# Or let it auto-detect:
+/specweave:living-docs
+# → "Found orphaned job abc12345. Resume? [Y/n]"
+```
+
+### Quick Analysis (Non-Interactive)
+
+```bash
+# Quick scan - 5-10 minutes
+/specweave:living-docs --depth quick
+
+# Standard analysis - 15-30 minutes
+/specweave:living-docs --depth standard --priority auth,payments
+
+# AI-powered deep analysis (FREE with MAX subscription)
+/specweave:living-docs --depth deep-native --priority core,api
+```
+
+---
+
+## Analysis Depths
+
+| Depth | Duration | What It Does | Cost |
+|-------|----------|--------------|------|
+| `quick` | ~5-10 min | Structure scan, tech detection, imports map | Free |
+| `standard` | ~15-30 min | Module analysis, exports, dependencies | Free |
+| `deep-native` | Progress-based | AI analysis via Claude Code CLI | FREE (MAX) |
+| `deep-api` | Progress-based | AI analysis via API key | API costs |
+
+### Deep-Native (Recommended for MAX Users)
+
+Uses your Claude MAX subscription via `claude --print`:
+- **No extra cost** - included in MAX
+- Runs in **background** - survives terminal close
+- **Checkpoint/resume** - can resume from any phase
+- Uses **Opus 4.5** for best quality
+
+```bash
+/specweave:living-docs --depth deep-native
+
+# Monitor progress:
+/specweave:jobs --follow <jobId>
+```
+
+---
+
+## Implementation Steps
+
+When this command is invoked:
+
+### Step 1: Check for Orphaned Jobs
+
+```typescript
+import { getOrphanedJobs, getJobManager } from '../../../src/core/background/job-launcher.js';
+
+const orphaned = getOrphanedJobs(projectPath).filter(j => j.type === 'living-docs-builder');
+if (orphaned.length > 0) {
+  // Prompt: "Found orphaned job {id}. Resume? [Y/n]"
+  // If yes: resume job
+  // If no: ask if they want to start fresh
+}
+```
+
+### Step 2: Collect Configuration (if not --resume)
+
+If no `--resume` flag and no auto-resume:
+
+```typescript
+import { collectLivingDocsInputs } from '../../../src/cli/helpers/init/living-docs-preflight.js';
+
+const result = await collectLivingDocsInputs({
+  projectPath,
+  language: 'en',
+  isCi: hasFlags, // Skip prompts if flags provided
+});
+```
+
+Override with flags:
+- `--depth` → `result.userInputs.analysisDepth`
+- `--priority` → `result.userInputs.priorityAreas`
+- `--sources` → `result.userInputs.additionalSources`
+
+### Step 3: Launch Job
+
+```typescript
+import { launchLivingDocsJob } from '../../../src/core/background/job-launcher.js';
+
+const { job, pid, isBackground } = await launchLivingDocsJob({
+  projectPath,
+  userInputs: result.userInputs,
+  dependsOn: dependsOnJobIds,
+  foreground: hasForegroundFlag,
+});
+```
+
+### Step 4: Display Status
+
+```
+✅ Living Docs Builder launched!
+
+   Job ID: ldb-abc12345
+   Depth: deep-native (Claude Code Opus 4.5)
+   Priority: auth, payments, api
+   PID: 45678
+
+   Monitor: /specweave:jobs --follow ldb-abc12345
+   Logs: /specweave:jobs --logs ldb-abc12345
+
+💡 This job runs in background and survives terminal close.
+   Output will be saved to:
+   - .specweave/docs/SUGGESTIONS.md
+   - .specweave/docs/ENTERPRISE-HEALTH.md
+```
+
+---
+
+## Resume Behavior
+
+When resuming a job:
+
+1. **Load checkpoint** from `.specweave/state/jobs/<jobId>/checkpoints/`
+2. **Skip completed phases**:
+   - `waiting` → dependency waiting
+   - `discovery` → codebase scanning
+   - `foundation` → high-level docs
+   - `integration` → work item matching
+   - `deep-dive` → module analysis (per-module checkpoints)
+   - `suggestions` → recommendations
+   - `enterprise` → health report
+3. **Continue from resume point**
+
+```bash
+# Example: Job crashed during deep-dive phase
+/specweave:living-docs --resume abc12345
+
+# Output:
+# Resuming from checkpoint: phase=deep-dive, module=auth (5/18)
+# ✓ Skipping completed phases: waiting, discovery, foundation, integration
+# → Continuing deep-dive from module: payments
+```
+
+---
+
+## Waiting for Dependencies
+
+For umbrella projects with clone/import jobs:
+
+```bash
+# Launch after clone completes
+/specweave:living-docs --depends-on clone-xyz123 --depth standard
+
+# Launch after both clone and import complete
+/specweave:living-docs --depends-on clone-xyz123,import-abc456
+```
+
+The job will:
+1. Enter `waiting` phase
+2. Poll dependency status every 30 seconds
+3. Start analysis once all dependencies complete
+4. Warn if any dependency failed (proceeds with available data)
+
+---
+
+## Output Files
+
+After completion:
+
+| File | Description |
+|------|-------------|
+| `.specweave/docs/SUGGESTIONS.md` | Documentation recommendations by priority |
+| `.specweave/docs/ENTERPRISE-HEALTH.md` | Health score, coverage, accuracy metrics |
+| `.specweave/docs/overview/PROJECT-OVERVIEW.md` | Auto-generated project overview |
+| `.specweave/docs/overview/TECH-STACK.md` | Detected technologies and frameworks |
+| `.specweave/docs/modules/*.md` | Per-module documentation |
+
+---
+
+## Examples
+
+### Example 1: Post-Crash Resume
+
+```bash
+# Claude crashed after init, living docs job orphaned
+
+# Step 1: Check what's there
+/specweave:jobs
+# Shows: [ldb-abc123] living-docs-builder - ORPHANED (worker died)
+
+# Step 2: Resume
+/specweave:living-docs --resume ldb-abc123
+
+# Output:
+# ✅ Resuming Living Docs Builder (ldb-abc123)
+#    Last checkpoint: deep-dive phase, module 12/45
+#    Continuing from: payments-service
+```
+
+### Example 2: Large Brownfield (247 repos)
+
+```bash
+# Focus on critical modules first
+/specweave:living-docs --depth deep-native \
+  --priority auth,payments,billing,core \
+  --depends-on clone-main123
+
+# Monitor in another terminal
+/specweave:jobs --follow ldb-xyz789
+```
+
+### Example 3: CI/CD Integration
+
+```bash
+# In CI pipeline (non-interactive)
+specweave living-docs --depth quick --foreground
+
+# Or background with polling
+specweave living-docs --depth standard
+specweave jobs --wait ldb-latest  # Wait for completion
+```
+
+---
+
+## Error Handling
+
+### Worker Crashed
+```
+/specweave:jobs
+# Shows: ORPHANED status
+
+/specweave:living-docs --resume <jobId>
+# Resumes from last checkpoint
+```
+
+### Dependency Failed
+```
+⚠️  Dependency clone-xyz123 failed
+    Reason: Network timeout
+
+Proceeding with available data...
+Some repositories may be missing from analysis.
+```
+
+### No Brownfield Detected
+```
+ℹ️  No existing code detected (greenfield project)
+    Living docs will sync automatically as you create increments.
+
+    To force analysis anyway: /specweave:living-docs --force
+```
+
+---
+
+## See Also
+
+- `/specweave:jobs` - Monitor all background jobs
+- `/specweave:import-docs` - Import existing documentation
+- `specweave:brownfield-analyzer` skill - Analyze doc gaps
+- `specweave:brownfield-onboarder` skill - Merge existing docs
+
+---
+
+**Implementation**: `src/cli/commands/living-docs.ts`

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

@@ -103,22 +103,53 @@ await syncSpecs(args);
 
 **This will**:
 1. **Derive feature ID from increment number** (e.g., 0040 → FS-040, 0002 → FS-002)
-2. **Smart project matching** from (priority order):
-   - `**Project**:` field in spec.md (explicit)
+2. **Read project/board from spec.md YAML frontmatter** (v0.31.0+ REQUIRED):
+   - For 1-level: `project:` field REQUIRED
+   - For 2-level: `project:` AND `board:` fields REQUIRED
+   - See [ADR-0190](/internal/architecture/adr/0190-spec-project-board-requirement.md)
+3. **Smart project matching fallback** (only if YAML fields missing - deprecated):
+   - `**Project**:` field in spec.md body (legacy)
    - `multiProject.activeProject` in config.json
    - ADO area path / JIRA board mapping
    - Git remote (repo name)
    - **ASK USER if unsure** (multi-project mode)
-3. Parse spec.md for user stories and acceptance criteria
-4. Create living docs structure:
-   - `.specweave/docs/internal/specs/{project}/FS-XXX/FEATURE.md`
-   - `.specweave/docs/internal/specs/{project}/FS-XXX/us-*.md`
+4. Parse spec.md for user stories and acceptance criteria
+5. Create living docs structure:
+   - 1-level: `.specweave/docs/internal/specs/{project}/FS-XXX/`
+   - 2-level: `.specweave/docs/internal/specs/{project}/{board}/FS-XXX/`
 
 **CRITICAL**: Feature ID is DERIVED from increment number (ADR-0187)
 - Increment 0002-user-authentication → FS-002
 - Increment 0040-some-feature → FS-040
 - NO date-based patterns like FS-YY-MM-DD-name
 
+### 3.2 Project/Board Validation (v0.31.0+)
+
+**Structure Level Detection** (from `src/utils/structure-level-detector.ts`):
+- Detects 1-level vs 2-level from config (ADO, JIRA, umbrella, multiProject, folders)
+- Validates spec.md has required fields based on structure level
+- For 2-level: **ERROR if project OR board missing** (cannot sync)
+- For 1-level: **WARNING if project missing** (uses fallback, deprecated)
+
+**Expected spec.md frontmatter**:
+
+```yaml
+# 1-level structure
+---
+increment: 0001-feature-name
+project: my-project          # REQUIRED for 1-level
+---
+
+# 2-level structure
+---
+increment: 0001-feature-name
+project: acme-corp           # REQUIRED for 2-level
+board: clinical-insights     # REQUIRED for 2-level
+---
+```
+
+**Migration**: See [Migration Guide](/public/guides/migration-v031-project-fields.md)
+
 ---
 
 ## STEP 4: Report Distribution Results

package/plugins/specweave/hooks/hooks.json

@@ -20,6 +20,16 @@
             "command": "bash -c 'F=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/dispatcher.mjs\"; [ -f \"$F\" ] && node \"$F\" completion-guard || printf \"{\\\"continue\\\":true}\"' 2>/dev/null || printf '{\"continue\":true}'"
           }
         ]
+      },
+      {
+        "matcher": "Write",
+        "matcher_content": "\\.specweave/increments/\\d{4}-[^/]+/spec\\.md",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'F=\"${CLAUDE_PLUGIN_ROOT}/hooks/spec-project-validator.sh\"; [ -f \"$F\" ] && \"$F\" || printf \"{\\\"decision\\\":\\\"allow\\\"}\"' 2>/dev/null || printf '{\"decision\":\"allow\"}'"
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/plugins/specweave/hooks/spec-project-validator.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+#
+# spec-project-validator.sh
+#
+# Pre-tool-use hook that validates spec.md has required project/board fields
+# before allowing Write tool to create/update spec.md files.
+#
+# Activation:
+# - tool_name: Write
+# - file_path matches: .specweave/increments/*/spec.md
+#
+# Rules:
+# - 1-level structure: spec.md MUST have `project:` in YAML frontmatter
+# - 2-level structure: spec.md MUST have BOTH `project:` AND `board:` in frontmatter
+#
+# Returns exit code 1 (block) if validation fails, 0 (allow) otherwise.
+
+set -e
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Extract tool name
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# Only validate Write tool calls
+if [ "$TOOL_NAME" != "Write" ]; then
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# Extract file path
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only validate spec.md files in increments folder
+if [[ ! "$FILE_PATH" =~ \.specweave/increments/[0-9]{4}-[^/]+/spec\.md$ ]]; then
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# Extract file content
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
+
+# Check if content has YAML frontmatter
+if [[ ! "$CONTENT" =~ ^---$'\n' ]]; then
+  echo '{"decision": "block", "reason": "spec.md must have YAML frontmatter (starting with ---)"}'
+  exit 0
+fi
+
+# Extract YAML frontmatter
+FRONTMATTER=$(echo "$CONTENT" | sed -n '/^---$/,/^---$/p' | tail -n +2 | head -n -1)
+
+# Check for unresolved project placeholder
+if echo "$FRONTMATTER" | grep -q 'project:\s*{{PROJECT_ID}}'; then
+  echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{PROJECT_ID}}. Run STEP 0B to select project before creating spec.md."}'
+  exit 0
+fi
+
+# Check for unresolved board placeholder
+if echo "$FRONTMATTER" | grep -q 'board:\s*{{BOARD_ID}}'; then
+  echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{BOARD_ID}}. Run STEP 0B to select board before creating spec.md."}'
+  exit 0
+fi
+
+# Check for project field
+PROJECT=$(echo "$FRONTMATTER" | grep -E '^project:\s*' | sed 's/^project:\s*//' | tr -d '"'"'" | tr -d '[:space:]')
+
+# Detect structure level by checking config
+PROJECT_ROOT="${FILE_PATH%%/.specweave/*}"
+CONFIG_PATH="$PROJECT_ROOT/.specweave/config.json"
+
+IS_2_LEVEL=false
+
+if [ -f "$CONFIG_PATH" ]; then
+  # Check for ADO area path mapping (indicates 2-level)
+  if jq -e '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPathMapping.mappings | length > 0' "$CONFIG_PATH" >/dev/null 2>&1; then
+    IS_2_LEVEL=true
+  fi
+
+  # Check for ADO areaPaths (indicates 2-level)
+  if jq -e '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPaths | length > 0' "$CONFIG_PATH" >/dev/null 2>&1; then
+    IS_2_LEVEL=true
+  fi
+fi
+
+# Validation based on structure level
+if [ "$IS_2_LEVEL" = true ]; then
+  # 2-level: BOTH project AND board required
+  if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
+    echo '{"decision": "block", "reason": "spec.md missing required '\''project:'\'' field in YAML frontmatter. This is a 2-level structure - add '\''project: <project_name>'\'' to frontmatter."}'
+    exit 0
+  fi
+
+  BOARD=$(echo "$FRONTMATTER" | grep -E '^board:\s*' | sed 's/^board:\s*//' | tr -d '"'"'" | tr -d '[:space:]')
+
+  if [ -z "$BOARD" ] || [ "$BOARD" = "null" ]; then
+    echo '{"decision": "block", "reason": "spec.md missing required '\''board:'\'' field in YAML frontmatter. This is a 2-level structure - add '\''board: <board_name>'\'' to frontmatter."}'
+    exit 0
+  fi
+else
+  # 1-level: project is strongly recommended (warning, not block)
+  if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
+    # For 1-level, we warn but don't block (backward compatibility)
+    echo '{"decision": "allow", "message": "⚠️  spec.md should have '\''project:'\'' field in YAML frontmatter for explicit sync target."}'
+    exit 0
+  fi
+fi
+
+# All validations passed
+echo '{"decision": "allow"}'
+exit 0

package/plugins/specweave/hooks/v2/handlers/github-sync-handler.sh

@@ -26,15 +26,24 @@ GITHUB_ENABLED=$(grep -o '"enabled"[[:space:]]*:[[:space:]]*true' "$CONFIG_FILE"
 
 # Throttle: max once per 5 minutes per increment
 THROTTLE_FILE="$PROJECT_ROOT/.specweave/state/.github-sync-$INC_ID"
+THROTTLE_LOG="$PROJECT_ROOT/.specweave/logs/throttle.log"
+THROTTLE_WINDOW=300  # 5 minutes
+mkdir -p "$(dirname "$THROTTLE_LOG")" 2>/dev/null
+
 if [[ -f "$THROTTLE_FILE" ]]; then
   if [[ "$(uname)" == "Darwin" ]]; then
     AGE=$(($(date +%s) - $(stat -f %m "$THROTTLE_FILE" 2>/dev/null || echo 0)))
   else
     AGE=$(($(date +%s) - $(stat -c %Y "$THROTTLE_FILE" 2>/dev/null || echo 0)))
   fi
-  [[ $AGE -lt 300 ]] && exit 0
+  if [[ $AGE -lt $THROTTLE_WINDOW ]]; then
+    REMAINING=$((THROTTLE_WINDOW - AGE))
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] THROTTLED $INC_ID (wait ${REMAINING}s, use /specweave:sync-progress to bypass)" >> "$THROTTLE_LOG" 2>/dev/null
+    exit 0
+  fi
 fi
 touch "$THROTTLE_FILE"
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] EXECUTING $INC_ID" >> "$THROTTLE_LOG" 2>/dev/null
 
 # Cross-platform timeout wrapper
 run_with_timeout() {

package/plugins/specweave/hooks/v2/handlers/living-docs-handler.sh

@@ -19,15 +19,24 @@ done
 
 # Throttle: max once per minute per increment
 THROTTLE_FILE="$PROJECT_ROOT/.specweave/state/.living-docs-$INC_ID"
+THROTTLE_LOG="$PROJECT_ROOT/.specweave/logs/throttle.log"
+THROTTLE_WINDOW=60  # 1 minute
+mkdir -p "$(dirname "$THROTTLE_LOG")" 2>/dev/null
+
 if [[ -f "$THROTTLE_FILE" ]]; then
   if [[ "$(uname)" == "Darwin" ]]; then
     AGE=$(($(date +%s) - $(stat -f %m "$THROTTLE_FILE" 2>/dev/null || echo 0)))
   else
     AGE=$(($(date +%s) - $(stat -c %Y "$THROTTLE_FILE" 2>/dev/null || echo 0)))
   fi
-  [[ $AGE -lt 60 ]] && exit 0
+  if [[ $AGE -lt $THROTTLE_WINDOW ]]; then
+    REMAINING=$((THROTTLE_WINDOW - AGE))
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [living-docs] THROTTLED $INC_ID (wait ${REMAINING}s)" >> "$THROTTLE_LOG" 2>/dev/null
+    exit 0
+  fi
 fi
 touch "$THROTTLE_FILE"
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [living-docs] EXECUTING $INC_ID" >> "$THROTTLE_LOG" 2>/dev/null
 
 # Cross-platform timeout wrapper
 run_with_timeout() {