deepflow 0.1.107 → 0.1.108

package/bin/worktree-deps.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * deepflow worktree-deps
+ * Symlinks node_modules from the main repo into a worktree so that
+ * TypeScript / LSP / builds resolve dependencies without a full install.
+ *
+ * Usage: node bin/worktree-deps.js --source /path/to/repo --worktree /path/to/worktree
+ *
+ * Walks the source repo looking for node_modules directories (max depth 2)
+ * and creates corresponding symlinks in the worktree.
+ *
+ * Exit codes: 0=OK, 1=ERROR
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--source' && args[i + 1]) opts.source = args[++i];
+    else if (args[i] === '--worktree' && args[i + 1]) opts.worktree = args[++i];
+  }
+  if (!opts.source || !opts.worktree) {
+    console.error('Usage: node bin/worktree-deps.js --source <repo> --worktree <worktree>');
+    process.exit(1);
+  }
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Find node_modules directories (depth 0 and 1 level of nesting)
+// ---------------------------------------------------------------------------
+
+function findNodeModules(root) {
+  const results = [];
+
+  // Root node_modules
+  const rootNM = path.join(root, 'node_modules');
+  if (fs.existsSync(rootNM)) {
+    results.push('node_modules');
+  }
+
+  // Scan common monorepo directory patterns for nested node_modules
+  const monorepoPatterns = ['packages', 'apps', 'libs', 'services', 'modules', 'plugins'];
+
+  for (const dir of monorepoPatterns) {
+    const dirPath = path.join(root, dir);
+    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) continue;
+
+    let entries;
+    try {
+      entries = fs.readdirSync(dirPath);
+    } catch (_) {
+      continue;
+    }
+
+    for (const entry of entries) {
+      const entryPath = path.join(dirPath, entry);
+      if (!fs.statSync(entryPath).isDirectory()) continue;
+
+      const nm = path.join(entryPath, 'node_modules');
+      if (fs.existsSync(nm)) {
+        results.push(path.join(dir, entry, 'node_modules'));
+      }
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Create symlinks
+// ---------------------------------------------------------------------------
+
+function symlinkDeps(source, worktree) {
+  const nodeModulesPaths = findNodeModules(source);
+
+  if (nodeModulesPaths.length === 0) {
+    console.log('{"linked":0,"message":"no node_modules found in source"}');
+    return;
+  }
+
+  let linked = 0;
+  const errors = [];
+
+  for (const relPath of nodeModulesPaths) {
+    const srcAbs = path.join(source, relPath);
+    const dstAbs = path.join(worktree, relPath);
+
+    // Skip if already exists (symlink or directory)
+    if (fs.existsSync(dstAbs)) {
+      continue;
+    }
+
+    // Ensure parent directory exists in worktree
+    const parent = path.dirname(dstAbs);
+    if (!fs.existsSync(parent)) {
+      fs.mkdirSync(parent, { recursive: true });
+    }
+
+    try {
+      fs.symlinkSync(srcAbs, dstAbs, 'dir');
+      linked++;
+    } catch (err) {
+      errors.push({ path: relPath, error: err.message });
+    }
+  }
+
+  const result = { linked, total: nodeModulesPaths.length };
+  if (errors.length > 0) result.errors = errors;
+  console.log(JSON.stringify(result));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const opts = parseArgs();
+symlinkDeps(opts.source, opts.worktree);

package/hooks/df-spec-lint.js

@@ -123,12 +123,23 @@ function computeLayer(content) {
  * @param {string} content  - The raw markdown content of the spec file.
  * @param {object} opts
  * @param {'interactive'|'auto'} opts.mode
+ * @param {string|null} opts.filename - Optional filename (basename) used for stem validation.
  * @returns {{ hard: string[], advisory: string[] }}
  */
-function validateSpec(content, { mode = 'interactive', specsDir = null } = {}) {
+function validateSpec(content, { mode = 'interactive', specsDir = null, filename = null } = {}) {
   const hard = [];
   const advisory = [];
 
+  // ── Spec filename stem validation ────────────────────────────────────
+  if (filename !== null) {
+    let stem = path.basename(filename, '.md');
+    stem = stem.replace(/^(doing-|done-)/, '');
+    const SAFE_STEM = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+    if (!SAFE_STEM.test(stem)) {
+      hard.push(`Spec filename stem contains unsafe characters: "${stem}"`);
+    }
+  }
+
   // ── Frontmatter: parse and validate derives-from ─────────────────────
   const { frontmatter } = parseFrontmatter(content);
   if (frontmatter['derives-from'] !== undefined) {
@@ -339,7 +350,7 @@ if (require.main === module) {
   const content = fs.readFileSync(filePath, 'utf8');
   const mode = process.argv.includes('--auto') ? 'auto' : 'interactive';
   const specsDir = path.resolve(path.dirname(filePath));
-  const result = validateSpec(content, { mode, specsDir });
+  const result = validateSpec(content, { mode, specsDir, filename: path.basename(filePath) });
 
   if (result.hard.length > 0) {
     console.error('HARD invariant failures:');

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

@@ -410,3 +410,136 @@ describe('derives-from validation', () => {
     assert.deepEqual(resultWith.hard, resultWithout.hard);
   });
 });
+
+// ---------------------------------------------------------------------------
+// validateSpec — spec filename stem validation
+// ---------------------------------------------------------------------------
+
+describe('validateSpec stem validation', () => {
+  test('valid plain name passes', () => {
+    const result = validateSpec(fullSpec(), { filename: 'my-spec.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('valid name with numbers passes', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec-v2-fix.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('single character name passes', () => {
+    const result = validateSpec(fullSpec(), { filename: 'a.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('doing- prefix is stripped before validation', () => {
+    const result = validateSpec(fullSpec(), { filename: 'doing-my-spec.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('done- prefix is stripped before validation', () => {
+    const result = validateSpec(fullSpec(), { filename: 'done-my-spec.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('filename with dollar sign is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec-$bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with backtick is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec-`bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with pipe character is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec|bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with semicolon is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec;bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with ampersand is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec&bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with space is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec bad.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with path traversal (..) is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: '..evil.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with leading hyphen is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: '-leading.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('filename with trailing hyphen is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: 'trailing-.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('empty stem (only prefix) is rejected as hard failure', () => {
+    // A filename of just "doing-.md" strips to empty string
+    const result = validateSpec(fullSpec(), { filename: 'doing-.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('empty filename stem (.md only) is rejected as hard failure', () => {
+    const result = validateSpec(fullSpec(), { filename: '.md' });
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 1);
+  });
+
+  test('stem validation failure is in hard array, not advisory', () => {
+    const result = validateSpec(fullSpec(), { filename: 'spec$bad.md' });
+    const hardErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    const advisoryErrors = result.advisory.filter((m) => m.includes('unsafe characters'));
+    assert.equal(hardErrors.length, 1);
+    assert.equal(advisoryErrors.length, 0);
+  });
+
+  test('no filename passed (null) skips stem validation', () => {
+    // No filename option — stem check should not run
+    const result = validateSpec(fullSpec());
+    const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+    assert.equal(stemErrors.length, 0);
+  });
+
+  test('all existing repo spec names pass validation', () => {
+    const existingNames = [
+      'done-dashboard-model-cost-fixes.md',
+      'done-orchestrator-v2.md',
+      'done-plan-cleanup.md',
+      'done-plan-fanout.md',
+      'done-quality-gates.md',
+    ];
+    for (const filename of existingNames) {
+      const result = validateSpec(fullSpec(), { filename });
+      const stemErrors = result.hard.filter((m) => m.includes('unsafe characters'));
+      assert.equal(stemErrors.length, 0, `Expected ${filename} to pass but got stem errors`);
+    }
+  });
+});

package/package.json

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

package/src/commands/df/execute.md

@@ -44,6 +44,14 @@ Shell: `` !`cat .deepflow/checkpoint.json 2>/dev/null || echo 'NOT_FOUND'` `` /
 
 Require clean HEAD. Derive SPEC_NAME from `specs/doing-*.md`. Create `.deepflow/worktrees/{spec}` on branch `df/{spec}`. Reuse if exists; `--fresh` deletes first. If `worktree.sparse_paths` non-empty: `git worktree add --no-checkout`, `sparse-checkout set {paths}`, checkout.
 
+### 1.5.1. SYMLINK DEPENDENCIES
+
+After worktree creation, symlink `node_modules` from the main repo so TypeScript/LSP/build can resolve dependencies without a full install:
+```bash
+node "${HOME}/.claude/bin/worktree-deps.js" --source "$(git rev-parse --show-toplevel)" --worktree "${WORKTREE_PATH}"
+```
+The script finds `node_modules` at root and inside monorepo directories (`packages/`, `apps/`, etc.) and creates symlinks in the worktree. Outputs JSON: `{"linked": N, "total": M}`. Errors are non-fatal — log and continue.
+
 ### 1.6. RATCHET SNAPSHOT
 
 Snapshot pre-existing test files — only these count for ratchet (agent-created excluded):
@@ -159,7 +167,7 @@ The script handles all health checks internally and outputs structured JSON:
 **Broken-tests policy:** Updating pre-existing tests requires a separate dedicated task in PLAN.md with explicit justification — never inline during execution.
 
 **Orchestrator response by exit code:**
-- **Exit 0 (PASS):** Commit stands. TaskUpdate(status: "completed"), update PLAN.md [x] + commit hash.
+- **Exit 0 (PASS):** Commit stands. TaskUpdate(status: "completed"), update PLAN.md [x] + commit hash. **Extract decisions** (see §5.5.1).
 - **Exit 1 (FAIL):** Script already reverted. Set `TaskUpdate(status: "pending")`. Recompute remaining waves:
   ```
   WAVE_JSON=!`node "${HOME}/.claude/bin/wave-runner.js" --json --plan PLAN.md --recalc --failed T{N} 2>/dev/null || echo 'WAVE_ERROR'`
@@ -168,6 +176,18 @@ The script handles all health checks internally and outputs structured JSON:
   Report: `"✗ T{n}: reverted"`.
 - **Exit 2 (SALVAGEABLE):** Spawn `Agent(model="sonnet")` to fix lint/typecheck issues. Re-run `node "${HOME}/.claude/bin/ratchet.js"`. If still non-zero → revert both commits, set status pending.
 
+#### 5.5.1. DECISION EXTRACTION (on ratchet pass)
+
+Parse the agent's response for `DECISIONS:` line. If present:
+1. Split by ` | ` to get individual decisions
+2. Each decision has format `[TAG] description — rationale` where TAG ∈ {APPROACH, PROVISIONAL, ASSUMPTION, FUTURE, UPDATE}
+3. Append to `.deepflow/decisions.md` under `### {date} — {spec_name}` header (create header if first decision for this spec today, reuse if exists)
+4. Format: `- [TAG] description — rationale`
+
+If no `DECISIONS:` line in agent output → skip silently (mechanical tasks don't produce decisions).
+
+**This runs on every ratchet pass, not just at verify time.** Decisions are captured incrementally as tasks complete, so they're never lost even if verify fails or merge is manual.
+
 **Edit scope validation:** `git diff HEAD~1 --name-only` vs allowed globs. Violation → revert, report.
 **Impact completeness:** diff vs Impact callers/duplicates. Gap → advisory warning (no revert).
 
@@ -324,12 +344,42 @@ Prior tasks: {dep_id}: {summary}
 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.
+DECISIONS: If you made non-obvious choices, append to the LAST LINE BEFORE TASK_STATUS:
+DECISIONS: [TAG] {decision} — {rationale} | [TAG] {decision2} — {rationale2}
+Tags:
+  [APPROACH] — chose X over Y (architectural/design choice)
+  [PROVISIONAL] — works for now but won't scale / needs revisit
+  [ASSUMPTION] — assumed X is true; if wrong, Y breaks
+  [FUTURE] — deferred X because Y; revisit when Z
+  [UPDATE] — changed prior decision from X to Y because Z
+Skip for trivial/mechanical changes.
 Last line of your response MUST be: TASK_STATUS:pass (if successful) or TASK_STATUS:fail (if failed) or TASK_STATUS:revert (if reverted)
 ```
 
+**Integration Task** (`Agent(model="opus")`):
+```
+--- START ---
+{task_id} [INTEGRATION]: Verify contracts between {spec_a} ↔ {spec_b}
+Integration ACs: {list from PLAN.md}
+--- MIDDLE ---
+Specs involved: {spec file paths}
+Interface Map: {from integration task detail}
+Contract Risks: {from integration task detail}
+--- END ---
+RULES:
+- Fix the CONSUMER to match the PRODUCER's declared interface. Never weaken the producer.
+- Each fix must reference the specific contract being repaired.
+- If a migration conflict exists, make ALL migrations idempotent (IF NOT EXISTS, IF NOT COLUMN, etc.)
+- Do NOT create new variables or intermediate adapters to paper over mismatches. Fix the actual call site.
+- Do NOT modify acceptance criteria or spec definitions.
+- Commit as fix({spec}): {contract description}. One commit per contract fix.
+DECISIONS: Report each contract fix as: [TAG] {what was mismatched} — {which side changed and why}. Use [APPROACH] for definitive fixes, [PROVISIONAL] if the fix is a workaround, [UPDATE] if changing a prior decision.
+Last line: TASK_STATUS:pass or TASK_STATUS:fail
+```
+
 **Bootstrap:** `BOOTSTRAP: Write tests for edit_scope files. Do NOT change implementation. Commit as test({spec}): bootstrap. Last line: TASK_STATUS:pass or TASK_STATUS:fail`
 
-**Spike:** `{task_id} [SPIKE]: {hypothesis}. Files+Spec. {reverted warnings}. Minimal spike. Commit as spike({spec}): {desc}. Last line: TASK_STATUS:pass or TASK_STATUS:fail`
+**Spike:** `{task_id} [SPIKE]: {hypothesis}. Files+Spec. {reverted warnings}. Minimal spike. Commit as spike({spec}): {desc}. If you discovered constraints, rejected approaches, or made assumptions, report: DECISIONS: [TAG] {finding} — {why it matters} (use PROVISIONAL for "works but needs revisit", ASSUMPTION for "assumed X; if wrong Y breaks", APPROACH for definitive choices). Last line: TASK_STATUS:pass or TASK_STATUS:fail`
 
 **Optimize Task** (`Agent(model="opus")`):
 ```
@@ -399,6 +449,7 @@ Reverted task: `TaskUpdate(status: "pending")`, dependents stay blocked. Repeate
 
 | Rule | Detail |
 |------|--------|
+| Integration tasks run last | [INTEGRATION] tasks execute after all blocked-by tasks complete. Fix tasks from integration failures are prescriptive (name the contract, producer, consumer, and which side to change). Never weaken the producer's declared interface — prefer fixing the consumer. |
 | Zero tests → bootstrap first | Sole task when snapshot empty |
 | 1 task = 1 agent = 1 commit | `atomic-commits` skill |
 | 1 file = 1 writer | Sequential on conflict |