deepflow 0.1.105 → 0.1.107

package/hooks/df-explore-protocol.js

@@ -18,6 +18,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { readStdinIfMain } = require('./lib/hook-stdin');
 
 /**
  * Locate the explore-protocol.md template.
@@ -34,50 +35,40 @@ function findProtocol(cwd) {
   return null;
 }
 
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => raw += chunk);
-process.stdin.on('end', () => {
-  try {
-    const payload = JSON.parse(raw);
-    const { tool_name, tool_input, cwd } = payload;
+readStdinIfMain(module, (payload) => {
+  const { tool_name, tool_input, cwd } = payload;
 
-    // Only intercept Agent calls with subagent_type "Explore"
-    if (tool_name !== 'Agent') {
-      process.exit(0);
-    }
-    const subagentType = (tool_input.subagent_type || '').toLowerCase();
-    if (subagentType !== 'explore') {
-      process.exit(0);
-    }
+  // Only intercept Agent calls with subagent_type "Explore"
+  if (tool_name !== 'Agent') {
+    return;
+  }
+  const subagentType = (tool_input.subagent_type || '').toLowerCase();
+  if (subagentType !== 'explore') {
+    return;
+  }
 
-    const protocolPath = findProtocol(cwd || process.cwd());
-    if (!protocolPath) {
-      // No template found — allow without modification
-      process.exit(0);
-    }
+  const protocolPath = findProtocol(cwd || process.cwd());
+  if (!protocolPath) {
+    // No template found — allow without modification
+    return;
+  }
 
-    const protocol = fs.readFileSync(protocolPath, 'utf8').trim();
-    const originalPrompt = tool_input.prompt || '';
+  const protocol = fs.readFileSync(protocolPath, 'utf8').trim();
+  const originalPrompt = tool_input.prompt || '';
 
-    // Append protocol as a system-level suffix the agent must follow
-    const updatedPrompt = `${originalPrompt}\n\n---\n## Search Protocol (auto-injected — MUST follow)\n\n${protocol}`;
+  // Append protocol as a system-level suffix the agent must follow
+  const updatedPrompt = `${originalPrompt}\n\n---\n## Search Protocol (auto-injected — MUST follow)\n\n${protocol}`;
 
-    const result = {
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'allow',
-        updatedInput: {
-          ...tool_input,
-          prompt: updatedPrompt,
-        },
+  const result = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      updatedInput: {
+        ...tool_input,
+        prompt: updatedPrompt,
       },
-    };
+    },
+  };
 
-    process.stdout.write(JSON.stringify(result));
-    process.exit(0);
-  } catch {
-    // Never break Claude Code
-    process.exit(0);
-  }
+  process.stdout.write(JSON.stringify(result));
 });

package/hooks/df-invariant-check.js

@@ -18,6 +18,7 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const { extractSection } = require('./df-spec-lint');
+const { readStdinIfMain } = require('./lib/hook-stdin');
 
 // ── LSP availability check (REQ-5, AC-11) ────────────────────────────────────
 
@@ -141,6 +142,7 @@ const TAGS = {
   STUB: 'STUB',               // Incomplete stub left in production code
   PHANTOM: 'PHANTOM',         // Reference to non-existent symbol/file/function
   SCOPE_GAP: 'SCOPE_GAP',     // Implementation goes beyond or falls short of spec scope
+  CONFIG_GUARD: 'CONFIG_GUARD', // config.yaml/yml modified inside a worktree path
 };
 
 // ── Diff parsing ──────────────────────────────────────────────────────────────
@@ -947,6 +949,43 @@ function formatOutput(results) {
 
 // ── Core API ──────────────────────────────────────────────────────────────────
 
+/**
+ * REQ-3: Guard against creation or modification of .deepflow/config.yaml (or config.yml)
+ * inside worktree paths. Agents must never alter project-level config from a worktree.
+ *
+ * Matches `+++ b/` diff header lines whose path contains `.deepflow/config.yaml` or
+ * `.deepflow/config.yml`, regardless of worktree depth.
+ *
+ * Always HARD severity — no advisory variant. Tag: [CONFIG_GUARD]
+ *
+ * @param {Array} files - Parsed diff files
+ * @param {string} specContent - Raw spec markdown (unused, kept for uniform signature)
+ * @param {string} taskType - Task type (unused, check always runs)
+ * @returns {Array<{ file: string, line: number, tag: string, description: string }>}
+ */
+function checkConfigYamlGuard(files, specContent, taskType) { // eslint-disable-line no-unused-vars
+  const violations = [];
+
+  // Pattern matches .deepflow/config.yaml or .deepflow/config.yml anywhere in the path,
+  // which covers worktree sub-paths like .claude/worktrees/agent-xyz/.deepflow/config.yaml
+  const CONFIG_PATTERN = /\.deepflow\/config\.ya?ml$/;
+
+  for (const f of files) {
+    if (CONFIG_PATTERN.test(f.file)) {
+      violations.push({
+        file: f.file,
+        line: 1,
+        tag: TAGS.CONFIG_GUARD,
+        description:
+          `[CONFIG_GUARD] Modification of "${f.file}" detected inside a worktree. ` +
+          'Agents must not create or modify .deepflow/config.yaml from within a worktree.',
+      });
+    }
+  }
+
+  return violations;
+}
+
 /**
  * Check implementation diffs against spec invariants.
  *
@@ -1011,6 +1050,10 @@ function checkInvariants(diff, specContent, opts = {}) {
   const reqOnlyInTestsViolations = checkReqOnlyInTests(files, specContent, taskType);
   hard.push(...reqOnlyInTestsViolations);
 
+  // REQ-3: config.yaml guard — always hard, no advisory variant
+  const configGuardViolations = checkConfigYamlGuard(files, specContent, taskType);
+  hard.push(...configGuardViolations);
+
   // ── Auto-mode escalation (REQ-9) ─────────────────────────────────────────
   // In auto mode (non-interactive CI/hook runs), all advisory items are promoted
   // to hard failures so the pipeline blocks on any violation.
@@ -1080,78 +1123,63 @@ function isGitCommitBash(toolName, toolInput) {
   return /git\s+commit\b/.test(cmd);
 }
 
-// Run hook mode when stdin is not a TTY (i.e., piped payload from Claude Code)
-if (!process.stdin.isTTY) {
-  let raw = '';
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', (chunk) => { raw += chunk; });
-  process.stdin.on('end', () => {
-    let data;
-    try {
-      data = JSON.parse(raw);
-    } catch (_) {
-      // Not valid JSON — not a hook payload, exit silently
-      process.exit(0);
-    }
+// Run hook mode when called as main module (stdin payload from Claude Code).
+// readStdinIfMain guards against hanging when required by tests.
+readStdinIfMain(module, (data) => {
+  // CLI --invariants mode is handled separately below; if we're here,
+  // we got a JSON payload on stdin (PostToolUse hook invocation).
+  if (process.argv.includes('--invariants')) return;
 
-    try {
-      const toolName = data.tool_name || '';
-      const toolInput = data.tool_input || {};
+  const toolName = data.tool_name || '';
+  const toolInput = data.tool_input || {};
 
-      // Only run after a git commit bash call
-      if (!isGitCommitBash(toolName, toolInput)) {
-        process.exit(0);
-      }
+  // Only run after a git commit bash call
+  if (!isGitCommitBash(toolName, toolInput)) {
+    process.exit(0);
+  }
 
-      const cwd = data.cwd || process.cwd();
+  const cwd = data.cwd || process.cwd();
 
-      const diff = extractDiffFromLastCommit(cwd);
-      if (!diff) {
-        // No diff available (e.g. initial commit) — pass through
-        process.exit(0);
-      }
+  const diff = extractDiffFromLastCommit(cwd);
+  if (!diff) {
+    // No diff available (e.g. initial commit) — pass through
+    process.exit(0);
+  }
 
-      const specContent = loadActiveSpec(cwd);
-      if (!specContent) {
-        // No active spec found — not a deepflow project or no spec in progress
-        process.exit(0);
-      }
+  const specContent = loadActiveSpec(cwd);
+  if (!specContent) {
+    // No active spec found — not a deepflow project or no spec in progress
+    process.exit(0);
+  }
 
-      const results = checkInvariants(diff, specContent, { mode: 'auto', taskType: 'implementation', projectRoot: cwd });
+  const results = checkInvariants(diff, specContent, { mode: 'auto', taskType: 'implementation', projectRoot: cwd });
 
-      if (results.hard.length > 0) {
-        console.error('[df-invariant-check] Hard invariant failures detected:');
-        const outputLines = formatOutput(results);
-        for (const line of outputLines) {
-          if (results.hard.some((v) => formatViolation(v) === line)) {
-            console.error(`  ${line}`);
-          }
-        }
-        process.exit(1);
-      }
-
-      if (results.advisory.length > 0) {
-        console.warn('[df-invariant-check] Advisory warnings:');
-        for (const v of results.advisory) {
-          console.warn(`  ${formatViolation(v)}`);
-        }
+  if (results.hard.length > 0) {
+    console.error('[df-invariant-check] Hard invariant failures detected:');
+    const outputLines = formatOutput(results);
+    for (const line of outputLines) {
+      if (results.hard.some((v) => formatViolation(v) === line)) {
+        console.error(`  ${line}`);
       }
+    }
+    process.exit(1);
+  }
 
-      process.exit(0);
-    } catch (_err) {
-      // Unexpected error — fail open so we never break non-deepflow projects
-      process.exit(0);
+  if (results.advisory.length > 0) {
+    console.warn('[df-invariant-check] Advisory warnings:');
+    for (const v of results.advisory) {
+      console.warn(`  ${formatViolation(v)}`);
     }
-  });
-} else {
+  }
+});
 
 // ── CLI entry point (REQ-6) ───────────────────────────────────────────────────
-if (require.main === module) {
+if (require.main === module && process.argv.includes('--invariants')) {
   const args = process.argv.slice(2);
 
   // Parse --invariants <spec-path> <diff-file>
   const invariantsIdx = args.indexOf('--invariants');
-  if (invariantsIdx === -1 || args.length < invariantsIdx + 3) {
+  if (args.length < invariantsIdx + 3) {
     console.error('Usage: df-invariant-check.js --invariants <spec-file.md> <diff-file>');
     console.error('');
     console.error('Options:');
@@ -1216,8 +1244,6 @@ if (require.main === module) {
   process.exit(results.hard.length > 0 ? 1 : 0);
 }
 
-} // end else (TTY / CLI mode)
-
 module.exports = {
   checkInvariants,
   checkLspAvailability,
@@ -1231,4 +1257,5 @@ module.exports = {
   checkReqOnlyInTests,
   checkPhantoms,
   checkScopeGaps,
+  checkConfigYamlGuard,
 };

package/hooks/df-invariant-check.test.js

@@ -15,7 +15,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { isBinaryAvailable } = require('./df-invariant-check');
+const { isBinaryAvailable, checkConfigYamlGuard } = require('./df-invariant-check');
 
 const HOOK_SOURCE = fs.readFileSync(
   path.resolve(__dirname, 'df-invariant-check.js'),
@@ -139,3 +139,177 @@ describe('extractDiffFromLastCommit implementation', () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// 4. checkConfigYamlGuard — config.yaml/yml modification detection
+// ---------------------------------------------------------------------------
+
+describe('checkConfigYamlGuard', () => {
+  // Helper: build a minimal parsed-file object matching the shape used by check functions
+  function makeFiles(...paths) {
+    return paths.map((p) => ({ file: p, chunks: [] }));
+  }
+
+  test('detects .deepflow/config.yaml modification as HARD violation', () => {
+    const files = makeFiles('.deepflow/config.yaml');
+    const violations = checkConfigYamlGuard(files, '', 'implementation');
+
+    assert.equal(violations.length, 1);
+    assert.equal(violations[0].tag, 'CONFIG_GUARD');
+    assert.equal(violations[0].file, '.deepflow/config.yaml');
+    assert.equal(violations[0].line, 1);
+    assert.ok(violations[0].description.includes('[CONFIG_GUARD]'));
+  });
+
+  test('detects .deepflow/config.yml variant as HARD violation', () => {
+    const files = makeFiles('.deepflow/config.yml');
+    const violations = checkConfigYamlGuard(files, '', 'implementation');
+
+    assert.equal(violations.length, 1);
+    assert.equal(violations[0].tag, 'CONFIG_GUARD');
+    assert.equal(violations[0].file, '.deepflow/config.yml');
+  });
+
+  test('detects config.yaml inside a worktree sub-path', () => {
+    const worktreePath = '.claude/worktrees/agent-abc123/.deepflow/config.yaml';
+    const files = makeFiles(worktreePath);
+    const violations = checkConfigYamlGuard(files, '', 'implementation');
+
+    assert.equal(violations.length, 1);
+    assert.equal(violations[0].tag, 'CONFIG_GUARD');
+    assert.equal(violations[0].file, worktreePath);
+  });
+
+  test('detects config.yml inside a deeply nested worktree path', () => {
+    const deepPath = 'some/deep/path/.deepflow/config.yml';
+    const files = makeFiles(deepPath);
+    const violations = checkConfigYamlGuard(files, '', 'implementation');
+
+    assert.equal(violations.length, 1);
+    assert.equal(violations[0].tag, 'CONFIG_GUARD');
+  });
+
+  test('returns no violations for non-config files', () => {
+    const files = makeFiles(
+      'src/index.js',
+      'hooks/df-invariant-check.js',
+      'package.json',
+      '.deepflow/decisions.md'
+    );
+    const violations = checkConfigYamlGuard(files, '', 'implementation');
+
+    assert.equal(violations.length, 0);
+  });
+
+  test('ignores files that partially match but are not config.yaml/yml', () => {
+    const files = makeFiles(
+      '.deepflow/config.yaml.bak',
+      '.deepflow/config.yamls',
+      '.deepflow/my-config.yaml',
+      'config.yaml'  // not under .deepflow/
+    );
+    const violations = checkConfigYamlGuard(files, '', 'implementation');
+
+    assert.equal(violations.length, 0);
+  });
+
+  test('returns one violation per matching file when multiple configs present', () => {
+    const files = makeFiles(
+      '.deepflow/config.yaml',
+      '.claude/worktrees/agent-xyz/.deepflow/config.yml'
+    );
+    const violations = checkConfigYamlGuard(files, '', 'implementation');
+
+    assert.equal(violations.length, 2);
+    assert.equal(violations[0].tag, 'CONFIG_GUARD');
+    assert.equal(violations[1].tag, 'CONFIG_GUARD');
+  });
+
+  test('returns empty array when files list is empty', () => {
+    const violations = checkConfigYamlGuard([], '', 'implementation');
+    assert.equal(violations.length, 0);
+  });
+
+  test('works regardless of specContent and taskType arguments', () => {
+    const files = makeFiles('.deepflow/config.yaml');
+
+    // Different specContent and taskType should not affect the result
+    const v1 = checkConfigYamlGuard(files, 'some spec content', 'spike');
+    const v2 = checkConfigYamlGuard(files, '', 'bootstrap');
+
+    assert.equal(v1.length, 1);
+    assert.equal(v2.length, 1);
+  });
+
+  test('violation description mentions the offending file path', () => {
+    const targetPath = '.claude/worktrees/agent-foo/.deepflow/config.yaml';
+    const files = makeFiles(targetPath);
+    const violations = checkConfigYamlGuard(files, '', 'implementation');
+
+    assert.ok(
+      violations[0].description.includes(targetPath),
+      'description should include the exact file path'
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. T3 — stdin hang fix: readStdinIfMain guard and no raw stdin listeners
+// ---------------------------------------------------------------------------
+
+describe('stdin hang fix (T3)', () => {
+  test('source does not contain process.stdin.on calls', () => {
+    // The old code used process.stdin.on('data') directly, which caused hangs
+    // when the file was required by tests. readStdinIfMain replaces this.
+    const lines = HOOK_SOURCE.split('\n');
+    const offendingLines = lines.filter((line) => {
+      if (line.trimStart().startsWith('//') || line.trimStart().startsWith('*')) return false;
+      return /process\.stdin\.on\b/.test(line);
+    });
+    assert.equal(
+      offendingLines.length,
+      0,
+      `Found process.stdin.on in source: ${offendingLines.map((l) => l.trim()).join('; ')}`
+    );
+  });
+
+  test('source calls readStdinIfMain', () => {
+    // readStdinIfMain(module, callback) should be the entry point for stdin reading
+    assert.ok(
+      /readStdinIfMain\s*\(\s*module\b/.test(HOOK_SOURCE),
+      'source should call readStdinIfMain(module, ...) to guard stdin reading'
+    );
+  });
+
+  test('source imports readStdinIfMain from hook-stdin', () => {
+    assert.ok(
+      /require\(['"]\.\/lib\/hook-stdin['"]\)/.test(HOOK_SOURCE),
+      'source should require ./lib/hook-stdin'
+    );
+    assert.ok(
+      /readStdinIfMain/.test(HOOK_SOURCE),
+      'readStdinIfMain should be destructured from the import'
+    );
+  });
+
+  test('--invariants CLI entry point is preserved', () => {
+    // The CLI path must still exist: require.main === module && --invariants
+    assert.ok(
+      /require\.main\s*===\s*module/.test(HOOK_SOURCE),
+      'source should have require.main === module guard for CLI mode'
+    );
+    assert.ok(
+      /--invariants/.test(HOOK_SOURCE),
+      'source should reference --invariants flag'
+    );
+  });
+
+  test('requiring the module does not hang (exits immediately)', () => {
+    // AC-5: node -e "require('./hooks/df-invariant-check.js')" should exit fast.
+    // We already required it at the top of this file without hanging,
+    // so reaching this test at all proves require() does not block.
+    // Additionally, verify the exported API is still accessible.
+    assert.equal(typeof isBinaryAvailable, 'function');
+    assert.equal(typeof checkConfigYamlGuard, 'function');
+  });
+});

package/hooks/df-snapshot-guard.js

@@ -19,6 +19,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { readStdinIfMain } = require('./lib/hook-stdin');
 
 function loadSnapshotPaths(cwd) {
   try {
@@ -55,52 +56,43 @@ function isSnapshotFile(filePath, snapshotPaths, cwd) {
   return false;
 }
 
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const data = JSON.parse(raw);
-    const toolName = data.tool_name || '';
-
-    // Only guard Write and Edit
-    if (toolName !== 'Write' && toolName !== 'Edit') {
-      process.exit(0);
-    }
+readStdinIfMain(module, (data) => {
+  const toolName = data.tool_name || '';
 
-    const filePath = (data.tool_input && data.tool_input.file_path) || '';
-    const cwd = data.cwd || process.cwd();
+  // Only guard Write and Edit
+  if (toolName !== 'Write' && toolName !== 'Edit') {
+    return;
+  }
 
-    if (!filePath) {
-      process.exit(0);
-    }
+  const filePath = (data.tool_input && data.tool_input.file_path) || '';
+  const cwd = data.cwd || process.cwd();
 
-    const snapshotPaths = loadSnapshotPaths(cwd);
+  if (!filePath) {
+    return;
+  }
 
-    // No snapshot file present — not a deepflow project or ratchet not initialized
-    if (snapshotPaths === null) {
-      process.exit(0);
-    }
+  const snapshotPaths = loadSnapshotPaths(cwd);
 
-    // Empty snapshot — nothing to protect
-    if (snapshotPaths.length === 0) {
-      process.exit(0);
-    }
+  // No snapshot file present — not a deepflow project or ratchet not initialized
+  if (snapshotPaths === null) {
+    return;
+  }
 
-    if (!isSnapshotFile(filePath, snapshotPaths, cwd)) {
-      process.exit(0);
-    }
+  // Empty snapshot — nothing to protect
+  if (snapshotPaths.length === 0) {
+    return;
+  }
 
-    // File is in the snapshot — block the write
-    console.error(
-      `[df-snapshot-guard] Blocked ${toolName} to "${filePath}" — this file is listed in ` +
-      `.deepflow/auto-snapshot.txt (ratchet baseline). ` +
-      `Pre-existing test files must not be modified by agents. ` +
-      `If you need to update this file, do so manually outside the autonomous loop.`
-    );
-    process.exit(1);
-  } catch (_e) {
-    // Parse or unexpected error — fail open so we never break non-deepflow projects
-    process.exit(0);
+  if (!isSnapshotFile(filePath, snapshotPaths, cwd)) {
+    return;
   }
+
+  // File is in the snapshot — block the write
+  console.error(
+    `[df-snapshot-guard] Blocked ${toolName} to "${filePath}" — this file is listed in ` +
+    `.deepflow/auto-snapshot.txt (ratchet baseline). ` +
+    `Pre-existing test files must not be modified by agents. ` +
+    `If you need to update this file, do so manually outside the autonomous loop.`
+  );
+  process.exit(1);
 });

package/hooks/df-statusline.js

@@ -8,6 +8,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { readStdinIfMain } = require('./lib/hook-stdin');
 
 // ANSI colors
 const colors = {
@@ -21,18 +22,8 @@ const colors = {
   cyan: '\x1b[36m'
 };
 
-// Read JSON from stdin
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => input += chunk);
-process.stdin.on('end', () => {
-  try {
-    const data = JSON.parse(input);
-    console.log(buildStatusLine(data));
-  } catch (e) {
-    // Fail silently to avoid breaking statusline
-    console.log('');
-  }
+readStdinIfMain(module, (data) => {
+  console.log(buildStatusLine(data));
 });
 
 function buildStatusLine(data) {