devflow-kit 2.4.0 → 2.5.0

package/src/assets/scripts/hooks/preamble

@@ -66,11 +66,8 @@ elif [[ "$HEAD" == "Implement the following plan:"* ]]; then
 elif [[ "$HEAD" == "/"* ]]; then
   dbg "EXIT: slash command — no reminder"
 else
-  # Model-tier taxonomy (haiku=mechanical, sonnet=defined execution, opus=analysis/design/research)
-  # is cross-referenced with the full routing table in orchestrator-charter.md.
-  # Update both together if routing changes.
   dbg "ORCHESTRATOR_REMINDER injected"
-  json_prompt_output "Orchestrator reminder: coordinate, don't produce — delegate edits, builds, multi-file reads, and debug loops via the Agent tool (haiku=mechanical, sonnet=defined execution, opus=analysis/design/research) or the matching devflow workflow skill.
+  json_prompt_output "Orchestrator reminder: coordinate, don't produce — delegate edits, builds, multi-file reads, and debug loops to the fitting roster agent (Agent tool) or the matching devflow workflow skill.
 Keep only judgment work mainline: conversation, decisions, routing, synthesis of agent reports."
 fi
 

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

@@ -22,18 +22,41 @@
 # queue_append_both <memory_queue> <learning_queue> <memory_enabled> <learning_enabled> <role> <content> <ts>
 #   Calls queue_append_row for each queue whose *_enabled flag is "true". Each
 #   queue is gated independently -- callers compute memory_enabled/learning_enabled
-#   from feature config themselves (see queue_read_gates below for the one-fork
-#   combined read that keeps this to a single config subprocess per hook).
+#   themselves (see queue_read_gates below for the at-most-one-fork read of both).
 #
-# queue_read_gates <feature_config_path>
-#   Reads BOTH the "memory" and "learning" fields from .devflow/config.json in a
-#   SINGLE subprocess fork (AC-P1 -- exactly one config-read fork per capture
-#   hook, not two). Sets _QG_MEMORY and _QG_LEARNING ("true"/"false") in the
-#   caller's scope. Missing config file -> both default "true". The two values
-#   are newline-separated rather than using a control-character delimiter:
-#   they are always the literal strings "true"/"false", never arbitrary
-#   content, so a plain newline split is unambiguous and easy to review (no
-#   invisible bytes hiding in the source).
+# queue_read_gates <manifest_path>
+#   Reads BOTH `features.memory` and `features.learning` from the devflow-global
+#   ~/.devflow/manifest.json in at most ONE subprocess fork (AC-P1 -- at most one
+#   gate-read fork per capture hook, not two; none when D-GATES-FAST-PATH
+#   settles it). Sets _QG_MEMORY and _QG_LEARNING ("true"/"false") in the
+#   caller's scope. The two values are newline-separated
+#   rather than using a control-character delimiter: they are always the literal
+#   strings "true"/"false", never arbitrary content, so a plain newline split is
+#   unambiguous and easy to review (no invisible bytes hiding in the source).
+#
+#   D-FEATURES-MACHINE-WIDE (src/core/feature-switch.ts): memory and learning are
+#   switched for the WHOLE MACHINE by the manifest alone -- `devflow init` and
+#   `devflow memory|learning --enable/--disable` both write it -- so the answer is
+#   the same in every repo and every non-git cwd. The per-repo
+#   .devflow/config.json is never read here: its old memory/learning keys are
+#   retired, and reading them is what let a feature keep running in every repo
+#   but the one `init --no-<feature>` ran in (#378). Only an explicit boolean
+#   `false` switches a feature off -- an absent, unreadable or malformed manifest,
+#   a missing key, or a non-boolean value leaves it ON (fail-open, ADR-028), the
+#   same rule isMachineFeatureOn() applies in the CLI.
+#
+#   D-LEARNING-LEGACY-DECISIONS: learning reads `features.learning` when it is a
+#   boolean, else the pre-rename `features.decisions` (ADR-011) -- readManifest's
+#   migration precedence exactly, so a legacy `decisions: false` switches
+#   learning off before any command has healed the file. Only a boolean `false`
+#   in whichever key decides is off, as above.
+#
+#   Every hook that gates on memory or learning reads it through here: the
+#   capture hooks, session-start-context (Sections 1-2), memory-worker,
+#   session-start-memory, pre-compact-memory and background-memory-update. The
+#   callers resolve <manifest_path> from ${DEVFLOW_DIR:-$HOME/.devflow} BEFORE
+#   they shadow DEVFLOW_DIR with the project-scoped .devflow (memory-worker hands
+#   its resolved path to the background worker it spawns).
 
 queue_append_row() {
   local _qar_file="$1" _qar_role="$2" _qar_content="$3" _qar_ts="$4"
@@ -84,27 +107,48 @@ queue_append_both() {
 }
 
 queue_read_gates() {
-  local _qg_config="$1"
+  local _qg_manifest="${1:-}" _qg_text="" _qg_parse="false"
   _QG_MEMORY="true"
   _QG_LEARNING="true"
 
-  if [ -f "$_qg_config" ]; then
+  if [ -n "$_qg_manifest" ] && [ -f "$_qg_manifest" ]; then
+    # D-GATES-FAST-PATH: every capture hook and every session start pays this
+    # read, and on most machines both switches are on. Only a JSON boolean
+    # `false` under a "memory", "learning" or "decisions" key can switch anything
+    # off, and a `\u` escape is the only JSON spelling of a letter other than the
+    # letter itself, so without one such a key appears literally. A text holding
+    # no `\u` and no key-then-`false` sequence therefore cannot switch anything
+    # off -- valid or not, it reads both-on either way -- and is settled by shell
+    # builtins (read, case, [[ =~ ]]) with no jq/node fork; everything else takes
+    # the full parse below. `read -d ''` succeeds only on reaching a NUL byte,
+    # i.e. before the end of the file, so a text it cut short is parsed in full
+    # too. An unreadable file reads empty and fails open, as the parser would.
+    local _qg_re='"(memory|learning|decisions)"[[:space:]]*:[[:space:]]*false'
+    IFS= read -r -d '' _qg_text 2>/dev/null < "$_qg_manifest" && _qg_parse="true"
+    case "$_qg_text" in *'\u'*) _qg_parse="true" ;; esac
+    if [[ $_qg_text =~ $_qg_re ]]; then _qg_parse="true"; fi
+  fi
+
+  if [ "$_qg_parse" = "true" ]; then
     local _qg_fields
     if [ "$_HAS_JQ" = "true" ]; then
-      # if/then/else (not //) preserves an explicit `false` -- mirrors json_field_file's
-      # own documented rationale (jq's // would replace a real `false` with the default).
-      # The comma produces two raw-output lines (newline-separated) in one jq process.
+      # `try` covers a manifest whose top level or `features` is not an object; a
+      # parse failure empties the output, which reads as "not switched off". The
+      # comma produces two raw-output lines (newline-separated) in one jq process.
       _qg_fields=$(jq -r '
-        (if (.memory | type) == "null" then "true" else (.memory | tostring) end),
-        (if (.learning | type) == "null" then "true" else (.learning | tostring) end)
-      ' "$_qg_config" 2>/dev/null) || _qg_fields=""
+        (if (try .features.memory catch null) == false then "false" else "true" end),
+        (if (try (.features | if (.learning | type) == "boolean" then .learning else .decisions end) catch null) == false
+          then "false" else "true" end)
+      ' "$_qg_manifest" 2>/dev/null) || _qg_fields=""
     else
       _qg_fields=$(node -e "
-        const j = JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'));
-        const m = j.memory === undefined ? 'true' : String(j.memory);
-        const d = j.learning === undefined ? 'true' : String(j.learning);
-        process.stdout.write(m + String.fromCharCode(10) + d);
-      " -- "$_qg_config" 2>/dev/null) || _qg_fields=""
+        const m = JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'));
+        const f = m !== null && typeof m === 'object' ? m.features : undefined;
+        const isObj = f !== null && typeof f === 'object';
+        const on = (k) => !(isObj && f[k] === false);
+        const learnKey = isObj && typeof f.learning !== 'boolean' ? 'decisions' : 'learning';
+        process.stdout.write(String(on('memory')) + String.fromCharCode(10) + String(on(learnKey)));
+      " -- "$_qg_manifest" 2>/dev/null) || _qg_fields=""
     fi
     if [ -n "$_qg_fields" ]; then
       _QG_MEMORY="${_qg_fields%%$'\n'*}"

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

@@ -2,8 +2,9 @@
 
 # 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 machine-wide `features.learning` switch in
+# ~/.devflow/manifest.json (D-FEATURES-MACHINE-WIDE) — this hook itself is never
+# disabled.
 #
 # 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 +12,10 @@
 # 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.
 
 # Safe no-op fallback: must exist before hook-bootstrap is sourced.
 dbg() { :; }
@@ -61,18 +66,89 @@ PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || 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 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".
+#
+# 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 `;` 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.
+#
+# 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 both values are 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".
+#
+# 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.
+DIRECTIVE_ROOT_SAFE="yes"
+case "$PROJECT_ROOT" in
+  ''|*[!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.
+DIRECTIVE_PATHS_SAFE="$DIRECTIVE_ROOT_SAFE"
+case "$TRACKER_DEVFLOW_DIR" in
+  ''|*[!A-Za-z0-9/._-]*)
+    DIRECTIVE_PATHS_SAFE=""
+    ;;
+esac
+
 DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
 LEARNING_DIR="$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-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.
+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"
+LEARNING_ENABLED="$_QG_LEARNING"
 
 # --- Section 1: Project Decisions TL;DR ---
 if [ "$LEARNING_ENABLED" = "true" ]; then
@@ -130,6 +206,13 @@ 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"
+    LEARNING_WORK=""
+  fi
+
   if [ -n "$LEARNING_WORK" ]; then
     # Model resolution: project learning.json → global ~/.devflow/learning.json → opus
     LEARNING_MODEL=""
@@ -164,6 +247,270 @@ ${LEARNING_SECTION}"
   fi
 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.
+#
+# [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.
+#
+# 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.
+#
+# 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_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.
+  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 sentinel, 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 and TRACKER_PROVIDER are deliberately not `local`: they are
+  # 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 tracker.md. 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 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
+    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 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
+    # 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).
+    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
+    # 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 tracker.md while leaving an earlier install's 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 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\")
+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
+
 # --- Output ---
 
 # Only output if we have something to inject

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

@@ -42,20 +42,24 @@ source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
 PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 [ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
 
+# The machine-wide manifest (the memory switch, D-FEATURES-MACHINE-WIDE in
+# queue-append) is user-scope: resolve it from the inherited DEVFLOW_DIR (or
+# ~/.devflow) BEFORE the project-scoped assignment below shadows that value.
+DEVFLOW_MANIFEST="${DEVFLOW_DIR:-$HOME/.devflow}/manifest.json"
 DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
 MEMORY_DIR="$DEVFLOW_DIR/memory"
 
 # Normal logging
 source "$SCRIPT_DIR/hook-log-init" "session-start-memory"
 
-# Check feature config — single source of truth for memory enabled/disabled (ADR-001).
-FEATURE_CONFIG="$DEVFLOW_DIR/config.json"
-if [ -f "$FEATURE_CONFIG" ]; then
-  MEMORY_ENABLED=$(json_field_file "$FEATURE_CONFIG" "memory" "true")
-  if [ "$MEMORY_ENABLED" = "false" ]; then
-    dbg "EXIT: memory disabled in feature config"
-    exit 0
-  fi
+# Memory gate: the machine-wide switch, read by the helper every memory/learning
+# gate shares (D-FEATURES-MACHINE-WIDE, see queue-append). The per-repo config
+# is never consulted.
+source "$SCRIPT_DIR/queue-append" || { echo "session-start-memory: failed to source queue-append" >&2; exit 1; }
+queue_read_gates "$DEVFLOW_MANIFEST"
+if [ "$_QG_MEMORY" != "true" ]; then
+  dbg "EXIT: memory disabled machine-wide"
+  exit 0
 fi
 
 # --- D56c cold-path recovery: orphaned .pending-turns.processing ---