devflow-kit 3.0.1 → 3.2.0

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

@@ -66,6 +66,16 @@ fi
 # Auto-create .devflow/ and ensure .gitignore entries (idempotent after first run)
 source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 
+# D-HOOKS-NO-SYMLINK (git-marker): every write below lands in the memory folder,
+# so a linked folder, which would take the backup and the working memory into the
+# folder it names, ends the hook here. The backup's own target is checked where the
+# backup is renamed onto it.
+if ! df_no_symlink_below "$PROJECT_ROOT" "$MEMORY_DIR"; then
+  log "SKIP: a symbolic link sits on the path to $MEMORY_DIR; no backup or working memory written"
+  dbg "EXIT: symbolic link on the memory folder path"
+  exit 0
+fi
+
 BACKUP_FILE="$MEMORY_DIR/backup.json"
 
 # Capture git state
@@ -102,25 +112,60 @@ if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
   dbg "GIT_BRANCH=$GIT_BRANCH HEAD=$GIT_HEAD_SHA"
 fi
 
-# Snapshot current WORKING-MEMORY.md (preserves session context through compaction)
+# Snapshot current WORKING-MEMORY.md (preserves session context through compaction).
+# The snapshot goes into the backup the next session start injects, so a working
+# memory a symbolic link leads to is treated as absent (D-HOOKS-NO-SYMLINK).
 MEMORY_SNAPSHOT=""
-if [ -f "$MEMORY_DIR/WORKING-MEMORY.md" ]; then
+if df_file_below "$PROJECT_ROOT" "$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"
+# D-BACKUP-RENAME: the backup is written whole into a copy beside it, then
+# renamed over it; it is never truncated and refilled in place. Reason:
+# session-start-memory reads it twice, and a read landing between a truncate
+# and the write that refills it would meet a partial file; a rename hands every
+# read either the previous backup or the new one. SEC-2: the copy is created
+# under umask 077, and 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. The rename gives the
+# backup the copy's inode and mode, so the backup, which holds the working
+# memory, is 0600 whatever the caller's umask (as in queue-append). A write or
+# rename that fails removes whatever holds the copy's name and keeps the
+# previous backup; the bootstrap below still runs.
+#
+# The rename's target is checked first (D-HOOKS-NO-SYMLINK, git-marker): `mv`
+# moves the copy into a folder a link at backup.json names, so a link there, to
+# anything, skips the backup with nothing created, logged once, and the
+# bootstrap below still runs.
+#
+# A run killed after creating its copy and before renaming it (by the hook's
+# timeout, say) leaves the copy under its own PID, a name no later run writes,
+# so each run first removes the copies nothing has written to for an hour. A
+# write ends within the hook's 10 s timeout, so no live run's copy is that old
+# and a concurrent run's copy is left alone.
+find "$MEMORY_DIR" -maxdepth 1 -type f -name "${BACKUP_FILE##*/}.tmp.*" -mmin +60 -delete 2>/dev/null || true
+BACKUP_TMP="$BACKUP_FILE.tmp.$$"
+if ! df_no_symlink_below "$PROJECT_ROOT" "$BACKUP_FILE"; then
+  log "Backup not written: a symbolic link sits on the path to $BACKUP_FILE"
+  dbg "Backup not written: symbolic link at $BACKUP_FILE"
+elif [ ! -e "$BACKUP_TMP" ] && [ ! -L "$BACKUP_TMP" ] && (umask 077 && set -o noclobber && 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_TMP") && mv "$BACKUP_TMP" "$BACKUP_FILE"; then
+  log "Wrote backup: $BACKUP_FILE"
+  dbg "Wrote backup: $BACKUP_FILE"
+else
+  rm -f "$BACKUP_TMP" 2>/dev/null || true
+  log "Backup not written; the previous one is kept: $BACKUP_FILE"
+  dbg "Backup not written: $BACKUP_FILE"
+fi
 
 # Bootstrap minimal WORKING-MEMORY.md if absent; skip on an unborn branch or a
 # malformed SHA. is_hex_sha 40 40: exactly 40 lowercase hex chars required. A detached
@@ -131,9 +176,16 @@ dbg "Wrote backup: $BACKUP_FILE"
 # avoids REL-5: O_EXCL-style atomic create via noclobber so the existence test and the
 # create are one operation — if the worker's CAS mv lands in the window, noclobber fails
 # (file already exists) and we skip the bootstrap rather than truncating fresh memory.
+# D-HOOKS-NO-SYMLINK (git-marker): the create is made only where nothing stands, tested
+# with builtins first, since noclobber alone opens a link to a FIFO or a device (no
+# regular file stands there) and would wait on the FIFO or write the text into the
+# device. A link there is left as it was and logged; the memory folder above it was
+# checked at the top.
 MEMORY_FILE="$MEMORY_DIR/WORKING-MEMORY.md"
 if [ -n "$GIT_BRANCH" ] && is_hex_sha "$GIT_HEAD_SHA" 40 40; then
-  if (set -o noclobber; : > "$MEMORY_FILE") 2>/dev/null; then
+  if [ -L "$MEMORY_FILE" ]; then
+    log "Working memory not bootstrapped: $MEMORY_FILE is a symbolic link"
+  elif [ ! -e "$MEMORY_FILE" ] && (set -o noclobber; : > "$MEMORY_FILE") 2>/dev/null; then
     {
       echo "<!-- memory-head: $GIT_HEAD_SHA branch: $GIT_BRANCH -->"
       echo ""

package/src/assets/scripts/hooks/preamble

@@ -62,7 +62,15 @@ 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."
+  # D-ARGS-ONCE: the directive passes the Skill call NO arguments. The handoff
+  # prompt IS the plan, so it is already in the conversation; handing it to the
+  # skill as an argument would put a second copy in the main-thread context for
+  # nothing. The skill's empty-input path takes the plan from the conversation.
+  # No plan body or plan path is parsed here: detection stays the literal prefix.
+  # This string is double-quoted bash: it must hold no dollar sign and no
+  # unescaped backtick, and it must equal HANDOFF_TEMPLATE in
+  # tests/fixtures/ambient-templates.ts byte for byte.
+  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 and no arguments: the plan is already in this conversation, so the skill needs no input. Do not pause to ask whether to proceed."
 elif [[ "$HEAD" == "/"* ]]; then
   dbg "EXIT: slash command — no reminder"
 else

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
@@ -42,7 +49,7 @@
 #               `devflow memory|learning --enable/--disable` write. Only an
 #               explicit boolean `false` switches a feature off -- an absent,
 #               unreadable or malformed manifest, a missing key, or a non-boolean
-#               value leaves it ON (fail-open, ADR-028), the rule
+#               value leaves it ON (fail-open), the rule
 #               isMachineFeatureOn() applies in the CLI.
 #     project   <root>/.devflow/project.json (team-committed) and
 #     personal  <root>/.devflow/config.json (this worktree's own), read ONLY under
@@ -60,7 +67,7 @@
 #
 #   D-LEARNING-LEGACY-DECISIONS: in the MANIFEST only, learning reads
 #   `features.learning` when it is a boolean, else the pre-rename
-#   `features.decisions` (ADR-011) -- readManifest's migration precedence
+#   `features.decisions` -- readManifest's migration precedence
 #   exactly, so a legacy `decisions: false` switches learning off before any
 #   command has healed the file. Only a boolean `false` in whichever key decides
 #   is off, as above.
@@ -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/resolve-project-root

@@ -56,10 +56,9 @@ _df_nongit_root() {
 #   DF_LEDGER_ROOT — where the learning ledger and its queue live.
 #
 # D-LEDGER-MAIN-WORKTREE: a linked worktree (`git worktree add`, `claude
-# --worktree`) has its own toplevel, so a ledger anchored there restarts at
-# ADR-001 — main's decisions are invisible in it, and the IDs it mints collide
-# with main's (in a repo whose collision guard refuses, the Learning agent stops
-# for good). The ledger is one per REPOSITORY, not per checkout: DF_LEDGER_ROOT
+# --worktree`) has its own toplevel, so a ledger anchored there restarts its
+# numbering at 001 — main's decisions are invisible in it, and the IDs it mints collide
+# with main's. The ledger is one per REPOSITORY, not per checkout: DF_LEDGER_ROOT
 # is the main worktree — the parent of `--git-common-dir` — when that common dir
 # is a `<dir>/.git` directory AND `<dir>/.devflow` already exists; otherwise it is
 # DF_ROOT. The existence test keeps a main checkout that never ran devflow from

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

@@ -8,7 +8,8 @@
 # not the home directory (D-HOOKS-GIT-ONLY), and they read the learning ledger of
 # the main worktree when this is a linked one (D-LEDGER-MAIN-WORKTREE).
 #
-# Section 1: Project decisions TL;DR (decisions.md / pitfalls.md header lines).
+# Section 1: Project decisions TL;DR (decisions.md / pitfalls.md header lines),
+# then the path of the decisions index when it lists entries.
 # 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.
@@ -57,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
@@ -85,10 +91,18 @@ fi
 # Ensure the project root .gitignore ignores .devflow/ wholesale. This runs on every
 # git-project 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
+# 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=""
 
@@ -101,7 +115,8 @@ TRACKER_DEVFLOW_DIR="$HOME/.devflow"
 #
 # Section 2 embeds $LEDGER_ROOT; Section 3 embeds $PROJECT_ROOT and
 # $TRACKER_DEVFLOW_DIR — each inside a double-quoted `prompt: "..."` string the
-# model reads out of additionalContext. The provider and model TOKENS in those
+# model reads out of additionalContext. Section 1's index line embeds
+# $LEDGER_ROOT too, as the path the model reads the decisions index from. The provider and model TOKENS in those
 # directives are admitted by positive allowlists, and so are these: the gate is the
 # POSITIVE shape ^[A-Za-z0-9/._+-]+$, expressed as "rejects if any character falls
 # outside it".
@@ -134,16 +149,16 @@ TRACKER_DEVFLOW_DIR="$HOME/.devflow"
 # admitted set is locale-dependent, and no rule here rests on it.
 #
 # Checked ONCE, here, where every value is resolved and above every section that
-# interpolates them, so no sink can embed a value no gate saw (PF-023 — the
+# interpolates them, so no sink can embed a value no gate saw (the
 # invariant belongs at the convergence point all callers pass through, not in
 # whichever section someone remembered). `case` is a shell builtin, so the GitHub
 # path still forks zero times [DR-10]. The empty arm is explicit: an unset root
 # must not read as "no forbidden character, therefore safe".
 #
 # ONE gate per VALUE, applied to the root each section embeds, not one over their
-# concatenation. Section 2 interpolates $LEDGER_ROOT alone — the main worktree's
-# root in a linked worktree (D-LEDGER-MAIN-WORKTREE), so it is the value checked
-# for that section, not the checkout's own; only Section 3 interpolates
+# concatenation. Sections 1 and 2 interpolate $LEDGER_ROOT alone — the main
+# worktree's root in a linked worktree (D-LEDGER-MAIN-WORKTREE), so it is the value
+# checked for them, not the checkout's own; only Section 3 interpolates
 # $PROJECT_ROOT and $TRACKER_DEVFLOW_DIR. Gating values jointly made a rejected
 # ~/.devflow shape suppress the Learning directive as well — a value Section 2
 # never embeds, silently disabling the whole learning pipeline for any machine
@@ -178,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
@@ -197,24 +209,52 @@ 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"
         fi
       fi
     done
-    if [ -n "$DECISIONS_TLDR" ]; then
-      dbg "Decisions TL;DR found"
-      DECISIONS_SECTION="--- PROJECT DECISIONS (TL;DR) ---
+    # 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)`. 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" ] && 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
+    if [ -n "$DECISIONS_TLDR" ] || [ -n "$DECISIONS_INDEX_LINE" ]; then
+      dbg "Decisions TL;DR or index found"
+      DECISIONS_SECTION="--- PROJECT DECISIONS (TL;DR) ---"
+      if [ -n "$DECISIONS_TLDR" ]; then
+        DECISIONS_SECTION="${DECISIONS_SECTION}
 $(printf '%b' "$DECISIONS_TLDR")"
+      fi
+      # The index line goes last.
+      if [ -n "$DECISIONS_INDEX_LINE" ]; then
+        DECISIONS_SECTION="${DECISIONS_SECTION}
+${DECISIONS_INDEX_LINE}"
+      fi
       if [ -n "$CONTEXT" ]; then
         CONTEXT="${CONTEXT}
 
@@ -227,18 +267,23 @@ ${DECISIONS_SECTION}"
 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.
+# Emitted when captured turns are waiting: the queue is non-empty, or a
+# .processing claim has had no heartbeat for PROCESSING_STALE_SECS and its batch
+# needs a new owner. A FRESH .processing means a live Learning agent holds the
+# claim, so the directive is suppressed even if new turns queued since. This
+# check is advisory and decides only whether to spawn: the claim itself is taken
+# by json-helper's claim-queue op under the learning lock, which applies the same
+# threshold (D-OWNED-CLAIM, lib/learning-store.cjs), so a spawn that loses a race
+# exits on `busy`.
 if [ "$LEARNING_ENABLED" = "true" ]; then
   QUEUE_FILE="$LEARNING_DIR/.pending-turns.jsonl"
   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)
@@ -247,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
 
@@ -271,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_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" ] && [ -f "$HOME/.devflow/learning.json" ]; then
-      LEARNING_MODEL=$(json_field_file "$HOME/.devflow/learning.json" "model" "")
+    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}
@@ -440,8 +540,8 @@ if [ -n "$TRACKER_PROVIDER" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
   tracker_gates_open() {
     # Gate 1 — the attempt cap. Read with the `read` builtin: no fork.
     #
-    # The counter's shape is ONE decimal integer line and nothing else (PF-062 —
-    # document the shape of any file that gates an action, and keep absent and
+    # The counter's shape is ONE decimal integer line and nothing else
+    # (document the shape of any file that gates an action, and keep absent and
     # malformed distinct from a value). Absent means "no attempt yet" = 0.
     # Malformed self-heals to 0 and is overwritten with a well-formed count on
     # emission below, so a stray byte can never recur: refusing forever would
@@ -571,7 +671,7 @@ if [ -n "$TRACKER_PROVIDER" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
     # allowlisted tokens. Decided once at the top of the file, where both values are
     # resolved; consulted here because this is one of the two sinks that interpolate
     # them, and a control stated once for the file is not a control at a sink that
-    # never consults it (PF-023). The third path, the conventions file, is composed
+    # never consults it. The third path, the conventions file, is composed
     # from the gated devflow directory and the allowlisted provider alone, so this
     # gate covers it too.
     if [ -z "$DIRECTIVE_PATHS_SAFE" ]; then
@@ -607,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) ;;