deepflow 0.1.102 → 0.1.104

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

@@ -0,0 +1,200 @@
+/**
+ * Tests for hooks/df-tool-usage.js — T3: active_command field in tool-usage records
+ *
+ * Validates that the tool usage hook reads .deepflow/active-command.json marker
+ * and includes the active_command field in tool-usage.jsonl records.
+ *
+ * Uses Node.js built-in node:test to avoid adding dependencies.
+ */
+
+'use strict';
+
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('os');
+const { execFileSync } = require('node:child_process');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const HOOK_PATH = path.resolve(__dirname, 'df-tool-usage.js');
+
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'df-tool-usage-test-'));
+}
+
+function rmrf(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Run the tool usage hook as a child process with JSON piped to stdin.
+ * Overrides HOME so tool-usage.jsonl goes to a temp location.
+ * Returns { stdout, stderr, code }.
+ */
+function runHook(input, { cwd, env: extraEnv } = {}) {
+  const json = typeof input === 'string' ? input : JSON.stringify(input);
+  const env = { ...process.env, ...extraEnv };
+  // Override HOME so the log file goes to our temp dir
+  env.HOME = cwd || os.tmpdir();
+  try {
+    const stdout = execFileSync(
+      process.execPath,
+      [HOOK_PATH],
+      {
+        input: json,
+        cwd: cwd || os.tmpdir(),
+        encoding: 'utf8',
+        timeout: 5000,
+        env,
+      }
+    );
+    return { stdout, stderr: '', code: 0 };
+  } catch (err) {
+    return {
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      code: err.status ?? 1,
+    };
+  }
+}
+
+/**
+ * Build a minimal PostToolUse event payload.
+ */
+function makeToolInput(cwd) {
+  return {
+    session_id: 'tool-test-session',
+    tool_name: 'Read',
+    tool_input: { file_path: '/tmp/test.js' },
+    tool_response: { content: 'file contents here' },
+    cwd: cwd,
+  };
+}
+
+/**
+ * Read the last record from tool-usage.jsonl.
+ */
+function readLastToolRecord(homeDir) {
+  const logPath = path.join(homeDir, '.claude', 'tool-usage.jsonl');
+  if (!fs.existsSync(logPath)) return null;
+  const lines = fs.readFileSync(logPath, 'utf8').trim().split('\n');
+  return JSON.parse(lines[lines.length - 1]);
+}
+
+// ---------------------------------------------------------------------------
+// T3: active_command field in tool-usage records
+// ---------------------------------------------------------------------------
+
+describe('T3 — tool-usage active_command field', () => {
+  let tmpDir;
+  let deepflowDir;
+
+  beforeEach(() => {
+    tmpDir = makeTmpDir();
+    deepflowDir = path.join(tmpDir, '.deepflow');
+    fs.mkdirSync(deepflowDir, { recursive: true });
+    // Create .claude dir for tool-usage.jsonl output
+    fs.mkdirSync(path.join(tmpDir, '.claude'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmrf(tmpDir);
+  });
+
+  test('active_command is set when active-command.json marker exists', () => {
+    fs.writeFileSync(
+      path.join(deepflowDir, 'active-command.json'),
+      JSON.stringify({ command: 'df:plan', started_at: new Date().toISOString() })
+    );
+
+    const input = makeToolInput(tmpDir);
+    const { code } = runHook(input, { cwd: tmpDir });
+    assert.equal(code, 0, 'Hook should exit successfully');
+
+    const record = readLastToolRecord(tmpDir);
+    assert.ok(record, 'Tool usage record should exist');
+    assert.equal(record.active_command, 'df:plan', 'active_command should match marker');
+  });
+
+  test('active_command is null when no marker file exists', () => {
+    const input = makeToolInput(tmpDir);
+    const { code } = runHook(input, { cwd: tmpDir });
+    assert.equal(code, 0);
+
+    const record = readLastToolRecord(tmpDir);
+    assert.ok(record, 'Tool usage record should exist');
+    assert.equal(record.active_command, null, 'active_command should be null without marker');
+  });
+
+  test('active_command is null when marker file contains corrupt JSON', () => {
+    fs.writeFileSync(
+      path.join(deepflowDir, 'active-command.json'),
+      '{{corrupt json'
+    );
+
+    const input = makeToolInput(tmpDir);
+    const { code } = runHook(input, { cwd: tmpDir });
+    assert.equal(code, 0, 'Hook should not crash on corrupt marker');
+
+    const record = readLastToolRecord(tmpDir);
+    assert.ok(record);
+    assert.equal(record.active_command, null, 'active_command should be null for corrupt marker');
+  });
+
+  test('active_command is null when marker has no command field', () => {
+    fs.writeFileSync(
+      path.join(deepflowDir, 'active-command.json'),
+      JSON.stringify({ other_field: 'value' })
+    );
+
+    const input = makeToolInput(tmpDir);
+    const { code } = runHook(input, { cwd: tmpDir });
+    assert.equal(code, 0);
+
+    const record = readLastToolRecord(tmpDir);
+    assert.ok(record);
+    assert.equal(record.active_command, null, 'active_command should be null when command field missing');
+  });
+
+  test('active_command field always present in tool-usage record schema', () => {
+    const input = makeToolInput(tmpDir);
+    runHook(input, { cwd: tmpDir });
+
+    const record = readLastToolRecord(tmpDir);
+    assert.ok(record);
+    assert.ok('active_command' in record, 'active_command key must always be present');
+    // Verify other expected fields
+    assert.ok('timestamp' in record);
+    assert.ok('session_id' in record);
+    assert.ok('tool_name' in record);
+    assert.ok('phase' in record);
+  });
+
+  test('active_command reads df:execute correctly', () => {
+    fs.writeFileSync(
+      path.join(deepflowDir, 'active-command.json'),
+      JSON.stringify({ command: 'df:execute' })
+    );
+
+    const input = makeToolInput(tmpDir);
+    runHook(input, { cwd: tmpDir });
+
+    const record = readLastToolRecord(tmpDir);
+    assert.ok(record);
+    assert.equal(record.active_command, 'df:execute');
+  });
+
+  test('hook exits 0 even when marker is unreadable (permissions)', () => {
+    // Write marker then make the deepflow dir inaccessible won't work on all OS.
+    // Instead, set cwd to a non-existent path to trigger the fallback.
+    const input = makeToolInput('/nonexistent/path/that/does/not/exist');
+    const { code } = runHook(input, { cwd: tmpDir });
+    assert.equal(code, 0, 'Hook should always exit 0');
+  });
+});

package/hooks/df-worktree-guard.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @hook-event: PostToolUse
 /**
  * deepflow worktree guard
  * PostToolUse hook: blocks Write/Edit to main-branch files when a df/* worktree exists.

package/package.json

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

package/src/commands/df/debate.md

@@ -30,7 +30,7 @@ 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
-Glob/Grep/Read relevant 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.
+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.
 
 ### 3. SPAWN PERSPECTIVES
 

package/src/commands/df/eval.md

@@ -0,0 +1,117 @@
+---
+name: df:eval
+description: Evaluate a skill or command against a benchmark suite, or scaffold a new benchmark directory
+allowed-tools: [Read, Bash, Write, Glob, Grep]
+---
+
+# /df:eval — Skill Evaluation
+
+Run a benchmark suite against a skill/command, or scaffold a new benchmark directory.
+
+## Usage
+
+```
+/df:eval --scaffold benchmarks/<name>/                        # Create benchmark directory structure
+/df:eval benchmarks/<name>/                                   # Run benchmark suite (reads hypotheses.md)
+/df:eval benchmarks/<name>/ --hypothesis "reduce token use"   # Override hypothesis explicitly
+```
+
+## Subcommands
+
+### `--scaffold <target-dir>`
+
+Creates a benchmark directory from the fixture template at `templates/eval-fixture-template/`.
+
+**What gets created:**
+
+```
+<target-dir>/
+  fixture/          # Minimal repo fixture (hooks, specs, src, package.json)
+  tests/            # Behavior and guard test files
+  spec.md           # Benchmark objective and acceptance criteria
+  config.yaml       # Benchmark configuration (skill under test, thresholds)
+  hypotheses.md     # Hypotheses to validate
+```
+
+**Steps:**
+
+1. Validate `<target-dir>` argument is provided; abort with usage hint if missing.
+2. Check `<target-dir>` does not already exist; abort with error if it does.
+3. Copy `templates/eval-fixture-template/` recursively to `<target-dir>`.
+4. Confirm with summary:
+
+```
+Created benchmark scaffold at <target-dir>/
+  fixture/    - minimal repo fixture
+  tests/      - behavior.test.js, guard.test.js
+  spec.md     - edit to define benchmark objective
+  config.yaml - edit to set skill under test and thresholds
+  hypotheses.md - edit to define hypotheses
+
+Next: edit spec.md and config.yaml, then run /df:eval <target-dir>/
+```
+
+**Implementation:**
+
+```bash
+# Parse --scaffold flag and target dir from $ARGUMENTS
+# e.g. /df:eval --scaffold benchmarks/my-bench/
+ARGS="$ARGUMENTS"
+TARGET=$(echo "$ARGS" | sed 's/--scaffold[[:space:]]*//')
+TEMPLATE="templates/eval-fixture-template"
+
+if [ -z "$TARGET" ]; then
+  echo "Error: target directory required. Usage: /df:eval --scaffold benchmarks/<name>/"
+  exit 1
+fi
+
+if [ -d "$TARGET" ]; then
+  echo "Error: $TARGET already exists."
+  exit 1
+fi
+
+cp -r "$TEMPLATE/" "$TARGET"
+echo "Created benchmark scaffold at $TARGET"
+```
+
+### `--hypothesis <text>`
+
+Overrides the mutation hypothesis for the eval session. Without this flag the
+loop reads `{benchDir}/hypotheses.md` and uses the first list item it finds.
+
+**Hypothesis resolution order:**
+
+1. `--hypothesis "<text>"` flag value — used as-is.
+2. `{benchDir}/hypotheses.md` first list item (ordered or unordered markdown list).
+3. Error if neither source is available.
+
+**Module:** `src/eval/hypothesis.js` — `loadHypothesis({ flag, benchDir })`
+
+---
+
+## Main Eval Loop (T9 — implemented)
+
+Running `/df:eval benchmarks/<name>/` without `--scaffold` runs the Karpathy loop:
+
+1. Load `benchmarks/<name>/config.yaml` — skill under test, thresholds, iteration count
+2. Resolve hypothesis via `--hypothesis` flag or `benchmarks/<name>/hypotheses.md` (first list item)
+3. Create a worktree-isolated branch for the session (`eval/<skill>/<timestamp>`)
+4. **Loop** (until Ctrl+C or `--loop N`):
+   a. Mutate skill file via agent prompt built from current content + history
+   b. Commit experiment (`status:pending`)
+   c. Run guard check (build + test commands from config)
+      - Guard fail → `git revert`, log `status:guard_fail`, next iteration
+   d. Collect metrics from `.deepflow/` JSONL files
+   e. Compare target metric against baseline
+      - Improved → log `status:kept`, update baseline
+      - Regression → `git revert`, log `status:reverted`
+   f. Record secondary metrics in commit message (never influence keep/revert)
+
+**Implementation:** `src/eval/loop.js` (`runEvalLoop`), `src/eval/hypothesis.js` (`loadHypothesis`)
+
+## Rules
+
+- `--scaffold` never overwrites an existing directory
+- Template is always copied from `templates/eval-fixture-template/`
+- Main eval loop is non-deterministic by design — it samples skill behavior across N runs
+- No LLM judges another LLM — only objective metrics (file diffs, test results, token counts) are used

package/src/commands/df/execute.md

@@ -376,7 +376,7 @@ Success criteria: {ACs from spec relevant to this task}
 {TASK_DETAIL if available, else inline block:}
 Impact: Callers: {file} ({why}) | Duplicates: [active→consolidate] [dead→DELETE] | Data flow: {consumers}
 Prior tasks: {dep_id}: {summary}
-Steps: 1. chub search/get for APIs 2. LSP findReferences, add unlisted callers 3. Read all Impact files 4. Implement 5. Commit
+Steps: 1. chub search/get for APIs 2. LSP findReferences, add unlisted callers 3. LSP documentSymbol on Impact files → Read with offset/limit on relevant ranges only (never read full files) 4. Implement 5. Commit
 --- END ---
 Duplicates: [active]→consolidate [dead]→DELETE. ONLY job: code+commit. No merge/rename/checkout.
 Last line of your response MUST be: TASK_STATUS:pass (if successful) or TASK_STATUS:fail (if failed) or TASK_STATUS:revert (if reverted)

package/src/commands/df/fix.md

@@ -0,0 +1,104 @@
+---
+name: df:fix
+description: Create a new spec derived from a completed spec to address issues, regressions, or unmet acceptance criteria
+allowed-tools: [Read, Write, AskUserQuestion]
+---
+
+# /df:fix {done-spec-name} — Create Fix Spec from Completed Spec
+
+## Purpose
+
+Creates a new spec file pre-populated with lineage from a `done-*` spec. Use when a completed feature has regressions, unmet ACs, or needs targeted fixes without reopening the original spec.
+
+## Behavior
+
+### 1. VALIDATE ARGUMENT
+
+The command receives one argument: `{done-spec-name}` (e.g., `done-auth`).
+
+If no argument is provided, ask:
+```
+Which completed spec needs a fix? (e.g., done-auth)
+```
+
+### 2. READ PARENT SPEC
+
+Read `specs/{done-spec-name}.md`.
+
+If the file does not exist, show:
+```
+Error: specs/{done-spec-name}.md not found.
+Make sure the spec exists and uses the done-* prefix.
+```
+Then stop.
+
+Extract from the parent spec:
+- **Objective** (from `## Objective` section)
+- **Acceptance Criteria** (all items from `## Acceptance Criteria` section)
+
+### 3. ASK WHAT NEEDS FIXING
+
+Use `AskUserQuestion` to ask (max 4 questions per call):
+
+1. What is broken or not working as expected?
+2. Which acceptance criteria from the original spec are failing or incomplete? (show the extracted ACs as reference)
+3. Any new constraints or scope boundaries for this fix?
+
+### 4. CREATE FIX SPEC
+
+Determine a short name for the fix spec. Default: `fix-{done-spec-name-without-done-prefix}` (e.g., `fix-auth`).
+
+Create `specs/{fix-name}.md`:
+
+```markdown
+---
+derives-from: {done-spec-name}
+---
+
+# Fix: {Title derived from done-spec-name}
+
+## Objective
+
+Fix issues in `{done-spec-name}`: {one sentence summarizing what needs to be fixed, from user input}
+
+## Requirements
+
+- **REQ-1**: [Requirement based on user-described issue]
+
+## Constraints
+
+- Scope limited to fixing regressions/gaps from `{done-spec-name}`
+- Must not break passing ACs from the parent spec
+
+## Acceptance Criteria
+
+<!-- Failing ACs carried over from parent spec -->
+{carried-over failing ACs as unchecked items}
+
+<!-- New ACs for this fix -->
+- [ ] {new criterion from user input, if any}
+
+## Technical Notes
+
+Parent spec: `specs/{done-spec-name}.md`
+Parent objective: {parent objective text}
+```
+
+### 5. CONFIRM
+
+```
+Created specs/{fix-name}.md
+
+derives-from: {done-spec-name}
+Carried over {N} ACs from parent spec
+
+Next: Run /df:plan {fix-name} to generate fix tasks
+```
+
+## Rules
+
+- Always set `derives-from` in the frontmatter — this is the lineage anchor
+- Carry over only ACs that are failing or unverified; do not duplicate passing ones
+- Keep fix specs narrowly scoped — no scope creep beyond the stated issue
+- Do not reopen or modify the parent `done-*` spec
+- Fix spec name must start with `fix-` by default; user may override

package/src/eval/git-memory.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const { execSync } = require('child_process');
+
+/**
+ * Formats the commit message for an experiment commit.
+ * Format: experiment({skillName}): {hypothesis} | {target}={value} delta={delta}% {status} | {secondaries}
+ */
+function formatCommitMessage({ skillName, hypothesis, target, value, delta, status, secondaries }) {
+  const secondariesStr = secondaries != null ? String(secondaries) : '';
+  return `experiment(${skillName}): ${hypothesis} | ${target}=${value} delta=${delta}% ${status} | ${secondariesStr}`;
+}
+
+/**
+ * Commits all staged/unstaged changes as an experiment commit.
+ * AC-10, AC-13: Each experiment gets exactly one commit before verification.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd        - Working directory (git repo root)
+ * @param {string} opts.skillName  - Skill being evaluated
+ * @param {string} opts.hypothesis - Short hypothesis string
+ * @param {string} opts.target     - Primary metric name
+ * @param {string|number} opts.value      - Primary metric value
+ * @param {string|number} opts.delta      - Delta percentage (numeric, sign included)
+ * @param {string} opts.status     - "pass" | "fail" | "inconclusive"
+ * @param {string} [opts.secondaries]     - Secondary metrics string
+ * @returns {string} The commit hash (short)
+ */
+function commitExperiment({ cwd, skillName, hypothesis, target, value, delta, status, secondaries }) {
+  const message = formatCommitMessage({ skillName, hypothesis, target, value, delta, status, secondaries });
+
+  // Stage all changes so the commit captures the experiment state
+  execSync('git add -A', { cwd, stdio: 'pipe' });
+  execSync(`git commit -m ${JSON.stringify(message)}`, { cwd, stdio: 'pipe' });
+
+  const hash = execSync('git rev-parse --short HEAD', { cwd, stdio: 'pipe' }).toString().trim();
+  return hash;
+}
+
+/**
+ * Reverts the HEAD commit using `git revert --no-edit`.
+ * AC-7: Keeps failed experiment in history (no reset/amend).
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd - Working directory (git repo root)
+ * @returns {string} The revert commit hash (short)
+ */
+function revertExperiment({ cwd }) {
+  execSync('git revert HEAD --no-edit', { cwd, stdio: 'pipe' });
+  const hash = execSync('git rev-parse --short HEAD', { cwd, stdio: 'pipe' }).toString().trim();
+  return hash;
+}
+
+/**
+ * Parses a single commit subject line into a structured experiment record.
+ * Returns null if the line does not match the experiment format.
+ *
+ * @param {string} hash
+ * @param {string} subject
+ * @returns {object|null}
+ */
+function parseExperimentLine(hash, subject) {
+  // Pattern: experiment({skillName}): {hypothesis} | {target}={value} delta={delta}% {status} | {secondaries}
+  const outerMatch = subject.match(/^experiment\(([^)]+)\):\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.*)$/);
+  if (!outerMatch) return null;
+
+  const [, parsedSkillName, hypothesis, metricsPart, secondaries] = outerMatch;
+
+  // Parse metrics: {target}={value} delta={delta}% {status}
+  const metricsMatch = metricsPart.match(/^(\S+)=(\S+)\s+delta=([-+]?[\d.]+)%\s+(\S+)$/);
+  if (!metricsMatch) return null;
+
+  const [, target, value, delta, status] = metricsMatch;
+
+  return {
+    hash,
+    skillName: parsedSkillName,
+    hypothesis,
+    target,
+    value,
+    delta: parseFloat(delta),
+    status,
+    secondaries: secondaries.trim(),
+  };
+}
+
+/**
+ * Queries git log for experiment commits matching a given skill.
+ * AC-10: Uses `git log --grep` to retrieve complete experiment history.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd       - Working directory (git repo root)
+ * @param {string} [opts.skillName] - If provided, filters by experiment({skillName}):
+ * @returns {Array<{hash, skillName, hypothesis, target, value, delta, status, secondaries}>}
+ */
+function queryExperiments({ cwd, skillName }) {
+  const grepPattern = skillName
+    ? `experiment(${skillName}):`
+    : 'experiment(';
+
+  let output;
+  try {
+    output = execSync(
+      `git log --grep=${JSON.stringify(grepPattern)} --format="%H %s"`,
+      { cwd, stdio: 'pipe' }
+    ).toString().trim();
+  } catch {
+    return [];
+  }
+
+  if (!output) return [];
+
+  const results = [];
+  for (const line of output.split('\n')) {
+    const spaceIdx = line.indexOf(' ');
+    if (spaceIdx === -1) continue;
+    const hash = line.slice(0, spaceIdx);
+    const subject = line.slice(spaceIdx + 1);
+    const parsed = parseExperimentLine(hash, subject);
+    if (parsed) results.push(parsed);
+  }
+  return results;
+}
+
+/**
+ * Returns a formatted history string suitable for inclusion in a mutator prompt.
+ * AC-10: Provides the complete experiment history for a skill.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd         - Working directory (git repo root)
+ * @param {string} [opts.skillName] - Filter by skill name
+ * @param {number} [opts.maxEntries=20] - Maximum number of entries to return
+ * @returns {string} Formatted history or "(no experiment history)" if empty
+ */
+function getExperimentHistory({ cwd, skillName, maxEntries = 20 }) {
+  const experiments = queryExperiments({ cwd, skillName });
+  const entries = experiments.slice(0, maxEntries);
+
+  if (entries.length === 0) {
+    return '(no experiment history)';
+  }
+
+  const lines = entries.map((e) => {
+    const secondary = e.secondaries ? ` | ${e.secondaries}` : '';
+    return `[${e.hash}] ${e.skillName}: ${e.hypothesis} => ${e.target}=${e.value} delta=${e.delta}% ${e.status}${secondary}`;
+  });
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  commitExperiment,
+  revertExperiment,
+  queryExperiments,
+  getExperimentHistory,
+  // exported for testing
+  formatCommitMessage,
+  parseExperimentLine,
+};