devflow-kit 3.7.0 → 3.9.0

package/src/assets/scripts/hooks/background-memory-update

@@ -29,6 +29,9 @@
 #               for the next run (D-QUEUE-NO-ORPHAN-DELETE)
 # No parser:    neither jq nor node on PATH → exits with no LLM run; the queue and any .processing batch are left in place
 # Parser fails: jq or node exits non-zero while it reads the queue or the batch → exits with no LLM run; the turns are kept
+# Paused area:  git tracks files in the memory folder, or a `.git` entry stands and git does not answer → exits with
+#               result=skip and no LLM run, and reads, claims, writes and notices nothing; asked at the start, and again
+#               after the run, where a late answer leaves the staged file unswapped and the batch in .processing
 
 set -e
 
@@ -128,6 +131,59 @@ source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
 # The staged-path check, the settings JSON with the worker's Edit allow and deny rules, the
 # result line and the one-time notice (needs df_no_symlink_below from resolve-project-root).
 source "$SCRIPT_DIR/memory-permission" || { echo "background-memory-update: failed to source memory-permission" >&2; exit 1; }
+source "$SCRIPT_DIR/queue-append" || { echo "background-memory-update: failed to source queue-append" >&2; exit 1; }
+
+# --- The memory area check: git tracks files in the memory folder, or does not answer ---
+# A folder that git tracks holds the repository's content, not devflow's data. While git
+# tracks files in the memory folder of this checkout, or a `.git` entry stands and git does
+# not answer, the memory area is paused, and the worker reads and writes nothing there.
+# Sets DF_TRACKED_AREA_MEMORY to `tracked`, `untracked` or `unknown` for the project root in
+# $1: queue_tracked_area in git mode, run in a background subshell that answers by its exit
+# status (10 untracked, 11 tracked), so that a git that hangs can be cut and no file is made.
+# Every call asks git afresh: the second ask of a run must see what changed during the run.
+# The bound is DEVFLOW_BG_AREA_PROBE_SECS (default 5, at most 60; tests override it as they
+# do DEVFLOW_BG_WATCHDOG_SECS), kept by the watchdog's background-and-kill idiom: a SIGKILL
+# to the probe's process group (set -m) after a sleep, and a SIGKILL cancel of the watchdog,
+# so no exit trap runs in either subshell (the one `Run:` line, above). A probe that is
+# cut, or ends in any other status, reads `unknown`: the area stays paused. The notices of
+# memory-permission read this variable, so the worker leaves one only after this check has
+# asked and found the area free. Always returns 0.
+probe_memory_area() {
+  local _root="${1:-}" _secs _pid _wd_pid _status=1
+  DF_TRACKED_AREA_MEMORY="unknown"
+  _secs="${DEVFLOW_BG_AREA_PROBE_SECS:-5}"
+  case "$_secs" in
+    ''|*[!0123456789]*|????*) _secs=5 ;;
+  esac
+  if [ "$_secs" -lt 1 ] || [ "$_secs" -gt 60 ]; then _secs=5; fi
+  set -m
+  (
+    _QTA_ASKED_MEMORY=""
+    queue_tracked_area "$_root" memory git
+    case "$DF_TRACKED_AREA_MEMORY" in
+      untracked) exit 10 ;;
+      tracked) exit 11 ;;
+    esac
+    exit 12
+  ) </dev/null >/dev/null 2>&1 &
+  _pid=$!
+  set +m
+  (
+    sleep "$_secs"
+    kill -KILL -"$_pid" 2>/dev/null || true
+  ) </dev/null >/dev/null 2>&1 &
+  _wd_pid=$!
+  if wait "$_pid" 2>/dev/null; then _status=0; else _status=$?; fi
+  # SIGKILL, not SIGTERM, as for the other watchdogs: no trap can run in the subshell.
+  kill -KILL "$_wd_pid" 2>/dev/null || true
+  wait "$_wd_pid" 2>/dev/null || true
+  case "$_status" in
+    10) DF_TRACKED_AREA_MEMORY="untracked" ;;
+    11) DF_TRACKED_AREA_MEMORY="tracked" ;;
+  esac
+  return 0
+}
+
 PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 [ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
 # One canonical root feeds every path below, the staged path in the prompt and in the
@@ -136,6 +192,7 @@ PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 PROJECT_ROOT_CANONICAL=$(cd -P -- "$PROJECT_ROOT" 2>/dev/null && pwd -P) || PROJECT_ROOT_CANONICAL=""
 if [ -z "$PROJECT_ROOT_CANONICAL" ]; then
   log "SKIP: project root could not be resolved; no LLM run"
+  probe_memory_area "$PROJECT_ROOT"
   memory_notice_write "$PROJECT_ROOT/.devflow/memory" "$PROJECT_ROOT" path
   exit 0
 fi
@@ -152,15 +209,25 @@ OK_FILE="$MEMORY_DIR/.last-refresh-ok"
 
 # --- Re-check the memory switch at runtime (defense-in-depth: the feature may
 # have been disabled since spawn, or narrowed by a checkout that now carries a
-# `features.memory: false`). Same helper as every other memory/learning gate
+# `features.memory: false`). Same helper as every other memory/curation gate
 # (D-FEATURES-NARROW-ONLY, see queue-append).
-source "$SCRIPT_DIR/queue-append" || { echo "background-memory-update: failed to source queue-append" >&2; exit 1; }
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 if [ "$_QG_MEMORY" != "true" ]; then
   log "ABORT: memory disabled (disabled after spawn)"
   exit 0
 fi
 
+# --- Ask whether git tracks files in the memory folder ---
+# The area may have become tracked since the Stop hook spawned this worker. A paused area
+# ends the run here, before the binary is resolved, a link is checked, the lock is taken or
+# a batch is claimed: nothing is read, moved or written, and no notice is left. The run's
+# `Run:` line says skip.
+probe_memory_area "$PROJECT_ROOT"
+if [ "$DF_TRACKED_AREA_MEMORY" != "untracked" ]; then
+  log "SKIP: the memory area is paused (git tracks files in the memory folder, or did not answer); nothing read or written; no LLM run"
+  exit 0
+fi
+
 # --- Resolve claude binary ---
 CLAUDE_BIN=$(command -v claude 2>/dev/null || true)
 if [ -z "$CLAUDE_BIN" ]; then
@@ -340,7 +407,7 @@ else
   fi
 fi
 
-# --- Worker-level lock (300s stale-break — much longer than learning-lock's 30s) ---
+# --- Worker-level lock (300s stale-break — much longer than curation-lock's 30s) ---
 # This prevents a second worker (spawned 121s later) from double-writing WORKING-MEMORY.md
 # while the first worker's claude -p call (up to 120s) is still in flight.
 #
@@ -1126,6 +1193,17 @@ case "$MEMORY_RESULT_DENIALS" in
   *) RESULT_DENIED="yes" ;;
 esac
 
+# The run took minutes, so the memory area is asked again before anything lands in the
+# folder. If git tracks files there now, or does not answer, nothing below runs: the staged
+# file is not checked, moved or removed, no stamp is touched, no denied run is counted and
+# no notice is left. The batch stays in .processing.
+probe_memory_area "$PROJECT_ROOT"
+if [ "$DF_TRACKED_AREA_MEMORY" != "untracked" ]; then
+  RUN_RESULT="skip"
+  log "SKIP: the memory area is paused (git tracks files in the memory folder, or did not answer); nothing swapped or stamped; the batch stays in .processing"
+  exit 0
+fi
+
 # A folder or a link at the staged path now was put there during the run: the path was
 # empty at the spawn. It is removed the way it is before a run (memory_staged_remove), and
 # the run ends as failed: the checks below find no staged file, and the batch stays for

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

@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# Learning System: capture-prompt (UserPromptSubmit Hook)
-# Dual-append: writes the user turn to BOTH the memory queue and the learning
+# Curation System: capture-prompt (UserPromptSubmit Hook)
+# Dual-append: writes the user turn to BOTH the memory queue and the curation
 # queue, each independently gated by its own feature flag (AC-F4). Delegates
 # the actual JSONL-write logic to the shared queue-append helper rather than
 # duplicating it inline.
@@ -41,18 +41,18 @@ devflow_debug_set_cwd "$CWD"
 source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
 df_resolve_roots "$CWD" 2>/dev/null || true
 PROJECT_ROOT="${DF_ROOT:-$CWD}"
-# The learning queue is the repository's, not the checkout's: in a linked worktree
+# The curation queue is the repository's, not the checkout's: in a linked worktree
 # it is the main worktree's queue (D-LEDGER-MAIN-WORKTREE, resolve-project-root),
 # the one the Curate agent drains into the shared ledger. Memory stays per checkout.
 LEDGER_ROOT="${DF_LEDGER_ROOT:-$PROJECT_ROOT}"
 
-# The machine-wide manifest (the memory/learning switches, D-FEATURES-NARROW-ONLY
+# The machine-wide manifest (the memory/curation switches, D-FEATURES-NARROW-ONLY
 # in queue-append) lives at the machine root,
 # $HOME/.devflow (D-ONE-HOME).
 DEVFLOW_MANIFEST="$HOME/.devflow/manifest.json"
 PROJECT_DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
 MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
-LEARNING_DIR="$LEDGER_ROOT/.devflow/learning"
+CURATION_DIR="$LEDGER_ROOT/.devflow/curation"
 
 if [ -z "$PROMPT" ]; then
   dbg "EXIT: empty PROMPT"
@@ -61,16 +61,16 @@ fi
 
 source "$SCRIPT_DIR/queue-append" || { echo "capture-prompt: failed to source queue-append" >&2; exit 1; }
 
-# --- AC-P1: at most ONE gate-read fork for memory + learning ---
+# --- AC-P1: at most ONE gate-read fork for memory + curation ---
 # The machine switch, narrowed by this checkout's project.json/config.json
 # `features` (D-FEATURES-NARROW-ONLY, see queue-append).
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 MEMORY_ENABLED="$_QG_MEMORY"
-LEARNING_ENABLED="$_QG_LEARNING"
+CURATION_ENABLED="$_QG_CURATION"
 
-dbg "MEMORY_ENABLED=$MEMORY_ENABLED LEARNING_ENABLED=$LEARNING_ENABLED"
+dbg "MEMORY_ENABLED=$MEMORY_ENABLED CURATION_ENABLED=$CURATION_ENABLED"
 
-if [ "$MEMORY_ENABLED" != "true" ] && [ "$LEARNING_ENABLED" != "true" ]; then
+if [ "$MEMORY_ENABLED" != "true" ] && [ "$CURATION_ENABLED" != "true" ]; then
   dbg "EXIT: both features disabled"
   exit 0
 fi
@@ -82,15 +82,15 @@ source "$SCRIPT_DIR/hook-log-init" "capture-prompt"
 source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-prompt: failed to source get-mtime" >&2; exit 1; }
-source "$SCRIPT_DIR/learning-lock" || { echo "capture-prompt: failed to source learning-lock" >&2; exit 1; }
+source "$SCRIPT_DIR/curation-lock" || { echo "capture-prompt: failed to source curation-lock" >&2; exit 1; }
 
 # Each queue is checked from the root it lies below, and its folder created there,
 # by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 TS=$(date +%s)
 queue_append_both \
   "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
-  "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
-  "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
+  "$LEDGER_ROOT" "$CURATION_DIR/.pending-turns.jsonl" \
+  "$MEMORY_ENABLED" "$CURATION_ENABLED" \
   "user" "$PROMPT" "$TS"
 
 log "Captured user turn (${#PROMPT} chars)"

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

@@ -1,8 +1,8 @@
 #!/bin/bash
 
-# Learning System: capture-question (PostToolUse Hook, matcher: AskUserQuestion)
+# Curation System: capture-question (PostToolUse Hook, matcher: AskUserQuestion)
 # Captures each answered question as a {role:"qa"} row into BOTH the memory and
-# learning queues -- high decision-signal content that free-running Stop-hook
+# curation queues -- high decision-signal content that free-running Stop-hook
 # turns miss (the model's own paraphrase of an answer is lossy; the raw Q&A
 # pair is not).
 #
@@ -60,18 +60,18 @@ devflow_debug_set_cwd "$CWD"
 source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
 df_resolve_roots "$CWD" 2>/dev/null || true
 PROJECT_ROOT="${DF_ROOT:-$CWD}"
-# The learning queue is the repository's, not the checkout's: in a linked worktree
+# The curation queue is the repository's, not the checkout's: in a linked worktree
 # it is the main worktree's queue (D-LEDGER-MAIN-WORKTREE, resolve-project-root),
 # the one the Curate agent drains into the shared ledger. Memory stays per checkout.
 LEDGER_ROOT="${DF_LEDGER_ROOT:-$PROJECT_ROOT}"
 
-# The machine-wide manifest (the memory/learning switches, D-FEATURES-NARROW-ONLY
+# The machine-wide manifest (the memory/curation switches, D-FEATURES-NARROW-ONLY
 # in queue-append) lives at the machine root,
 # $HOME/.devflow (D-ONE-HOME).
 DEVFLOW_MANIFEST="$HOME/.devflow/manifest.json"
 PROJECT_DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
 MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
-LEARNING_DIR="$LEDGER_ROOT/.devflow/learning"
+CURATION_DIR="$LEDGER_ROOT/.devflow/curation"
 
 # --- Parse questions + answers into "question<TAB>answer" rows (one subprocess) ---
 # Defensive against: tool_response absent or a plain string (error case), missing
@@ -123,14 +123,14 @@ fi
 
 source "$SCRIPT_DIR/queue-append" || { echo "capture-question: failed to source queue-append" >&2; exit 1; }
 
-# --- AC-P1: at most ONE gate-read fork for memory + learning ---
+# --- AC-P1: at most ONE gate-read fork for memory + curation ---
 # The machine switch, narrowed by this checkout's project.json/config.json
 # `features` (D-FEATURES-NARROW-ONLY, see queue-append).
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 MEMORY_ENABLED="$_QG_MEMORY"
-LEARNING_ENABLED="$_QG_LEARNING"
+CURATION_ENABLED="$_QG_CURATION"
 
-if [ "$MEMORY_ENABLED" != "true" ] && [ "$LEARNING_ENABLED" != "true" ]; then
+if [ "$MEMORY_ENABLED" != "true" ] && [ "$CURATION_ENABLED" != "true" ]; then
   dbg "EXIT: both features disabled"
   exit 0
 fi
@@ -138,7 +138,7 @@ fi
 source "$SCRIPT_DIR/hook-log-init" "capture-question"
 source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-question: failed to source get-mtime" >&2; exit 1; }
-source "$SCRIPT_DIR/learning-lock" || { echo "capture-question: failed to source learning-lock" >&2; exit 1; }
+source "$SCRIPT_DIR/curation-lock" || { echo "capture-question: failed to source curation-lock" >&2; exit 1; }
 
 # Each queue is checked from the root it lies below, and its folder created there,
 # by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
@@ -151,8 +151,8 @@ A: ${A}"
   TS=$(date +%s)
   queue_append_both \
     "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
-    "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
-    "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
+    "$LEDGER_ROOT" "$CURATION_DIR/.pending-turns.jsonl" \
+    "$MEMORY_ENABLED" "$CURATION_ENABLED" \
     "qa" "$CONTENT" "$TS"
   _QUESTION_COUNT=$(( _QUESTION_COUNT + 1 ))
 done <<EOF

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

@@ -1,8 +1,8 @@
 #!/bin/bash
 
-# Learning System: capture-turn (Stop Hook)
+# Curation System: capture-turn (Stop Hook)
 # Dual-append: writes the assistant turn to BOTH the memory queue and the
-# learning queue, each independently gated by its own feature flag (AC-F4). The
+# curation queue, each independently gated by its own feature flag (AC-F4). The
 # 120s-throttle/nohup-spawn block lives in memory-worker, a separate Stop
 # hook that Claude Code runs in parallel with this one; the worker tolerates a
 # queue this hook has not appended to yet (D-QUEUE-NO-ORPHAN-DELETE).
@@ -45,18 +45,18 @@ dbg "ASSISTANT_MSG length=${#ASSISTANT_MSG}"
 source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
 df_resolve_roots "$CWD" 2>/dev/null || true
 PROJECT_ROOT="${DF_ROOT:-$CWD}"
-# The learning queue is the repository's, not the checkout's: in a linked worktree
+# The curation queue is the repository's, not the checkout's: in a linked worktree
 # it is the main worktree's queue (D-LEDGER-MAIN-WORKTREE, resolve-project-root),
 # the one the Curate agent drains into the shared ledger. Memory stays per checkout.
 LEDGER_ROOT="${DF_LEDGER_ROOT:-$PROJECT_ROOT}"
 
-# The machine-wide manifest (the memory/learning switches, D-FEATURES-NARROW-ONLY
+# The machine-wide manifest (the memory/curation switches, D-FEATURES-NARROW-ONLY
 # in queue-append) lives at the machine root,
 # $HOME/.devflow (D-ONE-HOME).
 DEVFLOW_MANIFEST="$HOME/.devflow/manifest.json"
 PROJECT_DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
 MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
-LEARNING_DIR="$LEDGER_ROOT/.devflow/learning"
+CURATION_DIR="$LEDGER_ROOT/.devflow/curation"
 
 # Skip if empty response
 if [ -z "$ASSISTANT_MSG" ]; then
@@ -66,16 +66,16 @@ fi
 
 source "$SCRIPT_DIR/queue-append" || { echo "capture-turn: failed to source queue-append" >&2; exit 1; }
 
-# --- AC-P1: at most ONE gate-read fork for memory + learning ---
+# --- AC-P1: at most ONE gate-read fork for memory + curation ---
 # The machine switch, narrowed by this checkout's project.json/config.json
 # `features` (D-FEATURES-NARROW-ONLY, see queue-append).
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 MEMORY_ENABLED="$_QG_MEMORY"
-LEARNING_ENABLED="$_QG_LEARNING"
+CURATION_ENABLED="$_QG_CURATION"
 
-dbg "MEMORY_ENABLED=$MEMORY_ENABLED LEARNING_ENABLED=$LEARNING_ENABLED"
+dbg "MEMORY_ENABLED=$MEMORY_ENABLED CURATION_ENABLED=$CURATION_ENABLED"
 
-if [ "$MEMORY_ENABLED" != "true" ] && [ "$LEARNING_ENABLED" != "true" ]; then
+if [ "$MEMORY_ENABLED" != "true" ] && [ "$CURATION_ENABLED" != "true" ]; then
   dbg "EXIT: both features disabled"
   exit 0
 fi
@@ -88,15 +88,15 @@ source "$SCRIPT_DIR/hook-log-init" "capture-turn"
 source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-turn: failed to source get-mtime" >&2; exit 1; }
-source "$SCRIPT_DIR/learning-lock" || { echo "capture-turn: failed to source learning-lock" >&2; exit 1; }
+source "$SCRIPT_DIR/curation-lock" || { echo "capture-turn: failed to source curation-lock" >&2; exit 1; }
 
 # Each queue is checked from the root it lies below, and its folder created there,
 # by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 TS=$(date +%s)
 queue_append_both \
   "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
-  "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
-  "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
+  "$LEDGER_ROOT" "$CURATION_DIR/.pending-turns.jsonl" \
+  "$MEMORY_ENABLED" "$CURATION_ENABLED" \
   "assistant" "$ASSISTANT_MSG" "$TS"
 
 log "Captured assistant turn (${#ASSISTANT_MSG} chars)"

package/src/assets/scripts/hooks/{learning-lock → curation-lock}

@@ -8,7 +8,7 @@
 # break) rather than crashing on a BSD-only stat flag — safe-by-construction,
 # never a hard failure, but source get-mtime first for accurate staleness.
 
-learning_lock_acquire() {
+curation_lock_acquire() {
   local lock_dir="$1"
   local timeout="${2:-3}"
   local stale_threshold=30
@@ -39,6 +39,6 @@ learning_lock_acquire() {
   return 1
 }
 
-learning_lock_release() {
+curation_lock_release() {
   rmdir "$1" 2>/dev/null || true
 }

package/src/assets/scripts/hooks/curation-move

@@ -0,0 +1,293 @@
+#!/bin/bash
+# curation-move -- the one-time ledger folder move for hooks (sourced, not executed).
+#
+# Sourcing it only defines functions -- no side effects until they are called. It is
+# installed with the other hooks and is NOT gated on the curation switch: the old
+# folder holds the project's decisions whether the feature is on or off, and a
+# creator that ran before the move would hide it.
+#
+# df_curation_move <ledger_root> [retry]
+#   Moves <ledger_root>/.devflow/learning to .devflow/curation, once, by running the
+#   move op of json-helper.cjs (moveLedger in lib/curation-move.cjs). <ledger_root>
+#   is the repository's ledger root (DF_LEDGER_ROOT), never the checkout's own.
+#   Always returns 0, and never waits: a move another process holds is skipped and
+#   tried again at the next event.
+#
+#   1. Probe the old folder with a builtin test. Absent is the steady state: nothing
+#      is forked, no key is computed, nothing is logged.
+#   2. Builtin refusals, which do nothing else: the root is not a directory, is a
+#      link, is the home directory or the machine directory (~/.devflow), or a link
+#      sits on the way down to its .devflow. The op refuses the same set.
+#   3. Compute the marker key (df_curation_move_key) with builtins only, and test the
+#      four markers, files at the logs root, never inside the project: curation-move.<key>.skip
+#      (an earlier attempt was refused or failed; the refused marker), curation-move.<key>.busy
+#      (a fresh queue claim held the move, and a claim can last 15 minutes), and
+#      curation-move.<key>.tracked and curation-move.<key>.unknown (the move was skipped: git
+#      tracks files in a curation data folder, or git did not answer). A marker means
+#      return, with no fork and no log line. A second argument `retry` (session start) removes all four first, so a
+#      refusal, a skip and a claim are looked at again once per session; that removal
+#      forks only when a marker exists. The HUD and status read every marker but the busy
+#      one: a busy move is not a refusal.
+#   4. Fork node once, with the root as one argv word (no path is ever part of the
+#      script text); the op knows the two folder names itself. The op answers on its first line:
+#        moved <mode>   one log line (the mode, then the backup folder and the notes
+#                       the op reports, when any);
+#        busy           nothing: no log line and no marker, the next event retries (a
+#                       lock is held, which does not last);
+#        busy claim     nothing is logged, and the busy marker is written, so no event
+#                       forks node again until the next session start;
+#        skipped <why>  <why> is `tracked` or `unknown`. Nothing in the project changed.
+#                       One log line (with `unknown`, the fixed cause word from the
+#                       op's `cause <word>` line), the marker of that reason is
+#                       written, and DF_CURATION_MOVE_SKIPPED is set to the reason, so
+#                       the hook that called the shim can tell the user
+#                       (session-start-context);
+#        none           nothing (the folder went away after the probe);
+#        anything else, or a non-zero exit (a refusal or an I/O error): one log line,
+#                       and the refused marker is written.
+#   Hooks that run under `set -e` call it as a plain statement: every path ends in
+#   `return 0`, the marker write and the node call are guarded.
+#
+#   DF_CURATION_MOVE_SKIPPED is empty at every call, and holds the reason only after the
+#   call that ran node and got a skip.
+#
+# df_curation_move_key <root>
+#   Sets DF_CURATION_MOVE_KEY to the marker key of <root>: a 32-bit hash over every
+#   byte of the root under LC_ALL=C (each step: hash = 33 * hash + (byte & 255),
+#   masked to 32 bits, starting from 5381) as eight lowercase hex characters, an
+#   underscore, then the last 60 bytes of the root (all of them when it is shorter)
+#   with every byte outside letters and digits replaced by an underscore. The
+#   TypeScript twin is curationMoveMarkerKey in src/core/project-paths.ts; status and
+#   the HUD read the marker through it (tests/shell-hooks.test.ts holds both to the
+#   same answers). Returns 1, setting nothing, for a root of more than 4096 bytes.
+#
+# df_curation_move_plain <text>
+#   Sets DF_CURATION_MOVE_PLAIN to <text> with every control character replaced by a
+#   space: C0 and DEL, and the C1 controls U+0080-U+009F (the bytes C2 80 to C2 9F in
+#   UTF-8). Builtin expansion only, so it forks nothing. node's answer can carry a name
+#   the repository holds, and no log line may carry an escape sequence or break in two.
+#   It works bytewise under LC_ALL=C, which it puts back as it was, so other UTF-8
+#   text, whatever the locale, is kept.
+#
+# df_curation_move_names
+#   Sets the names the shell reads: DF_CM_OLD_FOLDER and DF_CM_NEW_FOLDER (the ledger
+#   folder before and after the rename) and DF_CM_NEW_TUNING_FILE. They mirror
+#   LEGACY_NAMES.folder, CURATION_DIR_NAME and CURATION_TUNING_FILE_NAME in
+#   src/core/project-paths.ts and hooks/lib/project-paths.cjs (tests/project-paths.test.ts
+#   holds all three to the same values). The old backup prefix and the old tuning file
+#   are read only by the node move, so the shell holds no copy of them. Every hook that
+#   names a ledger folder (queue-append, ensure-devflow-init, session-start-context)
+#   takes the name from here.
+#
+# Source-order requirement: none. This file sources its sibling git-marker itself,
+# for df_no_symlink_below; one that failed to source is a command not found, which
+# the refusal below reads as "a link may sit on the path". The caller defines log()
+# to have the move reported; without it the move is silent.
+
+source "${BASH_SOURCE[0]%/*}/git-marker" 2>/dev/null || true
+
+df_curation_move_names() {
+  DF_CM_OLD_FOLDER="learning"
+  DF_CM_NEW_FOLDER="curation"
+  DF_CM_NEW_TUNING_FILE="curation.json"
+  return 0
+}
+
+df_curation_move_key() {
+  local _root="$1" _hash=5381 _i=0 _len=0 _char="" _byte=0 _start=0 _hex="" _tail="" _lc_set=0 _lc_old=""
+  if [ "${LC_ALL+set}" = "set" ]; then _lc_set=1; _lc_old="$LC_ALL"; fi
+  LC_ALL=C
+  _len=${#_root}
+  if [ "$_len" -gt 4096 ]; then
+    if [ "$_lc_set" = 1 ]; then LC_ALL="$_lc_old"; else unset LC_ALL; fi
+    return 1
+  fi
+  while [ "$_i" -lt "$_len" ]; do
+    _char="${_root:$_i:1}"
+    printf -v _byte '%d' "'$_char"
+    _hash=$(( (_hash * 33 + (_byte & 255)) & 4294967295 ))
+    _i=$((_i + 1))
+  done
+  printf -v _hex '%08x' "$_hash"
+  if [ "$_len" -gt 60 ]; then _start=$((_len - 60)); fi
+  _tail="${_root:$_start}"
+  _tail="${_tail//[^A-Za-z0-9]/_}"
+  if [ "$_lc_set" = 1 ]; then LC_ALL="$_lc_old"; else unset LC_ALL; fi
+  DF_CURATION_MOVE_KEY="${_hex}_${_tail}"
+  return 0
+}
+
+df_curation_move_plain() {
+  local _text="$1" _lc_set=0 _lc_old=""
+  if [ "${LC_ALL+set}" = "set" ]; then _lc_set=1; _lc_old="$LC_ALL"; fi
+  LC_ALL=C
+  _text="${_text//$'\xc2'[$'\x80'-$'\x9f']/ }"
+  _text="${_text//[[:cntrl:]]/ }"
+  if [ "$_lc_set" = 1 ]; then LC_ALL="$_lc_old"; else unset LC_ALL; fi
+  DF_CURATION_MOVE_PLAIN="$_text"
+  return 0
+}
+
+# The marker paths of the key in DF_CURATION_MOVE_KEY, built here and nowhere else. The
+# refused marker keeps the file suffix `.skip` (getCurationMoveMarkerPath in
+# src/core/curation-move-notice.ts).
+_df_cm_markers() {
+  local _stem="$HOME/.devflow/logs/curation-move.${DF_CURATION_MOVE_KEY}"
+  DF_CM_REFUSED_MARKER="${_stem}.skip"
+  DF_CM_BUSY_MARKER="${_stem}.busy"
+  DF_CM_TRACKED_MARKER="${_stem}.tracked"
+  DF_CM_UNKNOWN_MARKER="${_stem}.unknown"
+  return 0
+}
+
+# True when anything stands at $1. A link counts as a marker and is never followed.
+_df_cm_present() {
+  [ -e "$1" ] || [ -L "$1" ]
+}
+
+# Remove the marker at $1. It forks only when one stands there.
+_df_cm_clear() {
+  if _df_cm_present "$1"; then rm -f "$1" 2>/dev/null || true; fi
+  return 0
+}
+
+# Create the marker at $1 under noclobber, which is put back as it was. A marker that
+# cannot be written is ignored: the next event looks again.
+_df_cm_mark() {
+  local _noclobber=0
+  case $- in *C*) _noclobber=1 ;; esac
+  if ! _df_cm_present "$1"; then
+    set -o noclobber
+    { : > "$1"; } 2>/dev/null || true
+    if [ "$_noclobber" = 0 ]; then set +o noclobber; fi
+  fi
+  return 0
+}
+
+# Log the one line for a move: $1 is the op's whole answer, $2 its first line (`moved <mode>`).
+# The lines after it are `backup <name>` and `note <text>`; at most 32 are read.
+_df_cm_report_moved() {
+  local _out="$1" _first="$2" _rest="" _line="" _backup="" _notes="" _n=0
+  _rest="${_out#*$'\n'}"
+  if [ "$_rest" = "$_out" ]; then _rest=""; fi
+  while [ -n "$_rest" ] && [ "$_n" -lt 32 ]; do
+    _line="${_rest%%$'\n'*}"
+    case "$_line" in
+      "backup "*) df_curation_move_plain "${_line#backup }"; _backup=", backup folder $DF_CURATION_MOVE_PLAIN" ;;
+      "note "*) df_curation_move_plain "${_line#note }"; _notes="${_notes:+$_notes; }$DF_CURATION_MOVE_PLAIN" ;;
+    esac
+    if [ "$_line" = "$_rest" ]; then _rest=""; else _rest="${_rest#*$'\n'}"; fi
+    _n=$((_n + 1))
+  done
+  if declare -F log >/dev/null 2>&1; then
+    log "Curation move (${_first#moved })${_backup}${_notes:+: $_notes}"
+  fi
+  return 0
+}
+
+# Log the refusal in $1 (the op's first line) and write the refused marker.
+_df_cm_mark_refused() {
+  if declare -F log >/dev/null 2>&1; then
+    log "Curation move refused: ${1:0:200}; not tried again until the next session start"
+  fi
+  _df_cm_mark "$DF_CM_REFUSED_MARKER"
+  return 0
+}
+
+# Set DF_CM_CAUSE to the fixed word of the `cause <word>` line in the op's whole answer $1
+# (lowercase letters and hyphens, at most 32 bytes), or to "" when there is none.
+_df_cm_cause() {
+  local _rest="${1#*$'\n'}" _word=""
+  DF_CM_CAUSE=""
+  if [ "$_rest" = "$1" ]; then return 0; fi
+  case "${_rest%%$'\n'*}" in
+    "cause "*) _word="${_rest%%$'\n'*}"; _word="${_word#cause }" ;;
+  esac
+  case "$_word" in
+    ""|*[!a-z-]*) ;;
+    *) if [ "${#_word}" -le 32 ]; then DF_CM_CAUSE="$_word"; fi ;;
+  esac
+  return 0
+}
+
+# Log the skip for reason $1 (`tracked` or `unknown`), write its marker and record the
+# reason in DF_CURATION_MOVE_SKIPPED. $2 is the op's whole answer, whose cause word the
+# `unknown` line carries. The log words are fixed: they hold nothing from the project.
+_df_cm_mark_skipped() {
+  local _why="$1" _words="" _marker=""
+  DF_CURATION_MOVE_SKIPPED="$_why"
+  case "$_why" in
+    tracked)
+      _words="git tracks files in the .devflow data folders"
+      _marker="$DF_CM_TRACKED_MARKER" ;;
+    *)
+      _df_cm_cause "${2:-}"
+      _words="git did not answer${DF_CM_CAUSE:+ ($DF_CM_CAUSE)}"
+      _marker="$DF_CM_UNKNOWN_MARKER" ;;
+  esac
+  if declare -F log >/dev/null 2>&1; then
+    log "Curation move skipped: $_words; not tried again until the next session start"
+  fi
+  _df_cm_mark "$_marker"
+  return 0
+}
+
+df_curation_move() {
+  local _root="$1" _retry="${2:-}"
+  local _devflow="" _back="$PWD" _real="" _home_real="" _machine_real=""
+  local _helper="" _out="" _rc=0 _first="" _marker=""
+
+  DF_CURATION_MOVE_SKIPPED=""
+  [ -n "$_root" ] || return 0
+  [ -n "${HOME:-}" ] || return 0
+  df_curation_move_names
+  _devflow="$_root/.devflow"
+
+  # 1. The steady state: no old folder (a link or a file at its name counts as
+  # present, so the op can refuse it).
+  if [ ! -e "$_devflow/$DF_CM_OLD_FOLDER" ] && [ ! -L "$_devflow/$DF_CM_OLD_FOLDER" ]; then
+    return 0
+  fi
+
+  # 2. The refusals that need no fork. The physical paths are compared, because the
+  # root, HOME and a repository's toplevel reach here by different routes (on macOS
+  # /var is /private/var): cd -P publishes the resolved path in $PWD.
+  [ -d "$_root" ] || return 0
+  if [ -L "$_root" ]; then return 0; fi
+  if cd -P "$_root" 2>/dev/null; then _real="$PWD"; fi
+  if cd -P "$HOME" 2>/dev/null; then _home_real="$PWD"; fi
+  if cd -P "$HOME/.devflow" 2>/dev/null; then _machine_real="$PWD"; fi
+  cd "$_back" 2>/dev/null || true
+  [ -n "$_real" ] || return 0
+  if [ "$_real" = "$_home_real" ] || [ "$_real" = "$_machine_real" ]; then return 0; fi
+  if ! df_no_symlink_below "$_root" "$_devflow"; then return 0; fi
+
+  # 3. The markers.
+  df_curation_move_key "$_root" || return 0
+  _df_cm_markers
+  set -- "$DF_CM_REFUSED_MARKER" "$DF_CM_BUSY_MARKER" "$DF_CM_TRACKED_MARKER" "$DF_CM_UNKNOWN_MARKER"
+  if [ "$_retry" = "retry" ]; then
+    for _marker in "$@"; do _df_cm_clear "$_marker"; done
+  fi
+  for _marker in "$@"; do
+    if _df_cm_present "$_marker"; then return 0; fi
+  done
+
+  # 4. The one fork. 2>&1 so a refusal's message reaches the log line.
+  _helper="${BASH_SOURCE[0]%/*}/json-helper.cjs"
+  _out=$(node "$_helper" move-ledger "$_root" 2>&1) || _rc=$?
+  df_curation_move_plain "${_out%%$'\n'*}"
+  _first="$DF_CURATION_MOVE_PLAIN"
+
+  if [ "$_rc" -eq 0 ]; then
+    case "$_first" in
+      busy|none) return 0 ;;
+      "busy claim") _df_cm_mark "$DF_CM_BUSY_MARKER"; return 0 ;;
+      "skipped tracked") _df_cm_mark_skipped tracked; return 0 ;;
+      "skipped unknown") _df_cm_mark_skipped unknown "$_out"; return 0 ;;
+      "moved "*) _df_cm_report_moved "$_out" "$_first"; return 0 ;;
+    esac
+  fi
+  _df_cm_mark_refused "$_first"
+  return 0
+}