devflow-kit 3.1.0 → 3.2.0

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

@@ -8,21 +8,28 @@
 #
 # 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
+# calling queue_append_row or queue_append_both, and define log/dbg. This file
+# sources its sibling git-marker itself, for df_no_symlink_below. Sourcing it 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_row <root> <queue_file> <role> <content> <ts>
+#   Appends one JSONL row {role, content, ts} to <queue_file>, which lies below
+#   <root>: the project root for the memory queue, the ledger root for the learning
+#   queue. When the queue, or a folder between <root> and it, is a symbolic link,
+#   nothing is written: the skip is logged once and the call returns 0, as a
+#   skipped capture does (D-HOOKS-NO-SYMLINK, git-marker). Otherwise it
+#   creates the queue's folder if absent, and the file with mode 0600 (umask 077).
+#   After appending, truncates from 200 to the newest 100 lines under a lock
+#   (learning_lock_acquire on "<queue_file>.lock", 2s timeout), keeping mode 0600.
+#   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
-#   themselves (see queue_read_gates below for the at-most-one-fork read of both).
+# queue_append_both <memory_root> <memory_queue> <learning_root> <learning_queue> <memory_enabled> <learning_enabled> <role> <content> <ts>
+#   Calls queue_append_row for each queue whose *_enabled flag is "true", with the
+#   root that queue lies below. Each queue is gated independently -- callers
+#   compute memory_enabled/learning_enabled themselves (see queue_read_gates below
+#   for the at-most-one-fork read of both).
 #
 # queue_read_gates <manifest_path> [<root>]
 #   Reads BOTH switches, `memory` and `learning`, in at most ONE subprocess fork
@@ -72,8 +79,20 @@
 #   root (D-ONE-HOME); memory-worker hands its resolved path to the background
 #   worker it spawns.
 
+# queue_append_row checks its queue with df_no_symlink_below, so this helper sources
+# git-marker itself rather than trusting every caller to have done so first. One that
+# failed to source is a command not found: the refusing branch, so nothing is written.
+source "${BASH_SOURCE[0]%/*}/git-marker" 2>/dev/null || true
+
 queue_append_row() {
-  local _qar_file="$1" _qar_role="$2" _qar_content="$3" _qar_ts="$4"
+  local _qar_root="$1" _qar_file="$2" _qar_role="$3" _qar_content="$4" _qar_ts="$5"
+
+  # D-HOOKS-NO-SYMLINK (git-marker): a skipped append is a skipped capture.
+  if ! df_no_symlink_below "$_qar_root" "$_qar_file"; then
+    log "Queue skipped: a symbolic link sits on the path to $_qar_file; nothing written"
+    return 0
+  fi
+  mkdir -p "${_qar_file%/*}" 2>/dev/null || true
 
   if [ ! -f "$_qar_file" ]; then
     (umask 077 && touch "$_qar_file") 2>/dev/null || true
@@ -97,9 +116,21 @@ queue_append_row() {
         _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)"
+          # SEC-2: the trimmed copy is created under umask 077, so the renamed
+          # queue keeps mode 0600. mv replaces the inode, so the queue takes the
+          # copy's mode, and a chmod after the mv would leave a window. The copy is
+          # created only where nothing stands at its name: builtin tests come first,
+          # so an entry already there, a link to a FIFO or a device included, is
+          # never opened (noclobber alone would open one, as no regular file stands
+          # there), and noclobber then makes the create itself exclusive. Such an
+          # entry is removed instead, and the trim waits for a later append.
+          if [ ! -e "$_qar_tmp" ] && [ ! -L "$_qar_tmp" ] && (umask 077 && set -o noclobber && tail -100 "$_qar_file" > "$_qar_tmp") && mv "$_qar_tmp" "$_qar_file"; then
+            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)"
+          else
+            rm -f "$_qar_tmp" 2>/dev/null || true
+            log "Queue overflow: not truncated, its copy could not be written ($(basename "$_qar_file"))"
+          fi
         fi
         learning_lock_release "$_qar_lock"
       fi
@@ -108,15 +139,16 @@ queue_append_row() {
 }
 
 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"
+  local _qab_memory_root="$1" _qab_memory_queue="$2"
+  local _qab_learning_root="$3" _qab_learning_queue="$4"
+  local _qab_memory_enabled="$5" _qab_learning_enabled="$6"
+  local _qab_role="$7" _qab_content="$8" _qab_ts="$9"
 
   if [ "$_qab_memory_enabled" = "true" ]; then
-    queue_append_row "$_qab_memory_queue" "$_qab_role" "$_qab_content" "$_qab_ts"
+    queue_append_row "$_qab_memory_root" "$_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"
+    queue_append_row "$_qab_learning_root" "$_qab_learning_queue" "$_qab_role" "$_qab_content" "$_qab_ts"
   fi
 }
 

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

@@ -58,6 +58,11 @@ fi
 devflow_debug_set_cwd "$CWD"
 dbg "CWD=$CWD"
 
+# Normal logging, set up before the carve-out below: its skips, and those of the
+# ensure-root-gitignore it sources, are written with log(), and with memory and
+# learning both off this hook is the only one that reaches the carve-out.
+source "$SCRIPT_DIR/hook-log-init" "session-start-context"
+
 # Anchor .devflow/ to the project root (prevents a stray nested .devflow/ when this
 # hook runs with a CWD inside .devflow/...). One git call yields both roots
 # (resolve-project-root): PROJECT_ROOT is this checkout's toplevel, LEDGER_ROOT the
@@ -88,8 +93,16 @@ fi
 # (learning/knowledge only) still get .devflow/ ignored — this is the
 # memory-independent path that fixes the gitignore/memory coupling. Single
 # source of truth: ensure-root-gitignore. Soft-fail: a gitignore write must never
-# block context injection. Marker keeps it O(1).
-[ -n "$PROJECT_OK" ] && [ -d "$PROJECT_ROOT" ] && [ -f "$SCRIPT_DIR/ensure-root-gitignore" ] && source "$SCRIPT_DIR/ensure-root-gitignore" "$PROJECT_ROOT" || true
+# block context injection. Marker keeps it O(1). A `.devflow` that is a symbolic
+# link is skipped, since the marker would land in the folder the link names, and
+# the skip is logged once (D-HOOKS-NO-SYMLINK, git-marker).
+if [ -n "$PROJECT_OK" ] && [ -d "$PROJECT_ROOT" ] && [ -f "$SCRIPT_DIR/ensure-root-gitignore" ]; then
+  if df_no_symlink_below "$PROJECT_ROOT" "$PROJECT_ROOT/.devflow"; then
+    source "$SCRIPT_DIR/ensure-root-gitignore" "$PROJECT_ROOT" || true
+  else
+    log "Skipped: $PROJECT_ROOT/.devflow is a symbolic link; nothing written under it"
+  fi
+fi
 
 CONTEXT=""
 
@@ -180,9 +193,6 @@ PROJECT_DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
 LEDGER_DEVFLOW_DIR="$LEDGER_ROOT/.devflow"
 LEARNING_DIR="$LEDGER_DEVFLOW_DIR/learning"
 
-# Normal logging
-source "$SCRIPT_DIR/hook-log-init" "session-start-context"
-
 # --- Learning gate: the machine switch, narrowed by this checkout ---
 # D-FEATURES-NARROW-ONLY (see queue-append): ~/.devflow/manifest.json's
 # features.learning, narrowed by PROJECT_ROOT's project.json / config.json, is
@@ -199,14 +209,23 @@ LEARNING_ENABLED="$_QG_LEARNING"
 
 # --- Section 1: Project Decisions TL;DR ---
 if [ "$LEARNING_ENABLED" = "true" ]; then
-  # Heal older installs that have .devflow/ but not .devflow/learning/
+  # Heal older installs that have .devflow/ but not .devflow/learning/, never
+  # through a symbolic link (D-HOOKS-NO-SYMLINK, git-marker).
   if [ -d "$LEDGER_DEVFLOW_DIR" ] && [ ! -d "$LEARNING_DIR" ]; then
-    mkdir -p "$LEARNING_DIR" 2>/dev/null || true
+    if df_no_symlink_below "$LEDGER_ROOT" "$LEARNING_DIR"; then
+      mkdir -p "$LEARNING_DIR" 2>/dev/null || true
+    else
+      log "Skipped: a symbolic link sits on the path to $LEARNING_DIR; nothing written"
+    fi
   fi
   if [ -d "$LEARNING_DIR" ]; then
+    # D-HOOKS-NO-SYMLINK (git-marker): this section and the next read the learning
+    # files into the context, or name them to the model and the Learning agent, so
+    # each is read only where no symbolic link sits on its path; a file a link leads
+    # to is treated as absent, and its refusal logged once.
     DECISIONS_TLDR=""
     for kf in "$LEARNING_DIR"/decisions.md "$LEARNING_DIR"/pitfalls.md; do
-      if [ -f "$kf" ]; then
+      if df_file_below "$LEDGER_ROOT" "$kf"; then
         TLDR_LINE=$(sed -n '1s/<!-- TL;DR: \(.*\) -->/\1/p' "$kf")
         if [ -n "$TLDR_LINE" ]; then
           DECISIONS_TLDR="${DECISIONS_TLDR}${TLDR_LINE}\n"
@@ -216,9 +235,11 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
     # The index line names the decisions index, so the main model can pass it on
     # as DECISIONS_CONTEXT. It interpolates $LEDGER_ROOT, so it needs that root's
     # shape gate, and it is left out when the index lists no entry: an empty
-    # corpus renders `(none)`. Builtins only — no fork on any path.
+    # corpus renders `(none)`. It is left out too when a link leads to the index,
+    # since the model would read the file the link names and pass that on.
+    # Builtins only: no fork, save the log line of a refused index.
     _SC_INDEX="$LEARNING_DIR/index.md"; DECISIONS_INDEX_LINE=""
-    if [ -n "$DIRECTIVE_LEDGER_SAFE" ] && [ -s "$_SC_INDEX" ]; then
+    if [ -n "$DIRECTIVE_LEDGER_SAFE" ] && df_file_below "$LEDGER_ROOT" "$_SC_INDEX" && [ -s "$_SC_INDEX" ]; then
       _SC_IDX1=""; IFS= read -r _SC_IDX1 < "$_SC_INDEX" || true
       [ "$_SC_IDX1" != "(none)" ] && DECISIONS_INDEX_LINE="Index: $_SC_INDEX"
     fi
@@ -259,8 +280,10 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
   PROCESSING_FILE="$LEARNING_DIR/.pending-turns.processing"
   PROCESSING_STALE_SECS=900
 
+  # The queue and the batch are what the directive sends the Learning agent to, so
+  # one a symbolic link leads to counts as absent (D-HOOKS-NO-SYMLINK, Section 1).
   LEARNING_WORK=""
-  if [ -f "$PROCESSING_FILE" ]; then
+  if df_file_below "$LEDGER_ROOT" "$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)
@@ -269,7 +292,7 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
     else
       dbg "learning directive suppressed: fresh .processing (live agent owns the batch)"
     fi
-  elif [ -s "$QUEUE_FILE" ]; then
+  elif df_file_below "$LEDGER_ROOT" "$QUEUE_FILE" && [ -s "$QUEUE_FILE" ]; then
     LEARNING_WORK="queue"
   fi
 
@@ -293,28 +316,83 @@ ${LEARNING_PAUSED_SECTION}"
   fi
 
   if [ -n "$LEARNING_WORK" ]; then
-    # Model resolution: project learning.json → global ~/.devflow/learning.json → opus
+    # D-LEARNING-MODEL-PRECEDENCE — the model of the spawn. The first layer that
+    # supplies a model decides:
+    #   1. a valid project learning.json "model"                      -> model="<value>"
+    #   2. agents.learning.model in $HOME/.devflow/agent-models.json,
+    #      the `devflow agents` Learning mapping                      -> no model=
+    #   3. a valid $HOME/.devflow/learning.json "model"               -> model="<value>"
+    #   4. none                                                       -> no model=
+    # With no model= the spawn takes the model of the installed Learning agent's
+    # frontmatter, which is where a `devflow agents` mapping is applied, so the
+    # mapping reaches the spawn. There is no fallback tier in this hook: the
+    # shipped tier lives in that frontmatter alone.
+    #
+    # Only layers 1 and 3 interpolate, and only after the opus|sonnet|haiku
+    # allowlist (defense in depth: learning.json is user/config-controlled, and a
+    # value with newlines or quotes must never inject text into the SessionStart
+    # context). Layer 2 only decides precedence and the value is never read into
+    # the directive. It counts only when agents.learning.model is a JSON STRING
+    # that is a model name by the rule readAgentMapping (src/core/agent-models.ts)
+    # keeps a model by, MODEL_NAME_RE in src/core/agent-frontmatter.ts:
+    # ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. Anything readAgentMapping drops, a number,
+    # boolean, object, array, empty or out-of-charset string, is a mapping that
+    # supplies no model: the installed frontmatter keeps the shipped tier, so the
+    # layer reads as absent and the lookup falls through to the global file rather
+    # than silently ignoring it for a model nothing will run. The type is read by
+    # json_string_field_file, which keeps the number 42 apart from the string "42"
+    # on both the jq and the node backend. An entry with an effort alone supplies
+    # no model either, so it does not displace a global learning.json. An invalid
+    # layer-1 or layer-3 value counts as absent and falls through. A missing,
+    # unreadable or malformed agent-models.json reads as empty (the typed read
+    # discards its errors), so the mapping layer is absent. A dormant external
+    # mapping model, any name of that charset, still decides: its model is inactive
+    # while the proxy is off and the shipped tier runs, but this hook does not know
+    # the proxy state.
+    # A project learning.json a symbolic link leads to is absent (D-HOOKS-NO-SYMLINK).
+    # The machine root is $HOME/.devflow and nothing relocates it.
     LEARNING_MODEL=""
-    if [ -f "$LEARNING_DIR/learning.json" ]; then
-      LEARNING_MODEL=$(json_field_file "$LEARNING_DIR/learning.json" "model" "")
+    LEARNING_MODEL_LAYER=""
+    if df_file_below "$LEDGER_ROOT" "$LEARNING_DIR/learning.json"; then
+      _SC_LM=$(json_field_file "$LEARNING_DIR/learning.json" "model" "")
+      case "$_SC_LM" in
+        opus|sonnet|haiku) LEARNING_MODEL="$_SC_LM"; LEARNING_MODEL_LAYER="project" ;;
+      esac
     fi
-    if [ -z "$LEARNING_MODEL" ] && [ -f "$HOME/.devflow/learning.json" ]; then
-      LEARNING_MODEL=$(json_field_file "$HOME/.devflow/learning.json" "model" "")
+    if [ -z "$LEARNING_MODEL_LAYER" ] && [ -f "$HOME/.devflow/agent-models.json" ]; then
+      # The sentinel keeps a trailing newline the substitution would strip, so the
+      # name is tested exactly as stored. The first character is a letter or digit,
+      # the rest add . _ -, and the whole is 64 characters at most. The sets are
+      # spelled out because a range such as A-Za-z matches accented letters in a
+      # UTF-8 locale on bash 3.2.
+      _SC_LM=$(json_string_field_file "$HOME/.devflow/agent-models.json" "agents.learning.model"; printf x)
+      _SC_LM=${_SC_LM%x}
+      _SC_NAME_HEAD='ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
+      _SC_NAME_TAIL="${_SC_NAME_HEAD}._-"
+      case "$_SC_LM" in
+        ''|[!$_SC_NAME_HEAD]*|*[!$_SC_NAME_TAIL]*) ;;
+        *)
+          if [ "${#_SC_LM}" -le 64 ]; then
+            LEARNING_MODEL_LAYER="mapping"
+          fi
+          ;;
+      esac
+    fi
+    if [ -z "$LEARNING_MODEL_LAYER" ] && [ -f "$HOME/.devflow/learning.json" ]; then
+      _SC_LM=$(json_field_file "$HOME/.devflow/learning.json" "model" "")
+      case "$_SC_LM" in
+        opus|sonnet|haiku) LEARNING_MODEL="$_SC_LM"; LEARNING_MODEL_LAYER="global" ;;
+      esac
+    fi
+    LEARNING_MODEL_ARG=""
+    if [ -n "$LEARNING_MODEL" ]; then
+      LEARNING_MODEL_ARG=" model=\"$LEARNING_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)"
+    dbg "learning directive emitted (reason=$LEARNING_WORK model=${LEARNING_MODEL:-frontmatter} layer=${LEARNING_MODEL_LAYER:-none})"
     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: $LEDGER_ROOT\")
+Agent(subagent_type=\"Learning\",${LEARNING_MODEL_ARG} run_in_background: true, prompt: \"Process the pending learning queue per your agent instructions. Project root: $LEDGER_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}
@@ -629,7 +707,8 @@ if [ -n "$TRACKER_PROVIDER" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
     # assertion of the closed domain rather than a sanitiser, and it is the single
     # place the tier is validated, so a later config read cannot be wired in
     # without passing through it. The literal must equal the Tracker agent's
-    # frontmatter `model:` (pinned against loadShippedDefaults in shell-hooks).
+    # frontmatter `model:` (pinned against loadShippedAgentDefaults()['tracker'].model
+    # in shell-hooks-tracker).
     TRACKER_MODEL="sonnet"
     case "$TRACKER_MODEL" in
       opus|sonnet|haiku) ;;

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

@@ -70,7 +70,11 @@ fi
 # re-spawns (memory disabled mid-flight, host offline, etc.): a SessionStart
 # arriving >300s after the crash with no intervening Stop hook.
 # Non-clobber: only recovers when .pending-turns.jsonl does NOT already exist,
-# so a concurrent session's fresh queue is never overwritten.
+# so a concurrent session's fresh queue is never overwritten. Nor where a
+# symbolic link sits on the path to the batch or to the queue it is renamed onto
+# (D-HOOKS-NO-SYMLINK, git-marker): `mv` would move the batch into a folder a
+# linked memory folder or queue path names, and a linked batch would become a
+# linked queue.
 source "$SCRIPT_DIR/get-mtime" || { echo "session-start-memory: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/is-hex-sha" || { echo "session-start-memory: failed to source is-hex-sha" >&2; exit 1; }
 _SSM_PT_PROC="$MEMORY_DIR/.pending-turns.processing"
@@ -81,7 +85,10 @@ if [ -f "$_SSM_PT_PROC" ]; then
   _SSM_NOW_PT=$(date +%s)
   _SSM_PT_AGE=$(( _SSM_NOW_PT - _SSM_PT_MTIME ))
   if [ "$_SSM_PT_AGE" -gt 300 ]; then
-    if [ ! -f "$_SSM_PT_JSONL" ]; then
+    if ! df_no_symlink_below "$PROJECT_ROOT" "$_SSM_PT_PROC" "$_SSM_PT_JSONL"; then
+      dbg "Stale .pending-turns.processing skipped — a symbolic link sits on its path or the queue's"
+      log "Stale .pending-turns.processing skipped (cold path): a symbolic link sits on the path to $_SSM_PT_PROC or $_SSM_PT_JSONL"
+    elif [ ! -f "$_SSM_PT_JSONL" ]; then
       mv "$_SSM_PT_PROC" "$_SSM_PT_JSONL" 2>/dev/null || true
       dbg "Recovered orphaned .pending-turns.processing (age ${_SSM_PT_AGE}s)"
       log "Recovered orphaned .pending-turns.processing → .pending-turns.jsonl (cold path)"
@@ -135,27 +142,31 @@ parse_and_validate_stamp() {
   esac
 }
 
-# --- detect_refresh_failing: sets REFRESH_FAILING in caller's scope.
+# --- detect_refresh_failing <now> <memory_dir> <log_dir> <root>: sets
+# REFRESH_FAILING in caller's scope. <root> is the project root the memory folder
+# lies below.
 # Condition: queue non-empty AND (.last-refresh-ok missing OR >600s old)
 # orphaned-processing depth fix: count both .pending-turns.jsonl AND
 # .pending-turns.processing toward _queue_depth. Before this fix, an orphaned
 # .processing (whose mtime is between 0s and the D56c 300s cold-path gate)
 # was invisible to State-C — a crashed worker's batch would sit silently with
-# no user-visible warning.
+# no user-visible warning. The count reaches the session, so a batch a symbolic
+# link leads to counts as absent (D-HOOKS-NO-SYMLINK, git-marker).
 detect_refresh_failing() {
   local _now="$1"
   local _memory_dir="$2"
   local _log_dir="$3"
+  local _root="$4"
   local _queue_file="$_memory_dir/.pending-turns.jsonl"
   local _proc_file="$_memory_dir/.pending-turns.processing"
   local _ok_file="$_memory_dir/.last-refresh-ok"
   local _queue_depth=0
-  if [ -f "$_queue_file" ] && [ -s "$_queue_file" ]; then
+  if df_file_below "$_root" "$_queue_file" && [ -s "$_queue_file" ]; then
     _queue_depth=$(wc -l < "$_queue_file" | tr -d ' ')
   fi
   # Also count lines in .processing — an orphaned batch left by a crashed worker
   # is unprocessed content even if .jsonl is empty (applies B4 blind-spot fix)
-  if [ -f "$_proc_file" ] && [ -s "$_proc_file" ]; then
+  if df_file_below "$_root" "$_proc_file" && [ -s "$_proc_file" ]; then
     local _proc_depth
     _proc_depth=$(wc -l < "$_proc_file" | tr -d ' ')
     _queue_depth=$(( _queue_depth + _proc_depth ))
@@ -180,7 +191,14 @@ detect_refresh_failing() {
   fi
 }
 
-if [ -f "$MEMORY_FILE" ]; then
+# D-HOOKS-NO-SYMLINK (git-marker): the working memory, the batches State C counts
+# and the pre-compact backup are all read into the session, so each is read only
+# where no symbolic link sits on its path; a file a link leads to is treated as
+# absent, and its refusal logged once.
+MEMORY_PRESENT=""
+if df_file_below "$PROJECT_ROOT" "$MEMORY_FILE"; then MEMORY_PRESENT="yes"; fi
+
+if [ -n "$MEMORY_PRESENT" ]; then
   dbg "MEMORY_FILE exists: $MEMORY_FILE"
   MEMORY_CONTENT=$(head -c 65536 "$MEMORY_FILE")
 
@@ -239,7 +257,7 @@ if [ -f "$MEMORY_FILE" ]; then
   fi
 
   # --- State C detection: refresh failing ---
-  detect_refresh_failing "$NOW" "$MEMORY_DIR" "$LOG_DIR"
+  detect_refresh_failing "$NOW" "$MEMORY_DIR" "$LOG_DIR" "$PROJECT_ROOT"
 
   # --- Build state-specific header ---
   # D-DETACHED-HEAD: where the session is, as one phrase. On a branch it is
@@ -292,8 +310,12 @@ fi
 # Re-inject compaction snapshot when it's more recent than the memory file (compact overwrote
 # WORKING-MEMORY.md with a summary, but the pre-compact snapshot may have richer context).
 BACKUP_FILE="$MEMORY_DIR/backup.json"
-if [ -f "$BACKUP_FILE" ]; then
-  BACKUP_MEMORY=$(json_field_file "$BACKUP_FILE" "memory_snapshot" "")
+if df_file_below "$PROJECT_ROOT" "$BACKUP_FILE"; then
+  # Under set -e a failed read would end the hook before it prints the working
+  # memory built above, so a backup that does not parse is read as no snapshot,
+  # like an absent one, discarding what jq printed before it failed. The read
+  # below runs only once this one has parsed the whole file.
+  BACKUP_MEMORY=$(json_field_file "$BACKUP_FILE" "memory_snapshot" "") || BACKUP_MEMORY=""
   if [ -n "$BACKUP_MEMORY" ]; then
     BACKUP_TS=$(json_field_file "$BACKUP_FILE" "timestamp" "")
     BACKUP_EPOCH=0
@@ -303,7 +325,7 @@ if [ -f "$BACKUP_FILE" ]; then
         || echo "0")
     fi
     FILE_MTIME_CK=0
-    if [ -f "$MEMORY_FILE" ]; then
+    if [ -n "$MEMORY_PRESENT" ]; then
       FILE_MTIME_CK=$(get_mtime "$MEMORY_FILE" 2>/dev/null || echo "0")
     fi
     if [ "$BACKUP_EPOCH" -gt "$FILE_MTIME_CK" ]; then

package/src/assets/skills/test-driven-development/SKILL.md

@@ -34,6 +34,8 @@ Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define t
 
 ## The Cycle
 
+**Affected tests**: the tests that cover the changed files, selected by the runner's related-test option (Jest's `--findRelatedTests`, Vitest's `related`) or, where the runner has none, the package or path that owns them. Every "run the tests" step below means the affected tests; the full suite belongs to Validate.
+
 ### Step 1: RED — Write a Failing Test
 
 Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
@@ -56,19 +58,19 @@ Don't write code "you'll need later." Write code the test demands NOW.
 Don't optimize. Don't refactor. Don't clean up. Just pass the test.
 ```
 
-**Checkpoint:** All tests pass. If any test fails, fix it before moving on.
+**Checkpoint:** All affected tests pass. If any test fails, fix it before moving on.
 
 ### Step 3: REFACTOR — Improve Without Changing Behavior
 
 Now clean up. Extract helpers, rename variables, simplify logic. Tests stay green throughout.
 
 ```
-Run tests after every refactoring step.
+Run the affected tests after every refactoring step.
 If a test breaks during refactor, undo immediately — you changed behavior.
 Apply DRY, extract patterns, improve readability.
 ```
 
-**Checkpoint:** All tests still pass. Code is clean. Repeat from Step 1 for next behavior.
+**Checkpoint:** All affected tests still pass. Code is clean. Repeat from Step 1 for next behavior.
 
 ---
 
@@ -79,7 +81,7 @@ After each RED-GREEN-REFACTOR cycle, ALL must hold:
 - [ ] Test existed BEFORE production code (not concurrent, not after)
 - [ ] Test failed for the RIGHT reason (expected behavior absent, not syntax/import error)
 - [ ] Production code is minimal — no speculative additions beyond what the test demands
-- [ ] ALL tests pass, not just the new one
+- [ ] ALL affected tests pass, not just the new one
 - [ ] Refactoring happened in Step 3 (or code is already clean — state explicitly)
 - [ ] No untested production code remains