deepflow 0.1.103 → 0.1.104

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

@@ -0,0 +1,412 @@
+/**
+ * Tests for hooks/df-spec-lint.js
+ *
+ * Validates that computeLayer, validateSpec, and extractSection correctly
+ * handle YAML frontmatter (including derives-from fields) without
+ * misinterpreting frontmatter lines as section headers.
+ *
+ * Uses Node.js built-in node:test to avoid adding dependencies.
+ */
+
+'use strict';
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { computeLayer, validateSpec, extractSection, parseFrontmatter } = require('./df-spec-lint');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Minimal L0 spec (just Objective) */
+function minimalSpec(objective = 'Build the thing') {
+  return `## Objective\n${objective}\n`;
+}
+
+/** Full L3 spec with all required sections */
+function fullSpec() {
+  return [
+    '## 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');
+}
+
+/** Wrap content with YAML frontmatter */
+function withFrontmatter(body, fields = {}) {
+  const yamlLines = Object.entries(fields).map(([k, v]) => `${k}: ${v}`);
+  return ['---', ...yamlLines, '---', '', body].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// computeLayer — frontmatter handling
+// ---------------------------------------------------------------------------
+
+describe('computeLayer', () => {
+  test('returns L0 for spec with only Objective', () => {
+    assert.equal(computeLayer(minimalSpec()), 0);
+  });
+
+  test('returns L0 when frontmatter with derives-from precedes Objective', () => {
+    const content = withFrontmatter(minimalSpec(), {
+      'derives-from': 'done-auth',
+    });
+    assert.equal(computeLayer(content), 0);
+  });
+
+  test('returns L3 for full spec with derives-from frontmatter', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'done-auth',
+      name: 'spec-lineage',
+    });
+    assert.equal(computeLayer(content), 3);
+  });
+
+  test('frontmatter --- lines are not counted as section headers', () => {
+    // If --- were mistaken for headers, layer computation would break.
+    // Verify that a spec with frontmatter computes same layer as without.
+    const bare = fullSpec();
+    const wrapped = withFrontmatter(fullSpec(), {
+      'derives-from': 'done-auth',
+    });
+    assert.equal(computeLayer(bare), computeLayer(wrapped));
+  });
+
+  test('derives-from value is not mistaken for a section name', () => {
+    // derives-from: done-auth — should not create a phantom header
+    const content = withFrontmatter(minimalSpec(), {
+      'derives-from': 'done-auth',
+    });
+    // Still L0, not some higher layer from phantom headers
+    assert.equal(computeLayer(content), 0);
+  });
+
+  test('returns -1 when frontmatter exists but no Objective section', () => {
+    const content = withFrontmatter('Just some text, no headings.', {
+      'derives-from': 'done-auth',
+    });
+    assert.equal(computeLayer(content), -1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateSpec — frontmatter handling
+// ---------------------------------------------------------------------------
+
+describe('validateSpec with frontmatter', () => {
+  test('full spec with derives-from frontmatter produces no hard errors', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'done-auth',
+    });
+    const result = validateSpec(content);
+    assert.deepEqual(result.hard, []);
+  });
+
+  test('layer is correctly reported when frontmatter is present', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'done-auth',
+    });
+    const result = validateSpec(content);
+    assert.equal(result.layer, 3);
+  });
+
+  test('L0 spec with frontmatter reports missing sections as advisory only', () => {
+    const content = withFrontmatter(minimalSpec(), {
+      'derives-from': 'done-auth',
+    });
+    const result = validateSpec(content);
+    // L0 only requires Objective — everything else is advisory
+    assert.deepEqual(result.hard, []);
+    assert.ok(result.advisory.length > 0, 'should have advisory warnings for missing sections');
+  });
+
+  test('frontmatter --- delimiters do not appear in hard or advisory messages', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'done-auth',
+    });
+    const result = validateSpec(content);
+    const allMessages = [...result.hard, ...result.advisory];
+    for (const msg of allMessages) {
+      assert.ok(!msg.includes('---'), `Unexpected --- in message: ${msg}`);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractSection — frontmatter handling
+// ---------------------------------------------------------------------------
+
+describe('extractSection with frontmatter', () => {
+  test('extracts Objective section when frontmatter is present', () => {
+    const content = withFrontmatter(minimalSpec('Build the thing'), {
+      'derives-from': 'done-auth',
+    });
+    const section = extractSection(content, 'Objective');
+    assert.ok(section !== null, 'Objective section should be found');
+    assert.ok(section.includes('Build the thing'));
+  });
+
+  test('extracts Requirements section with frontmatter', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'done-auth',
+    });
+    const section = extractSection(content, 'Requirements');
+    assert.ok(section !== null);
+    assert.ok(section.includes('REQ-1'));
+  });
+
+  test('frontmatter content does not leak into extracted sections', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'done-auth',
+      description: 'A spec about things',
+    });
+    const objective = extractSection(content, 'Objective');
+    assert.ok(objective !== null);
+    assert.ok(!objective.includes('derives-from'));
+    assert.ok(!objective.includes('done-auth'));
+    assert.ok(!objective.includes('description'));
+  });
+
+  test('returns null for non-existent section even with frontmatter', () => {
+    const content = withFrontmatter(minimalSpec(), {
+      'derives-from': 'done-auth',
+    });
+    const section = extractSection(content, 'Nonexistent');
+    assert.equal(section, null);
+  });
+
+  test('extracts section using alias when frontmatter is present', () => {
+    const content = withFrontmatter(
+      '## Goal\nDo the thing\n\n## Requirements\n- REQ-1: stuff\n',
+      { 'derives-from': 'done-auth' }
+    );
+    // 'goal' is an alias for 'Objective'
+    const section = extractSection(content, 'Objective');
+    assert.ok(section !== null, 'Should find section via alias "Goal"');
+    assert.ok(section.includes('Do the thing'));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases — frontmatter-like patterns inside body
+// ---------------------------------------------------------------------------
+
+describe('frontmatter edge cases', () => {
+  test('--- inside spec body (e.g. horizontal rule) does not break computeLayer', () => {
+    const content = [
+      '---',
+      'derives-from: done-auth',
+      '---',
+      '',
+      '## Objective',
+      'Build it',
+      '',
+      '---',
+      '',
+      '## Requirements',
+      '- REQ-1: Something',
+    ].join('\n');
+    // Should at least be L1 (has Objective + Requirements)
+    assert.ok(computeLayer(content) >= 1);
+  });
+
+  test('multiple derives-from fields in frontmatter do not affect layer', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'done-auth, done-payments',
+    });
+    assert.equal(computeLayer(content), 3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseFrontmatter — direct unit tests
+// ---------------------------------------------------------------------------
+
+describe('parseFrontmatter', () => {
+  test('parses key-value pairs and returns body without frontmatter', () => {
+    const content = [
+      '---',
+      'derives-from: done-auth',
+      'name: spec-lineage',
+      '---',
+      '',
+      '## Objective',
+      'Build it',
+    ].join('\n');
+    const { frontmatter, body } = parseFrontmatter(content);
+    assert.equal(frontmatter['derives-from'], 'done-auth');
+    assert.equal(frontmatter['name'], 'spec-lineage');
+    assert.ok(body.includes('## Objective'));
+    assert.ok(body.includes('Build it'));
+  });
+
+  test('returns empty frontmatter and full body when no --- opener', () => {
+    const content = '## Objective\nBuild it\n';
+    const { frontmatter, body } = parseFrontmatter(content);
+    assert.deepEqual(frontmatter, {});
+    assert.equal(body, content);
+  });
+
+  test('returns empty frontmatter when opening --- exists but no closing ---', () => {
+    const content = '---\nderives-from: done-auth\n## Objective\nBuild it\n';
+    const { frontmatter, body } = parseFrontmatter(content);
+    assert.deepEqual(frontmatter, {});
+    assert.equal(body, content);
+  });
+
+  test('handles empty frontmatter block (--- immediately followed by ---)', () => {
+    const content = ['---', '---', '', '## Objective', 'Build it'].join('\n');
+    const { frontmatter, body } = parseFrontmatter(content);
+    assert.deepEqual(frontmatter, {});
+    assert.ok(body.includes('## Objective'));
+  });
+
+  test('trims whitespace from keys and values', () => {
+    const content = [
+      '---',
+      '  derives-from  :   done-auth  ',
+      '---',
+      '',
+      '## Objective',
+      'Build it',
+    ].join('\n');
+    const { frontmatter } = parseFrontmatter(content);
+    assert.equal(frontmatter['derives-from'], 'done-auth');
+  });
+
+  test('handles empty string input', () => {
+    const { frontmatter, body } = parseFrontmatter('');
+    assert.deepEqual(frontmatter, {});
+    assert.equal(body, '');
+  });
+
+  test('body does not include frontmatter delimiters', () => {
+    const content = withFrontmatter('## Objective\nBuild it', {
+      'derives-from': 'done-auth',
+    });
+    const { body } = parseFrontmatter(content);
+    // Body should not start with ---
+    assert.ok(!body.trimStart().startsWith('---'));
+  });
+
+  test('handles value containing colons', () => {
+    const content = [
+      '---',
+      'description: a spec: with colons: inside',
+      '---',
+      '',
+      'body',
+    ].join('\n');
+    const { frontmatter } = parseFrontmatter(content);
+    assert.equal(frontmatter['description'], 'a spec: with colons: inside');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// derives-from validation in validateSpec
+// ---------------------------------------------------------------------------
+
+describe('derives-from validation', () => {
+  test('spec without derives-from produces no derives-from advisory', () => {
+    const content = fullSpec();
+    const result = validateSpec(content);
+    const derivesAdvisory = result.advisory.filter((m) => m.includes('derives-from'));
+    assert.equal(derivesAdvisory.length, 0);
+  });
+
+  test('derives-from with no specsDir skips reference check (no warning)', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'nonexistent-spec',
+    });
+    // No specsDir passed — cannot verify, should not warn
+    const result = validateSpec(content);
+    const derivesAdvisory = result.advisory.filter((m) => m.includes('derives-from'));
+    assert.equal(derivesAdvisory.length, 0);
+  });
+
+  test('derives-from referencing missing spec emits advisory warning, not hard error', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'nonexistent-spec',
+    });
+    // Use a real directory that won't contain spec files
+    const tmpDir = path.join(__dirname, '..', 'templates');
+    const result = validateSpec(content, { specsDir: tmpDir });
+    // Should be advisory, not hard
+    const derivesHard = result.hard.filter((m) => m.includes('derives-from'));
+    assert.equal(derivesHard.length, 0, 'missing derives-from reference must not be a hard error');
+    const derivesAdvisory = result.advisory.filter((m) => m.includes('derives-from'));
+    assert.ok(derivesAdvisory.length > 0, 'should emit advisory warning for missing reference');
+  });
+
+  test('advisory message includes the referenced spec name', () => {
+    const content = withFrontmatter(fullSpec(), {
+      'derives-from': 'phantom-spec',
+    });
+    const tmpDir = path.join(__dirname, '..', 'templates');
+    const result = validateSpec(content, { specsDir: tmpDir });
+    const derivesAdvisory = result.advisory.filter((m) => m.includes('derives-from'));
+    assert.ok(
+      derivesAdvisory.some((m) => m.includes('phantom-spec')),
+      'advisory should mention the referenced spec name'
+    );
+  });
+
+  test('derives-from referencing existing spec file produces no advisory', () => {
+    // Create a temp specs dir with a matching file
+    const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'spec-lint-test-'));
+    try {
+      fs.writeFileSync(path.join(tmpDir, 'done-auth.md'), '## Objective\nAuth\n');
+      const content = withFrontmatter(fullSpec(), {
+        'derives-from': 'done-auth',
+      });
+      const result = validateSpec(content, { specsDir: tmpDir });
+      const derivesAdvisory = result.advisory.filter((m) => m.includes('derives-from'));
+      assert.equal(derivesAdvisory.length, 0, 'should not warn when reference exists');
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test('derives-from resolves done- prefixed files', () => {
+    // Reference "auth" but file is "done-auth.md" — should resolve
+    const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'spec-lint-test-'));
+    try {
+      fs.writeFileSync(path.join(tmpDir, 'done-auth.md'), '## Objective\nAuth\n');
+      const content = withFrontmatter(fullSpec(), {
+        'derives-from': 'auth',
+      });
+      const result = validateSpec(content, { specsDir: tmpDir });
+      const derivesAdvisory = result.advisory.filter((m) => m.includes('derives-from'));
+      assert.equal(derivesAdvisory.length, 0, 'should resolve done- prefixed file');
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test('spec layer and hard errors are unaffected by derives-from presence', () => {
+    const withDerives = withFrontmatter(fullSpec(), { 'derives-from': 'done-auth' });
+    const without = fullSpec();
+    const resultWith = validateSpec(withDerives);
+    const resultWithout = validateSpec(without);
+    assert.equal(resultWith.layer, resultWithout.layer);
+    assert.deepEqual(resultWith.hard, resultWithout.hard);
+  });
+});

package/hooks/df-statusline.js

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

package/hooks/df-subagent-registry.js

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

package/hooks/df-tool-usage.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @hook-event: PostToolUse
 /**
  * deepflow tool usage logger
  * Logs every PostToolUse event to ~/.claude/tool-usage.jsonl for token instrumentation.
@@ -67,13 +68,22 @@ process.stdin.on('end', () => {
       activeCommand = JSON.parse(markerRaw).command || null;
     } catch (_e) { /* no marker or unreadable — null */ }
 
+    // Extract a compact tool_input summary per tool type
+    const ti = data.tool_input || {};
+    let inputSummary = null;
+    if (toolName === 'Bash') inputSummary = ti.command || null;
+    else if (toolName === 'LSP') inputSummary = `${ti.operation || '?'}:${(ti.filePath || '').split('/').pop()}:${ti.line || '?'}`;
+    else if (toolName === 'Read') inputSummary = (ti.file_path || '').split('/').pop() + (ti.offset ? `:${ti.offset}-${ti.offset + (ti.limit || 0)}` : '');
+    else if (toolName === 'Grep') inputSummary = ti.pattern || null;
+    else if (toolName === 'Glob') inputSummary = ti.pattern || null;
+    else if (toolName === 'Agent') inputSummary = `${ti.subagent_type || '?'}/${ti.model || '?'}`;
+    else if (toolName === 'Edit' || toolName === 'Write') inputSummary = (ti.file_path || '').split('/').pop();
+
     const record = {
       timestamp: new Date().toISOString(),
       session_id: data.session_id || null,
       tool_name: toolName,
-      command: (toolName === 'Bash' && data.tool_input && data.tool_input.command != null)
-        ? data.tool_input.command
-        : null,
+      input: inputSummary,
       output_size_est_tokens: Math.ceil(JSON.stringify(toolResponse).length / 4),
       project: cwd ? path.basename(cwd) : null,
       phase: inferPhase(cwd),

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.103",
+  "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)