devflow-kit 3.0.1 → 3.2.0

package/src/assets/mds/tracker/_linear.mds

@@ -56,7 +56,7 @@ conflict the contract wins.
 Headings below each section's own anchor are `###` by grammar, not by taste: a
 column-0 `## ` line outside a fence terminates the section for every guard that
 reads it through `extractOpSectionFromCorpus`, and everything under it becomes
-invisible while the bytes stay on disk (PF-063). The one `## ` heading in this
+invisible while the bytes stay on disk. The one `## ` heading in this
 file is the module-level section below, which sits above every section marker and
 is therefore emitted nowhere.
 
@@ -218,13 +218,13 @@ Over `{{comment_cap()}}` characters the rolling item is closed and a successor i
 
 Load when the resolved tracker provider is `linear` and the operation is `create-release`.
 
-**Mechanics held here:** the closed-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
 
 ### Process
 
 Inside step 5 (compose release notes):
 
-   - If `SHIPPED_ISSUES` is provided: append a `## Closed Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
+   - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
    - {{common.ref_preflight_list("linear", "**either** anchored form — the team-key form `^[A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$` or the internal-id form `^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$`", "**ASCII-upper-normalise every entry first.** ", ", never joined into one alternation", " and the section is omitted rather than rendered empty.")}}
    - `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the reference itself on its own line, and record the discard under `### Substitutions`.
 

package/src/assets/mds/tracker/_mcp.mds

@@ -32,16 +32,17 @@ extraction that turns a universal obligation into per-consumer opt-in is the
 defect, not the saving.
 
 The preamble names it on the SAME physical line that composes the per-operation
-mechanics path, which is what keeps PF-023's single convergence point at exactly
-one line. That is sound rather than a loophole: what PF-023 counts is where a path
-is BUILT, and this one is a fixed literal built from nothing — the validated
+mechanics path, which is what keeps the single convergence point (validation lives
+at the one sink every path passes through, not at each entry) at exactly one line.
+That is sound rather than a loophole: what that rule counts is where a path is
+BUILT, and this one is a fixed literal built from nothing — the validated
 provider token selects the mechanics directory and never reaches this name. A
 per-operation file naming it again is forbidden, and asserted as forbidden.
 
 Headings below the first are `###` by grammar, not by taste: a column-0 `## `
 line outside a fence terminates this file's section for every guard that reads it
 through `extractOpSectionFromCorpus`, and everything under it becomes invisible
-while the bytes stay on disk (PF-063).
+while the bytes stay on disk.
 
 TWO ROLES, AND THE SECOND ONE IS EMITTED NOWHERE. `@define tool_call_contract()`
 below is the artifact: it becomes `tracker/_mcp.md` and is read once per spawn.
@@ -81,7 +82,7 @@ to `_common.mds` cost 1.2 s in total. A rule that belongs here by subject and
 would be the tenth define belongs in `_common.mds` with its audience stated at
 the define, and this paragraph is the reason.
 
-NOTHING MORE GOES INTO THIS MODULE (PF-073). Anything further that wants
+NOTHING MORE GOES INTO THIS MODULE. Anything further that wants
 hoisting goes to `_common.mds`, or this module shrinks first; and every importer
 reaches it by ALIAS (`as mcp`), never by a selective import, whose deep copy per
 importing define is the same cliff. `tests/build-mds-compile-time.test.ts` holds

package/src/assets/scripts/hooks/assets/orchestrator-charter.md

@@ -1,7 +1,7 @@
 --- ORCHESTRATOR CHARTER ---
 You are the orchestrator of this session: you coordinate, agents produce.
 
-Never do work-product mainline: no file edits, no builds, no multi-file reads, no codebase orientation, no debug loops. Delegate all of it.
+Never do work-product mainline: no file edits, no builds, no multi-file reads, no codebase orientation, no debug loops. Delegate all of it, with one bounded exception: the main thread may run only a single git, gh or script command whose output stays under about 40 lines, and never a diff, log or test run.
 
 Routing (Agent tool) — pick the roster agent that fits the work:
 - Search and listing: Explore. Codebase orientation: Skim.
@@ -14,6 +14,8 @@ Stays mainline (judgment work): conversation, decisions, routing, synthesizing a
 Operating rules:
 - Decompose mainline. Subagents cannot spawn subagents — you own task breakdown, then delegate leaf tasks.
 - Subagents see none of this conversation. Make every delegation self-contained: goal, constraints, relevant session decisions and facts, exact paths. A deliverable that draws on the conversation (issue, PR, report) needs the substance in the prompt — not a pointer to it.
+- Report cap: ask every direct delegation for a final report of at most about 1,500 tokens — findings, paths and verdicts, not file dumps.
 - Parallelize independent delegations in one message. Git operations stay sequential.
 - Feature knowledge (direct delegations only — workflow skills handle their own): before delegating non-trivial code work, match the task area against .devflow/features/index.md and pass matching KNOWLEDGE.md content as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge to refresh that KB.
-- Plan handoff: if the user's first message begins with `Implement the following plan:`, say so in one sentence, then immediately invoke devflow:implement via the Skill tool with the full plan. Do not pause to ask.
+- Decisions (direct delegations only — workflow skills load their own): pass the index named under PROJECT DECISIONS as DECISIONS_CONTEXT — its content, read once — to every agent that takes it.
+- Plan handoff: if the user's first message begins with `Implement the following plan:`, say so in one sentence, then immediately invoke devflow:implement via the Skill tool with no arguments — the plan is already in this conversation. Do not pause to ask.

package/src/assets/scripts/hooks/background-memory-update

@@ -2,12 +2,12 @@
 
 # background-memory-update — Eager working-memory refresh worker
 # Spawned as a detached background process by memory-worker (Stop hook) after the
-# 120s throttle expires. Drains .pending-turns.jsonl → calls `claude -p` (sonnet 4.6) →
+# 120s throttle expires. Drains .pending-turns.jsonl → calls `claude -p` (sonnet 5.5) →
 # rewrites WORKING-MEMORY.md with a git-reconciliation stamp on line 1.
 #
-# Applies ADR-008 (LLM-vs-plumbing): artifact content (WORKING-MEMORY.md) is
+# Applies the LLM-vs-plumbing principle: artifact content (WORKING-MEMORY.md) is
 # authored by the LLM; this script only does plumbing (lock, queue drain, spawn).
-# Avoids PF-006 (does NOT parse Stop hook JSON), PF-007 (edit source only).
+# Does NOT parse Stop hook JSON. Edit this source file, not the installed copy.
 #
 # Usage: background-memory-update <CWD> [<manifest_path>]
 #   <manifest_path> — the devflow-global manifest whose `features.memory` is the
@@ -73,7 +73,7 @@ MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
 QUEUE_FILE="$MEMORY_DIR/.pending-turns.jsonl"
 PROCESSING_FILE="$MEMORY_DIR/.pending-turns.processing"
 MEMORY_FILE="$MEMORY_DIR/WORKING-MEMORY.md"
-STAGED_FILE="$MEMORY_FILE.new"  # staging path for CAS write (applies ADR-023)
+STAGED_FILE="$MEMORY_FILE.new"  # staging path for CAS write (D-MEMORY-STAGED-CAS)
 LOCK_DIR="$MEMORY_DIR/.working-memory.lock"
 TRIGGER_FILE="$MEMORY_DIR/.working-memory-last-trigger"
 OK_FILE="$MEMORY_DIR/.last-refresh-ok"
@@ -99,13 +99,25 @@ fi
 # --- Assert cksum availability (required for CAS verification — avoids fail-open swap) ---
 # cksum must be on PATH at startup; a missing binary makes both CAS sentinels collapse
 # to the same "ABSENT" literal, compare equal, and swap unconditionally — reinstating
-# the exact clobber ADR-023 was designed to prevent. Fail loudly here rather than
-# silently degrading. applies ADR-023
+# the exact clobber of a human edit the CAS was designed to prevent
+# (D-MEMORY-STAGED-CAS). Fail loudly here rather than silently degrading.
 if ! command -v cksum >/dev/null 2>&1; then
   log "SKIP: cksum not on PATH — CAS verification unavailable, refusing to write"
   exit 0
 fi
 
+# --- Never write through a symbolic link (D-HOOKS-NO-SYMLINK, git-marker) ---
+# The lock (`mkdir`), the batch merge (`>>`), the claim heartbeat and the success
+# stamp (`touch`) write these paths in place; the claim and the trim rename onto the
+# batch and the swap onto the working memory, and `mv` moves a file into the folder
+# a link at its target names. The trim's copy is created only where nothing stands.
+# So the run is skipped, before it takes the lock or starts an LLM run, when any of
+# these paths or a folder above them is a link.
+if ! df_no_symlink_below "$PROJECT_ROOT" "$LOCK_DIR" "$QUEUE_FILE" "$PROCESSING_FILE" "$OK_FILE" "$MEMORY_FILE"; then
+  log "SKIP: a symbolic link sits on the path to the memory files in $MEMORY_DIR; nothing written"
+  exit 0
+fi
+
 # --- Worker-level lock (300s stale-break — much longer than learning-lock's 30s) ---
 # This prevents a second worker (spawned 121s later) from double-writing WORKING-MEMORY.md
 # while the first worker's claude -p call (up to 120s) is still in flight.
@@ -158,7 +170,7 @@ fi
 
 # Clean up any staged file left by a watchdog-killed prior run.
 # Without this, a stale staged file with a valid stamp would be mistakenly
-# mv-ed to the real path on the NEXT run's CAS check (applies ADR-023).
+# mv-ed to the real path on the NEXT run's CAS check (D-MEMORY-STAGED-CAS).
 rm -f "$STAGED_FILE" 2>/dev/null || true
 
 # --- Orphan-only skip: if queue has no assistant/qa turn, exit and leave the queue ---
@@ -180,7 +192,7 @@ if [ ! -f "$PROCESSING_FILE" ] && [ -f "$QUEUE_FILE" ] && [ -s "$QUEUE_FILE" ] &
     _HAS_CONTENT=$(jq -r 'select(.role=="assistant" or .role=="qa") | .role' "$QUEUE_FILE" 2>/dev/null | head -1 || echo "")
   else
     # SECURITY: pass path via argv, never interpolate into node -e source (avoids shell injection
-    # for repo paths containing quotes or special characters — applies ADR-008 plumbing principle)
+    # for repo paths containing quotes or special characters)
     _HAS_CONTENT=$(node -e '
       const f = process.argv[1];
       const lines = require("fs").readFileSync(f, "utf8").split("\n");
@@ -210,8 +222,20 @@ if [ -f "$PROCESSING_FILE" ]; then
   _PROC_LINES=$(wc -l < "$PROCESSING_FILE" | tr -d ' ')
   if [ "$_PROC_LINES" -gt "$PROC_OVERFLOW_CAP" ]; then
     _PROC_TMP="$PROCESSING_FILE.tmp.$$"
-    tail -"$PROC_OVERFLOW_TARGET" "$PROCESSING_FILE" > "$_PROC_TMP" && mv "$_PROC_TMP" "$PROCESSING_FILE" || rm -f "$_PROC_TMP" 2>/dev/null || true
-    log "Processing overflow: truncated from $_PROC_LINES to $PROC_OVERFLOW_TARGET lines"
+    # SEC-2: the batch is the claimed queue, 0600 like the queue itself, and the
+    # cold path at session start moves it back to the queue. mv gives it the
+    # trimmed copy's inode and mode, so the copy is created under umask 077, and
+    # only where nothing stands at its name: builtin tests come first, so an entry
+    # already there, a link to a FIFO or a device included, is never opened
+    # (noclobber alone would open one, as no regular file stands there), and
+    # noclobber then makes the create itself exclusive. Such an entry is removed
+    # instead, and the batch is left untrimmed.
+    if [ ! -e "$_PROC_TMP" ] && [ ! -L "$_PROC_TMP" ] && (umask 077 && set -o noclobber && tail -"$PROC_OVERFLOW_TARGET" "$PROCESSING_FILE" > "$_PROC_TMP") && mv "$_PROC_TMP" "$PROCESSING_FILE"; then
+      log "Processing overflow: truncated from $_PROC_LINES to $PROC_OVERFLOW_TARGET lines"
+    else
+      rm -f "$_PROC_TMP" 2>/dev/null || true
+      log "Processing overflow: not truncated, its copy could not be written ($_PROC_LINES lines)"
+    fi
   fi
 elif [ -f "$QUEUE_FILE" ]; then
   mv "$QUEUE_FILE" "$PROCESSING_FILE" 2>/dev/null || { log "SKIP: failed to claim queue (race condition — another worker got it)"; exit 0; }
@@ -330,37 +354,44 @@ fi
 
 log "Built $TURN_COUNT turns from queue"
 
-# --- Capture pre-run cksum baseline + read existing memory ---
+# --- Capture pre-run cksum baseline (D-MEMORY-STAGED-CAS) + read existing memory ---
 # Baseline captured BEFORE content read so the cksum reflects the exact bytes we
 # synthesised from. ABSENT sentinel when file missing — resolves toward false-conflict,
 # never false-success (a file created externally during the run triggers CONFLICT,
-# which is safer than accepting a write we did not produce). applies ADR-023.
+# which is safer than accepting a write we did not produce).
 #
 # CKSUM_FAILED: if cksum invocation fails (EACCES, missing binary for this path, etc.)
 # on either side, the CAS must treat it as CONFLICT rather than a match — separating
 # the "cksum invocation failure" sentinel from "file absent" keeps the "resolves toward
 # false-conflict, never false-success" invariant true even when cksum errors.
+#
+# D-HOOKS-NO-SYMLINK (git-marker): the existing memory goes into the prompt, so a
+# working memory a symbolic link leads to is treated as absent. A link at its own
+# path has already skipped the run, since the swap renames onto it (above), so
+# only one that appeared since can reach this read.
+MEMORY_PRESENT=""
+if df_file_below "$PROJECT_ROOT" "$MEMORY_FILE"; then MEMORY_PRESENT="yes"; fi
 CKSUM_FAILED="false"
 PRE_RUN_CKSUM="ABSENT"
-if [ -f "$MEMORY_FILE" ]; then
+if [ -n "$MEMORY_PRESENT" ]; then
   PRE_RUN_CKSUM=$(cksum "$MEMORY_FILE" 2>/dev/null) || CKSUM_FAILED="true"
 fi
 
 EXISTING_MEMORY=""
 MEMORY_READ_LIMIT=65536  # bytes — keep prompt under context limit
-if [ -f "$MEMORY_FILE" ]; then
+if [ -n "$MEMORY_PRESENT" ]; then
   EXISTING_MEMORY=$(head -c "$MEMORY_READ_LIMIT" "$MEMORY_FILE")
 fi
 
 # Sets COMMITS_SINCE_NOTE in caller scope.
 # Reads EXISTING_MEMORY and HEAD_SHA from caller scope (must be set before call).
-# Pure parameter expansion for stamp parsing (PF-008-safe); git commands are guarded
-# with || echo / || true per set -e discipline (avoids PF-008 on pipeline exits).
+# Pure parameter expansion for stamp parsing (no pipe whose exit status a later stage
+# could mask); git commands are guarded with || echo / || true per set -e discipline.
 compute_commits_since_note() {
   local _stamp_line="${EXISTING_MEMORY%%$'\n'*}" _stamp_sha="" _rest
   case "$_stamp_line" in
     "<!-- memory-head: "[0-9a-f]*" branch: "*)
-      # Extract stamp SHA using pure parameter expansion — no subprocess (PF-008-safe).
+      # Extract stamp SHA using pure parameter expansion — no subprocess.
       _rest="${_stamp_line#<!-- memory-head: }"
       _stamp_sha="${_rest%% *}"
       ;;
@@ -418,7 +449,7 @@ fi
 
 # --- Build prompt (passed via STDIN, not argv — turn content may hold secrets) ---
 # SECURITY: argv is visible to ps(1); all user/assistant content goes via stdin.
-# SECURITY: avoids PF-023 — each untrusted block is wrapped in named XML tags and preceded
+# SECURITY: each untrusted block is wrapped in named XML tags and preceded
 # by an explicit containment declaration so injected prose cannot masquerade as operator
 # instructions regardless of positional ordering.
 PROMPT=$(cat <<EOF
@@ -469,7 +500,7 @@ Instructions:
 EOF
 )
 
-log "Spawning claude -p (model claude-sonnet-4-6, ${TURN_COUNT} turns)"
+log "Spawning claude -p (model claude-sonnet-5-5, ${TURN_COUNT} turns)"
 # SECURITY: never log PROMPT — it contains turn content which may include secrets
 
 # --- Watchdog timeout (overridable for tests: DEVFLOW_BG_WATCHDOG_SECS=2) ---
@@ -481,7 +512,6 @@ WATCHDOG_KILL_GRACE_SECS=5  # grace period between SIGTERM and SIGKILL
 # recovery can never evict a still-live worker.  If DEVFLOW_BG_WATCHDOG_SECS is raised above
 # 294 (leaving < 1s margin), this will fail loudly rather than silently corrupt the
 # safety guarantee.  Checked before spawning claude so a bad override is caught early.
-# avoids PF-011
 _WATCHDOG_TOTAL=$(( WATCHDOG_SECS + WATCHDOG_KILL_GRACE_SECS ))
 if [ "$STALE_THRESHOLD" -le "$_WATCHDOG_TOTAL" ]; then
   echo "[background-memory-update] FATAL: STALE_THRESHOLD ($STALE_THRESHOLD) must exceed watchdog total (${WATCHDOG_SECS}+${WATCHDOG_KILL_GRACE_SECS}=${_WATCHDOG_TOTAL})" >&2
@@ -509,7 +539,7 @@ fi
 # Job-control notifications go to stderr which is redirected to the log — suppress them.
 set -m
 DEVFLOW_BG_UPDATER=1 "$CLAUDE_BIN" -p \
-  --model claude-sonnet-4-6 \
+  --model claude-sonnet-5-5 \
   --dangerously-skip-permissions \
   --allowedTools 'Read,Write' \
   --output-format text \
@@ -547,7 +577,7 @@ if [ "$CLAUDE_EXIT" -gt 128 ]; then
   # Retry-count ceiling: this worker is rate-bounded to one spawn per 120s by memory-worker's
   # throttle (.working-memory-last-trigger mtime). Persistent failure is surfaced to the user
   # via session-start-memory State C (stale .last-refresh-ok) rather than a retry counter here,
-  # keeping this plumbing script simple (applies ADR-008).
+  # keeping this plumbing script simple.
   exit 0
 elif [ "$CLAUDE_EXIT" -ne 0 ]; then
   log "FAIL: claude -p exited with code $CLAUDE_EXIT"
@@ -555,36 +585,58 @@ elif [ "$CLAUDE_EXIT" -ne 0 ]; then
   exit 0
 fi
 
-# --- CAS verification (applies ADR-023: staged compare-and-swap) ---
-# Only our own claude run can create STAGED_FILE between lock-acquire and here,
-# so verifying its content proves OUR write succeeded — as opposed to accepting
-# any mtime bump, which could come from a concurrent human edit of the real file.
+# --- CAS verification (staged compare-and-swap) ---
+# D-MEMORY-STAGED-CAS: claude never writes WORKING-MEMORY.md. The prompt names
+# only STAGED_FILE (WORKING-MEMORY.md.new); this function checks that file and
+# moves it into place only when the real file is byte-identical (cksum) to the
+# pre-run read. A changed real file means someone edited it during the run:
+# CONFLICT keeps their version, discards the staged file, leaves .last-refresh-ok
+# untouched and keeps the batch in .processing for the next run. Reason: only our
+# own claude run can create STAGED_FILE between lock-acquire and here, so a valid
+# staged file proves OUR write succeeded. A check on the real file (an mtime bump,
+# a stamped line 1) passes for a human's edit too, and taking that for success
+# would delete an unprocessed batch; a direct write would also overwrite an edit
+# made mid-run.
 #
 # Sets OUTCOME to one of: updated | conflict | failed
 # Reads PRE_RUN_CKSUM, CKSUM_FAILED, STAGED_FILE, MEMORY_FILE from caller scope.
 # Each state is assigned exactly once at the point it is decided (single OUTCOME
-# variable, three states). applies ADR-023
+# variable, three states).
 verify_and_swap() {
-  [ -f "$STAGED_FILE" ] && [ -s "$STAGED_FILE" ] || {
+  # A symbolic link at the staged path counts as no staged file (D-HOOKS-NO-SYMLINK,
+  # git-marker): `head` below would read the file it names, and the swap's `mv`
+  # would rename the link itself into the working memory's place. The worker
+  # removed that path before the LLM run, so a link there was planted during it.
+  # df_file_below checks it before both, and logs the refusal once.
+  df_file_below "$PROJECT_ROOT" "$STAGED_FILE" && [ -s "$STAGED_FILE" ] || {
     log "WARN: staged file missing or empty after claude -p run"; OUTCOME="failed"; return; }
   case "$(head -1 "$STAGED_FILE" 2>/dev/null || echo "")" in
     "<!-- memory-head:"*) : ;;
     *) log "WARN: staged file exists but stamp missing on line 1 — treating as failure"
        rm -f "$STAGED_FILE" 2>/dev/null || true; OUTCOME="failed"; return ;;
   esac
+  # A symbolic link on the working memory's path refuses the swap
+  # (D-HOOKS-NO-SYMLINK, git-marker): the run began without one, so a link there now
+  # is a change made during the run, and `mv` would move the staged memory into a
+  # folder it names. When the run began with no working memory, the cksum
+  # comparison below would take the link for that absent file.
+  if ! df_no_symlink_below "$PROJECT_ROOT" "$MEMORY_FILE"; then
+    rm -f "$STAGED_FILE" 2>/dev/null || true
+    log "CONFLICT: a symbolic link appeared on the path to $MEMORY_FILE during the run — not swapped, leaving .processing for retry"
+    OUTCOME="conflict"; return
+  fi
   # Re-check real file cksum before swapping.
   # Residual TOCTOU: a human edit landing in the O(ms) window between this
   # cksum re-check and the mv would be clobbered; this is accepted — the
   # staged content was synthesised from the pre-run file, so the next run
   # re-synthesises from the then-current content (no net information loss).
-  # applies ADR-023 (staged compare-and-swap)
   local _post="ABSENT" _post_cksum_failed="false"
   if [ -f "$MEMORY_FILE" ]; then
     _post=$(cksum "$MEMORY_FILE" 2>/dev/null) || _post_cksum_failed="true"
   fi
   # If either cksum invocation failed, treat as conflict (fail-closed — resolves toward
   # false-conflict, never false-success; a cksum error must never silently degrade the
-  # CAS to "always overwrite", reinstating the clobber ADR-023 exists to prevent).
+  # CAS to "always overwrite", reinstating the clobber of a human edit it exists to prevent).
   if [ "$CKSUM_FAILED" = "true" ] || [ "$_post_cksum_failed" = "true" ]; then
     rm -f "$STAGED_FILE" 2>/dev/null || true
     log "CONFLICT: cksum failed during CAS verification — leaving .processing for retry (fail-closed)"
@@ -607,14 +659,26 @@ verify_and_swap() {
 OUTCOME="failed"
 verify_and_swap
 
+# Each stamp below is a `touch`, which follows a symbolic link, and its path was
+# checked before the LLM run, which can take minutes. So, like the swap's target,
+# it is checked again just before the touch: a link there now is a change made
+# during the run, and the stamp is skipped and logged (D-HOOKS-NO-SYMLINK, git-marker).
 if [ "$OUTCOME" = "updated" ]; then
   rm -f "$PROCESSING_FILE" 2>/dev/null || true
-  touch "$OK_FILE" 2>/dev/null || true
-  log "SUCCESS: queue drained, .last-refresh-ok touched"
+  if df_no_symlink_below "$PROJECT_ROOT" "$OK_FILE"; then
+    touch "$OK_FILE" 2>/dev/null || true
+    log "SUCCESS: queue drained, .last-refresh-ok touched"
+  else
+    log "SUCCESS: queue drained; .last-refresh-ok not touched, a symbolic link appeared on its path during the run"
+  fi
 elif [ "$OUTCOME" = "conflict" ]; then
   # Heartbeat: this batch is still owned by the retry cycle, not orphaned.
   # Keeps session-start-memory's 300s cold path from reclaiming a live retry.
-  touch "$PROCESSING_FILE" 2>/dev/null || true
+  if df_no_symlink_below "$PROJECT_ROOT" "$PROCESSING_FILE"; then
+    touch "$PROCESSING_FILE" 2>/dev/null || true
+  else
+    log "Heartbeat skipped: a symbolic link appeared on the path to $PROCESSING_FILE during the run"
+  fi
   log "CONFLICT: queue retained in .processing, .last-refresh-ok untouched"
 else
   # Leave .processing for session-start-memory's D56c cold path; do NOT touch .last-refresh-ok

package/src/assets/scripts/hooks/capture-prompt

@@ -84,11 +84,12 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-prompt: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-prompt: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 TS=$(date +%s)
 queue_append_both \
-  "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+  "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+  "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
   "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
   "user" "$PROMPT" "$TS"
 

package/src/assets/scripts/hooks/capture-question

@@ -140,8 +140,8 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-question: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-question: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 _QUESTION_COUNT=0
 while IFS=$'\t' read -r Q A; do
   [ -z "$Q" ] && continue
@@ -150,7 +150,8 @@ while IFS=$'\t' read -r Q A; do
 A: ${A}"
   TS=$(date +%s)
   queue_append_both \
-    "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+    "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+    "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
     "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
     "qa" "$CONTENT" "$TS"
   _QUESTION_COUNT=$(( _QUESTION_COUNT + 1 ))

package/src/assets/scripts/hooks/capture-turn

@@ -2,9 +2,7 @@
 
 # Learning System: capture-turn (Stop Hook)
 # Dual-append: writes the assistant turn to BOTH the memory queue and the
-# learning queue, each independently gated by its own feature flag (AC-F4). Runs
-# the decisions usage scanner (D29 grep-first) regardless of which queue is
-# gated on/off -- memory-disabled projects still run the usage scanner. The
+# learning queue, each independently gated by its own feature flag (AC-F4). The
 # 120s-throttle/nohup-spawn block lives in memory-worker, a separate Stop
 # hook that Claude Code runs in parallel with this one; the worker tolerates a
 # queue this hook has not appended to yet (D-QUEUE-NO-ORPHAN-DELETE).
@@ -77,20 +75,6 @@ LEARNING_ENABLED="$_QG_LEARNING"
 
 dbg "MEMORY_ENABLED=$MEMORY_ENABLED LEARNING_ENABLED=$LEARNING_ENABLED"
 
-# --- Decisions usage scanner (independent of the memory/learning queue gates below) ---
-# D29: Grep-first reorder -- cheap in-process citation check gates the scanner call.
-# The scanner writes the ledger's usage file, and it runs before ensure-devflow-init,
-# so it takes the D-HOOKS-GIT-ONLY gate itself (df_is_project_root, git-marker via
-# resolve-project-root; zero forks): a `.devflow/` an older devflow left in a
-# non-git directory, or at HOME, is not a project's ledger.
-SCANNER="$SCRIPT_DIR/decisions-usage-scan.cjs"
-if [ -f "$SCANNER" ] && printf '%s' "$ASSISTANT_MSG" | grep -qE 'ADR-[0-9]+|PF-[0-9]+'; then
-  if [ "$LEARNING_ENABLED" = "true" ] && df_is_project_root "$PROJECT_ROOT" 2>/dev/null; then
-    dbg "Running decisions usage scanner"
-    printf '%s' "$ASSISTANT_MSG" | node "$SCANNER" --cwd "$LEDGER_ROOT" 2>/dev/null || true
-  fi
-fi
-
 if [ "$MEMORY_ENABLED" != "true" ] && [ "$LEARNING_ENABLED" != "true" ]; then
   dbg "EXIT: both features disabled"
   exit 0
@@ -106,11 +90,12 @@ source "$SCRIPT_DIR/ensure-devflow-init" "$CWD" || exit 0
 source "$SCRIPT_DIR/get-mtime" || { echo "capture-turn: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/learning-lock" || { echo "capture-turn: failed to source learning-lock" >&2; exit 1; }
 
-mkdir -p "$MEMORY_DIR" "$LEARNING_DIR" 2>/dev/null || true
-
+# Each queue is checked from the root it lies below, and its folder created there,
+# by queue_append_row (D-HOOKS-NO-SYMLINK, git-marker).
 TS=$(date +%s)
 queue_append_both \
-  "$MEMORY_DIR/.pending-turns.jsonl" "$LEARNING_DIR/.pending-turns.jsonl" \
+  "$PROJECT_ROOT" "$MEMORY_DIR/.pending-turns.jsonl" \
+  "$LEDGER_ROOT" "$LEARNING_DIR/.pending-turns.jsonl" \
   "$MEMORY_ENABLED" "$LEARNING_ENABLED" \
   "assistant" "$ASSISTANT_MSG" "$TS"
 

package/src/assets/scripts/hooks/ensure-devflow-init

@@ -2,7 +2,8 @@
 # Ensures .devflow/ and all subdirectories exist and the project root .gitignore
 # ignores .devflow/. Called from capture-prompt, capture-turn, capture-question,
 # memory-worker, and pre-compact-memory. Idempotent.
-# Returns non-zero, having written nothing, outside a git project or at HOME.
+# Returns non-zero, having written nothing, outside a git project, at HOME, or when
+# .devflow is a symbolic link.
 # Usage: source ensure-devflow-init "$CWD"
 
 [ -z "$1" ] && return 1
@@ -25,7 +26,7 @@ _EDI_LEDGER="${DF_LEDGER_ROOT:-$_EDI_ROOT}"
 # pre-compact-memory) passes through before it writes, and each of them treats a
 # non-zero return as "stop" (`|| exit 0`), so memory and learning stop together
 # in a non-git directory. ensure-root-gitignore itself stays ungated: it is a
-# pure writer its parity suite runs in plain directories (PF-059), and both of
+# pure writer its parity suite runs in plain directories, and both of
 # its callers now decide before reaching it. A helper that failed to source is a
 # command not found — the refusing branch, so the failure mode writes nothing.
 source "$_EDI_DIR/git-marker" 2>/dev/null || true
@@ -33,6 +34,17 @@ df_is_project_root "$_EDI_ROOT" 2>/dev/null || return 1
 
 _DEVFLOW_DIR="$_EDI_ROOT/.devflow"
 
+# D-HOOKS-NO-SYMLINK (git-marker): a `.devflow` that is itself a symbolic link
+# would take every folder below and the carve-out marker into the folder it names,
+# so nothing is written and the caller stops, as at any root it may not write to.
+# The skip is logged once, through log() where the caller defines it. A folder below
+# `.devflow` that is a link is left to the write under it: `mkdir -p` creates
+# nothing through a link it ends at.
+if ! df_no_symlink_below "$_EDI_ROOT" "$_DEVFLOW_DIR"; then
+  declare -F log >/dev/null 2>&1 && log "Skipped: $_DEVFLOW_DIR is a symbolic link; nothing written under it"
+  return 1
+fi
+
 # learning/ is scaffolded only where the ledger lives. In a linked worktree whose
 # main checkout holds the ledger (D-LEDGER-MAIN-WORKTREE, resolve-project-root) a
 # learning/ here would be an empty directory nothing writes to; the capture hooks

package/src/assets/scripts/hooks/ensure-proxy

@@ -15,8 +15,8 @@
 # Branding: "subswitch" is an internal identifier (health check body match, SUBSWITCH_CONFIG env var,
 # spawn args); it MUST NOT appear in user-visible strings or additionalContext messages.
 #
-# avoids PF-001: port is digit-validated before interpolation into /dev/tcp and context strings.
-# avoids PF-014: hook always exits 0; no fd held across exit.
+# Port is digit-validated, falling back to the default, before reaching /dev/tcp or context strings.
+# Hook always exits 0; no fd held across exit.
 
 # Safe no-op fallback — must exist before hook-bootstrap is sourced
 dbg() { :; }
@@ -71,7 +71,7 @@ if [ "$PROXY_ENABLED" != "true" ]; then
   exit 0
 fi
 
-# Digit-validate port before use in /dev/tcp and string interpolation (avoids PF-001)
+# Digit-validate port before use in /dev/tcp and string interpolation
 PROXY_PORT_RAW=$(json_field_file "$PROXY_STATE_FILE" "port" "4141")
 PROXY_PORT="4141"
 case "$PROXY_PORT_RAW" in
@@ -189,8 +189,7 @@ dbg "PROXY_BIN=$PROXY_BIN PROXY_CONFIG=$PROXY_CONFIG"
 #   b) `command -v subswitch` — globally installed CLI.
 # Re-resolution is best-effort: on failure the existing warning is emitted and the
 # hook exits 0 as before. The healed path is used for this session only; the next
-# successful `devflow proxy --enable` persists it to proxy.json. (avoids PF-001,
-# avoids PF-009: non-fatal on failure, always exits 0)
+# successful `devflow proxy --enable` persists it to proxy.json.
 if [ -z "$PROXY_BIN" ] || [ ! -f "$PROXY_BIN" ]; then
   log "prereq: binPath missing or not a file (${PROXY_BIN:-<empty>}) — attempting re-resolution"
   _RESOLVED_BIN=""
@@ -295,7 +294,7 @@ log "spawning relay: $NODE_BIN $PROXY_BIN serve"
 (umask 077 && touch "$LOG_FILE") 2>/dev/null || true
 chmod 600 "$LOG_FILE" 2>/dev/null || true
 
-# SEC-2 (allowlist): scope the relay's env to exactly what it needs — avoids PF-017.
+# SEC-2 (allowlist): scope the relay's env to exactly what it needs.
 # NODE_EXTRA_CA_CERTS is included when non-empty so corporate-TLS deployments can
 # supply a CA bundle; an unset/empty value is not injected (an empty path causes
 # TLS errors rather than being a no-op). NODE_OPTIONS is deliberately excluded: