devflow-kit 3.2.0 → 3.4.0

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

@@ -23,6 +23,31 @@
 # Section 4: Legacy install notice — one line when this repository still carries
 # a retired project-local devflow install (its .claude/settings.json registers
 # devflow hooks), pointing at `devflow uninstall --scope local`.
+# Section 5: Compaction resume directive — on a `compact` SessionStart, one fixed
+# line telling the model to re-read the devflow command it was running from the
+# phase in progress (D-COMPACT-RESUME-DIRECTIVE).
+# Section 6: CLAUDE.md import audit — a top-level systemMessage (shown to the user,
+# never part of additionalContext) naming an `@path` import that puts a large file
+# into every thread's always-loaded context, once per finding, with a stamp that
+# makes an unchanged start free (D-CLAUDE-MD-IMPORT-AUDIT, D-AUDIT-STAMP,
+# D-SYSTEMMESSAGE-ENVELOPE).
+#
+# Sections 5 and 6 add NO new exit path: neither calls `exit`, a failure in either
+# leaves the other sections and the directive intact, and the hook still exits as it
+# did before (the existing exits are the bad-CWD and re-entrancy returns, the
+# no-JSON-tool return at the top, and the two sourcing failures). With neither jq nor
+# node the hook returns before Section 5 can run, so there is no directive then; that
+# is accepted and documented.
+#
+# Cost of Sections 5 and 6 (the [DR-10] table below belongs to Section 3):
+#   - Section 5: a `case` on a value parsed with the CWD, in the same single
+#     subprocess as before; zero extra forks.
+#   - Section 6, unchanged start (the stamp's root set equals the current one and no
+#     recorded path changed): shell builtins only, one bounded read of the stamp, no
+#     fork, no node process.
+#   - Section 6, changed start: ONE node process (claude-md-audit.cjs), and a
+#     sibling temp file renamed over the stamp. When none of the roots exists there
+#     is nothing to audit: the stamp is written with builtins, and node is not started.
 
 # Safe no-op fallback: must exist before hook-bootstrap is sourced.
 dbg() { :; }
@@ -49,7 +74,13 @@ source "$SCRIPT_DIR/hook-bootstrap" "session-start-context"
 source "$SCRIPT_DIR/json-parse" || { echo "session-start-context: failed to source json-parse" >&2; exit 1; }
 if [ "$_JSON_AVAILABLE" = "false" ]; then exit 0; fi
 
-CWD=$(printf '%s' "$INPUT" | json_field "cwd" "")
+# One subprocess yields both fields: the working directory and the SessionStart
+# `source` (startup|resume|clear|compact) that Section 5 gates on, so the directive
+# costs no fork of its own. Sections 3 and 4 keep reading `source` themselves, where
+# they gate (startup|clear), so neither depends on this value.
+_SC_FIELDS=$(printf '%s' "$INPUT" | json_extract_cwd_field "source")
+CWD="${_SC_FIELDS%%$'\001'*}"
+SESSION_SOURCE="${_SC_FIELDS#*$'\001'}"
 if [ -z "$CWD" ] || [ ! -d "$CWD" ]; then
   dbg "EXIT: bad CWD"
   exit 0
@@ -239,6 +270,7 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
     # since the model would read the file the link names and pass that on.
     # Builtins only: no fork, save the log line of a refused index.
     _SC_INDEX="$LEARNING_DIR/index.md"; DECISIONS_INDEX_LINE=""
+    DECISIONS_PASS_RULE="Decisions (direct delegations only — workflow skills load their own): pass this index as DECISIONS_CONTEXT — its content, read once — to every agent that takes it."
     if [ -n "$DIRECTIVE_LEDGER_SAFE" ] && df_file_below "$LEDGER_ROOT" "$_SC_INDEX" && [ -s "$_SC_INDEX" ]; then
       _SC_IDX1=""; IFS= read -r _SC_IDX1 < "$_SC_INDEX" || true
       [ "$_SC_IDX1" != "(none)" ] && DECISIONS_INDEX_LINE="Index: $_SC_INDEX"
@@ -250,10 +282,19 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
         DECISIONS_SECTION="${DECISIONS_SECTION}
 $(printf '%b' "$DECISIONS_TLDR")"
       fi
-      # The index line goes last.
+      # The index line goes last among the data lines, and the pass rule follows it.
+      # D-DECISIONS-CHARTER-HANDOFF: the rule that tells the main model to pass this
+      # index on as DECISIONS_CONTEXT lives here, not in the orchestrator charter. It
+      # is only useful with an index line to pass, so it is emitted only with one, and
+      # this block is already gated on the machine switch narrowed by the repository,
+      # so a learning-off machine or repo never sees it (the charter paid for it in
+      # every session, learning or not). It also reaches sessions with ambient off,
+      # which the charter never did. A static literal: no input is interpolated, so it
+      # needs no shape gate. The same text reaches the jq and the node envelope.
       if [ -n "$DECISIONS_INDEX_LINE" ]; then
         DECISIONS_SECTION="${DECISIONS_SECTION}
-${DECISIONS_INDEX_LINE}"
+${DECISIONS_INDEX_LINE}
+${DECISIONS_PASS_RULE}"
       fi
       if [ -n "$CONTEXT" ]; then
         CONTEXT="${CONTEXT}
@@ -779,11 +820,270 @@ ${LEGACY_SECTION}"
   fi
 fi
 
+# --- Section 5: Compaction resume directive ---
+# D-COMPACT-RESUME-DIRECTIVE: after a compaction nothing tells the model to re-read
+# the devflow command it was running; Claude Code re-injects a long command only in
+# part (the plan records commands over about 5k tokens being truncated on re-injection,
+# which this repository cannot verify). On the SessionStart whose source is `compact`
+# this section adds one fixed line, appended to CONTEXT with the other sections'
+# join, and never sent as a systemMessage.
+#
+# The line is a constant: a single-quoted string that interpolates nothing, so the
+# `$CLAUDE_CONFIG_DIR` in it reaches the model as text and its bytes do not depend on
+# the caller. It names, in at most 250 ASCII characters (tests/session-start-compact
+# holds the cap and the numeric-floors ceiling `compact-directive-max-chars`):
+#   (a) an if-clause, so it applies only when a devflow command was running, with an
+#       explicit ignore clause;
+#   (b) where the command file lives, by rule: commands/devflow/ under the Claude
+#       config directory ($CLAUDE_CONFIG_DIR, else ~/.claude);
+#   (c) the read mechanics: list the headings, then read from the phase in progress,
+#       never the whole file;
+#   (d) that the command's input (COMMAND_INPUT in the commands that bind it, an
+#       ARGUMENTS line in the others) comes from the conversation summary, not from a
+#       placeholder in the file;
+#   (e) to resume after the last finished phase.
+# The gate is a POSITIVE `compact` case, emitted on every compact run whatever the
+# project (the directive does no project work), so it never becomes a denylist and a
+# missing, absent or unrecognised source emits nothing. The model decides whether a
+# command was running: detecting one here would be judgment, which stays out of hooks.
+case "$SESSION_SOURCE" in
+  compact)
+    dbg "compaction resume directive emitted"
+    COMPACT_SECTION='If a devflow command was running: re-read {$CLAUDE_CONFIG_DIR or ~/.claude}/commands/devflow/<name>.md, list headings, read from current phase, take input (COMMAND_INPUT/ARGUMENTS) from the summary, resume after the last finished phase. Else ignore.'
+    if [ -n "$CONTEXT" ]; then
+      CONTEXT="${CONTEXT}
+
+${COMPACT_SECTION}"
+    else
+      CONTEXT="$COMPACT_SECTION"
+    fi
+    ;;
+esac
+
+# --- Section 6: CLAUDE.md import audit and its stamp ---
+# D-CLAUDE-MD-IMPORT-AUDIT: a CLAUDE.md `@path` import loads its file into every
+# thread at launch, so a large import is paid for in every session. This section
+# reports the ones over the thresholds that claude-md-audit.cjs holds (and documents:
+# grammar, bounds, thresholds, the upstream differences) in a top-level systemMessage,
+# which the user sees and the model does not (D-SYSTEMMESSAGE-ENVELOPE, json-parse).
+# It never enters CONTEXT, and the audit READS only: this section and init write the
+# stamp, nothing else.
+#
+# D-AUDIT-STAMP: one machine-root file, $HOME/.devflow/.claude-md-audit, so a changed
+# start costs one node process and an unchanged one costs none. Its rows are `V 1`,
+# `R <root>` (the gated root set), `P <flag> <path>` (every path the last audit
+# examined: 0 absent, 1 regular file, 2 exists but is not one), `K <key>` (a finding
+# already displayed) and `E <reason>`; the format is specified in claude-md-audit.cjs.
+#   Gated roots: CLAUDE.md in the Claude config directory ($CLAUDE_CONFIG_DIR when
+#   absolute, else ~/.claude) always; in a git project that is not HOME
+#   (PROJECT_OK) also its CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md.
+#   Fast path (builtins only, no fork): the audit is skipped when the stamp's R rows
+#   equal the current root set and every P row still holds: `-e` agrees with the
+#   flag, and a regular file is not `-nt` (newer than) the stamp. Mtimes are whole
+#   seconds. Two gaps are accepted: a file whose mtime is moved back before the stamp
+#   is missed until its next forward change, and a write landing while an audit runs
+#   can be missed the same way. The fast path decides only whether the audit runs.
+#   Slow path: ONE node process over the roots (none when no root exists: there is
+#   nothing to read, so the stamp records the absent roots with builtins). A finding is recorded as displayed
+#   only after the output below was emitted, so a lost stamp update can repeat a
+#   message and can never hide a new finding.
+#   Failure: node failing, the script missing or throwing, or output that is not the
+#   framed block shows nothing, and writes a stamp holding the R rows, the keys
+#   already displayed and an error marker; an unchanged broken state then starts no
+#   node process, and a changed root set retries. A root path holding a control byte
+#   is never recorded, so a setup with one re-audits at every start (rare).
+#   Skipped silently: no node on PATH, no ~/.devflow (a session never creates the
+#   machine root), or a stamp path that is a link or not a regular file.
+# A stamp over 256 KiB, or one with a NUL byte, is read as absent.
+SYSTEM_MESSAGE=""
+AUDIT_STAMP_NEXT=""
+AUDIT_STAMP_FILE="$TRACKER_DEVFLOW_DIR/.claude-md-audit"
+AUDIT_SCRIPT="$SCRIPT_DIR/../claude-md-audit.cjs"
+_SC_AUDIT_OLD_STAMP=""
+_SC_AUDIT_ROOTS=()
+
+# _sc_audit_stamp_blocked — succeeds when the stamp path is a link or exists and is
+# not a regular file: the write is refused and the audit skipped (D-AUDIT-STAMP).
+_sc_audit_stamp_blocked() {
+  if [ -L "$AUDIT_STAMP_FILE" ]; then return 0; fi
+  if [ -e "$AUDIT_STAMP_FILE" ] && [ ! -f "$AUDIT_STAMP_FILE" ]; then return 0; fi
+  return 1
+}
+
+# _sc_audit_stamp_fresh — succeeds when the audit can be skipped. Builtins only.
+# Sets _SC_AUDIT_OLD_STAMP to the stamp text (empty when absent, over 256 KiB or
+# holding a NUL: `read -d '' -n N` succeeds only when it stops short of the end of
+# the file, which is a stamp the shell cannot vouch for). Ends in an explicit return
+# so a caller running under set -e would not die on the normal path: a function's last
+# status is the status of its call, and under errexit a non-zero one is fatal.
+_sc_audit_stamp_fresh() {
+  local line="" have="" want="" root="" path=""
+  _SC_AUDIT_OLD_STAMP=""
+  [ -f "$AUDIT_STAMP_FILE" ] || return 1
+  if IFS= read -r -d '' -n 262145 _SC_AUDIT_OLD_STAMP 2>/dev/null < "$AUDIT_STAMP_FILE"; then
+    _SC_AUDIT_OLD_STAMP=""
+    return 1
+  fi
+  case "$_SC_AUDIT_OLD_STAMP" in
+    'V 1'|'V 1'$'\n'*) ;;
+    *) _SC_AUDIT_OLD_STAMP=""; return 1 ;;
+  esac
+  for root in "${_SC_AUDIT_ROOTS[@]}"; do
+    want="${want}R ${root}"$'\n'
+  done
+  while IFS= read -r line; do
+    case "$line" in
+      'R '*) have="${have}${line}"$'\n' ;;
+    esac
+  done <<< "$_SC_AUDIT_OLD_STAMP"
+  if [ "$have" != "$want" ]; then return 1; fi
+  while IFS= read -r line; do
+    case "$line" in
+      'P 0 '*)
+        path="${line#P 0 }"
+        if [ -e "$path" ]; then return 1; fi
+        ;;
+      'P 1 '*)
+        path="${line#P 1 }"
+        if [ ! -e "$path" ] || [ "$path" -nt "$AUDIT_STAMP_FILE" ]; then return 1; fi
+        ;;
+      'P 2 '*)
+        path="${line#P 2 }"
+        if [ ! -e "$path" ]; then return 1; fi
+        ;;
+    esac
+  done <<< "$_SC_AUDIT_OLD_STAMP"
+  return 0
+}
+
+# _sc_audit_shell_stamp <absent|failed> — a stamp the shell writes without node, for the
+# two cases that need no audit text. Sets AUDIT_STAMP_NEXT. The rows are the ones
+# claude-md-audit.cjs renders for the same state (tests/session-start-compact.test.ts
+# holds the two equal): a root with a control byte is left out, as the script leaves it
+# out, and the keys of the previous stamp are kept.
+#   absent  No root exists, so there is nothing to audit and nothing to show: the root
+#           rows and a `P 0` row each. A CLAUDE.md appearing at any of them re-audits.
+#   failed  The audit could not run: the root rows and an error marker, no P rows, so
+#           only a changed root set retries.
+_sc_audit_shell_stamp() {
+  local kind="$1" line="" root="" text='V 1'$'\n'
+  for root in "${_SC_AUDIT_ROOTS[@]}"; do
+    case "$root" in
+      *[[:cntrl:]]*) ;;
+      *) text="${text}R ${root}"$'\n' ;;
+    esac
+  done
+  if [ "$kind" = "absent" ]; then
+    for root in "${_SC_AUDIT_ROOTS[@]}"; do
+      case "$root" in
+        *[[:cntrl:]]*) ;;
+        *) text="${text}P 0 ${root}"$'\n' ;;
+      esac
+    done
+  fi
+  while IFS= read -r line; do
+    case "$line" in
+      'K '*) text="${text}${line}"$'\n' ;;
+    esac
+  done <<< "$_SC_AUDIT_OLD_STAMP"
+  if [ "$kind" = "failed" ]; then text="${text}E audit-failed"$'\n'; fi
+  AUDIT_STAMP_NEXT="$text"
+  return 0
+}
+
+# _sc_audit_no_root — succeeds when none of the gated roots exists. The common case on a
+# machine with no CLAUDE.md anywhere, settled by `-e` tests alone: no node process.
+_sc_audit_no_root() {
+  local root=""
+  for root in "${_SC_AUDIT_ROOTS[@]}"; do
+    if [ -e "$root" ]; then return 1; fi
+  done
+  return 0
+}
+
+# _sc_audit_run — the slow path: one node process, its framed block parsed with
+# builtins. `M ` rows are the systemMessage lines; V/R/P/K/E rows are the new stamp.
+# Sets SYSTEM_MESSAGE and AUDIT_STAMP_NEXT; a block that is not complete is a failure.
+_sc_audit_run() {
+  local out="" line="" rc=0 magic="" end="" msg="" stamp=""
+  out=$(node "$AUDIT_SCRIPT" hook "$HOME" "$AUDIT_STAMP_FILE" "${_SC_AUDIT_ROOTS[@]}" 2>/dev/null)
+  rc=$?
+  if [ "$rc" -eq 0 ]; then
+    while IFS= read -r line; do
+      case "$line" in
+        'devflow-claude-md-audit 1') magic="yes" ;;
+        'END') end="yes" ;;
+        'M '*)
+          if [ -n "$msg" ]; then msg="${msg}"$'\n'"${line#M }"; else msg="${line#M }"; fi
+          ;;
+        [VRPKE]' '*) stamp="${stamp}${line}"$'\n' ;;
+      esac
+    done <<< "$out"
+  fi
+  if [ "$rc" -eq 0 ] && [ -n "$magic" ] && [ -n "$end" ] && [ -n "$stamp" ]; then
+    SYSTEM_MESSAGE="$msg"
+    AUDIT_STAMP_NEXT="$stamp"
+    dbg "claude-md audit ran (message=${#msg} chars)"
+  else
+    dbg "claude-md audit failed — recording the failure, showing nothing"
+    _sc_audit_shell_stamp failed
+  fi
+  return 0
+}
+
+# _sc_audit_record — write AUDIT_STAMP_NEXT, after the output has been emitted. A
+# sibling temp file (owner-only: the umask is set before the copy exists, because a rename
+# installs the copy's mode and not the replaced file's) is
+# renamed over the stamp; nothing stands at either name that is a link or not a
+# regular file (noclobber alone would still open a FIFO, and mv onto a linked directory
+# moves into it), and a failed write leaves the old stamp. Never fails the hook.
+_sc_audit_record() {
+  local tmp="${AUDIT_STAMP_FILE}.tmp.$$"
+  [ -n "$AUDIT_STAMP_NEXT" ] || return 0
+  [ -d "$TRACKER_DEVFLOW_DIR" ] || return 0
+  if _sc_audit_stamp_blocked; then return 0; fi
+  if [ -e "$tmp" ] || [ -L "$tmp" ]; then return 0; fi
+  if ( umask 077; set -o noclobber; printf '%s' "$AUDIT_STAMP_NEXT" > "$tmp" ) 2>/dev/null; then
+    if _sc_audit_stamp_blocked; then
+      rm -f -- "$tmp" 2>/dev/null
+      return 0
+    fi
+    mv -f -- "$tmp" "$AUDIT_STAMP_FILE" 2>/dev/null || rm -f -- "$tmp" 2>/dev/null
+  else
+    rm -f -- "$tmp" 2>/dev/null
+  fi
+  return 0
+}
+
+if [ "$_HAS_NODE" = "true" ] && [ -d "$TRACKER_DEVFLOW_DIR" ]; then
+  if _sc_audit_stamp_blocked; then
+    dbg "claude-md audit skipped: the stamp path is a link or not a regular file"
+  else
+    _SC_AUDIT_CLAUDE_DIR="$HOME/.claude"
+    case "${CLAUDE_CONFIG_DIR:-}" in /*) _SC_AUDIT_CLAUDE_DIR="$CLAUDE_CONFIG_DIR" ;; esac
+    _SC_AUDIT_ROOTS=("$_SC_AUDIT_CLAUDE_DIR/CLAUDE.md")
+    if [ -n "$PROJECT_OK" ]; then
+      _SC_AUDIT_ROOTS+=("$PROJECT_ROOT/CLAUDE.md" "$PROJECT_ROOT/.claude/CLAUDE.md" "$PROJECT_ROOT/CLAUDE.local.md")
+    fi
+    if _sc_audit_stamp_fresh; then
+      dbg "claude-md audit skipped: the stamp is current"
+    elif _sc_audit_no_root; then
+      dbg "claude-md audit skipped: no root exists — recording that"
+      _sc_audit_shell_stamp absent
+    else
+      _sc_audit_run
+    fi
+  fi
+fi
+
 # --- Output ---
 
-# Only output if we have something to inject
-if [ -z "$CONTEXT" ]; then
+# Only output if we have something to inject or to tell the user. The stamp is
+# recorded here too: an audit that found nothing to show still ran, and recording it
+# is what makes the next unchanged start free.
+if [ -z "$CONTEXT" ] && [ -z "$SYSTEM_MESSAGE" ]; then
   dbg "EXIT: no context to inject"
+  _sc_audit_record
   exit 0
 fi
 
@@ -791,5 +1091,13 @@ dbg "OUTPUT_LENGTH=${#CONTEXT}"
 log "Injecting context (${#CONTEXT} chars)"
 dbg "=== HOOK COMPLETE ==="
 
-# Output as additionalContext JSON envelope (Claude sees it as system context, not user-visible)
-json_session_output "$CONTEXT"
+# Output as additionalContext JSON envelope (Claude sees it as system context, not
+# user-visible). The audit text, if any, travels in the envelope's top-level
+# systemMessage and never in the context (D-SYSTEMMESSAGE-ENVELOPE). With no message
+# the second argument is empty and the envelope is the one callers always got.
+json_session_output "$CONTEXT" "$SYSTEM_MESSAGE"
+_SC_OUT_RC=$?
+
+# A finding is recorded as displayed only after it was shown (D-AUDIT-STAMP).
+if [ "$_SC_OUT_RC" -eq 0 ]; then _sc_audit_record; fi
+exit "$_SC_OUT_RC"

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. Never load decisions files otherwise.

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

@@ -1,8 +1,8 @@
 ---
 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
+allowed-tools: Read, Bash
 ---
 
 # Apply Feature Knowledge
@@ -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 `FEATURE_KNOWLEDGE` block (headed `--- Feature knowledge: {slug} ---`): `Rules:` holds anti-patterns, gotchas and invariants; `KB:` is the full file's path (under `WORKTREE_PATH` when given).
+2. **Apply** them: check your work against every bullet and cite it as `{slug} KB-AP-n` (a section-labelled bullet as `{slug} {section}`), never a bare ID. For architecture or integration context, Read that section on demand, with `offset` and `limit`: its start line is on the `Headings:` line, or comes from `command grep -n '^## ' "<KB path>"`. Quote KB text only from a Read view.
+3. **Verify** against current code: where an assertion is outdated or contradicts the code, Read the source and trust it. Note a discrepancy in your output when it matters.
 
 ---
 
@@ -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, 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
 ---