deepflow 0.1.110 → 0.1.112

package/hooks/df-invariant-check.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: PostToolUse
+// @hook-owner: deepflow
 /**
  * deepflow invariant checker
  * Checks implementation diffs against spec invariants.
@@ -16,7 +17,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execFileSync } = require('child_process');
+const { execFileSync, spawn } = require('child_process');
 const { extractSection } = require('./df-spec-lint');
 const { readStdinIfMain } = require('./lib/hook-stdin');
 
@@ -134,6 +135,157 @@ function checkLspAvailability(projectRoot, diffFilePaths) {
   return { available: true, binary: detected.binary, installCmd: null, message: null };
 }
 
+/**
+ * REQ-9: Query a language server using JSON-RPC 2.0 over stdio (LSP wire protocol).
+ *
+ * Fast-fails in <1s when the binary is missing (existence check before spawn).
+ * Applies a 10s overall timeout for the full LSP query.
+ *
+ * Protocol sequence:
+ *   1. Send "initialize" request
+ *   2. Send the caller-supplied method request
+ *   3. Parse Content-Length–framed responses from stdout until we get a
+ *      response matching the method request id
+ *
+ * @param {string} binary      - LSP binary name or absolute path (e.g. "typescript-language-server")
+ * @param {string} projectRoot - Absolute path to the project root (passed as rootUri/rootPath)
+ * @param {string} fileUri     - file:// URI of the document being queried
+ * @param {string} method      - LSP method name (e.g. "textDocument/definition")
+ * @param {object} params      - Method parameters object
+ * @returns {Promise<{ ok: true, result: * } | { ok: false, reason: 'lsp_unavailable' }>}
+ */
+async function queryLsp(binary, projectRoot, fileUri, method, params) {
+  // ── Fast-fail: binary existence check (<1s) ────────────────────────────────
+  // Resolve absolute path directly, or locate via which-style PATH scan.
+  const binaryExists = (() => {
+    if (path.isAbsolute(binary)) {
+      return fs.existsSync(binary);
+    }
+    // Check each directory on PATH for the binary
+    const pathDirs = (process.env.PATH || '').split(path.delimiter);
+    for (const dir of pathDirs) {
+      if (!dir) continue;
+      const candidate = path.join(dir, binary);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+      } catch (_) {
+        // Not found in this dir
+      }
+    }
+    return false;
+  })();
+
+  if (!binaryExists) {
+    return { ok: false, reason: 'lsp_unavailable' };
+  }
+
+  return new Promise((resolve) => {
+    const LSP_TIMEOUT_MS = 10_000;
+    let settled = false;
+
+    function fail() {
+      if (settled) return;
+      settled = true;
+      try { proc.kill(); } catch (_) { /* ignore */ }
+      resolve({ ok: false, reason: 'lsp_unavailable' });
+    }
+
+    // ── Spawn the LSP binary ───────────────────────────────────────────────
+    let proc;
+    try {
+      proc = spawn(binary, ['--stdio'], {
+        cwd: projectRoot,
+        stdio: ['pipe', 'pipe', 'ignore'],
+      });
+    } catch (_) {
+      return resolve({ ok: false, reason: 'lsp_unavailable' });
+    }
+
+    proc.on('error', fail);
+    proc.on('close', () => { if (!settled) fail(); });
+
+    // ── Overall 10s timeout ────────────────────────────────────────────────
+    const timer = setTimeout(fail, LSP_TIMEOUT_MS);
+
+    // ── JSON-RPC helpers ───────────────────────────────────────────────────
+    let msgId = 1;
+
+    function sendMessage(msg) {
+      const json = JSON.stringify(msg);
+      const header = `Content-Length: ${Buffer.byteLength(json, 'utf8')}\r\n\r\n`;
+      proc.stdin.write(header + json, 'utf8');
+    }
+
+    const INIT_ID = msgId++;
+    const METHOD_ID = msgId++;
+
+    // ── stdout parser: Content-Length framing ─────────────────────────────
+    let buffer = '';
+    let expectedLength = -1;
+
+    proc.stdout.on('data', (chunk) => {
+      if (settled) return;
+      buffer += chunk.toString('utf8');
+
+      while (true) { // eslint-disable-line no-constant-condition
+        if (expectedLength === -1) {
+          // Look for the header/body separator
+          const sepIdx = buffer.indexOf('\r\n\r\n');
+          if (sepIdx === -1) break;
+
+          const header = buffer.slice(0, sepIdx);
+          const lenMatch = header.match(/Content-Length:\s*(\d+)/i);
+          if (!lenMatch) { fail(); return; }
+
+          expectedLength = parseInt(lenMatch[1], 10);
+          buffer = buffer.slice(sepIdx + 4); // skip past "\r\n\r\n"
+        }
+
+        if (buffer.length < expectedLength) break;
+
+        const body = buffer.slice(0, expectedLength);
+        buffer = buffer.slice(expectedLength);
+        expectedLength = -1;
+
+        let msg;
+        try { msg = JSON.parse(body); } catch (_) { fail(); return; }
+
+        if (msg.id === INIT_ID) {
+          // Initialize response received — now send the actual method request
+          sendMessage({ jsonrpc: '2.0', id: METHOD_ID, method, params });
+        } else if (msg.id === METHOD_ID) {
+          // Got our response
+          if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            try { proc.kill(); } catch (_) { /* ignore */ }
+            if (msg.error) {
+              resolve({ ok: false, reason: 'lsp_unavailable' });
+            } else {
+              resolve({ ok: true, result: msg.result });
+            }
+          }
+        }
+        // Ignore notifications (id-less messages) and other responses
+      }
+    });
+
+    // ── Send initialize request ────────────────────────────────────────────
+    sendMessage({
+      jsonrpc: '2.0',
+      id: INIT_ID,
+      method: 'initialize',
+      params: {
+        processId: process.pid,
+        rootUri: `file://${projectRoot}`,
+        rootPath: projectRoot,
+        capabilities: {},
+      },
+    });
+  });
+}
+
 // ── Valid violation tags (REQ-7) ──────────────────────────────────────────────
 const TAGS = {
   MOCK: 'MOCK',               // Production code contains mock/stub placeholders
@@ -1249,6 +1401,7 @@ module.exports = {
   checkLspAvailability,
   detectLanguageServer,
   isBinaryAvailable,
+  queryLsp,
   formatOutput,
   formatViolation,
   parseDiff,

package/hooks/df-quota-logger.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: SessionStart, SessionEnd
+// @hook-owner: dashboard
 /**
  * deepflow quota logger
  * Logs Anthropic API quota/usage data to ~/.claude/quota-history.jsonl

package/hooks/df-snapshot-guard.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: PostToolUse
+// @hook-owner: deepflow
 /**
  * deepflow snapshot guard
  * PostToolUse hook: blocks Write/Edit to files listed in .deepflow/auto-snapshot.txt.

package/hooks/df-spec-lint.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// @hook-event: PostToolUse
+// @hook-owner: deepflow
 /**
  * deepflow spec linter
  * Validates spec files against hard invariants and advisory checks.
@@ -222,6 +224,10 @@ function validateSpec(content, { mode = 'interactive', specsDir = null, filename
         hard.push(
           `Acceptance Criteria line missing "- [ ]" checkbox: "${line.trim()}"`
         );
+      } else if (!/\*\*AC-\d+\*\*/.test(line)) {
+        hard.push(
+          `Acceptance Criteria checkbox missing **AC-N** identifier: "${line.trim()}"`
+        );
       }
     }
   } else if (!hasInlineAC) {

package/hooks/df-spec-lint.test.js

@@ -43,7 +43,7 @@ function fullSpec() {
     'Not doing X',
     '',
     '## Acceptance Criteria',
-    '- [ ] REQ-1 works',
+    '- [ ] **AC-1** REQ-1 works',
     '',
     '## Technical Notes',
     'Use module Y',
@@ -150,6 +150,62 @@ describe('validateSpec with frontmatter', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// validateSpec — Acceptance Criteria AC-N format enforcement
+// ---------------------------------------------------------------------------
+
+describe('validateSpec AC-N format enforcement', () => {
+  test('bare "- [ ]" line without **AC-N** identifier causes hard failure', () => {
+    const specWithBareAC = [
+      '## Objective',
+      'Build the thing',
+      '',
+      '## Requirements',
+      '- REQ-1: Do something',
+      '',
+      '## Constraints',
+      'Must be fast',
+      '',
+      '## Out of Scope',
+      'Not doing X',
+      '',
+      '## Acceptance Criteria',
+      '- [ ] REQ-1 works',
+      '',
+      '## Technical Notes',
+      'Use module Y',
+    ].join('\n');
+    const result = validateSpec(specWithBareAC);
+    const acErrors = result.hard.filter((m) => m.includes('AC-N'));
+    assert.ok(acErrors.length > 0, 'should hard-fail when AC checkbox lacks **AC-N** identifier');
+  });
+
+  test('AC line with **AC-N** identifier passes without hard error', () => {
+    const result = validateSpec(fullSpec());
+    const acErrors = result.hard.filter((m) => m.includes('AC-N'));
+    assert.equal(acErrors.length, 0, 'should not hard-fail when AC checkbox has **AC-N** identifier');
+  });
+
+  test('bare "- [ ]" line hard error message references the offending line', () => {
+    const specWithBareAC = [
+      '## Objective',
+      'Build the thing',
+      '',
+      '## Requirements',
+      '- REQ-1: Do something',
+      '',
+      '## Acceptance Criteria',
+      '- [ ] bare item without identifier',
+    ].join('\n');
+    const result = validateSpec(specWithBareAC);
+    const acErrors = result.hard.filter((m) => m.includes('AC-N'));
+    assert.ok(
+      acErrors.some((m) => m.includes('bare item without identifier')),
+      'hard error message should include the offending line text'
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // extractSection — frontmatter handling
 // ---------------------------------------------------------------------------

package/hooks/df-statusline.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: statusLine
+// @hook-owner: deepflow
 /**
  * deepflow statusline for Claude Code
  * Displays: update | model | project | context usage

package/hooks/df-subagent-registry.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: SubagentStop
+// @hook-owner: dashboard
 'use strict';
 const fs = require('fs');
 const path = require('path');

package/hooks/df-tool-usage-spike.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// @hook-event: PostToolUse
+// @hook-owner: dashboard
 /**
  * Spike hook: capture raw PostToolUse stdin payload
  * Writes the raw JSON to /tmp/df-posttooluse-payload.json for inspection.

package/hooks/df-tool-usage.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: PostToolUse
+// @hook-owner: dashboard
 /**
  * deepflow tool usage logger
  * Logs every PostToolUse event to ~/.claude/tool-usage.jsonl for token instrumentation.

package/hooks/df-worktree-guard.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 // @hook-event: PostToolUse
+// @hook-owner: deepflow
 /**
  * deepflow worktree guard
  * PostToolUse hook: blocks Write/Edit to main-branch files when a df/* worktree exists.
@@ -19,6 +20,8 @@
 'use strict';
 
 const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
 const { readStdinIfMain } = require('./lib/hook-stdin');
 
 // Paths that are always allowed regardless of worktree state
@@ -57,6 +60,111 @@ function dfWorktreeExists(cwd) {
   }
 }
 
+/**
+ * List all worktrees as { path, branch } objects parsed from `git worktree list --porcelain`.
+ * Returns [] on git failure.
+ */
+function listWorktrees(cwd) {
+  let out;
+  try {
+    out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+      encoding: 'utf8',
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (_) {
+    return [];
+  }
+
+  const worktrees = [];
+  let current = {};
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (current.path) worktrees.push(current);
+      current = { path: line.slice('worktree '.length).trim() };
+    } else if (line.startsWith('branch ')) {
+      // e.g. "branch refs/heads/df/foo"
+      const ref = line.slice('branch '.length).trim();
+      current.branch = ref.replace(/^refs\/heads\//, '');
+    } else if (line === '') {
+      if (current.path) {
+        worktrees.push(current);
+        current = {};
+      }
+    }
+  }
+  if (current.path) worktrees.push(current);
+  return worktrees;
+}
+
+/**
+ * Parse PLAN.md content and return the in-progress task's Files: list.
+ * "In-progress" = first unchecked `[ ]` task, or the task whose id matches branchName.
+ * Returns an array of file path strings (possibly empty).
+ */
+function extractInProgressFiles(planContent, branchName) {
+  if (!planContent) return [];
+  const lines = planContent.split('\n');
+
+  // Collect task blocks: start indices at lines matching `- [ ]` or `- [x]`
+  const taskStarts = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*-\s*\[[ xX]\]\s*\*?\*?T\d+/.test(lines[i]) || /^\s*-\s*\[[ xX]\]/.test(lines[i])) {
+      taskStarts.push(i);
+    }
+  }
+
+  function getBlock(startIdx) {
+    const end = taskStarts.find(i => i > startIdx) ?? lines.length;
+    return lines.slice(startIdx, end);
+  }
+
+  function getFilesFromBlock(block) {
+    for (const line of block) {
+      const m = line.match(/^\s*-?\s*Files:\s*(.+)$/i);
+      if (m) {
+        return m[1]
+          .split(',')
+          .map(s => s.trim().replace(/^[`"']|[`"']$/g, ''))
+          .filter(s => s.length > 0 && !/^\{.*\}$/.test(s) && !/^\[.*\]$/.test(s));
+      }
+    }
+    return [];
+  }
+
+  // Prefer: first unchecked task
+  for (const idx of taskStarts) {
+    if (/^\s*-\s*\[ \]/.test(lines[idx])) {
+      return getFilesFromBlock(getBlock(idx));
+    }
+  }
+
+  // Fallback: task matching branch name (e.g., df/feature-x → match "feature-x" in header)
+  if (branchName) {
+    const slug = branchName.replace(/^df\//, '');
+    for (const idx of taskStarts) {
+      if (lines[idx].toLowerCase().includes(slug.toLowerCase())) {
+        return getFilesFromBlock(getBlock(idx));
+      }
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Normalize a file path for intersection comparison.
+ * Returns path relative to repo root when possible; otherwise basename.
+ */
+function normalizePath(p, repoRoot) {
+  if (!p) return '';
+  const abs = path.isAbsolute(p) ? p : path.resolve(repoRoot || '', p);
+  if (repoRoot && abs.startsWith(repoRoot + path.sep)) {
+    return abs.slice(repoRoot.length + 1);
+  }
+  return p;
+}
+
 readStdinIfMain(module, (data) => {
   const toolName = data.tool_name || '';
 
@@ -75,6 +183,55 @@ readStdinIfMain(module, (data) => {
 
   const branch = currentBranch(cwd);
 
+  // REQ-2: Cross-worktree file intersection check.
+  // For every df/* worktree OTHER than the current one, read its PLAN.md,
+  // find the in-progress task, and BLOCK if filePath intersects its Files: list.
+  try {
+    const worktrees = listWorktrees(cwd);
+    const currentWorktreePath = worktrees.find(w => w.branch === branch)?.path || cwd;
+
+    for (const wt of worktrees) {
+      if (!wt.branch || !wt.branch.startsWith('df/')) continue;
+      if (wt.path === currentWorktreePath) continue;
+
+      const planPath = path.join(wt.path, 'PLAN.md');
+      let planContent;
+      try {
+        planContent = fs.readFileSync(planPath, 'utf8');
+      } catch (_) {
+        continue; // no PLAN.md — skip gracefully
+      }
+
+      const claimed = extractInProgressFiles(planContent, wt.branch);
+      if (claimed.length === 0) continue;
+
+      // Repo root of the OTHER worktree: normalize writing file against current cwd
+      // but compare against claimed paths (which are repo-relative in PLAN.md).
+      const writeRel = normalizePath(filePath, currentWorktreePath);
+      const writeBase = path.basename(filePath);
+
+      for (const claimedFile of claimed) {
+        const claimedRel = claimedFile.replace(/^\.\//, '');
+        const claimedBase = path.basename(claimedRel);
+        if (
+          writeRel === claimedRel ||
+          filePath === claimedRel ||
+          filePath.endsWith('/' + claimedRel) ||
+          writeBase === claimedBase && (writeRel.endsWith(claimedRel) || claimedRel.endsWith(writeRel))
+        ) {
+          console.error(
+            `[df-worktree-guard] Blocked ${toolName} to "${filePath}" — ` +
+            `file is claimed by in-progress task in worktree ${wt.branch} (${wt.path}). ` +
+            `Coordinate or wait for that task to complete.`
+          );
+          process.exit(1);
+        }
+      }
+    }
+  } catch (_) {
+    // Never break tool execution on unexpected errors
+  }
+
   // Only guard when on main/master
   if (branch !== 'main' && branch !== 'master') {
     return;

package/hooks/lib/installer-utils.js

@@ -0,0 +1,114 @@
+'use strict';
+/**
+ * Shared installer utilities for deepflow hook management.
+ * Used by bin/install.js and any owner-specific installer logic.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Valid hook events (settings.hooks keys + special "statusLine")
+const VALID_HOOK_EVENTS = new Set([
+  'SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse', 'SubagentStop', 'statusLine'
+]);
+
+/**
+ * Atomically write data to targetPath using a write-to-temp + rename pattern.
+ * If the write fails, the original file is left untouched and the temp file is
+ * cleaned up. Temp file is created in the same directory as the target so the
+ * rename is within the same filesystem (atomic on POSIX).
+ */
+function atomicWriteFileSync(targetPath, data) {
+  const tmpPath = targetPath + '.tmp';
+  try {
+    fs.writeFileSync(tmpPath, data);
+    fs.renameSync(tmpPath, targetPath);
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    throw err;
+  }
+}
+
+/**
+ * Scan hook source files for @hook-event tags. Returns:
+ *   { eventMap: Map<event, [filename, ...]>, untagged: [filename, ...] }
+ *
+ * @param {string} hooksSourceDir - Directory to scan for hook files
+ * @param {string} [filterOwner]  - When set, only include files whose @hook-owner tag
+ *                                  matches this value (case-sensitive). Files with no
+ *                                  @hook-owner tag are always excluded when filterOwner
+ *                                  is provided.
+ */
+function scanHookEvents(hooksSourceDir, filterOwner) {
+  const eventMap = new Map();  // event → [filenames]
+  const untagged = [];
+
+  if (!fs.existsSync(hooksSourceDir)) return { eventMap, untagged };
+
+  for (const file of fs.readdirSync(hooksSourceDir)) {
+    if (!file.endsWith('.js') || file.endsWith('.test.js')) continue;
+
+    const content = fs.readFileSync(path.join(hooksSourceDir, file), 'utf8');
+    const firstLines = content.split('\n').slice(0, 10).join('\n');
+
+    // Apply owner filter if requested
+    if (filterOwner !== undefined) {
+      const ownerMatch = firstLines.match(/\/\/\s*@hook-owner:\s*(.+)/);
+      if (!ownerMatch || ownerMatch[1].trim() !== filterOwner) continue;
+    }
+
+    const match = firstLines.match(/\/\/\s*@hook-event:\s*(.+)/);
+
+    if (!match) {
+      untagged.push(file);
+      continue;
+    }
+
+    const events = match[1].split(',').map(e => e.trim()).filter(Boolean);
+    let hasValidEvent = false;
+
+    for (const event of events) {
+      if (!VALID_HOOK_EVENTS.has(event)) {
+        // Surface warning via stderr so callers can decide how to display it
+        process.stderr.write(`[installer-utils] Warning: unknown event "${event}" in ${file} — skipped\n`);
+        continue;
+      }
+      hasValidEvent = true;
+      if (!eventMap.has(event)) eventMap.set(event, []);
+      eventMap.get(event).push(file);
+    }
+
+    if (!hasValidEvent) {
+      untagged.push(file);
+    }
+  }
+
+  return { eventMap, untagged };
+}
+
+/**
+ * Remove all deepflow hook entries (commands containing /hooks/df-) from settings.
+ * Preserves non-deepflow hooks.
+ */
+function removeDeepflowHooks(settings) {
+  const isDeepflow = (hook) => {
+    const cmd = hook.hooks?.[0]?.command || '';
+    return cmd.includes('/hooks/df-');
+  };
+
+  // Clean settings.hooks.*
+  if (settings.hooks) {
+    for (const event of Object.keys(settings.hooks)) {
+      settings.hooks[event] = settings.hooks[event].filter(h => !isDeepflow(h));
+      if (settings.hooks[event].length === 0) delete settings.hooks[event];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  }
+
+  // Clean settings.statusLine if it's a deepflow hook
+  if (settings.statusLine?.command && settings.statusLine.command.includes('/hooks/df-')) {
+    delete settings.statusLine;
+  }
+}
+
+module.exports = { atomicWriteFileSync, scanHookEvents, removeDeepflowHooks, VALID_HOOK_EVENTS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.110",
+  "version": "0.1.112",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",

package/src/commands/df/debate.md

@@ -1,7 +1,7 @@
 ---
 name: df:debate
 description: Generate multi-perspective analysis of a problem before formalizing into a spec
-allowed-tools: [Read, Grep, Glob, Agent]
+allowed-tools: [Agent, AskUserQuestion]
 ---
 
 # /df:debate — Multi-Perspective Analysis
@@ -12,7 +12,7 @@ Coordinate reasoner agents to debate a problem from multiple perspectives, then
 
 **NEVER:** use TaskOutput, `run_in_background`, Explore agents, EnterPlanMode, ExitPlanMode
 
-**ONLY:** Gather codebase context (Glob/Grep/Read), spawn reasoner agents (non-background), write debate file, respond conversationally
+**ONLY:** Spawn context-fork agent for codebase gathering, spawn reasoner agents (non-background), write debate file, respond conversationally
 
 ## Agents
 
@@ -30,7 +30,23 @@ Coordinate reasoner agents to debate a problem from multiple perspectives, then
 Summarize conversation context in ~200 words: core problem, requirements, constraints, user priorities. Passed to each perspective agent.
 
 ### 2. GATHER CODEBASE CONTEXT
-Prefer LSP documentSymbol to understand file structure, then Read with offset/limit on relevant ranges only (never read full files). Glob/Grep to locate files (up to 5-6, focus on core logic). Produce ~300 word codebase summary: what exists, key interfaces, current limitations, dependencies. Passed to every agent.
+Spawn a context-fork agent (subagent_type="default", model="sonnet") with the following prompt:
+
+```
+## Task: Codebase Context Gathering
+
+Problem being analyzed: {summary}
+
+Instructions:
+- Use LSP documentSymbol to understand file structure where available
+- Use Read with offset/limit on relevant ranges only (never read full files)
+- Use Glob/Grep to locate relevant files (up to 5-6, focus on core logic)
+- Produce a ~300 word summary covering: what exists, key interfaces, current limitations, dependencies
+
+Return ONLY the codebase summary text (~300 words). No preamble, no explanation.
+```
+
+Store the agent's response as {codebase_summary}. Passed to every perspective agent.
 
 ### 3. SPAWN PERSPECTIVES
 
@@ -82,6 +98,6 @@ Present key tensions and open decisions, then: `Next: Run /df:spec {name} to for
 ## Rules
 
 - ALL 4 perspective agents MUST be spawned in ONE message (parallel, non-background)
-- Orchestrator gathers codebase context (step 2), passes to agents via prompt — agents never read files
+- Orchestrator delegates codebase gathering (step 2) to a context-fork agent — orchestrator never reads files directly
 - File name MUST be `.debate-{name}.md` (dot prefix = auxiliary file, lives in `specs/`)
 - Word limits: each perspective <400 words, synthesis <500 words

package/src/commands/df/discover.md

@@ -1,7 +1,7 @@
 ---
 name: df:discover
 description: Explore a problem space deeply through structured questioning to surface requirements and constraints
-allowed-tools: [AskUserQuestion, Read, Agent]
+allowed-tools: [AskUserQuestion, Agent]
 ---
 
 # /df:discover — Deep Problem Exploration