deepflow 0.1.52 → 0.1.53

package/bin/install.js

@@ -8,6 +8,18 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');
+const { execFileSync } = require('child_process');
+
+// Subcommand routing: `deepflow auto [...]` -> bin/deepflow-auto.sh
+if (process.argv[2] === 'auto') {
+  const scriptPath = path.join(__dirname, 'deepflow-auto.sh');
+  try {
+    execFileSync('bash', [scriptPath, ...process.argv.slice(3)], { stdio: 'inherit' });
+  } catch (e) {
+    process.exit(e.status || 1);
+  }
+  process.exit(0);
+}
 
 // Colors
 const c = {
@@ -118,6 +130,13 @@ async function main() {
     }
   }
 
+  // Ensure deepflow-auto.sh is executable
+  const autoScript = path.join(PACKAGE_DIR, 'bin', 'deepflow-auto.sh');
+  if (fs.existsSync(autoScript)) {
+    fs.chmodSync(autoScript, 0o755);
+    log('deepflow-auto.sh marked executable');
+  }
+
   // Get version from package.json (single source of truth)
   const packageJson = require(path.join(PACKAGE_DIR, 'package.json'));
   const installedVersion = packageJson.version;
@@ -154,9 +173,11 @@ async function main() {
   console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:note, /df:resume, /df:update');
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness');
   console.log('  agents/          — reasoner');
+  console.log('  bin/             — deepflow auto (autonomous overnight execution)');
   if (level === 'global') {
     console.log('  hooks/           — statusline, update checker');
   }
+  console.log('  hooks/df-spec-*  — spec validation (auto-enforced by /df:spec and /df:plan)');
   console.log('  env/             — ENABLE_LSP_TOOL (code navigation via goToDefinition, findReferences, workspaceSymbol)');
   console.log('');
   if (level === 'project') {

package/hooks/df-spec-lint.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * deepflow spec linter
+ * Validates spec files against hard invariants and advisory checks.
+ *
+ * Usage (CLI):   node df-spec-lint.js <spec-file.md>
+ * Usage (module): const { validateSpec } = require('./df-spec-lint');
+ */
+
+'use strict';
+
+const REQUIRED_SECTIONS = [
+  'Objective',
+  'Requirements',
+  'Constraints',
+  'Out of Scope',
+  'Acceptance Criteria',
+  'Technical Notes',
+];
+
+/**
+ * Validate a spec's content against hard invariants and advisory checks.
+ *
+ * @param {string} content  - The raw markdown content of the spec file.
+ * @param {object} opts
+ * @param {'interactive'|'auto'} opts.mode
+ * @returns {{ hard: string[], advisory: string[] }}
+ */
+function validateSpec(content, { mode = 'interactive' } = {}) {
+  const hard = [];
+  const advisory = [];
+
+  // ── (a) Required sections ────────────────────────────────────────────
+  const headersFound = [];
+  for (const line of content.split('\n')) {
+    const m = line.match(/^##\s+(.+)/i);
+    if (m) headersFound.push(m[1].trim());
+  }
+
+  for (const section of REQUIRED_SECTIONS) {
+    const found = headersFound.some(
+      (h) => h.toLowerCase() === section.toLowerCase()
+    );
+    if (!found) {
+      hard.push(`Missing required section: "## ${section}"`);
+    }
+  }
+
+  // ── (b) Requirement lines must have REQ-N: prefix ───────────────────
+  const reqSection = extractSection(content, 'Requirements');
+  if (reqSection !== null) {
+    const lines = reqSection.split('\n');
+    for (const line of lines) {
+      // Only consider list items (lines starting with - or *)
+      if (!/^\s*[-*]\s+/.test(line)) continue;
+      // Must match REQ-\d+: with optional bold markers
+      if (!/^\s*[-*]\s*\*{0,2}(REQ-\d+)\*{0,2}\s*:/.test(line)) {
+        hard.push(
+          `Requirement line missing REQ-N: prefix: "${line.trim()}"`
+        );
+      }
+    }
+  }
+
+  // ── (c) Acceptance Criteria must use checkbox format ─────────────────
+  const acSection = extractSection(content, 'Acceptance Criteria');
+  if (acSection !== null) {
+    const lines = acSection.split('\n');
+    for (const line of lines) {
+      if (!/^\s*[-*]\s+/.test(line)) continue;
+      if (!/^\s*- \[ \]/.test(line)) {
+        hard.push(
+          `Acceptance Criteria line missing "- [ ]" checkbox: "${line.trim()}"`
+        );
+      }
+    }
+  }
+
+  // ── (d) No duplicate REQ-N IDs ──────────────────────────────────────
+  const reqIdPattern = /\*{0,2}(REQ-\d+)\*{0,2}\s*:/g;
+  const seenIds = new Map();
+  let match;
+  while ((match = reqIdPattern.exec(content)) !== null) {
+    const id = match[1];
+    if (seenIds.has(id)) {
+      hard.push(`Duplicate requirement ID: ${id}`);
+    }
+    seenIds.set(id, true);
+  }
+
+  // ── Advisory checks ──────────────────────────────────────────────────
+
+  // (adv-a) Line count > 100
+  const lineCount = content.split('\n').length;
+  if (lineCount > 100) {
+    advisory.push(`Spec exceeds 100 lines (${lineCount} lines)`);
+  }
+
+  // (adv-b) Orphaned REQ-N IDs not referenced in Acceptance Criteria
+  if (reqSection !== null && acSection !== null) {
+    const reqIds = [];
+    const reqLinePattern = /\*{0,2}(REQ-\d+)\*{0,2}\s*:/g;
+    let reqMatch;
+    while ((reqMatch = reqLinePattern.exec(reqSection)) !== null) {
+      reqIds.push(reqMatch[1]);
+    }
+    for (const id of reqIds) {
+      if (!acSection.includes(id)) {
+        advisory.push(`Orphaned requirement: ${id} not found in Acceptance Criteria`);
+      }
+    }
+  }
+
+  // (adv-c) Technical Notes section > 10 lines
+  const techNotes = extractSection(content, 'Technical Notes');
+  if (techNotes !== null) {
+    const techLines = techNotes.split('\n').filter((l) => l.trim().length > 0);
+    if (techLines.length > 10) {
+      advisory.push(`Technical Notes section too long (${techLines.length} non-empty lines, limit 10)`);
+    }
+  }
+
+  // (adv-d) More than 12 requirements
+  if (seenIds.size > 12) {
+    advisory.push(`Too many requirements (${seenIds.size}, limit 12)`);
+  }
+
+  // ── Auto-mode escalation ─────────────────────────────────────────────
+  if (mode === 'auto') {
+    hard.push(...advisory.splice(0, advisory.length));
+  }
+
+  return { hard, advisory };
+}
+
+/**
+ * Extract the content of a named ## section (up to the next ## or EOF).
+ * Returns null if the section is not found.
+ */
+function extractSection(content, sectionName) {
+  const lines = content.split('\n');
+  let capturing = false;
+  const captured = [];
+
+  for (const line of lines) {
+    const headerMatch = line.match(/^## \s*(.+)/);
+    if (headerMatch) {
+      if (capturing) break; // hit the next section
+      if (headerMatch[1].trim().toLowerCase() === sectionName.toLowerCase()) {
+        capturing = true;
+      }
+      continue;
+    }
+    if (capturing) {
+      captured.push(line);
+    }
+  }
+
+  return capturing ? captured.join('\n') : null;
+}
+
+// ── CLI entry point ──────────────────────────────────────────────────────
+if (require.main === module) {
+  const fs = require('fs');
+
+  const filePath = process.argv[2];
+  if (!filePath) {
+    console.error('Usage: df-spec-lint.js <spec-file.md>');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const mode = process.argv.includes('--auto') ? 'auto' : 'interactive';
+  const result = validateSpec(content, { mode });
+
+  if (result.hard.length > 0) {
+    console.error('HARD invariant failures:');
+    for (const msg of result.hard) {
+      console.error(`  [FAIL] ${msg}`);
+    }
+  }
+
+  if (result.advisory.length > 0) {
+    console.warn('Advisory warnings:');
+    for (const msg of result.advisory) {
+      console.warn(`  [WARN] ${msg}`);
+    }
+  }
+
+  if (result.hard.length === 0 && result.advisory.length === 0) {
+    console.log('All checks passed.');
+  }
+
+  process.exit(result.hard.length > 0 ? 1 : 0);
+}
+
+module.exports = { validateSpec };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.52",
+  "version": "0.1.53",
   "description": "Stay in flow state - lightweight spec-driven task orchestration for Claude Code",
   "keywords": [
     "claude",

package/src/commands/df/plan.md

@@ -36,6 +36,8 @@ Load:
 Determine source_dir from config or default to src/
 ```
 
+Run `validateSpec` on each loaded spec. Hard failures → skip that spec entirely and emit an error line. Advisory warnings → include them in plan output.
+
 If no new specs: report counts, suggest `/df:execute`.
 
 ### 2. CHECK PAST EXPERIMENTS (SPIKE-FIRST)
@@ -98,6 +100,8 @@ Scale agent count based on codebase size:
 
 Spawn `Task(subagent_type="reasoner", model="opus")`. Reasoner maps each requirement to DONE / PARTIAL / MISSING / CONFLICT. Flag spec gaps; don't silently assume.
 
+Check spec health: verify REQ-AC alignment, requirement clarity, and completeness. Note any issues (orphan ACs, vague requirements) in plan output.
+
 **Priority order:** Dependencies → Impact → Risk
 
 ### 6. GENERATE SPIKE TASKS (IF NEEDED)

package/src/commands/df/spec.md

@@ -86,10 +86,16 @@ The reasoner will:
 - Identify constraints from existing architecture
 - Suggest requirements based on patterns found
 - Flag potential conflicts with existing code
+- Verify every REQ-N has at least one corresponding Acceptance Criterion; flag any uncovered requirements
+- Identify and flag vague or untestable requirements before finalizing (e.g., "should be fast" without a metric)
 
 ### 4. GENERATE SPEC
 
-Once gaps covered and context gathered, create `specs/{name}.md`:
+Once gaps covered and context gathered, run `validateSpec` on the generated content **before** writing the file.
+- **Hard failure:** Do NOT write the file. Show errors to the user with actionable fix suggestions and re-synthesize.
+- **Advisory warnings:** Write the file but display the warnings to the user after confirmation.
+
+Create `specs/{name}.md`:
 
 ```markdown
 # {Name}