devflow-kit 2.5.0 → 3.0.1

package/src/assets/scripts/hooks/session-start-context

@@ -2,9 +2,11 @@
 
 # SessionStart Hook: Cross-Feature Context Injection
 # Always-on hook that injects learning context as additionalContext. Sections
-# 1–2 are gated by the machine-wide `features.learning` switch in
-# ~/.devflow/manifest.json (D-FEATURES-MACHINE-WIDE) — this hook itself is never
-# disabled.
+# 1–2 are gated by the `features.learning` switch in ~/.devflow/manifest.json,
+# which this checkout's project.json / config.json can only narrow
+# (D-FEATURES-NARROW-ONLY) — this hook itself is never disabled. They and the .gitignore carve-out run only in a git project that is
+# not the home directory (D-HOOKS-GIT-ONLY), and they read the learning ledger of
+# the main worktree when this is a linked one (D-LEDGER-MAIN-WORKTREE).
 #
 # Section 1: Project decisions TL;DR (decisions.md / pitfalls.md header lines).
 # Section 2: Learning maintenance directive — when captured turns are pending in
@@ -12,10 +14,14 @@
 # the main model to spawn the background Learning agent with the resolved model.
 # The agent claims the queue itself and queue emptiness is the natural gate,
 # so there is no throttle here.
-# Section 3: Tracker setup directive — when the machine's manifest names a
-# non-GitHub issue tracker and no ~/.devflow/tracker.md has been inferred for it
-# yet, instructs the main model to spawn the background Tracker agent. Gated on a
-# zero-byte presence sentinel so a GitHub user pays one stat and zero forks.
+# Section 3: Tracker setup directive — when the issue tracker in effect for this
+# project is not GitHub and no ~/.devflow/tracker/{provider}.md has been inferred
+# for it yet, instructs the main model to spawn the background Tracker agent. The
+# machine provider comes from a sentinel read with a builtin, so a GitHub user —
+# and a jira machine whose conventions are learned — forks nothing.
+# Section 4: Legacy install notice — one line when this repository still carries
+# a retired project-local devflow install (its .claude/settings.json registers
+# devflow hooks), pointing at `devflow uninstall --scope local`.
 
 # Safe no-op fallback: must exist before hook-bootstrap is sourced.
 dbg() { :; }
@@ -52,36 +58,53 @@ devflow_debug_set_cwd "$CWD"
 dbg "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.
+# hook runs with a CWD inside .devflow/...). One git call yields both roots
+# (resolve-project-root): PROJECT_ROOT is this checkout's toplevel, LEDGER_ROOT the
+# main worktree when this is a linked worktree whose main checkout already has a
+# .devflow (D-LEDGER-MAIN-WORKTREE). 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"
+df_resolve_roots "$CWD" 2>/dev/null || true
+PROJECT_ROOT="${DF_ROOT:-$CWD}"
+LEDGER_ROOT="${DF_LEDGER_ROOT:-$PROJECT_ROOT}"
+
+# D-HOOKS-GIT-ONLY (git-marker): per-project work — the .gitignore carve-out and
+# Sections 1–2 — happens only for a git project that is not the home directory.
+# Outside one there is no repository for the carve-out to protect, so writing it
+# would litter whatever directory Claude Code was launched from, and at `~` the
+# project data would land inside the machine root. df_is_project_root is two
+# builtin walks, so this gate forks nothing. Section 3 keeps its own marker gate below: tracker
+# setup is machine-scoped and is not project scaffolding.
+source "$SCRIPT_DIR/git-marker" 2>/dev/null || true
+PROJECT_OK=""
+if df_is_project_root "$PROJECT_ROOT" 2>/dev/null; then
+  PROJECT_OK="yes"
+else
+  dbg "project work skipped: not a git project, or the project root is HOME"
+fi
 
 # Ensure the project root .gitignore ignores .devflow/ wholesale. This runs on every
-# session regardless of feature toggles, so memory-off projects (learning/knowledge
-# only) still get .devflow/ ignored — this is the memory-independent path that fixes
-# the gitignore/memory coupling (PF-014). Single source of truth: ensure-root-gitignore.
-# Soft-fail: a gitignore write must never block context injection. Marker keeps it O(1).
-[ -d "$PROJECT_ROOT" ] && [ -f "$SCRIPT_DIR/ensure-root-gitignore" ] && source "$SCRIPT_DIR/ensure-root-gitignore" "$PROJECT_ROOT" || true
+# git-project session regardless of feature toggles, so memory-off projects
+# (learning/knowledge only) still get .devflow/ ignored — this is the
+# memory-independent path that fixes the gitignore/memory coupling (PF-014). Single
+# source of truth: ensure-root-gitignore. Soft-fail: a gitignore write must never
+# block context injection. Marker keeps it O(1).
+[ -n "$PROJECT_OK" ] && [ -d "$PROJECT_ROOT" ] && [ -f "$SCRIPT_DIR/ensure-root-gitignore" ] && source "$SCRIPT_DIR/ensure-root-gitignore" "$PROJECT_ROOT" || true
 
 CONTEXT=""
 
-# The devflow-GLOBAL root (~/.devflow), honouring the DEVFLOW_DIR env override —
-# the ensure-proxy:58-60 idiom. Captured HERE, above the project-scoped
-# DEVFLOW_DIR assignment that shadows the inherited value, because Section 3's
-# tracker files and the manifest the learning gate reads are user-scope and not
-# project-scope. (Known divergence,
-# deliberately not propagated: the global learning.json read in Section 2
-# hardcodes $HOME/.devflow and ignores this override.)
-TRACKER_DEVFLOW_DIR="${DEVFLOW_DIR:-$HOME/.devflow}"
+# The devflow machine root, always $HOME/.devflow (D-ONE-HOME): Section 3's
+# tracker files and the manifest the learning gate reads are machine-wide, not
+# project-scoped (the project's own .devflow is PROJECT_DEVFLOW_DIR below).
+TRACKER_DEVFLOW_DIR="$HOME/.devflow"
 
 # The shape gate for every path this hook interpolates into a directive.
 #
-# Sections 2 and 3 embed $PROJECT_ROOT — and Section 3 also $TRACKER_DEVFLOW_DIR —
-# inside a double-quoted `prompt: "..."` string the model reads out of
-# additionalContext. The provider and model TOKENS in those directives are admitted
-# by positive allowlists, and so are these: the gate is the POSITIVE shape
-# ^[A-Za-z0-9/._-]+$, expressed as "rejects if any character falls outside it".
+# Section 2 embeds $LEDGER_ROOT; Section 3 embeds $PROJECT_ROOT and
+# $TRACKER_DEVFLOW_DIR — each inside a double-quoted `prompt: "..."` string the
+# model reads out of additionalContext. The provider and model TOKENS in those
+# directives are admitted by positive allowlists, and so are these: the gate is the
+# POSITIVE shape ^[A-Za-z0-9/._+-]+$, expressed as "rejects if any character falls
+# outside it".
 #
 # Positive, not a denylist of the characters that are known to hurt. A denylist
 # enumerates the injections someone thought of — `"` closes the prompt string, `\`
@@ -91,10 +114,17 @@ TRACKER_DEVFLOW_DIR="${DEVFLOW_DIR:-$HOME/.devflow}"
 # by construction rather than by a later amendment.
 #
 # The narrowing is real and deliberate: a project root containing a space, a
-# quote, a backtick, `$` or `;` now suppresses the directive that embeds it
-# rather than interpolating an unproven value. That is the fail-closed direction
-# — the directive is an optimisation, and `dbg` names the reason on the debug
-# path.
+# quote, a backtick, `$` or `;` suppresses the directive that embeds it rather
+# than interpolating an unproven value. That is the fail-closed direction — the
+# directive is an optimisation — but it must not be a SILENT one: a refused
+# Learning root with pending work emits the fixed `--- LEARNING PAUSED ---`
+# notice instead (Section 2), which interpolates nothing, so the user learns why
+# the queue never drains rather than finding it capped at 200 rows one day.
+#
+# `+` is admitted: Claude Code names a worktree for a slash branch with it
+# (`feat/x` → `feat+x`), so refusing it would silence learning in exactly the
+# linked worktrees users open most, and it is inert inside a double-quoted prompt
+# string — it closes nothing, escapes nothing and expands nothing.
 #
 # What the range does NOT promise is "ASCII only". A `case` bracket range
 # collates under LC_COLLATE, so `A-Za-z0-9` admits an accented letter under a
@@ -103,57 +133,72 @@ TRACKER_DEVFLOW_DIR="${DEVFLOW_DIR:-$HOME/.devflow}"
 # both, so the security property holds either way; only the exact width of the
 # admitted set is locale-dependent, and no rule here rests on it.
 #
-# Checked ONCE, here, where both values are resolved and above every section that
+# Checked ONCE, here, where every value is resolved and above every section that
 # interpolates them, so no sink can embed a value no gate saw (PF-023 — the
 # invariant belongs at the convergence point all callers pass through, not in
 # whichever section someone remembered). `case` is a shell builtin, so the GitHub
-# path still forks zero times [DR-10]. The empty arm is explicit: an unset
-# PROJECT_ROOT must not read as "no forbidden character, therefore safe".
+# path still forks zero times [DR-10]. The empty arm is explicit: an unset root
+# must not read as "no forbidden character, therefore safe".
 #
-# ONE gate per VALUE, not one over their concatenation. Section 2 interpolates
-# $PROJECT_ROOT alone; only Section 3 also interpolates $TRACKER_DEVFLOW_DIR.
-# Gating the two values jointly made a rejected ~/.devflow shape suppress the
-# Learning directive as well — a value Section 2 never embeds, silently
-# disabling the whole learning pipeline for any machine whose home directory
-# carries a space. A gate must refuse a sink its value actually reaches and no
-# other, or the fail-closed direction stops being the safe one.
+# ONE gate per VALUE, applied to the root each section embeds, not one over their
+# concatenation. Section 2 interpolates $LEDGER_ROOT alone — the main worktree's
+# root in a linked worktree (D-LEDGER-MAIN-WORKTREE), so it is the value checked
+# for that section, not the checkout's own; only Section 3 interpolates
+# $PROJECT_ROOT and $TRACKER_DEVFLOW_DIR. Gating values jointly made a rejected
+# ~/.devflow shape suppress the Learning directive as well — a value Section 2
+# never embeds, silently disabling the whole learning pipeline for any machine
+# whose home directory carries a space. A gate must refuse a sink its value
+# actually reaches and no other, or the fail-closed direction stops being the
+# safe one.
+DIRECTIVE_LEDGER_SAFE="yes"
+case "$LEDGER_ROOT" in
+  ''|*[!A-Za-z0-9/._+-]*)
+    DIRECTIVE_LEDGER_SAFE=""
+    ;;
+esac
+
 DIRECTIVE_ROOT_SAFE="yes"
 case "$PROJECT_ROOT" in
-  ''|*[!A-Za-z0-9/._-]*)
+  ''|*[!A-Za-z0-9/._+-]*)
     DIRECTIVE_ROOT_SAFE=""
     ;;
 esac
 
-# Section 3's flag: BOTH values, because Section 3 interpolates both. Seeded from
-# the root flag so it can only ever be narrower — a root the sections may not
-# embed is not embeddable by the section that embeds more of them.
+# Section 3's flag: BOTH of its values, because Section 3 interpolates both.
+# Seeded from the project-root flag so it can only ever be narrower — a root the
+# section may not embed is not embeddable alongside a second path either.
 DIRECTIVE_PATHS_SAFE="$DIRECTIVE_ROOT_SAFE"
 case "$TRACKER_DEVFLOW_DIR" in
-  ''|*[!A-Za-z0-9/._-]*)
+  ''|*[!A-Za-z0-9/._+-]*)
     DIRECTIVE_PATHS_SAFE=""
     ;;
 esac
 
-DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
-LEARNING_DIR="$DEVFLOW_DIR/learning"
+PROJECT_DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
+LEDGER_DEVFLOW_DIR="$LEDGER_ROOT/.devflow"
+LEARNING_DIR="$LEDGER_DEVFLOW_DIR/learning"
 
 # Normal logging
 source "$SCRIPT_DIR/hook-log-init" "session-start-context"
 
-# --- Learning gate: the machine-wide switch ---
-# D-FEATURES-MACHINE-WIDE (see queue-append): ~/.devflow/manifest.json's
-# features.learning is read by the same helper the capture hooks use, so the
-# directive and the queue it drains can never disagree about whether learning
-# is on. The manifest lives under the devflow-global root captured above, not
-# the project-scoped DEVFLOW_DIR.
+# --- Learning gate: the machine switch, narrowed by this checkout ---
+# D-FEATURES-NARROW-ONLY (see queue-append): ~/.devflow/manifest.json's
+# features.learning, narrowed by PROJECT_ROOT's project.json / config.json, is
+# read by the same helper the capture hooks use, so the directive and the queue
+# it drains can never disagree about whether learning is on. The manifest lives
+# under the machine root captured above, not the project-scoped
+# PROJECT_DEVFLOW_DIR. Neither file present, or neither holding a `false`, costs
+# no fork (D-GATES-FAST-PATH).
 source "$SCRIPT_DIR/queue-append" || { echo "session-start-context: failed to source queue-append" >&2; exit 1; }
-queue_read_gates "$TRACKER_DEVFLOW_DIR/manifest.json"
+queue_read_gates "$TRACKER_DEVFLOW_DIR/manifest.json" "$PROJECT_ROOT"
 LEARNING_ENABLED="$_QG_LEARNING"
+# Learning is project work: off outside a git project (D-HOOKS-GIT-ONLY above).
+[ -n "$PROJECT_OK" ] || LEARNING_ENABLED="false"
 
 # --- Section 1: Project Decisions TL;DR ---
 if [ "$LEARNING_ENABLED" = "true" ]; then
   # Heal older installs that have .devflow/ but not .devflow/learning/
-  if [ -d "$DEVFLOW_DIR" ] && [ ! -d "$LEARNING_DIR" ]; then
+  if [ -d "$LEDGER_DEVFLOW_DIR" ] && [ ! -d "$LEARNING_DIR" ]; then
     mkdir -p "$LEARNING_DIR" 2>/dev/null || true
   fi
   if [ -d "$LEARNING_DIR" ]; then
@@ -206,11 +251,23 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
     LEARNING_WORK="queue"
   fi
 
-  # $PROJECT_ROOT is the only path this directive interpolates (line below), so
-  # it is the only one whose shape may suppress it.
-  if [ -n "$LEARNING_WORK" ] && [ -z "$DIRECTIVE_ROOT_SAFE" ]; then
-    dbg "learning directive suppressed: interpolated path shape rejected"
+  # $LEDGER_ROOT is the only path this directive interpolates (line below), so
+  # it is the only one whose shape may suppress it. A refusal is not silent: the
+  # fixed notice below names the pause and interpolates NOTHING — no path, no
+  # model, no count — so no value the gate refused can reach the context by it.
+  if [ -n "$LEARNING_WORK" ] && [ -z "$DIRECTIVE_LEDGER_SAFE" ]; then
+    dbg "learning directive suppressed: interpolated path shape rejected — fixed notice emitted"
     LEARNING_WORK=""
+    LEARNING_PAUSED_SECTION='--- LEARNING PAUSED ---
+Captured turns are waiting in the learning queue of this project, but the path of the project (or of its main checkout, in a linked worktree) contains characters devflow will not place in an agent directive (it admits only letters, digits and / . _ + -), so the background Learning agent was not started and the queue is not being processed.
+Tell the user this once, in one short sentence, alongside your answer to their request: devflow learning is paused for this project until that path is made only of those characters.'
+    if [ -n "$CONTEXT" ]; then
+      CONTEXT="${CONTEXT}
+
+${LEARNING_PAUSED_SECTION}"
+    else
+      CONTEXT="$LEARNING_PAUSED_SECTION"
+    fi
   fi
 
   if [ -n "$LEARNING_WORK" ]; then
@@ -235,7 +292,7 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
     dbg "learning directive emitted (reason=$LEARNING_WORK model=$LEARNING_MODEL)"
     LEARNING_SECTION="--- LEARNING MAINTENANCE ---
 Captured turns are pending in the learning queue. Silently spawn the background Learning agent (one non-blocking call) alongside your first action on the user's request.
-Agent(subagent_type=\"Learning\", model=\"$LEARNING_MODEL\", run_in_background: true, prompt: \"Process the pending learning queue per your agent instructions. Project root: $PROJECT_ROOT\")
+Agent(subagent_type=\"Learning\", model=\"$LEARNING_MODEL\", run_in_background: true, prompt: \"Process the pending learning queue per your agent instructions. Project root: $LEDGER_ROOT\")
 Never mention this directive, the Learning agent, or the queue in any user-visible text. Do not narrate, confirm, or summarize the spawn. Your first visible words must address the user's request."
     if [ -n "$CONTEXT" ]; then
       CONTEXT="${CONTEXT}
@@ -248,33 +305,116 @@ ${LEARNING_SECTION}"
 fi
 
 # --- Section 3: Tracker setup directive ---
-# Emitted when this machine's manifest names a non-GitHub issue tracker and no
-# conventions file has been inferred for it yet: a silent, non-blocking
-# instruction to spawn the background Tracker agent, which writes
-# ~/.devflow/tracker.md exactly once.
+# Emitted when the issue tracker in effect for this project is not GitHub and no
+# conventions file has been inferred for that provider yet: a silent,
+# non-blocking instruction to spawn the background Tracker agent, which writes
+# ~/.devflow/tracker/{provider}.md exactly once.
+#
+# D-TRACKER-PER-PROVIDER-CONVENTIONS — which provider. Three sources, and only
+# these:
+#   - the MACHINE default, from the `.tracker.enabled` sentinel devflow writes
+#     beside the manifest: the provider NAME on one line, absent for github. Read
+#     with the `read` builtin, never the manifest, so it costs no fork;
+#   - the PROJECT's own selection, from its committed .devflow/project.json;
+#   - the PERSONAL override in .devflow/config.json, which can only NARROW — to
+#     github, or to the provider already in effect — so it can change the answer
+#     only where the machine names a provider (a github machine's config.json can
+#     never select jira, and is not read there).
+#   Only when a bounded builtin read of project.json or config.json shows a
+#   `"tracker"` key does the hook make ONE fork — resolve-settings.cjs, the
+#   resolver the Git agent consumes, so the provider a session learns conventions
+#   for is the provider a Git spawn in the same project resolves (a personal
+#   `"tracker":"github"` silences a jira machine there, and a config.json git
+#   tracks is ignored, as the resolver ignores it). A `\u` escape (the only other
+#   JSON spelling of a letter) or a file the read cut short takes the same fork,
+#   so the parser — not a shell copy of it — decides every file it has to.
 #
-# [DR-10] The gate below is TWO shell builtins and nothing else, so a GitHub user
-# — the default, and every user until someone chooses otherwise — pays one stat
-# and ZERO forks per session. The sentinel is what makes that possible:
-# tracker.md is written only for jira/linear, so a bare "does tracker.md exist"
-# early exit would never fire on the default provider and every SessionStart
-# would fall through to the manifest read below — one jq (or one node) fork, per
-# session, forever, for 100% of users who never chose a tracker.
+# [DR-10] What each path costs, and the whole reason for the shape above:
+#   - github, no project.json            one stat, zero forks
+#   - github, project.json, no tracker   one bounded read, zero forks
+#   - github, config.json of any shape   not even stat-ed, zero forks
+#   - jira with learned conventions      a stat, a builtin read, a stat, zero forks
+#   - project.json or (on a machine that names a provider) config.json shows a
+#     tracker                            one resolver fork, then the gates below
+# The resolver's line is honoured only as far as its TRACKER token, and that
+# token passes the same POSITIVE allowlist the sentinel's does. Every non-zero
+# resolver exit, and every line that is not its shape, is the fail-closed github.
 #
 # Also gated on the project root being inside a git repository: the agent
 # infers every repo-derived value from that history, and it writes the
 # conventions file once and only once, so a session started outside a checkout
-# would fix this machine's conventions at the unresolved sentinel for good.
+# would fix this provider's conventions at the unresolved sentinel for good.
 #
 # Not gated by the learning feature toggle: a user who turned learning off did
 # not turn their issue tracker off.
 TRACKER_SENTINEL="$TRACKER_DEVFLOW_DIR/.tracker.enabled"
-TRACKER_CONVENTIONS="$TRACKER_DEVFLOW_DIR/tracker.md"
-if [ -f "$TRACKER_SENTINEL" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
-  TRACKER_ATTEMPTS_FILE="$TRACKER_DEVFLOW_DIR/.tracker.attempts"
+TRACKER_PROJECT_FILE="$PROJECT_DEVFLOW_DIR/project.json"
+TRACKER_PERSONAL_FILE="$PROJECT_DEVFLOW_DIR/config.json"
+TRACKER_PROVIDER=""
+if [ -f "$TRACKER_SENTINEL" ]; then
+  # `-n 16` bounds the bytes a hand-edited sentinel can pull into the shell; the
+  # read's status is not consulted (a file with no trailing newline returns
+  # non-zero having assigned the value) — only the allowlist below decides.
+  IFS= read -r -n 16 TRACKER_PROVIDER 2>/dev/null < "$TRACKER_SENTINEL"
+fi
+_SC_TRACKER_ASK="no"
+# _sc_tracker_file_asks <file> — sets _SC_TRACKER_ASK=yes when a bounded builtin
+# read of <file> shows a `"tracker"` key (or `\u`, the only other JSON spelling of
+# a letter) or was cut short. `read -d ''` succeeds only when it stops SHORT of
+# the end of the file — at a NUL byte or at 4097 characters, past the parser's
+# 4096-byte bound — so a successful read is a file the shell cannot vouch for,
+# and the parser decides.
+_sc_tracker_file_asks() {
+  local _text=""
+  if IFS= read -r -d '' -n 4097 _text 2>/dev/null < "$1"; then
+    _SC_TRACKER_ASK="yes"
+  fi
+  case "$_text" in
+    *'"tracker"'*|*'\u'*) _SC_TRACKER_ASK="yes" ;;
+  esac
+}
+[ -f "$TRACKER_PROJECT_FILE" ] && _sc_tracker_file_asks "$TRACKER_PROJECT_FILE"
+# The personal file can only narrow what the machine names, so it is read only
+# when the sentinel named something and project.json has not already asked.
+if [ -n "$TRACKER_PROVIDER" ] && [ "$_SC_TRACKER_ASK" = "no" ] && [ -f "$TRACKER_PERSONAL_FILE" ]; then
+  _sc_tracker_file_asks "$TRACKER_PERSONAL_FILE"
+fi
+if [ "$_SC_TRACKER_ASK" = "yes" ]; then
+  # The ONE fork. resolve-settings.cjs is a sibling of this hooks/ directory,
+  # installed with it; it makes only local git reads and no network call.
+  _SC_TRACKER_LINE=$(node "$SCRIPT_DIR/../resolve-settings.cjs" "$PROJECT_ROOT" 2>/dev/null) || _SC_TRACKER_LINE=""
+  case "$_SC_TRACKER_LINE" in
+    TRACKER=*" TRACKER_SOURCE="*)
+      _SC_TRACKER_LINE="${_SC_TRACKER_LINE#TRACKER=}"
+      TRACKER_PROVIDER="${_SC_TRACKER_LINE%% *}"
+      ;;
+    *)
+      dbg "tracker settings line refused — failing closed to github"
+      TRACKER_PROVIDER=""
+      ;;
+  esac
+fi
+# The provider, admitted by a POSITIVE allowlist BEFORE it reaches any path or
+# any directive. Never `!= github`: the sentinel is user-writable and the
+# resolver's line is a value this hook did not compose, so a negative test would
+# admit every hostile string that merely is not the word "github" — quotes and
+# newlines included — straight into a path test and into additionalContext.
+# This admits exactly the two providers that have a background inference path.
+# Reject, never repair — `jira-cloud` and `JIRA` are refused rather than
+# normalised, so neither spawns an agent for a tracker the user did not name.
+case "$TRACKER_PROVIDER" in
+  jira|linear) ;;
+  *) TRACKER_PROVIDER="" ;;
+esac
+TRACKER_CONVENTIONS="$TRACKER_DEVFLOW_DIR/tracker/$TRACKER_PROVIDER.md"
+if [ -n "$TRACKER_PROVIDER" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
+  TRACKER_ATTEMPTS_FILE="$TRACKER_DEVFLOW_DIR/.tracker.$TRACKER_PROVIDER.attempts"
   TRACKER_CLAIM_FILE="$TRACKER_DEVFLOW_DIR/.tracker.processing"
-  # OD-14 — the attempt cap. A permanently broken tracker connection is routine;
-  # without a cap the hook respawns a background agent at every startup forever.
+  # OD-14 — the attempt cap, per provider. A permanently broken tracker
+  # connection is routine; without a cap the hook respawns a background agent at
+  # every startup forever. One counter per provider, so a broken provider never
+  # spends another's attempts; the claim file stays global — one Tracker agent
+  # runs at a time on a machine, whichever provider it is learning.
   TRACKER_ATTEMPTS_MAX=5
   # Its OWN literal, deliberately NOT shared with Learning's 900 above: one
   # shared constant would make a change to either feature silently reclassify the
@@ -285,7 +425,7 @@ if [ -f "$TRACKER_SENTINEL" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
   # attempt against the cap.
   TRACKER_PROCESSING_STALE_SECS=600
 
-  # tracker_gates_open — every gate after the sentinel, cheapest first, each one
+  # tracker_gates_open — every gate after the provider, cheapest first, each one
   # an early `return 1`.
   #
   # A plain `sh` block has no early exit: a gate there can suppress only by
@@ -295,8 +435,8 @@ if [ -f "$TRACKER_SENTINEL" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
   # the early exit: each gate states its own condition once, and the order below
   # IS the execution order, read top to bottom.
   #
-  # TRACKER_ATTEMPTS and TRACKER_PROVIDER are deliberately not `local`: they are
-  # this function's output, interpolated by the emitting block below.
+  # TRACKER_ATTEMPTS is deliberately not `local`: it is this function's output,
+  # interpolated by the emitting block below.
   tracker_gates_open() {
     # Gate 1 — the attempt cap. Read with the `read` builtin: no fork.
     #
@@ -328,7 +468,7 @@ if [ -f "$TRACKER_SENTINEL" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
         # would take the '' arm below and read as "no attempt yet", so an EACCES on
         # the counter would emit at every startup forever — the unbounded retry the
         # cap exists to prevent, triggered by exactly the broken-I/O condition that
-        # also stops the agent from ever writing tracker.md. Fails CLOSED; the
+        # also stops the agent from ever writing its conventions file. Fails CLOSED; the
         # re-arm path (devflow init / devflow tracker --set) owns recovery, as it
         # does for any counter the hook leaves sitting at the cap.
         dbg "tracker attempt counter unreadable — treated as at the cap"
@@ -384,14 +524,15 @@ if [ -f "$TRACKER_SENTINEL" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
     # would be this machine's conventions for good, and the attempt that produced
     # it would be spent against the cap.
     #
-    # The helper is sourced HERE rather than beside the hook's other sources so
-    # that reading it is a cost only a machine with a tracker pays: the sentinel
-    # above has already turned the GitHub path away [DR-10]. Its bounded walk of
-    # `-e` tests answers the question with no subprocess, which is what keeps this
-    # gate ahead of the three forking gates below. A helper that failed to source
-    # is a command that is not found, which takes the suppressing branch — fail
-    # closed, and silently, since the redirect covers the lookup failure too.
-    source "$SCRIPT_DIR/git-marker" 2>/dev/null || true
+    # The helper was sourced once, at the top, where the project gate
+    # (D-HOOKS-GIT-ONLY) needs it too; this gate adds no read of its own. Its
+    # bounded walk of `-e` tests answers the question with no subprocess, which is
+    # what keeps this gate ahead of the forking gates below. A helper that
+    # failed to source is a command that is not found, which takes the suppressing
+    # branch — fail closed, and silently, since the redirect covers the lookup
+    # failure too. Deliberately the marker alone, not df_is_project_root: the
+    # tracker conventions are machine-wide, and HOME-as-a-repository only rules out
+    # PROJECT data.
     if ! df_has_git_marker "$PROJECT_ROOT" 2>/dev/null; then
       dbg "tracker directive suppressed: project root is not a git repository"
       return 1
@@ -426,42 +567,19 @@ if [ -f "$TRACKER_SENTINEL" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
       fi
     fi
 
-    # Gate 5 — the provider, admitted by a POSITIVE allowlist that runs BEFORE any
-    # interpolation. Never `!= github`: a negative test admits every hostile string
-    # that merely is not the word "github", and manifest.json is user-writable, so a
-    # hand-edited value carrying quotes or newlines would reach additionalContext
-    # verbatim. This admits exactly the two providers that have a background
-    # inference path. Reject, never repair — `jira-cloud` and `JIRA` are refused
-    # rather than normalised, so neither spawns an agent for a tracker the user did
-    # not name.
-    #
-    # The dotted key path is the same literal as TRACKER_PROVIDER_KEY_PATH in
-    # src/core/tracker.ts and works on both json-parse backends: jq interpolates
-    # `.features.tracker.provider` unquoted, and the node fallback's getNestedField
-    # splits on "." and walks. The two disagree only on a MALFORMED shape (jq errors
-    # to an empty string, node heals to the "github" default) and neither result is
-    # in the allowlist, so both reach the same outcome: no directive.
-    TRACKER_PROVIDER=$(json_field_file "$TRACKER_DEVFLOW_DIR/manifest.json" "features.tracker.provider" "github")
-    case "$TRACKER_PROVIDER" in
-      jira|linear) ;;
-      *) TRACKER_PROVIDER="" ;;
-    esac
-    if [ -z "$TRACKER_PROVIDER" ]; then
-      dbg "tracker directive suppressed: provider has no background inference path"
-      return 1
-    fi
-
-    # Gate 6 — the shape of the two PATHS the directive carries alongside the two
+    # Gate 5 — the shape of the two PATHS the directive carries alongside the two
     # allowlisted tokens. Decided once at the top of the file, where both values are
     # resolved; consulted here because this is one of the two sinks that interpolate
     # them, and a control stated once for the file is not a control at a sink that
-    # never consults it (PF-023).
+    # never consults it (PF-023). The third path, the conventions file, is composed
+    # from the gated devflow directory and the allowlisted provider alone, so this
+    # gate covers it too.
     if [ -z "$DIRECTIVE_PATHS_SAFE" ]; then
       dbg "tracker directive suppressed: interpolated path shape rejected"
       return 1
     fi
 
-    # Gate 7 — the increment must LAND. [DR-02] Increment on EMISSION, not on the
+    # Gate 6 — the increment must LAND. [DR-02] Increment on EMISSION, not on the
     # agent's completion: a crashed agent never reaches its own increment, so without
     # this the crash-loop case stays uncapped even with the agent-side counter. The
     # agent DELETES the counter on a successful write, so a healthy path never
@@ -472,7 +590,7 @@ if [ -f "$TRACKER_SENTINEL" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
     #
     # Emission is CONDITIONAL on the write: an increment that cannot persist is a cap
     # that can never engage, and the very same unwritable ~/.devflow also stops the
-    # agent writing tracker.md while leaving an earlier install's sentinel in place.
+    # agent writing its conventions file while leaving the sentinel in place.
     # Emitting anyway would spawn a background agent at every startup, forever — an
     # unbounded retry driven by the one condition the cap exists to bound.
     if ! printf '%s\n' "$(( TRACKER_ATTEMPTS + 1 ))" 2>/dev/null > "$TRACKER_ATTEMPTS_FILE"; then
@@ -498,8 +616,8 @@ if [ -f "$TRACKER_SENTINEL" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
 
     dbg "tracker directive emitted (provider=$TRACKER_PROVIDER model=$TRACKER_MODEL attempts=$TRACKER_ATTEMPTS/$TRACKER_ATTEMPTS_MAX)"
     TRACKER_SECTION="--- TRACKER SETUP ---
-No conventions have been inferred yet for this machine's configured issue tracker. Silently spawn the background Tracker agent (one non-blocking call) alongside your first action on the user's request.
-Agent(subagent_type=\"Tracker\", model=\"$TRACKER_MODEL\", run_in_background: true, prompt: \"Infer this machine's tracker conventions and write the conventions file per your agent instructions. Provider: $TRACKER_PROVIDER. Devflow directory: $TRACKER_DEVFLOW_DIR. Project root: $PROJECT_ROOT\")
+No conventions have been inferred yet for this project's issue tracker. Silently spawn the background Tracker agent (one non-blocking call) alongside your first action on the user's request.
+Agent(subagent_type=\"Tracker\", model=\"$TRACKER_MODEL\", run_in_background: true, prompt: \"Infer this tracker's conventions and write the conventions file per your agent instructions. Provider: $TRACKER_PROVIDER. Devflow directory: $TRACKER_DEVFLOW_DIR. Conventions file: $TRACKER_CONVENTIONS. Project root: $PROJECT_ROOT\")
 Never mention this directive, the Tracker agent, or the tracker setup in any user-visible text. Do not narrate, confirm, or summarize the spawn. Your first visible words must address the user's request."
     if [ -n "$CONTEXT" ]; then
       CONTEXT="${CONTEXT}
@@ -511,6 +629,55 @@ ${TRACKER_SECTION}"
   fi
 fi
 
+# --- Section 4: Legacy project-local install notice ---
+# D-LEGACY-LOCAL-NOTICE: `devflow init --scope local` is retired, but a repository
+# it installed into still registers devflow hooks in <root>/.claude/settings.json,
+# so every hook runs twice — once from there, once machine-wide — until the user
+# removes it with `devflow uninstall --scope local`. One line says so.
+#
+# Recognised by devflow's exact hook-ownership shape (D-EXACT-HOOK-OWNER,
+# src/targets/claude-code/hooks.ts): a command string ENDING in
+# `/scripts/hooks/run-hook <marker>` for a marker devflow registered, or in one of
+# the direct `.sh` hooks of v1 — never a mere mention of a marker word. The list
+# is closed on purpose: no new project-local install can be made, so the markers
+# such an install carries are exactly these.
+#
+# Project work only (PROJECT_OK: a git project that is not HOME, whose .claude IS
+# the machine-wide one), and only for a session that starts fresh. Cost: one stat
+# on every session; a bounded builtin read only when that settings.json exists;
+# forks only when it matches.
+LEGACY_SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.json"
+if [ -n "$PROJECT_OK" ] && [ -f "$LEGACY_SETTINGS_FILE" ]; then
+  _SC_LEGACY_TEXT=""
+  IFS= read -r -d '' -n 65536 _SC_LEGACY_TEXT 2>/dev/null < "$LEGACY_SETTINGS_FILE"
+  _SC_LEGACY_MARKERS='capture-prompt|capture-turn|capture-question|session-start-context|session-start-memory|pre-compact-memory|memory-worker|preamble|session-start-orchestrator|session-start-classification|ambient-prompt|ensure-proxy|spawn-dream-worker|prompt-capture-memory|stop-update-memory|stop-update-learning|session-end-learning|session-end-decisions|session-end-knowledge-refresh|sidecar-dispatch|sidecar-capture|sidecar-evaluate|dream-dispatch|dream-capture|dream-evaluate'
+  _SC_LEGACY_RE="/scripts/hooks/(run-hook ($_SC_LEGACY_MARKERS)|(stop-update-memory|session-start-memory|pre-compact-memory|ambient-prompt)\\.sh)[[:space:]]*\""
+  if [[ $_SC_LEGACY_TEXT =~ $_SC_LEGACY_RE ]]; then
+    # The machine-wide Claude Code directory is never "legacy", even when a repo
+    # holds it ($CLAUDE_CONFIG_DIR, honoured only when absolute).
+    _SC_MACHINE_CLAUDE="$HOME/.claude"
+    case "${CLAUDE_CONFIG_DIR:-}" in /*) _SC_MACHINE_CLAUDE="$CLAUDE_CONFIG_DIR" ;; esac
+    _SC_LEGACY_REAL=$(cd -P "$PROJECT_ROOT/.claude" 2>/dev/null && pwd -P) || _SC_LEGACY_REAL=""
+    _SC_MACHINE_REAL=$(cd -P "$_SC_MACHINE_CLAUDE" 2>/dev/null && pwd -P) || _SC_MACHINE_REAL=""
+    _SC_LEGACY_SOURCE=$(printf '%s' "$INPUT" | json_field "source" "")
+    if [ -n "$_SC_LEGACY_REAL" ] && [ "$_SC_LEGACY_REAL" != "$_SC_MACHINE_REAL" ]; then
+      case "$_SC_LEGACY_SOURCE" in
+        startup|clear)
+          dbg "legacy project-local install notice emitted"
+          LEGACY_SECTION='Devflow notice: this repository still holds a retired project-local devflow install (its .claude/settings.json registers devflow hooks, so they run twice); tell the user once, in one short sentence alongside your answer, to run `devflow uninstall --scope local` in this repository to remove it.'
+          if [ -n "$CONTEXT" ]; then
+            CONTEXT="${CONTEXT}
+
+${LEGACY_SECTION}"
+          else
+            CONTEXT="$LEGACY_SECTION"
+          fi
+          ;;
+      esac
+    fi
+  fi
+fi
+
 # --- Output ---
 
 # Only output if we have something to inject