devflow-kit 3.1.0 → 3.3.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/scripts/release-trace.cjs

@@ -113,12 +113,28 @@ const FULL_SHA_RE = /^[0-9a-f]{40}$/;
 const KEY_RE = /^[A-Z][A-Z0-9_]{1,9}$/;
 
 /**
- * Step 3a's closing-keyword regex, byte-for-byte the literal the built
- * `gather-release-evidence` references state, applied case-insensitively WITHOUT
- * the `u` flag — so a non-ASCII letter (`ſ`, the Kelvin sign) never folds onto an
- * ASCII keyword letter. A parity test pins `.source` and `.flags` to the built text.
+ * D-TRACE-KEYWORDS: two keyword sets, deliberately unequal, because they answer
+ * two different questions.
+ *
+ * CLOSING_KEYWORD_RE is step 3a's closing-keyword regex, byte-for-byte the literal
+ * the built `gather-release-evidence` references state: a commit that carries one
+ * of these keywords ships the issue it names. `Refs #N` only mentions an issue, so
+ * `refs` is not a closing keyword and the prompt never lets such a commit reach
+ * SHIPPED_ISSUES. The script itself classifies with TRACE_KEYWORD_RE; this regex
+ * is exported so a parity test can pin the prompt's rule to a literal.
+ *
+ * TRACE_KEYWORD_RE is the closing set plus `refs`. The trace map asks the weaker
+ * question "does this commit name an issue at all?", and a `Refs #N` commit does,
+ * so it is `traced` and not `untraced`. Narrowing the closing set must not turn
+ * those commits into traceability gaps in the release confirm.
+ *
+ * Both apply case-insensitively WITHOUT the `u` flag — so a non-ASCII letter
+ * (`ſ`, the Kelvin sign) never folds onto an ASCII keyword letter. A parity test
+ * pins CLOSING_KEYWORD_RE's `.source` and `.flags` to the built text, and
+ * TRACE_KEYWORD_RE to the closing set plus `refs`.
  */
-const KEYWORD_RE = /^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?|refs):?$/i;
+const CLOSING_KEYWORD_RE = /^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?):?$/i;
+const TRACE_KEYWORD_RE = /^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?|refs):?$/i;
 
 /** Step 3a's trailing-strip class, byte-for-byte the built literal (parity-pinned). */
 const TRAILING_CLASS = '[.,;:)\\]!?]';
@@ -377,11 +393,11 @@ function gateCandidate(candidate, grammar, key) {
 
 /**
  * Step 3a, executed, then the grammar's gate: the first reference `message`
- * yields, or null. Per line, a whitespace token matching KEYWORD_RE opens a run:
- * the next token, plus each further token while the previous one ends in `,`.
+ * yields, or null. Per line, a whitespace token matching TRACE_KEYWORD_RE opens a
+ * run: the next token, plus each further token while the previous one ends in `,`.
  * Each run token splits on `,`, is stripped, and non-empty parts are gated.
  *
- * Linear in the message: a keyword token never ends in `,` (KEYWORD_RE is
+ * Linear in the message: a keyword token never ends in `,` (TRACE_KEYWORD_RE is
  * anchored), so every comma run is walked by at most the one keyword before it.
  *
  * @param {string} message
@@ -393,7 +409,7 @@ function findReference(message, grammar, key) {
   for (const line of message.split('\n')) {
     const tokens = line.split(/\s+/).filter(t => t !== '');
     for (let i = 0; i < tokens.length; i++) {
-      if (!KEYWORD_RE.test(tokens[i])) continue;
+      if (!TRACE_KEYWORD_RE.test(tokens[i])) continue;
       for (let j = i + 1; j < tokens.length; j++) {
         for (const part of tokens[j].split(',')) {
           const stripped = stripCandidate(part);
@@ -1117,7 +1133,8 @@ module.exports = Object.freeze({
   EXIT_CODES,
   LIMITS,
   RELEASE_TAG_RE,
-  KEYWORD_RE,
+  CLOSING_KEYWORD_RE,
+  TRACE_KEYWORD_RE,
   TRAILING_CLASS,
   GRAMMARS,
   GRAMMAR_RULES,

package/src/assets/skills/accessibility/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: accessibility
-description: This skill should be used when the user asks to "add accessibility", "check ARIA", "handle keyboard navigation", "add focus management", or creates UI components, forms, or interactive elements. Provides WCAG 2.2 AA patterns for keyboard navigation, ARIA roles and states, focus management, color contrast, and screen reader support.
+description: This skill should be used when the user asks to "add accessibility", "check ARIA", "handle keyboard navigation", or creates UI components, forms, or interactive elements.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 activation: