devflow-kit 2.4.0 → 3.0.0

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

@@ -22,18 +22,55 @@
 # 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
-#   from feature config themselves (see queue_read_gates below for the one-fork
-#   combined read that keeps this to a single config subprocess per hook).
+#   themselves (see queue_read_gates below for the at-most-one-fork read of both).
 #
-# queue_read_gates <feature_config_path>
-#   Reads BOTH the "memory" and "learning" fields from .devflow/config.json in a
-#   SINGLE subprocess fork (AC-P1 -- exactly one config-read fork per capture
-#   hook, not two). Sets _QG_MEMORY and _QG_LEARNING ("true"/"false") in the
-#   caller's scope. Missing config file -> both default "true". 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).
+# 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-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: 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 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"
@@ -83,34 +120,115 @@ 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_config="$1"
+  local _qg_manifest="${1:-}" _qg_root="${2:-}" _qg_text="" _qg_parse="false" _qg_repo="false" _qg_fields=""
   _QG_MEMORY="true"
   _QG_LEARNING="true"
 
-  if [ -f "$_qg_config" ]; then
-    local _qg_fields
+  if [ -n "$_qg_manifest" ] && [ -f "$_qg_manifest" ]; then
+    # D-GATES-FAST-PATH: every capture hook and every session start pays this
+    # read, and on most machines both switches are on. Only a JSON boolean
+    # `false` under a "memory", "learning" or "decisions" key can switch anything
+    # off, and a `\u` escape is the only JSON spelling of a letter other than the
+    # letter itself, so without one such a key appears literally. A text holding
+    # no `\u` and no key-then-`false` sequence therefore cannot switch anything
+    # off -- valid or not, it reads both-on either way -- and is settled by shell
+    # builtins (read, case, [[ =~ ]]) with no jq/node fork; everything else takes
+    # the full parse below. `read -d ''` succeeds only on reaching a NUL byte,
+    # i.e. before the end of the file, so a text it cut short is parsed in full
+    # too. An unreadable file reads empty and fails open, as the parser would.
+    local _qg_re='"(memory|learning|decisions)"[[:space:]]*:[[:space:]]*false'
+    IFS= read -r -d '' _qg_text 2>/dev/null < "$_qg_manifest" && _qg_parse="true"
+    case "$_qg_text" in *'\u'*) _qg_parse="true" ;; esac
+    if [[ $_qg_text =~ $_qg_re ]]; then _qg_parse="true"; fi
+  fi
+
+  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
-      # if/then/else (not //) preserves an explicit `false` -- mirrors json_field_file's
-      # own documented rationale (jq's // would replace a real `false` with the default).
-      # The comma produces two raw-output lines (newline-separated) in one jq process.
+      # `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
+      # comma produces two raw-output lines (newline-separated) in one jq process.
       _qg_fields=$(jq -r '
-        (if (.memory | type) == "null" then "true" else (.memory | tostring) end),
-        (if (.learning | type) == "null" then "true" else (.learning | tostring) end)
-      ' "$_qg_config" 2>/dev/null) || _qg_fields=""
+        (if (try .features.memory catch null) == false then "false" else "true" end),
+        (if (try (.features | if (.learning | type) == "boolean" then .learning else .decisions end) catch null) == false
+          then "false" else "true" end)
+      ' "$_qg_manifest" 2>/dev/null) || _qg_fields=""
     else
       _qg_fields=$(node -e "
-        const j = JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'));
-        const m = j.memory === undefined ? 'true' : String(j.memory);
-        const d = j.learning === undefined ? 'true' : String(j.learning);
-        process.stdout.write(m + String.fromCharCode(10) + d);
-      " -- "$_qg_config" 2>/dev/null) || _qg_fields=""
+        const m = JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'));
+        const f = m !== null && typeof m === 'object' ? m.features : undefined;
+        const isObj = f !== null && typeof f === 'object';
+        const on = (k) => !(isObj && f[k] === false);
+        const learnKey = isObj && typeof f.learning !== 'boolean' ? 'decisions' : 'learning';
+        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
+}