deepflow 0.1.84 → 0.1.86

package/README.md

@@ -148,6 +148,7 @@ $ git log --oneline
 | `/df:consolidate` | Deduplicate and clean up decisions.md |
 | `/df:resume` | Session continuity briefing |
 | `/df:update` | Update deepflow to latest |
+| `/df:report` | Generate session cost report (tokens, cache, quota) |
 | `/df:auto` | Autonomous mode (plan → loop → verify, no human needed) |
 
 ## File Structure
@@ -163,6 +164,9 @@ your-project/
     +-- decisions.md           # auto-extracted + ad-hoc decisions
     +-- auto-report.md         # morning report (autonomous mode)
     +-- auto-memory.yaml       # cross-cycle learning
+    +-- token-history.jsonl    # per-render token usage (auto)
+    +-- report.json            # session cost report (/df:report)
+    +-- report.md              # human-readable report (/df:report)
     +-- experiments/           # spike results (pass/fail)
     +-- worktrees/             # isolated execution
         +-- upload/            # one worktree per spec
@@ -190,15 +194,23 @@ your-project/
 
 Deepflow's design isn't opinionated — it's a direct response to measured LLM limitations:
 
-**Focused tasks > giant context** — LLMs lose ~2% effectiveness per 100K additional tokens, even on trivial tasks ([Chroma "Context Rot", 2025](https://research.trychroma.com/context-rot), 18 models tested). Deepflow keeps each task's context minimal and focused instead of loading the entire codebase.
+**Focused tasks > giant context** — LLMs lose ~2% effectiveness per 100K additional tokens, even on trivial tasks ([Chroma "Context Rot", 2025](https://research.trychroma.com/context-rot), 18 models tested). Accuracy drops from 89% at 8K tokens to 25% at 1M tokens ([Augment Code, 2025](https://www.augmentcode.com/tools/context-window-wars-200k-vs-1m-token-strategies)). Deepflow keeps each task's context minimal and focused instead of loading the entire codebase.
 
-**Tool use > context stuffing** — Information in the middle of context has up to 40% less recall than at the start/end ([Lost in the Middle, 2023](https://arxiv.org/abs/2307.03172)). Agents access code on-demand via LSP (`findReferences`, `incomingCalls`) and grep — always fresh, no attention dilution.
+**Search efficiency > model capability** — Coding agents spend [60% of their time searching, not coding](https://cognition.ai/blog/swe-grep) (Cognition, 2025). Input tokens dominate cost with up to [10x variance driven entirely by search efficiency](https://openreview.net/forum?id=1bUeVB3fov), not coding ability. Deepflow's LSP-first search and 3-phase explore protocol (DIVERSIFY/CONVERGE/EARLY STOP) minimize search waste.
+
+**The framework matters more than the model** — Same model, same tasks, different orchestration: [25.6 percentage point swing](https://arxiv.org/pdf/2509.16941) on SWE-Bench Lite (GPT-4: 2.7% with naive retrieval vs 28.3% with structured orchestration). On SWE-Bench Pro, three products using the same model scored 17 problems apart on 731 issues — the only difference was how they managed context, search, and edits. Deepflow is that orchestration layer.
+
+**Tool use > context stuffing** — Information in the middle of context has up to 40% less recall than at the start/end ([Lost in the Middle, 2024](https://arxiv.org/abs/2307.03172), Stanford/TACL). [LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025) found GPT-4O scoring 60-64% at full context vs 87-92% with oracle retrieval. Agents access code on-demand via LSP (`findReferences`, `incomingCalls`) and grep — always fresh, no attention dilution.
+
+**Fresh context beats long sessions** — Every AI agent's success rate decreases after [35 minutes of equivalent task time](https://zylos.ai/research/2026-01-16-long-running-ai-agents); doubling duration quadruples failure rate. Deepflow's autonomous mode (`/df:auto`) starts a fresh context each cycle — checkpoint state, not conversation history.
+
+**Input:output ratio matters** — Agent token ratio is [~100:1 input to output](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) (Manus, 2025). Deepflow truncates ratchet output (success = zero tokens), context-forks high-ratio skills, and strips prompt sections by effort level to keep the ratio low.
 
 **Model routing > one-size-fits-all** — Mechanical tasks with cheap models (haiku), complex tasks with powerful models (opus). Fewer tokens per task = less degradation = better results. Effort-aware context budgets strip unnecessary sections from prompts for simpler tasks.
 
 **Prompt order follows attention** — Execute prompts follow the attention U-curve: critical instructions (task definition, failure history, success criteria) at start and end, navigable data (impact analysis, dependency context) in the middle. Distractors eliminated by design.
 
-**LSP-powered impact analysis** — Plan-time uses `findReferences` and `incomingCalls` to map blast radius precisely. Execute-time runs a freshness check before implementing — catching callers added after planning. Grep as fallback when LSP is unavailable.
+**LSP-powered impact analysis** — Plan-time uses `findReferences` and `incomingCalls` to map blast radius precisely. Execute-time runs a freshness check before implementing — catching callers added after planning. Grep as fallback — though [embedding-based retrieval has a hard mathematical ceiling](https://arxiv.org/abs/2508.21038) (Google DeepMind, 2025) that LSP doesn't share.
 
 ## Skills
 

package/bin/install.js

@@ -183,7 +183,7 @@ async function main() {
   console.log(`${c.green}Installation complete!${c.reset}`);
   console.log('');
   console.log(`Installed to ${c.cyan}${CLAUDE_DIR}${c.reset}:`);
-  console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:auto, /df:note, /df:resume, /df:update');
+  console.log('  commands/df/     — /df:discover, /df:debate, /df:spec, /df:plan, /df:execute, /df:verify, /df:auto, /df:note, /df:resume, /df:update, /df:report');
   console.log('  skills/          — gap-discovery, atomic-commits, code-completeness, browse-fetch, browse-verify');
   console.log('  agents/          — reasoner (/df:auto — autonomous execution via /loop)');
   if (level === 'global') {
@@ -237,6 +237,7 @@ async function configureHooks(claudeDir) {
   const statuslineCmd = `node "${path.join(claudeDir, 'hooks', 'df-statusline.js')}"`;
   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')}"`;
 
   let settings = {};
 
@@ -286,10 +287,10 @@ async function configureHooks(claudeDir) {
     settings.hooks.SessionStart = [];
   }
 
-  // Remove any existing deepflow update check hooks
+  // Remove any existing deepflow update check / quota logger hooks from SessionStart
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter(hook => {
     const cmd = hook.hooks?.[0]?.command || '';
-    return !cmd.includes('df-check-update') && !cmd.includes('df-consolidation-check');
+    return !cmd.includes('df-check-update') && !cmd.includes('df-consolidation-check') && !cmd.includes('df-quota-logger');
   });
 
   // Add update check hook
@@ -307,8 +308,36 @@ async function configureHooks(claudeDir) {
       command: consolidationCheckCmd
     }]
   });
+
+  // Add quota logger to SessionStart
+  settings.hooks.SessionStart.push({
+    hooks: [{
+      type: 'command',
+      command: quotaLoggerCmd
+    }]
+  });
   log('SessionStart hook configured');
 
+  // Configure SessionEnd hook for quota logging
+  if (!settings.hooks.SessionEnd) {
+    settings.hooks.SessionEnd = [];
+  }
+
+  // Remove any existing quota logger from SessionEnd
+  settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(hook => {
+    const cmd = hook.hooks?.[0]?.command || '';
+    return !cmd.includes('df-quota-logger');
+  });
+
+  // Add quota logger to SessionEnd
+  settings.hooks.SessionEnd.push({
+    hooks: [{
+      type: 'command',
+      command: quotaLoggerCmd
+    }]
+  });
+  log('Quota logger configured');
+
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 }
 
@@ -489,7 +518,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');
+    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');
   }
 
   for (const item of toRemove) {
@@ -518,17 +547,26 @@ async function uninstall() {
         if (settings.hooks?.SessionStart) {
           settings.hooks.SessionStart = settings.hooks.SessionStart.filter(hook => {
             const cmd = hook.hooks?.[0]?.command || '';
-            return !cmd.includes('df-check-update') && !cmd.includes('df-consolidation-check');
+            return !cmd.includes('df-check-update') && !cmd.includes('df-consolidation-check') && !cmd.includes('df-quota-logger');
           });
           if (settings.hooks.SessionStart.length === 0) {
             delete settings.hooks.SessionStart;
           }
-          if (Object.keys(settings.hooks).length === 0) {
-            delete settings.hooks;
+        }
+        if (settings.hooks?.SessionEnd) {
+          settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(hook => {
+            const cmd = hook.hooks?.[0]?.command || '';
+            return !cmd.includes('df-quota-logger');
+          });
+          if (settings.hooks.SessionEnd.length === 0) {
+            delete settings.hooks.SessionEnd;
           }
-          fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-          console.log(`  ${c.green}✓${c.reset} Removed SessionStart hook`);
         }
+        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`);
       } catch (e) {
         // Fail silently
       }

package/hooks/df-quota-logger.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * deepflow quota logger
+ * Logs Anthropic API quota/usage data to ~/.claude/quota-history.jsonl
+ * Runs on SessionStart and SessionEnd events.
+ * Exits silently (code 0) on non-macOS or when Keychain token is absent.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+const https = require('https');
+
+const QUOTA_LOG = path.join(os.homedir(), '.claude', 'quota-history.jsonl');
+
+// Only supported on macOS (Keychain access)
+if (process.platform !== 'darwin') {
+  process.exit(0);
+}
+
+// Spawn background process so hook returns immediately
+if (process.argv[2] !== '--background') {
+  const { spawn } = require('child_process');
+  const child = spawn(process.execPath, [__filename, '--background'], {
+    detached: true,
+    stdio: 'ignore'
+  });
+  child.unref();
+  process.exit(0);
+}
+
+// --- Background process ---
+
+async function main() {
+  try {
+    const token = getToken();
+    if (!token) {
+      process.exit(0);
+    }
+
+    const data = await fetchQuota(token);
+    if (!data) {
+      process.exit(0);
+    }
+
+    appendLog(data);
+  } catch (_e) {
+    // Never break session hooks
+  }
+  process.exit(0);
+}
+
+function getToken() {
+  try {
+    const raw = execFileSync(
+      'security',
+      ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
+      { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }
+    ).toString().trim();
+
+    if (!raw) return null;
+
+    // The stored value may be a JSON blob with an access_token field
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed.access_token || parsed.token || raw;
+    } catch (_e) {
+      return raw;
+    }
+  } catch (_e) {
+    return null;
+  }
+}
+
+function fetchQuota(token) {
+  return new Promise((resolve) => {
+    const options = {
+      hostname: 'api.anthropic.com',
+      path: '/v1/organizations/me/usage',
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'anthropic-version': '2023-06-01',
+        'anthropic-beta': 'oauth-2025-04-20'
+      },
+      timeout: 10000
+    };
+
+    const req = https.request(options, (res) => {
+      let body = '';
+      res.on('data', chunk => { body += chunk; });
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(body);
+          resolve({ statusCode: res.statusCode, data: json });
+        } catch (_e) {
+          resolve({ statusCode: res.statusCode, raw: body.slice(0, 500) });
+        }
+      });
+    });
+
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.end();
+  });
+}
+
+function appendLog(payload) {
+  try {
+    const logDir = path.dirname(QUOTA_LOG);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    const event = process.env.CLAUDE_HOOK_EVENT || 'unknown';
+    const entry = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      event,
+      ...payload
+    });
+
+    fs.appendFileSync(QUOTA_LOG, entry + '\n');
+  } catch (_e) {
+    // Fail silently
+  }
+}
+
+main();

package/hooks/df-statusline.js

@@ -53,13 +53,13 @@ function buildStatusLine(data) {
   parts.push(`${colors.cyan}${project}${colors.reset}`);
 
   // Context window meter (Claude Code format: data.context_window)
-  const contextMeter = buildContextMeter(data.context_window || {});
+  const contextMeter = buildContextMeter(data.context_window || {}, data);
   parts.push(contextMeter);
 
   return parts.join(` ${colors.dim}│${colors.reset} `);
 }
 
-function buildContextMeter(contextWindow) {
+function buildContextMeter(contextWindow, data) {
   // Use pre-calculated percentage if available
   let percentage = contextWindow.used_percentage || 0;
 
@@ -77,6 +77,9 @@ function buildContextMeter(contextWindow) {
   // Write context usage to file for deepflow commands
   writeContextUsage(percentage);
 
+  // Write token history for instrumentation
+  writeTokenHistory(contextWindow, data);
+
   // Build 10-segment bar
   const segments = 10;
   const filled = Math.round((percentage / 100) * segments);
@@ -124,3 +127,35 @@ function writeContextUsage(percentage) {
     // Fail silently
   }
 }
+
+function writeTokenHistory(contextWindow, data) {
+  try {
+    const deepflowDir = path.join(process.cwd(), '.deepflow');
+    if (!fs.existsSync(deepflowDir)) {
+      fs.mkdirSync(deepflowDir, { recursive: true });
+    }
+
+    const usage = contextWindow.current_usage || {};
+    const timestamp = new Date().toISOString();
+    const model = data.model?.id || data.model?.display_name || 'unknown';
+    const sessionId = data.session_id || 'unknown';
+    const contextWindowSize = contextWindow.context_window_size || 0;
+    const usedPercentage = contextWindow.used_percentage || 0;
+
+    const record = {
+      timestamp,
+      input_tokens: usage.input_tokens || 0,
+      cache_creation_input_tokens: usage.cache_creation_input_tokens || 0,
+      cache_read_input_tokens: usage.cache_read_input_tokens || 0,
+      context_window_size: contextWindowSize,
+      used_percentage: usedPercentage,
+      model,
+      session_id: sessionId
+    };
+
+    const tokenHistoryPath = path.join(deepflowDir, 'token-history.jsonl');
+    fs.appendFileSync(tokenHistoryPath, JSON.stringify(record) + '\n');
+  } catch (e) {
+    // Fail silently
+  }
+}

package/package.json

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

package/src/commands/df/execute.md

@@ -123,6 +123,13 @@ Context ≥50%: checkpoint and exit.
 
 Before spawning: `TaskUpdate(taskId: native_id, status: "in_progress")` — activates UI spinner.
 
+**Token tracking — record start:**
+```
+start_percentage = !`cat .deepflow/context.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('percentage',''))" 2>/dev/null || echo ''`
+start_timestamp  = !`date -u +%Y-%m-%dT%H:%M:%SZ`
+```
+Store both values in memory (keyed by task_id) for use after ratchet completes. Omit if context.json unavailable.
+
 **NEVER use `isolation: "worktree"` on Task calls.** Deepflow manages a shared worktree so wave 2 sees wave 1 commits.
 
 **Spawn ALL ready tasks in ONE message** — EXCEPT file conflicts (see below).
@@ -181,6 +188,57 @@ After ratchet checks complete, truncate command output for context efficiency:
 - **Test failure:** Include failed test name(s) + last 20 lines of test output
 - **Typecheck/lint failure:** Include error count + first 5 errors only
 
+**Token tracking — write result (on ratchet pass):**
+
+After all checks pass, compute and write the token block to `.deepflow/results/T{N}.yaml`:
+
+```
+end_percentage = !`cat .deepflow/context.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('percentage',''))" 2>/dev/null || echo ''`
+```
+
+Parse `.deepflow/token-history.jsonl` to sum token fields for lines whose `timestamp` falls between `start_timestamp` and `end_timestamp` (ISO 8601 compare):
+```bash
+python3 - <<'EOF'
+import json, sys
+from datetime import datetime, timezone
+
+start = "REPLACE_start_timestamp"
+end   = "REPLACE_end_timestamp"   # current time: date -u +%Y-%m-%dT%H:%M:%SZ
+
+totals = {"input_tokens": 0, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0}
+try:
+    with open(".deepflow/token-history.jsonl") as f:
+        for line in f:
+            entry = json.loads(line)
+            ts = entry.get("timestamp", "")
+            if start <= ts <= end:
+                for k in totals:
+                    totals[k] += entry.get(k, 0)
+except FileNotFoundError:
+    sys.exit(0)
+
+print(json.dumps(totals))
+EOF
+```
+
+Append (or create) `.deepflow/results/T{N}.yaml` with the following block. Use shell injection to read the existing file first:
+```
+!`cat .deepflow/results/T{N}.yaml 2>/dev/null || echo ''`
+```
+
+Write the `tokens` block:
+```yaml
+tokens:
+  start_percentage: {start_percentage}
+  end_percentage: {end_percentage}
+  delta_percentage: {end_percentage - start_percentage}
+  input_tokens: {sum from jsonl}
+  cache_creation_input_tokens: {sum from jsonl}
+  cache_read_input_tokens: {sum from jsonl}
+```
+
+**Omit entirely if:** context.json was unavailable at start OR end, OR token-history.jsonl is missing, OR python3 is unavailable. Never fail the ratchet due to token tracking errors.
+
 **Evaluate:** All pass + no violations → commit stands. Any failure → attempt partial salvage before reverting:
 
 **Partial salvage protocol:**

package/src/commands/df/report.md

@@ -0,0 +1,230 @@
+---
+name: df:report
+description: Generate session cost report with token usage, cache hit ratio, per-task costs, and quota impact
+allowed-tools: [Read, Write, Bash]
+---
+
+# /df:report — Session Cost Report
+
+## Orchestrator Role
+
+You aggregate token usage data from multiple sources and produce a structured report.
+
+**NEVER:** Spawn agents, use Task tool, use AskUserQuestion, run git, use EnterPlanMode, use ExitPlanMode
+
+**ONLY:** Read data files, compute aggregates, write `.deepflow/report.json` and `.deepflow/report.md`
+
+---
+
+## Purpose
+
+Produce a cost and context report for the current session. Reads token-history.jsonl, quota-history.jsonl, per-task YAML result files, and auto-memory.yaml. Outputs a machine-readable JSON report and a human-readable Markdown summary.
+
+## Usage
+
+```
+/df:report
+```
+
+No arguments. Operates on `.deepflow/` data written by the statusline hook, execute command, and quota logger.
+
+---
+
+## Behavior
+
+### 1. LOAD DATA SOURCES
+
+Read each source gracefully — if a file does not exist, treat it as empty and continue.
+
+**a. Token history** — `.deepflow/token-history.jsonl`
+
+Parse each newline-delimited JSON object. Each line has fields:
+`timestamp`, `input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `context_window_size`, `used_percentage`, `model`, `session_id`
+
+Shell injection (use output directly):
+- `` !`cat .deepflow/token-history.jsonl 2>/dev/null || echo ''` ``
+
+Aggregate across all lines:
+- `total_input_tokens` = sum of `input_tokens`
+- `total_cache_creation` = sum of `cache_creation_input_tokens`
+- `total_cache_read` = sum of `cache_read_input_tokens`
+- `cache_hit_ratio` = `total_cache_read / (total_input_tokens + total_cache_creation + total_cache_read)` — clamp to `[0, 1]`, default `0` if denominator is 0
+- `peak_context_percentage` = max of `used_percentage` across all lines
+- `model` = value from the most recent line (last line)
+
+**b. Quota history** — `~/.claude/quota-history.jsonl`
+
+Parse the last 5 lines. Each line has `timestamp`, `event`, and API response payload fields.
+
+Shell injection:
+- `` !`tail -5 ~/.claude/quota-history.jsonl 2>/dev/null || echo ''` ``
+
+Extract the most recent quota entry. If the file does not exist or is empty, set `quota.available = false`.
+
+**c. Per-task results** — `.deepflow/results/T*.yaml`
+
+Shell injection:
+- `` !`ls .deepflow/results/T*.yaml 2>/dev/null || echo ''` ``
+
+For each YAML file found, read and extract the `tokens` block:
+```yaml
+tokens:
+  start_percentage: N
+  end_percentage: N
+  delta_percentage: N
+  input_tokens: N
+  cache_creation_input_tokens: N
+  cache_read_input_tokens: N
+```
+
+Derive `task_id` from the filename (e.g., `T3.yaml` → `"T3"`).
+
+If a file has no `tokens` block, skip it without error.
+
+**d. Session metadata** — `.deepflow/auto-memory.yaml`
+
+Shell injection:
+- `` !`cat .deepflow/auto-memory.yaml 2>/dev/null || echo ''` ``
+
+Read for context (session_id, start time, etc.) if available. Optional — do not fail if absent.
+
+### 2. COMPUTE AGGREGATES
+
+Using data from step 1:
+
+```
+total_tokens_all = total_input_tokens + total_cache_creation + total_cache_read
+cache_hit_ratio  = total_cache_read / total_tokens_all   (0 if total_tokens_all == 0)
+```
+
+Round `cache_hit_ratio` to 4 decimal places.
+
+### 3. WRITE `.deepflow/report.json`
+
+Generate an ISO 8601 timestamp for the `generated` field (current time).
+
+Schema:
+```json
+{
+  "version": 1,
+  "generated": "2026-03-17T12:00:00Z",
+  "session_summary": {
+    "total_input_tokens": 0,
+    "total_cache_creation": 0,
+    "total_cache_read": 0,
+    "cache_hit_ratio": 0.0,
+    "peak_context_percentage": 0,
+    "model": "claude-sonnet-4-5"
+  },
+  "tasks": [
+    {
+      "task_id": "T1",
+      "start_percentage": 0,
+      "end_percentage": 0,
+      "delta_percentage": 0,
+      "input_tokens": 0,
+      "cache_creation": 0,
+      "cache_read": 0
+    }
+  ],
+  "quota": {
+    "available": false
+  }
+}
+```
+
+Rules:
+- `version` is always `1`
+- `tasks` is an empty array `[]` if no task result files were found or none had a `tokens` block
+- `quota.available` is `false` if quota data is missing or could not be read; `true` with additional fields from the API payload if data was found
+- All token fields are integers >= 0
+- `cache_hit_ratio` is a float in `[0, 1]`
+
+### 4. WRITE `.deepflow/report.md`
+
+Generate a human-readable Markdown report. Use actual values from step 2.
+
+Required section headings (exact text):
+
+```markdown
+## Session Summary
+
+| Metric | Value |
+|--------|-------|
+| Model | {model} |
+| Total Input Tokens | {total_input_tokens} |
+| Cache Creation Tokens | {total_cache_creation} |
+| Cache Read Tokens | {total_cache_read} |
+| Cache Hit Ratio | {cache_hit_ratio} ({percentage}%) |
+| Peak Context Usage | {peak_context_percentage}% |
+
+## Per-Task Costs
+
+| Task | Start % | End % | Delta % | Input Tokens | Cache Creation | Cache Read |
+|------|---------|-------|---------|-------------|----------------|------------|
+| T1   | 0       | 5     | 5       | 12000        | 3000           | 1000       |
+
+_(No task data available)_ if tasks array is empty
+
+## Quota Impact
+
+{quota data table or "Not available (non-macOS or no token)"}
+```
+
+For **Quota Impact**:
+- If `quota.available = true`: render a table with the quota fields from the API payload
+- If `quota.available = false`: write exactly `Not available (non-macOS or no token)`
+
+### 5. CONFIRM
+
+Report to the user:
+
+```
+Report generated:
+  .deepflow/report.json  — machine-readable (version=1)
+  .deepflow/report.md    — human-readable summary
+```
+
+If any data source was missing, list them as a note:
+```
+Note: Missing data sources: token-history.jsonl, quota-history.jsonl
+```
+
+---
+
+## Rules
+
+- **Graceful degradation** — any missing file yields zero/empty values for that source; never error out
+- **No hallucination** — only write values derived from actual file contents; use 0 for missing numeric fields
+- **Idempotent** — re-running overwrites `.deepflow/report.json` and `.deepflow/report.md` with fresh data
+- **cache_hit_ratio always in [0,1]** — clamp if arithmetic produces out-of-range value
+- **ISO 8601 timestamps** — `generated` field uses UTC
+
+---
+
+## Example
+
+```
+USER: /df:report
+
+CLAUDE: [Reads .deepflow/token-history.jsonl — 42 lines found]
+[Reads ~/.claude/quota-history.jsonl — last 5 lines found]
+[Reads .deepflow/results/T1.yaml, T2.yaml, T3.yaml — tokens blocks extracted]
+[Reads .deepflow/auto-memory.yaml — session metadata found]
+
+[Computes:
+  total_input_tokens = 185000
+  total_cache_creation = 45000
+  total_cache_read = 320000
+  cache_hit_ratio = 320000 / (185000 + 45000 + 320000) = 0.5818
+  peak_context_percentage = 73
+  model = claude-sonnet-4-5
+]
+
+[Writes .deepflow/report.json]
+[Writes .deepflow/report.md]
+
+Report generated:
+  .deepflow/report.json  — machine-readable (version=1)
+  .deepflow/report.md    — human-readable summary
+```

package/templates/config-template.yaml

@@ -95,3 +95,10 @@ quality:
 
   # Timeout in seconds to wait for the dev server to become ready (default: 30)
   browser_timeout: 30
+
+# Recommended .gitignore entries
+# Add these entries to your .gitignore to exclude instrumentation artifacts
+gitignore_entries:
+  - "# Deepflow instrumentation artifacts"
+  - ".deepflow/token-history.jsonl   # Token usage history from autonomous mode"
+  - ".deepflow/report.json           # Instrumentation metrics summary"