devflow-kit 2.4.0 → 3.0.0

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

@@ -2,8 +2,11 @@
 
 # SessionStart Hook: Cross-Feature Context Injection
 # Always-on hook that injects learning context as additionalContext. Sections
-# are gated by the `learning` field in feature config (config-only, ADR-001) —
-# 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
@@ -11,6 +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 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() { :; }
@@ -47,37 +58,147 @@ 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=""
 
-DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
-LEARNING_DIR="$DEVFLOW_DIR/learning"
+# 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.
+#
+# 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, `\`
+# reads as an escape, LF and CR put the rest of the path on its own line as free
+# text — and admits every one that was not on the list. An allowlist admits only
+# what is known to be inert, so the next escape nobody has thought of is refused
+# 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 `;` 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
+# UTF-8 locale and refuses it under C. Every byte the gate exists to refuse —
+# quote, backslash, CR, LF, space, backtick, `$`, `;` — is outside the range in
+# 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 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 root
+# must not read as "no forbidden character, therefore safe".
+#
+# 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/._+-]*)
+    DIRECTIVE_ROOT_SAFE=""
+    ;;
+esac
+
+# 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/._+-]*)
+    DIRECTIVE_PATHS_SAFE=""
+    ;;
+esac
+
+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 (config-only) ---
-FEATURE_CONFIG="$DEVFLOW_DIR/config.json"
-LEARNING_ENABLED="true"
-if [ -f "$FEATURE_CONFIG" ]; then
-  LEARNING_ENABLED=$(json_field_file "$FEATURE_CONFIG" "learning" "true")
-fi
+# --- 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" "$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
@@ -130,6 +251,25 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
     LEARNING_WORK="queue"
   fi
 
+  # $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
     # Model resolution: project learning.json → global ~/.devflow/learning.json → opus
     LEARNING_MODEL=""
@@ -152,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}
@@ -164,6 +304,380 @@ ${LEARNING_SECTION}"
   fi
 fi
 
+# --- Section 3: Tracker setup directive ---
+# 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] 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 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_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, 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
+  # other's live runs as crashed. 600s is longer than the memory worker's 300s
+  # lock (a Tracker run does more — a capability probe plus bounded git scans)
+  # and shorter than Learning's 900s (no multi-part curation phase). Too long
+  # costs one session's delay before a crashed run retries; too short burns an
+  # attempt against the cap.
+  TRACKER_PROCESSING_STALE_SECS=600
+
+  # 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
+  # clearing a flag that every later gate must then re-test, which turns the
+  # cheapest-first ordering that delivers [DR-10]'s zero-fork guarantee into a
+  # stack of re-entries rather than the linear sequence it is. A function supplies
+  # the early exit: each gate states its own condition once, and the order below
+  # IS the execution order, read top to bottom.
+  #
+  # 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.
+    #
+    # The counter's shape is ONE decimal integer line and nothing else (PF-062 —
+    # document the shape of any file that gates an action, and keep absent and
+    # malformed distinct from a value). Absent means "no attempt yet" = 0.
+    # Malformed self-heals to 0 and is overwritten with a well-formed count on
+    # emission below, so a stray byte can never recur: refusing forever would
+    # disable inference permanently with no user-visible reason, and treating it as
+    # uncapped would defeat the cap. `read` returns non-zero at an EOF with no
+    # trailing newline but HAS assigned the variable, so its status is deliberately
+    # not consulted — only the value's shape is.
+    #
+    # `-n 16` bounds the BYTES consumed, which the `case` below cannot: the file is
+    # user-scope and hand-editable, and one very long line would otherwise be pulled
+    # whole into a shell variable and pattern-matched whole on the SessionStart
+    # critical path. Sixteen characters is past every arm's decision point — a
+    # well-formed count never reaches two digits, and the out-of-range arm fires at
+    # seven — so every arm keeps the verdict it would have reached unbounded.
+    # `2>/dev/null` is spelled BEFORE the input redirect for the same reason it is
+    # on the write below: redirections apply left to right, and a failed open is
+    # reported by the shell itself, so silencing stderr afterwards would be too late.
+    TRACKER_ATTEMPTS=""
+    if [ -f "$TRACKER_ATTEMPTS_FILE" ]; then
+      if [ -r "$TRACKER_ATTEMPTS_FILE" ]; then
+        IFS= read -r -n 16 TRACKER_ATTEMPTS 2>/dev/null < "$TRACKER_ATTEMPTS_FILE"
+      else
+        # Present but unreadable is NOT a fresh start. Leaving the variable empty
+        # 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 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"
+        TRACKER_ATTEMPTS="$TRACKER_ATTEMPTS_MAX"
+      fi
+    fi
+    case "$TRACKER_ATTEMPTS" in
+      '') TRACKER_ATTEMPTS=0 ;;
+      *[!0-9]*)
+        dbg "tracker attempt counter malformed — self-healed to 0"
+        TRACKER_ATTEMPTS=0
+        ;;
+      0) ;;  # a bare zero is a well-formed count, not a padded one
+      0*)
+        # A zero-padded count is ONE string that this hook's two consumers of it read
+        # in DIFFERENT BASES. `[ "$N" -ge "$MAX" ]` parses base 10, so `08` compares
+        # as eight; the `$(( N + 1 ))` that writes the next count is shell arithmetic,
+        # where a leading `0` means OCTAL and `08` is "value too great for base" — an
+        # error that escapes the write's own `2>/dev/null`, because expansion runs
+        # before redirection. Nothing in the padded shape says which reading was
+        # meant, so it self-heals to 0 with every other malformed value instead of
+        # being carried into the disagreement. This hook writes a bare decimal, so
+        # padding came from elsewhere. Placed BEFORE the digit-count arm so a
+        # six-character `000008` heals rather than reading as "six digits, at the cap".
+        dbg "tracker attempt counter zero-padded — self-healed to 0"
+        TRACKER_ATTEMPTS=0
+        ;;
+      ???????*)
+        # Bounded before the comparison: `[ "$N" -ge 5 ]` on a value past intmax_t
+        # prints "integer expression expected" to stderr and takes the FALSE branch,
+        # so an unbounded digit string would fail OPEN — uncapped — and leak a shell
+        # error. `-n 16` above already puts that state out of reach; this arm is the
+        # semantic half and survives a change to the read bound. It matches SEVEN
+        # digits or more (the earlier arms have taken every non-digit and every
+        # zero-padded value), which is the shape CLAUDE.md documents as "at the cap",
+        # and a count that matters needs one digit, so anything reaching here is past
+        # the cap by six orders of magnitude. Six digits and fewer are compared as
+        # the integers they are.
+        dbg "tracker attempt counter out of range — treated as at the cap"
+        TRACKER_ATTEMPTS="$TRACKER_ATTEMPTS_MAX"
+        ;;
+    esac
+    if [ "$TRACKER_ATTEMPTS" -ge "$TRACKER_ATTEMPTS_MAX" ]; then
+      dbg "tracker directive suppressed: attempt cap reached ($TRACKER_ATTEMPTS/$TRACKER_ATTEMPTS_MAX)"
+      return 1
+    fi
+
+    # Gate 2 — the repository. Every repo-derived value the Tracker agent writes
+    # comes from the project root's history, and the agent refuses to infer from
+    # history at all when the root carries no git marker — outside a checkout it
+    # would write its unresolved sentinel into every one of those sections. It
+    # writes the conventions file ONCE, create-exclusive, so that degraded file
+    # would be this machine's conventions for good, and the attempt that produced
+    # it would be spent against the cap.
+    #
+    # 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
+    fi
+
+    # Gate 3 — source. Only a fresh session (startup) and a cleared one (clear)
+    # begin work that needs conventions; resume and compact continue a session that
+    # already had its chance, so re-asking there would spawn an agent mid-flight.
+    TRACKER_SOURCE=$(printf '%s' "$INPUT" | json_field "source" "")
+    case "$TRACKER_SOURCE" in
+      startup|clear) ;;
+      *)
+        dbg "tracker directive suppressed: not a session start"
+        return 1
+        ;;
+    esac
+
+    # Gate 4 — the claim file, mirroring Section 2's freshness check. A FRESH
+    # claim means a live Tracker agent owns the run. A STALE one means a previous
+    # run crashed, so re-arm — but never delete it: re-claiming is the agent's job
+    # (it touches the file), and a hook that deleted it would race a slow-but-live
+    # run. An unreadable mtime falls to the suppressing branch (fail closed).
+    if [ -f "$TRACKER_CLAIM_FILE" ]; then
+      source "$SCRIPT_DIR/get-mtime" 2>/dev/null || true
+      _SC_TRACKER_MTIME=$(get_mtime "$TRACKER_CLAIM_FILE" 2>/dev/null || true)
+      _SC_TRACKER_NOW=$(date +%s)
+      if [ -n "$_SC_TRACKER_MTIME" ] && [ $(( _SC_TRACKER_NOW - _SC_TRACKER_MTIME )) -ge "$TRACKER_PROCESSING_STALE_SECS" ]; then
+        dbg "tracker claim file is stale — previous run crashed, re-arming"
+      else
+        dbg "tracker directive suppressed: fresh .tracker.processing (live agent owns the run)"
+        return 1
+      fi
+    fi
+
+    # 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). 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 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
+    # accumulates. printf is a builtin and the redirect is the shell's — no fork.
+    # `2>/dev/null` is spelled FIRST: redirections are applied left to right, and a
+    # failed open on the counter path is reported by the shell itself, so silencing
+    # stderr after the failing redirect would be too late to keep the hook quiet.
+    #
+    # 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 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
+      dbg "tracker directive suppressed: attempt counter not writable"
+      return 1
+    fi
+
+    return 0
+  }
+
+  if tracker_gates_open; then
+    # Allowlisted the same way LEARNING_MODEL is. The tier is
+    # a constant today — there is no tracker tuning config — so this `case` is an
+    # assertion of the closed domain rather than a sanitiser, and it is the single
+    # place the tier is validated, so a later config read cannot be wired in
+    # without passing through it. The literal must equal the Tracker agent's
+    # frontmatter `model:` (pinned against loadShippedDefaults in shell-hooks).
+    TRACKER_MODEL="sonnet"
+    case "$TRACKER_MODEL" in
+      opus|sonnet|haiku) ;;
+      *) TRACKER_MODEL="sonnet" ;;
+    esac
+
+    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 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}
+
+${TRACKER_SECTION}"
+    else
+      CONTEXT="$TRACKER_SECTION"
+    fi
+  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