specflow-cc 1.12.0 → 1.14.0

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.12.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"