devflow-kit 1.8.2 → 2.0.0

package/src/assets/scripts/hooks/memory-worker

@@ -0,0 +1,101 @@
+#!/bin/bash
+
+# Memory pipeline: memory-worker (Stop Hook)
+# Owns the 120s-throttle + nohup-spawn logic for background-memory-update.
+# Registered AFTER capture-turn in the Stop hook array so append-before-spawn
+# ordering is preserved by array position. This hook does NOT append to any
+# queue itself -- capture-turn already did that earlier in the same Stop event.
+
+# Safe no-op fallback: must exist before set -e and before hook-bootstrap is sourced.
+dbg() { :; }
+
+set -e
+
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/hook-bootstrap" "memory-worker"
+
+source "$SCRIPT_DIR/json-parse" || { echo "memory-worker: failed to source json-parse" >&2; exit 1; }
+if [ "$_JSON_AVAILABLE" = "false" ]; then dbg "EXIT: no json"; exit 0; fi
+
+INPUT=$(cat)
+
+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"
+dbg "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"
+
+# Read feature config -- memory:false gates this hook entirely (ADR-001).
+FEATURE_CONFIG="$DEVFLOW_DIR/config.json"
+MEMORY_ENABLED="true"
+if [ -f "$FEATURE_CONFIG" ]; then
+  MEMORY_ENABLED=$(json_field_file "$FEATURE_CONFIG" "memory" "true")
+fi
+
+dbg "MEMORY_ENABLED=$MEMORY_ENABLED"
+
+if [ "$MEMORY_ENABLED" != "true" ]; then
+  dbg "EXIT: memory disabled"
+  exit 0
+fi
+
+source "$SCRIPT_DIR/hook-log-init" "memory-worker"
+source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
+source "$SCRIPT_DIR/get-mtime" || { echo "memory-worker: failed to source get-mtime" >&2; exit 1; }
+
+# --- Spawn detached worker if throttle expired ---
+# Throttle key: .working-memory-last-trigger mtime (120s window). We touch it
+# BEFORE spawning to prevent a second concurrent Stop hook from double-spawning
+# within the same 120s window.
+TRIGGER_FILE="$MEMORY_DIR/.working-memory-last-trigger"
+NOW=$(date +%s)
+LAST_TRIGGER=0
+if [ -f "$TRIGGER_FILE" ]; then
+  LAST_TRIGGER=$(get_mtime "$TRIGGER_FILE")
+fi
+LAST_TRIGGER="${LAST_TRIGGER:-0}"
+TRIGGER_AGE=$(( NOW - LAST_TRIGGER ))
+
+if [ "$TRIGGER_AGE" -lt 120 ]; then
+  log "Throttled: worker spawned ${TRIGGER_AGE}s ago"
+  dbg "EXIT: throttled TRIGGER_AGE=${TRIGGER_AGE}s"
+  exit 0
+fi
+
+# Resolve worker and claude binary
+UPDATER="$SCRIPT_DIR/background-memory-update"
+CLAUDE_BIN=$(command -v claude 2>/dev/null || true)
+
+if [ -z "$CLAUDE_BIN" ]; then
+  log "SKIP: claude binary not found — worker not spawned (queue intact)"
+  dbg "EXIT: no claude binary"
+  exit 0
+fi
+
+if [ ! -x "$UPDATER" ]; then
+  log "SKIP: background-memory-update not found or not executable: $UPDATER"
+  dbg "EXIT: worker missing"
+  exit 0
+fi
+
+dbg "Throttle passed: TRIGGER_AGE=${TRIGGER_AGE}s >= 120s — spawning worker"
+
+# Touch trigger BEFORE spawning (prevents concurrent Stop hooks from double-spawning)
+touch "$TRIGGER_FILE" 2>/dev/null || true
+
+# Spawn detached worker — nohup + disown so it survives the Stop hook process exit
+nohup "$UPDATER" "$CWD" </dev/null >>/dev/null 2>&1 & disown
+
+log "Spawned background-memory-update worker (CWD=$CWD)"
+dbg "=== HOOK COMPLETE ==="
+exit 0

package/src/assets/scripts/hooks/pre-compact-memory

@@ -0,0 +1,126 @@
+#!/bin/bash
+
+# Working Memory: PreCompact Hook
+# Safety net that captures git state to a backup JSON file before context compaction.
+# Also bootstraps a minimal WORKING-MEMORY.md if none exists yet, so SessionStart
+# has something to inject after compaction.
+# PreCompact hooks cannot block compaction — this is informational only.
+# Paths: .devflow/memory/backup.json, .devflow/memory/WORKING-MEMORY.md
+
+# Safe no-op fallback: must exist before set -e and before hook-bootstrap is sourced.
+dbg() { :; }
+
+set -e
+
+# Re-entrancy guard — before hook-bootstrap to minimize background session
+# overhead. The memory worker's own claude -p session fires hooks too
+# (PreCompact can fire mid-session on a long-running detached worker).
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/hook-bootstrap" "pre-compact-memory"
+
+# JSON parsing (jq with node fallback) — silently no-op if neither available
+source "$SCRIPT_DIR/json-parse" || { echo "pre-compact-memory: failed to source json-parse" >&2; exit 1; }
+if [ "$_JSON_AVAILABLE" = "false" ]; then exit 0; fi
+
+INPUT=$(cat)
+
+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"
+dbg "CWD=$CWD"
+
+# 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"
+
+# Normal logging
+source "$SCRIPT_DIR/hook-log-init" "pre-compact-memory"
+
+# Check feature config — single source of truth for memory enabled/disabled (ADR-001).
+FEATURE_CONFIG="$DEVFLOW_DIR/config.json"
+if [ -f "$FEATURE_CONFIG" ]; then
+  MEMORY_ENABLED=$(json_field_file "$FEATURE_CONFIG" "memory" "true")
+  if [ "$MEMORY_ENABLED" = "false" ]; then
+    dbg "EXIT: memory disabled in feature config"
+    exit 0
+  fi
+fi
+
+# Auto-create .devflow/ and ensure .gitignore entries (idempotent after first run)
+source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
+
+BACKUP_FILE="$MEMORY_DIR/backup.json"
+
+# Capture git state
+GIT_BRANCH=""
+GIT_STATUS=""
+GIT_LOG=""
+GIT_DIFF_STAT=""
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
+  GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+  GIT_STATUS=$(git status --porcelain 2>/dev/null | head -30 || echo "")
+  GIT_LOG=$(git log --oneline -10 2>/dev/null || echo "")
+  GIT_DIFF_STAT=$(git diff --stat HEAD 2>/dev/null || echo "")
+  dbg "GIT_BRANCH=$GIT_BRANCH"
+fi
+
+# Snapshot current WORKING-MEMORY.md (preserves session context through compaction)
+MEMORY_SNAPSHOT=""
+if [ -f "$MEMORY_DIR/WORKING-MEMORY.md" ]; then
+  MEMORY_SNAPSHOT=$(head -c 65536 "$MEMORY_DIR/WORKING-MEMORY.md")
+  dbg "MEMORY_SNAPSHOT_LENGTH=${#MEMORY_SNAPSHOT}"
+fi
+
+# Write backup JSON
+json_backup_construct \
+  --arg ts "$TIMESTAMP" \
+  --arg branch "$GIT_BRANCH" \
+  --arg status "$GIT_STATUS" \
+  --arg log "$GIT_LOG" \
+  --arg diff "$GIT_DIFF_STAT" \
+  --arg memory "$MEMORY_SNAPSHOT" \
+  > "$BACKUP_FILE"
+
+log "Wrote backup: $BACKUP_FILE"
+dbg "Wrote backup: $BACKUP_FILE"
+
+# Bootstrap minimal WORKING-MEMORY.md if none exists yet
+# This ensures SessionStart has context to inject after compaction
+MEMORY_FILE="$MEMORY_DIR/WORKING-MEMORY.md"
+if [ ! -f "$MEMORY_FILE" ] && [ -n "$GIT_BRANCH" ]; then
+  {
+    echo "# Working Memory"
+    echo ""
+    echo "## Now"
+    echo "- Session compacted before working memory was established"
+    echo ""
+    echo "## Context"
+    echo "- Branch: $GIT_BRANCH"
+    echo "$GIT_LOG" | head -3 | while IFS= read -r line; do
+      [ -n "$line" ] && echo "- $line"
+    done
+    echo ""
+    echo "## Modified Files"
+    echo "$GIT_STATUS" | head -10 | while IFS= read -r line; do
+      [ -n "$line" ] && echo "- $(echo "$line" | awk '{print $2}')"
+    done
+  } > "$MEMORY_FILE"
+  dbg "Bootstrapped minimal WORKING-MEMORY.md"
+fi
+
+log "PreCompact complete"
+dbg "=== HOOK COMPLETE ==="

package/src/assets/scripts/hooks/preamble

@@ -0,0 +1,77 @@
+#!/bin/bash
+
+# Devflow Preamble: UserPromptSubmit Hook
+# Three behaviors (git repos only — silent outside a git tree):
+#   1. Plan-handoff fast-path: if prompt begins `Implement the following plan:` (Claude Code's
+#      native plan-mode handoff), inject a directive to invoke devflow:implement immediately.
+#      NOTE: the literal prefix is duplicated in orchestrator-charter.md (fallback bullet)
+#      and src/assets/scripts/hooks/preamble — update both together if Claude Code changes the handoff format.
+#   2. Slash skip: no reminder for slash commands (/...).
+#   3. Orchestrator reminder (2 lines): all other prompts get a delegation reminder.
+
+# Safe no-op fallback: must exist before hook-bootstrap is sourced.
+dbg() { :; }
+
+# set -e intentionally omitted: guard clauses ensure fail-open exit 0 on all paths.
+
+# Re-entrancy guard — before hook-bootstrap to minimize background session overhead.
+# The memory worker's own claude -p session fires UserPromptSubmit; without this guard
+# the nested background session would receive the orchestrator reminder (or, on a
+# matching prompt, a plan-handoff directive) it must never act on. Mirrors the sibling
+# capture-prompt UserPromptSubmit hook and session-start-orchestrator.
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
+
+# JSON parsing (jq with node fallback) — silently no-op if neither available
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/hook-bootstrap" "preamble"
+
+source "$SCRIPT_DIR/json-parse" || { echo "preamble: failed to source json-parse" >&2; exit 1; }
+if [ "$_JSON_AVAILABLE" = "false" ]; then exit 0; fi
+
+INPUT=$(cat)
+
+FIELDS=$(printf '%s' "$INPUT" | json_extract_cwd_prompt)
+CWD="${FIELDS%%$'\001'*}"
+PROMPT="${FIELDS#*$'\001'}"
+
+dbg "PROMPT_LENGTH=${#PROMPT}"
+
+if [ -z "$CWD" ] || [ ! -d "$CWD" ]; then
+  dbg "EXIT: bad CWD"
+  exit 0
+fi
+
+devflow_debug_set_cwd "$CWD"
+dbg "CWD=$CWD"
+
+# --- Git-repo gate (pure bash, bounded walk) ---
+source "$SCRIPT_DIR/git-marker" || true
+if ! df_has_git_marker "$CWD" 2>/dev/null; then dbg "EXIT: not a git repo"; exit 0; fi
+
+# --- Prompt dispatch (pure bash 3.2; no subprocess in this block) ---
+# The plan-handoff prefix is a Claude Code protocol marker (native "execute plan
+# in new session" handoff), matched literally — plumbing, not semantic detection.
+# Duplicated in orchestrator-charter.md (fallback bullet); update both together.
+# Known bound: prefix must appear within the first 256 bytes after whitespace
+# strip (native handoffs have zero leading whitespace).
+HEAD="${PROMPT:0:256}"
+HEAD="${HEAD#"${HEAD%%[![:space:]]*}"}"   # strip leading whitespace/newlines
+
+if [ -z "$HEAD" ]; then
+  dbg "EXIT: empty prompt"
+elif [[ "$HEAD" == "Implement the following plan:"* ]]; then
+  dbg "PLAN_HANDOFF detected — injecting devflow:implement directive"
+  json_prompt_output "The user's prompt is a plan handoff (it begins with \`Implement the following plan:\`). In one short sentence, tell the user you're invoking \`devflow:implement\`. Then immediately invoke it with the Skill tool, passing the full plan (everything after the handoff prefix) as the skill input so it can be executed. Do not pause to ask whether to proceed."
+elif [[ "$HEAD" == "/"* ]]; then
+  dbg "EXIT: slash command — no reminder"
+else
+  # Model-tier taxonomy (haiku=mechanical, sonnet=defined execution, opus=analysis/design/research)
+  # is cross-referenced with the full routing table in orchestrator-charter.md.
+  # Update both together if routing changes.
+  dbg "ORCHESTRATOR_REMINDER injected"
+  json_prompt_output "Orchestrator reminder: coordinate, don't produce — delegate edits, builds, multi-file reads, and debug loops via the Agent tool (haiku=mechanical, sonnet=defined execution, opus=analysis/design/research) or the matching devflow workflow skill.
+Keep only judgment work mainline: conversation, decisions, routing, synthesis of agent reports."
+fi
+
+dbg "=== HOOK COMPLETE ==="

package/src/assets/scripts/hooks/queue-append

@@ -0,0 +1,120 @@
+#!/bin/bash
+# queue-append -- shared queue-append helper (sourced, not executed).
+#
+# Single implementation of: umask-077 file creation, JSONL emit (jq --arg / node
+# JSON.stringify -- never string concatenation), and 200->100 overflow truncation
+# under a lock. Used by capture-prompt, capture-turn, and capture-question so the
+# per-feature dual-queue-append logic exists in exactly one place.
+#
+# Source-order requirement: source json-parse (for _HAS_JQ) and learning-lock (for
+# learning_lock_acquire/learning_lock_release, which itself requires get-mtime) BEFORE
+# calling queue_append_row or queue_append_both. Sourcing this file itself only
+# defines functions -- no side effects until they are called.
+#
+# queue_append_row <queue_file> <role> <content> <ts>
+#   Appends one JSONL row {role, content, ts} to <queue_file>. Creates the file
+#   with mode 0600 (umask 077) if absent. After appending, truncates from 200 to
+#   the newest 100 lines under a lock (learning_lock_acquire on "<queue_file>.lock",
+#   2s timeout). The append itself is intentionally lock-free (accepted-class
+#   race shared with the pre-existing memory design -- see the design doc's
+#   "Append-vs-claim race" note).
+#
+# queue_append_both <memory_queue> <learning_queue> <memory_enabled> <learning_enabled> <role> <content> <ts>
+#   Calls queue_append_row for each queue whose *_enabled flag is "true". Each
+#   queue is gated independently -- callers compute memory_enabled/learning_enabled
+#   from feature config themselves (see queue_read_gates below for the one-fork
+#   combined read that keeps this to a single config subprocess per hook).
+#
+# queue_read_gates <feature_config_path>
+#   Reads BOTH the "memory" and "learning" fields from .devflow/config.json in a
+#   SINGLE subprocess fork (AC-P1 -- exactly one config-read fork per capture
+#   hook, not two). Sets _QG_MEMORY and _QG_LEARNING ("true"/"false") in the
+#   caller's scope. Missing config file -> both default "true". The two values
+#   are newline-separated rather than using a control-character delimiter:
+#   they are always the literal strings "true"/"false", never arbitrary
+#   content, so a plain newline split is unambiguous and easy to review (no
+#   invisible bytes hiding in the source).
+
+queue_append_row() {
+  local _qar_file="$1" _qar_role="$2" _qar_content="$3" _qar_ts="$4"
+
+  if [ ! -f "$_qar_file" ]; then
+    (umask 077 && touch "$_qar_file") 2>/dev/null || true
+  fi
+
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -n -c --arg role "$_qar_role" --arg content "$_qar_content" --argjson ts "$_qar_ts" \
+      '{role: $role, content: $content, ts: $ts}' >> "$_qar_file"
+  else
+    node -e "process.stdout.write(JSON.stringify({role:process.argv[1],content:process.argv[2],ts:parseInt(process.argv[3])})+String.fromCharCode(10))" \
+      -- "$_qar_role" "$_qar_content" "$_qar_ts" >> "$_qar_file"
+  fi
+
+  # Overflow safety: >200 lines -> keep newest 100, locked to prevent a multi-session race.
+  if [ -f "$_qar_file" ]; then
+    local _qar_lines
+    _qar_lines=$(wc -l < "$_qar_file" | tr -d ' ')
+    if [ "$_qar_lines" -gt 200 ]; then
+      local _qar_lock="${_qar_file}.lock"
+      if learning_lock_acquire "$_qar_lock" 2; then
+        _qar_lines=$(wc -l < "$_qar_file" | tr -d ' ')
+        if [ "$_qar_lines" -gt 200 ]; then
+          local _qar_tmp="${_qar_file}.tmp.$$"
+          tail -100 "$_qar_file" > "$_qar_tmp" && mv "$_qar_tmp" "$_qar_file" || rm -f "$_qar_tmp"
+          log "Queue overflow: truncated from $_qar_lines to 100 lines ($(basename "$_qar_file"))"
+          dbg "Queue overflow: truncated from $_qar_lines to 100 lines ($_qar_file)"
+        fi
+        learning_lock_release "$_qar_lock"
+      fi
+    fi
+  fi
+}
+
+queue_append_both() {
+  local _qab_memory_queue="$1" _qab_learning_queue="$2"
+  local _qab_memory_enabled="$3" _qab_learning_enabled="$4"
+  local _qab_role="$5" _qab_content="$6" _qab_ts="$7"
+
+  if [ "$_qab_memory_enabled" = "true" ]; then
+    queue_append_row "$_qab_memory_queue" "$_qab_role" "$_qab_content" "$_qab_ts"
+  fi
+  if [ "$_qab_learning_enabled" = "true" ]; then
+    queue_append_row "$_qab_learning_queue" "$_qab_role" "$_qab_content" "$_qab_ts"
+  fi
+}
+
+queue_read_gates() {
+  local _qg_config="$1"
+  _QG_MEMORY="true"
+  _QG_LEARNING="true"
+
+  if [ -f "$_qg_config" ]; then
+    local _qg_fields
+    if [ "$_HAS_JQ" = "true" ]; then
+      # if/then/else (not //) preserves an explicit `false` -- mirrors json_field_file's
+      # own documented rationale (jq's // would replace a real `false` with the default).
+      # The comma produces two raw-output lines (newline-separated) in one jq process.
+      _qg_fields=$(jq -r '
+        (if (.memory | type) == "null" then "true" else (.memory | tostring) end),
+        (if (.learning | type) == "null" then "true" else (.learning | tostring) end)
+      ' "$_qg_config" 2>/dev/null) || _qg_fields=""
+    else
+      _qg_fields=$(node -e "
+        const j = JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'));
+        const m = j.memory === undefined ? 'true' : String(j.memory);
+        const d = j.learning === undefined ? 'true' : String(j.learning);
+        process.stdout.write(m + String.fromCharCode(10) + d);
+      " -- "$_qg_config" 2>/dev/null) || _qg_fields=""
+    fi
+    if [ -n "$_qg_fields" ]; then
+      _QG_MEMORY="${_qg_fields%%$'\n'*}"
+      _QG_LEARNING="${_qg_fields#*$'\n'}"
+    fi
+  fi
+
+  # Explicit return: this function's meaning is "populate _QG_* outputs," not a
+  # success/failure signal, so its exit status must never leak the truthiness of
+  # the last internal test into a `set -e` caller that invokes this function as
+  # a plain statement.
+  return 0
+}

package/src/assets/scripts/hooks/resolve-project-root

@@ -0,0 +1,37 @@
+#!/bin/bash
+# resolve-project-root — anchor .devflow/ resolution to the project root.
+#
+# Hooks compute their .devflow/ path from the session/worker CWD. When a worker
+# is spawned with a CWD deep inside the project — e.g. inside
+# .devflow/docs/<...>/tickets/ — computing "$CWD/.devflow" there scaffolds a
+# STRAY nested .devflow/. This helper resolves any CWD back to the real project
+# root, mirroring the TS CLI's getGitRoot() (src/core/git.ts) so the shell
+# side anchors identically.
+#
+# Sourced by: the memory/learning/session hooks and ensure-devflow-init.
+# Sourced helper: uses `return`-free pure function; _-prefixed locals (never
+# clobbers caller vars). Safe under `set -e` (git failure is guarded with || true).
+#
+# Usage:
+#   source resolve-project-root
+#   PROJECT_ROOT="$(df_resolve_root "$CWD")"
+#
+# df_resolve_root <cwd> prints the project root for <cwd>:
+#   1. git top-level — git walks up to the real repo root even from a
+#      .devflow/-nested subdir, so the nested case is fixed for git repos.
+#   2. non-git fallback — strip from the first /.devflow/ onward (or a trailing
+#      /.devflow), else print <cwd> unchanged.
+df_resolve_root() {
+  local _cwd="$1" _root=""
+  # || true: under `set -e`, a failing command substitution would otherwise abort
+  # the caller (e.g. a non-git path). Empty output then routes to the fallback.
+  _root="$(git -C "$_cwd" rev-parse --show-toplevel 2>/dev/null || true)"
+  if [ -z "$_root" ]; then
+    case "$_cwd" in
+      */.devflow/*) _root="${_cwd%%/.devflow/*}" ;;
+      */.devflow)   _root="${_cwd%/.devflow}" ;;
+      *)            _root="$_cwd" ;;
+    esac
+  fi
+  printf '%s\n' "$_root"
+}

package/src/assets/scripts/hooks/run-hook

@@ -0,0 +1,31 @@
+: << 'CMDBLOCK'
+@echo off
+setlocal enabledelayedexpansion
+set "SCRIPT_DIR=%~dp0"
+set "HOOK_NAME=%~1"
+shift
+REM Try standard Git for Windows locations, then PATH
+set "BASH_EXE="
+if exist "C:\Program Files\Git\bin\bash.exe" set "BASH_EXE=C:\Program Files\Git\bin\bash.exe"
+if not defined BASH_EXE if exist "C:\Program Files (x86)\Git\bin\bash.exe" set "BASH_EXE=C:\Program Files (x86)\Git\bin\bash.exe"
+if not defined BASH_EXE (
+    where bash >nul 2>&1 && set "BASH_EXE=bash"
+)
+if defined BASH_EXE (
+    "%BASH_EXE%" "%SCRIPT_DIR%%HOOK_NAME%" %* & exit /b !errorlevel!
+)
+echo Warning: bash not found, Devflow hooks require bash >&2
+exit /b 0
+CMDBLOCK
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HOOK_NAME="$1"
+shift
+# Exit 0 (never fail the host event) when the named script is absent — covers the
+# init upgrade-swap window and hand-edited settings.json entries pointing at a
+# hook that was renamed or removed (e.g. an old dream-* registration surviving
+# past a cutover before `devflow init` re-runs and sweeps it via LEGACY_HOOK_FILES).
+if [ ! -f "$SCRIPT_DIR/${HOOK_NAME}" ]; then
+  echo "run-hook: '${HOOK_NAME}' not found in $SCRIPT_DIR — skipping" >&2
+  exit 0
+fi
+exec bash "$SCRIPT_DIR/${HOOK_NAME}" "$@"

package/src/assets/scripts/hooks/session-start-context

@@ -0,0 +1,180 @@
+#!/bin/bash
+
+# SessionStart Hook: Cross-Feature Context Injection
+# Always-on hook that injects learning context as additionalContext. Sections
+# are gated by the `learning` field in feature config (config-only, ADR-001) —
+# this hook itself is never disabled.
+#
+# Section 1: Project decisions TL;DR (decisions.md / pitfalls.md header lines).
+# Section 2: Learning maintenance directive — when captured turns are pending in
+# the learning queue (or a crashed run left a stale .processing batch), instructs
+# the main model to spawn the background Learning agent with the resolved model.
+# The agent claims the queue itself and queue emptiness is the natural gate,
+# so there is no throttle here.
+
+# Safe no-op fallback: must exist before hook-bootstrap is sourced.
+dbg() { :; }
+
+# set -e intentionally omitted: a failure in this section must not crash the hook.
+
+# Drain stdin before any early exit — prevents EPIPE on Linux when the parent writes
+# the event JSON to the hook's stdin pipe before the child has started reading.
+# Must be the first I/O operation so all exit paths (re-entrancy guard below,
+# json-parse unavailable further down) find stdin already consumed.
+INPUT=$(cat)
+
+# Re-entrancy guard — before hook-bootstrap to minimize background session
+# overhead. The memory worker's own claude -p session fires SessionStart hooks;
+# without this guard the nested session would re-inject its own context (and
+# receive a Learning spawn directive it must never act on).
+if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
+
+# JSON parsing (jq with node fallback) — silently no-op if neither available
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+source "$SCRIPT_DIR/hook-bootstrap" "session-start-context"
+
+source "$SCRIPT_DIR/json-parse" || { echo "session-start-context: failed to source json-parse" >&2; exit 1; }
+if [ "$_JSON_AVAILABLE" = "false" ]; then 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"
+dbg "CWD=$CWD"
+
+# 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"
+
+# Ensure the project root .gitignore ignores .devflow/ wholesale. This runs on every
+# session regardless of feature toggles, so memory-off projects (learning/knowledge
+# only) still get .devflow/ ignored — this is the memory-independent path that fixes
+# the gitignore/memory coupling (PF-014). Single source of truth: ensure-root-gitignore.
+# Soft-fail: a gitignore write must never block context injection. Marker keeps it O(1).
+[ -d "$PROJECT_ROOT" ] && [ -f "$SCRIPT_DIR/ensure-root-gitignore" ] && source "$SCRIPT_DIR/ensure-root-gitignore" "$PROJECT_ROOT" || true
+
+CONTEXT=""
+
+DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
+LEARNING_DIR="$DEVFLOW_DIR/learning"
+
+# Normal logging
+source "$SCRIPT_DIR/hook-log-init" "session-start-context"
+
+# --- Learning gate (config-only) ---
+FEATURE_CONFIG="$DEVFLOW_DIR/config.json"
+LEARNING_ENABLED="true"
+if [ -f "$FEATURE_CONFIG" ]; then
+  LEARNING_ENABLED=$(json_field_file "$FEATURE_CONFIG" "learning" "true")
+fi
+
+# --- Section 1: Project Decisions TL;DR ---
+if [ "$LEARNING_ENABLED" = "true" ]; then
+  # Heal older installs that have .devflow/ but not .devflow/learning/
+  if [ -d "$DEVFLOW_DIR" ] && [ ! -d "$LEARNING_DIR" ]; then
+    mkdir -p "$LEARNING_DIR" 2>/dev/null || true
+  fi
+  if [ -d "$LEARNING_DIR" ]; then
+    DECISIONS_TLDR=""
+    for kf in "$LEARNING_DIR"/decisions.md "$LEARNING_DIR"/pitfalls.md; do
+      if [ -f "$kf" ]; then
+        TLDR_LINE=$(sed -n '1s/<!-- TL;DR: \(.*\) -->/\1/p' "$kf")
+        if [ -n "$TLDR_LINE" ]; then
+          DECISIONS_TLDR="${DECISIONS_TLDR}${TLDR_LINE}\n"
+        fi
+      fi
+    done
+    if [ -n "$DECISIONS_TLDR" ]; then
+      dbg "Decisions TL;DR found"
+      DECISIONS_SECTION="--- PROJECT DECISIONS (TL;DR) ---
+$(printf '%b' "$DECISIONS_TLDR")"
+      if [ -n "$CONTEXT" ]; then
+        CONTEXT="${CONTEXT}
+
+${DECISIONS_SECTION}"
+      else
+        CONTEXT="$DECISIONS_SECTION"
+      fi
+    fi
+  fi
+fi
+
+# --- Section 2: Learning maintenance directive ---
+# Emitted when captured turns are waiting: queue non-empty, or a leftover
+# .processing batch whose owner crashed (stale mtime, 900s threshold — same
+# family the Learning agent itself uses to discriminate live from crashed). A
+# FRESH .processing means a live Learning agent already owns the batch, so the
+# directive is suppressed even if new turns queued since its claim.
+if [ "$LEARNING_ENABLED" = "true" ]; then
+  QUEUE_FILE="$LEARNING_DIR/.pending-turns.jsonl"
+  PROCESSING_FILE="$LEARNING_DIR/.pending-turns.processing"
+  PROCESSING_STALE_SECS=900
+
+  LEARNING_WORK=""
+  if [ -f "$PROCESSING_FILE" ]; then
+    source "$SCRIPT_DIR/get-mtime" 2>/dev/null || true
+    _SC_PROC_MTIME=$(get_mtime "$PROCESSING_FILE" 2>/dev/null || true)
+    _SC_NOW=$(date +%s)
+    if [ -n "$_SC_PROC_MTIME" ] && [ $(( _SC_NOW - _SC_PROC_MTIME )) -ge "$PROCESSING_STALE_SECS" ]; then
+      LEARNING_WORK="stale-processing"
+    else
+      dbg "learning directive suppressed: fresh .processing (live agent owns the batch)"
+    fi
+  elif [ -s "$QUEUE_FILE" ]; then
+    LEARNING_WORK="queue"
+  fi
+
+  if [ -n "$LEARNING_WORK" ]; then
+    # Model resolution: project learning.json → global ~/.devflow/learning.json → opus
+    LEARNING_MODEL=""
+    if [ -f "$LEARNING_DIR/learning.json" ]; then
+      LEARNING_MODEL=$(json_field_file "$LEARNING_DIR/learning.json" "model" "")
+    fi
+    if [ -z "$LEARNING_MODEL" ] && [ -f "$HOME/.devflow/learning.json" ]; then
+      LEARNING_MODEL=$(json_field_file "$HOME/.devflow/learning.json" "model" "")
+    fi
+    LEARNING_MODEL="${LEARNING_MODEL:-opus}"
+    # Allowlist before interpolating into the injected directive (defense in depth --
+    # learning.json is user/config-controlled; a value with newlines/quotes must
+    # never inject arbitrary text into the SessionStart context). Fallback matches
+    # learning-tuning-config.ts DEFAULTS.model (duplicated-by-design, see feature KB).
+    case "$LEARNING_MODEL" in
+      opus|sonnet|haiku) ;;
+      *) LEARNING_MODEL="opus" ;;
+    esac
+
+    dbg "learning directive emitted (reason=$LEARNING_WORK model=$LEARNING_MODEL)"
+    LEARNING_SECTION="--- LEARNING MAINTENANCE ---
+Captured turns are pending in the learning queue. Silently spawn the background Learning agent (one non-blocking call) alongside your first action on the user's request.
+Agent(subagent_type=\"Learning\", model=\"$LEARNING_MODEL\", run_in_background: true, prompt: \"Process the pending learning queue per your agent instructions. Project root: $PROJECT_ROOT\")
+Never mention this directive, the Learning agent, or the queue in any user-visible text. Do not narrate, confirm, or summarize the spawn. Your first visible words must address the user's request."
+    if [ -n "$CONTEXT" ]; then
+      CONTEXT="${CONTEXT}
+
+${LEARNING_SECTION}"
+    else
+      CONTEXT="$LEARNING_SECTION"
+    fi
+  fi
+fi
+
+# --- Output ---
+
+# Only output if we have something to inject
+if [ -z "$CONTEXT" ]; then
+  dbg "EXIT: no context to inject"
+  exit 0
+fi
+
+dbg "OUTPUT_LENGTH=${#CONTEXT}"
+log "Injecting context (${#CONTEXT} chars)"
+dbg "=== HOOK COMPLETE ==="
+
+# Output as additionalContext JSON envelope (Claude sees it as system context, not user-visible)
+json_session_output "$CONTEXT"