devflow-kit 2.5.0 → 3.0.0

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

@@ -39,16 +39,20 @@ devflow_debug_set_cwd "$CWD"
 # Anchor .devflow/ to the project root (prevents a stray nested .devflow/ when this
 # hook runs with a CWD inside .devflow/...). Empty → fall back to CWD.
 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/learning switches, 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"
-LEARNING_DIR="$DEVFLOW_DIR/learning"
+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
+# it is the main worktree's queue (D-LEDGER-MAIN-WORKTREE, resolve-project-root),
+# the one the Learning 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
+# 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"
 
 if [ -z "$PROMPT" ]; then
   dbg "EXIT: empty PROMPT"
@@ -57,8 +61,10 @@ fi
 
 source "$SCRIPT_DIR/queue-append" || { echo "capture-prompt: failed to source queue-append" >&2; exit 1; }
 
-# --- AC-P1: exactly ONE gate-read fork for memory + learning (machine-wide) ---
-queue_read_gates "$DEVFLOW_MANIFEST"
+# --- AC-P1: at most ONE gate-read fork for memory + learning ---
+# 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"
 

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

@@ -58,16 +58,20 @@ if [ -z "$CWD" ] || [ ! -d "$CWD" ]; then dbg "EXIT: bad CWD"; exit 0; fi
 devflow_debug_set_cwd "$CWD"
 
 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/learning switches, 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"
-LEARNING_DIR="$DEVFLOW_DIR/learning"
+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
+# it is the main worktree's queue (D-LEDGER-MAIN-WORKTREE, resolve-project-root),
+# the one the Learning 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
+# 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"
 
 # --- Parse questions + answers into "question<TAB>answer" rows (one subprocess) ---
 # Defensive against: tool_response absent or a plain string (error case), missing
@@ -119,8 +123,10 @@ fi
 
 source "$SCRIPT_DIR/queue-append" || { echo "capture-question: failed to source queue-append" >&2; exit 1; }
 
-# --- AC-P1: exactly ONE gate-read fork for memory + learning (machine-wide) ---
-queue_read_gates "$DEVFLOW_MANIFEST"
+# --- AC-P1: at most ONE gate-read fork for memory + learning ---
+# 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"
 

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

@@ -5,9 +5,9 @@
 # learning queue, each independently gated by its own feature flag (AC-F4). Runs
 # the decisions usage scanner (D29 grep-first) regardless of which queue is
 # gated on/off -- memory-disabled projects still run the usage scanner. The
-# 120s-throttle/nohup-spawn block lives in memory-worker, registered
-# separately in the Stop hook array AFTER this hook so append-before-spawn
-# ordering is preserved by array position, not by anything in this script.
+# 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).
 # This hook never spawns a process (AC-F5).
 
 # Safe no-op fallback: must exist before set -e and before hook-bootstrap is sourced.
@@ -45,16 +45,20 @@ dbg "ASSISTANT_MSG length=${#ASSISTANT_MSG}"
 # Anchor .devflow/ to the project root (prevents a stray nested .devflow/ when this
 # hook runs with a CWD inside .devflow/...). Empty → fall back to CWD.
 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/learning switches, 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"
-LEARNING_DIR="$DEVFLOW_DIR/learning"
+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
+# it is the main worktree's queue (D-LEDGER-MAIN-WORKTREE, resolve-project-root),
+# the one the Learning 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
+# 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"
 
 # Skip if empty response
 if [ -z "$ASSISTANT_MSG" ]; then
@@ -64,8 +68,10 @@ fi
 
 source "$SCRIPT_DIR/queue-append" || { echo "capture-turn: failed to source queue-append" >&2; exit 1; }
 
-# --- AC-P1: exactly ONE gate-read fork for memory + learning (machine-wide) ---
-queue_read_gates "$DEVFLOW_MANIFEST"
+# --- AC-P1: at most ONE gate-read fork for memory + learning ---
+# 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"
 
@@ -73,11 +79,15 @@ dbg "MEMORY_ENABLED=$MEMORY_ENABLED LEARNING_ENABLED=$LEARNING_ENABLED"
 
 # --- Decisions usage scanner (independent of the memory/learning queue gates below) ---
 # D29: Grep-first reorder -- cheap in-process citation check gates the scanner call.
+# The scanner writes the ledger's usage file, and it runs before ensure-devflow-init,
+# so it takes the D-HOOKS-GIT-ONLY gate itself (df_is_project_root, git-marker via
+# resolve-project-root; zero forks): a `.devflow/` an older devflow left in a
+# non-git directory, or at HOME, is not a project's ledger.
 SCANNER="$SCRIPT_DIR/decisions-usage-scan.cjs"
 if [ -f "$SCANNER" ] && printf '%s' "$ASSISTANT_MSG" | grep -qE 'ADR-[0-9]+|PF-[0-9]+'; then
-  if [ "$LEARNING_ENABLED" = "true" ]; then
+  if [ "$LEARNING_ENABLED" = "true" ] && df_is_project_root "$PROJECT_ROOT" 2>/dev/null; then
     dbg "Running decisions usage scanner"
-    printf '%s' "$ASSISTANT_MSG" | node "$SCANNER" --cwd "$PROJECT_ROOT" 2>/dev/null || true
+    printf '%s' "$ASSISTANT_MSG" | node "$SCANNER" --cwd "$LEDGER_ROOT" 2>/dev/null || true
   fi
 fi
 

package/src/assets/scripts/hooks/debug-trace

@@ -61,12 +61,17 @@ devflow_debug_init() {
 devflow_debug_set_cwd() {
   local cwd="$1"
   if [ -z "$cwd" ] || [ "${DEVFLOW_HOOK_DEBUG:-}" != "1" ]; then return; fi
-  # Phase 2: switch to per-project log (only when debug is active)
-  local slug
-  slug=$(echo "$cwd" | sed 's|^/||' | tr '/' '-')
-  local project_log_dir="$HOME/.devflow/logs/$slug"
-  mkdir -p "$project_log_dir" 2>/dev/null || true
-  chmod 700 "$project_log_dir" 2>/dev/null || true
+  # Phase 2: switch to per-project log (only when debug is active). The folder
+  # comes from log-paths' devflow_log_dir, so a folder created here goes through
+  # the same D-LOG-DIR-CAP prune as every other hook log folder. log-paths sits
+  # beside this file; a hook that already sourced it is not re-sourced (that
+  # would reset its cached log dir).
+  if ! declare -F devflow_log_dir >/dev/null 2>&1; then
+    source "$(dirname "${BASH_SOURCE[0]}")/log-paths" 2>/dev/null || return 0
+  fi
+  local project_log_dir
+  project_log_dir=$(devflow_log_dir "$cwd" 2>/dev/null) || project_log_dir=""
+  [ -n "$project_log_dir" ] || return 0
   _DEVFLOW_DBG_LOG="$project_log_dir/.hook-debug.log"
   _devflow_dbg_size_guard "$_DEVFLOW_DBG_LOG"
   dbg() {

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

@@ -2,6 +2,7 @@
 # Ensures .devflow/ and all subdirectories exist and the project root .gitignore
 # 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 or at HOME.
 # Usage: source ensure-devflow-init "$CWD"
 
 [ -z "$1" ] && return 1
@@ -11,23 +12,49 @@
 # by a hook or directly by tests). Empty → fall back to "$1" (old behavior).
 _EDI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$_EDI_DIR/resolve-project-root" 2>/dev/null || true
-_EDI_ROOT="$(df_resolve_root "$1" 2>/dev/null || true)"
-[ -n "$_EDI_ROOT" ] || _EDI_ROOT="$1"
+df_resolve_roots "$1" 2>/dev/null || true
+_EDI_ROOT="${DF_ROOT:-$1}"
+_EDI_LEDGER="${DF_LEDGER_ROOT:-$_EDI_ROOT}"
+
+# D-HOOKS-GIT-ONLY (git-marker): scaffold nothing outside a git project, and
+# nothing at a repository rooted at HOME. D-HOOKS-TOPLEVEL-ONLY (git-marker): nor
+# below a checkout's toplevel — when git refuses the cwd (dubious ownership,
+# GIT_CEILING_DIRECTORIES) the root above is that cwd, and a subdirectory holds no
+# `.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
+# in a non-git directory. ensure-root-gitignore itself stays ungated: it is a
+# pure writer its parity suite runs in plain directories (PF-059), 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
+df_is_project_root "$_EDI_ROOT" 2>/dev/null || return 1
 
 _DEVFLOW_DIR="$_EDI_ROOT/.devflow"
 
-# Fast-path: if all subdirectories already exist, skip mkdir and gitignore setup
+# learning/ 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=""
+
+# 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" ] && \
-   [ -d "$_DEVFLOW_DIR/learning" ] && \
+   { [ -z "$_EDI_LEARNING" ] || [ -d "$_EDI_LEARNING" ]; } && \
    [ -d "$_DEVFLOW_DIR/features" ] && \
-   [ -f "$_DEVFLOW_DIR/.root-gitignore-configured-v5" ]; then
+   [ -f "$_DEVFLOW_DIR/.root-gitignore-configured-v6" ]; then
   return 0
 fi
 
 # Create all subdirectories
 mkdir -p \
   "$_DEVFLOW_DIR/memory" \
-  "$_DEVFLOW_DIR/learning" \
+  ${_EDI_LEARNING:+"$_EDI_LEARNING"} \
   "$_DEVFLOW_DIR/features" \
   "$_DEVFLOW_DIR/docs" \
   2>/dev/null || return 1

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

@@ -3,7 +3,7 @@
 # ensure-proxy — SessionStart + UserPromptSubmit hook
 # Ensures the Devflow proxy relay is running when external model routing is enabled.
 # NOT git-gated (proxy is a global user-scope feature, not per-project).
-# NOT project-scoped: proxy state lives at $DEVFLOW_DIR/proxy.json (user-scope).
+# NOT project-scoped: proxy state lives at $HOME/.devflow/proxy.json (machine-wide).
 #
 # SessionStart:  probe port → if DOWN attempt spawn → inject additionalContext warning if still down
 # UserPromptSubmit: fast exit (both port-up and port-down) — silent; SessionStart handles all warnings
@@ -55,9 +55,10 @@ if [ "$HOOK_EVENT" = "UserPromptSubmit" ]; then
 fi
 
 # ── Proxy state ────────────────────────────────────────────────────────────────
-# Proxy is user-scope (global), not project-scoped. Use $DEVFLOW_DIR (env) or default.
-DEVFLOW_DIR="${DEVFLOW_DIR:-$HOME/.devflow}"
-PROXY_STATE_FILE="$DEVFLOW_DIR/proxy.json"
+# Proxy is machine-wide, not project-scoped: state lives at the machine root,
+# always $HOME/.devflow (D-ONE-HOME).
+MACHINE_DEVFLOW_DIR="$HOME/.devflow"
+PROXY_STATE_FILE="$MACHINE_DEVFLOW_DIR/proxy.json"
 
 if [ ! -f "$PROXY_STATE_FILE" ]; then
   dbg "EXIT: no proxy state file"
@@ -93,7 +94,7 @@ if [ "${DEVFLOW_HOOK_DEBUG:-}" = "1" ]; then
 fi
 
 # ── Log setup (SessionStart only) ──────────────────────────────────────────────
-LOG_DIR="$DEVFLOW_DIR/logs"
+LOG_DIR="$MACHINE_DEVFLOW_DIR/logs"
 mkdir -p "$LOG_DIR" 2>/dev/null || true
 # SEC-2: harden log directory to 0700 (best-effort; pre-existing dirs may be wider).
 chmod 700 "$LOG_DIR" 2>/dev/null || true
@@ -101,7 +102,7 @@ LOG_FILE="$LOG_DIR/proxy.log"
 
 # Size guard: 2MB max → truncate to 1MB tail (matches hook-log-init guard pattern).
 # Sharing hook-log-init is not feasible here: hook-log-init requires $CWD and targets
-# the per-project log path; ensure-proxy uses the user-scope $DEVFLOW_DIR/logs path.
+# the per-project log path; ensure-proxy uses the machine-wide $MACHINE_DEVFLOW_DIR/logs path.
 # The existence guard is required: wc -c uses a shell redirect whose failure is emitted
 # by bash itself (before wc starts), bypassing 2>/dev/null.
 _LOG_MAX_BYTES=2097152
@@ -268,7 +269,7 @@ fi
 source "$SCRIPT_DIR/get-mtime" 2>/dev/null || true
 source "$SCRIPT_DIR/learning-lock" 2>/dev/null || true
 
-SPAWN_LOCK="$DEVFLOW_DIR/.proxy-spawn.lock"
+SPAWN_LOCK="$MACHINE_DEVFLOW_DIR/.proxy-spawn.lock"
 
 if ! learning_lock_acquire "$SPAWN_LOCK" 2 2>/dev/null; then
   # Another session is racing to start the proxy — give it a moment then re-probe
@@ -324,7 +325,7 @@ log "relay spawned with pid $_RELAY_PID"
 # Best-effort pid record for `devflow proxy --status` — mirrors the CLI enable path.
 # Written unconditionally after spawn (like the CLI): a stale pid from a relay that
 # never came up is harmless, since --status liveness-checks it before display.
-printf '%s' "$_RELAY_PID" > "$DEVFLOW_DIR/proxy.pid" 2>/dev/null || \
+printf '%s' "$_RELAY_PID" > "$MACHINE_DEVFLOW_DIR/proxy.pid" 2>/dev/null || \
   log "warn: could not write proxy.pid (non-fatal)"
 
 # Bounded wait: 80×0.1s = 8s maximum (well within 15s hook timeout)

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

@@ -3,13 +3,16 @@
 # rules that govern .devflow/.
 #
 # .devflow/ holds per-developer runtime state (memory, learning, docs, locks) —
-# local by default. THREE exceptions are shared via git:
+# 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).
 # 2. .devflow/conventions.md — naming-convention authority written by the Git
 #    learn-conventions operation; shared so the team uses one naming source.
-# 3. .devflow/policy.json — the team-owned evidence policy, read from the default
-#    branch by resolve-evidence-policy.cjs. Devflow never writes it.
+# 3. .devflow/policy.json — the retired evidence-policy file: never parsed, but
+#    where project.json has no `evidence` its presence holds the repository at
+#    required (D-POLICY-JSON-RETIRED). Devflow never writes it.
+# 4. .devflow/project.json — the team-committed settings both resolvers read
+#    (D-GITIGNORE-V6). Devflow never writes it.
 #
 # Everything else under .devflow/ stays local. A user opts back out of the first two
 # by re-adding `.devflow/features/` or `.devflow/conventions.md` to their own .gitignore.
@@ -25,17 +28,29 @@
 # Both reach this one writer so the rule is applied identically everywhere; this
 # decouples git-tracking of .devflow/ from any single feature toggle (avoids PF-014).
 #
-# Idempotent and O(1) after the first run via the .root-gitignore-configured-v5
+# Idempotent and O(1) after the first run via the .root-gitignore-configured-v6
 # marker under .devflow/ (project-local). The marker is a claim, not proof, so the
-# fast path also requires the block's own sentinel, the policy line AND a
-# .claudeignore entry to be present; a .gitignore that lost any of them (a merge
-# resolution, a hand edit) is healed on the next run. A v4-marked project misses the
-# fast path, gains the policy line and is re-stamped v5.
+# fast path also requires the block's own sentinel, the policy line, the project
+# line AND a .claudeignore entry to be present; a .gitignore that lost any of them (a
+# merge resolution, a hand edit) is healed on the next run. A v5-marked project
+# misses the fast path, gains the project line just before its .claudeignore line
+# and is re-stamped v6 (D-GITIGNORE-V6); a v4-marked one gains the policy and
+# project lines.
 #
-# D-GITIGNORE-V5: the block is detected ONLY by its devflow-unique sentinel
-# `!.devflow/conventions.md` — NEVER by `.claudeignore` or `!.devflow/policy.json`,
-# which users legitimately author themselves. Those two are completion lines: each is
-# topped up when missing, in block order (policy, then .claudeignore). Keying presence
+# D-GITIGNORE-IN-BLOCK: a line topped up into an existing block goes INSIDE the
+# block, where a fresh block holds it, never at the end of the file. gitignore is
+# last-match-wins, so a `!.devflow/project.json` appended after a user's own later
+# `.devflow/project.json` would silently override their re-ignore. The missing
+# lines are inserted as one run, in block order, right after the block sentinel
+# and the block lines that precede the first missing one in a fresh block (at most
+# three: the sentinel, the policy line, the project line). Every other byte of the
+# file is kept.
+#
+# D-GITIGNORE-V5 / D-GITIGNORE-V6: the block is detected ONLY by its devflow-unique
+# sentinel `!.devflow/conventions.md` — NEVER by `.claudeignore`,
+# `!.devflow/policy.json` or `!.devflow/project.json`, which users legitimately author
+# themselves. Those three are completion lines: each is topped up when missing, in
+# block order (policy, project, then .claudeignore). Keying presence
 # off a user-authored line inverts both halves of the contract: projects that already
 # carry that line never receive the carve-out (so .devflow/ runtime files leak into
 # git), and re-appending `.claudeignore` after a user's `!.claudeignore` reverses
@@ -50,7 +65,7 @@
 [ -z "$1" ] && return 1
 
 _ERG_DEVFLOW_DIR="$1/.devflow"
-_ERG_MARKER="$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v5"
+_ERG_MARKER="$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v6"
 _ERG_GITIGNORE="$1/.gitignore"
 
 # Whole-line, whitespace-tolerant matchers. `*` and `.` are escaped so the ERE
@@ -60,9 +75,10 @@ _ERG_RE_LEGACY='^[[:space:]]*\.devflow/[[:space:]]*$'
 _ERG_RE_SENTINEL='^[[:space:]]*!\.devflow/conventions\.md[[:space:]]*$'
 _ERG_RE_SENTINEL_V2='^[[:space:]]*!\.devflow/features/\*/KNOWLEDGE\.md[[:space:]]*$'
 _ERG_RE_POLICY='^[[:space:]]*!\.devflow/policy\.json[[:space:]]*$'
+_ERG_RE_PROJECT='^[[:space:]]*!\.devflow/project\.json[[:space:]]*$'
 _ERG_RE_CLAUDEIGNORE='^[[:space:]]*!?\.claudeignore[[:space:]]*$'
 
-# Drop every legacy marker beside v5 — builtin `[ -e ]` tests, so rm forks only for a
+# Drop every legacy marker beside v6 — builtin `[ -e ]` tests, so rm forks only for a
 # marker that exists. Called from the fast path and from the on-success stamp below,
 # so an older devflow's marker is dropped whichever path a run takes.
 # Always returns 0 (never fails the caller under `set -e`): the last iteration's
@@ -70,7 +86,7 @@ _ERG_RE_CLAUDEIGNORE='^[[:space:]]*!?\.claudeignore[[:space:]]*$'
 # and a function call's own exit status is NOT exempt from errexit the way an inlined
 # for-loop's is — unlike this same loop when it sat directly inside the caller's `{ }`.
 _erg_drop_legacy_markers() {
-  for _ERG_OLD in -v4 -v3 -v2 ''; do
+  for _ERG_OLD in -v5 -v4 -v3 -v2 ''; do
     [ -e "$_ERG_DEVFLOW_DIR/.root-gitignore-configured$_ERG_OLD" ] \
       && rm -f "$_ERG_DEVFLOW_DIR/.root-gitignore-configured$_ERG_OLD" 2>/dev/null
   done
@@ -78,11 +94,12 @@ _erg_drop_legacy_markers() {
 }
 
 # Fast path: converged only when the marker is stamped AND the block sentinel is
-# present AND the policy line is present AND a .claudeignore entry exists. Every
-# other state falls through and recomputes.
+# present AND the policy and project lines are present AND a .claudeignore entry
+# exists. Every other state falls through and recomputes.
 if [ -f "$_ERG_MARKER" ] \
   && grep -qE "$_ERG_RE_SENTINEL" "$_ERG_GITIGNORE" 2>/dev/null \
   && grep -qE "$_ERG_RE_POLICY" "$_ERG_GITIGNORE" 2>/dev/null \
+  && grep -qE "$_ERG_RE_PROJECT" "$_ERG_GITIGNORE" 2>/dev/null \
   && grep -qE "$_ERG_RE_CLAUDEIGNORE" "$_ERG_GITIGNORE" 2>/dev/null; then
   _erg_drop_legacy_markers
   return 0
@@ -100,9 +117,10 @@ mkdir -p "$_ERG_DEVFLOW_DIR" 2>/dev/null || return 1
 printf -v _ERG_BLOCK_NO_CI '%s\n' \
   '# Devflow runtime data — local by default (memory, learning, docs, locks).' \
   '# Shared via git: feature knowledge bases under .devflow/features/ (index.md and' \
-  '# every {slug}/KNOWLEDGE.md), .devflow/conventions.md (naming authority) and' \
-  '# .devflow/policy.json (evidence policy). To stop sharing the first two, re-add' \
-  '# `.devflow/features/` or `.devflow/conventions.md` to your own .gitignore.' \
+  '# every {slug}/KNOWLEDGE.md), .devflow/conventions.md (naming authority),' \
+  '# .devflow/policy.json (retired; presence only) and .devflow/project.json (team settings).' \
+  '# To stop sharing the first two, re-add `.devflow/features/` or' \
+  '# `.devflow/conventions.md` to your own .gitignore.' \
   '.devflow/*' \
   '!.devflow/features/' \
   '.devflow/features/*' \
@@ -111,33 +129,55 @@ printf -v _ERG_BLOCK_NO_CI '%s\n' \
   '.devflow/features/*/*' \
   '!.devflow/features/*/KNOWLEDGE.md' \
   '!.devflow/conventions.md' \
-  '!.devflow/policy.json'
+  '!.devflow/policy.json' \
+  '!.devflow/project.json'
 printf -v _ERG_LINE_SENTINEL '%s\n' '!.devflow/conventions.md'
 printf -v _ERG_LINE_POLICY '%s\n' '!.devflow/policy.json'
+printf -v _ERG_LINE_PROJECT '%s\n' '!.devflow/project.json'
 printf -v _ERG_LINE_CLAUDEIGNORE '%s\n' '.claudeignore'
 _ERG_BLOCK="$_ERG_BLOCK_NO_CI$_ERG_LINE_CLAUDEIGNORE"
 
-# Does the file already carry the policy line, or a .claudeignore entry of the user's
-# own (either form)? Computed BEFORE the legacy filter below, which rewrites the file.
+# Does the file already carry the policy line, the project line, or a .claudeignore
+# entry of the user's own (either form)? Computed BEFORE the legacy filter below,
+# which rewrites the file.
 _ERG_HAS_POLICY=0
 grep -qE "$_ERG_RE_POLICY" "$_ERG_GITIGNORE" 2>/dev/null && _ERG_HAS_POLICY=1
+_ERG_HAS_PROJECT=0
+grep -qE "$_ERG_RE_PROJECT" "$_ERG_GITIGNORE" 2>/dev/null && _ERG_HAS_PROJECT=1
 _ERG_HAS_CI=0
 grep -qE "$_ERG_RE_CLAUDEIGNORE" "$_ERG_GITIGNORE" 2>/dev/null && _ERG_HAS_CI=1
 
-# The completion lines this file lacks, in block order (policy, then .claudeignore).
-# Mirrors missingCompletionLines in the TS twin.
+# The completion lines this file lacks, in block order (policy, project, then
+# .claudeignore). Mirrors missingCompletionLines in the TS twin.
 _ERG_COMPLETION=''
 if [ "$_ERG_HAS_POLICY" = 0 ]; then
   _ERG_COMPLETION="$_ERG_LINE_POLICY"
 fi
+if [ "$_ERG_HAS_PROJECT" = 0 ]; then
+  _ERG_COMPLETION="$_ERG_COMPLETION$_ERG_LINE_PROJECT"
+fi
 if [ "$_ERG_HAS_CI" = 0 ]; then
   _ERG_COMPLETION="$_ERG_COMPLETION$_ERG_LINE_CLAUDEIGNORE"
 fi
 
+# The block lines a top-up run is inserted after: the sentinel, then whichever of
+# the policy and project lines precede the first missing line in a fresh block.
+# Mirrors blockRunBefore in the TS twin.
+if [ "$_ERG_HAS_POLICY" = 0 ]; then
+  _ERG_RUN_RE='^[[:space:]]*(!\.devflow/conventions\.md)[[:space:]]*$'
+elif [ "$_ERG_HAS_PROJECT" = 0 ]; then
+  _ERG_RUN_RE='^[[:space:]]*(!\.devflow/conventions\.md|!\.devflow/policy\.json)[[:space:]]*$'
+else
+  _ERG_RUN_RE='^[[:space:]]*(!\.devflow/conventions\.md|!\.devflow/policy\.json|!\.devflow/project\.json)[[:space:]]*$'
+fi
+
 # Classify: noop (nothing to do) | continue (extend an existing block) |
 # block (install a fresh block) | fail (a rewrite failed; leave the file alone).
+# continue inserts _ERG_APPEND after the first line matching _ERG_ANCHOR_RE and the
+# run of lines matching _ERG_RUN_RE right after it (empty: no run).
 _ERG_MODE=noop
 _ERG_APPEND=''
+_ERG_ANCHOR_RE=''
 if grep -qE "$_ERG_RE_OPTOUT" "$_ERG_GITIGNORE" 2>/dev/null; then
   # User-authored `/.devflow/` (leading slash) — respect it; don't force the carve-out.
   # Checked FIRST so a file containing both it and a sentinel keeps the user's entry.
@@ -147,11 +187,15 @@ elif grep -qE "$_ERG_RE_SENTINEL" "$_ERG_GITIGNORE" 2>/dev/null; then
   if [ -n "$_ERG_COMPLETION" ]; then
     _ERG_MODE=continue
     _ERG_APPEND="$_ERG_COMPLETION"
+    _ERG_ANCHOR_RE="$_ERG_RE_SENTINEL"
   fi
 elif grep -qE "$_ERG_RE_SENTINEL_V2" "$_ERG_GITIGNORE" 2>/dev/null; then
-  # v2 block installed — append the lines it lacks, in block order.
+  # v2 block installed — insert the lines it lacks, in block order, right after
+  # its sentinel, the last carve-out line it has.
   _ERG_MODE=continue
   _ERG_APPEND="$_ERG_LINE_SENTINEL$_ERG_COMPLETION"
+  _ERG_ANCHOR_RE="$_ERG_RE_SENTINEL_V2"
+  _ERG_RUN_RE=''
 else
   # No devflow block — install one, omitting the .claudeignore line the user owns.
   _ERG_MODE=block
@@ -180,21 +224,52 @@ else
   fi
 fi
 
-# The two append shapes, mirrored byte-for-byte by the TS twin's appendLines and
-# appendBlock. `tail -c 1` yields the empty string when the file already ends in a
-# newline (command substitution strips it), so a file whose last byte is not a
-# newline gets one before the appended text fuses onto its last line. Existing
-# trailing newlines are preserved verbatim — no trimming, no blank-line dedupe.
+# _erg_insert_in_block <anchor-ERE> <run-ERE or ''> <text> — rewrite the file with
+# <text> inserted after the first line matching <anchor-ERE> and the run of up to
+# three lines matching <run-ERE> right after it (D-GITIGNORE-IN-BLOCK). Mirrors
+# insertInBlock in the TS twin byte for byte: head and tail copy every other byte
+# unchanged, and when the run ends on a last line with no newline, one is added
+# before <text>. Each read ends in a trailing `x`, so command substitution cannot
+# strip the file's own trailing newlines. The file is rewritten in place with one
+# `>`, as the TS twin's writeFile does, so a symlinked .gitignore keeps its link.
+# Returns non-zero, having written nothing, when the anchor line cannot be found.
+_erg_insert_in_block() {
+  local _anchor="$1" _run="$2" _text="$3" _hit="" _n="" _next="" _line="" _i=0 _head="" _tail=""
+  _hit="$(grep -n -m 1 -E "$_anchor" "$_ERG_GITIGNORE" 2>/dev/null)" || return 1
+  _n="${_hit%%:*}"
+  case "$_n" in ''|*[!0-9]*) return 1 ;; esac
+  if [ -n "$_run" ]; then
+    _next="$(sed -n "$((_n + 1)),$((_n + 3))p" "$_ERG_GITIGNORE" 2>/dev/null)"
+    while [ "$_i" -lt 3 ] && [ -n "$_next" ]; do
+      _line="${_next%%$'\n'*}"
+      if [ "$_line" = "$_next" ]; then _next=''; else _next="${_next#*$'\n'}"; fi
+      [[ $_line =~ $_run ]] || break
+      _n=$((_n + 1))
+      _i=$((_i + 1))
+    done
+  fi
+  # The `x` is printed only when the read succeeded, so a failed read leaves none
+  # and nothing is written — never a truncated file.
+  _head="$(head -n "$_n" "$_ERG_GITIGNORE" 2>/dev/null && printf x)"
+  case "$_head" in *x) _head="${_head%x}" ;; *) return 1 ;; esac
+  _tail="$(tail -n "+$((_n + 1))" "$_ERG_GITIGNORE" 2>/dev/null && printf x)"
+  case "$_tail" in *x) _tail="${_tail%x}" ;; *) return 1 ;; esac
+  case "$_head" in *$'\n') ;; *) _head="$_head"$'\n' ;; esac
+  printf '%s%s%s' "$_head" "$_text" "$_tail" > "$_ERG_GITIGNORE"
+}
+
+# The fresh-block append shape, mirrored byte-for-byte by the TS twin's appendBlock.
+# `tail -c 1` yields the empty string when the file already ends in a newline
+# (command substitution strips it), so a file whose last byte is not a newline gets
+# one before the appended text fuses onto its last line. Existing trailing newlines
+# are preserved verbatim — no trimming, no blank-line dedupe.
 _ERG_OK=0
 case "$_ERG_MODE" in
   noop)
     _ERG_OK=1
     ;;
   continue)
-    if [ -n "$(tail -c 1 "$_ERG_GITIGNORE" 2>/dev/null)" ]; then
-      printf '\n' >> "$_ERG_GITIGNORE"
-    fi
-    printf '%s' "$_ERG_APPEND" >> "$_ERG_GITIGNORE" && _ERG_OK=1
+    _erg_insert_in_block "$_ERG_ANCHOR_RE" "$_ERG_RUN_RE" "$_ERG_APPEND" && _ERG_OK=1
     ;;
   block)
     if [ ! -s "$_ERG_GITIGNORE" ]; then
@@ -209,7 +284,7 @@ case "$_ERG_MODE" in
     ;;
 esac
 
-# On success, stamp the current-format v5 marker and drop legacy markers.
+# On success, stamp the current-format v6 marker and drop legacy markers.
 [ "$_ERG_OK" = 1 ] && {
   touch "$_ERG_MARKER"
   _erg_drop_legacy_markers

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

@@ -14,3 +14,51 @@ df_has_git_marker() {
   done
   return 1
 }
+
+# df_is_project_root <root> — returns 0 when <root> may hold per-project devflow
+# data: it is a checkout's toplevel — it holds its own `.git` entry — AND it is not
+# the home directory.
+#
+# D-HOOKS-GIT-ONLY: the hooks that scaffold `.devflow/` and the root `.gitignore`
+# carve-out — session-start-context and ensure-devflow-init, which every capture
+# and memory hook reaches — run only for a git project. Outside one there is no
+# repository for the carve-out to protect and no branch for memory to describe,
+# and scaffolding there would leave `.devflow/` and a `.gitignore` block in `~`,
+# Downloads or a folder of repos — wherever Claude Code happened to start.
+# A repository rooted at HOME (a dotfiles repo) is refused too: its `.devflow` IS
+# the machine root, so per-project data would land inside `~/.devflow` and its
+# carve-out in the user's home `.gitignore`.
+#
+# D-HOOKS-TOPLEVEL-ONLY: the `.git` entry must sit AT <root>, not merely above it.
+# Callers pass the root df_resolve_roots resolved, and when `git rev-parse` fails
+# from inside a checkout — the repository has dubious ownership, or
+# GIT_CEILING_DIRECTORIES stops git's search — that root is the raw cwd, possibly a
+# subdirectory. An ancestor walk would still find the checkout's `.git` and admit
+# it, and `.devflow/` plus a `.gitignore` block would land in that subdirectory.
+# Requiring the marker at the root makes the gate and the resolver agree: git's
+# toplevel always holds `.git` (a directory, or the file a linked worktree or
+# submodule carries), a subdirectory never does. A directory that holds its own
+# `.git` still passes when git cannot read it — the marker contract is the zero-fork
+# one above, and writing there scatters nothing, because it is the checkout's root.
+#
+# The comparison is between PHYSICAL paths, because the two sides reach it by
+# different routes: git reports a toplevel with every symlink resolved, while
+# $HOME is whatever the login shell was handed — on macOS the temp tree is
+# /var → /private/var, and a home directory can itself sit behind a symlink. A
+# textual compare would miss exactly the case it exists for.
+#
+# Zero forks, like the marker walk above: a builtin `-e` test, then `cd -P`, which
+# resolves a path physically and publishes it in $PWD — both shell builtins, so no
+# `$(...)` subshell and no realpath/readlink binary is involved. The caller's directory is restored before
+# returning. An unresolvable <root> is refused (fail closed: nothing is written);
+# an unset or unresolvable HOME cannot equal a resolved root, so it refuses nothing.
+df_is_project_root() {
+  local _root="$1" _back="$PWD" _root_real="" _home_real=""
+  [ -n "$_root" ] || return 1
+  [ -e "$_root/.git" ] || return 1
+  if cd -P "$_root" 2>/dev/null; then _root_real="$PWD"; fi
+  if [ -n "${HOME:-}" ] && cd -P "$HOME" 2>/dev/null; then _home_real="$PWD"; fi
+  cd "$_back" 2>/dev/null || true
+  [ -n "$_root_real" ] || return 1
+  [ "$_root_real" != "$_home_real" ]
+}