devflow-kit 2.4.0 → 3.0.0

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-v2" ]; 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,14 +3,19 @@
 # rules that govern .devflow/.
 #
 # .devflow/ holds per-developer runtime state (memory, learning, docs, locks) —
-# local by default. TWO 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 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 by re-adding
-# `.devflow/features/` or `.devflow/conventions.md` to their own .gitignore.
+# 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.
 #
 # Re-including files under an ignored tree requires un-ignoring each level with a
 # `dir/*` + `!dir/keep` pair: a bare `.devflow/` excludes the directory outright,
@@ -23,9 +28,35 @@
 # 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-v3
-# marker. The marker is versioned: bumping it (v2 → v3) forces existing installs
-# to re-run once and upgrade their block (adds !.devflow/conventions.md line).
+# 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, 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-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
+# their intent under gitignore's last-match-wins. Hence: a `.claudeignore` OR
+# `!.claudeignore` entry means "the user owns that line" — emit the block without it.
+# All matching is whole-line and whitespace-tolerant; never substring.
 #
 # Usage: source ensure-root-gitignore "$PROJECT_ROOT"
 # Sourced helper: uses `return` (never exit), _ERG_-prefixed locals (never clobbers
@@ -34,31 +65,62 @@
 [ -z "$1" ] && return 1
 
 _ERG_DEVFLOW_DIR="$1/.devflow"
-_ERG_MARKER="$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v3"
+_ERG_MARKER="$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v6"
 _ERG_GITIGNORE="$1/.gitignore"
 
-# Fast-path with verification: marker normally means the block is installed, but
-# the marker is a claim, not proof — a merge-conflict resolution may have dropped
-# the block. Gate the fast-path return on the v3 sentinel actually being present
-# in .gitignore. Idempotent: sentinel present → return 0; sentinel absent → heal.
-if [ -f "$_ERG_MARKER" ]; then
-  grep -qF '!.devflow/conventions.md' "$_ERG_GITIGNORE" 2>/dev/null && return 0
-  # Sentinel absent — marker is stale; fall through to re-apply the block.
+# Whole-line, whitespace-tolerant matchers. `*` and `.` are escaped so the ERE
+# matches the literal gitignore patterns.
+_ERG_RE_OPTOUT='^[[:space:]]*/\.devflow/[[:space:]]*$'
+_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 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
+# `[ -e ]` test is false whenever the unversioned marker is absent (the common case),
+# 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 -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
+  return 0
+}
+
+# Fast path: converged only when the marker is stamped AND the block sentinel is
+# 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
 fi
 
 # The marker lives under .devflow/, so the directory must exist before we touch it.
 # (ensure-devflow-init creates it earlier; session-start-context may reach here first.)
 mkdir -p "$_ERG_DEVFLOW_DIR" 2>/dev/null || return 1
 
-# The carve-out block, built once into _ERG_BLOCK (emitted on create and append).
-# Keep byte-identical to ensureDevflowGitignore in src/targets/claude-code/post-install.ts.
-# D-GITIGNORE-V3: v3 adds !.devflow/conventions.md (naming authority, git-tracked).
-printf -v _ERG_BLOCK '%s\n' \
+# The carve-out block, built once. _ERG_BLOCK_NO_CI is the block a project that owns
+# its own .claudeignore entry receives; _ERG_BLOCK is that plus the final line.
+# Both trail a newline. Keep byte-identical to DEVFLOW_GITIGNORE_BLOCK and
+# 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).' \
-  '# Two exceptions are shared via git: feature knowledge bases under .devflow/features/' \
-  '# (index.md and every {slug}/KNOWLEDGE.md) and .devflow/conventions.md (naming' \
-  '# authority). To stop sharing, re-add `.devflow/features/` or `.devflow/conventions.md`' \
-  '# to your own .gitignore.' \
+  '# 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).' \
+  '# To stop sharing the first two, re-add `.devflow/features/` or' \
+  '# `.devflow/conventions.md` to your own .gitignore.' \
   '.devflow/*' \
   '!.devflow/features/' \
   '.devflow/features/*' \
@@ -66,51 +128,165 @@ printf -v _ERG_BLOCK '%s\n' \
   '!.devflow/features/*/' \
   '.devflow/features/*/*' \
   '!.devflow/features/*/KNOWLEDGE.md' \
-  '!.devflow/conventions.md'
+  '!.devflow/conventions.md' \
+  '!.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"
 
-_ERG_OK=0
-if [ ! -f "$_ERG_GITIGNORE" ]; then
-  # No .gitignore yet — create it with the block.
-  printf '%s' "$_ERG_BLOCK" > "$_ERG_GITIGNORE" && _ERG_OK=1
-elif grep -qF '!.devflow/conventions.md' "$_ERG_GITIGNORE"; then
-  # v3 carve-out already present — nothing to do.
-  _ERG_OK=1
-elif grep -qE '^/\.devflow/[[:space:]]*$' "$_ERG_GITIGNORE"; then
+# 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, 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 BEFORE the v2 sentinel so a file containing both keeps the user-authored
-  # entry (matches ensureDevflowGitignore TS order: v3→/.devflow/→v2→wholesale→append).
-  _ERG_OK=1
-elif grep -qF '!.devflow/features/*/KNOWLEDGE.md' "$_ERG_GITIGNORE"; then
-  # v2→v3 upgrade: v2 sentinel present but conventions.md line absent — append just the
-  # missing line. A .gitignore whose last byte is not a newline would otherwise fuse the
-  # appended line onto the last existing one, corrupting BOTH patterns; the sibling append
-  # branches below get this for free by emitting a leading '\n'. `tail -c 1` yields the
-  # empty string when the file already ends in a newline (command substitution strips it).
-  if [ -n "$(tail -c 1 "$_ERG_GITIGNORE" 2>/dev/null)" ]; then
-    printf '\n' >> "$_ERG_GITIGNORE"
+  # Checked FIRST so a file containing both it and a sentinel keeps the user's entry.
+  _ERG_MODE=noop
+elif grep -qE "$_ERG_RE_SENTINEL" "$_ERG_GITIGNORE" 2>/dev/null; then
+  # Block installed (v3 and later) — top up only the completion lines it lacks.
+  if [ -n "$_ERG_COMPLETION" ]; then
+    _ERG_MODE=continue
+    _ERG_APPEND="$_ERG_COMPLETION"
+    _ERG_ANCHOR_RE="$_ERG_RE_SENTINEL"
   fi
-  printf '!.devflow/conventions.md\n' >> "$_ERG_GITIGNORE" && _ERG_OK=1
-elif grep -qE '^\.devflow/[[:space:]]*$' "$_ERG_GITIGNORE"; then
-  # Upgrade our legacy wholesale entry: strip the bare `.devflow/` line and our old
-  # comment, then append the carve-out block. Portable (grep filter + mv; no sed -i,
-  # which differs on BSD/GNU). An empty filter result is fine — the block is appended
-  # regardless; a leading blank is added only when prior content survived.
-  _ERG_TMP="$_ERG_GITIGNORE.devflow-tmp.$$"
-  grep -vE '^\.devflow/[[:space:]]*$' "$_ERG_GITIGNORE" 2>/dev/null \
-    | grep -vF '# Devflow runtime data (local by default; remove to share via git)' \
-    > "$_ERG_TMP" 2>/dev/null
-  { [ -s "$_ERG_TMP" ] && printf '\n'; printf '%s' "$_ERG_BLOCK"; } >> "$_ERG_TMP" \
-    && mv "$_ERG_TMP" "$_ERG_GITIGNORE" && _ERG_OK=1
-  [ "$_ERG_OK" = 1 ] || rm -f "$_ERG_TMP" 2>/dev/null
+elif grep -qE "$_ERG_RE_SENTINEL_V2" "$_ERG_GITIGNORE" 2>/dev/null; then
+  # 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
-  # .gitignore exists but has no Devflow entry — append the block.
-  { printf '\n'; printf '%s' "$_ERG_BLOCK"; } >> "$_ERG_GITIGNORE" && _ERG_OK=1
+  # No devflow block — install one, omitting the .claudeignore line the user owns.
+  _ERG_MODE=block
+  if [ "$_ERG_HAS_CI" = 1 ]; then
+    _ERG_APPEND="$_ERG_BLOCK_NO_CI"
+  else
+    _ERG_APPEND="$_ERG_BLOCK"
+  fi
+  if grep -qE "$_ERG_RE_LEGACY" "$_ERG_GITIGNORE" 2>/dev/null; then
+    # Upgrade our legacy wholesale entry: strip the bare `.devflow/` line and our old
+    # comment first, then fall through to the shared append below. Portable (grep
+    # filter + mv; no sed -i, which differs on BSD/GNU).
+    # The pipeline's own status is deliberately ignored: grep -v exits 1 when it
+    # emits no lines, which is the correct outcome for a .gitignore whose only
+    # content was the legacy entry. The redirect creates _ERG_TMP either way.
+    _ERG_TMP="$_ERG_GITIGNORE.devflow-tmp.$$"
+    grep -vE "$_ERG_RE_LEGACY" "$_ERG_GITIGNORE" 2>/dev/null \
+      | grep -vF '# Devflow runtime data (local by default; remove to share via git)' \
+      > "$_ERG_TMP" 2>/dev/null
+    if [ -f "$_ERG_TMP" ] && mv "$_ERG_TMP" "$_ERG_GITIGNORE"; then
+      :
+    else
+      rm -f "$_ERG_TMP" 2>/dev/null
+      _ERG_MODE=fail
+    fi
+  fi
 fi
 
-# On success, stamp the current-format v3 marker and drop legacy markers.
+# _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)
+    _erg_insert_in_block "$_ERG_ANCHOR_RE" "$_ERG_RUN_RE" "$_ERG_APPEND" && _ERG_OK=1
+    ;;
+  block)
+    if [ ! -s "$_ERG_GITIGNORE" ]; then
+      # Absent or empty — the block is the whole file, with no leading blank line.
+      printf '%s' "$_ERG_APPEND" > "$_ERG_GITIGNORE" && _ERG_OK=1
+    else
+      if [ -n "$(tail -c 1 "$_ERG_GITIGNORE" 2>/dev/null)" ]; then
+        printf '\n' >> "$_ERG_GITIGNORE"
+      fi
+      { printf '\n'; printf '%s' "$_ERG_APPEND"; } >> "$_ERG_GITIGNORE" && _ERG_OK=1
+    fi
+    ;;
+esac
+
+# On success, stamp the current-format v6 marker and drop legacy markers.
 [ "$_ERG_OK" = 1 ] && {
   touch "$_ERG_MARKER"
-  rm -f "$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v2" 2>/dev/null
-  rm -f "$_ERG_DEVFLOW_DIR/.root-gitignore-configured" 2>/dev/null
+  _erg_drop_legacy_markers
 }
 return 0

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" ]
+}

package/src/assets/scripts/hooks/hook-log-init

@@ -29,9 +29,11 @@ LOG_FILE="$LOG_DIR/.${_HOOK_LOG_NAME}.log"
 
 # Size guard: truncate log to tail 1MB when it exceeds 2MB (runs once per hook invocation)
 # stat -f%z (macOS/BSD) → stat -c%s (GNU/Linux) → wc -c (last resort), matching debug-trace pattern.
+# `2>/dev/null` precedes `<`: redirections apply left to right, so the shell's own
+# "No such file or directory" for a missing log (first run for a cwd) lands in /dev/null.
 _LOG_SIZE=$(stat -f%z "$LOG_FILE" 2>/dev/null) \
   || _LOG_SIZE=$(stat -c%s "$LOG_FILE" 2>/dev/null) \
-  || _LOG_SIZE=$(wc -c < "$LOG_FILE" 2>/dev/null) \
+  || _LOG_SIZE=$(wc -c 2>/dev/null < "$LOG_FILE") \
   || _LOG_SIZE=0
 if [ -f "$LOG_FILE" ] && [ "$_LOG_SIZE" -gt 2097152 ]; then
   _LTMP="$LOG_FILE.tmp.$$"