deepflow 0.1.87 → 0.1.88

package/bin/install.js

@@ -238,6 +238,7 @@ async function configureHooks(claudeDir) {
   const updateCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-check-update.js')}"`;
   const consolidationCheckCmd = `node "${path.join(claudeDir, 'hooks', 'df-consolidation-check.js')}"`;
   const quotaLoggerCmd = `node "${path.join(claudeDir, 'hooks', 'df-quota-logger.js')}"`;
+  const toolUsageCmd = `node "${path.join(claudeDir, 'hooks', 'df-tool-usage.js')}"`;
 
   let settings = {};
 
@@ -338,6 +339,26 @@ async function configureHooks(claudeDir) {
   });
   log('Quota logger configured');
 
+  // Configure PostToolUse hook for tool usage instrumentation
+  if (!settings.hooks.PostToolUse) {
+    settings.hooks.PostToolUse = [];
+  }
+
+  // Remove any existing deepflow tool usage hooks from PostToolUse
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(hook => {
+    const cmd = hook.hooks?.[0]?.command || '';
+    return !cmd.includes('df-tool-usage');
+  });
+
+  // Add tool usage hook
+  settings.hooks.PostToolUse.push({
+    hooks: [{
+      type: 'command',
+      command: toolUsageCmd
+    }]
+  });
+  log('PostToolUse hook configured');
+
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 }
 
@@ -518,7 +539,7 @@ async function uninstall() {
   ];
 
   if (level === 'global') {
-    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js', 'hooks/df-consolidation-check.js', 'hooks/df-invariant-check.js', 'hooks/df-quota-logger.js');
+    toRemove.push('hooks/df-statusline.js', 'hooks/df-check-update.js', 'hooks/df-consolidation-check.js', 'hooks/df-invariant-check.js', 'hooks/df-quota-logger.js', 'hooks/df-tool-usage.js');
   }
 
   for (const item of toRemove) {
@@ -562,11 +583,20 @@ async function uninstall() {
             delete settings.hooks.SessionEnd;
           }
         }
+        if (settings.hooks?.PostToolUse) {
+          settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(hook => {
+            const cmd = hook.hooks?.[0]?.command || '';
+            return !cmd.includes('df-tool-usage');
+          });
+          if (settings.hooks.PostToolUse.length === 0) {
+            delete settings.hooks.PostToolUse;
+          }
+        }
         if (settings.hooks && Object.keys(settings.hooks).length === 0) {
           delete settings.hooks;
         }
         fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-        console.log(`  ${c.green}✓${c.reset} Removed SessionStart/SessionEnd hooks`);
+        console.log(`  ${c.green}✓${c.reset} Removed SessionStart/SessionEnd/PostToolUse hooks`);
       } catch (e) {
         // Fail silently
       }

package/hooks/df-spec-lint.js

@@ -22,6 +22,62 @@ const REQUIRED_SECTIONS = [
   ['Technical Notes', 'architecture notes', 'architecture', 'tech notes', 'implementation notes'],
 ];
 
+// ── Spec layers (onion model) ───────────────────────────────────────────
+// Each layer defines sections that must ALL be present (cumulative with prior layers).
+// The computed layer is the highest where all cumulative sections exist.
+//
+// L0: Problem defined        → spikes only
+// L1: Requirements known     → targeted spikes
+// L2: Verifiable             → implementation tasks
+// L3: Fully constrained      → full impact analysis + optimize tasks
+const LAYER_DEFINITIONS = [
+  { layer: 0, sections: ['Objective'] },
+  { layer: 1, sections: ['Requirements'] },
+  { layer: 2, sections: ['Acceptance Criteria'] },
+  { layer: 3, sections: ['Constraints', 'Out of Scope', 'Technical Notes'] },
+];
+
+/**
+ * Compute the spec layer from its content.
+ * Returns the highest layer (0–3) where ALL cumulative required sections are present.
+ * Returns -1 if not even L0 (no Objective).
+ */
+function computeLayer(content) {
+  const headersFound = [];
+  for (const line of content.split('\n')) {
+    const m = line.match(/^##\s+(.+)/i);
+    if (m) {
+      const raw = m[1].trim().replace(/^\d+\.\s*/, '');
+      headersFound.push(raw.toLowerCase());
+    }
+  }
+
+  // Inline *AC: lines satisfy the Acceptance Criteria requirement
+  const hasInlineAC = /\*AC[:.]/.test(content);
+
+  let currentLayer = -1;
+  for (const { layer, sections } of LAYER_DEFINITIONS) {
+    const allPresent = sections.every((section) => {
+      // Find the REQUIRED_SECTIONS entry for aliases
+      const entry = REQUIRED_SECTIONS.find(
+        ([canonical]) => canonical.toLowerCase() === section.toLowerCase()
+      );
+      const allNames = entry
+        ? [entry[0], ...entry.slice(1)].map((n) => n.toLowerCase())
+        : [section.toLowerCase()];
+
+      if (section === 'Acceptance Criteria' && hasInlineAC) return true;
+      return headersFound.some((h) => allNames.includes(h));
+    });
+    if (allPresent) {
+      currentLayer = layer;
+    } else {
+      break; // layers are cumulative — can't skip
+    }
+  }
+  return currentLayer;
+}
+
 /**
  * Validate a spec's content against hard invariants and advisory checks.
  *
@@ -34,7 +90,11 @@ function validateSpec(content, { mode = 'interactive', specsDir = null } = {}) {
   const hard = [];
   const advisory = [];
 
-  // ── (a) Required sections ────────────────────────────────────────────
+  const layer = computeLayer(content);
+
+  // ── (a) Required sections (layer-aware) ──────────────────────────────
+  // Hard-fail only for sections required by the CURRENT layer.
+  // Missing sections beyond the current layer are advisory (hints to deepen).
   const headersFound = [];
   for (const line of content.split('\n')) {
     const m = line.match(/^##\s+(.+)/i);
@@ -45,13 +105,25 @@ function validateSpec(content, { mode = 'interactive', specsDir = null } = {}) {
     }
   }
 
+  // Collect all sections required up to the current layer
+  const layerRequiredSections = new Set();
+  for (const { layer: l, sections } of LAYER_DEFINITIONS) {
+    if (l <= layer) {
+      for (const s of sections) layerRequiredSections.add(s.toLowerCase());
+    }
+  }
+
   for (const [canonical, ...aliases] of REQUIRED_SECTIONS) {
     const allNames = [canonical, ...aliases].map((n) => n.toLowerCase());
     const found = headersFound.some((h) => allNames.includes(h.toLowerCase()));
     if (!found) {
       // Inline *AC: lines satisfy the Acceptance Criteria requirement
       if (canonical === 'Acceptance Criteria' && /\*AC[:.]/.test(content)) continue;
-      hard.push(`Missing required section: "## ${canonical}"`);
+      if (layerRequiredSections.has(canonical.toLowerCase())) {
+        hard.push(`Missing required section: "## ${canonical}"`);
+      } else {
+        advisory.push(`Missing section for deeper layer: "## ${canonical}"`);
+      }
     }
   }
 
@@ -161,7 +233,7 @@ function validateSpec(content, { mode = 'interactive', specsDir = null } = {}) {
     hard.push(...advisory.splice(0, advisory.length));
   }
 
-  return { hard, advisory };
+  return { layer, hard, advisory };
 }
 
 /**
@@ -230,7 +302,9 @@ if (require.main === module) {
     console.log('All checks passed.');
   }
 
+  console.log(`Spec layer: L${result.layer} (${['problem defined', 'requirements known', 'verifiable', 'fully constrained'][result.layer] || 'incomplete'})`);
+
   process.exit(result.hard.length > 0 ? 1 : 0);
 }
 
-module.exports = { validateSpec, extractSection };
+module.exports = { validateSpec, extractSection, computeLayer };

package/hooks/df-statusline.js

@@ -75,11 +75,14 @@ function buildContextMeter(contextWindow, data) {
   percentage = Math.min(100, Math.round(percentage));
 
   // Write context usage to file for deepflow commands
-  writeContextUsage(percentage);
+  writeContextUsage(percentage, data);
 
   // Write token history for instrumentation
   writeTokenHistory(contextWindow, data);
 
+  // Write cache history for cross-session persistence
+  writeCacheHistory(contextWindow, data);
+
   // Build 10-segment bar
   const segments = 10;
   const filled = Math.round((percentage / 100) * segments);
@@ -112,9 +115,10 @@ function checkForUpdate() {
   return null;
 }
 
-function writeContextUsage(percentage) {
+function writeContextUsage(percentage, data) {
   try {
-    const deepflowDir = path.join(process.cwd(), '.deepflow');
+    const baseDir = data?.workspace?.current_dir || process.cwd();
+    const deepflowDir = path.join(baseDir, '.deepflow');
     if (!fs.existsSync(deepflowDir)) {
       fs.mkdirSync(deepflowDir, { recursive: true });
     }
@@ -130,7 +134,8 @@ function writeContextUsage(percentage) {
 
 function writeTokenHistory(contextWindow, data) {
   try {
-    const deepflowDir = path.join(process.cwd(), '.deepflow');
+    const baseDir = data?.workspace?.current_dir || process.cwd();
+    const deepflowDir = path.join(baseDir, '.deepflow');
     if (!fs.existsSync(deepflowDir)) {
       fs.mkdirSync(deepflowDir, { recursive: true });
     }
@@ -142,6 +147,9 @@ function writeTokenHistory(contextWindow, data) {
     const contextWindowSize = contextWindow.context_window_size || 0;
     const usedPercentage = contextWindow.used_percentage || 0;
 
+    const agentRole = process.env.DEEPFLOW_AGENT_ROLE || 'orchestrator';
+    const taskId = process.env.DEEPFLOW_TASK_ID || null;
+
     const record = {
       timestamp,
       input_tokens: usage.input_tokens || 0,
@@ -150,7 +158,9 @@ function writeTokenHistory(contextWindow, data) {
       context_window_size: contextWindowSize,
       used_percentage: usedPercentage,
       model,
-      session_id: sessionId
+      session_id: sessionId,
+      agent_role: agentRole,
+      task_id: taskId
     };
 
     const tokenHistoryPath = path.join(deepflowDir, 'token-history.jsonl');
@@ -159,3 +169,65 @@ function writeTokenHistory(contextWindow, data) {
     // Fail silently
   }
 }
+
+function writeCacheHistory(contextWindow, data) {
+  try {
+    const usage = contextWindow.current_usage || {};
+    const sessionId = data.session_id || 'unknown';
+
+    const inputTokens = usage.input_tokens || 0;
+    const cacheCreationTokens = usage.cache_creation_input_tokens || 0;
+    const cacheReadTokens = usage.cache_read_input_tokens || 0;
+    const totalTokens = inputTokens + cacheCreationTokens + cacheReadTokens;
+
+    // Compute cache hit ratio: cache_read / total
+    const cacheHitRatio = totalTokens > 0 ? cacheReadTokens / totalTokens : 0;
+
+    const model = data.model?.id || data.model?.display_name || 'unknown';
+    const agentRole = process.env.DEEPFLOW_AGENT_ROLE || 'orchestrator';
+    const taskId = process.env.DEEPFLOW_TASK_ID || null;
+
+    const cacheHistoryPath = path.join(os.homedir(), '.claude', 'cache-history.jsonl');
+
+    // Dedup: only write if session_id differs from last written record
+    let lastSessionId = null;
+    if (fs.existsSync(cacheHistoryPath)) {
+      const content = fs.readFileSync(cacheHistoryPath, 'utf8');
+      const lines = content.trimEnd().split('\n');
+      if (lines.length > 0) {
+        try {
+          const lastRecord = JSON.parse(lines[lines.length - 1]);
+          lastSessionId = lastRecord.session_id;
+        } catch (e) {
+          // Ignore parse errors on last line
+        }
+      }
+    }
+
+    if (sessionId === lastSessionId) {
+      return;
+    }
+
+    const record = {
+      timestamp: new Date().toISOString(),
+      session_id: sessionId,
+      cache_hit_ratio: Math.round(cacheHitRatio * 10000) / 10000,
+      total_tokens: totalTokens,
+      agent_breakdown: {
+        agent_role: agentRole,
+        task_id: taskId,
+        model
+      }
+    };
+
+    // Ensure ~/.claude directory exists
+    const claudeDir = path.join(os.homedir(), '.claude');
+    if (!fs.existsSync(claudeDir)) {
+      fs.mkdirSync(claudeDir, { recursive: true });
+    }
+
+    fs.appendFileSync(cacheHistoryPath, JSON.stringify(record) + '\n');
+  } catch (e) {
+    // Fail silently
+  }
+}

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

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Spike hook: capture raw PostToolUse stdin payload
+ * Writes the raw JSON to /tmp/df-posttooluse-payload.json for inspection.
+ * Safe to install temporarily — exits cleanly (code 0) always.
+ *
+ * Usage in ~/.claude/settings.json:
+ *   "PostToolUse": [{ "hooks": [{ "type": "command", "command": "node /path/to/df-tool-usage-spike.js" }] }]
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; });
+process.stdin.on('end', () => {
+  try {
+    // Write raw payload for inspection
+    fs.writeFileSync('/tmp/df-posttooluse-payload.json', raw);
+
+    // Also append a minimal summary line for quick review
+    const data = JSON.parse(raw);
+    const summary = {
+      hook_event_name: data.hook_event_name,
+      tool_name: data.tool_name,
+      tool_use_id: data.tool_use_id,
+      session_id: data.session_id,
+      cwd: data.cwd,
+      permission_mode: data.permission_mode,
+      tool_input_keys: data.tool_input ? Object.keys(data.tool_input) : [],
+      tool_response_keys: data.tool_response ? Object.keys(data.tool_response) : [],
+      transcript_path: data.transcript_path,
+    };
+    fs.appendFileSync('/tmp/df-posttooluse-summary.jsonl', JSON.stringify(summary) + '\n');
+  } catch (_e) {
+    // Fail silently — never break tool execution
+  }
+  process.exit(0);
+});

package/hooks/df-tool-usage.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * deepflow tool usage logger
+ * Logs every PostToolUse event to ~/.claude/tool-usage.jsonl for token instrumentation.
+ * Exits silently (code 0) on all errors — never breaks tool execution.
+ *
+ * Output record fields (REQ-2):
+ *   timestamp, session_id, tool_name, command, output_size_est_tokens,
+ *   project, phase, task_id
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const TOOL_USAGE_LOG = path.join(os.homedir(), '.claude', 'tool-usage.jsonl');
+
+/**
+ * Infer phase from cwd.
+ * If cwd contains .deepflow/worktrees/, parse the worktree dir name for phase.
+ * Worktree dirs are named "execute", "verify", or task-specific names.
+ * Default: "manual"
+ */
+function inferPhase(cwd) {
+  if (!cwd) return 'manual';
+  const match = cwd.match(/\.deepflow[/\\]worktrees[/\\]([^/\\]+)/);
+  if (!match) return 'manual';
+  const worktreeName = match[1].toLowerCase();
+  if (worktreeName === 'execute') return 'execute';
+  if (worktreeName === 'verify') return 'verify';
+  // Could be a task-specific worktree — still inside worktrees/, treat as execute
+  return 'execute';
+}
+
+/**
+ * Extract task_id from worktree directory name.
+ * Pattern: T{n} prefix, e.g. "T3-feature" → "T3", "T12" → "T12"
+ * Returns null if not in a worktree or no task prefix found.
+ */
+function extractTaskId(cwd) {
+  if (!cwd) return null;
+  const match = cwd.match(/\.deepflow[/\\]worktrees[/\\]([^/\\]+)/);
+  if (!match) return null;
+  const worktreeName = match[1];
+  const taskMatch = worktreeName.match(/^(T\d+)/i);
+  return taskMatch ? taskMatch[1].toUpperCase() : null;
+}
+
+// Read all stdin, then process
+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 || null;
+    const toolResponse = data.tool_response;
+    const cwd = data.cwd || '';
+
+    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,
+      output_size_est_tokens: Math.ceil(JSON.stringify(toolResponse).length / 4),
+      project: cwd ? path.basename(cwd) : null,
+      phase: inferPhase(cwd),
+      task_id: extractTaskId(cwd),
+    };
+
+    const logDir = path.dirname(TOOL_USAGE_LOG);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    fs.appendFileSync(TOOL_USAGE_LOG, JSON.stringify(record) + '\n');
+  } catch (_e) {
+    // Fail silently — never break tool execution
+  }
+  process.exit(0);
+});

package/package.json

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