devflow-kit 3.2.0 → 3.3.0

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

@@ -2,7 +2,9 @@
 
 # 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 5.5) →
+# 120s throttle expires. Drains .pending-turns.jsonl → calls `claude -p` on the model
+# and effort the `agents.memory` entry of ~/.devflow/agent-models.json names, else the
+# shipped worker default, in a lean session (D-MEMORY-WORKER-LEAN) →
 # rewrites WORKING-MEMORY.md with a git-reconciliation stamp on line 1.
 #
 # Applies the LLM-vs-plumbing principle: artifact content (WORKING-MEMORY.md) is
@@ -118,6 +120,92 @@ if ! df_no_symlink_below "$PROJECT_ROOT" "$LOCK_DIR" "$QUEUE_FILE" "$PROCESSING_
   exit 0
 fi
 
+# --- CLI version probe: choose the argv form (D-MEMORY-WORKER-LEAN) ---
+# The lean argv (--effort, --safe-mode, --max-turns, ...) is verified from
+# MEMORY_MIN_CLAUDE_VERSION up. A CLI older than that, or one whose version cannot be
+# read, gets the legacy argv instead, because one flag a CLI does not know fails every
+# run. The probe runs here, once $CLAUDE_BIN has resolved and the link check has
+# passed, and before the lock is taken, so a slow or hung `--version` can never extend
+# the lock's hold. It is bounded by DEVFLOW_BG_VERSION_PROBE_SECS (default 10, at most
+# 60; tests override it as they do DEVFLOW_BG_WATCHDOG_SECS) with the watchdog's
+# background-and-kill idiom. Its output is parsed, never executed.
+#
+# Errexit safety: the worker runs under `set -e`, and a helper's last non-zero status
+# aborts the caller, so each helper below ends in an explicit return status and is
+# called inside an `if` condition.
+MEMORY_MIN_CLAUDE_VERSION="2.1.286"
+
+# Sets CLAUDE_VERSION_TEXT to the first 512 bytes `claude --version` printed ("" on any
+# failure). Returns 0 when it exited 0 inside the bound, else 1. A hung probe gets
+# SIGTERM to its own process group (set -m, as for the spawn below) after the bound
+# and SIGKILL 2s later; the watchdog subshell has its descriptors closed so a sleep it
+# leaves behind holds no pipe open.
+probe_claude_version() {
+  local _secs _out _pid _wd_pid _status=1
+  CLAUDE_VERSION_TEXT=""
+  _secs="${DEVFLOW_BG_VERSION_PROBE_SECS:-10}"
+  case "$_secs" in
+    ''|*[!0123456789]*|????*) _secs=10 ;;
+  esac
+  if [ "$_secs" -lt 1 ] || [ "$_secs" -gt 60 ]; then _secs=10; fi
+  _out=$(mktemp "${TMPDIR:-/tmp}/devflow-claude-version.XXXXXX" 2>/dev/null) || return 1
+  set -m
+  "$CLAUDE_BIN" --version </dev/null >"$_out" 2>/dev/null &
+  _pid=$!
+  set +m
+  (
+    sleep "$_secs"
+    kill -TERM -"$_pid" 2>/dev/null || true
+    sleep 2
+    kill -KILL -"$_pid" 2>/dev/null || true
+  ) </dev/null >/dev/null 2>&1 &
+  _wd_pid=$!
+  if wait "$_pid" 2>/dev/null; then _status=0; fi
+  kill "$_wd_pid" 2>/dev/null || true
+  wait "$_wd_pid" 2>/dev/null || true
+  if [ "$_status" -eq 0 ]; then
+    CLAUDE_VERSION_TEXT=$(head -c 512 "$_out" 2>/dev/null || true)
+  fi
+  rm -f "$_out" 2>/dev/null || true
+  return "$_status"
+}
+
+# Returns 0 when the first X.Y.Z in $1 is at or above the first X.Y.Z in $2, comparing
+# the three components as base-10 numbers left to right (2.10.0 is above 2.1.286, and
+# a leading zero is not octal). Returns 1 when it is below, or when either text holds
+# no X.Y.Z or a component longer than six digits. The digit set is spelled out: a
+# range such as 0-9 collates by locale on bash 3.2.
+claude_version_at_least() {
+  local _text="$1" _floor="$2" _re='([0123456789]+)\.([0123456789]+)\.([0123456789]+)'
+  local _f1 _f2 _f3 _v1 _v2 _v3
+  [[ "$_floor" =~ $_re ]] || return 1
+  _f1=${BASH_REMATCH[1]}; _f2=${BASH_REMATCH[2]}; _f3=${BASH_REMATCH[3]}
+  [[ "$_text" =~ $_re ]] || return 1
+  _v1=${BASH_REMATCH[1]}; _v2=${BASH_REMATCH[2]}; _v3=${BASH_REMATCH[3]}
+  if [ "${#_v1}" -gt 6 ] || [ "${#_v2}" -gt 6 ] || [ "${#_v3}" -gt 6 ]; then return 1; fi
+  _v1=$((10#$_v1)); _v2=$((10#$_v2)); _v3=$((10#$_v3))
+  _f1=$((10#$_f1)); _f2=$((10#$_f2)); _f3=$((10#$_f3))
+  if [ "$_v1" -ne "$_f1" ]; then
+    if [ "$_v1" -gt "$_f1" ]; then return 0; fi
+    return 1
+  fi
+  if [ "$_v2" -ne "$_f2" ]; then
+    if [ "$_v2" -gt "$_f2" ]; then return 0; fi
+    return 1
+  fi
+  if [ "$_v3" -ge "$_f3" ]; then return 0; fi
+  return 1
+}
+
+CLAUDE_ARGV_FORM="legacy"
+if ! probe_claude_version; then
+  log "claude --version probe failed or timed out — using the legacy argv"
+elif claude_version_at_least "$CLAUDE_VERSION_TEXT" "$MEMORY_MIN_CLAUDE_VERSION"; then
+  CLAUDE_ARGV_FORM="lean"
+else
+  log "claude --version is below ${MEMORY_MIN_CLAUDE_VERSION} or unparseable — using the legacy argv"
+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.
@@ -171,7 +259,20 @@ 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 (D-MEMORY-STAGED-CAS).
+#
+# D-MEMORY-WORKER-LEAN: the removal is also a CHECKED precondition. The model gets the
+# Write tool alone, and Write refuses a file that exists and has not been read, which
+# is how an earlier Write-only worker failed silently: every Write errored while the
+# run exited 0. Once nothing stands at the staged path, the one Write is always a
+# create, so Write-only is safe. A path `rm -f` cannot clear (a directory, say) would
+# make every Write fail, so the run stops here instead: no LLM call, the batch and
+# the queue untouched (nothing has been claimed yet), the lock released by the EXIT
+# trap. `-e` or `-L`, so a link there counts as present.
 rm -f "$STAGED_FILE" 2>/dev/null || true
+if [ -e "$STAGED_FILE" ] || [ -L "$STAGED_FILE" ]; then
+  log "SKIP: $STAGED_FILE could not be removed — a Write to it would fail, so no LLM run; the batch and the queue are left as they are"
+  exit 0
+fi
 
 # --- Orphan-only skip: if queue has no assistant/qa turn, exit and leave the queue ---
 # This prevents fabrication-prone LLM runs with only user turns in the queue.
@@ -500,7 +601,107 @@ Instructions:
 EOF
 )
 
-log "Spawning claude -p (model claude-sonnet-5-5, ${TURN_COUNT} turns)"
+# --- Model and effort (D-MEMORY-WORKER-LEAN) ---
+# One authority: WORKER_AGENTS.memory in src/core/agent-models.ts, which `devflow
+# agents` shows as the worker's default. The two defaults below are that row spelled
+# out for bash, held equal to it by tests/agent-models-worker.test.ts, as are the
+# alias and effort lists and the name rules. A personal `agents.memory` entry in
+# $HOME/.devflow/agent-models.json (the machine root; nothing relocates it) overrides
+# them. Each field is validated on its own against the worker domain, so a bad model
+# keeps a good effort and the reverse:
+#   model  = `default` (the shipped one), one of the aliases, or a `claude-` name;
+#            a name starts with a letter or digit, continues with those and . _ -,
+#            and is 64 characters at most (MODEL_NAME_RE in src/core/agent-frontmatter.ts)
+#   effort = `default` (the shipped one) or one of the levels
+# `inherit` is outside both, since a background worker has no session to inherit from.
+# Only a value that passed its match reaches argv. A value that is absent, empty or
+# not a JSON string reads as absent and takes the shipped one silently; a string that
+# fails its match takes it with one log line naming the field, never the value.
+# The character sets are spelled out because a range such as A-Za-z matches accented
+# letters in a UTF-8 locale on bash 3.2.
+MEMORY_MODEL_DEFAULT="claude-sonnet-5-5"
+MEMORY_EFFORT_DEFAULT="high"
+MEMORY_MODEL_ALIASES="haiku sonnet opus fable"
+MEMORY_MODEL_PREFIX="claude-"
+MEMORY_MODEL_MAX_LEN=64
+MEMORY_EFFORT_LEVELS="low medium high xhigh max"
+MEMORY_NAME_HEAD="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+MEMORY_EFFORT_CHARS="abcdefghijklmnopqrstuvwxyz"
+
+# Prints the string value of agents.memory.<field> followed by one `x` (the caller strips
+# it, so a value's own trailing newline survives the command substitution). Prints just
+# the `x` when the file, the field or a string there is missing. Always returns 0.
+memory_agent_field() {
+  local _file="$HOME/.devflow/agent-models.json"
+  if [ "$_JSON_AVAILABLE" = "true" ] && [ -f "$_file" ]; then
+    json_string_field_file "$_file" "agents.memory.$1" 2>/dev/null || true
+  fi
+  printf x
+  return 0
+}
+
+# Sets MEMORY_MODEL. Always returns 0.
+resolve_memory_model() {
+  local _raw _tail="${MEMORY_NAME_HEAD}._-" _ok=""
+  MEMORY_MODEL="$MEMORY_MODEL_DEFAULT"
+  _raw=$(memory_agent_field model)
+  _raw=${_raw%x}
+  case "$_raw" in
+    ''|default) return 0 ;;
+    [!$MEMORY_NAME_HEAD]*|*[!$_tail]*) ;;
+    *)
+      if [ "${#_raw}" -le "$MEMORY_MODEL_MAX_LEN" ]; then
+        case " $MEMORY_MODEL_ALIASES " in
+          *" $_raw "*) _ok="yes" ;;
+        esac
+        case "$_raw" in
+          "$MEMORY_MODEL_PREFIX"?*) _ok="yes" ;;
+        esac
+      fi
+      ;;
+  esac
+  if [ -n "$_ok" ]; then
+    MEMORY_MODEL="$_raw"
+  else
+    log "agents.memory.model: not a model the worker accepts (default, an alias or a ${MEMORY_MODEL_PREFIX} name) — using the shipped model"
+  fi
+  return 0
+}
+
+# Sets MEMORY_EFFORT. Always returns 0.
+resolve_memory_effort() {
+  local _raw _ok=""
+  MEMORY_EFFORT="$MEMORY_EFFORT_DEFAULT"
+  _raw=$(memory_agent_field effort)
+  _raw=${_raw%x}
+  case "$_raw" in
+    ''|default) return 0 ;;
+    *[!$MEMORY_EFFORT_CHARS]*) ;;
+    *)
+      case " $MEMORY_EFFORT_LEVELS " in
+        *" $_raw "*) _ok="yes" ;;
+      esac
+      ;;
+  esac
+  if [ -n "$_ok" ]; then
+    MEMORY_EFFORT="$_raw"
+  else
+    log "agents.memory.effort: not an effort level the worker accepts (default or a level) — using the shipped effort"
+  fi
+  return 0
+}
+
+resolve_memory_model
+resolve_memory_effort
+
+if [ "$CLAUDE_ARGV_FORM" = "lean" ]; then
+  EFFORT_LOG="effort ${MEMORY_EFFORT}"
+  ARGV_LOG="lean argv"
+else
+  EFFORT_LOG="no effort passed"
+  ARGV_LOG="legacy argv"
+fi
+log "Spawning claude -p (model ${MEMORY_MODEL}, ${EFFORT_LOG}, ${ARGV_LOG}, ${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) ---
@@ -537,14 +738,94 @@ fi
 # Restore set +m immediately after capturing CLAUDE_PID so the watchdog subshell and
 # other subsequent background operations stay in the worker's group.
 # Job-control notifications go to stderr which is redirected to the log — suppress them.
+#
+# D-MEMORY-WORKER-LEAN — the spawn. The worker opens a headless session to make one
+# Write, so the session is cut to what that Write needs. Prompt on stdin, output and
+# errors to the log, as before. Two argv forms, chosen by the version probe above:
+#
+#   lean (CLI at or above MEMORY_MIN_CLAUDE_VERSION):
+#     -p --model M --effort E --safe-mode --tools Write --disable-slash-commands \
+#     --strict-mcp-config --mcp-config '{"mcpServers":{}}' --max-turns 3 \
+#     --dangerously-skip-permissions --output-format text
+#   legacy (older, unreadable or timed-out probe):
+#     -p --model M --tools Write --dangerously-skip-permissions --output-format text
+#
+# What each flag is for:
+#   --model, --effort  the resolved agents.memory values above. --effort is the only
+#                      effort source: an inherited CLAUDE_CODE_EFFORT_LEVEL beats the
+#                      flag (measured on 2026-10-09), so it is unset below, for both
+#                      forms, and the log's "no effort passed" is then true.
+#   --safe-mode        starts with the user's customisations off: instruction files,
+#                      skills, plugins, hooks, MCP servers, custom commands and agents.
+#                      Auth, model selection and built-in tools work as usual, and
+#                      settings `env` (the provider URL and key) still applies under
+#                      it (measured on 2026-10-09), so a routed or keyed install works.
+#   --tools Write      Write is the only tool. `--allowedTools` only pre-approves, it
+#                      leaves every tool, listing and MCP server loaded.
+#   --disable-slash-commands, --strict-mcp-config with an empty --mcp-config
+#                      no slash-command or skill listing, no MCP server and none of the
+#                      instructions they add to the context.
+#   --max-turns 3      the worker's own pattern is one Write and then the end of the
+#                      turn, two requests; the third is margin. A run that reaches the
+#                      cap exits non-zero, so its batch stays for the retry; the Write
+#                      on the capped turn still runs. 3 was verified on claude 2.1.294
+#                      on 2026-10-09 (cap 1 exits 1, caps 2 and 3 exit 0 on that
+#                      pattern). `--max-turns` is not listed in `claude --help` there
+#                      but is registered (`--max-turns abc` errors "must be a number"),
+#                      which is why it was exercised rather than read off the help.
+#   --dangerously-skip-permissions  headless: nothing could answer a prompt.
+#   --output-format text
+#   DEVFLOW_BG_UPDATER=1  the recursion guard stays on both forms, though --safe-mode
+#                      also disables hooks. CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 and
+#                      CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 keep the instruction files and
+#                      auto-memory out on both forms, including the legacy one.
+#
+# Why Write-only is safe: the staged path is empty before every run (the removal and
+# the checked precondition after the lock above), so the one Write is always a create.
+# Write refuses an existing file that has not been read, and that is the whole history
+# of this flag set:
+#   a472a490  passed `--tools "Write"` with `--allowedTools` for two memory files;
+#   e701cecc  widened the tools to `Read,Write,Bash` after counting the silent
+#             read-before-write failures (the run exited 0 while every Write errored);
+#   baf02265  removed both flags, with no reason in its message;
+#   6186645f  raised the worker's model and kept `--allowedTools 'Read,Write'`.
+#
+# The version floor is 2.1.286, the lowest CLI on which the whole lean argv was run
+# and its flags, the settings `env` under --safe-mode and the effort override were
+# checked (2.1.286 and 2.1.292 to 2.1.294 behave identically; 2026-10-09, recorded in
+# docs/reference/platform-assumptions.md). The legacy form carries no --effort,
+# --safe-mode, --max-turns, --disable-slash-commands, --strict-mcp-config or
+# --mcp-config, none of which is verified on older CLIs, so on it effort is not
+# applied, MCP servers stay loaded and there is no turn cap.
+#
+# The turns input has no byte cap: the queue holds every turn whole by design, and the
+# prompt is bounded by the newest-20-rows window above and the 64 KB existing-memory
+# cap, not by cutting a turn.
+unset CLAUDE_CODE_EFFORT_LEVEL
 set -m
-DEVFLOW_BG_UPDATER=1 "$CLAUDE_BIN" -p \
-  --model claude-sonnet-5-5 \
-  --dangerously-skip-permissions \
-  --allowedTools 'Read,Write' \
-  --output-format text \
-  <<< "$PROMPT" \
-  >> "$LOG_FILE" 2>&1 &
+if [ "$CLAUDE_ARGV_FORM" = "lean" ]; then
+  DEVFLOW_BG_UPDATER=1 CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 "$CLAUDE_BIN" -p \
+    --model "$MEMORY_MODEL" \
+    --effort "$MEMORY_EFFORT" \
+    --safe-mode \
+    --tools Write \
+    --disable-slash-commands \
+    --strict-mcp-config \
+    --mcp-config '{"mcpServers":{}}' \
+    --max-turns 3 \
+    --dangerously-skip-permissions \
+    --output-format text \
+    <<< "$PROMPT" \
+    >> "$LOG_FILE" 2>&1 &
+else
+  DEVFLOW_BG_UPDATER=1 CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 "$CLAUDE_BIN" -p \
+    --model "$MEMORY_MODEL" \
+    --tools Write \
+    --dangerously-skip-permissions \
+    --output-format text \
+    <<< "$PROMPT" \
+    >> "$LOG_FILE" 2>&1 &
+fi
 CLAUDE_PID=$!
 set +m
 

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

@@ -113,12 +113,28 @@ const FULL_SHA_RE = /^[0-9a-f]{40}$/;
 const KEY_RE = /^[A-Z][A-Z0-9_]{1,9}$/;
 
 /**
- * Step 3a's closing-keyword regex, byte-for-byte the literal the built
- * `gather-release-evidence` references state, applied case-insensitively WITHOUT
- * the `u` flag — so a non-ASCII letter (`ſ`, the Kelvin sign) never folds onto an
- * ASCII keyword letter. A parity test pins `.source` and `.flags` to the built text.
+ * D-TRACE-KEYWORDS: two keyword sets, deliberately unequal, because they answer
+ * two different questions.
+ *
+ * CLOSING_KEYWORD_RE is step 3a's closing-keyword regex, byte-for-byte the literal
+ * the built `gather-release-evidence` references state: a commit that carries one
+ * of these keywords ships the issue it names. `Refs #N` only mentions an issue, so
+ * `refs` is not a closing keyword and the prompt never lets such a commit reach
+ * SHIPPED_ISSUES. The script itself classifies with TRACE_KEYWORD_RE; this regex
+ * is exported so a parity test can pin the prompt's rule to a literal.
+ *
+ * TRACE_KEYWORD_RE is the closing set plus `refs`. The trace map asks the weaker
+ * question "does this commit name an issue at all?", and a `Refs #N` commit does,
+ * so it is `traced` and not `untraced`. Narrowing the closing set must not turn
+ * those commits into traceability gaps in the release confirm.
+ *
+ * Both apply case-insensitively WITHOUT the `u` flag — so a non-ASCII letter
+ * (`ſ`, the Kelvin sign) never folds onto an ASCII keyword letter. A parity test
+ * pins CLOSING_KEYWORD_RE's `.source` and `.flags` to the built text, and
+ * TRACE_KEYWORD_RE to the closing set plus `refs`.
  */
-const KEYWORD_RE = /^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?|refs):?$/i;
+const CLOSING_KEYWORD_RE = /^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?):?$/i;
+const TRACE_KEYWORD_RE = /^\(?(close[sd]?|fix(e[sd])?|resolve[sd]?|refs):?$/i;
 
 /** Step 3a's trailing-strip class, byte-for-byte the built literal (parity-pinned). */
 const TRAILING_CLASS = '[.,;:)\\]!?]';
@@ -377,11 +393,11 @@ function gateCandidate(candidate, grammar, key) {
 
 /**
  * Step 3a, executed, then the grammar's gate: the first reference `message`
- * yields, or null. Per line, a whitespace token matching KEYWORD_RE opens a run:
- * the next token, plus each further token while the previous one ends in `,`.
+ * yields, or null. Per line, a whitespace token matching TRACE_KEYWORD_RE opens a
+ * run: the next token, plus each further token while the previous one ends in `,`.
  * Each run token splits on `,`, is stripped, and non-empty parts are gated.
  *
- * Linear in the message: a keyword token never ends in `,` (KEYWORD_RE is
+ * Linear in the message: a keyword token never ends in `,` (TRACE_KEYWORD_RE is
  * anchored), so every comma run is walked by at most the one keyword before it.
  *
  * @param {string} message
@@ -393,7 +409,7 @@ function findReference(message, grammar, key) {
   for (const line of message.split('\n')) {
     const tokens = line.split(/\s+/).filter(t => t !== '');
     for (let i = 0; i < tokens.length; i++) {
-      if (!KEYWORD_RE.test(tokens[i])) continue;
+      if (!TRACE_KEYWORD_RE.test(tokens[i])) continue;
       for (let j = i + 1; j < tokens.length; j++) {
         for (const part of tokens[j].split(',')) {
           const stripped = stripCandidate(part);
@@ -1117,7 +1133,8 @@ module.exports = Object.freeze({
   EXIT_CODES,
   LIMITS,
   RELEASE_TAG_RE,
-  KEYWORD_RE,
+  CLOSING_KEYWORD_RE,
+  TRACE_KEYWORD_RE,
   TRAILING_CLASS,
   GRAMMARS,
   GRAMMAR_RULES,

package/src/assets/skills/accessibility/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: accessibility
-description: This skill should be used when the user asks to "add accessibility", "check ARIA", "handle keyboard navigation", "add focus management", or creates UI components, forms, or interactive elements. Provides WCAG 2.2 AA patterns for keyboard navigation, ARIA roles and states, focus management, color contrast, and screen reader support.
+description: This skill should be used when the user asks to "add accessibility", "check ARIA", "handle keyboard navigation", or creates UI components, forms, or interactive elements.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 activation:

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

@@ -1,14 +1,12 @@
 ---
 name: apply-decisions
-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.
+description: Consume the DECISIONS_CONTEXT index; cite IDs in-session only
 user-invocable: false
-allowed-tools: Read
+allowed-tools: Read, Bash
 ---
 
 # Apply Decisions
 
-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
 
 > **VERBATIM IDs ONLY — NEVER FABRICATE**
@@ -17,104 +15,36 @@ Canonical consumer algorithm for the `DECISIONS_CONTEXT` index passed by orchest
 > in the index, do not cite it. If an entry looks relevant but you haven't Read its
 > full body, do not cite it. Fabricated citations are worse than no citations.
 
----
-
 ## 5-Step Algorithm
 
 ### Step 1: Scan the index
 
-Read through all entries in `DECISIONS_CONTEXT`. The index lists active entries only, in two line kinds:
-
-```
-Decisions (N):
-  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-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.
+One line per active entry: its ID (`ADR-NNN` or `PF-NNN`), a title, then a status tag and/or, after `—`, its area or scope. The footer names the decisions and pitfalls files.
 
 ### Step 2: Identify plausibly-relevant entries
 
-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
-
-A v1 title may be cut short — if a truncated title looks relevant, proceed to Step 3.
+Pick entries whose title, area or scope overlaps the files you touch (a matching scope glob is a strong signal), the kind of issue or the architectural area. Follow up a cut-short title that looks relevant.
 
 ### 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:
+Find the entry's heading line in the file the footer names, then Read only that section:
 
+```bash
+command grep -nF '## ADR-NNN:' "{worktree-from-footer}/.devflow/learning/decisions.md"
 ```
-## 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.
-
-```
-Use the exact paths from the DECISIONS_CONTEXT footer, e.g.:
-  {worktree-from-footer}/.devflow/learning/decisions.md   → find ## ADR-NNN: heading
-  {worktree-from-footer}/.devflow/learning/pitfalls.md    → find ## PF-NNN: heading
-```
-
-Only cite an entry after you have read its full body and confirmed it applies.
+For a pitfall use `## PF-NNN:` and `pitfalls.md`. Read with `offset` at the printed line and a `limit` of about 25, stopping at the next `## `. The footer is the single source of truth for paths; the ledger is git-ignored, so only a shell search finds the line. A `verified` date is when the entry was last confirmed true; none means unconfirmed. Cite only after reading the body and confirming it applies.
 
 ### 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.
+Cite `applies ADR-NNN` or `avoids PF-NNN` in-session only: your reasoning, prompts to downstream agents, your report back.
 
-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.
+Anything committed, pushed or posted states the rule in words, never its ID (code, comments, tests, docs, commit messages, PR and issue text, review comments, and any report copied into those). IDs are numbered per machine, so no other clone can resolve one.
 
 ### Step 5: Use verbatim IDs only
 
-Cite only IDs that appear verbatim in `DECISIONS_CONTEXT`. Do not guess at IDs that might exist. Do not construct IDs from memory. If no entry is clearly relevant, skip citation entirely — silence is correct when nothing applies.
-
----
-
-## Worked Example
-
-**Scenario**: Reviewing `src/assets/scripts/hooks/background-learning` for issues.
-
-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-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
-
----
+Cite only IDs in `DECISIONS_CONTEXT`; never guess or rebuild one. When nothing clearly applies, cite nothing.
 
 ## Skip Guard
 
-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.
-
----
-
-## Citation Format Reference
-
-| Situation | Citation |
-|-----------|----------|
-| Applying a prior architectural decision | `applies ADR-NNN` |
-| 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) |
+When `DECISIONS_CONTEXT` is empty, `(none)` or not provided, skip this skill — unless your instructions tell you to read the decisions index yourself; that index is then your `DECISIONS_CONTEXT`. Never load decisions files otherwise.

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

@@ -1,6 +1,6 @@
 ---
 name: apply-feature-knowledge
-description: Consumption algorithm for FEATURE_KNOWLEDGE variable — pre-computed feature context
+description: Consume FEATURE_KNOWLEDGE, the pre-computed feature context
 user-invocable: false
 allowed-tools: Read
 ---
@@ -11,37 +11,17 @@ allowed-tools: Read
 
 > **Pre-computed context, not a cage. Verify against current code — always.**
 >
-> A feature knowledge captures patterns AS THEY WERE when last written. Code evolves.
-> Use the feature knowledge as a starting point, not gospel truth. When something feels
-> off, Read the actual files. Code is authoritative; feature knowledge is supplementary.
+> A feature knowledge captures patterns AS THEY WERE when last written. Use it as a
+> starting point, not gospel truth; when something feels off, Read the actual files.
+> Code is authoritative.
 
 ---
 
 ## 3-Step Algorithm
 
-### Step 1: Read the Feature Knowledge
-
-When `FEATURE_KNOWLEDGE` is provided and is not `(none)`:
-
-1. Read each feature knowledge section (separated by `--- Feature knowledge: {slug} ---` headers)
-2. Absorb: architecture, data flow, key patterns, anti-patterns, gotchas
-3. Note integration points that relate to your current task
-
-### Step 2: Apply to Current Task
-
-1. **Patterns as defaults**: Follow documented patterns unless you have a specific reason not to
-2. **Anti-patterns as warnings**: Check your work against documented anti-patterns
-3. **Gotchas as checklists**: Verify each gotcha doesn't apply to your changes
-4. **Integration points**: Ensure your changes respect documented boundaries
-5. **Key files**: Use as starting points for exploration
-
-### Step 3: Verify Against Current Code
-
-The feature knowledge may not reflect recent changes:
-- If the feature knowledge doesn't address your specific area, explore further
-- **When an assertion seems outdated**: Read the relevant source files to confirm — code wins
-- When you find a contradiction between the KB and actual code, trust the code
-- Note discrepancies in your output when they matter for the task
+1. **Read** each section of `FEATURE_KNOWLEDGE` (headed `--- Feature knowledge: {slug} ---`) for architecture, data flow, patterns, anti-patterns, gotchas and the integration points your task touches.
+2. **Apply** it: follow documented patterns unless you have a specific reason not to; check your work against each anti-pattern and gotcha; respect documented integration boundaries; start exploring from the key files.
+3. **Verify** against current code: it may not reflect recent changes. Where it is silent on your area, explore further. Where an assertion seems outdated or contradicts the code, Read the source and trust it. Note a discrepancy in your output when it matters for the task.
 
 ---
 
@@ -52,18 +32,4 @@ Do not mention feature knowledge or its absence in your output.
 
 ## Freshness Model
 
-Feature knowledge uses **write-through + verify-on-read** for freshness:
-- KBs are written at the point a documented area changes (not on a background schedule)
-- Readers verify key assertions against current code rather than relying on staleness markers
-- When in doubt, Read the file — that resolves any uncertainty immediately
-
-## Concatenation Format
-
-Multiple feature knowledge entries are concatenated with slug headers:
-```
---- Feature knowledge: payments ---
-[full KNOWLEDGE.md content]
-
---- Feature knowledge: auth ---
-[full KNOWLEDGE.md content]
-```
+Feature knowledge is **verify-on-read**: check key assertions against current code, not staleness markers, and when in doubt Read the file.

package/src/assets/skills/architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: architecture
-description: This skill should be used when reviewing code for SOLID violations, tight coupling, or layering issues.
+description: This skill should be used when reviewing code for SOLID or layering issues.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 ---

package/src/assets/skills/boundary-validation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: boundary-validation
-description: This skill should be used when the user asks to "validate input", "parse request data", "handle form data", "add Zod schema", "sanitize user input", or creates API endpoints and system boundaries. Provides parse-don't-validate patterns with schema validation for type-safe boundary enforcement and hostile input defense.
+description: This skill should be used when the user asks to "validate input", "parse request data", "add Zod schema", or creates API endpoints and system boundaries.
 user-invocable: false
 allowed-tools: Read, Grep, Glob, AskUserQuestion
 ---

package/src/assets/skills/complexity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: complexity
-description: This skill should be used when reviewing code for high cyclomatic complexity, deep nesting, or long functions.
+description: This skill should be used when reviewing code for deep nesting or long functions.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 ---

package/src/assets/skills/compliance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: compliance
-description: This skill should be used when reviewing code handling PII, payment data, health records, audit logs, data retention, or IaC under GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, or SOX.
+description: This skill should be used when reviewing code that handles PII, payments or health data.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 ---