deepflow 0.1.107 → 0.1.109

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.109",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",
@@ -42,5 +42,8 @@
   },
   "dependencies": {
     "playwright": "^1.58.2"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2"
   }
 }

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. **AC coverage check** (see §5.5.1). TaskUpdate(status: "completed"), update PLAN.md [x] + commit hash. **Extract decisions** (see §5.5.2).
 - **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,32 @@ 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. AC COVERAGE CHECK (after ratchet pass)
+
+After ratchet PASS (exit 0), run AC coverage check to verify agent reported all acceptance criteria:
+```bash
+node "${HOME}/.claude/bin/hooks/ac-coverage.js" --spec {spec_path} --output-file {agent_output_file} --status pass
+```
+
+where `{spec_path}` is the path to `specs/doing-{spec_name}.md` and `{agent_output_file}` is the task agent's full output transcript (from TaskOutput or notification context).
+
+**Exit codes from ac-coverage.js:**
+- **Exit 0:** All ACs covered or no ACs in spec. Status remains PASS. Proceed to decision extraction (§5.5.2).
+- **Exit 2 (SALVAGEABLE):** Missed ACs detected despite agent reporting TASK_STATUS:pass. Script outputs summary: `[ac-coverage] N/M ACs covered — missed: AC-X, AC-Y; ...`. Override final status to SALVAGEABLE. Commit stands. TaskUpdate(status: "completed") with note that ACs are incomplete.
+- **Exit 1 (script error):** Log error, do not change status. Proceed as if ratchet PASS (exit 0 from ac-coverage).
+
+#### 5.5.2. 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).
 
@@ -304,6 +338,25 @@ TASK_DETAIL=!`cat .deepflow/plans/doing-{task_id}.md 2>/dev/null || echo 'NOT_FO
 ```
 If `TASK_DETAIL` is not `NOT_FOUND`, use it as the full Middle section (Steps, ACs, Impact) in the agent prompt, overriding the inline PLAN.md block. If `NOT_FOUND`, fall back to the inline PLAN.md task block.
 
+**Pre-prompt type context extraction (before building agent prompt):**
+
+Run LSP `documentSymbol` on the task's `files` list to collect existing type definitions. This runs BEFORE prompt construction so the result can be injected as `EXISTING_TYPES`.
+
+<!-- AC-7: No new tool calls or latency added when context sources are empty -->
+**Early exit (AC-7):** If the task's `Files:` list is empty, skip all `documentSymbol` calls entirely. Set `EXISTING_TYPES` to empty string immediately and proceed to prompt construction.
+
+Steps (only when `Files:` list is non-empty):
+1. Cap the file list at 10 files (take the first 10 from the task's `Files:` list).
+2. For each file (up to the cap), call `documentSymbol` via LSP.
+3. Filter results: keep only symbols with kind ∈ {Class, Interface, Enum, TypeAlias} (LSP SymbolKind values 5, 11, 10, 26 respectively).
+4. For each matching symbol, extract the source range (`range.start.line` to `range.end.line`) — read those lines from the file.
+5. Accumulate extracted lines with a **120-line total budget** — stop adding symbols once the budget is reached.
+6. Join all extracted ranges into a single string: `EXISTING_TYPES`.
+
+**AC-8 — graceful no-op:** If no matching symbols are found across all processed files (either `documentSymbol` returns nothing or no Class/Interface/Enum/TypeAlias symbols exist), set `EXISTING_TYPES` to empty string. No context block is added to the prompt.
+
+<!-- AC-6: Backward-compatible no-op — when neither Domain Model section exists in the spec nor Existing Types extraction yields content (EXISTING_TYPES is empty string), the Standard Task prompt contains no extra context blocks and is identical to the pre-injection baseline. Zero prompt overhead, zero tool calls for tasks that lack these context sources. -->
+
 **Standard Task** (`Agent(model="{Model}", ...)`):
 ```
 --- START ---
@@ -317,6 +370,16 @@ spike_results:
   insight: {insight from probe_learnings}
 }
 Success criteria: {ACs from spec relevant to this task}
+{If spec contains ## Domain Model section:
+--- CONTEXT: Domain Model ---
+{Domain Model section content from doing-*.md, extracted via shell injection:
+  DOMAIN_MODEL=!`sed -n '/^## Domain Model$/,/^## [^D]/p' specs/doing-{spec_name}.md | head -n -1 2>/dev/null || echo 'NOT_FOUND'`
+}
+}
+{If EXISTING_TYPES is non-empty:
+--- CONTEXT: Existing Types ---
+{EXISTING_TYPES}
+}
 --- MIDDLE (omit for low effort; omit deps for medium) ---
 {TASK_DETAIL if available, else inline block:}
 Impact: Callers: {file} ({why}) | Duplicates: [active→consolidate] [dead→DELETE] | Data flow: {consumers}
@@ -324,12 +387,58 @@ 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.
+**Acceptance Criteria Coverage:** If the spec has acceptance criteria (AC-N), emit this block:
+```
+AC_COVERAGE:
+AC-1:done
+AC-2:skip:reason here (if applicable)
+AC_COVERAGE_END
+```
+Format: one line per AC with either `AC-N:done` or `AC-N:skip:reason`. Omit this block if the spec has no acceptance criteria.
+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.
+**Acceptance Criteria Coverage:** If the spec has acceptance criteria (AC-N), emit this block:
+```
+AC_COVERAGE:
+AC-1:done
+AC-2:skip:reason here (if applicable)
+AC_COVERAGE_END
+```
+Format: one line per AC with either `AC-N:done` or `AC-N:skip:reason`. Omit this block if the spec has no acceptance criteria.
+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 +508,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 |