devflow-kit 3.0.1 → 3.2.0

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

@@ -70,7 +70,11 @@ fi
 # re-spawns (memory disabled mid-flight, host offline, etc.): a SessionStart
 # arriving >300s after the crash with no intervening Stop hook.
 # Non-clobber: only recovers when .pending-turns.jsonl does NOT already exist,
-# so a concurrent session's fresh queue is never overwritten.
+# so a concurrent session's fresh queue is never overwritten. Nor where a
+# symbolic link sits on the path to the batch or to the queue it is renamed onto
+# (D-HOOKS-NO-SYMLINK, git-marker): `mv` would move the batch into a folder a
+# linked memory folder or queue path names, and a linked batch would become a
+# linked queue.
 source "$SCRIPT_DIR/get-mtime" || { echo "session-start-memory: failed to source get-mtime" >&2; exit 1; }
 source "$SCRIPT_DIR/is-hex-sha" || { echo "session-start-memory: failed to source is-hex-sha" >&2; exit 1; }
 _SSM_PT_PROC="$MEMORY_DIR/.pending-turns.processing"
@@ -81,7 +85,10 @@ if [ -f "$_SSM_PT_PROC" ]; then
   _SSM_NOW_PT=$(date +%s)
   _SSM_PT_AGE=$(( _SSM_NOW_PT - _SSM_PT_MTIME ))
   if [ "$_SSM_PT_AGE" -gt 300 ]; then
-    if [ ! -f "$_SSM_PT_JSONL" ]; then
+    if ! df_no_symlink_below "$PROJECT_ROOT" "$_SSM_PT_PROC" "$_SSM_PT_JSONL"; then
+      dbg "Stale .pending-turns.processing skipped — a symbolic link sits on its path or the queue's"
+      log "Stale .pending-turns.processing skipped (cold path): a symbolic link sits on the path to $_SSM_PT_PROC or $_SSM_PT_JSONL"
+    elif [ ! -f "$_SSM_PT_JSONL" ]; then
       mv "$_SSM_PT_PROC" "$_SSM_PT_JSONL" 2>/dev/null || true
       dbg "Recovered orphaned .pending-turns.processing (age ${_SSM_PT_AGE}s)"
       log "Recovered orphaned .pending-turns.processing → .pending-turns.jsonl (cold path)"
@@ -135,27 +142,31 @@ parse_and_validate_stamp() {
   esac
 }
 
-# --- detect_refresh_failing: sets REFRESH_FAILING in caller's scope.
+# --- detect_refresh_failing <now> <memory_dir> <log_dir> <root>: sets
+# REFRESH_FAILING in caller's scope. <root> is the project root the memory folder
+# lies below.
 # Condition: queue non-empty AND (.last-refresh-ok missing OR >600s old)
 # orphaned-processing depth fix: count both .pending-turns.jsonl AND
 # .pending-turns.processing toward _queue_depth. Before this fix, an orphaned
 # .processing (whose mtime is between 0s and the D56c 300s cold-path gate)
 # was invisible to State-C — a crashed worker's batch would sit silently with
-# no user-visible warning.
+# no user-visible warning. The count reaches the session, so a batch a symbolic
+# link leads to counts as absent (D-HOOKS-NO-SYMLINK, git-marker).
 detect_refresh_failing() {
   local _now="$1"
   local _memory_dir="$2"
   local _log_dir="$3"
+  local _root="$4"
   local _queue_file="$_memory_dir/.pending-turns.jsonl"
   local _proc_file="$_memory_dir/.pending-turns.processing"
   local _ok_file="$_memory_dir/.last-refresh-ok"
   local _queue_depth=0
-  if [ -f "$_queue_file" ] && [ -s "$_queue_file" ]; then
+  if df_file_below "$_root" "$_queue_file" && [ -s "$_queue_file" ]; then
     _queue_depth=$(wc -l < "$_queue_file" | tr -d ' ')
   fi
   # Also count lines in .processing — an orphaned batch left by a crashed worker
   # is unprocessed content even if .jsonl is empty (applies B4 blind-spot fix)
-  if [ -f "$_proc_file" ] && [ -s "$_proc_file" ]; then
+  if df_file_below "$_root" "$_proc_file" && [ -s "$_proc_file" ]; then
     local _proc_depth
     _proc_depth=$(wc -l < "$_proc_file" | tr -d ' ')
     _queue_depth=$(( _queue_depth + _proc_depth ))
@@ -180,7 +191,14 @@ detect_refresh_failing() {
   fi
 }
 
-if [ -f "$MEMORY_FILE" ]; then
+# D-HOOKS-NO-SYMLINK (git-marker): the working memory, the batches State C counts
+# and the pre-compact backup are all read into the session, so each is read only
+# where no symbolic link sits on its path; a file a link leads to is treated as
+# absent, and its refusal logged once.
+MEMORY_PRESENT=""
+if df_file_below "$PROJECT_ROOT" "$MEMORY_FILE"; then MEMORY_PRESENT="yes"; fi
+
+if [ -n "$MEMORY_PRESENT" ]; then
   dbg "MEMORY_FILE exists: $MEMORY_FILE"
   MEMORY_CONTENT=$(head -c 65536 "$MEMORY_FILE")
 
@@ -239,7 +257,7 @@ if [ -f "$MEMORY_FILE" ]; then
   fi
 
   # --- State C detection: refresh failing ---
-  detect_refresh_failing "$NOW" "$MEMORY_DIR" "$LOG_DIR"
+  detect_refresh_failing "$NOW" "$MEMORY_DIR" "$LOG_DIR" "$PROJECT_ROOT"
 
   # --- Build state-specific header ---
   # D-DETACHED-HEAD: where the session is, as one phrase. On a branch it is
@@ -292,8 +310,12 @@ fi
 # Re-inject compaction snapshot when it's more recent than the memory file (compact overwrote
 # WORKING-MEMORY.md with a summary, but the pre-compact snapshot may have richer context).
 BACKUP_FILE="$MEMORY_DIR/backup.json"
-if [ -f "$BACKUP_FILE" ]; then
-  BACKUP_MEMORY=$(json_field_file "$BACKUP_FILE" "memory_snapshot" "")
+if df_file_below "$PROJECT_ROOT" "$BACKUP_FILE"; then
+  # Under set -e a failed read would end the hook before it prints the working
+  # memory built above, so a backup that does not parse is read as no snapshot,
+  # like an absent one, discarding what jq printed before it failed. The read
+  # below runs only once this one has parsed the whole file.
+  BACKUP_MEMORY=$(json_field_file "$BACKUP_FILE" "memory_snapshot" "") || BACKUP_MEMORY=""
   if [ -n "$BACKUP_MEMORY" ]; then
     BACKUP_TS=$(json_field_file "$BACKUP_FILE" "timestamp" "")
     BACKUP_EPOCH=0
@@ -303,7 +325,7 @@ if [ -f "$BACKUP_FILE" ]; then
         || echo "0")
     fi
     FILE_MTIME_CK=0
-    if [ -f "$MEMORY_FILE" ]; then
+    if [ -n "$MEMORY_PRESENT" ]; then
       FILE_MTIME_CK=$(get_mtime "$MEMORY_FILE" 2>/dev/null || echo "0")
     fi
     if [ "$BACKUP_EPOCH" -gt "$FILE_MTIME_CK" ]; then

package/src/assets/scripts/lib/project-config.cjs

@@ -2,14 +2,14 @@
 //
 // The ONE parser of devflow's per-repository config files — the team-committed
 // `.devflow/project.json` and the personal, uncommitted `.devflow/config.json`
-// (applies PF-023: the invariant lives at the sink every reader passes through).
+// (the invariant lives at the sink every reader passes through).
 // Installed beside its two callers as ~/.devflow/scripts/lib/project-config.cjs:
 //   resolve-evidence-policy.cjs  reads `evidence` and `compliance` at every source
 //   resolve-settings.cjs         reads every key of both files, locally
 //
 // Pure except the two readers (readBoundedRegularFile, readMachineManifest), which
 // only ever read. Nothing here writes, spawns or prints: devflow never writes
-// project.json (applies ADR-024).
+// project.json, which the team owns and commits.
 //
 // D-PROJECT-CONFIG: `.devflow/project.json` is a JSON object whose every key is
 // optional and whose unknown keys are ignored:

package/src/assets/scripts/pr-evidence.cjs

@@ -898,7 +898,7 @@ function needsDiff(x) {
 /**
  * D-LADDER: the arms, in the order they are tried. PRECEDENCE is derived from
  * this table. Every arm but the last is a POSITIVE match; the last is the
- * conservative default (applies PF-075: a verified state is only ever reached by
+ * conservative default (a verified state is only ever reached by
  * a positive conjunction, never because nothing else matched).
  *
  * @type {readonly Arm[]}
@@ -978,7 +978,7 @@ const ARMS = Object.freeze([
 /**
  * D-LADDER: the order `classify` tries its arms in — first match wins, and the
  * terminal arm is the conservative UNVERIFIED, so no state is ever reached by
- * exhaustion (applies PF-075). DERIVED from ARMS, so the order the contract states
+ * exhaustion. DERIVED from ARMS, so the order the contract states
  * (parity-pinned to this list) and the order the code runs cannot drift apart.
  */
 const PRECEDENCE = Object.freeze(/** @type {State[]} */ (ARMS.map(arm => arm.state)));
@@ -1446,7 +1446,7 @@ function parseEvidenceComment(text) {
 }
 
 // ---------------------------------------------------------------------------
-// splice — only the bytes between the markers are devflow's (applies ADR-024)
+// splice — only the bytes between the markers are devflow's
 // ---------------------------------------------------------------------------
 
 /**

package/src/assets/scripts/redact-secrets.cjs

@@ -40,19 +40,19 @@
 //      posted" from "the script broke": the first is final, the second is retried.
 //
 // Design constraints (binding):
-//   PF-011  the file sink — the one file this script writes — goes via
-//           temp-sibling + rename (atomic same-fs write; readers see old-or-new,
-//           never a momentarily absent file). `--emit` prints to stdout and
-//           touches no file, so it has nothing to protect
-//   PF-014  never call process.exit() inside any scope with pending cleanup or
-//           buffered output; main() returns an exit code; the single top-level
-//           boundary writes stdout SYNCHRONOUSLY then sets process.exitCode so
-//           nothing is truncated and no finally block is skipped
-//   PF-018  all regexes are bounded (no unbounded [\s\S]*); skip-list checked
-//           before any replacement; the unterminated-header pattern uses a
-//           character class instead of a lazy quantifier for bounded scan
-//   PF-023  self-contained sink-side control — never assumes upstream masking
-//           happened; the scrubber is authoritative for its own rule set
+//   - the file sink — the one file this script writes — goes via
+//     temp-sibling + rename (atomic same-fs write; readers see old-or-new,
+//     never a momentarily absent file). `--emit` prints to stdout and
+//     touches no file, so it has nothing to protect
+//   - never call process.exit() inside any scope with pending cleanup or
+//     buffered output; main() returns an exit code; the single top-level
+//     boundary writes stdout SYNCHRONOUSLY then sets process.exitCode so
+//     nothing is truncated and no finally block is skipped
+//   - all regexes are bounded (no unbounded [\s\S]*); skip-list checked
+//     before any replacement; the unterminated-header pattern uses a
+//     character class instead of a lazy quantifier for bounded scan
+//   - self-contained sink-side control — never assumes upstream masking
+//     happened; the scrubber is authoritative for its own rule set
 
 'use strict';
 
@@ -98,7 +98,7 @@ const NONCE_HEX_CHARS = 32;
  * rule then describes a property of every body this script can emit, instead of
  * an obligation nine documents have to restate correctly.
  *
- * PF-018: bounded — a fixed alternation over two literals, anchored per line by
+ * Bounded — a fixed alternation over two literals, anchored per line by
  * the `m` flag, with no quantifier to backtrack through. The trailing space is
  * load-bearing: it is what keeps prose such as `D11-FAILURE` out of the refusal.
  */
@@ -268,7 +268,7 @@ function hasMixedAlphanumerics(s) {
 // Scrubbing pass
 //
 // Rules are applied in the declared order. Each rule uses a bounded regex to
-// avoid catastrophic backtracking (PF-018). The final secret-assignment rule
+// avoid catastrophic backtracking. The final secret-assignment rule
 // operates line-by-line and applies entropy + character-class heuristics to
 // avoid false positives on config references.
 // ---------------------------------------------------------------------------
@@ -375,7 +375,7 @@ function scrub(content) {
   // (`this.apiToken`, `api-key`). Without these the rule only ever fired on a
   // bare column-0 assignment, which is the rarest form inside a review finding.
   // The declarator group is bounded {0,3} and each iteration must consume a
-  // literal keyword, so the added alternation cannot backtrack (PF-018).
+  // literal keyword, so the added alternation cannot backtrack.
   //
   // Conditions for replacement (all must hold):
   //   (a) The KEY matches SECRET_KEY_RE — not merely the line, so a prose line
@@ -590,7 +590,7 @@ function frameEmit(scrubbed, scrubLine, nonceSource) {
 // ---------------------------------------------------------------------------
 // main — returns an exit code (never calls process.exit() internally)
 //
-// PF-014: no process.exit() inside any scope that has pending cleanup or
+// No process.exit() inside any scope that has pending cleanup or
 // buffered output. main() returns a numeric code for error paths or an
 // object {scrubLine} for the success path. The single top-level boundary
 // writes stdout synchronously and sets process.exitCode — nothing is
@@ -656,7 +656,7 @@ function readInput(inputPath) {
 function runFileMode(args, content) {
   const { result, counts } = scrub(content);
 
-  // ---- atomic write (PF-011: temp-sibling + rename) ----
+  // ---- atomic write (temp-sibling + rename) ----
   const tmpPath = args.outputPath + '.tmp';
   try {
     fs.writeFileSync(tmpPath, result, 'utf8');
@@ -686,7 +686,7 @@ function runFileMode(args, content) {
  * prints them, so there is nothing for a write discipline to protect: a scrubbed
  * comment body put on disk is a second copy with the input directory's lifetime,
  * and proving that directory writable would let a filesystem property refuse a
- * clean, fully gated body. The file mode's temp-sibling + rename (PF-011) guards
+ * clean, fully gated body. The file mode's temp-sibling + rename guards
  * the one file this script does write.
  *
  * @param {string} content
@@ -762,7 +762,7 @@ function main(argv, deps) {
 //
 // This is the ONLY place that writes to stdout and sets process.exitCode.
 // No other code path may call process.exit() or write to stdout.
-// (PF-014: single synchronous write, no pending cleanup, no buffered output)
+// (single synchronous write, no pending cleanup, no buffered output)
 //
 // AMENDED for --emit, not bypassed. main()'s return widened from
 // `number | {scrubLine}` to also carry `{emitLine, body, code}`, and the write

package/src/assets/scripts/release-trace.cjs

@@ -445,7 +445,7 @@ function isChangelogOnly(paths) {
 /**
  * D-TRACE-CLASSIFY: one first-parent commit's class. First match wins, in
  * CLASSES order, and the terminal arm is `untraced` — an input no rule
- * recognises surfaces in the confirm rather than passing silently (avoids PF-075).
+ * recognises surfaces in the confirm rather than passing silently.
  *
  * @param {Commit} commit
  * @param {ClassifyContext} ctx

package/src/assets/scripts/resolve-evidence-policy.cjs

@@ -11,7 +11,7 @@
 // The policy is plumbing, decided once by the caller: this script prints it plus
 // the mechanism inputs, and operations only ever see the inputs. It WRITES NOTHING
 // — no file, no git ref, no remote state — so `.devflow/project.json` stays a
-// team-owned file that only the team commits (applies ADR-024). A committed
+// team-owned file that only the team commits. A committed
 // `.devflow/policy.json` is detected by presence and never parsed
 // (D-POLICY-JSON-RETIRED).
 //
@@ -432,7 +432,7 @@ function readManifestCompliance() {
  * starting (ENOENT), timing out, overflowing its buffer or being killed. Only an
  * answered non-zero exit is a real "no" ("not a repository", "no such path",
  * "no such ref"); an unanswered call is NOT KNOWING, and a local-git step that
- * does not know must not read as the permissive answer (avoids PF-075).
+ * does not know must not read as the permissive answer.
  *
  * @param {CallResult} r
  * @returns {boolean}
@@ -621,7 +621,7 @@ function lsRemoteDefaultBranch(ctx, root) {
  *   unreadable  git did not answer, or origin/HEAD exists but its answer names
  *               no safe branch (another remote, a hostile or unparseable name).
  *               Either is a failure, never the residual case: gatherFacts reads
- *               it as an invalid base, which resolves required (avoids PF-075).
+ *               it as an invalid base, which resolves required.
  *               resolve-settings' defaultBranchCompliance fails the same answer
  *               closed, to `generic`.
  *

package/src/assets/scripts/resolve-settings.cjs

@@ -35,7 +35,7 @@
 // publication can only lower it (D-PUBLICATION-CEILING) — a branch's
 // `reviewPublication: "full"` raises nothing, since only a personal value asks
 // for more than `auto`. The tracker (provider, site, key) is taken as the
-// branch states it. It WRITES NOTHING (applies ADR-024).
+// branch states it. It WRITES NOTHING: each layer it folds is changed only by its owner.
 //
 // stdout is exactly one line plus "\n", or empty (D-SETTINGS-LINE):
 //   TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default>
@@ -750,7 +750,7 @@ function readRepoLayers(root, deps) {
  * (D-LENS-UNION, D-SETTINGS-LOCAL-ONLY): origin/HEAD names the branch D, and
  * `refs/remotes/origin/<D>:.devflow/project.json` is read through the same
  * parser. The lens only adds, so every state that cannot be read is a malformed
- * declaration (`generic`), never "declares nothing" (avoids PF-075):
+ * declaration (`generic`), never "declares nothing":
  *   absent     origin/HEAD is not recorded, or D holds no project.json
  *   malformed  a git call did not answer, origin/HEAD names no safe branch, the
  *              blob overflows its bound, the file is unreadable, or its
@@ -898,7 +898,7 @@ function settleOutcome(outcome) {
 }
 
 // ---------------------------------------------------------------------------
-// The suggestion the CLI prints (never writes — ADR-024)
+// The suggestion the CLI prints (never writes — the team commits it)
 // ---------------------------------------------------------------------------
 
 /**

package/src/assets/scripts/verify-evidence.cjs

@@ -459,7 +459,7 @@ function runCall(io, file, args, timeout, maxBuffer) {
 /**
  * Whether a call ran to completion and exited on its own. Only an answered exit
  * is a real "no"; a call that never started, timed out, overflowed or was refused
- * is NOT KNOWING, and never reads as the permissive answer (avoids PF-075).
+ * is NOT KNOWING, and never reads as the permissive answer.
  *
  * @param {CallResult} r
  * @returns {boolean}
@@ -1530,7 +1530,7 @@ function gateEvidenceLine(deps, fields, total) {
 }
 
 // ---------------------------------------------------------------------------
-// splice — the compare-and-swap (D-VERIFY-CAS, applies ADR-023 and ADR-024)
+// splice — the compare-and-swap (D-VERIFY-CAS)
 // ---------------------------------------------------------------------------
 
 /**

package/src/assets/skills/apply-decisions/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: apply-decisions
-description: Canonical algorithm for consuming DECISIONS_CONTEXT index — scan index, identify relevant entries, Read full bodies on demand, cite verbatim IDs inline.
+description: Canonical algorithm for consuming DECISIONS_CONTEXT index — scan index, identify relevant entries, Read full bodies on demand, cite verbatim IDs in-session and state the rule in words in anything committed or posted.
 user-invocable: false
 allowed-tools: Read
 ---
 
 # Apply Decisions
 
-Canonical consumer algorithm for the `DECISIONS_CONTEXT` index passed by orchestrators. The index lists each ADR/PF entry with ID, truncated title, status, and area — not the full body. Use this skill to surface the right decisions and pitfalls for your task without loading the entire corpus.
+Canonical consumer algorithm for the `DECISIONS_CONTEXT` index passed by orchestrators. The index lists each active ADR/PF entry with its ID and title — plus a status tag and an area on a v1 line, or the entry's scope on a v2 line — not the full body. Use this skill to surface the right decisions and pitfalls for your task without loading the entire corpus.
 
 ## Iron Law
 
@@ -23,35 +23,52 @@ Canonical consumer algorithm for the `DECISIONS_CONTEXT` index passed by orchest
 
 ### Step 1: Scan the index
 
-Read through all entries in `DECISIONS_CONTEXT`. The index format is:
+Read through all entries in `DECISIONS_CONTEXT`. The index lists active entries only, in two line kinds:
 
 ```
 Decisions (N):
-  ADR-001  Title truncated to 60 chars  [Active]
-  ADR-002  Another decision             [Active]
+  ADR-NNN  Return Result types from every fallible operation  [Accepted]
+  ADR-NNN  Claim the learning queue with an op, never with mv  —  src/assets/scripts/hooks/**, area:learning
 
 Pitfalls (M):
-  PF-004  Background hook god scripts  [Active]  —  src/assets/scripts/hooks/foo.cjs
-  PF-011  DECISIONS_CONTEXT fan-out    [Active]  —  src/assets/commands/...
+  PF-NNN  Background hook god scripts  [Active]  —  src/assets/scripts/hooks/foo.cjs
+  PF-NNN  A rename claims a shared file only while nothing re-creates it  —  area:hooks
 
 ADR-NNN entries live in {worktree}/.devflow/learning/decisions.md
 PF-NNN  entries live in {worktree}/.devflow/learning/pitfalls.md
 Read the relevant file and locate the matching `## ADR-NNN:` or `## PF-NNN:` heading for the full body.
 ```
 
+- **A v1 line** ends in a status tag — `[Accepted]` on a decision, `[Active]` on a pitfall — after a title cut to 60 characters, and a pitfall adds its area after `—`.
+- **A v2 line** has no tag. Its title is whole, and after `—` comes its scope: the globs and `area:` tags the rule governs, cut to 80 characters.
+
 ### Step 2: Identify plausibly-relevant entries
 
-From the index, identify entries whose title or area plausibly overlaps with:
-- The files you are modifying or reviewing
+From the index, identify entries whose title, area or scope plausibly overlaps with:
+- The files you are modifying or reviewing — a v2 scope glob that matches one of them is a strong signal
 - The category of issue you are addressing (e.g., error handling, hook scripts, JSON parsing)
 - The architectural area of your change
 
-Titles are truncated to 60 characters — if a truncated title looks relevant, proceed to Step 3.
+A v1 title may be cut short — if a truncated title looks relevant, proceed to Step 3.
 
 ### Step 3: Read the full body
 
 For each plausibly-relevant entry, use the Read tool to open the decisions file listed in the `DECISIONS_CONTEXT` footer and locate the matching `## ADR-NNN:` or `## PF-NNN:` heading. Read the full section to confirm relevance and understand the decision or pitfall completely.
 
+A v2 body reads:
+
+```
+## ADR-NNN: {title}
+
+- **Status**: Accepted · verified {date}
+- **Scope**: `{glob}`, `area:{tag}`
+- **Decision**: {the rule}
+- **Why**: {why it holds}
+- **Source**: {where it was learned}
+```
+
+A pitfall's Status is `Active` and its rule line is labelled `**Rule**`. The verified date is the day the entry was last confirmed true; a body without one has not been confirmed since it was written. A v1 body carries `**Date**`, `**Status**`, `**Context**`, `**Decision**` and `**Consequences**` for a decision, or `**Area**`, `**Issue**`, `**Impact**`, `**Resolution**` and `**Status**` for a pitfall.
+
 **The footer is the single source of truth for file paths.** Never substitute hardcoded paths — the footer resolves to the correct worktree, which may differ from your cwd in multi-worktree flows.
 
 ```
@@ -62,9 +79,11 @@ Use the exact paths from the DECISIONS_CONTEXT footer, e.g.:
 
 Only cite an entry after you have read its full body and confirmed it applies.
 
-### Step 4: Cite inline
+### Step 4: Cite inline — in-session handoffs only
+
+When applying a prior decision, cite as `applies ADR-NNN`. When avoiding a known pitfall, cite as `avoids PF-NNN`. Place these citations only where they stay in the session: your reasoning, decision tables, prompts to downstream agents, and your report back to the caller.
 
-When applying a prior decision, cite as `applies ADR-NNN` in your reasoning or output. When avoiding a known pitfall, cite as `avoids PF-NNN`. Place citations in the Reasoning column of decision tables, in inline comments, or in your structured output — wherever your agent's output format captures rationale.
+Anything committed, pushed or posted states the rule in words, never its ID: code, comments, tests, docs, KNOWLEDGE.md files, commit messages, PR and issue text, review and PR comments, resolution summaries — and any report a later step copies into one of those. The ledger is gitignored and numbered per machine, so no other clone can resolve an ID, and numbers get reused.
 
 ### Step 5: Use verbatim IDs only
 
@@ -76,17 +95,17 @@ Cite only IDs that appear verbatim in `DECISIONS_CONTEXT`. Do not guess at IDs t
 
 **Scenario**: Reviewing `src/assets/scripts/hooks/background-learning` for issues.
 
-1. **Scan** — Index shows `PF-004  Background hook god scripts  [Active]  —  src/assets/scripts/hooks/foo.cjs`
+1. **Scan** — Index shows `PF-NNN  Background hook god scripts  [Active]  —  src/assets/scripts/hooks/foo.cjs`
 2. **Identify** — Area field includes `src/assets/scripts/hooks/` which overlaps with the file under review
-3. **Read** — Open the pitfalls file at the path given in the DECISIONS_CONTEXT footer (e.g., `<worktree>/.devflow/learning/pitfalls.md`), find `## PF-004:` section, read full body
-4. **Cite** — If the file shows signs of the god-script pattern, note `avoids PF-004` in reasoning
-5. **Verbatim** — ID `PF-004` appeared in the index; citation is valid
+3. **Read** — Open the pitfalls file at the path given in the DECISIONS_CONTEXT footer (e.g., `<worktree>/.devflow/learning/pitfalls.md`), find `## PF-NNN:` section, read full body
+4. **Cite** — If the file shows signs of the god-script pattern, note `avoids PF-NNN` in reasoning; a comment you commit for the fix says why in words ("hooks stay thin dispatchers"), never the ID
+5. **Verbatim** — ID `PF-NNN` appeared in the index; citation is valid
 
 ---
 
 ## Skip Guard
 
-When `DECISIONS_CONTEXT` is empty, `(none)`, or not provided: skip this skill entirely. Do not attempt to load decisions files independently. Do not speculate about what decisions or pitfalls might exist.
+When `DECISIONS_CONTEXT` is empty, `(none)`, or not provided: skip this skill entirely — unless your agent instructions tell you to read the decisions index yourself, in which case the index you read is your `DECISIONS_CONTEXT`. Do not otherwise load decisions files independently. Do not speculate about what decisions or pitfalls might exist.
 
 ---
 
@@ -98,3 +117,4 @@ When `DECISIONS_CONTEXT` is empty, `(none)`, or not provided: skip this skill en
 | Avoiding a known pitfall | `avoids PF-NNN` |
 | Entry not in index | (no citation — silence is correct) |
 | Entry in index but not read yet | (no citation — read first) |
+| Text that is committed, pushed or posted | (no ID — state the rule in words) |

package/src/assets/skills/docs-framework/SKILL.md

@@ -140,8 +140,8 @@ ensure_docs_dir() { mkdir -p "$(get_docs_root)/.devflow/docs/$1"; }
 | Resolve cmd | `.devflow/docs/reviews/{branch-slug}/{timestamp}/resolution-summary.md` | Written by /resolve orchestrator (Phase 5) |
 | Code-review cmd | `.devflow/docs/reviews/{branch-slug}/.last-review-head` | Overwrites with HEAD SHA |
 | Working Memory | `.devflow/memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
-| Decisions | `.devflow/learning/decisions.md` | Rendered from `decisions-ledger.jsonl` (active ADR-NNN rows; retired rows dropped) |
-| Pitfalls | `.devflow/learning/pitfalls.md` | Rendered from `decisions-ledger.jsonl` (active PF-NNN rows; retired rows dropped) |
+| Decisions | `.devflow/learning/decisions.md` | Rendered from `decisions-ledger.jsonl` (active ADR-NNN entries in full; inactive ones listed in its Inactive table) |
+| Pitfalls | `.devflow/learning/pitfalls.md` | Rendered from `decisions-ledger.jsonl` (active PF-NNN entries in full; inactive ones listed in its Inactive table) |
 | Design agent (via /plan) | `.devflow/docs/design/{ISSUE_ID}-{topic-slug}.{timestamp}.md` | Creates new design artifact |
 | Research agent | `.devflow/docs/research/{topic-slug}/{timestamp}/{type}.md` | Creates new in timestamped dir |
 | Synthesize agent (research) | `.devflow/docs/research/{topic-slug}/{timestamp}/research-summary.md` | Creates new in timestamped dir |

package/src/assets/skills/feature-knowledge/SKILL.md

@@ -117,7 +117,7 @@ updated: {ISO date}
 [Most important files with one-line descriptions]
 
 ## Related
-[Links to ADR/PF entries, other feature knowledge entries, key source files]
+[Links to other feature knowledge entries and key source files — never an ADR/PF ID]
 ```
 
 ### Category Templates
@@ -167,9 +167,10 @@ Bad: `"Integration stuff"`
 
 Knowledge files must not exist in isolation. The **Related** section must link to:
 - Other feature knowledge entries that cover related topics
-- ADR/PF entries from DECISIONS_CONTEXT (if provided)
 - Key source files referenced in the knowledge
 
+A decision or pitfall from DECISIONS_CONTEXT that shapes this area is stated in words in the section it governs, never by its ADR/PF ID: KNOWLEDGE.md is git-tracked and shared with every clone, and ledger IDs resolve only on the machine that recorded them.
+
 References should be bidirectional — when creating a new feature knowledge entry that relates to an existing one, note the connection.
 
 ---
@@ -230,7 +231,7 @@ Run through this before writing. If any check fails, go back and fix it.
 - [ ] File stays under 500 lines (split if necessary)
 
 **Connections:**
-- [ ] Cross-references to related feature knowledge entries and ADR/PF entries in Related section
+- [ ] Cross-references to related feature knowledge entries in Related section; decisions and pitfalls stated in words, with no ADR/PF ID anywhere in the file
 - [ ] No isolated knowledge islands — file connects to the broader knowledge network
 - [ ] Key source files listed in Key Files section
 
@@ -325,8 +326,8 @@ All constants use `SCREAMING_SNAKE_CASE` with a descriptive prefix. If a value c
 
 ## Related
 
-- ADR-003: Lib/command separation principle
-- PF-001: Config drift when constants are scattered
+- `.devflow/features/cli-commands/KNOWLEDGE.md` — the command side of the lib/command split: catching errors and routing them to `showError()`
+- `src/commands/` — where each integration is wired into a command
 ````
 
 ---

package/src/assets/skills/test-driven-development/SKILL.md

@@ -34,6 +34,8 @@ Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define t
 
 ## The Cycle
 
+**Affected tests**: the tests that cover the changed files, selected by the runner's related-test option (Jest's `--findRelatedTests`, Vitest's `related`) or, where the runner has none, the package or path that owns them. Every "run the tests" step below means the affected tests; the full suite belongs to Validate.
+
 ### Step 1: RED — Write a Failing Test
 
 Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
@@ -56,19 +58,19 @@ Don't write code "you'll need later." Write code the test demands NOW.
 Don't optimize. Don't refactor. Don't clean up. Just pass the test.
 ```
 
-**Checkpoint:** All tests pass. If any test fails, fix it before moving on.
+**Checkpoint:** All affected tests pass. If any test fails, fix it before moving on.
 
 ### Step 3: REFACTOR — Improve Without Changing Behavior
 
 Now clean up. Extract helpers, rename variables, simplify logic. Tests stay green throughout.
 
 ```
-Run tests after every refactoring step.
+Run the affected tests after every refactoring step.
 If a test breaks during refactor, undo immediately — you changed behavior.
 Apply DRY, extract patterns, improve readability.
 ```
 
-**Checkpoint:** All tests still pass. Code is clean. Repeat from Step 1 for next behavior.
+**Checkpoint:** All affected tests still pass. Code is clean. Repeat from Step 1 for next behavior.
 
 ---
 
@@ -79,7 +81,7 @@ After each RED-GREEN-REFACTOR cycle, ALL must hold:
 - [ ] Test existed BEFORE production code (not concurrent, not after)
 - [ ] Test failed for the RIGHT reason (expected behavior absent, not syntax/import error)
 - [ ] Production code is minimal — no speculative additions beyond what the test demands
-- [ ] ALL tests pass, not just the new one
+- [ ] ALL affected tests pass, not just the new one
 - [ ] Refactoring happened in Step 3 (or code is already clean — state explicitly)
 - [ ] No untested production code remains
 

package/dist/core/observation-io.js

@@ -1,50 +0,0 @@
-import { promises as fs } from 'fs';
-import * as p from '@clack/prompts';
-import { writeFileAtomicExclusive } from './fs-atomic.js';
-import { loadAndCountObservations } from './observations.js';
-/**
- * @file observation-io.ts
- *
- * File I/O for observations and user-facing warnings.
- * Bridges the pure data module (observations.ts) with the filesystem.
- *
- * The `.md` files are a pure render of the decisions ledger — never edit them
- * directly. To change the status of a decision or pitfall, use the
- * `retire-anchor` op in `json-helper.cjs`, which flips `decisions_status` on
- * the ledger row and re-renders both `.md` files atomically.
- */
-/**
- * Read and parse observations from a log file.
- * Returns empty results if the file does not exist.
- */
-export async function readObservations(logPath) {
-    try {
-        const logContent = await fs.readFile(logPath, 'utf-8');
-        return loadAndCountObservations(logContent);
-    }
-    catch {
-        return { observations: [], invalidCount: 0 };
-    }
-}
-/**
- * Write observations back to a log file atomically.
- * Each observation is serialized as a JSON line. Uses a `.tmp` sibling + rename so
- * concurrent readers (e.g. background-learning during a race) never observe a
- * half-written file. Delegates to `writeFileAtomicExclusive` in fs-atomic.ts
- * (D34/D39: canonical TS atomic-write helper).
- */
-export async function writeObservations(logPath, observations) {
-    const lines = observations.map(o => JSON.stringify(o));
-    const content = lines.join('\n') + (lines.length ? '\n' : '');
-    await writeFileAtomicExclusive(logPath, content);
-}
-/**
- * Warn the user if invalid entries were found in a log file.
- * Invalid entries are cleaned up automatically by the background curation pass.
- */
-export function warnIfInvalid(invalidCount) {
-    if (invalidCount > 0) {
-        p.log.warn(`Note: ${invalidCount} invalid entry(ies) found. They will be cleaned up automatically.`);
-    }
-}
-//# sourceMappingURL=observation-io.js.map