devflow-kit 3.7.0 → 3.9.0

package/src/assets/scripts/hooks/ensure-devflow-init

@@ -3,7 +3,9 @@
 # ignores .devflow/. Called from capture-prompt, capture-turn, capture-question,
 # memory-worker, and pre-compact-memory. Idempotent.
 # Returns non-zero, having written nothing, outside a git project, at HOME, or when
-# .devflow is a symbolic link.
+# .devflow is a symbolic link. Also non-zero when it is given no root, when the ledger
+# folder check fails (df_ledger_folder), and when the scaffold folders cannot be made.
+# A missing curation-move shim is no failure: the ledger folder step is skipped.
 # Usage: source ensure-devflow-init "$CWD"
 
 [ -z "$1" ] && return 1
@@ -24,12 +26,14 @@ _EDI_LEDGER="${DF_LEDGER_ROOT:-$_EDI_ROOT}"
 # `.git` of its own, so it is refused rather than scaffolded. This is the one gate every capture and
 # memory caller (capture-prompt, capture-turn, capture-question, memory-worker,
 # pre-compact-memory) passes through before it writes, and each of them treats a
-# non-zero return as "stop" (`|| exit 0`), so memory and learning stop together
+# non-zero return as "stop" (`|| exit 0`), so memory and curation stop together
 # in a non-git directory. ensure-root-gitignore itself stays ungated: it is a
 # pure writer its parity suite runs in plain directories, and both of
-# its callers now decide before reaching it. A helper that failed to source is a
-# command not found — the refusing branch, so the failure mode writes nothing.
-source "$_EDI_DIR/git-marker" 2>/dev/null || true
+# its callers now decide before reaching it. A helper that is missing is a
+# command not found — the refusing branch, so the failure mode writes nothing. Each
+# source is guarded by a builtin readability test: bash 3.2 under `set -e` ends the
+# shell at a `source` of a missing file, even inside `|| true`.
+[ -r "$_EDI_DIR/git-marker" ] && source "$_EDI_DIR/git-marker" 2>/dev/null || true
 df_is_project_root "$_EDI_ROOT" 2>/dev/null || return 1
 
 _DEVFLOW_DIR="$_EDI_ROOT/.devflow"
@@ -45,32 +49,60 @@ if ! df_no_symlink_below "$_EDI_ROOT" "$_DEVFLOW_DIR"; then
   return 1
 fi
 
-# learning/ is scaffolded only where the ledger lives. In a linked worktree whose
+# The one-time move of the old learning/ ledger folder to curation/ (curation-move):
+# before anything below reads or creates the ledger folder, on the LEDGER root (the
+# main worktree's, in a linked worktree), and whether or not the curation switch is
+# on. A move another process holds, or a refused one, leaves the old folder where it
+# is; the creator rule below then takes the old folder as the ledger folder. A shim that
+# is missing skips the move, and the ledger folder step below.
+[ -r "$_EDI_DIR/curation-move" ] && source "$_EDI_DIR/curation-move" 2>/dev/null || true
+df_curation_move "$_EDI_LEDGER" 2>/dev/null || true
+
+# curation/ is scaffolded only where the ledger lives. In a linked worktree whose
 # main checkout holds the ledger (D-LEDGER-MAIN-WORKTREE, resolve-project-root) a
-# learning/ here would be an empty directory nothing writes to; the capture hooks
-# create the ledger's own learning/ at the ledger root when they append to it.
-_EDI_LEARNING="$_DEVFLOW_DIR/learning"
-[ "$_EDI_LEDGER" = "$_EDI_ROOT" ] || _EDI_LEARNING=""
+# curation/ here would be an empty directory nothing writes to; the capture hooks
+# create the ledger's own curation/ at the ledger root when they append to it.
+# The creator rule (git-marker, df_make_ledger_folder): the folder made is the new one
+# only when the old name is absent, so a new folder never hides an old ledger, and a
+# creator never makes the old folder. The names come from the move shim
+# (df_curation_move_names), the one shell place that holds them. Either name satisfies
+# the fast path below, so a root whose old folder is still there (held, refused or not
+# yet tried) forks no mkdir.
+# Without the shim there are no names, and this step has no ledger folder to check or
+# make: the rest of the scaffold goes on.
+_EDI_CURATION=""
+if df_curation_move_names 2>/dev/null; then
+  df_ledger_folder "$_DEVFLOW_DIR" "$DF_CM_OLD_FOLDER" "$DF_CM_NEW_FOLDER" || return 1
+  _EDI_CURATION="$DF_LEDGER_FOLDER"
+  [ "$_EDI_LEDGER" = "$_EDI_ROOT" ] || _EDI_CURATION=""
+fi
 
 # Fast-path: if all subdirectories already exist, skip mkdir and gitignore setup.
 # The marker is the CURRENT carve-out version (D-GITIGNORE-V6), bumped with both
 # writers' stamps, so a v5-stamped project misses this once and gains the
 # `!.devflow/project.json` line.
 if [ -d "$_DEVFLOW_DIR/memory" ] && [ -d "$_DEVFLOW_DIR/docs" ] && \
-   { [ -z "$_EDI_LEARNING" ] || [ -d "$_EDI_LEARNING" ]; } && \
+   { [ -z "$_EDI_CURATION" ] || [ -d "$_EDI_CURATION" ]; } && \
    [ -d "$_DEVFLOW_DIR/features" ] && \
    [ -f "$_DEVFLOW_DIR/.root-gitignore-configured-v6" ]; then
   return 0
 fi
 
-# Create all subdirectories
+# Create all subdirectories. The ledger folder is made by its own guarded creator, never
+# by this mkdir: a probe that saw the old folder must not bring it back after a move.
 mkdir -p \
   "$_DEVFLOW_DIR/memory" \
-  ${_EDI_LEARNING:+"$_EDI_LEARNING"} \
   "$_DEVFLOW_DIR/features" \
   "$_DEVFLOW_DIR/docs" \
   2>/dev/null || return 1
 
+# A ledger folder that could not be made leaves the memory scaffold as it is, and the
+# next event looks again. A link on its path makes the capture hooks refuse its queue;
+# after a failed mkdir, the append makes the folder again, as its creator.
+if [ -n "$_EDI_CURATION" ]; then
+  df_make_ledger_folder "$_EDI_ROOT" "$_DEVFLOW_DIR" "$DF_CM_OLD_FOLDER" "$DF_CM_NEW_FOLDER" || true
+fi
+
 # One-time root .gitignore setup — delegated to the sibling ensure-root-gitignore
 # helper (single source of truth) so the always-on, memory-independent
 # session-start-context hook applies the identical rule. _EDI_DIR and _EDI_ROOT

package/src/assets/scripts/hooks/ensure-proxy

@@ -22,7 +22,7 @@
 dbg() { :; }
 
 # Re-entrancy guard — must come before hook-bootstrap to minimize overhead
-# in background worker sessions (claude -p for memory / learning workers fire hooks too)
+# in background worker sessions (claude -p for memory / curation workers fire hooks too)
 if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then exit 0; fi
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -266,11 +266,11 @@ fi
 # Acquire spawn lock — prevents concurrent sessions from double-spawning the relay
 # Stale break: 30s (lock abandoned by crashed hook)
 source "$SCRIPT_DIR/get-mtime" 2>/dev/null || true
-source "$SCRIPT_DIR/learning-lock" 2>/dev/null || true
+source "$SCRIPT_DIR/curation-lock" 2>/dev/null || true
 
 SPAWN_LOCK="$MACHINE_DEVFLOW_DIR/.proxy-spawn.lock"
 
-if ! learning_lock_acquire "$SPAWN_LOCK" 2 2>/dev/null; then
+if ! curation_lock_acquire "$SPAWN_LOCK" 2 2>/dev/null; then
   # Another session is racing to start the proxy — give it a moment then re-probe
   log "spawn lock busy — another session may be starting proxy"
   sleep 1
@@ -339,7 +339,7 @@ while [ "$_i" -lt 80 ]; do
   _i=$(( _i + 1 ))
 done
 
-learning_lock_release "$SPAWN_LOCK"
+curation_lock_release "$SPAWN_LOCK"
 
 if [ "$_RELAY_UP" = "true" ]; then
   log "relay ready after $(( _i + 1 )) probe(s)"

package/src/assets/scripts/hooks/ensure-root-gitignore

@@ -2,7 +2,7 @@
 # ensure-root-gitignore — single source of truth for the project root .gitignore
 # rules that govern .devflow/.
 #
-# .devflow/ holds per-developer runtime state (memory, learning, docs, locks) —
+# .devflow/ holds per-developer runtime state (memory, curation, docs, locks) —
 # local by default. FOUR exceptions are shared via git:
 # 1. Feature knowledge bases under .devflow/features/: index.md and every
 #    {slug}/KNOWLEDGE.md (tracked, committed by the Knowledge agent at workflow end).
@@ -22,9 +22,9 @@
 # so git never descends and later negations are dead. Hence the multi-line block.
 #
 # Sourced by:
-#   - ensure-devflow-init (reached via the memory/learning hooks)
+#   - ensure-devflow-init (reached via the memory/curation hooks)
 #   - session-start-context (always-on, memory-independent — covers memory-off
-#     projects that still use learning/knowledge)
+#     projects that still use curation/knowledge)
 # Both reach this one writer so the rule is applied identically everywhere; this
 # decouples git-tracking of .devflow/ from any single feature toggle.
 #
@@ -201,7 +201,7 @@ mkdir -p "$_ERG_DEVFLOW_DIR" 2>/dev/null || return 1
 # DEVFLOW_GITIGNORE_BLOCK_WITHOUT_CLAUDEIGNORE in
 # src/targets/claude-code/post-install.ts.
 printf -v _ERG_BLOCK_NO_CI '%s\n' \
-  '# Devflow runtime data — local by default (memory, learning, docs, locks).' \
+  '# Devflow runtime data — local by default (memory, curation, docs, locks).' \
   '# Shared via git: feature knowledge bases under .devflow/features/ (index.md and' \
   '# every {slug}/KNOWLEDGE.md), .devflow/conventions.md (naming authority),' \
   '# .devflow/policy.json (retired; presence only) and .devflow/project.json (team settings).' \

package/src/assets/scripts/hooks/git-marker

@@ -133,3 +133,84 @@ df_file_below() {
   fi
   return 1
 }
+
+# df_ledger_folder <devflow_dir> <old> [<new>] — sets DF_LEDGER_FOLDER to the path of
+# the ledger folder a creator may create or write into: <devflow_dir>/<old> while that
+# name is present (a folder, a file or a link, dangling or not), else
+# <devflow_dir>/<new>. <new> defaults to <old>, so a caller that names only the old
+# folder gets the old folder's path in every state.
+#
+# The creator rule: a creator makes the new folder only when the old name is absent.
+# A new folder made beside a present old one would hide the old ledger from every
+# reader, so the session-start heal, the ensure-devflow-init scaffold and queue
+# append all take their folder from here. It answers a path and creates nothing; the
+# caller checks the path with df_no_symlink_below and creates it.
+#
+# Zero forks: builtin tests and parameter expansion only. It always returns 0; read
+# the answer from DF_LEDGER_FOLDER, not from a command substitution.
+df_ledger_folder() {
+  local _dir="$1" _old="$2" _new="${3:-$2}"
+  if [ -e "$_dir/$_old" ] || [ -L "$_dir/$_old" ]; then
+    DF_LEDGER_FOLDER="$_dir/$_old"
+  else
+    DF_LEDGER_FOLDER="$_dir/$_new"
+  fi
+  return 0
+}
+
+# df_ledger_queue <queue_file> <old> [<new>] — sets DF_LEDGER_QUEUE to the queue file
+# a creator may append to. A queue file whose folder is named <old> or <new> is
+# answered under the folder df_ledger_folder picks for that folder's parent; a queue
+# in any other folder (the memory queue) and a path with fewer than two parts come
+# back unchanged. <new> defaults to <old>. Creates nothing; zero forks; returns 0.
+df_ledger_queue() {
+  local _file="$1" _old="$2" _new="${3:-$2}" _folder="" _parent="" _name=""
+  DF_LEDGER_QUEUE="$_file"
+  case "$_file" in */*/*) ;; *) return 0 ;; esac
+  _folder="${_file%/*}"
+  _parent="${_folder%/*}"
+  _name="${_folder##*/}"
+  case "$_name" in
+    "$_old"|"$_new")
+      df_ledger_folder "$_parent" "$_old" "$_new"
+      DF_LEDGER_QUEUE="$DF_LEDGER_FOLDER/${_file##*/}"
+      ;;
+  esac
+  return 0
+}
+
+# df_make_ledger_folder <root> <devflow_dir> <old> <new> — the one creator of the
+# ledger folder for a hook. It sets DF_LEDGER_FOLDER as df_ledger_folder does, then
+# makes the NEW folder and only the new one, and only where the old name is absent at
+# the probe and no link sits on the way down from <root> (df_no_symlink_below). Where
+# the old name is present it makes nothing, so a creator never makes the old folder:
+# a `mkdir -p` on it would bring back an empty old folder beside the new one after a
+# move had renamed it away. It logs nothing, so each hook words its own skip once.
+# A predicate: it returns 0 when nothing is left to make or the folder was made, 2 for
+# a link on the path (nothing is made), and 1 for an empty argument or a failed mkdir.
+# Call it in an `if` or an `||` list, never as a plain statement under `set -e`.
+#
+# The remaining window is the gap between the probe and the mkdir. A move that
+# finishes inside it leaves no folder this time, and the next event makes the new one.
+# An old folder that appears inside it, from an older install or by hand, leaves the
+# new folder beside it, and the next move merges the two. No data is lost either way:
+# the helper only ever makes an empty folder, and never writes into or removes one.
+df_make_ledger_folder() {
+  local _root="$1" _dir="$2" _old="$3" _new="$4"
+  [ -n "$_root" ] && [ -n "$_dir" ] && [ -n "$_old" ] && [ -n "$_new" ] || return 1
+  df_ledger_folder "$_dir" "$_old" "$_new"
+  [ "$DF_LEDGER_FOLDER" = "$_dir/$_new" ] || return 0
+  if ! df_no_symlink_below "$_root" "$DF_LEDGER_FOLDER"; then return 2; fi
+  if [ -d "$DF_LEDGER_FOLDER" ]; then return 0; fi
+  mkdir -p "$DF_LEDGER_FOLDER" 2>/dev/null || return 1
+  return 0
+}
+
+# df_global_tuning_file <machine_dir> — sets DF_GLOBAL_TUNING_FILE to the global
+# curate-agent tuning file inside the machine directory (~/.devflow). The shell
+# twin of getGlobalCurateTuningConfigPath in src/core/project-paths.ts: the one
+# place a hook names the file. Zero forks; returns 0.
+df_global_tuning_file() {
+  DF_GLOBAL_TUNING_FILE="$1/curation.json"
+  return 0
+}