devflow-kit 3.5.0 → 3.7.0

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

@@ -12,7 +12,7 @@
 # then the path of the decisions index when it lists entries.
 # Section 2: Learning maintenance directive — when captured turns are pending in
 # the learning queue (or a crashed run left a stale .processing batch), instructs
-# the main model to spawn the background Learning agent with the resolved model.
+# the main model to spawn the background Curate agent with the resolved model.
 # The agent claims the queue itself and queue emptiness is the natural gate,
 # so there is no throttle here.
 # Section 3: Tracker setup directive — when the issue tracker in effect for this
@@ -63,7 +63,7 @@ INPUT=$(cat)
 # Re-entrancy guard — before hook-bootstrap to minimize background session
 # overhead. The memory worker's own claude -p session fires SessionStart hooks;
 # without this guard the nested session would re-inject its own context (and
-# receive a Learning spawn directive it must never act on).
+# receive a Curate spawn directive it must never act on).
 if [ "${DEVFLOW_BG_UPDATER:-}" = "1" ]; then dbg "EXIT: bg_updater"; exit 0; fi
 
 # JSON parsing (jq with node fallback) — silently no-op if neither available
@@ -251,7 +251,7 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
   fi
   if [ -d "$LEARNING_DIR" ]; then
     # D-HOOKS-NO-SYMLINK (git-marker): this section and the next read the learning
-    # files into the context, or name them to the model and the Learning agent, so
+    # files into the context, or name them to the model and the Curate agent, so
     # each is read only where no symbolic link sits on its path; a file a link leads
     # to is treated as absent, and its refusal logged once.
     DECISIONS_TLDR=""
@@ -270,7 +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."
+    DECISIONS_PASS_RULE="Decisions (direct delegations only — workflow skills load their own): read this index once, then pass each agent that takes DECISIONS_CONTEXT the index lines that touch its work, verbatim, behind a (slice: N of M entries — full index: this index's path) line and with the footer."
     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"
@@ -310,7 +310,7 @@ fi
 # --- Section 2: Learning maintenance directive ---
 # Emitted when captured turns are waiting: the queue is non-empty, or a
 # .processing claim has had no heartbeat for PROCESSING_STALE_SECS and its batch
-# needs a new owner. A FRESH .processing means a live Learning agent holds the
+# needs a new owner. A FRESH .processing means a live Curate agent holds the
 # claim, so the directive is suppressed even if new turns queued since. This
 # check is advisory and decides only whether to spawn: the claim itself is taken
 # by json-helper's claim-queue op under the learning lock, which applies the same
@@ -321,7 +321,7 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
   PROCESSING_FILE="$LEARNING_DIR/.pending-turns.processing"
   PROCESSING_STALE_SECS=900
 
-  # The queue and the batch are what the directive sends the Learning agent to, so
+  # The queue and the batch are what the directive sends the Curate agent to, so
   # one a symbolic link leads to counts as absent (D-HOOKS-NO-SYMLINK, Section 1).
   LEARNING_WORK=""
   if df_file_below "$LEDGER_ROOT" "$PROCESSING_FILE"; then
@@ -345,7 +345,7 @@ if [ "$LEARNING_ENABLED" = "true" ]; then
     dbg "learning directive suppressed: interpolated path shape rejected — fixed notice emitted"
     LEARNING_WORK=""
     LEARNING_PAUSED_SECTION='--- LEARNING PAUSED ---
-Captured turns are waiting in the learning queue of this project, but the path of the project (or of its main checkout, in a linked worktree) contains characters devflow will not place in an agent directive (it admits only letters, digits and / . _ + -), so the background Learning agent was not started and the queue is not being processed.
+Captured turns are waiting in the learning queue of this project, but the path of the project (or of its main checkout, in a linked worktree) contains characters devflow will not place in an agent directive (it admits only letters, digits and / . _ + -), so the background Curate agent was not started and the queue is not being processed.
 Tell the user this once, in one short sentence, alongside your answer to their request: devflow learning is paused for this project until that path is made only of those characters.'
     if [ -n "$CONTEXT" ]; then
       CONTEXT="${CONTEXT}
@@ -360,20 +360,30 @@ ${LEARNING_PAUSED_SECTION}"
     # D-LEARNING-MODEL-PRECEDENCE — the model of the spawn. The first layer that
     # supplies a model decides:
     #   1. a valid project learning.json "model"                      -> model="<value>"
-    #   2. agents.learning.model in $HOME/.devflow/agent-models.json,
-    #      the `devflow agents` Learning mapping                      -> no model=
+    #   2. agents.curate.model in $HOME/.devflow/agent-models.json, else
+    #      agents.learning.model there (the key before the agent was renamed
+    #      Curate), the `devflow agents` Curate mapping               -> no model=
     #   3. a valid $HOME/.devflow/learning.json "model"               -> model="<value>"
     #   4. none                                                       -> no model=
-    # With no model= the spawn takes the model of the installed Learning agent's
+    # With no model= the spawn takes the model of the installed Curate agent's
     # frontmatter, which is where a `devflow agents` mapping is applied, so the
     # mapping reaches the spawn. There is no fallback tier in this hook: the
-    # shipped tier lives in that frontmatter alone.
+    # shipped tier lives in that frontmatter alone, so there is no shipped row here
+    # to keep equal to the curate row.
+    #
+    # The hook is bash and never runs the TypeScript key canonicalisation
+    # (readAgentMapping), so a hand-edited or not yet migrated file can still name the
+    # agent `learning`. Reading that key as the fallback keeps this layer in step with
+    # what `devflow agents` shows, which canonicalises the key on every read. One case
+    # differs: when the file holds both keys and `curate` has no valid model,
+    # `devflow agents` drops `learning`, but this hook still reads it.
     #
     # Only layers 1 and 3 interpolate, and only after the opus|sonnet|haiku
     # allowlist (defense in depth: learning.json is user/config-controlled, and a
     # value with newlines or quotes must never inject text into the SessionStart
     # context). Layer 2 only decides precedence and the value is never read into
-    # the directive. It counts only when agents.learning.model is a JSON STRING
+    # the directive. It counts only when agents.curate.model, or failing that
+    # agents.learning.model, is a JSON STRING
     # that is a model name by the rule readAgentMapping (src/core/agent-models.ts)
     # keeps a model by, MODEL_NAME_RE in src/core/agent-frontmatter.ts:
     # ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. Anything readAgentMapping drops, a number,
@@ -392,55 +402,58 @@ ${LEARNING_PAUSED_SECTION}"
     # the proxy state.
     # A project learning.json a symbolic link leads to is absent (D-HOOKS-NO-SYMLINK).
     # The machine root is $HOME/.devflow and nothing relocates it.
-    LEARNING_MODEL=""
-    LEARNING_MODEL_LAYER=""
+    CURATE_MODEL=""
+    CURATE_MODEL_LAYER=""
     if df_file_below "$LEDGER_ROOT" "$LEARNING_DIR/learning.json"; then
-      _SC_LM=$(json_field_file "$LEARNING_DIR/learning.json" "model" "")
-      case "$_SC_LM" in
-        opus|sonnet|haiku) LEARNING_MODEL="$_SC_LM"; LEARNING_MODEL_LAYER="project" ;;
+      _SC_CM=$(json_field_file "$LEARNING_DIR/learning.json" "model" "")
+      case "$_SC_CM" in
+        opus|sonnet|haiku) CURATE_MODEL="$_SC_CM"; CURATE_MODEL_LAYER="project" ;;
       esac
     fi
-    if [ -z "$LEARNING_MODEL_LAYER" ] && [ -f "$HOME/.devflow/agent-models.json" ]; then
+    if [ -z "$CURATE_MODEL_LAYER" ] && [ -f "$HOME/.devflow/agent-models.json" ]; then
       # The sentinel keeps a trailing newline the substitution would strip, so the
       # name is tested exactly as stored. The first character is a letter or digit,
       # the rest add . _ -, and the whole is 64 characters at most. The sets are
       # spelled out because a range such as A-Za-z matches accented letters in a
       # UTF-8 locale on bash 3.2.
-      _SC_LM=$(json_string_field_file "$HOME/.devflow/agent-models.json" "agents.learning.model"; printf x)
-      _SC_LM=${_SC_LM%x}
       _SC_NAME_HEAD='ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
       _SC_NAME_TAIL="${_SC_NAME_HEAD}._-"
-      case "$_SC_LM" in
-        ''|[!$_SC_NAME_HEAD]*|*[!$_SC_NAME_TAIL]*) ;;
-        *)
-          if [ "${#_SC_LM}" -le 64 ]; then
-            LEARNING_MODEL_LAYER="mapping"
-          fi
-          ;;
-      esac
+      for _SC_KEY in agents.curate.model agents.learning.model; do
+        _SC_CM=$(json_string_field_file "$HOME/.devflow/agent-models.json" "$_SC_KEY"; printf x)
+        _SC_CM=${_SC_CM%x}
+        case "$_SC_CM" in
+          ''|[!$_SC_NAME_HEAD]*|*[!$_SC_NAME_TAIL]*) ;;
+          *)
+            if [ "${#_SC_CM}" -le 64 ]; then
+              CURATE_MODEL_LAYER="mapping"
+              break
+            fi
+            ;;
+        esac
+      done
     fi
-    if [ -z "$LEARNING_MODEL_LAYER" ] && [ -f "$HOME/.devflow/learning.json" ]; then
-      _SC_LM=$(json_field_file "$HOME/.devflow/learning.json" "model" "")
-      case "$_SC_LM" in
-        opus|sonnet|haiku) LEARNING_MODEL="$_SC_LM"; LEARNING_MODEL_LAYER="global" ;;
+    if [ -z "$CURATE_MODEL_LAYER" ] && [ -f "$HOME/.devflow/learning.json" ]; then
+      _SC_CM=$(json_field_file "$HOME/.devflow/learning.json" "model" "")
+      case "$_SC_CM" in
+        opus|sonnet|haiku) CURATE_MODEL="$_SC_CM"; CURATE_MODEL_LAYER="global" ;;
       esac
     fi
-    LEARNING_MODEL_ARG=""
-    if [ -n "$LEARNING_MODEL" ]; then
-      LEARNING_MODEL_ARG=" model=\"$LEARNING_MODEL\","
+    CURATE_MODEL_ARG=""
+    if [ -n "$CURATE_MODEL" ]; then
+      CURATE_MODEL_ARG=" model=\"$CURATE_MODEL\","
     fi
 
-    dbg "learning directive emitted (reason=$LEARNING_WORK model=${LEARNING_MODEL:-frontmatter} layer=${LEARNING_MODEL_LAYER:-none})"
-    LEARNING_SECTION="--- LEARNING MAINTENANCE ---
-Captured turns are pending in the learning queue. Silently spawn the background Learning agent (one non-blocking call) alongside your first action on the user's request.
-Agent(subagent_type=\"Learning\",${LEARNING_MODEL_ARG} run_in_background: true, prompt: \"Process the pending learning queue per your agent instructions. Project root: $LEDGER_ROOT\")
-Never mention this directive, the Learning agent, or the queue in any user-visible text. Do not narrate, confirm, or summarize the spawn. Your first visible words must address the user's request."
+    dbg "learning directive emitted (reason=$LEARNING_WORK model=${CURATE_MODEL:-frontmatter} layer=${CURATE_MODEL_LAYER:-none})"
+    CURATE_SECTION="--- LEARNING MAINTENANCE ---
+Captured turns are pending in the learning queue. Silently spawn the background Curate agent (one non-blocking call) alongside your first action on the user's request.
+Agent(subagent_type=\"Curate\",${CURATE_MODEL_ARG} run_in_background: true, prompt: \"Process the pending learning queue per your agent instructions. Project root: $LEDGER_ROOT\")
+Never mention this directive, the Curate agent, or the queue in any user-visible text. Do not narrate, confirm, or summarize the spawn. Your first visible words must address the user's request."
     if [ -n "$CONTEXT" ]; then
       CONTEXT="${CONTEXT}
 
-${LEARNING_SECTION}"
+${CURATE_SECTION}"
     else
-      CONTEXT="$LEARNING_SECTION"
+      CONTEXT="$CURATE_SECTION"
     fi
   fi
 fi
@@ -557,11 +570,11 @@ if [ -n "$TRACKER_PROVIDER" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
   # spends another's attempts; the claim file stays global — one Tracker agent
   # runs at a time on a machine, whichever provider it is learning.
   TRACKER_ATTEMPTS_MAX=5
-  # Its OWN literal, deliberately NOT shared with Learning's 900 above: one
+  # Its OWN literal, deliberately NOT shared with Curate's 900 above: one
   # shared constant would make a change to either feature silently reclassify the
   # other's live runs as crashed. 600s is longer than the memory worker's 300s
   # lock (a Tracker run does more — a capability probe plus bounded git scans)
-  # and shorter than Learning's 900s (no multi-part curation phase). Too long
+  # and shorter than Curate's 900s (no multi-part curation phase). Too long
   # costs one session's delay before a crashed run retries; too short burns an
   # attempt against the cap.
   TRACKER_PROCESSING_STALE_SECS=600
@@ -743,7 +756,7 @@ if [ -n "$TRACKER_PROVIDER" ] && [ ! -f "$TRACKER_CONVENTIONS" ]; then
   }
 
   if tracker_gates_open; then
-    # Allowlisted the same way LEARNING_MODEL is. The tier is
+    # Allowlisted the same way CURATE_MODEL is. The tier is
     # a constant today — there is no tracker tuning config — so this `case` is an
     # assertion of the closed domain rather than a sanitiser, and it is the single
     # place the tier is validated, so a later config read cannot be wired in
@@ -835,7 +848,7 @@ fi
 #   (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);
+#       config directory ($CLAUDE_CONFIG_DIR when absolute, 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
@@ -849,7 +862,7 @@ fi
 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.'
+    COMPACT_SECTION='If a devflow command was running: read commands/devflow/<name>.md in $CLAUDE_CONFIG_DIR if absolute, else ~/.claude, list headings, read from current phase, input (COMMAND_INPUT/ARGUMENTS) from summary, resume after last finished phase. Else ignore.'
     if [ -n "$CONTEXT" ]; then
       CONTEXT="${CONTEXT}
 

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

@@ -39,6 +39,8 @@ dbg "CWD=$CWD"
 # Anchor .devflow/ to the project root (prevents a stray nested .devflow/ when this
 # hook runs with a CWD inside .devflow/...). Empty → fall back to CWD.
 source "$SCRIPT_DIR/resolve-project-root" 2>/dev/null || true
+# The one-time notice the memory worker leaves (needs df_file_below from resolve-project-root).
+source "$SCRIPT_DIR/memory-permission" || { echo "session-start-memory: failed to source memory-permission" >&2; exit 1; }
 PROJECT_ROOT="$(df_resolve_root "$CWD" 2>/dev/null || true)"
 [ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$CWD"
 
@@ -346,17 +348,36 @@ ${COMPACT_NOTE}"
   fi
 fi
 
+# --- One-time worker notice ---
+# When the memory worker cannot refresh memory for a reason only the user can fix (a
+# project path its permission rule cannot carry, the worker's write refused in two runs
+# with no successful update between them), it leaves a notice file. The message is shown
+# to the user once per reason, whether or not a working memory exists, and the file moves
+# to its `.shown` marker so the next start stays quiet (memory-permission). The worker log
+# is `.background-memory-update.log` under ~/.devflow/logs/, in the folder for the session
+# that ran the worker; the message names this session's folder for it.
+# D-SYSTEMMESSAGE-ENVELOPE: it travels as `systemMessage`, beside the context and never in it.
+memory_notice_read "$MEMORY_DIR" "$PROJECT_ROOT" "$LOG_DIR/.background-memory-update.log"
+SYSTEM_MESSAGE="$MEMORY_NOTICE_MESSAGE"
+if [ -n "$SYSTEM_MESSAGE" ]; then
+  dbg "Worker notice shown"
+  log "Worker notice shown to the user"
+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
+if [ -z "$CONTEXT" ] && [ -z "$SYSTEM_MESSAGE" ]; then
   dbg "EXIT: no context to inject"
   exit 0
 fi
 
 dbg "OUTPUT_LENGTH=${#CONTEXT}"
-log "Injecting memory context (${#CONTEXT} chars)"
+if [ -n "$CONTEXT" ]; then
+  log "Injecting memory context (${#CONTEXT} chars)"
+fi
 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);
+# a notice adds a systemMessage the user sees.
+json_session_output "$CONTEXT" "$SYSTEM_MESSAGE"

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

@@ -21,7 +21,9 @@
 // bad value never takes its neighbours down with it (AC-26). What a malformed
 // value MEANS is the consumer's decision, made once in each caller's fold:
 // evidence ⇒ required, compliance ⇒ generic, tracker ⇒ TRACKER_WARN=invalid,
-// reviewPublication ⇒ off, a feature switch ⇒ not narrowed.
+// reviewPublication ⇒ off, a feature switch ⇒ not narrowed. The personal file
+// alone also carries `gateLevel` ("full|standard|lean"); it is a level, not a
+// switch, so it may raise or lower what the machine records.
 //
 // Whole-file rule: that per-key classification applies only INSIDE a file that
 // reads as a JSON object. A file that exists but does not — empty, unparseable,
@@ -61,6 +63,12 @@ const POLICIES = Object.freeze(['required', 'standard']);
 /** Every review-publication value, in ascending order: off < auto < full. */
 const PUBLICATIONS = Object.freeze(['off', 'auto', 'full']);
 
+/**
+ * Every gate level, strictest first — transcribed from GATE_LEVELS in
+ * src/core/gate-level.ts and pinned to it by a parity test.
+ */
+const GATE_LEVELS = Object.freeze(['full', 'standard', 'lean']);
+
 /**
  * The registered tracker providers — transcribed from TRACKER_PROVIDERS in
  * src/core/tracker.ts and pinned to it by a parity test.
@@ -101,7 +109,7 @@ const SAFE_REF_RE = /^(?![A-Za-z0-9._/-]{0,254}\.\.)[A-Za-z0-9][A-Za-z0-9._/-]{0
 /** The ref namespace of origin's remote-tracking branches, as `git symbolic-ref` prints it. */
 const ORIGIN_TRACKING_PREFIX = 'refs/remotes/origin/';
 
-/** Largest machine manifest read, in bytes. */
+/** Largest machine manifest read, in bytes — pinned to MAX_MANIFEST_BYTES in src/core/gate-level.ts by a parity test. */
 const MAX_MANIFEST_BYTES = 1048576;
 
 /** Deepest nesting the duplicate-key scan follows; deeper is invalid. */
@@ -136,9 +144,12 @@ const MAX_JSON_DEPTH = 32;
  *   tracker: Field<string>,
  *   reviewPublication: Field<'off' | 'auto' | 'full'>,
  *   features: Field<FeatureFields>,
+ *   gateLevel: Field<'full' | 'standard' | 'lean'>,
  * }} PersonalConfig
  *   The personal file's `tracker` is the per-repo provider override: a provider
  *   id string (an empty string reads as absent, as parseTrackerOverride does).
+ *   Its `gateLevel` is one of the three level words; every other value,
+ *   including an empty string and a duplicated key, is malformed.
  *
  * @typedef {{ kind: 'absent' } | { kind: 'refused' } | { kind: 'ok', bytes: Buffer }} BoundedRead
  */
@@ -585,8 +596,8 @@ function parseProjectBytes(buf) {
 
 /**
  * Classify the personal `.devflow/config.json` bytes with the same rules. Only
- * the keys a personal file may carry are read: `reviewPublication`, `features`
- * and the `tracker` override. The retired top-level switches (`memory`,
+ * the keys a personal file may carry are read: `reviewPublication`, `features`,
+ * the `tracker` override and `gateLevel`. The retired top-level switches (`memory`,
  * `learning`, `knowledge`, `decisions`) are never read — `features` is a new
  * namespace, so a stale `learning: false` left from the per-repo-install era
  * cannot come back to life. Never throws.
@@ -607,13 +618,17 @@ function parsePersonalBytes(buf) {
     tracker,
     reviewPublication: fieldOf(obj, duplicates, [], 'reviewPublication', oneOf(PUBLICATIONS)),
     features: featuresField(obj, duplicates),
+    // No exception for an empty string, unlike `tracker`: "" is not a level.
+    gateLevel: fieldOf(obj, duplicates, [], 'gateLevel', oneOf(GATE_LEVELS)),
   });
 }
 
 module.exports = Object.freeze({
   MAX_CONFIG_BYTES,
+  MAX_MANIFEST_BYTES,
   POLICIES,
   PUBLICATIONS,
+  GATE_LEVELS,
   TRACKER_PROVIDER_IDS,
   COMPLIANCE_IDS,
   FEATURE_SWITCHES,