devflow-kit 3.3.0 → 3.5.0

package/src/assets/scripts/hooks/json-parse

@@ -98,18 +98,42 @@ json_extract_cwd_prompt() {
 
 # --- Hook output envelopes ---
 
-# Build SessionStart output. Usage: json_session_output "$CONTEXT"
+# Build SessionStart output. Usage: json_session_output "$CONTEXT" ["$SYSTEM_MESSAGE"]
+#
+# D-SYSTEMMESSAGE-ENVELOPE: the optional second argument is a message shown to the
+# user, carried in the top-level `systemMessage` key beside (never inside)
+# `hookSpecificOutput`; it does not enter the model's context. With ONE argument the
+# envelope is exactly what every existing caller has always received, byte for byte
+# (ensure-proxy, session-start-orchestrator, session-start-memory and Sections 1-5 of
+# session-start-context pass one). With two:
+#   - a message and a context  -> both keys, hookSpecificOutput first;
+#   - a message and no context -> `systemMessage` alone, with NO hookSpecificOutput key;
+#   - an empty message         -> the one-argument envelope for that context.
+# The node fallback (json-helper.cjs session-output) builds the same content, compact
+# where jq pretty-prints.
 json_session_output() {
-  local ctx="$1"
-  if [ "$_HAS_JQ" = "true" ]; then
-    jq -n --arg ctx "$ctx" '{
-      "hookSpecificOutput": {
-        "hookEventName": "SessionStart",
-        "additionalContext": $ctx
-      }
-    }'
+  local ctx="$1" msg="${2:-}"
+  if [ "$#" -lt 2 ] || [ -z "$msg" ]; then
+    if [ "$_HAS_JQ" = "true" ]; then
+      jq -n --arg ctx "$ctx" '{
+        "hookSpecificOutput": {
+          "hookEventName": "SessionStart",
+          "additionalContext": $ctx
+        }
+      }'
+    else
+      node "$_JSON_HELPER" session-output "$ctx"
+    fi
+  elif [ "$_HAS_JQ" = "true" ]; then
+    jq -n --arg ctx "$ctx" --arg msg "$msg" '
+      (if $ctx != "" then {
+        "hookSpecificOutput": {
+          "hookEventName": "SessionStart",
+          "additionalContext": $ctx
+        }
+      } else {} end) + {"systemMessage": $msg}'
   else
-    node "$_JSON_HELPER" session-output "$ctx"
+    node "$_JSON_HELPER" session-output "$ctx" "$msg"
   fi
 }
 

package/src/assets/scripts/hooks/lib/project-paths.cjs

@@ -164,11 +164,6 @@ function getResearchDir(projectRoot) {
   return path.join(projectRoot, '.devflow', 'docs', 'research');
 }
 
-/** .devflow/docs/handoff-{branchSlug}.md — Code agent phase handoff artifact */
-function getHandoffPath(projectRoot, branchSlug) {
-  return path.join(projectRoot, '.devflow', 'docs', `handoff-${branchSlug}.md`);
-}
-
 module.exports = {
   // Core directories
   getMemoryDir,
@@ -201,5 +196,4 @@ module.exports = {
   getReviewsDir,
   getDesignDir,
   getResearchDir,
-  getHandoffPath,
 };

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/skills/agent-references/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: agent-references
+description: Agent-owned reference files, read by explicit path, never preloaded
+user-invocable: false
+disable-model-invocation: true
+allowed-tools: Read
+---
+
+# Agent References
+
+<!-- D-AGENT-REFS: a reference-only skill. It holds text that one agent mode needs and the
+     other modes do not, so the agent body stays small and the spawn reads one file on demand.
+     D-MODE-BY-PATH: Synthesize reads exactly one synthesize/{mode}.md by explicit path.
+     D-MAINTAIN-ON-DUE: Learning reads learning/maintain.md only after claim-due hands out an entry. -->
+
+## Iron Law
+
+> **READ BY EXPLICIT PATH ONLY; NEVER PRELOAD**
+>
+> An agent that owns a file here names its full path in its own body and reads it with the
+> Read tool when its mode needs it. No agent `skills:` list and no plugin preload names this
+> skill: a preload would put every file in every spawn and undo the saving.
+
+## Files
+
+| Path under `references/` | Owner | Read when |
+|--------------------------|-------|-----------|
+| `synthesize/{mode}.md` | Synthesize | The prompt's `Mode:` line names `{mode}` |
+| `learning/maintain.md` | Learning | `claim-due` hands out at least one entry |
+
+The installed directory is `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/devflow:agent-references/`.
+The model never invokes this skill: `disable-model-invocation: true` keeps it out of the
+model's own skill choices, and `user-invocable: false` keeps it out of the slash menu.

package/src/assets/skills/agent-references/references/learning/maintain.md

@@ -0,0 +1,71 @@
+## Part 2 — Maintain the due entries
+
+You read this because `claim-due` handed out at least one entry. Its output is in your context.
+
+The first line, `ref <origin/HEAD|HEAD> <sha12>`, names the verify ref: check every claim
+at that ref (`git show <ref>:<path>`). Each further line, `<anchor> <reason> <bytes>`, is
+one due entry. The reason is one or more integrity flags joined by `,` —
+`duplicate-obs-id` (two active entries share one observation), `ledger-without-log` (the
+entry's observation is gone from the log), `scope-matches-nothing` (no tracked file
+matches its scope) — or `legacy-v1` (a v1 entry) or `verify-age` (not verified for over
+30 days). Each entry is leased for a day, so whatever you leave unfinished comes back.
+`ref none` means there is no commit to check against: leave every
+due entry as it is.
+
+**LLM judgment — the maintenance ladder.** For each due entry, run `show <anchor>`. A
+`ledger-without-log` entry first gets its observation back: `put-observation --create`
+under the same id, carrying the entry's content in the entry format, which re-projects
+the entry. Then take the first rung that matches. Exactly one final action per entry;
+when unsure, Keep.
+
+1. **Encoded** — the codebase now enforces or states the rule, by a strict bar: a test or
+   guard that fails on a new violation anywhere in the entry's scope, or the rule stated in
+   CLAUDE.md, a rules file, or a prompt loaded for all work in that scope. One JSDoc line
+   does not count, and neither does a test pinning one instance. Find it with `git grep -P`,
+   confirm it at the ref, then retire the entry with the file and a line of it:
+
+   ```bash
+   cd "<project root>" && node "$HOME/.devflow/scripts/hooks/json-helper.cjs" retire-anchor <anchor> Encoded <<'EOF'
+   {"at": "<path from the repository root>", "quote": "<one line of that file, 12 to 200 characters>"}
+   EOF
+   ```
+
+   The op checks the quote in the file as committed at the verify ref. A refusal saying
+   `the quote is not in …` or `… is not a file at …` means the encoding is not there yet:
+   Keep the entry.
+2. **No longer true at the ref** — the code the rule governs is gone or changed so the rule
+   cannot apply; `scope-matches-nothing` is a prompt to check. A missing file is not proof
+   alone: an entry that records removing or replacing something is confirmed by the
+   absence. When the lesson still applies elsewhere, rewrite it (`put-observation --update`
+   with a corrected scope) and Keep it; otherwise retire it as `Retired`.
+3. **Duplicate** — another active entry covers the same concern; `duplicate-obs-id` always
+   means one does. Choose the survivor: the more precise entry, or the more accurate type
+   when an ADR and a PF cover one incident. Absorb what only the other says into the
+   survivor with `put-observation --update`, then retire the other as `Superseded` by the
+   survivor.
+4. **One-off** — it recorded a single incident with no general lesson: retire it as `Retired`.
+5. **Keep** — every other entry. Rewrite it only when it is legacy (`legacy-v1`), wrong or
+   vague: `put-observation --update` with its whole content, which also converts a v1 entry
+   to v2. Before rewriting a v1 entry, read the `flags` of its `show`: `ledger-only-content`
+   names details only its ledger row holds — carry over what is still true; history and the
+   pre-v2 backup keep the rest.
+
+After each maintained entry, refresh the claim (Step 0).
+
+**RETIRE BY STATUS — never hand-edit the .md.** `retire-anchor <anchor> <status>` takes one
+JSON object on stdin, by status, and refuses a key the status does not take:
+
+- `Retired`, `Deprecated`: `{"reason": "<why, one line, 1 to 120 characters>"}`
+- `Superseded`: `{"by": "<anchor>"}` — an active entry other than this one, of either type
+- `Encoded`: `at` and `quote`, as in rung 1
+
+**Close with one batch** listing every entry you kept, rewritten or not (skip it when you
+kept none):
+
+```bash
+cd "<project root>" && node "$HOME/.devflow/scripts/hooks/json-helper.cjs" refresh-anchor <anchor> [<anchor>...] --verified
+```
+
+List only active v2 entries — a v1 entry refuses the whole batch, which is why a kept v1
+entry is rewritten first. A refused batch names each refused anchor: drop those and run
+it once more.

package/src/assets/skills/agent-references/references/synthesize/bug-analysis.md

@@ -0,0 +1,71 @@
+## Mode: Bug Analysis
+
+Synthesize outputs from multiple Diagnose agents into a single actionable bug report.
+
+**Input:**
+- **ANALYSIS_BASE_DIR**: Timestamped directory containing `{focus}.md` files and `static-findings.md`
+- **BRANCH**: Branch name and base branch
+- **TIMESTAMP**: ISO timestamp for the report
+
+**Process:**
+1. Read all `{focus}.md` files from `${ANALYSIS_BASE_DIR}` — exclude `bug-analysis-summary.md` and `static-findings.md`
+2. Also read `${ANALYSIS_BASE_DIR}/static-findings.md` if it exists (contains raw tool output)
+3. Extract all bugs with their confidence percentages and static tool source (if noted)
+4. Cross-track confidence: findings that appear in both `static-findings.md` and a focus report get +10% confidence boost (static-confirmed)
+5. Deduplicate: same file:line from multiple analyzers → keep highest confidence, boost +10% per additional agent (cap 100%)
+6. Merge acceptance criteria coverage tables from the functional analyzer (if present)
+7. Sort bugs by severity (CRITICAL → HIGH → MEDIUM → LOW), then by confidence descending within each severity
+8. Determine overall risk assessment: highest severity of any CRITICAL/HIGH bug found
+
+**Output:**
+**CRITICAL**: Write the summary to disk using the Write tool:
+1. Create directory: `mkdir -p ${ANALYSIS_BASE_DIR}`
+2. Write to `${ANALYSIS_BASE_DIR}/bug-analysis-summary.md` using Write tool
+3. Confirm file written in final message
+
+Report format:
+
+```markdown
+# Bug Analysis Summary
+
+**Branch**: {branch} -> {base}
+**Date**: {timestamp}
+
+## Risk Assessment: {CRITICAL | HIGH | MEDIUM | LOW | CLEAN}
+
+{Brief reasoning — what drives the risk level, or "No bugs found above confidence threshold."}
+
+## Bug Summary
+| Category | CRITICAL | HIGH | MEDIUM | LOW | Total |
+|----------|----------|------|--------|-----|-------|
+| Security | {n} | {n} | {n} | {n} | {n} |
+| Functional | {n} | {n} | {n} | {n} | {n} |
+| Integration | {n} | {n} | {n} | {n} | {n} |
+| Usability | {n} | {n} | {n} | {n} | {n} |
+
+## Critical & High Bugs
+
+{For each CRITICAL and HIGH bug (sorted by severity then confidence):}
+**{Title}** — `file:line` ({n}% confidence, {Category})
+- Problem: {description}
+- Fix: {suggestion}
+
+## Acceptance Criteria Status
+
+(Omit section if no functional analyzer produced acceptance criteria coverage)
+
+| ID | Criterion | Status | Evidence |
+|----|-----------|--------|----------|
+| {id} | {criterion} | PASS / FAIL / NOT_TESTED | {file:line or note} |
+
+## Suggestions (Lower Confidence)
+
+{Max 5 items across all analyzers with 60-79% confidence. Brief description only.}
+
+- **{Issue}** — `file.ts:456` ({n}%, {Category}) — {brief description}
+
+## Action Plan
+1. {Highest-priority fix — CRITICAL or first HIGH}
+2. {Next priority fix}
+3. {Additional fixes in priority order}
+```

package/src/assets/skills/agent-references/references/synthesize/design.md

@@ -0,0 +1,36 @@
+## Mode: Design
+
+Synthesize outputs from multiple Design agents (gap analysis across different focus areas).
+
+**Process:**
+1. Extract findings from each Design agent
+2. Deduplicate: If multiple Design agents flag the same issue, boost confidence by 10% per additional agent (cap at 100%). **Exception — merge, don't boost:** a compliance finding and a security finding at the same location (same file:line or same design element) identify a single gap from two regulatory angles — merge into one finding, do not apply the confidence boost. Multi-agent agreement on a compliance+security overlap is not corroboration; it is one gap seen by two lenses.
+3. Categorize by actionability:
+   - **Blocking** (CRITICAL/HIGH): Must be resolved before implementation
+   - **Should-Address** (MEDIUM): Recommended improvements
+   - **Informational** (LOW): Noted but not actionable
+4. Sort by severity within each category
+
+**Output:**
+```markdown
+## Design Synthesis
+
+### Blocking Gaps
+| Gap | Focus | Severity | Confidence | Resolution |
+|-----|-------|----------|------------|------------|
+| {gap} | {focus area} | {CRITICAL/HIGH} | {n}% | {proposed resolution} |
+
+### Should-Address
+| Gap | Focus | Severity | Confidence | Recommendation |
+|-----|-------|----------|------------|----------------|
+| {gap} | {focus area} | MEDIUM | {n}% | {recommendation} |
+
+### Informational
+| Gap | Focus | Confidence | Note |
+|-----|-------|------------|------|
+| {gap} | {focus area} | {n}% | {note} |
+
+### Key Insights
+1. {cross-cutting insight}
+2. {insight}
+```