devflow-kit 2.4.0 → 3.0.0

package/src/assets/scripts/hooks/json-helper.cjs

@@ -24,7 +24,12 @@
 //   session-output <context>              Build SessionStart output envelope
 //   prompt-output <context>               Build UserPromptSubmit output envelope
 //   backup-construct                      Build pre-compact backup JSON from --arg pairs
-//   assign-anchor <type> <obs_id>         Claim next ADR/PF number, render both .md files
+//   assign-anchor <type> <obs_id> [--allow-collision]
+//                                          Claim next ADR/PF number, render both .md files.
+//                                          Refuses on a pre-mint citation collision (E4) unless
+//                                          --allow-collision is passed.
+//   next-anchor <type>                    Read-only: print the next candidate ADR/PF id and
+//                                          any pre-mint collision hits; mutates nothing (E4)
 //   retire-anchor <anchor_id> <status>    Flip ledger row status, re-render both .md files
 //   refresh-anchor <anchor_id>            Re-project log obs onto ledger row, re-render
 //   rotate-observations [<log>] [<arch>]  Archive observing rows older than 30 days
@@ -33,6 +38,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 
 const op = process.argv[2];
 const args = process.argv.slice(3);
@@ -156,6 +162,154 @@ function nextAnchorFromLedger(ledgerRows, type) {
   return { anchorId: `${prefix}-${nextN}`, nextN };
 }
 
+// ---------------------------------------------------------------------------
+// Pre-mint collision guard (E4).
+//
+// A design doc can cite a design-local number ("PF-017") in tracked source
+// before the ledger ever mints that same number for an unrelated entry — the
+// two silently collide and nothing catches it until a human notices the text
+// doesn't match. This scans the project tree for a whole-word citation of the
+// candidate id BEFORE assign-anchor writes it, and refuses to mint over a hit.
+// The consumer-side counterpart lives in mdl's scripts/verify-ledger-citations.mjs.
+// ---------------------------------------------------------------------------
+
+/** Directory names excluded from collision scanning at any depth (E4). */
+const COLLISION_SCAN_EXCLUDED_SEGMENTS = new Set(['.git', 'node_modules', 'target', 'dist']);
+
+/** Files larger than this are skipped during collision scanning — bounds the scan (E4). */
+const COLLISION_SCAN_MAX_FILE_BYTES = 5 * 1024 * 1024;
+
+/**
+ * True when a project-relative path must be excluded from collision scanning:
+ * the ledger's own files (`.devflow/learning/**`, self-citation is expected,
+ * not a collision) or any of the excluded directory segments.
+ *
+ * @param {string} relPath - path relative to the project root, either separator style
+ * @returns {boolean}
+ */
+function isCollisionScanExcluded(relPath) {
+  const norm = relPath.split(path.sep).join('/');
+  if (norm === '.devflow/learning' || norm.startsWith('.devflow/learning/')) return true;
+  return norm.split('/').some(seg => COLLISION_SCAN_EXCLUDED_SEGMENTS.has(seg));
+}
+
+/**
+ * List tracked files via `git ls-files` (respects .gitignore; args passed as an
+ * array — never shelled through a string-built command). Throws when the
+ * project root is not a git working tree or the `git` binary is unavailable;
+ * callers fall back to `listFsWalkFiles`.
+ *
+ * D-NO-FSMONITOR: `ls-files` reads the index, and reading the index runs the
+ * command a repository's config names in `core.fsmonitor` — code chosen by the
+ * repository this hook runs inside. The call turns it off for itself
+ * (`-c core.fsmonitor=false`), so the listing stays a pure read.
+ *
+ * @param {string} projectRoot
+ * @returns {string[]} project-relative paths
+ */
+function listGitTrackedFiles(projectRoot) {
+  const out = execFileSync('git', ['-c', 'core.fsmonitor=false', 'ls-files', '-z'], {
+    cwd: projectRoot,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return out.toString('utf8').split('\0').filter(Boolean);
+}
+
+/**
+ * Bounded, non-recursing-into-excluded-dirs fs walk — fallback for a project
+ * root that is not a git working tree. The walk is bounded by construction:
+ * it only descends into directories actually present on disk, and never
+ * descends into an excluded directory at all (E4).
+ *
+ * @param {string} projectRoot
+ * @returns {string[]} project-relative paths
+ */
+function listFsWalkFiles(projectRoot) {
+  const results = [];
+  const stack = [''];
+  while (stack.length > 0) {
+    const relDir = stack.pop();
+    const absDir = relDir ? path.join(projectRoot, relDir) : projectRoot;
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      continue; // unreadable dir — best-effort scan, skip
+    }
+    for (const entry of entries) {
+      const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (isCollisionScanExcluded(relPath)) continue;
+      if (entry.isDirectory()) {
+        stack.push(relPath);
+      } else if (entry.isFile()) {
+        results.push(relPath);
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * Scan the project tree for a whole-word citation of `id` (e.g. `ADR-042`),
+ * excluding the ledger's own files and common vendored/build directories.
+ * Prefers tracked files (`git ls-files`) when the project root is a git
+ * working tree; falls back to a bounded fs walk otherwise. Best-effort:
+ * unreadable, binary, or oversized files are skipped rather than failing
+ * the scan.
+ *
+ * @param {string} projectRoot
+ * @param {string} id - e.g. 'ADR-042' or 'PF-017'
+ * @returns {{ file: string, line: number }[]} hits, empty when no collision
+ */
+function scanForAnchorCollision(projectRoot, id) {
+  let files;
+  try {
+    files = listGitTrackedFiles(projectRoot);
+  } catch {
+    files = listFsWalkFiles(projectRoot);
+  }
+
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`\\b${escaped}\\b`);
+  const hits = [];
+  for (const relPath of files) {
+    if (isCollisionScanExcluded(relPath)) continue;
+    const absPath = path.join(projectRoot, relPath);
+    let stat;
+    try {
+      stat = fs.statSync(absPath);
+    } catch {
+      continue; // race: listed then removed — best-effort scan, skip
+    }
+    if (!stat.isFile() || stat.size > COLLISION_SCAN_MAX_FILE_BYTES) continue;
+    let content;
+    try {
+      content = fs.readFileSync(absPath, 'utf8');
+    } catch {
+      continue; // unreadable or invalid utf8 — best-effort scan, skip
+    }
+    if (content.includes('\u0000')) continue; // binary heuristic
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (pattern.test(lines[i])) {
+        hits.push({ file: relPath, line: i + 1 });
+      }
+    }
+  }
+  return hits;
+}
+
+/**
+ * Format collision hits for a stderr/stdout report — one `file:line` per line,
+ * two-space indented (E4).
+ *
+ * @param {{ file: string, line: number }[]} hits
+ * @returns {string}
+ */
+function formatCollisionHits(hits) {
+  return hits.map(h => `  ${h.file}:${h.line}`).join('\n');
+}
+
 /**
  * Read .decisions-usage.json. Returns {version, entries} or empty default.
  * @param {string} projectRoot - Path to project root (cwd)
@@ -533,20 +687,36 @@ try {
     }
 
     // -------------------------------------------------------------------------
-    // assign-anchor <type> <obs_id>
+    // assign-anchor <type> <obs_id> [--allow-collision]
     // AC-A2: Assign next anchor ID for the given type (decision|pitfall) to the
     // observation identified by obs_id in decisions-log.jsonl. Atomic under a
     // single .decisions.lock acquisition. Registers usage, re-renders both .md.
     //
+    // E4: before writing, refuses if the candidate id is already cited as a
+    // whole word somewhere in tracked source (a pre-mint collision — see
+    // scanForAnchorCollision above). --allow-collision skips the scan and
+    // mints anyway, for the human-ruled case where the citation should be
+    // superseded by the ledger's number.
+    //
     // Locking discipline: holds ONLY .decisions.lock (never .observations.lock).
     // O(anchored) — single pass for max numeric suffix (AC-P2).
     // -------------------------------------------------------------------------
     case 'assign-anchor': {
-      const assignType = args[0]; // 'decision' or 'pitfall'
-      const assignObsId = args[1];
+      const aaKnownFlags = new Set(['--allow-collision']);
+      const aaFlags = args.filter(a => a.startsWith('--'));
+      const aaUnknownFlags = aaFlags.filter(f => !aaKnownFlags.has(f));
+      if (aaUnknownFlags.length > 0) {
+        process.stderr.write(`assign-anchor: unknown flag(s): ${aaUnknownFlags.join(', ')}\n`);
+        process.exit(1);
+      }
+      const aaAllowCollision = aaFlags.includes('--allow-collision');
+      const aaPositional = args.filter(a => !a.startsWith('--'));
+
+      const assignType = aaPositional[0]; // 'decision' or 'pitfall'
+      const assignObsId = aaPositional[1];
 
       if (!assignType || !assignObsId) {
-        process.stderr.write('assign-anchor: usage: assign-anchor <type> <obs_id>\n');
+        process.stderr.write('assign-anchor: usage: assign-anchor <type> <obs_id> [--allow-collision]\n');
         process.exit(1);
       }
       if (assignType !== 'decision' && assignType !== 'pitfall') {
@@ -565,6 +735,22 @@ try {
         // Compute next anchor — O(anchored), single pass
         const { anchorId: aaAnchorId } = nextAnchorFromLedger(aaLedgerRows, assignType);
 
+        // E4: pre-mint collision guard — refuse if the candidate id is already
+        // cited (as a whole word) somewhere in tracked source with a different
+        // meaning, before any ledger write. Never auto-skip to the next free
+        // number — the collision is a human call (rename the citation, or
+        // rerun with --allow-collision to mint over it deliberately).
+        if (!aaAllowCollision) {
+          const aaCollisionHits = scanForAnchorCollision(aaProjectRoot, aaAnchorId);
+          if (aaCollisionHits.length > 0) {
+            throw new Error(
+              `assign-anchor: '${aaAnchorId}' is already cited in source with a different ` +
+              `meaning; resolve the collision before minting (or pass --allow-collision):\n` +
+              formatCollisionHits(aaCollisionHits)
+            );
+          }
+        }
+
         // Read observation from log
         let aaLogEntries = parseLedger(aaLogPath);
         const aaObsIdx = aaLogEntries.findIndex(e => e.id === assignObsId);
@@ -648,6 +834,41 @@ try {
       break;
     }
 
+    // -------------------------------------------------------------------------
+    // next-anchor <type>
+    // E4: Read-only preview of what assign-anchor would mint next — no lock
+    // acquired, no file written, no usage entry registered. Prints the
+    // candidate id and, when a pre-mint collision guard would fire, its
+    // file:line hits — so a caller can check before committing to assign-anchor.
+    // -------------------------------------------------------------------------
+    case 'next-anchor': {
+      const naType = args[0];
+
+      if (!naType) {
+        process.stderr.write('next-anchor: usage: next-anchor <type>\n');
+        process.exit(1);
+      }
+      if (naType !== 'decision' && naType !== 'pitfall') {
+        process.stderr.write(`next-anchor: type must be 'decision' or 'pitfall', got '${naType}'\n`);
+        process.exit(1);
+      }
+
+      const naProjectRoot = process.cwd();
+      const naLedgerRows = parseLedger(getDecisionsLedgerPath(naProjectRoot));
+      const { anchorId: naAnchorId } = nextAnchorFromLedger(naLedgerRows, naType);
+      const naHits = scanForAnchorCollision(naProjectRoot, naAnchorId);
+
+      process.stdout.write(naAnchorId + '\n');
+      if (naHits.length > 0) {
+        process.stderr.write(
+          `next-anchor: '${naAnchorId}' is already cited in source — collision hits:\n` +
+          formatCollisionHits(naHits) + '\n'
+        );
+        process.exit(1);
+      }
+      break;
+    }
+
     // -------------------------------------------------------------------------
     // retire-anchor <anchor_id> <status>
     // AC-A3, AC-F5, AC-F7: Flip decisions_status on the ledger row. Idempotent.
@@ -906,5 +1127,7 @@ if (typeof module !== 'undefined' && module.exports) {
     initDecisionsContent,
     nextAnchorFromLedger,
     rotateObservations,
+    scanForAnchorCollision,
+    isCollisionScanExcluded,
   };
 }

package/src/assets/scripts/hooks/lib/project-paths.cjs

@@ -43,7 +43,7 @@ function getDocsDir(projectRoot) {
 // Feature config (neutral .devflow root — not inside learning/)
 // ---------------------------------------------------------------------------
 
-/** .devflow/config.json — feature toggles {memory, learning, knowledge} */
+/** .devflow/config.json — per-repo facts {reviewPublication, tracker override} */
 function getFeatureConfigPath(projectRoot) {
   return path.join(projectRoot, '.devflow', 'config.json');
 }
@@ -174,23 +174,6 @@ function getHandoffPath(projectRoot, branchSlug) {
   return path.join(projectRoot, '.devflow', 'docs', `handoff-${branchSlug}.md`);
 }
 
-// ---------------------------------------------------------------------------
-// Gitignore entries
-// ---------------------------------------------------------------------------
-
-/**
- * The canonical list of generic gitignore entries Devflow adds to a project's
- * root .gitignore for LOCAL-scope installs. Currently just `.claude/`.
- *
- * `.devflow/` is intentionally NOT here: it is managed by ensureDevflowGitignore
- * (TS) / ensure-root-gitignore (hook), which write the feature-knowledge carve-out
- * for ALL scopes. Adding a bare `.devflow/` here would append a wholesale-ignore
- * line after the carve-out and re-bury it (last match wins in .gitignore).
- */
-function getGitignoreEntries() {
-  return ['.claude/'];
-}
-
 module.exports = {
   // Core directories
   getMemoryDir,
@@ -225,6 +208,4 @@ module.exports = {
   getDesignDir,
   getResearchDir,
   getHandoffPath,
-  // Gitignore entries
-  getGitignoreEntries,
 };

package/src/assets/scripts/hooks/log-paths

@@ -2,11 +2,88 @@
 # Shared log path computation for Devflow hooks.
 # Source this file to get devflow_log_dir function.
 
+# D-LOG-DIR-CAP (hook side). Every hook logs under ~/.devflow/logs/<cwd-slug>/,
+# one folder per working directory, and `devflow init` prunes them to the
+# MAX_HOOK_LOG_DIRS most recent (src/core/hook-log-dirs.ts). A machine that never
+# re-inits would still grow without bound, so devflow_log_dir also prunes — but
+# ONLY when it creates a new folder, which is rare: the common path (the folder
+# already exists) pays nothing. The pass is bounded (one `ls`, at most
+# _DF_LOG_DIRS_SCANNED_MAX entries read, _DF_LOG_DIRS_PRUNED_PER_CALL removed in
+# one `rm`), bash 3.2 compatible, and never spawns node. Only directories are
+# counted or removed: root files (proxy.log) and symbolic links are left alone.
+#
+# Recency: folders are ranked by their own mtime (`ls -t`), which an append to a
+# log inside does not move, so a candidate is spared when any of its first
+# _DF_LOG_FILES_READ_PER_DIR entries is newer than the oldest folder the cap
+# keeps (`-nt`, a shell builtin). A spared folder can leave the count briefly
+# above the cap; init's exact prune settles it.
+#
+# _DF_MAX_HOOK_LOG_DIRS must equal MAX_HOOK_LOG_DIRS (tests/hook-log-paths.test.ts).
+_DF_MAX_HOOK_LOG_DIRS=200
+_DF_LOG_DIRS_PRUNED_PER_CALL=50
+_DF_LOG_DIRS_SCANNED_MAX=100000
+_DF_LOG_FILES_READ_PER_DIR=64
+
 # Cache the computed log dir path to avoid spawning 4 subprocesses (sed+tr+mkdir+chmod)
 # on every call within the same hook process.
 _LOG_DIR_CACHED=""
 _LOG_DIR_CACHED_CWD=""
 
+# _df_log_dir_is_recent <dir> <cutoff>
+# True when one of the first _DF_LOG_FILES_READ_PER_DIR entries in <dir> is newer
+# than <cutoff>. Globbing must be on.
+_df_log_dir_is_recent() {
+  local _dir="$1" _cutoff="$2" _f _read=0
+  for _f in "$_dir"/.[!.]* "$_dir"/..?* "$_dir"/*; do
+    [ "$_read" -lt "$_DF_LOG_FILES_READ_PER_DIR" ] || break
+    [ -e "$_f" ] || [ -L "$_f" ] || continue
+    _read=$((_read + 1))
+    if [ "$_f" -nt "$_cutoff" ]; then return 0; fi
+  done
+  return 1
+}
+
+# _df_prune_log_dirs <logs-root> <just-created-dir>
+# Remove the oldest folders beyond _DF_MAX_HOOK_LOG_DIRS, at most
+# _DF_LOG_DIRS_PRUNED_PER_CALL of them. Never fails the caller.
+_df_prune_log_dirs() {
+  local _logs="$1" _new="$2"
+  local _listing _name _n=0 _i _removed=0 _cutoff _d _glob_off=0
+  local -a _dirs _batch
+  _listing=$(ls -1At "$_logs" 2>/dev/null) || return 0
+
+  case $- in *f*) _glob_off=1 ;; esac
+  local IFS='
+'
+  set -f
+  for _name in $_listing; do
+    [ "$_n" -lt "$_DF_LOG_DIRS_SCANNED_MAX" ] || break
+    case "$_name" in */*) continue ;; esac
+    [ -L "$_logs/$_name" ] && continue
+    [ -d "$_logs/$_name" ] || continue
+    _dirs[_n]="$_logs/$_name"
+    _n=$((_n + 1))
+  done
+  set +f
+
+  if [ "$_n" -gt "$_DF_MAX_HOOK_LOG_DIRS" ]; then
+    _cutoff="${_dirs[_DF_MAX_HOOK_LOG_DIRS - 1]}"
+    _i=$((_n - 1))
+    while [ "$_i" -ge "$_DF_MAX_HOOK_LOG_DIRS" ] && [ "$_removed" -lt "$_DF_LOG_DIRS_PRUNED_PER_CALL" ]; do
+      _d="${_dirs[_i]}"
+      if [ "$_d" != "$_new" ] && ! _df_log_dir_is_recent "$_d" "$_cutoff"; then
+        _batch[_removed]="$_d"
+        _removed=$((_removed + 1))
+      fi
+      _i=$((_i - 1))
+    done
+    if [ "$_removed" -gt 0 ]; then rm -rf -- "${_batch[@]}" 2>/dev/null || true; fi
+  fi
+
+  if [ "$_glob_off" = 1 ]; then set -f; fi
+  return 0
+}
+
 devflow_log_dir() {
   local cwd="$1"
   if [ "$cwd" = "$_LOG_DIR_CACHED_CWD" ] && [ -n "$_LOG_DIR_CACHED" ]; then
@@ -16,8 +93,11 @@ devflow_log_dir() {
   local slug
   slug=$(echo "$cwd" | sed 's|^/||' | tr '/' '-')
   local dir="$HOME/.devflow/logs/$slug"
+  local created=0
+  [ -d "$dir" ] || created=1
   mkdir -p "$dir"
   chmod 700 "$dir"
+  if [ "$created" = 1 ]; then _df_prune_log_dirs "$HOME/.devflow/logs" "$dir" || true; fi
   _LOG_DIR_CACHED="$dir"
   _LOG_DIR_CACHED_CWD="$cwd"
   echo "$dir"

package/src/assets/scripts/hooks/memory-worker

@@ -2,9 +2,11 @@
 
 # Memory pipeline: memory-worker (Stop Hook)
 # Owns the 120s-throttle + nohup-spawn logic for background-memory-update.
-# Registered AFTER capture-turn in the Stop hook array so append-before-spawn
-# ordering is preserved by array position. This hook does NOT append to any
-# queue itself -- capture-turn already did that earlier in the same Stop event.
+# Claude Code runs a Stop event's hooks in parallel, so this hook may fire
+# before capture-turn has appended this turn's assistant row. That is safe:
+# background-memory-update leaves a user-only queue in place and skips the LLM
+# run (D-QUEUE-NO-ORPHAN-DELETE), and the next run takes the whole turn. This
+# hook does NOT append to any queue itself.
 
 # Safe no-op fallback: must exist before set -e and before hook-bootstrap is sourced.
 dbg() { :; }
@@ -32,15 +34,19 @@ 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"
 
-DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
-MEMORY_DIR="$DEVFLOW_DIR/memory"
+# The machine-wide manifest (the memory switch, D-FEATURES-NARROW-ONLY in
+# queue-append) lives at the machine root,
+# $HOME/.devflow (D-ONE-HOME).
+DEVFLOW_MANIFEST="$HOME/.devflow/manifest.json"
+PROJECT_DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
+MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
 
-# Read feature config -- memory:false gates this hook entirely (ADR-001).
-FEATURE_CONFIG="$DEVFLOW_DIR/config.json"
-MEMORY_ENABLED="true"
-if [ -f "$FEATURE_CONFIG" ]; then
-  MEMORY_ENABLED=$(json_field_file "$FEATURE_CONFIG" "memory" "true")
-fi
+# Memory gate: the machine switch, narrowed by this checkout's project.json /
+# config.json `features.memory`, gates this hook entirely -- read by the helper
+# every memory/learning gate shares (D-FEATURES-NARROW-ONLY, see queue-append).
+source "$SCRIPT_DIR/queue-append" || { echo "memory-worker: failed to source queue-append" >&2; exit 1; }
+queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
+MEMORY_ENABLED="$_QG_MEMORY"
 
 dbg "MEMORY_ENABLED=$MEMORY_ENABLED"
 
@@ -93,8 +99,11 @@ dbg "Throttle passed: TRIGGER_AGE=${TRIGGER_AGE}s >= 120s — spawning worker"
 # Touch trigger BEFORE spawning (prevents concurrent Stop hooks from double-spawning)
 touch "$TRIGGER_FILE" 2>/dev/null || true
 
-# Spawn detached worker — nohup + disown so it survives the Stop hook process exit
-nohup "$UPDATER" "$CWD" </dev/null >>/dev/null 2>&1 & disown
+# Spawn detached worker — nohup + disown so it survives the Stop hook process exit.
+# The manifest path is handed over explicitly: the worker re-checks the memory
+# switch after spawn against the same manifest this hook gated on (and the same
+# checkout's repository files, from the project root it resolves itself).
+nohup "$UPDATER" "$CWD" "$DEVFLOW_MANIFEST" </dev/null >>/dev/null 2>&1 & disown
 
 log "Spawned background-memory-update worker (CWD=$CWD)"
 dbg "=== HOOK COMPLETE ==="

package/src/assets/scripts/hooks/pre-compact-memory

@@ -43,20 +43,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"
 
-DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
-MEMORY_DIR="$DEVFLOW_DIR/memory"
+# The machine-wide manifest (the memory switch, D-FEATURES-NARROW-ONLY in
+# queue-append) lives at the machine root,
+# $HOME/.devflow (D-ONE-HOME).
+DEVFLOW_MANIFEST="$HOME/.devflow/manifest.json"
+PROJECT_DEVFLOW_DIR="$PROJECT_ROOT/.devflow"
+MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
 
 # Normal logging
 source "$SCRIPT_DIR/hook-log-init" "pre-compact-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 switch, narrowed by this checkout's project.json /
+# config.json `features.memory`, read by the helper every memory/learning gate
+# shares (D-FEATURES-NARROW-ONLY, see queue-append).
+source "$SCRIPT_DIR/queue-append" || { echo "pre-compact-memory: failed to source queue-append" >&2; exit 1; }
+queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
+if [ "$_QG_MEMORY" != "true" ]; then
+  dbg "EXIT: memory disabled"
+  exit 0
 fi
 
 # Auto-create .devflow/ and ensure .gitignore entries (idempotent after first run)
@@ -75,9 +79,26 @@ TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
   GIT_HEAD_SHA=$(git rev-parse HEAD 2>/dev/null || echo "")
   GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
-  GIT_STATUS=$(git status --porcelain 2>/dev/null | head -30 || echo "")
+  # D-DETACHED-HEAD: a checkout of a commit rather than a branch (`git checkout
+  # <sha>`, bisect, a rebase stop, `git worktree add --detach`, a CI checkout)
+  # prints no branch name. It is labelled `(detached)`, echoing git's own
+  # `(HEAD detached at …)` display and holding no space, so the stamp's
+  # one-token `branch:` field still parses; the backup names it and the bootstrap
+  # below still stamps memory, keyed on the commit it describes. (A branch really
+  # named `(detached)` is legal git and would read the same — accepted: nothing
+  # decides on the label, it only names.) An unborn branch has no HEAD commit,
+  # keeps the empty label, and is still skipped.
+  if [ -z "$GIT_BRANCH" ] && is_hex_sha "$GIT_HEAD_SHA" 40 40; then
+    GIT_BRANCH="(detached)"
+  fi
+  # D-NO-FSMONITOR: `status` and `diff` read the index, and reading the index
+  # runs the command the repository's config names in `core.fsmonitor` — code
+  # chosen by the repository this hook runs inside. Each index read turns it
+  # off for itself (`-c core.fsmonitor=false`); rev-parse, branch and log never
+  # read the index.
+  GIT_STATUS=$(git -c core.fsmonitor=false status --porcelain 2>/dev/null | head -30 || echo "")
   GIT_LOG=$(git log --oneline -10 2>/dev/null || echo "")
-  GIT_DIFF_STAT=$(git diff --stat HEAD 2>/dev/null || echo "")
+  GIT_DIFF_STAT=$(git -c core.fsmonitor=false diff --stat HEAD 2>/dev/null || echo "")
   dbg "GIT_BRANCH=$GIT_BRANCH HEAD=$GIT_HEAD_SHA"
 fi
 
@@ -101,8 +122,12 @@ json_backup_construct \
 log "Wrote backup: $BACKUP_FILE"
 dbg "Wrote backup: $BACKUP_FILE"
 
-# Bootstrap minimal WORKING-MEMORY.md if absent; skip on detached HEAD, unborn branch,
-# or malformed SHA. is_hex_sha 40 40: exactly 40 lowercase hex chars required.
+# Bootstrap minimal WORKING-MEMORY.md if absent; skip on an unborn branch or a
+# malformed SHA. is_hex_sha 40 40: exactly 40 lowercase hex chars required. A detached
+# HEAD bootstraps with a `branch: (detached)` stamp (D-DETACHED-HEAD, above): the
+# stamp's memory-head SHA is what drift detection keys on, and the Context line names
+# the commit by its short SHA, so the first compaction there no longer leaves the
+# session with nothing to restore.
 # avoids REL-5: O_EXCL-style atomic create via noclobber so the existence test and the
 # create are one operation — if the worker's CAS mv lands in the window, noclobber fails
 # (file already exists) and we skip the bootstrap rather than truncating fresh memory.
@@ -122,7 +147,11 @@ if [ -n "$GIT_BRANCH" ] && is_hex_sha "$GIT_HEAD_SHA" 40 40; then
       echo "- (none recorded)"
       echo ""
       echo "## Context"
-      echo "- Branch: $GIT_BRANCH"
+      if [ "$GIT_BRANCH" = "(detached)" ]; then
+        echo "- Branch: (detached) @ ${GIT_HEAD_SHA:0:7}"
+      else
+        echo "- Branch: $GIT_BRANCH"
+      fi
       echo "$GIT_LOG" | head -3 | while IFS= read -r line; do
         [ -n "$line" ] && echo "- $line"
       done

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