devflow-kit 1.8.2 → 2.0.0

package/src/assets/scripts/hooks/capture-question

@@ -0,0 +1,153 @@
+#!/bin/bash
+
+# Learning System: capture-question (PostToolUse Hook, matcher: AskUserQuestion)
+# Captures each answered question as a {role:"qa"} row into BOTH the memory and
+# learning queues -- high decision-signal content that free-running Stop-hook
+# turns miss (the model's own paraphrase of an answer is lossy; the raw Q&A
+# pair is not).
+#
+# PAYLOAD SHAPE (pinned empirically -- see .devflow/docs/handoff-*.md for the
+# mining method and exact captured samples):
+#   Envelope (captured via a scratch-project PostToolUse probe against the
+#   CURRENT harness version): session_id, transcript_path, cwd, prompt_id,
+#   permission_mode, effort, hook_event_name, tool_name, tool_input,
+#   tool_response, tool_use_id, duration_ms. Verified: tool_response is
+#   byte-identical to the toolUseResult recorded in the transcript JSONL for
+#   the same tool call.
+#   tool_input.questions: [{question, header, options:[{label,description}], multiSelect}]
+#   tool_response (success): {questions:[...], answers:{<question text>: <answer
+#     string, or string[] for multiSelect>}, annotations:{}}
+#   tool_response (validation error, e.g. missing "questions"): a PLAIN STRING,
+#     e.g. "InputValidationError: [...]" -- a real sample mined from
+#     ~/.claude/projects.
+#   No genuine cancelled/interrupted or free-text ("Other") sample was found
+#   despite an exhaustive machine-wide search; free text would use the SAME
+#   answers[question]=string shape as a listed option (confirmed structurally
+#   from the observed schema, not invented), so no special case is needed.
+#
+# Handling contract (regardless of shape): one qa row per question; cancelled/
+# absent/errored tool_response -> exit 0, zero writes; non-AskUserQuestion
+# tool_name -> exit 0 (defensive, even though the hook is matcher-scoped).
+
+# Safe no-op fallback: must exist before set -e and before hook-bootstrap is sourced.
+dbg() { :; }
+
+set -e
+
+# Feedback-loop guard -- before hook-bootstrap to minimize background session overhead.
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/hook-bootstrap" "capture-question"
+
+source "$SCRIPT_DIR/json-parse" || { echo "capture-question: failed to source json-parse" >&2; exit 1; }
+if [ "$_JSON_AVAILABLE" = "false" ]; then dbg "EXIT: no json"; exit 0; fi
+
+INPUT=$(cat)
+
+TOOL_NAME=$(printf '%s' "$INPUT" | json_field "tool_name" "")
+if [ "$TOOL_NAME" != "AskUserQuestion" ]; then
+  dbg "EXIT: not AskUserQuestion (tool_name=$TOOL_NAME)"
+  exit 0
+fi
+
+CWD=$(printf '%s' "$INPUT" | json_field "cwd" "")
+if [ -z "$CWD" ] || [ ! -d "$CWD" ]; then dbg "EXIT: bad CWD"; exit 0; fi
+
+devflow_debug_set_cwd "$CWD"
+
+source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
+PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
+[ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
+
+DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
+MEMORY_DIR="$DEVFLOW_DIR/memory"
+LEARNING_DIR="$DEVFLOW_DIR/learning"
+
+# --- Parse questions + answers into "question<TAB>answer" rows (one subprocess) ---
+# Defensive against: tool_response absent or a plain string (error case), missing
+# questions/answers, multiSelect array answers (joined with "; "), non-object
+# tool_input. Tabs/newlines within a question or answer are collapsed to spaces
+# so the TAB-delimited row format below stays unambiguous (mirrors
+# background-memory-update's own gsub("\n";" ") convention for the same reason).
+if [ "$_HAS_JQ" = "true" ]; then
+  QA_ROWS=$(printf '%s' "$INPUT" | jq -r '
+    (.tool_response // {}) as $tr
+    | if ($tr|type) != "object" then
+        empty
+      else
+        (.tool_input.questions // [])[] as $q
+        | ($tr.answers // {})[$q.question] as $a
+        | select($a != null)
+        | (($q.question // "") | gsub("\n";" ") | gsub("\t";" ")) as $qtext
+        | ((if ($a|type)=="array" then ($a|join("; ")) else ($a|tostring) end) | gsub("\n";" ") | gsub("\t";" ")) as $atext
+        | $qtext + "\t" + $atext
+      end
+  ' 2>/dev/null || echo "")
+else
+  QA_ROWS=$(printf '%s' "$INPUT" | node -e '
+    let raw = "";
+    try { raw = require("fs").readFileSync("/dev/stdin", "utf8"); } catch { process.exit(0); }
+    let input;
+    try { input = JSON.parse(raw); } catch { process.exit(0); }
+    const tr = input.tool_response;
+    if (!tr || typeof tr !== "object") process.exit(0);
+    const questions = Array.isArray(input.tool_input && input.tool_input.questions) ? input.tool_input.questions : [];
+    const answers = (tr.answers && typeof tr.answers === "object") ? tr.answers : {};
+    const clean = (s) => String(s).replace(/\n/g, " ").replace(/\t/g, " ");
+    const lines = [];
+    for (const q of questions) {
+      if (!q || typeof q.question !== "string") continue;
+      const a = answers[q.question];
+      if (a === undefined || a === null) continue;
+      const aStr = Array.isArray(a) ? a.join("; ") : String(a);
+      lines.push(clean(q.question) + "\t" + clean(aStr));
+    }
+    process.stdout.write(lines.join("\n"));
+  ' 2>/dev/null || echo "")
+fi
+
+if [ -z "$QA_ROWS" ]; then
+  dbg "EXIT: no answered questions found (cancelled/errored/absent tool_response, or non-object shape)"
+  exit 0
+fi
+
+source "$SCRIPT_DIR/queue-append" || { echo "capture-question: failed to source queue-append" >&2; exit 1; }
+
+# --- AC-P1-style: ONE config fork reads both memory + learning fields ---
+queue_read_gates "$DEVFLOW_DIR/config.json"
+MEMORY_ENABLED="$_QG_MEMORY"
+LEARNING_ENABLED="$_QG_LEARNING"
+
+if [ "$MEMORY_ENABLED" != "true" ] && [ "$LEARNING_ENABLED" != "true" ]; then
+  dbg "EXIT: both features disabled"
+  exit 0
+fi
+
+source "$SCRIPT_DIR/hook-log-init" "capture-question"
+source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
+source "$SCRIPT_DIR/get-mtime" || { echo "capture-question: failed to source get-mtime" >&2; exit 1; }
+source "$SCRIPT_DIR/learning-lock" || { echo "capture-question: failed to source learning-lock" >&2; exit 1; }
+
+mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
+
+_QUESTION_COUNT=0
+while IFS=$'\t' read -r Q A; do
+  [ -z "$Q" ] && continue
+
+  CONTENT="Q: ${Q}
+A: ${A}"
+  TS=$(date +%s)
+  queue_append_both \
+    "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+    "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
+    "qa" "$CONTENT" "$TS"
+  _QUESTION_COUNT=$(( _QUESTION_COUNT + 1 ))
+done <<EOF
+$QA_ROWS
+EOF
+
+log "Captured ${_QUESTION_COUNT} qa row(s)"
+dbg "=== HOOK COMPLETE ==="
+exit 0

package/src/assets/scripts/hooks/capture-turn

@@ -0,0 +1,105 @@
+#!/bin/bash
+
+# Learning System: capture-turn (Stop Hook)
+# Dual-append: writes the assistant turn to BOTH the memory queue and the
+# learning queue, each independently gated by its own feature flag (AC-F4). Runs
+# the decisions usage scanner (D29 grep-first) regardless of which queue is
+# gated on/off -- memory-disabled projects still run the usage scanner. The
+# 120s-throttle/nohup-spawn block lives in memory-worker, registered
+# separately in the Stop hook array AFTER this hook so append-before-spawn
+# ordering is preserved by array position, not by anything in this script.
+# This hook never spawns a process (AC-F5).
+
+# Safe no-op fallback: must exist before set -e and before hook-bootstrap is sourced.
+dbg() { :; }
+
+set -e
+
+# Feedback-loop guard -- before hook-bootstrap to minimize background session overhead.
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/hook-bootstrap" "capture-turn"
+
+source "$SCRIPT_DIR/json-parse" || { echo "capture-turn: failed to source json-parse" >&2; exit 1; }
+if [ "$_JSON_AVAILABLE" = "false" ]; then dbg "EXIT: no json"; exit 0; fi
+
+INPUT=$(cat)
+dbg "INPUT length=${#INPUT}"
+
+# Resolve project directory and assistant response in one subprocess via the
+# shared json_extract_cwd_field helper (json-parse) -- keeps the SOH delimiter
+# and jq/node fallback pair defined in exactly one place, shared with capture-prompt.
+_FIELDS=$(printf '%s' "$INPUT" | json_extract_cwd_field "last_assistant_message") || { dbg "EXIT: extraction failed"; exit 0; }
+CWD="${_FIELDS%%$'\001'*}"
+ASSISTANT_MSG="${_FIELDS#*$'\001'}"
+
+if [ -z "$CWD" ] || [ ! -d "$CWD" ]; then dbg "EXIT: bad CWD"; exit 0; fi
+
+devflow_debug_set_cwd "$CWD"
+dbg "CWD=$CWD"
+# SECURITY: Never log ASSISTANT_MSG or INPUT content -- may contain secrets.
+dbg "ASSISTANT_MSG length=${#ASSISTANT_MSG}"
+
+# Anchor .devflow/ to the project root (prevents a stray nested .devflow/ when this
+# hook runs with a CWD inside .devflow/...). Empty → fall back to CWD.
+source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
+PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
+[ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
+
+DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
+MEMORY_DIR="$DEVFLOW_DIR/memory"
+LEARNING_DIR="$DEVFLOW_DIR/learning"
+
+# Skip if empty response
+if [ -z "$ASSISTANT_MSG" ]; then
+  dbg "EXIT: empty ASSISTANT_MSG"
+  exit 0
+fi
+
+source "$SCRIPT_DIR/queue-append" || { echo "capture-turn: failed to source queue-append" >&2; exit 1; }
+
+# --- AC-P1: exactly ONE config-read fork, fetching both memory + learning fields ---
+queue_read_gates "$DEVFLOW_DIR/config.json"
+MEMORY_ENABLED="$_QG_MEMORY"
+LEARNING_ENABLED="$_QG_LEARNING"
+
+dbg "MEMORY_ENABLED=$MEMORY_ENABLED LEARNING_ENABLED=$LEARNING_ENABLED"
+
+# --- Decisions usage scanner (independent of the memory/learning queue gates below) ---
+# D29: Grep-first reorder -- cheap in-process citation check gates the scanner call.
+SCANNER="$SCRIPT_DIR/decisions-usage-scan.cjs"
+if [ -f "$SCANNER" ] && printf '%s' "$ASSISTANT_MSG" | grep -qE 'ADR-[0-9]+|PF-[0-9]+'; then
+  if [ "$LEARNING_ENABLED" = "true" ]; then
+    dbg "Running decisions usage scanner"
+    printf '%s' "$ASSISTANT_MSG" | node "$SCANNER" --cwd "$PROJECT_ROOT" 2>/dev/null || true
+  fi
+fi
+
+if [ "$MEMORY_ENABLED" != "true" ] && [ "$LEARNING_ENABLED" != "true" ]; then
+  dbg "EXIT: both features disabled"
+  exit 0
+fi
+
+# Logging (needs CWD and at-least-one-feature-enabled path — source after the
+# gate check so the log-paths subprocess overhead is only paid when needed)
+source "$SCRIPT_DIR/hook-log-init" "capture-turn"
+
+# Auto-create .devflow/ and ensure .gitignore entries
+source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
+
+source "$SCRIPT_DIR/get-mtime" || { echo "capture-turn: failed to source get-mtime" >&2; exit 1; }
+source "$SCRIPT_DIR/learning-lock" || { echo "capture-turn: failed to source learning-lock" >&2; exit 1; }
+
+mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
+
+TS=$(date +%s)
+queue_append_both \
+  "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+  "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
+  "assistant" "$ASSISTANT_MSG" "$TS"
+
+log "Captured assistant turn (${#ASSISTANT_MSG} chars)"
+dbg "=== HOOK COMPLETE ==="
+exit 0

package/src/assets/scripts/hooks/debug-trace

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Devflow Hook Debug Tracing
+# Source this file to get debug tracing helpers.
+#
+# Usage:
+#   dbg() { :; }                         # Safe no-op fallback before sourcing
+#   source "$SCRIPT_DIR/debug-trace" || true
+#   devflow_debug_init "hook-name"
+#   dbg "=== HOOK START ==="
+#   ...
+#   devflow_debug_set_cwd "$CWD"         # switches to per-project log
+#   dbg "CWD=$CWD"
+#
+# Toggle: DEVFLOW_HOOK_DEBUG=1 in ~/.claude/settings.json > env
+# Logs:   Phase 1 (pre-CWD)  → ~/.devflow/logs/.hook-debug.log
+#         Phase 2 (post-CWD) → ~/.devflow/logs/{project-slug}/.hook-debug.log
+
+_DEVFLOW_DBG_HOOK=""
+_DEVFLOW_DBG_LOG=""
+
+# _devflow_dbg_size_guard <log_file>
+# If the log file exceeds 5MB, truncate it to the tail 2.5MB to prevent
+# unbounded growth.  Uses `stat` to read the file size without forking `wc`.
+_devflow_dbg_size_guard() {
+  local log_file="$1"
+  [ -f "$log_file" ] || return 0
+  local size
+  # stat -f%z (macOS/BSD) with stat -c%s (GNU/Linux) fallback; last resort: wc -c
+  size=$(stat -f%z "$log_file" 2>/dev/null) \
+    || size=$(stat -c%s "$log_file" 2>/dev/null) \
+    || size=$(wc -c < "$log_file" 2>/dev/null) \
+    || size=0
+  if [ "${size:-0}" -gt 5242880 ]; then
+    local _TAIL_TMP="$log_file.tmp.$$"
+    if tail -c 2621440 "$log_file" > "$_TAIL_TMP" 2>/dev/null; then
+      mv "$_TAIL_TMP" "$log_file" 2>/dev/null || rm -f "$_TAIL_TMP" 2>/dev/null || true
+    else
+      rm -f "$_TAIL_TMP" 2>/dev/null || true
+    fi
+  fi
+}
+
+devflow_debug_init() {
+  _DEVFLOW_DBG_HOOK="${1:-hook}"
+  if [ "${DEVFLOW_HOOK_DEBUG:-}" != "1" ]; then
+    dbg() { :; }
+    return
+  fi
+  # Phase 1: global fallback log (before CWD is known)
+  local global_log_dir="$HOME/.devflow/logs"
+  mkdir -p "$global_log_dir" 2>/dev/null || true
+  chmod 700 "$global_log_dir" 2>/dev/null || true
+  _DEVFLOW_DBG_LOG="$global_log_dir/.hook-debug.log"
+  # Size guard: if log exceeds 5MB, keep the tail 2.5MB to prevent unbounded growth.
+  _devflow_dbg_size_guard "$_DEVFLOW_DBG_LOG"
+  dbg() {
+    echo "[$(date -u '+%Y-%m-%dT%H:%M:%SZ')] $_DEVFLOW_DBG_HOOK: $1" >> "$_DEVFLOW_DBG_LOG" 2>/dev/null || true
+  }
+}
+
+devflow_debug_set_cwd() {
+  local cwd="$1"
+  if [ -z "$cwd" ] || [ "${DEVFLOW_HOOK_DEBUG:-}" != "1" ]; then return; fi
+  # Phase 2: switch to per-project log (only when debug is active)
+  local slug
+  slug=$(echo "$cwd" | sed 's|^/||' | tr '/' '-')
+  local project_log_dir="$HOME/.devflow/logs/$slug"
+  mkdir -p "$project_log_dir" 2>/dev/null || true
+  chmod 700 "$project_log_dir" 2>/dev/null || true
+  _DEVFLOW_DBG_LOG="$project_log_dir/.hook-debug.log"
+  _devflow_dbg_size_guard "$_DEVFLOW_DBG_LOG"
+  dbg() {
+    echo "[$(date -u '+%Y-%m-%dT%H:%M:%SZ')] $_DEVFLOW_DBG_HOOK: $1" >> "$_DEVFLOW_DBG_LOG" 2>/dev/null || true
+  }
+}

package/src/assets/scripts/hooks/decisions-usage-scan.cjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+'use strict';
+
+// D29: Scanner runs after queue append, not before.
+// D19: Citation scanner is a separate .cjs module — independently testable.
+
+const fs = require('fs');
+const path = require('path');
+const { getMemoryDir, getDecisionsUsagePath, getDecisionsUsageLockDir } = require('./lib/project-paths.cjs');
+
+// Parse --cwd argument
+const cwdIdx = process.argv.indexOf('--cwd');
+const rawCwd = cwdIdx !== -1 && process.argv[cwdIdx + 1] ? process.argv[cwdIdx + 1] : null;
+if (!rawCwd) process.exit(0); // silent fail
+
+// Security: reject relative input BEFORE resolving (prevents CWE-23 path traversal).
+// path.resolve() unconditionally returns an absolute path, so checking isAbsolute *after*
+// resolving is a no-op. We must reject relative inputs first, then resolve to normalise
+// traversal sequences (e.g. /foo/../bar → /bar).
+// All legitimate callers (stop-hook) pass an absolute $CWD from bash.
+if (!path.isAbsolute(rawCwd)) {
+  console.error('cwd must be absolute, got:', rawCwd);
+  process.exit(2);
+}
+const cwd = path.resolve(rawCwd);
+
+const memoryDir = getMemoryDir(cwd);
+if (!fs.existsSync(memoryDir)) process.exit(0); // no .devflow/memory dir — nothing to scan
+
+// Read stdin synchronously
+let input = '';
+try {
+  input = fs.readFileSync(0, 'utf8'); // fd 0 = stdin
+} catch {
+  process.exit(0); // no stdin — nothing to scan
+}
+
+if (!input) process.exit(0);
+
+// Scan for ADR-NNN or PF-NNN citations
+const pattern = /(ADR|PF)-\d{3}/g;
+const matches = new Set();
+let match;
+while ((match = pattern.exec(input)) !== null) {
+  matches.add(match[0]);
+}
+
+if (matches.size === 0) process.exit(0);
+
+// Read usage file
+const usagePath = getDecisionsUsagePath(cwd);
+const lockDir = getDecisionsUsageLockDir(cwd);
+
+// Yield the current thread for the given number of milliseconds without spinning.
+// Atomics.wait on a freshly allocated SharedArrayBuffer never resolves (value never
+// changes), so it blocks the synchronous thread for exactly `ms` milliseconds with
+// zero CPU usage — unlike a busy-wait loop.
+function syncSleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// Simple mkdir-based lock with 2s timeout
+function acquireLock() {
+  const deadline = Date.now() + 2000;
+  while (Date.now() < deadline) {
+    try {
+      fs.mkdirSync(lockDir);
+      return true;
+    } catch (e) {
+      if (e.code !== 'EEXIST') return false;
+      // Check for stale lock (>5s old)
+      try {
+        const stat = fs.statSync(lockDir);
+        if (Date.now() - stat.mtimeMs > 5000) {
+          try { fs.rmdirSync(lockDir); } catch { /* race */ }
+        }
+      } catch { /* stat failed — retry */ }
+      // Yield for 10 ms instead of busy-spinning to avoid pegging the CPU.
+      syncSleep(10);
+    }
+  }
+  return false;
+}
+
+function releaseLock() {
+  try { fs.rmdirSync(lockDir); } catch { /* already released */ }
+}
+
+if (!acquireLock()) process.exit(0); // can't acquire lock — skip silently
+
+try {
+  let data = { version: 1, entries: {} };
+  try {
+    const raw = fs.readFileSync(usagePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && parsed.version === 1 && typeof parsed.entries === 'object') {
+      data = parsed;
+    }
+  } catch { /* ENOENT or malformed — use default */ }
+
+  const now = new Date().toISOString();
+  let changed = false;
+
+  for (const id of matches) {
+    // Only increment existing entries (D19: ignores unregistered IDs)
+    if (data.entries[id]) {
+      data.entries[id].cites = (data.entries[id].cites || 0) + 1;
+      data.entries[id].last_cited = now;
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    // PID-scope the tmp name so concurrent writers from different processes
+    // never collide on the same .tmp path.  mirrors fs-atomic.ts and proxy-log.ts.
+    const tmp = usagePath + '.tmp.' + process.pid;
+    const content = JSON.stringify(data, null, 2) + '\n';
+    // Use wx (O_EXCL) to reject any pre-existing file or symlink at the .tmp path,
+    // preventing TOCTOU symlink-follow attacks. On EEXIST, unlink and retry once.
+    try {
+      fs.writeFileSync(tmp, content, { flag: 'wx' });
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try { fs.unlinkSync(tmp); } catch { /* race — already removed */ }
+      fs.writeFileSync(tmp, content, { flag: 'wx' });
+    }
+    fs.renameSync(tmp, usagePath);
+  }
+} finally {
+  releaseLock();
+}

package/src/assets/scripts/hooks/ensure-devflow-init

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Ensures .devflow/ and all subdirectories exist and the project root .gitignore
+# ignores .devflow/. Called from capture-prompt, capture-turn, capture-question,
+# memory-worker, and pre-compact-memory. Idempotent.
+# Usage: source ensure-devflow-init "$CWD"
+
+[ -z "$1" ] && return 1
+
+# Anchor to the project root so a CWD nested inside .devflow/ never scaffolds a
+# stray nested .devflow/. Resolve our own dir via BASH_SOURCE (works whether sourced
+# by a hook or directly by tests). Empty → fall back to "$1" (old behavior).
+_EDI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$_EDI_DIR/resolve-project-root" 2>/dev/null || true
+_EDI_ROOT="$(df_resolve_root "$1" 2>/dev/null || true)"
+[ -n "$_EDI_ROOT" ] || _EDI_ROOT="$1"
+
+_DEVFLOW_DIR="$_EDI_ROOT/.devflow"
+
+# Fast-path: if all subdirectories already exist, skip mkdir and gitignore setup
+if [ -d "$_DEVFLOW_DIR/memory" ] && [ -d "$_DEVFLOW_DIR/docs" ] && \
+   [ -d "$_DEVFLOW_DIR/learning" ] && \
+   [ -d "$_DEVFLOW_DIR/features" ] && \
+   [ -f "$_DEVFLOW_DIR/.root-gitignore-configured-v2" ]; then
+  return 0
+fi
+
+# Create all subdirectories
+mkdir -p \
+  "$_DEVFLOW_DIR/memory" \
+  "$_DEVFLOW_DIR/learning" \
+  "$_DEVFLOW_DIR/features" \
+  "$_DEVFLOW_DIR/docs" \
+  2>/dev/null || return 1
+
+# One-time root .gitignore setup — delegated to the sibling ensure-root-gitignore
+# helper (single source of truth) so the always-on, memory-independent
+# session-start-context hook applies the identical rule. _EDI_DIR and _EDI_ROOT
+# were resolved at the top of this script.
+source "$_EDI_DIR/ensure-root-gitignore" "$_EDI_ROOT"