devflow-kit 2.4.0 → 2.5.0

package/src/assets/scripts/hooks/ensure-root-gitignore

@@ -3,14 +3,16 @@
 # rules that govern .devflow/.
 #
 # .devflow/ holds per-developer runtime state (memory, learning, docs, locks) —
-# local by default. TWO exceptions are shared via git:
+# local by default. THREE exceptions are shared via git:
 # 1. Feature knowledge bases under .devflow/features/: index.md and every
 #    {slug}/KNOWLEDGE.md (tracked, committed by the Knowledge agent at workflow end).
 # 2. .devflow/conventions.md — naming-convention authority written by the Git
 #    learn-conventions operation; shared so the team uses one naming source.
+# 3. .devflow/policy.json — the team-owned evidence policy, read from the default
+#    branch by resolve-evidence-policy.cjs. Devflow never writes it.
 #
-# Everything else under .devflow/ stays local. A user opts back out by re-adding
-# `.devflow/features/` or `.devflow/conventions.md` to their own .gitignore.
+# Everything else under .devflow/ stays local. A user opts back out of the first two
+# by re-adding `.devflow/features/` or `.devflow/conventions.md` to their own .gitignore.
 #
 # Re-including files under an ignored tree requires un-ignoring each level with a
 # `dir/*` + `!dir/keep` pair: a bare `.devflow/` excludes the directory outright,
@@ -23,9 +25,23 @@
 # Both reach this one writer so the rule is applied identically everywhere; this
 # decouples git-tracking of .devflow/ from any single feature toggle (avoids PF-014).
 #
-# Idempotent and O(1) after the first run via the .root-gitignore-configured-v3
-# marker. The marker is versioned: bumping it (v2 → v3) forces existing installs
-# to re-run once and upgrade their block (adds !.devflow/conventions.md line).
+# Idempotent and O(1) after the first run via the .root-gitignore-configured-v5
+# marker under .devflow/ (project-local). The marker is a claim, not proof, so the
+# fast path also requires the block's own sentinel, the policy line AND a
+# .claudeignore entry to be present; a .gitignore that lost any of them (a merge
+# resolution, a hand edit) is healed on the next run. A v4-marked project misses the
+# fast path, gains the policy line and is re-stamped v5.
+#
+# D-GITIGNORE-V5: the block is detected ONLY by its devflow-unique sentinel
+# `!.devflow/conventions.md` — NEVER by `.claudeignore` or `!.devflow/policy.json`,
+# which users legitimately author themselves. Those two are completion lines: each is
+# topped up when missing, in block order (policy, then .claudeignore). Keying presence
+# off a user-authored line inverts both halves of the contract: projects that already
+# carry that line never receive the carve-out (so .devflow/ runtime files leak into
+# git), and re-appending `.claudeignore` after a user's `!.claudeignore` reverses
+# their intent under gitignore's last-match-wins. Hence: a `.claudeignore` OR
+# `!.claudeignore` entry means "the user owns that line" — emit the block without it.
+# All matching is whole-line and whitespace-tolerant; never substring.
 #
 # Usage: source ensure-root-gitignore "$PROJECT_ROOT"
 # Sourced helper: uses `return` (never exit), _ERG_-prefixed locals (never clobbers
@@ -34,31 +50,59 @@
 [ -z "$1" ] && return 1
 
 _ERG_DEVFLOW_DIR="$1/.devflow"
-_ERG_MARKER="$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v3"
+_ERG_MARKER="$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v5"
 _ERG_GITIGNORE="$1/.gitignore"
 
-# Fast-path with verification: marker normally means the block is installed, but
-# the marker is a claim, not proof — a merge-conflict resolution may have dropped
-# the block. Gate the fast-path return on the v3 sentinel actually being present
-# in .gitignore. Idempotent: sentinel present → return 0; sentinel absent → heal.
-if [ -f "$_ERG_MARKER" ]; then
-  grep -qF '!.devflow/conventions.md' "$_ERG_GITIGNORE" 2>/dev/null && return 0
-  # Sentinel absent — marker is stale; fall through to re-apply the block.
+# Whole-line, whitespace-tolerant matchers. `*` and `.` are escaped so the ERE
+# matches the literal gitignore patterns.
+_ERG_RE_OPTOUT='^[[:space:]]*/\.devflow/[[:space:]]*$'
+_ERG_RE_LEGACY='^[[:space:]]*\.devflow/[[:space:]]*$'
+_ERG_RE_SENTINEL='^[[:space:]]*!\.devflow/conventions\.md[[:space:]]*$'
+_ERG_RE_SENTINEL_V2='^[[:space:]]*!\.devflow/features/\*/KNOWLEDGE\.md[[:space:]]*$'
+_ERG_RE_POLICY='^[[:space:]]*!\.devflow/policy\.json[[:space:]]*$'
+_ERG_RE_CLAUDEIGNORE='^[[:space:]]*!?\.claudeignore[[:space:]]*$'
+
+# Drop every legacy marker beside v5 — builtin `[ -e ]` tests, so rm forks only for a
+# marker that exists. Called from the fast path and from the on-success stamp below,
+# so an older devflow's marker is dropped whichever path a run takes.
+# Always returns 0 (never fails the caller under `set -e`): the last iteration's
+# `[ -e ]` test is false whenever the unversioned marker is absent (the common case),
+# and a function call's own exit status is NOT exempt from errexit the way an inlined
+# for-loop's is — unlike this same loop when it sat directly inside the caller's `{ }`.
+_erg_drop_legacy_markers() {
+  for _ERG_OLD in -v4 -v3 -v2 ''; do
+    [ -e "$_ERG_DEVFLOW_DIR/.root-gitignore-configured$_ERG_OLD" ] \
+      && rm -f "$_ERG_DEVFLOW_DIR/.root-gitignore-configured$_ERG_OLD" 2>/dev/null
+  done
+  return 0
+}
+
+# Fast path: converged only when the marker is stamped AND the block sentinel is
+# present AND the policy line is present AND a .claudeignore entry exists. Every
+# other state falls through and recomputes.
+if [ -f "$_ERG_MARKER" ] \
+  && grep -qE "$_ERG_RE_SENTINEL" "$_ERG_GITIGNORE" 2>/dev/null \
+  && grep -qE "$_ERG_RE_POLICY" "$_ERG_GITIGNORE" 2>/dev/null \
+  && grep -qE "$_ERG_RE_CLAUDEIGNORE" "$_ERG_GITIGNORE" 2>/dev/null; then
+  _erg_drop_legacy_markers
+  return 0
 fi
 
 # The marker lives under .devflow/, so the directory must exist before we touch it.
 # (ensure-devflow-init creates it earlier; session-start-context may reach here first.)
 mkdir -p "$_ERG_DEVFLOW_DIR" 2>/dev/null || return 1
 
-# The carve-out block, built once into _ERG_BLOCK (emitted on create and append).
-# Keep byte-identical to ensureDevflowGitignore in src/targets/claude-code/post-install.ts.
-# D-GITIGNORE-V3: v3 adds !.devflow/conventions.md (naming authority, git-tracked).
-printf -v _ERG_BLOCK '%s\n' \
+# The carve-out block, built once. _ERG_BLOCK_NO_CI is the block a project that owns
+# its own .claudeignore entry receives; _ERG_BLOCK is that plus the final line.
+# Both trail a newline. Keep byte-identical to DEVFLOW_GITIGNORE_BLOCK and
+# DEVFLOW_GITIGNORE_BLOCK_WITHOUT_CLAUDEIGNORE in
+# src/targets/claude-code/post-install.ts.
+printf -v _ERG_BLOCK_NO_CI '%s\n' \
   '# Devflow runtime data — local by default (memory, learning, docs, locks).' \
-  '# Two exceptions are shared via git: feature knowledge bases under .devflow/features/' \
-  '# (index.md and every {slug}/KNOWLEDGE.md) and .devflow/conventions.md (naming' \
-  '# authority). To stop sharing, re-add `.devflow/features/` or `.devflow/conventions.md`' \
-  '# to your own .gitignore.' \
+  '# Shared via git: feature knowledge bases under .devflow/features/ (index.md and' \
+  '# every {slug}/KNOWLEDGE.md), .devflow/conventions.md (naming authority) and' \
+  '# .devflow/policy.json (evidence policy). To stop sharing the first two, re-add' \
+  '# `.devflow/features/` or `.devflow/conventions.md` to your own .gitignore.' \
   '.devflow/*' \
   '!.devflow/features/' \
   '.devflow/features/*' \
@@ -66,51 +110,108 @@ printf -v _ERG_BLOCK '%s\n' \
   '!.devflow/features/*/' \
   '.devflow/features/*/*' \
   '!.devflow/features/*/KNOWLEDGE.md' \
-  '!.devflow/conventions.md'
+  '!.devflow/conventions.md' \
+  '!.devflow/policy.json'
+printf -v _ERG_LINE_SENTINEL '%s\n' '!.devflow/conventions.md'
+printf -v _ERG_LINE_POLICY '%s\n' '!.devflow/policy.json'
+printf -v _ERG_LINE_CLAUDEIGNORE '%s\n' '.claudeignore'
+_ERG_BLOCK="$_ERG_BLOCK_NO_CI$_ERG_LINE_CLAUDEIGNORE"
 
-_ERG_OK=0
-if [ ! -f "$_ERG_GITIGNORE" ]; then
-  # No .gitignore yet — create it with the block.
-  printf '%s' "$_ERG_BLOCK" > "$_ERG_GITIGNORE" && _ERG_OK=1
-elif grep -qF '!.devflow/conventions.md' "$_ERG_GITIGNORE"; then
-  # v3 carve-out already present — nothing to do.
-  _ERG_OK=1
-elif grep -qE '^/\.devflow/[[:space:]]*$' "$_ERG_GITIGNORE"; then
+# Does the file already carry the policy line, or a .claudeignore entry of the user's
+# own (either form)? Computed BEFORE the legacy filter below, which rewrites the file.
+_ERG_HAS_POLICY=0
+grep -qE "$_ERG_RE_POLICY" "$_ERG_GITIGNORE" 2>/dev/null && _ERG_HAS_POLICY=1
+_ERG_HAS_CI=0
+grep -qE "$_ERG_RE_CLAUDEIGNORE" "$_ERG_GITIGNORE" 2>/dev/null && _ERG_HAS_CI=1
+
+# The completion lines this file lacks, in block order (policy, then .claudeignore).
+# Mirrors missingCompletionLines in the TS twin.
+_ERG_COMPLETION=''
+if [ "$_ERG_HAS_POLICY" = 0 ]; then
+  _ERG_COMPLETION="$_ERG_LINE_POLICY"
+fi
+if [ "$_ERG_HAS_CI" = 0 ]; then
+  _ERG_COMPLETION="$_ERG_COMPLETION$_ERG_LINE_CLAUDEIGNORE"
+fi
+
+# Classify: noop (nothing to do) | continue (extend an existing block) |
+# block (install a fresh block) | fail (a rewrite failed; leave the file alone).
+_ERG_MODE=noop
+_ERG_APPEND=''
+if grep -qE "$_ERG_RE_OPTOUT" "$_ERG_GITIGNORE" 2>/dev/null; then
   # User-authored `/.devflow/` (leading slash) — respect it; don't force the carve-out.
-  # Checked BEFORE the v2 sentinel so a file containing both keeps the user-authored
-  # entry (matches ensureDevflowGitignore TS order: v3→/.devflow/→v2→wholesale→append).
-  _ERG_OK=1
-elif grep -qF '!.devflow/features/*/KNOWLEDGE.md' "$_ERG_GITIGNORE"; then
-  # v2→v3 upgrade: v2 sentinel present but conventions.md line absent — append just the
-  # missing line. A .gitignore whose last byte is not a newline would otherwise fuse the
-  # appended line onto the last existing one, corrupting BOTH patterns; the sibling append
-  # branches below get this for free by emitting a leading '\n'. `tail -c 1` yields the
-  # empty string when the file already ends in a newline (command substitution strips it).
-  if [ -n "$(tail -c 1 "$_ERG_GITIGNORE" 2>/dev/null)" ]; then
-    printf '\n' >> "$_ERG_GITIGNORE"
+  # Checked FIRST so a file containing both it and a sentinel keeps the user's entry.
+  _ERG_MODE=noop
+elif grep -qE "$_ERG_RE_SENTINEL" "$_ERG_GITIGNORE" 2>/dev/null; then
+  # Block installed (v3 and later) — top up only the completion lines it lacks.
+  if [ -n "$_ERG_COMPLETION" ]; then
+    _ERG_MODE=continue
+    _ERG_APPEND="$_ERG_COMPLETION"
   fi
-  printf '!.devflow/conventions.md\n' >> "$_ERG_GITIGNORE" && _ERG_OK=1
-elif grep -qE '^\.devflow/[[:space:]]*$' "$_ERG_GITIGNORE"; then
-  # Upgrade our legacy wholesale entry: strip the bare `.devflow/` line and our old
-  # comment, then append the carve-out block. Portable (grep filter + mv; no sed -i,
-  # which differs on BSD/GNU). An empty filter result is fine — the block is appended
-  # regardless; a leading blank is added only when prior content survived.
-  _ERG_TMP="$_ERG_GITIGNORE.devflow-tmp.$$"
-  grep -vE '^\.devflow/[[:space:]]*$' "$_ERG_GITIGNORE" 2>/dev/null \
-    | grep -vF '# Devflow runtime data (local by default; remove to share via git)' \
-    > "$_ERG_TMP" 2>/dev/null
-  { [ -s "$_ERG_TMP" ] && printf '\n'; printf '%s' "$_ERG_BLOCK"; } >> "$_ERG_TMP" \
-    && mv "$_ERG_TMP" "$_ERG_GITIGNORE" && _ERG_OK=1
-  [ "$_ERG_OK" = 1 ] || rm -f "$_ERG_TMP" 2>/dev/null
+elif grep -qE "$_ERG_RE_SENTINEL_V2" "$_ERG_GITIGNORE" 2>/dev/null; then
+  # v2 block installed — append the lines it lacks, in block order.
+  _ERG_MODE=continue
+  _ERG_APPEND="$_ERG_LINE_SENTINEL$_ERG_COMPLETION"
 else
-  # .gitignore exists but has no Devflow entry — append the block.
-  { printf '\n'; printf '%s' "$_ERG_BLOCK"; } >> "$_ERG_GITIGNORE" && _ERG_OK=1
+  # No devflow block — install one, omitting the .claudeignore line the user owns.
+  _ERG_MODE=block
+  if [ "$_ERG_HAS_CI" = 1 ]; then
+    _ERG_APPEND="$_ERG_BLOCK_NO_CI"
+  else
+    _ERG_APPEND="$_ERG_BLOCK"
+  fi
+  if grep -qE "$_ERG_RE_LEGACY" "$_ERG_GITIGNORE" 2>/dev/null; then
+    # Upgrade our legacy wholesale entry: strip the bare `.devflow/` line and our old
+    # comment first, then fall through to the shared append below. Portable (grep
+    # filter + mv; no sed -i, which differs on BSD/GNU).
+    # The pipeline's own status is deliberately ignored: grep -v exits 1 when it
+    # emits no lines, which is the correct outcome for a .gitignore whose only
+    # content was the legacy entry. The redirect creates _ERG_TMP either way.
+    _ERG_TMP="$_ERG_GITIGNORE.devflow-tmp.$$"
+    grep -vE "$_ERG_RE_LEGACY" "$_ERG_GITIGNORE" 2>/dev/null \
+      | grep -vF '# Devflow runtime data (local by default; remove to share via git)' \
+      > "$_ERG_TMP" 2>/dev/null
+    if [ -f "$_ERG_TMP" ] && mv "$_ERG_TMP" "$_ERG_GITIGNORE"; then
+      :
+    else
+      rm -f "$_ERG_TMP" 2>/dev/null
+      _ERG_MODE=fail
+    fi
+  fi
 fi
 
-# On success, stamp the current-format v3 marker and drop legacy markers.
+# The two append shapes, mirrored byte-for-byte by the TS twin's appendLines and
+# appendBlock. `tail -c 1` yields the empty string when the file already ends in a
+# newline (command substitution strips it), so a file whose last byte is not a
+# newline gets one before the appended text fuses onto its last line. Existing
+# trailing newlines are preserved verbatim — no trimming, no blank-line dedupe.
+_ERG_OK=0
+case "$_ERG_MODE" in
+  noop)
+    _ERG_OK=1
+    ;;
+  continue)
+    if [ -n "$(tail -c 1 "$_ERG_GITIGNORE" 2>/dev/null)" ]; then
+      printf '\n' >> "$_ERG_GITIGNORE"
+    fi
+    printf '%s' "$_ERG_APPEND" >> "$_ERG_GITIGNORE" && _ERG_OK=1
+    ;;
+  block)
+    if [ ! -s "$_ERG_GITIGNORE" ]; then
+      # Absent or empty — the block is the whole file, with no leading blank line.
+      printf '%s' "$_ERG_APPEND" > "$_ERG_GITIGNORE" && _ERG_OK=1
+    else
+      if [ -n "$(tail -c 1 "$_ERG_GITIGNORE" 2>/dev/null)" ]; then
+        printf '\n' >> "$_ERG_GITIGNORE"
+      fi
+      { printf '\n'; printf '%s' "$_ERG_APPEND"; } >> "$_ERG_GITIGNORE" && _ERG_OK=1
+    fi
+    ;;
+esac
+
+# On success, stamp the current-format v5 marker and drop legacy markers.
 [ "$_ERG_OK" = 1 ] && {
   touch "$_ERG_MARKER"
-  rm -f "$_ERG_DEVFLOW_DIR/.root-gitignore-configured-v2" 2>/dev/null
-  rm -f "$_ERG_DEVFLOW_DIR/.root-gitignore-configured" 2>/dev/null
+  _erg_drop_legacy_markers
 }
 return 0

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

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

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,149 @@ 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`.
+ *
+ * @param {string} projectRoot
+ * @returns {string[]} project-relative paths
+ */
+function listGitTrackedFiles(projectRoot) {
+  const out = execFileSync('git', ['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 +682,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 +730,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 +829,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 +1122,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');
 }

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

@@ -32,15 +32,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"
 
+# 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"
 
-# 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-wide switch gates this hook entirely, 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 "memory-worker: failed to source queue-append" >&2; exit 1; }
+queue_read_gates "$DEVFLOW_MANIFEST"
+MEMORY_ENABLED="$_QG_MEMORY"
 
 dbg "MEMORY_ENABLED=$MEMORY_ENABLED"
 
@@ -93,8 +97,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, and by now DEVFLOW_DIR names the project .devflow (and is
+# what the worker would inherit, were it exported), not the devflow-global root.
+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"
 
+# 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" "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-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 "pre-compact-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
 
 # Auto-create .devflow/ and ensure .gitignore entries (idempotent after first run)