specflow-cc 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to SpecFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.14.0] - 2026-03-05
+
+### Added
+
+- **Context Monitor Hook** — agent-facing context awareness via PostToolUse hook
+  - Statusline writes bridge file to `/tmp/claude-ctx-{session}.json`
+  - New `hooks/context-monitor.js` reads metrics and injects WARNING (35% remaining) / CRITICAL (25%) warnings into agent context
+  - Debounce (5 tool uses between warnings), severity escalation bypasses debounce
+  - Integrates with `/sf:pause` for graceful session saves
+  - Installer auto-registers the hook in settings.json
+
+- **`/sf:health`** — diagnose `.specflow/` directory integrity
+  - 13 error codes across 3 severity levels (error, warning, info)
+  - Checks: STATE.md integrity, orphaned specs, queue consistency, missing directories, stale execution state
+  - `--repair` flag for safe auto-fixes (create missing dirs, regenerate STATE.md, clear stale state)
+  - Repair verification: re-runs checks after repair to confirm resolution
+
+- **`/sf:validate`** — run validation checklist from specification
+  - Executes automated checks (test commands), code verifications (grep/glob), and manual prompts
+  - Pass/fail report per checklist item with overall validation status
+  - Graceful handling when spec has no validation checklist
+
+- **Validation Checklist in spec template** — spec-creator generates `## Validation Checklist` section for medium/large specs
+  - 3-5 concrete verification steps with expected outcomes
+  - Each item: action + expected result (e.g., "Run `npm test` — all pass")
+
+- **Enriched completion summaries** in `/sf:done`
+  - New sections: Outcome, Key Files, Patterns Established, Deviations
+  - Decisions extracted from both spec content and completion section
+
+- **Centralized CLI Tooling** (`bin/sf-tools.cjs`) — single Node.js CLI for SpecFlow operations
+  - `spec load <id>` — parse spec file, return frontmatter + sections as JSON
+  - `spec list [--status <s>]` — list specs with optional status filter
+  - `spec next-id` — next available SPEC-XXX number (checks specs/ + archive/)
+  - `queue next` — first actionable spec from queue
+  - `state get` / `state set-active <id> <status>` — STATE.md CRUD
+  - `resolve-model <agent-type>` — model resolution by profile
+  - `verify-structure` — `.specflow/` integrity checks
+  - `generate-slug <text>` — URL-safe slug generation
+  - Modular architecture: `bin/lib/core.cjs`, `state.cjs`, `spec.cjs`, `config.cjs`, `verify.cjs`
+  - 42 tests using Node.js `assert` (no external dependencies)
+
+### Fixed
+
+- Parent spec now correctly archived after `/sf:split`
+- `.specflow/` directory excluded from git tracking
+
+---
+
 ## [1.13.0] - 2026-02-11
 
 ### Added

package/README.md

@@ -200,15 +200,16 @@ If issues are found, `/sf:fix` addresses them. Loop until approved.
 
 ---
 
-### 5. Verify (Optional)
+### 5. Validate & Verify (Optional)
 
 ```
+/sf:validate
 /sf:verify
 ```
 
-Automated checks confirm code exists and tests pass. But does it actually *work*?
+**Validate** runs the spec's validation checklist — automated test commands, code checks, and manual verification prompts. Pass/fail per item.
 
-This step walks you through manual verification:
+**Verify** walks you through interactive acceptance testing:
 
 - "Can you log in with OAuth?"
 - "Does the redirect work?"
@@ -216,7 +217,7 @@ This step walks you through manual verification:
 
 You confirm each item. If something's broken, the system helps diagnose and creates fix plans.
 
-**Creates:** Verification record
+**Creates:** Validation/verification record
 
 ---
 
@@ -237,12 +238,12 @@ Your spec becomes documentation: why the code exists, what decisions were made,
 ```
                         /sf:quick (trivial tasks)
                               ↓
-/sf:new  →  /sf:audit  →  /sf:run  →  /sf:review  →  /sf:verify  →  /sf:done
-              ↓                          ↓              ↓
-         /sf:revise                  /sf:fix      (optional UAT)
-         (if needed)                 (if needed)
+/sf:new → /sf:audit → /sf:run → /sf:review → /sf:validate → /sf:verify → /sf:done
+            ↓                      ↓            ↓               ↓
+       /sf:revise              /sf:fix    (checklist)      (optional UAT)
+       (if needed)             (if needed)
 
-         /sf:autopilot — runs the entire flow above automatically
+       /sf:autopilot — runs the entire flow above automatically
 ```
 
 **Key principle:** Audits and reviews run in fresh context — no bias from creation.
@@ -312,6 +313,7 @@ Six months later, you can read the spec and understand not just *what* was built
 | `/sf:run` | Implement specification |
 | `/sf:review` | Review implementation (fresh context) |
 | `/sf:fix` | Fix based on review feedback |
+| `/sf:validate` | Run validation checklist from spec |
 | `/sf:verify` | Interactive user acceptance testing |
 | `/sf:done` | Complete and archive |
 | `/sf:autopilot` | Run full lifecycle autonomously |
@@ -396,6 +398,7 @@ before showing interactive options.
 | `/sf:deps` | Show spec dependencies |
 | `/sf:pause` | Save session context |
 | `/sf:resume` | Restore session |
+| `/sf:health` | Diagnose `.specflow/` integrity |
 | `/sf:help` | Command reference |
 
 ---
@@ -481,6 +484,10 @@ Use `max` for maximum quality everywhere, `quality` for critical features, `budg
 - Use `/sf:split` to decompose into smaller specs
 - Or let the system auto-decompose during `/sf:run`
 
+**STATE.md or queue seems corrupted?**
+- Run `/sf:health` to diagnose issues
+- Use `/sf:health --repair` for safe auto-fixes
+
 ---
 
 ## Philosophy

package/agents/spec-creator.md

@@ -146,8 +146,9 @@ Write to `.specflow/specs/SPEC-XXX.md` using the template structure:
 4. **Task:** What to do
 5. **Requirements:** Files, interfaces, deletions
 6. **Acceptance Criteria:** Specific, measurable
-7. **Constraints:** What NOT to do
-8. **Assumptions:** What you assumed (clearly marked)
+7. **Validation Checklist** (medium/large specs only): 3-5 concrete verification steps with expected outcomes. Each item = action + expected result. Examples: "Run `npm test` — all pass", "POST /api/users with invalid email — returns 422", "Open settings page — new toggle visible"
+8. **Constraints:** What NOT to do
+9. **Assumptions:** What you assumed (clearly marked)
    - **If `<prior_discussion>` provided:** Decisions from discussion are facts, not assumptions
 
 ## Step 5.5: Generate Implementation Tasks (for medium and large specs)

package/agents/spec-splitter.md

@@ -1,7 +1,7 @@
 ---
 name: sf-spec-splitter
 description: Analyzes large specifications and splits them into manageable sub-specifications with dependencies
-tools: Read, Write, Glob, Grep
+tools: Read, Write, Glob, Grep, Bash
 ---
 
 <role>

package/bin/install.js

@@ -266,6 +266,26 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
     console.log(`  ${green}✓${reset} Configured statusline`);
   }
 
+  // Configure context-monitor hook
+  const isGlobal = statuslineCommand.includes('$HOME');
+  const monitorCommand = isGlobal
+    ? 'node "$HOME/.claude/hooks/context-monitor.js"'
+    : 'node .claude/hooks/context-monitor.js';
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+
+  const hasMonitor = settings.hooks.PostToolUse.some(h =>
+    h.command && h.command.includes('context-monitor')
+  );
+  if (!hasMonitor) {
+    settings.hooks.PostToolUse.push({
+      type: 'command',
+      command: monitorCommand
+    });
+    console.log(`  ${green}✓${reset} Configured context monitor hook`);
+  }
+
   writeSettings(settingsPath, settings);
 
   console.log(`

package/bin/lib/config.cjs

@@ -0,0 +1,91 @@
+/**
+ * bin/lib/config.cjs — Config reading and model resolution
+ *
+ * Exports: MODEL_PROFILES, loadConfig(), cmdResolveModel()
+ */
+
+'use strict';
+
+const path = require('path');
+const { output, error, safeReadFile } = require('./core.cjs');
+
+/**
+ * Hardcoded MODEL_PROFILES table.
+ * MUST exactly match the profile table in commands/sf/run.md.
+ */
+const MODEL_PROFILES = {
+  'spec-creator':               { max: 'opus', quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'spec-auditor':               { max: 'opus', quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'spec-splitter':              { max: 'opus', quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'discusser':                  { max: 'opus', quality: 'opus',   balanced: 'opus',   budget: 'sonnet' },
+  'spec-executor':              { max: 'opus', quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'spec-executor-orchestrator': { max: 'opus', quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'spec-executor-worker':       { max: 'opus', quality: 'opus',   balanced: 'sonnet', budget: 'sonnet' },
+  'impl-reviewer':              { max: 'opus', quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'spec-reviser':               { max: 'opus', quality: 'sonnet', balanced: 'sonnet', budget: 'sonnet' },
+  'researcher':                 { max: 'opus', quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'codebase-scanner':           { max: 'opus', quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+};
+
+/**
+ * Load .specflow/config.json. Returns defaults if not found.
+ * @param {string} cwd - Working directory
+ * @returns {Object} Config object
+ */
+function loadConfig(cwd) {
+  const configPath = path.join(cwd, '.specflow', 'config.json');
+  const content = safeReadFile(configPath);
+
+  if (!content) {
+    return { model_profile: 'balanced' };
+  }
+
+  try {
+    const config = JSON.parse(content);
+    return {
+      model_profile: config.model_profile || 'balanced',
+      ...config,
+    };
+  } catch (e) {
+    return { model_profile: 'balanced' };
+  }
+}
+
+/**
+ * Resolve model for a given agent type based on current profile.
+ * @param {string} cwd - Working directory
+ * @param {string} agentType - Agent type (e.g., "spec-executor")
+ * @param {boolean} raw - Output raw string
+ */
+function cmdResolveModel(cwd, agentType, raw) {
+  if (!agentType) {
+    error('Missing agent type. Usage: resolve-model <agent-type>');
+  }
+
+  const config = loadConfig(cwd);
+  const profile = config.model_profile || 'balanced';
+
+  const agentProfiles = MODEL_PROFILES[agentType];
+
+  if (!agentProfiles) {
+    error('Unknown agent type: ' + agentType + '. Known types: ' + Object.keys(MODEL_PROFILES).join(', '));
+  }
+
+  const model = agentProfiles[profile];
+
+  if (!model) {
+    error('Unknown profile: ' + profile + '. Known profiles: max, quality, balanced, budget');
+  }
+
+  output({
+    agent: agentType,
+    profile: profile,
+    model: model,
+  }, raw, model);
+}
+
+module.exports = {
+  MODEL_PROFILES,
+  loadConfig,
+  cmdResolveModel,
+};

package/bin/lib/core.cjs

@@ -0,0 +1,120 @@
+/**
+ * bin/lib/core.cjs — Shared utilities for sf-tools CLI
+ *
+ * Exports: output(), error(), safeReadFile(), parseFrontmatter(), generateSlug()
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Output result to stdout as JSON, or raw string if raw flag is set.
+ * @param {*} result - The result object to output
+ * @param {boolean} raw - If true, output rawValue as plain string
+ * @param {string} [rawValue] - Plain string to output when raw is true
+ */
+function output(result, raw, rawValue) {
+  if (raw && rawValue !== undefined) {
+    process.stdout.write(String(rawValue) + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  }
+}
+
+/**
+ * Output error message to stderr and exit with code 1.
+ * @param {string} message - Error message
+ */
+function error(message) {
+  process.stderr.write('Error: ' + message + '\n');
+  process.exit(1);
+}
+
+/**
+ * Safely read a file, returning its contents as a string or null if not found.
+ * @param {string} filePath - Absolute or relative path to the file
+ * @returns {string|null} File contents or null
+ */
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Expects `---` delimited YAML at the start of the file.
+ * Returns simple key: value pairs only (no nested objects, no arrays).
+ * All values are returned as strings. No type coercion is performed.
+ *
+ * @param {string} content - Full file content
+ * @returns {{ frontmatter: Object, body: string }}
+ */
+function parseFrontmatter(content) {
+  if (!content || typeof content !== 'string') {
+    return { frontmatter: {}, body: content || '' };
+  }
+
+  const trimmed = content.trimStart();
+
+  if (!trimmed.startsWith('---')) {
+    return { frontmatter: {}, body: content };
+  }
+
+  // Find the closing ---
+  const secondDash = trimmed.indexOf('---', 3);
+  if (secondDash === -1) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const yamlBlock = trimmed.substring(3, secondDash).trim();
+  const body = trimmed.substring(secondDash + 3).replace(/^\r?\n/, '');
+
+  const frontmatter = {};
+  const lines = yamlBlock.split('\n');
+
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine || trimmedLine.startsWith('#')) continue;
+
+    const colonIndex = trimmedLine.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = trimmedLine.substring(0, colonIndex).trim();
+    const value = trimmedLine.substring(colonIndex + 1).trim();
+
+    // All values returned as strings — no type coercion
+    frontmatter[key] = value;
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Generate a URL-safe slug from text.
+ * Lowercase, replace spaces/special chars with hyphens, collapse multiples, trim edges.
+ *
+ * @param {string} text - Input text
+ * @returns {string} URL-safe slug
+ */
+function generateSlug(text) {
+  if (!text || typeof text !== 'string') return '';
+
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')  // replace non-alphanumeric with hyphens
+    .replace(/-+/g, '-')          // collapse multiple hyphens
+    .replace(/^-|-$/g, '');       // trim leading/trailing hyphens
+}
+
+module.exports = {
+  output,
+  error,
+  safeReadFile,
+  parseFrontmatter,
+  generateSlug,
+};

package/bin/lib/spec.cjs

@@ -0,0 +1,130 @@
+/**
+ * bin/lib/spec.cjs — Spec operations
+ *
+ * Exports: cmdSpecLoad(), cmdSpecList(), cmdSpecNextId()
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, parseFrontmatter } = require('./core.cjs');
+
+/**
+ * Load and parse a spec file.
+ * @param {string} cwd - Working directory
+ * @param {string} id - Spec ID (e.g., "SPEC-007")
+ * @param {boolean} raw - Output raw string
+ */
+function cmdSpecLoad(cwd, id, raw) {
+  if (!id) {
+    error('Missing spec ID. Usage: spec load <id>');
+  }
+
+  const specPath = path.join(cwd, '.specflow', 'specs', id + '.md');
+  const content = safeReadFile(specPath);
+
+  if (!content) {
+    error('Spec not found: ' + specPath);
+  }
+
+  const parsed = parseFrontmatter(content);
+
+  output({
+    frontmatter: parsed.frontmatter,
+    body: parsed.body,
+  }, raw, parsed.body);
+}
+
+/**
+ * List all specs in .specflow/specs/.
+ * Extracts id, title, status, complexity, priority from each.
+ * Title is parsed from the first # heading in the body.
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdSpecList(cwd, raw) {
+  const specsDir = path.join(cwd, '.specflow', 'specs');
+
+  let files;
+  try {
+    files = fs.readdirSync(specsDir).filter(f => f.endsWith('.md')).sort();
+  } catch (e) {
+    error('Cannot read specs directory: ' + specsDir);
+  }
+
+  const specs = [];
+
+  for (const file of files) {
+    const content = safeReadFile(path.join(specsDir, file));
+    if (!content) continue;
+
+    const parsed = parseFrontmatter(content);
+    const fm = parsed.frontmatter;
+
+    // Extract title from first # heading in body
+    let title = '';
+    const titleMatch = parsed.body.match(/^#\s+(.+)$/m);
+    if (titleMatch) {
+      title = titleMatch[1].trim();
+    }
+
+    specs.push({
+      id: fm.id || file.replace('.md', ''),
+      title: title,
+      status: fm.status || '',
+      complexity: fm.complexity || '',
+      priority: fm.priority || '',
+    });
+  }
+
+  output(specs, raw, specs.map(s => s.id).join('\n'));
+}
+
+/**
+ * Calculate the next available SPEC-XXX number.
+ * Scans both .specflow/specs/ and .specflow/archive/ directories.
+ * Ignores non-numeric spec IDs (e.g., SPEC-GSD-A).
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdSpecNextId(cwd, raw) {
+  const dirs = [
+    path.join(cwd, '.specflow', 'specs'),
+    path.join(cwd, '.specflow', 'archive'),
+  ];
+
+  let maxNum = 0;
+
+  for (const dir of dirs) {
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+    } catch (e) {
+      continue; // directory may not exist
+    }
+
+    for (const file of files) {
+      // Match SPEC-NNN pattern (numeric only)
+      const match = file.match(/^SPEC-(\d+)\.md$/);
+      if (match) {
+        const num = parseInt(match[1], 10);
+        if (num > maxNum) maxNum = num;
+      }
+    }
+  }
+
+  const nextNumber = maxNum + 1;
+  const nextId = 'SPEC-' + String(nextNumber).padStart(3, '0');
+
+  output({
+    next_id: nextId,
+    next_number: nextNumber,
+  }, raw, nextId);
+}
+
+module.exports = {
+  cmdSpecLoad,
+  cmdSpecList,
+  cmdSpecNextId,
+};