devflow-kit 2.5.0 → 3.0.1

package/src/assets/scripts/hooks/json-helper.cjs

@@ -199,11 +199,16 @@ function isCollisionScanExcluded(relPath) {
  * project root is not a git working tree or the `git` binary is unavailable;
  * callers fall back to `listFsWalkFiles`.
  *
+ * D-NO-FSMONITOR: `ls-files` reads the index, and reading the index runs the
+ * command a repository's config names in `core.fsmonitor` — code chosen by the
+ * repository this hook runs inside. The call turns it off for itself
+ * (`-c core.fsmonitor=false`), so the listing stays a pure read.
+ *
  * @param {string} projectRoot
  * @returns {string[]} project-relative paths
  */
 function listGitTrackedFiles(projectRoot) {
-  const out = execFileSync('git', ['ls-files', '-z'], {
+  const out = execFileSync('git', ['-c', 'core.fsmonitor=false', 'ls-files', '-z'], {
     cwd: projectRoot,
     stdio: ['ignore', 'pipe', 'ignore'],
   });

package/src/assets/scripts/hooks/lib/project-paths.cjs

@@ -174,23 +174,6 @@ function getHandoffPath(projectRoot, branchSlug) {
   return path.join(projectRoot, '.devflow', 'docs', `handoff-${branchSlug}.md`);
 }
 
-// ---------------------------------------------------------------------------
-// Gitignore entries
-// ---------------------------------------------------------------------------
-
-/**
- * The canonical list of generic gitignore entries Devflow adds to a project's
- * root .gitignore for LOCAL-scope installs. Currently just `.claude/`.
- *
- * `.devflow/` is intentionally NOT here: it is managed by ensureDevflowGitignore
- * (TS) / ensure-root-gitignore (hook), which write the feature-knowledge carve-out
- * for ALL scopes. Adding a bare `.devflow/` here would append a wholesale-ignore
- * line after the carve-out and re-bury it (last match wins in .gitignore).
- */
-function getGitignoreEntries() {
-  return ['.claude/'];
-}
-
 module.exports = {
   // Core directories
   getMemoryDir,
@@ -225,6 +208,4 @@ module.exports = {
   getDesignDir,
   getResearchDir,
   getHandoffPath,
-  // Gitignore entries
-  getGitignoreEntries,
 };

package/src/assets/scripts/hooks/log-paths

@@ -2,11 +2,88 @@
 # Shared log path computation for Devflow hooks.
 # Source this file to get devflow_log_dir function.
 
+# D-LOG-DIR-CAP (hook side). Every hook logs under ~/.devflow/logs/<cwd-slug>/,
+# one folder per working directory, and `devflow init` prunes them to the
+# MAX_HOOK_LOG_DIRS most recent (src/core/hook-log-dirs.ts). A machine that never
+# re-inits would still grow without bound, so devflow_log_dir also prunes — but
+# ONLY when it creates a new folder, which is rare: the common path (the folder
+# already exists) pays nothing. The pass is bounded (one `ls`, at most
+# _DF_LOG_DIRS_SCANNED_MAX entries read, _DF_LOG_DIRS_PRUNED_PER_CALL removed in
+# one `rm`), bash 3.2 compatible, and never spawns node. Only directories are
+# counted or removed: root files (proxy.log) and symbolic links are left alone.
+#
+# Recency: folders are ranked by their own mtime (`ls -t`), which an append to a
+# log inside does not move, so a candidate is spared when any of its first
+# _DF_LOG_FILES_READ_PER_DIR entries is newer than the oldest folder the cap
+# keeps (`-nt`, a shell builtin). A spared folder can leave the count briefly
+# above the cap; init's exact prune settles it.
+#
+# _DF_MAX_HOOK_LOG_DIRS must equal MAX_HOOK_LOG_DIRS (tests/hook-log-paths.test.ts).
+_DF_MAX_HOOK_LOG_DIRS=200
+_DF_LOG_DIRS_PRUNED_PER_CALL=50
+_DF_LOG_DIRS_SCANNED_MAX=100000
+_DF_LOG_FILES_READ_PER_DIR=64
+
 # Cache the computed log dir path to avoid spawning 4 subprocesses (sed+tr+mkdir+chmod)
 # on every call within the same hook process.
 _LOG_DIR_CACHED=""
 _LOG_DIR_CACHED_CWD=""
 
+# _df_log_dir_is_recent <dir> <cutoff>
+# True when one of the first _DF_LOG_FILES_READ_PER_DIR entries in <dir> is newer
+# than <cutoff>. Globbing must be on.
+_df_log_dir_is_recent() {
+  local _dir="$1" _cutoff="$2" _f _read=0
+  for _f in "$_dir"/.[!.]* "$_dir"/..?* "$_dir"/*; do
+    [ "$_read" -lt "$_DF_LOG_FILES_READ_PER_DIR" ] || break
+    [ -e "$_f" ] || [ -L "$_f" ] || continue
+    _read=$((_read + 1))
+    if [ "$_f" -nt "$_cutoff" ]; then return 0; fi
+  done
+  return 1
+}
+
+# _df_prune_log_dirs <logs-root> <just-created-dir>
+# Remove the oldest folders beyond _DF_MAX_HOOK_LOG_DIRS, at most
+# _DF_LOG_DIRS_PRUNED_PER_CALL of them. Never fails the caller.
+_df_prune_log_dirs() {
+  local _logs="$1" _new="$2"
+  local _listing _name _n=0 _i _removed=0 _cutoff _d _glob_off=0
+  local -a _dirs _batch
+  _listing=$(ls -1At "$_logs" 2>/dev/null) || return 0
+
+  case $- in *f*) _glob_off=1 ;; esac
+  local IFS='
+'
+  set -f
+  for _name in $_listing; do
+    [ "$_n" -lt "$_DF_LOG_DIRS_SCANNED_MAX" ] || break
+    case "$_name" in */*) continue ;; esac
+    [ -L "$_logs/$_name" ] && continue
+    [ -d "$_logs/$_name" ] || continue
+    _dirs[_n]="$_logs/$_name"
+    _n=$((_n + 1))
+  done
+  set +f
+
+  if [ "$_n" -gt "$_DF_MAX_HOOK_LOG_DIRS" ]; then
+    _cutoff="${_dirs[_DF_MAX_HOOK_LOG_DIRS - 1]}"
+    _i=$((_n - 1))
+    while [ "$_i" -ge "$_DF_MAX_HOOK_LOG_DIRS" ] && [ "$_removed" -lt "$_DF_LOG_DIRS_PRUNED_PER_CALL" ]; do
+      _d="${_dirs[_i]}"
+      if [ "$_d" != "$_new" ] && ! _df_log_dir_is_recent "$_d" "$_cutoff"; then
+        _batch[_removed]="$_d"
+        _removed=$((_removed + 1))
+      fi
+      _i=$((_i - 1))
+    done
+    if [ "$_removed" -gt 0 ]; then rm -rf -- "${_batch[@]}" 2>/dev/null || true; fi
+  fi
+
+  if [ "$_glob_off" = 1 ]; then set -f; fi
+  return 0
+}
+
 devflow_log_dir() {
   local cwd="$1"
   if [ "$cwd" = "$_LOG_DIR_CACHED_CWD" ] && [ -n "$_LOG_DIR_CACHED" ]; then
@@ -16,8 +93,11 @@ devflow_log_dir() {
   local slug
   slug=$(echo "$cwd" | sed 's|^/||' | tr '/' '-')
   local dir="$HOME/.devflow/logs/$slug"
+  local created=0
+  [ -d "$dir" ] || created=1
   mkdir -p "$dir"
   chmod 700 "$dir"
+  if [ "$created" = 1 ]; then _df_prune_log_dirs "$HOME/.devflow/logs" "$dir" || true; fi
   _LOG_DIR_CACHED="$dir"
   _LOG_DIR_CACHED_CWD="$cwd"
   echo "$dir"

package/src/assets/scripts/hooks/memory-worker

@@ -2,9 +2,11 @@
 
 # Memory pipeline: memory-worker (Stop Hook)
 # Owns the 120s-throttle + nohup-spawn logic for background-memory-update.
-# Registered AFTER capture-turn in the Stop hook array so append-before-spawn
-# ordering is preserved by array position. This hook does NOT append to any
-# queue itself -- capture-turn already did that earlier in the same Stop event.
+# Claude Code runs a Stop event's hooks in parallel, so this hook may fire
+# before capture-turn has appended this turn's assistant row. That is safe:
+# background-memory-update leaves a user-only queue in place and skips the LLM
+# run (D-QUEUE-NO-ORPHAN-DELETE), and the next run takes the whole turn. This
+# hook does NOT append to any queue itself.
 
 # Safe no-op fallback: must exist before set -e and before hook-bootstrap is sourced.
 dbg() { :; }
@@ -32,18 +34,18 @@ source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
 PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 [ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
 
-# The machine-wide manifest (the memory switch, D-FEATURES-MACHINE-WIDE in
-# queue-append) is user-scope: resolve it from the inherited DEVFLOW_DIR (or
-# ~/.devflow) BEFORE the project-scoped assignment below shadows that value.
-DEVFLOW_MANIFEST="${DEVFLOW_DIR:-$HOME/.devflow}/manifest.json"
-DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
-MEMORY_DIR="$DEVFLOW_DIR/memory"
+# The machine-wide manifest (the memory switch, 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"
 
-# Memory gate: the machine-wide switch gates this hook entirely, read by the
-# helper every memory/learning gate shares (D-FEATURES-MACHINE-WIDE, see
-# queue-append). The per-repo config is never consulted.
+# Memory gate: the machine switch, narrowed by this checkout's project.json /
+# config.json `features.memory`, gates this hook entirely -- read by the helper
+# every memory/learning gate shares (D-FEATURES-NARROW-ONLY, see queue-append).
 source "$SCRIPT_DIR/queue-append" || { echo "memory-worker: failed to source queue-append" >&2; exit 1; }
-queue_read_gates "$DEVFLOW_MANIFEST"
+queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 MEMORY_ENABLED="$_QG_MEMORY"
 
 dbg "MEMORY_ENABLED=$MEMORY_ENABLED"
@@ -99,8 +101,8 @@ touch "$TRIGGER_FILE" 2>/dev/null || true
 
 # Spawn detached worker — nohup + disown so it survives the Stop hook process exit.
 # The manifest path is handed over explicitly: the worker re-checks the memory
-# switch after spawn, and by now DEVFLOW_DIR names the project .devflow (and is
-# what the worker would inherit, were it exported), not the devflow-global root.
+# switch after spawn against the same manifest this hook gated on (and the same
+# checkout's repository files, from the project root it resolves itself).
 nohup "$UPDATER" "$CWD" "$DEVFLOW_MANIFEST" </dev/null >>/dev/null 2>&1 & disown
 
 log "Spawned background-memory-update worker (CWD=$CWD)"

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

@@ -43,23 +43,23 @@ source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
 PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 [ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
 
-# The machine-wide manifest (the memory switch, D-FEATURES-MACHINE-WIDE in
-# queue-append) is user-scope: resolve it from the inherited DEVFLOW_DIR (or
-# ~/.devflow) BEFORE the project-scoped assignment below shadows that value.
-DEVFLOW_MANIFEST="${DEVFLOW_DIR:-$HOME/.devflow}/manifest.json"
-DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
-MEMORY_DIR="$DEVFLOW_DIR/memory"
+# The machine-wide manifest (the memory switch, 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"
 
 # Normal logging
 source "$SCRIPT_DIR/hook-log-init" "pre-compact-memory"
 
-# Memory gate: the machine-wide switch, read by the helper every memory/learning
-# gate shares (D-FEATURES-MACHINE-WIDE, see queue-append). The per-repo config
-# is never consulted.
+# Memory gate: the machine switch, narrowed by this checkout's project.json /
+# config.json `features.memory`, read by the helper every memory/learning gate
+# shares (D-FEATURES-NARROW-ONLY, see queue-append).
 source "$SCRIPT_DIR/queue-append" || { echo "pre-compact-memory: failed to source queue-append" >&2; exit 1; }
-queue_read_gates "$DEVFLOW_MANIFEST"
+queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 if [ "$_QG_MEMORY" != "true" ]; then
-  dbg "EXIT: memory disabled machine-wide"
+  dbg "EXIT: memory disabled"
   exit 0
 fi
 
@@ -79,9 +79,26 @@ TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
   GIT_HEAD_SHA=$(git rev-parse HEAD 2>/dev/null || echo "")
   GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
-  GIT_STATUS=$(git status --porcelain 2>/dev/null | head -30 || echo "")
+  # D-DETACHED-HEAD: a checkout of a commit rather than a branch (`git checkout
+  # <sha>`, bisect, a rebase stop, `git worktree add --detach`, a CI checkout)
+  # prints no branch name. It is labelled `(detached)`, echoing git's own
+  # `(HEAD detached at …)` display and holding no space, so the stamp's
+  # one-token `branch:` field still parses; the backup names it and the bootstrap
+  # below still stamps memory, keyed on the commit it describes. (A branch really
+  # named `(detached)` is legal git and would read the same — accepted: nothing
+  # decides on the label, it only names.) An unborn branch has no HEAD commit,
+  # keeps the empty label, and is still skipped.
+  if [ -z "$GIT_BRANCH" ] && is_hex_sha "$GIT_HEAD_SHA" 40 40; then
+    GIT_BRANCH="(detached)"
+  fi
+  # D-NO-FSMONITOR: `status` and `diff` read the index, and reading the index
+  # runs the command the repository's config names in `core.fsmonitor` — code
+  # chosen by the repository this hook runs inside. Each index read turns it
+  # off for itself (`-c core.fsmonitor=false`); rev-parse, branch and log never
+  # read the index.
+  GIT_STATUS=$(git -c core.fsmonitor=false status --porcelain 2>/dev/null | head -30 || echo "")
   GIT_LOG=$(git log --oneline -10 2>/dev/null || echo "")
-  GIT_DIFF_STAT=$(git diff --stat HEAD 2>/dev/null || echo "")
+  GIT_DIFF_STAT=$(git -c core.fsmonitor=false diff --stat HEAD 2>/dev/null || echo "")
   dbg "GIT_BRANCH=$GIT_BRANCH HEAD=$GIT_HEAD_SHA"
 fi
 
@@ -105,8 +122,12 @@ json_backup_construct \
 log "Wrote backup: $BACKUP_FILE"
 dbg "Wrote backup: $BACKUP_FILE"
 
-# Bootstrap minimal WORKING-MEMORY.md if absent; skip on detached HEAD, unborn branch,
-# or malformed SHA. is_hex_sha 40 40: exactly 40 lowercase hex chars required.
+# 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
+# HEAD bootstraps with a `branch: (detached)` stamp (D-DETACHED-HEAD, above): the
+# stamp's memory-head SHA is what drift detection keys on, and the Context line names
+# the commit by its short SHA, so the first compaction there no longer leaves the
+# session with nothing to restore.
 # 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.
@@ -126,7 +147,11 @@ if [ -n "$GIT_BRANCH" ] && is_hex_sha "$GIT_HEAD_SHA" 40 40; then
       echo "- (none recorded)"
       echo ""
       echo "## Context"
-      echo "- Branch: $GIT_BRANCH"
+      if [ "$GIT_BRANCH" = "(detached)" ]; then
+        echo "- Branch: (detached) @ ${GIT_HEAD_SHA:0:7}"
+      else
+        echo "- Branch: $GIT_BRANCH"
+      fi
       echo "$GIT_LOG" | head -3 | while IFS= read -r line; do
         [ -n "$line" ] && echo "- $line"
       done

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

@@ -24,39 +24,53 @@
 #   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>
-#   Reads BOTH `features.memory` and `features.learning` from the devflow-global
-#   ~/.devflow/manifest.json in at most ONE subprocess fork (AC-P1 -- at most one
-#   gate-read fork per capture hook, not two; none when D-GATES-FAST-PATH
-#   settles it). Sets _QG_MEMORY and _QG_LEARNING ("true"/"false") in the
-#   caller's scope. The two values are newline-separated
+# queue_read_gates <manifest_path> [<root>]
+#   Reads BOTH switches, `memory` and `learning`, in at most ONE subprocess fork
+#   (AC-P1 -- at most one gate-read fork per capture hook, not two; none when
+#   the fast paths settle it). Sets _QG_MEMORY and _QG_LEARNING ("true"/"false")
+#   in the caller's scope. The two values are newline-separated
 #   rather than using a control-character delimiter: they are always the literal
 #   strings "true"/"false", never arbitrary content, so a plain newline split is
 #   unambiguous and easy to review (no invisible bytes hiding in the source).
 #
-#   D-FEATURES-MACHINE-WIDE (src/core/feature-switch.ts): memory and learning are
-#   switched for the WHOLE MACHINE by the manifest alone -- `devflow init` and
-#   `devflow memory|learning --enable/--disable` both write it -- so the answer is
-#   the same in every repo and every non-git cwd. The per-repo
-#   .devflow/config.json is never read here: its old memory/learning keys are
-#   retired, and reading them is what let a feature keep running in every repo
-#   but the one `init --no-<feature>` ran in (#378). 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
-#   same rule isMachineFeatureOn() applies in the CLI.
+#   D-FEATURES-NARROW-ONLY (src/core/feature-switch.ts): a switch is on iff the
+#   machine switch is on AND neither repository file sets `features.<name>` to
+#   the literal `false` -- the rule resolve-settings.cjs folds, held to the same
+#   answers by the shared table tests/fixtures/settings-switch-table.ts (TP-49).
+#   A repository can switch memory or learning off for itself, never back on.
+#     machine   <manifest_path>, the ~/.devflow/manifest.json `devflow init` and
+#               `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
+#               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
+#               `features.memory` / `features.learning`. The retired top-level
+#               keys (`memory`, `learning`, `decisions`) and `features.decisions`
+#               narrow nothing (#378: reading them let a feature run in every repo
+#               but one). An invalid file -- unparseable, over 4096 bytes, a BOM,
+#               a symlink, a duplicated key -- narrows nothing.
+#   <root> is the checkout's toplevel (DF_ROOT, which every caller holds as
+#   $PROJECT_ROOT), for learning too: project.json is committed per branch and
+#   config.json lives per worktree, so both are read where the session runs, as
+#   resolve-settings.cjs reads them -- never at DF_LEDGER_ROOT, which only says
+#   where the queue lands. Without <root> (or with an empty one) no repository
+#   file is read.
 #
-#   D-LEARNING-LEGACY-DECISIONS: learning reads `features.learning` when it is a
-#   boolean, else the pre-rename `features.decisions` (ADR-011) -- 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.
+#   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
+#   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.
 #
 #   Every hook that gates on memory or learning reads it through here: the
 #   capture hooks, session-start-context (Sections 1-2), memory-worker,
 #   session-start-memory, pre-compact-memory and background-memory-update. The
-#   callers resolve <manifest_path> from ${DEVFLOW_DIR:-$HOME/.devflow} BEFORE
-#   they shadow DEVFLOW_DIR with the project-scoped .devflow (memory-worker hands
-#   its resolved path to the background worker it spawns).
+#   callers pass <manifest_path> as $HOME/.devflow/manifest.json, the machine
+#   root (D-ONE-HOME); memory-worker hands its resolved path to the background
+#   worker it spawns.
 
 queue_append_row() {
   local _qar_file="$1" _qar_role="$2" _qar_content="$3" _qar_ts="$4"
@@ -106,8 +120,34 @@ queue_append_both() {
   fi
 }
 
+# _qg_repo_file_can_narrow <file> -- succeeds when <file> COULD set
+# features.memory or features.learning to false, so only the parser can decide
+# it; fails when it certainly cannot. Builtins only: no fork.
+#
+# D-GATES-FAST-PATH (repository files): the read is bounded -- `-n 4097`, which
+# bash 3.2 supports -- and `read -d ''` succeeds only when it stops short of the
+# end of the file: at a NUL byte (never valid in JSON) or at 4097 characters,
+# which is more than MAX_CONFIG_BYTES (4096) bytes. Either way the parser would
+# call the file invalid, and an invalid file narrows nothing. `-f` follows a
+# symlink and refuses a directory or FIFO, so nothing here can block; the parser
+# itself refuses the symlink. A `\u` escape is the only JSON spelling of a
+# letter other than the letter itself, so without one a narrowing file shows
+# `"features"`, then `{`, then `"memory"` or `"learning"`, then `false`,
+# literally and in that order. `.` spans newlines (POSIX ERE without
+# REG_NEWLINE), so the match can only over-report -- an over-report costs one
+# fork and the parser's answer, never a wrong one. No `"decisions"` and no
+# top-level key before `features` is ever matched.
+_qg_repo_file_can_narrow() {
+  local _qgf_text=""
+  local _qgf_re='"features"[[:space:]]*:[[:space:]]*[{].*"(memory|learning)"[[:space:]]*:[[:space:]]*false'
+  [ -f "$1" ] || return 1
+  if IFS= read -r -d '' -n 4097 _qgf_text 2>/dev/null < "$1"; then return 1; fi
+  case "$_qgf_text" in *'\u'*) return 0 ;; esac
+  [[ $_qgf_text =~ $_qgf_re ]]
+}
+
 queue_read_gates() {
-  local _qg_manifest="${1:-}" _qg_text="" _qg_parse="false"
+  local _qg_manifest="${1:-}" _qg_root="${2:-}" _qg_text="" _qg_parse="false" _qg_repo="false" _qg_fields=""
   _QG_MEMORY="true"
   _QG_LEARNING="true"
 
@@ -129,8 +169,38 @@ queue_read_gates() {
     if [[ $_qg_text =~ $_qg_re ]]; then _qg_parse="true"; fi
   fi
 
-  if [ "$_qg_parse" = "true" ]; then
-    local _qg_fields
+  if [ -n "$_qg_root" ]; then
+    if _qg_repo_file_can_narrow "$_qg_root/.devflow/project.json" \
+      || _qg_repo_file_can_narrow "$_qg_root/.devflow/config.json"; then
+      _qg_repo="true"
+    fi
+  fi
+
+  if [ "$_qg_repo" = "true" ]; then
+    # The ONE fork when a repository file can narrow: node on the resolver's own
+    # readRepoLayers + foldSettings (resolve-settings.cjs, a sibling of this
+    # hooks/ directory), so every file rule -- symlink, size, BOM, fatal UTF-8,
+    # duplicate keys -- is the parser's, not a shell copy of it. It folds the
+    # manifest too, read only when the fast path above flagged it (an unflagged
+    # manifest is both-on), so a false in all three layers still costs one fork.
+    # jq cannot see duplicate keys, so this path is node whatever _HAS_JQ says.
+    local _qg_scripts="${BASH_SOURCE[0]%/*}/.." _qg_manifest_arg=""
+    [ "$_qg_parse" = "true" ] && _qg_manifest_arg="$_qg_manifest"
+    _qg_fields=$(node -e "
+      const S = require(require('path').resolve(process.argv[1], 'resolve-settings.cjs'));
+      let m;
+      if (process.argv[2] !== '') {
+        try { m = JSON.parse(require('fs').readFileSync(process.argv[2], 'utf8')); } catch (_) { m = undefined; }
+      }
+      const w = S.foldSettings(Object.assign({ manifest: m }, S.readRepoLayers(process.argv[3]))).switches;
+      process.stdout.write(String(w.memory.on) + String.fromCharCode(10) + String(w.learning.on));
+    " -- "$_qg_scripts" "$_qg_manifest_arg" "$_qg_root" 2>/dev/null) || _qg_fields=""
+  fi
+
+  # The manifest-only parse: when no repository file can narrow, or when the
+  # fork above failed (the manifest's answer still stands; the repository's is
+  # lost, which fails open like every other unreadable layer).
+  if [ -z "$_qg_fields" ] && [ "$_qg_parse" = "true" ]; then
     if [ "$_HAS_JQ" = "true" ]; then
       # `try` covers a manifest whose top level or `features` is not an object; a
       # parse failure empties the output, which reads as "not switched off". The
@@ -150,11 +220,15 @@ queue_read_gates() {
         process.stdout.write(String(on('memory')) + String.fromCharCode(10) + String(on(learnKey)));
       " -- "$_qg_manifest" 2>/dev/null) || _qg_fields=""
     fi
-    if [ -n "$_qg_fields" ]; then
+  fi
+
+  # Only the four well-formed answers are taken; anything else is fail-open.
+  case "$_qg_fields" in
+    true$'\n'true|true$'\n'false|false$'\n'true|false$'\n'false)
       _QG_MEMORY="${_qg_fields%%$'\n'*}"
       _QG_LEARNING="${_qg_fields#*$'\n'}"
-    fi
-  fi
+      ;;
+  esac
 
   # Explicit return: this function's meaning is "populate _QG_* outputs," not a
   # success/failure signal, so its exit status must never leak the truthiness of

package/src/assets/scripts/hooks/resolve-project-root

@@ -9,13 +9,19 @@
 # side anchors identically.
 #
 # Sourced by: the memory/learning/session hooks and ensure-devflow-init.
-# Sourced helper: uses `return`-free pure function; _-prefixed locals (never
+# Sourced helper: uses `return`-free pure functions; _-prefixed locals (never
 # clobbers caller vars). Safe under `set -e` (git failure is guarded with || true).
 #
 # Usage:
 #   source resolve-project-root
-#   PROJECT_ROOT="$(df_resolve_root "$CWD")"
+#   PROJECT_ROOT="$(df_resolve_root "$CWD")"      # one root
+#   df_resolve_roots "$CWD"                        # sets DF_ROOT and DF_LEDGER_ROOT
 #
+# df_resolve_roots needs df_is_project_root, so this helper sources its sibling
+# git-marker itself rather than trusting every caller to have done so first.
+
+source "${BASH_SOURCE[0]%/*}/git-marker" 2>/dev/null || true
+
 # df_resolve_root <cwd> prints the project root for <cwd>:
 #   1. git top-level — git walks up to the real repo root even from a
 #      .devflow/-nested subdir, so the nested case is fixed for git repos.
@@ -27,11 +33,99 @@ df_resolve_root() {
   # the caller (e.g. a non-git path). Empty output then routes to the fallback.
   _root="$(git -C "$_cwd" rev-parse --show-toplevel 2>/dev/null || true)"
   if [ -z "$_root" ]; then
-    case "$_cwd" in
-      */.devflow/*) _root="${_cwd%%/.devflow/*}" ;;
-      */.devflow)   _root="${_cwd%/.devflow}" ;;
-      *)            _root="$_cwd" ;;
-    esac
+    _df_nongit_root "$_cwd"
+    _root="$_DF_NONGIT_ROOT"
   fi
   printf '%s\n' "$_root"
 }
+
+# _df_nongit_root <cwd> sets _DF_NONGIT_ROOT to the non-git fallback root: <cwd>
+# with its first /.devflow/ segment onward (or a trailing /.devflow) stripped.
+# A variable rather than stdout, so a caller pays no `$(...)` subshell for it.
+_df_nongit_root() {
+  case "$1" in
+    */.devflow/*) _DF_NONGIT_ROOT="${1%%/.devflow/*}" ;;
+    */.devflow)   _DF_NONGIT_ROOT="${1%/.devflow}" ;;
+    *)            _DF_NONGIT_ROOT="$1" ;;
+  esac
+}
+
+# df_resolve_roots <cwd> sets TWO roots in the caller's scope, from ONE git call:
+#   DF_ROOT        — the checkout's toplevel: where per-checkout data lives
+#                    (memory, the .gitignore carve-out, the knowledge bases).
+#   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
+# 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
+# being scaffolded by a worktree session. A main worktree at HOME (a dotfiles
+# repository) is refused as well (df_is_project_root, D-HOOKS-GIT-ONLY): its
+# `.devflow` is the machine root, which always exists, so the existence test alone
+# would put the ledger inside `~/.devflow`. A common dir that is not `/.git`
+# (a bare repository, `--separate-git-dir`, a submodule's modules/ dir) has no
+# main checkout to name, so it stays per checkout. Memory stays at DF_ROOT on
+# purpose: working memory describes the branch in front of you. A worktree that
+# already grew its own ledger before this rule keeps it — local data is left in
+# place, and the worktree simply stops appending to it.
+#
+# The one call asks for both answers at once:
+#   git rev-parse --path-format=absolute --show-toplevel --git-common-dir
+# and its output is accepted only when it is EXACTLY two lines, each an absolute
+# path. `--path-format` arrived in git 2.31; an older git echoes the unknown
+# flag back as a line of its own (three lines, the first not absolute), and that
+# falls back to df_resolve_root, so the ledger stays at the toplevel exactly as
+# before this rule. A failed call prints nothing: `--show-toplevel` itself failed
+# (not a work tree), so asking git again could only fail the same way, and the
+# non-git fallback applies directly. Inside a checkout git refuses (dubious
+# ownership, GIT_CEILING_DIRECTORIES) that fallback is the raw cwd, which may be a
+# subdirectory; df_is_project_root refuses any root without its own `.git`
+# (D-HOOKS-TOPLEVEL-ONLY), so no hook scaffolds there. Parsing is parameter expansion and `case`
+# only: one git call on the success path and on the non-git path alike.
+df_resolve_roots() {
+  local _cwd="$1" _out="" _top="" _common="" _main=""
+  DF_ROOT=""
+  DF_LEDGER_ROOT=""
+  _out="$(git -C "$_cwd" rev-parse --path-format=absolute --show-toplevel --git-common-dir 2>/dev/null || true)"
+  _top="${_out%%$'\n'*}"
+  if [ "$_top" != "$_out" ]; then
+    _common="${_out#*$'\n'}"
+  fi
+  case "$_top" in /*) ;; *) _top="" ;; esac
+  case "$_common" in
+    *$'\n'*) _common="" ;;
+    /*) ;;
+    *) _common="" ;;
+  esac
+  if [ -z "$_out" ]; then
+    _df_nongit_root "$_cwd"
+    DF_ROOT="$_DF_NONGIT_ROOT"
+    [ -n "$DF_ROOT" ] || DF_ROOT="$_cwd"
+    DF_LEDGER_ROOT="$DF_ROOT"
+    return 0
+  fi
+  if [ -z "$_top" ] || [ -z "$_common" ]; then
+    DF_ROOT="$(df_resolve_root "$_cwd")"
+    [ -n "$DF_ROOT" ] || DF_ROOT="$_cwd"
+    DF_LEDGER_ROOT="$DF_ROOT"
+    return 0
+  fi
+  DF_ROOT="$_top"
+  DF_LEDGER_ROOT="$_top"
+  case "$_common" in
+    */.git)
+      _main="${_common%/.git}"
+      # df_is_project_root forks nothing (builtin `cd -P` walks). Unavailable —
+      # git-marker failed to source — it is a command not found, which keeps the
+      # ledger in this checkout: the conservative answer.
+      if [ -n "$_main" ] && [ -d "$_main/.devflow" ] && df_is_project_root "$_main" 2>/dev/null; then
+        DF_LEDGER_ROOT="$_main"
+      fi
+      ;;
+  esac
+  return 0
+}