specflow-cc 1.13.0 → 1.14.0

package/commands/sf/health.md

@@ -0,0 +1,220 @@
+---
+name: sf:health
+description: Diagnose .specflow/ directory health and optionally repair issues
+argument-hint: [--repair]
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Write
+  - AskUserQuestion
+---
+
+<purpose>
+Validate `.specflow/` directory integrity and report actionable issues. Checks for missing files, invalid state, orphaned specs, and queue inconsistencies. Optionally repairs auto-fixable issues.
+</purpose>
+
+<context>
+@.specflow/STATE.md
+</context>
+
+<workflow>
+
+## Step 1: Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized. Run `/sf:init` first.
+```
+Exit.
+
+## Step 2: Parse Arguments
+
+Check if `--repair` flag is present.
+
+## Step 3: Run Health Checks
+
+Initialize collectors:
+- `errors[]` — critical issues
+- `warnings[]` — non-critical issues
+- `info[]` — informational notes
+- `repairs[]` — actions taken (if --repair)
+
+### 3.1 Core Files Check
+
+| Check | File | Severity | Repairable |
+|-------|------|----------|------------|
+| E001 | `.specflow/STATE.md` missing | error | Yes — regenerate minimal STATE.md |
+| E002 | `.specflow/STATE.md` missing `## Queue` section | error | No |
+| W001 | `.specflow/todos/TODO.md` missing | warning | Yes — create empty TODO.md |
+| W002 | `.specflow/specs/` directory missing | warning | Yes — create directory |
+| W003 | `.specflow/archive/` directory missing | warning | Yes — create directory |
+| W004 | `.specflow/execution/` directory missing | warning | Yes — create directory |
+
+For each check:
+1. Test existence
+2. If missing and repairable and `--repair`: fix it, add to `repairs[]`
+3. If missing and not repairable: add to `errors[]` or `warnings[]`
+
+### 3.2 STATE.md Integrity
+
+Read STATE.md and validate:
+
+**E003: Active spec references non-existent file**
+- Extract active spec ID from `## Active Specification`
+- If not "—" or empty, check `.specflow/specs/{ID}.md` exists
+- If missing: error (repairable — clear active spec to "—")
+
+**W005: Queue references non-existent spec file**
+- Parse queue table rows
+- For each spec ID, verify `.specflow/specs/{ID}.md` or `.specflow/archive/{ID}.md` exists
+- If missing: warning (not repairable — spec may have been manually deleted)
+
+**W006: Queue has duplicate spec IDs**
+- Parse all IDs from queue table
+- If duplicates found: warning (not repairable)
+
+**W007: STATUS.md malformed — missing required sections**
+- Check for: `## Active Specification`, `## Queue`
+- If missing: warning
+
+### 3.3 Orphaned Specs Check
+
+**I001: Spec file exists but not in queue or archive**
+- List all files in `.specflow/specs/`
+- For each, check if its ID appears in STATE.md queue
+- If not: info (may be work-in-progress)
+
+### 3.4 Archive Consistency
+
+**I002: Spec in queue marked as completed but not archived**
+- Parse queue for specs with status containing "done" or "complete"
+- Check if file exists in `.specflow/archive/`
+- If not: info
+
+### 3.5 Execution State
+
+**W008: Stale execution state files**
+- List `.specflow/execution/*.json`
+- For each, check if the spec ID is the currently active spec
+- If not active: warning (repairable — delete stale files)
+
+## Step 4: Calculate Status
+
+```
+HEALTHY  = 0 errors, 0 warnings
+DEGRADED = 0 errors, 1+ warnings
+BROKEN   = 1+ errors
+```
+
+## Step 5: Display Results
+
+**IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecFlow Health Check
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Status:** HEALTHY | DEGRADED | BROKEN
+**Errors:** N | **Warnings:** N | **Info:** N
+```
+
+**If repairs were performed:**
+```
+### Repairs Performed
+
+- Repaired: {description}
+- Repaired: {description}
+```
+
+**If errors exist:**
+```
+### Errors
+
+- [{code}] {message}
+  Fix: {suggested fix}
+```
+
+**If warnings exist:**
+```
+### Warnings
+
+- [{code}] {message}
+  Fix: {suggested fix}
+```
+
+**If info exists:**
+```
+### Info
+
+- [{code}] {message}
+```
+
+**Footer (if repairable issues exist and --repair was NOT used):**
+```
+---
+{N} issues can be auto-repaired. Run: `/sf:health --repair`
+```
+
+## Step 6: Offer Repair (if applicable)
+
+If repairable issues found and `--repair` was NOT passed:
+- Ask user if they want to run repairs
+- If yes, execute repairs and re-run checks to verify
+
+## Step 7: Verify Repairs (if --repair was used)
+
+Re-run all checks without repair to confirm resolution.
+Display final status.
+
+</workflow>
+
+<error_codes>
+
+| Code | Severity | Description | Repairable |
+|------|----------|-------------|------------|
+| E001 | error | STATE.md not found | Yes |
+| E002 | error | STATE.md missing Queue section | No |
+| E003 | error | Active spec references non-existent file | Yes |
+| W001 | warning | TODO.md not found | Yes |
+| W002 | warning | specs/ directory missing | Yes |
+| W003 | warning | archive/ directory missing | Yes |
+| W004 | warning | execution/ directory missing | Yes |
+| W005 | warning | Queue references non-existent spec | No |
+| W006 | warning | Queue has duplicate spec IDs | No |
+| W007 | warning | STATE.md missing required sections | No |
+| W008 | warning | Stale execution state files | Yes |
+| I001 | info | Spec not in queue (may be WIP) | No |
+| I002 | info | Completed spec not archived | No |
+
+</error_codes>
+
+<repair_actions>
+
+| Action | Effect | Risk |
+|--------|--------|------|
+| Create STATE.md | Minimal template with empty queue | None |
+| Create TODO.md | Empty TODO template | None |
+| Create directories | specs/, archive/, execution/ | None |
+| Clear active spec | Set to "—" if spec file missing | Loses active reference |
+| Delete stale execution | Remove orphaned .json state files | None |
+
+**Not repairable (too risky):**
+- STATE.md content/queue entries
+- Spec file contents
+- Archive decisions
+
+</repair_actions>
+
+<success_criteria>
+- [ ] All health checks executed
+- [ ] Clear status reported (HEALTHY/DEGRADED/BROKEN)
+- [ ] Each issue has error code and suggested fix
+- [ ] --repair only fixes safe, non-destructive issues
+- [ ] Repairs verified by re-running checks
+</success_criteria>

package/commands/sf/help.md

@@ -226,6 +226,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 | /sf:revise   | Revise spec based on audit feedback     |
 | /sf:run      | Execute specification                   |
 | /sf:review   | Review implementation (fresh context)   |
+| /sf:validate | Run validation checklist from spec      |
 | /sf:verify   | Interactive human verification          |
 | /sf:fix      | Fix implementation based on review      |
 | /sf:done     | Finalize, commit, and archive           |
@@ -288,6 +289,7 @@ Workflow: Spec → Audit → Revise → Run → Review → Fix → Done
 | Command      | Description                             |
 |--------------|-----------------------------------------|
 | /sf:help     | This help (or detailed: /sf:help new)   |
+| /sf:health   | Diagnose .specflow/ integrity (--repair)|
 | /sf:history  | View completed specifications           |
 | /sf:metrics  | Project statistics and insights         |
 

package/commands/sf/split.md

@@ -201,9 +201,20 @@ Your choice [1]:
 
 **If 1 (Accept):**
 - Agent creates child specifications
-- Agent archives parent
-- Agent updates STATE.md
-- Continue to Step 7
+- Agent archives parent and updates STATE.md
+- **Verify archival:** After agent completes, check if parent was moved:
+
+```bash
+if [ -f ".specflow/specs/{ID}.md" ]; then
+  mkdir -p .specflow/archive
+  mv ".specflow/specs/{ID}.md" ".specflow/archive/{ID}.md"
+  echo "ARCHIVED"
+else
+  echo "ALREADY_ARCHIVED"
+fi
+```
+
+- Continue to Step 8
 
 **If 2 (Modify):**
 - Use AskUserQuestion to get modifications

package/commands/sf/validate.md

@@ -0,0 +1,154 @@
+---
+name: sf:validate
+description: Validate implementation against spec's validation checklist
+argument-hint: [SPEC-XXX]
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - AskUserQuestion
+---
+
+<purpose>
+Run the validation checklist from a specification after implementation. Executes automated checks (test commands, grep verifications) and prompts for manual checks. Reports pass/fail per item and overall validation status.
+</purpose>
+
+<context>
+@.specflow/STATE.md
+</context>
+
+<workflow>
+
+## Step 1: Verify Initialization
+
+```bash
+[ -d .specflow ] && echo "OK" || echo "NOT_INITIALIZED"
+```
+
+**If NOT_INITIALIZED:**
+```
+SpecFlow not initialized. Run `/sf:init` first.
+```
+Exit.
+
+## Step 2: Resolve Specification
+
+**If SPEC-XXX argument provided:** Use that spec.
+**If no argument:** Use active spec from STATE.md.
+
+Read the spec file from `.specflow/specs/SPEC-XXX.md`.
+
+**If spec not found:** Check `.specflow/archive/SPEC-XXX.md`.
+
+**If still not found:**
+```
+Specification {ID} not found.
+```
+Exit.
+
+## Step 3: Extract Validation Checklist
+
+Look for `## Validation Checklist` section in the spec.
+
+**If section not found:**
+```
+No validation checklist found in {ID}.
+
+The spec was created without a validation checklist.
+You can:
+1. Add one manually to the spec
+2. Use `/sf:verify` for interactive human verification
+3. Use `/sf:review` for AI-powered code review
+```
+Exit.
+
+Parse checklist items. Each item should have:
+- **Action:** What to do (command to run, endpoint to hit, UI to check)
+- **Expected:** What should happen
+
+## Step 4: Display Plan
+
+**IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VALIDATION: {SPEC-XXX}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Spec:** {title}
+**Checklist items:** {count}
+
+Running validation...
+```
+
+## Step 5: Execute Checks
+
+For each checklist item:
+
+### 5.1 Automated Checks
+
+If the item contains a runnable command (backtick-wrapped command, `npm test`, `curl`, etc.):
+1. Execute the command
+2. Check exit code and output against expected result
+3. Record: PASS or FAIL with output
+
+### 5.2 Code Verification Checks
+
+If the item references code behavior (file exists, function exists, pattern present):
+1. Use Glob/Grep/Read to verify
+2. Record: PASS or FAIL
+
+### 5.3 Manual Checks
+
+If the item requires manual/visual verification (UI behavior, browser check):
+1. Ask user via AskUserQuestion: "Did this pass? {item description}"
+2. Record user's response
+
+### 5.4 Track Results
+
+For each item, record:
+- Item description
+- Type: automated / code / manual
+- Result: PASS / FAIL / SKIP
+- Details: output or user note
+
+## Step 6: Display Results
+
+**IMPORTANT:** Output the following directly as formatted text, NOT wrapped in a markdown code block:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VALIDATION RESULTS: {SPEC-XXX}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| # | Check | Type | Result |
+|---|-------|------|--------|
+| 1 | {description} | automated | PASS |
+| 2 | {description} | code | PASS |
+| 3 | {description} | manual | FAIL |
+
+---
+
+**Result:** {passed}/{total} checks passed
+
+{If all passed:}
+Validation PASSED. Ready for `/sf:done`.
+
+{If any failed:}
+Validation FAILED. Fix issues and re-run `/sf:validate`.
+```
+
+</workflow>
+
+<success_criteria>
+- [ ] Spec resolved (argument or active)
+- [ ] Validation checklist extracted from spec
+- [ ] Missing checklist handled gracefully
+- [ ] Automated commands executed and verified
+- [ ] Code checks performed via tools
+- [ ] Manual checks prompted to user
+- [ ] Clear pass/fail report displayed
+- [ ] Guidance on next step provided
+</success_criteria>

package/hooks/context-monitor.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Context Monitor - PostToolUse hook
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. Makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// How it works:
+// 1. The statusline hook writes metrics to /tmp/claude-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, it injects a warning
+//    as additionalContext, which the agent sees in its conversation
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WARNING_THRESHOLD = 35;
+const CRITICAL_THRESHOLD = 25;
+const STALE_SECONDS = 60;
+const DEBOUNCE_CALLS = 5;
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+
+    if (!fs.existsSync(metricsPath)) {
+      process.exit(0);
+    }
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Debounce logic
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {}
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Detect if SpecFlow is active
+    const cwd = data.cwd || process.cwd();
+    const isSfActive = fs.existsSync(path.join(cwd, '.specflow', 'STATE.md'));
+
+    let message;
+    if (isCritical) {
+      message = isSfActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Do NOT start new complex work. ' +
+          'Inform the user so they can run /sf:pause at the next natural stopping point.'
+        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Inform the user that context is low and ask how they want to proceed.';
+    } else {
+      message = isSfActive
+        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is getting limited. Avoid starting new complex work. ' +
+          'Inform the user so they can prepare to pause.'
+        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Be aware that context is getting limited. Avoid unnecessary exploration or starting new complex work.';
+    }
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: message
+      }
+    }));
+  } catch (e) {
+    process.exit(0);
+  }
+});

package/hooks/statusline.js

@@ -4,16 +4,20 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 // Read JSON from stdin (Claude Code protocol)
 let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
   try {
     const data = JSON.parse(input);
     const model = data.model?.display_name || 'Claude';
     const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
     const remaining = data.context_window?.remaining_percentage;
 
     // Context window display (shows USED percentage scaled to 80% limit)
@@ -25,6 +29,19 @@ process.stdin.on('end', () => {
       // Scale: 80% real usage = 100% displayed
       const used = Math.min(100, Math.round((rawUsed / 80) * 100));
 
+      // Write context metrics to bridge file for the context-monitor hook
+      if (session) {
+        try {
+          const bridgePath = path.join(os.tmpdir(), `claude-ctx-${session}.json`);
+          fs.writeFileSync(bridgePath, JSON.stringify({
+            session_id: session,
+            remaining_percentage: remaining,
+            used_pct: used,
+            timestamp: Math.floor(Date.now() / 1000)
+          }));
+        } catch (e) {}
+      }
+
       // Build progress bar (10 segments)
       const filled = Math.floor(used / 10);
       const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specflow-cc",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Spec-driven development system for Claude Code — quality-first workflow with explicit audit cycles",
   "bin": {
     "specflow-cc": "bin/install.js"