devflow-kit 3.0.1 → 3.1.0

package/src/assets/scripts/hooks/resolve-project-root

@@ -56,10 +56,9 @@ _df_nongit_root() {
 #   DF_LEDGER_ROOT — where the learning ledger and its queue live.
 #
 # D-LEDGER-MAIN-WORKTREE: a linked worktree (`git worktree add`, `claude
-# --worktree`) has its own toplevel, so a ledger anchored there restarts at
-# ADR-001 — main's decisions are invisible in it, and the IDs it mints collide
-# with main's (in a repo whose collision guard refuses, the Learning agent stops
-# for good). The ledger is one per REPOSITORY, not per checkout: DF_LEDGER_ROOT
+# --worktree`) has its own toplevel, so a ledger anchored there restarts its
+# numbering at 001 — main's decisions are invisible in it, and the IDs it mints collide
+# with main's. The ledger is one per REPOSITORY, not per checkout: DF_LEDGER_ROOT
 # is the main worktree — the parent of `--git-common-dir` — when that common dir
 # is a `<dir>/.git` directory AND `<dir>/.devflow` already exists; otherwise it is
 # DF_ROOT. The existence test keeps a main checkout that never ran devflow from

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

@@ -8,7 +8,8 @@
 # not the home directory (D-HOOKS-GIT-ONLY), and they read the learning ledger of
 # the main worktree when this is a linked one (D-LEDGER-MAIN-WORKTREE).
 #
-# Section 1: Project decisions TL;DR (decisions.md / pitfalls.md header lines).
+# Section 1: Project decisions TL;DR (decisions.md / pitfalls.md header lines),
+# then the path of the decisions index when it lists entries.
 # Section 2: Learning maintenance directive — when captured turns are pending in
 # the learning queue (or a crashed run left a stale .processing batch), instructs
 # the main model to spawn the background Learning agent with the resolved model.
@@ -85,7 +86,7 @@ fi
 # Ensure the project root .gitignore ignores .devflow/ wholesale. This runs on every
 # git-project session regardless of feature toggles, so memory-off projects
 # (learning/knowledge only) still get .devflow/ ignored — this is the
-# memory-independent path that fixes the gitignore/memory coupling (PF-014). Single
+# memory-independent path that fixes the gitignore/memory coupling. Single
 # source of truth: ensure-root-gitignore. Soft-fail: a gitignore write must never
 # block context injection. Marker keeps it O(1).
 [ -n "$PROJECT_OK" ] && [ -d "$PROJECT_ROOT" ] && [ -f "$SCRIPT_DIR/ensure-root-gitignore" ] && source "$SCRIPT_DIR/ensure-root-gitignore" "$PROJECT_ROOT" || true
@@ -101,7 +102,8 @@ TRACKER_DEVFLOW_DIR="$HOME/.devflow"
 #
 # Section 2 embeds $LEDGER_ROOT; Section 3 embeds $PROJECT_ROOT and
 # $TRACKER_DEVFLOW_DIR — each inside a double-quoted `prompt: "..."` string the
-# model reads out of additionalContext. The provider and model TOKENS in those
+# model reads out of additionalContext. Section 1's index line embeds
+# $LEDGER_ROOT too, as the path the model reads the decisions index from. The provider and model TOKENS in those
 # directives are admitted by positive allowlists, and so are these: the gate is the
 # POSITIVE shape ^[A-Za-z0-9/._+-]+$, expressed as "rejects if any character falls
 # outside it".
@@ -134,16 +136,16 @@ TRACKER_DEVFLOW_DIR="$HOME/.devflow"
 # admitted set is locale-dependent, and no rule here rests on it.
 #
 # Checked ONCE, here, where every value is resolved and above every section that
-# interpolates them, so no sink can embed a value no gate saw (PF-023 — the
+# interpolates them, so no sink can embed a value no gate saw (the
 # invariant belongs at the convergence point all callers pass through, not in
 # whichever section someone remembered). `case` is a shell builtin, so the GitHub
 # path still forks zero times [DR-10]. The empty arm is explicit: an unset root
 # must not read as "no forbidden character, therefore safe".
 #
 # ONE gate per VALUE, applied to the root each section embeds, not one over their
-# concatenation. Section 2 interpolates $LEDGER_ROOT alone — the main worktree's
-# root in a linked worktree (D-LEDGER-MAIN-WORKTREE), so it is the value checked
-# for that section, not the checkout's own; only Section 3 interpolates
+# concatenation. Sections 1 and 2 interpolate $LEDGER_ROOT alone — the main
+# worktree's root in a linked worktree (D-LEDGER-MAIN-WORKTREE), so it is the value
+# checked for them, not the checkout's own; only Section 3 interpolates
 # $PROJECT_ROOT and $TRACKER_DEVFLOW_DIR. Gating values jointly made a rejected
 # ~/.devflow shape suppress the Learning directive as well — a value Section 2
 # never embeds, silently disabling the whole learning pipeline for any machine
@@ -211,10 +213,27 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
         fi
       fi
     done
-    if [ -n "$DECISIONS_TLDR" ]; then
-      dbg "Decisions TL;DR found"
-      DECISIONS_SECTION="--- PROJECT DECISIONS (TL;DR) ---
+    # The index line names the decisions index, so the main model can pass it on
+    # as DECISIONS_CONTEXT. It interpolates $LEDGER_ROOT, so it needs that root's
+    # shape gate, and it is left out when the index lists no entry: an empty
+    # corpus renders `(none)`. Builtins only — no fork on any path.
+    _SC_INDEX="$LEARNING_DIR/index.md"; DECISIONS_INDEX_LINE=""
+    if [ -n "$DIRECTIVE_LEDGER_SAFE" ] && [ -s "$_SC_INDEX" ]; then
+      _SC_IDX1=""; IFS= read -r _SC_IDX1 < "$_SC_INDEX" || true
+      [ "$_SC_IDX1" != "(none)" ] && DECISIONS_INDEX_LINE="Index: $_SC_INDEX"
+    fi
+    if [ -n "$DECISIONS_TLDR" ] || [ -n "$DECISIONS_INDEX_LINE" ]; then
+      dbg "Decisions TL;DR or index found"
+      DECISIONS_SECTION="--- PROJECT DECISIONS (TL;DR) ---"
+      if [ -n "$DECISIONS_TLDR" ]; then
+        DECISIONS_SECTION="${DECISIONS_SECTION}
 $(printf '%b' "$DECISIONS_TLDR")"
+      fi
+      # The index line goes last.
+      if [ -n "$DECISIONS_INDEX_LINE" ]; then
+        DECISIONS_SECTION="${DECISIONS_SECTION}
+${DECISIONS_INDEX_LINE}"
+      fi
       if [ -n "$CONTEXT" ]; then
         CONTEXT="${CONTEXT}
 
@@ -227,11 +246,14 @@ ${DECISIONS_SECTION}"
 fi
 
 # --- Section 2: Learning maintenance directive ---
-# Emitted when captured turns are waiting: queue non-empty, or a leftover
-# .processing batch whose owner crashed (stale mtime, 900s threshold — same
-# family the Learning agent itself uses to discriminate live from crashed). A
-# FRESH .processing means a live Learning agent already owns the batch, so the
-# directive is suppressed even if new turns queued since its claim.
+# Emitted when captured turns are waiting: the queue is non-empty, or a
+# .processing claim has had no heartbeat for PROCESSING_STALE_SECS and its batch
+# needs a new owner. A FRESH .processing means a live Learning agent holds the
+# claim, so the directive is suppressed even if new turns queued since. This
+# check is advisory and decides only whether to spawn: the claim itself is taken
+# by json-helper's claim-queue op under the learning lock, which applies the same
+# threshold (D-OWNED-CLAIM, lib/learning-store.cjs), so a spawn that loses a race
+# exits on `busy`.
 if [ "$LEARNING_ENABLED" = "true" ]; then
   QUEUE_FILE="$LEARNING_DIR/.pending-turns.jsonl"
   PROCESSING_FILE="$LEARNING_DIR/.pending-turns.processing"
@@ -440,8 +462,8 @@ if [ -n "$TRACKER_PROVIDER" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
   tracker_gates_open() {
     # Gate 1 — the attempt cap. Read with the `read` builtin: no fork.
     #
-    # The counter's shape is ONE decimal integer line and nothing else (PF-062 —
-    # document the shape of any file that gates an action, and keep absent and
+    # The counter's shape is ONE decimal integer line and nothing else
+    # (document the shape of any file that gates an action, and keep absent and
     # malformed distinct from a value). Absent means "no attempt yet" = 0.
     # Malformed self-heals to 0 and is overwritten with a well-formed count on
     # emission below, so a stray byte can never recur: refusing forever would
@@ -571,7 +593,7 @@ if [ -n "$TRACKER_PROVIDER" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
     # allowlisted tokens. Decided once at the top of the file, where both values are
     # resolved; consulted here because this is one of the two sinks that interpolate
     # them, and a control stated once for the file is not a control at a sink that
-    # never consults it (PF-023). The third path, the conventions file, is composed
+    # never consults it. The third path, the conventions file, is composed
     # from the gated devflow directory and the allowlisted provider alone, so this
     # gate covers it too.
     if [ -z "$DIRECTIVE_PATHS_SAFE" ]; 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/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