devflow-kit 3.6.0 → 3.8.0

package/src/assets/scripts/hooks/ensure-root-gitignore

@@ -2,7 +2,7 @@
 # ensure-root-gitignore — single source of truth for the project root .gitignore
 # rules that govern .devflow/.
 #
-# .devflow/ holds per-developer runtime state (memory, learning, docs, locks) —
+# .devflow/ holds per-developer runtime state (memory, curation, docs, locks) —
 # local by default. FOUR exceptions are shared via git:
 # 1. Feature knowledge bases under .devflow/features/: index.md and every
 #    {slug}/KNOWLEDGE.md (tracked, committed by the Knowledge agent at workflow end).
@@ -22,9 +22,9 @@
 # so git never descends and later negations are dead. Hence the multi-line block.
 #
 # Sourced by:
-#   - ensure-devflow-init (reached via the memory/learning hooks)
+#   - ensure-devflow-init (reached via the memory/curation hooks)
 #   - session-start-context (always-on, memory-independent — covers memory-off
-#     projects that still use learning/knowledge)
+#     projects that still use curation/knowledge)
 # Both reach this one writer so the rule is applied identically everywhere; this
 # decouples git-tracking of .devflow/ from any single feature toggle.
 #
@@ -201,7 +201,7 @@ mkdir -p "$_ERG_DEVFLOW_DIR" 2>/dev/null || return 1
 # DEVFLOW_GITIGNORE_BLOCK_WITHOUT_CLAUDEIGNORE in
 # src/targets/claude-code/post-install.ts.
 printf -v _ERG_BLOCK_NO_CI '%s\n' \
-  '# Devflow runtime data — local by default (memory, learning, docs, locks).' \
+  '# Devflow runtime data — local by default (memory, curation, docs, locks).' \
   '# Shared via git: feature knowledge bases under .devflow/features/ (index.md and' \
   '# every {slug}/KNOWLEDGE.md), .devflow/conventions.md (naming authority),' \
   '# .devflow/policy.json (retired; presence only) and .devflow/project.json (team settings).' \

package/src/assets/scripts/hooks/git-marker

@@ -133,3 +133,84 @@ df_file_below() {
   fi
   return 1
 }
+
+# df_ledger_folder <devflow_dir> <old> [<new>] — sets DF_LEDGER_FOLDER to the path of
+# the ledger folder a creator may create or write into: <devflow_dir>/<old> while that
+# name is present (a folder, a file or a link, dangling or not), else
+# <devflow_dir>/<new>. <new> defaults to <old>, so a caller that names only the old
+# folder gets the old folder's path in every state.
+#
+# The creator rule: a creator makes the new folder only when the old name is absent.
+# A new folder made beside a present old one would hide the old ledger from every
+# reader, so the session-start heal, the ensure-devflow-init scaffold and queue
+# append all take their folder from here. It answers a path and creates nothing; the
+# caller checks the path with df_no_symlink_below and creates it.
+#
+# Zero forks: builtin tests and parameter expansion only. It always returns 0; read
+# the answer from DF_LEDGER_FOLDER, not from a command substitution.
+df_ledger_folder() {
+  local _dir="$1" _old="$2" _new="${3:-$2}"
+  if [ -e "$_dir/$_old" ] || [ -L "$_dir/$_old" ]; then
+    DF_LEDGER_FOLDER="$_dir/$_old"
+  else
+    DF_LEDGER_FOLDER="$_dir/$_new"
+  fi
+  return 0
+}
+
+# df_ledger_queue <queue_file> <old> [<new>] — sets DF_LEDGER_QUEUE to the queue file
+# a creator may append to. A queue file whose folder is named <old> or <new> is
+# answered under the folder df_ledger_folder picks for that folder's parent; a queue
+# in any other folder (the memory queue) and a path with fewer than two parts come
+# back unchanged. <new> defaults to <old>. Creates nothing; zero forks; returns 0.
+df_ledger_queue() {
+  local _file="$1" _old="$2" _new="${3:-$2}" _folder="" _parent="" _name=""
+  DF_LEDGER_QUEUE="$_file"
+  case "$_file" in */*/*) ;; *) return 0 ;; esac
+  _folder="${_file%/*}"
+  _parent="${_folder%/*}"
+  _name="${_folder##*/}"
+  case "$_name" in
+    "$_old"|"$_new")
+      df_ledger_folder "$_parent" "$_old" "$_new"
+      DF_LEDGER_QUEUE="$DF_LEDGER_FOLDER/${_file##*/}"
+      ;;
+  esac
+  return 0
+}
+
+# df_make_ledger_folder <root> <devflow_dir> <old> <new> — the one creator of the
+# ledger folder for a hook. It sets DF_LEDGER_FOLDER as df_ledger_folder does, then
+# makes the NEW folder and only the new one, and only where the old name is absent at
+# the probe and no link sits on the way down from <root> (df_no_symlink_below). Where
+# the old name is present it makes nothing, so a creator never makes the old folder:
+# a `mkdir -p` on it would bring back an empty old folder beside the new one after a
+# move had renamed it away. It logs nothing, so each hook words its own skip once.
+# A predicate: it returns 0 when nothing is left to make or the folder was made, 2 for
+# a link on the path (nothing is made), and 1 for an empty argument or a failed mkdir.
+# Call it in an `if` or an `||` list, never as a plain statement under `set -e`.
+#
+# The remaining window is the gap between the probe and the mkdir. A move that
+# finishes inside it leaves no folder this time, and the next event makes the new one.
+# An old folder that appears inside it, from an older install or by hand, leaves the
+# new folder beside it, and the next move merges the two. No data is lost either way:
+# the helper only ever makes an empty folder, and never writes into or removes one.
+df_make_ledger_folder() {
+  local _root="$1" _dir="$2" _old="$3" _new="$4"
+  [ -n "$_root" ] && [ -n "$_dir" ] && [ -n "$_old" ] && [ -n "$_new" ] || return 1
+  df_ledger_folder "$_dir" "$_old" "$_new"
+  [ "$DF_LEDGER_FOLDER" = "$_dir/$_new" ] || return 0
+  if ! df_no_symlink_below "$_root" "$DF_LEDGER_FOLDER"; then return 2; fi
+  if [ -d "$DF_LEDGER_FOLDER" ]; then return 0; fi
+  mkdir -p "$DF_LEDGER_FOLDER" 2>/dev/null || return 1
+  return 0
+}
+
+# df_global_tuning_file <machine_dir> — sets DF_GLOBAL_TUNING_FILE to the global
+# curate-agent tuning file inside the machine directory (~/.devflow). The shell
+# twin of getGlobalCurateTuningConfigPath in src/core/project-paths.ts: the one
+# place a hook names the file. Zero forks; returns 0.
+df_global_tuning_file() {
+  DF_GLOBAL_TUNING_FILE="$1/curation.json"
+  return 0
+}

package/src/assets/scripts/hooks/json-helper.cjs

@@ -2,16 +2,17 @@
 
 // src/assets/scripts/hooks/json-helper.cjs
 // Provides jq-equivalent operations for hooks when jq is not installed, and the
-// learning ops the Curate agent runs from the project root.
+// curation ops the Curate agent runs from the project root.
 // SECURITY: This is a local CLI helper invoked only by shell hooks and the
 // Curate agent with controlled arguments. No operation takes a file path: a
-// file's content arrives on stdin (json-parse redirects it), and the learning ops
+// file's content arrives on stdin (json-parse redirects it), and the curation ops
 // build every path from the current directory.
 // Usage: node json-helper.cjs <operation> [args...]
 //
 // Operations:
 //   get-field <field> [default]           Read field from stdin JSON
 //   get-string-field <field>              Read field from stdin JSON only when it is a string
+//   array-length <field>                  Count of an array field in stdin JSON; `unknown` for any other type
 //   extract-cwd-field <field>             Extract cwd + arbitrary field, SOH-byte delimited
 //   session-output <context> [message]    Build SessionStart output envelope (+ systemMessage)
 //   prompt-output <context>               Build UserPromptSubmit output envelope
@@ -36,13 +37,17 @@
 //   show <anchor|obs_id>                  Read-only: print one entry as pretty JSON
 //   claim-due                             Hand out the entries due for maintenance, leased
 //                                          for a day, after the ref their claims are checked at
-//   claim-queue                           Claim the learning queue for this run; prints
+//   claim-queue                           Claim the curation queue for this run; prints
 //                                          claimed <token>[ takeover] | busy | none
 //   release-claim <token>                 Release the claim the token owns; prints
 //                                          released | not-owner | gone
+//   move-ledger <root>                    Move a project's old ledger folder to the new name,
+//                                          once; prints none | busy | busy claim |
+//                                          skipped tracked | skipped unknown | moved <mode>
+//                                          and its backup, cause and notes
 //
-// Every learning op above except claim-queue and release-claim first refreshes
-// the mtime of an existing queue claim — the heartbeat (D-OWNED-CLAIM).
+// Every curation op above except claim-queue, release-claim and move-ledger first
+// refreshes the mtime of an existing queue claim — the heartbeat (D-OWNED-CLAIM).
 
 'use strict';
 
@@ -52,21 +57,35 @@ const { constants: { MAX_STRING_LENGTH } } = require('buffer');
 const op = process.argv[2];
 const args = process.argv.slice(3);
 
-/** The learning modules, once loaded; see learning(). */
-let learningModules = null;
+/** The curation modules, once loaded; see curation(). */
+let curationModules = null;
 
 /**
- * The learning store, loaded on first use and memoized. The generic ops never
+ * The curation store, loaded on first use and memoized. The generic ops never
  * call it, so a hook that falls back from jq to node never pays for loading it,
  * and the store loads the renderer only when an op renders.
  *
  * @returns {{ store: object }}
  */
-function learning() {
-  if (learningModules === null) {
-    learningModules = { store: require('./lib/learning-store.cjs') };
+function curation() {
+  if (curationModules === null) {
+    curationModules = { store: require('./lib/curation-store.cjs') };
   }
-  return learningModules;
+  return curationModules;
+}
+
+/** The ledger move module, once loaded; see curationMove(). */
+let curationMoveModule = null;
+
+/**
+ * The ledger move module, loaded on first use and memoized. Only the move op calls
+ * it, so no other curation op loads the move code.
+ *
+ * @returns {object}
+ */
+function curationMove() {
+  if (curationMoveModule === null) curationMoveModule = require('./lib/curation-move.cjs');
+  return curationMoveModule;
 }
 
 /** The bytes each read of stdin asks for. */
@@ -83,7 +102,7 @@ const STDIN_WAIT_CELL = new Int32Array(new SharedArrayBuffer(4));
 
 /**
  * Read stdin to its end, keeping at most `maxBytes`. Every op that reads stdin
- * reads it here, so the generic ops and the learning ops cannot read it two ways.
+ * reads it here, so the generic ops and the curation ops cannot read it two ways.
  * Never throws: a failure is a refusal.
  *
  * D-STDIN-FD0: stdin is read from file descriptor 0 itself, in reads repeated
@@ -167,14 +186,16 @@ function parseArgs(argList) {
 }
 
 // ---------------------------------------------------------------------------
-// Learning-op adapter
+// Curation-op adapter
 // ---------------------------------------------------------------------------
 
 /**
- * Print a learning op's Result: `format(value)` and a newline on stdout, or the
+ * Print a curation op's Result: `format(value)` and a newline on stdout, or the
  * error message and a newline on stderr. Returns the exit code for the op to set
  * as process.exitCode, so the process exits once, after the op has returned and
- * every lock it took is released.
+ * every lock it took is released. The error message keeps its line structure (a
+ * refusal lists one problem per line), and each line has no control character, as it
+ * may name a file the repository holds. At most REFUSAL_MAX_LINES lines print.
  *
  * @param {{ ok: true, value: unknown } | { ok: false, error: { message: string } }} result
  * @param {(value: any) => string} format - the stdout text for the value
@@ -185,10 +206,43 @@ function emit(result, format) {
     process.stdout.write(`${format(result.value)}\n`);
     return 0;
   }
-  process.stderr.write(`${result.error.message}\n`);
+  process.stderr.write(`${refusalText(result.error.message)}\n`);
   return 1;
 }
 
+/** The most lines of one refusal message that print. */
+const REFUSAL_MAX_LINES = 200;
+
+/**
+ * A refusal message with each line scrubbed (singleLine) and the line structure kept.
+ * Past REFUSAL_MAX_LINES lines, the rest become one `... N more lines` line.
+ *
+ * @param {string} message
+ * @returns {string}
+ */
+function refusalText(message) {
+  const { singleLine } = curation().store;
+  const lines = String(message).split('\n');
+  if (lines.length <= REFUSAL_MAX_LINES) return lines.map(line => singleLine(line)).join('\n');
+  const shown = lines.slice(0, REFUSAL_MAX_LINES).map(line => singleLine(line));
+  return [...shown, `... ${lines.length - REFUSAL_MAX_LINES} more lines`].join('\n');
+}
+
+/**
+ * The first line of move-ledger's answer: the state, with `moved` followed by its mode,
+ * `busy` followed by `claim` when a fresh queue claim holds the move, and `skipped`
+ * followed by its reason (`tracked` or `unknown`).
+ *
+ * @param {{ state: string, mode?: string, reason?: string }} moved
+ * @returns {string}
+ */
+function moveAnswerWord(moved) {
+  if (moved.state === 'moved') return `moved ${moved.mode}`;
+  if (moved.state === 'busy' && moved.reason === 'claim') return 'busy claim';
+  if (moved.state === 'skipped') return `skipped ${moved.reason}`;
+  return moved.state;
+}
+
 /**
  * Refuse a malformed command line: print `<op>: usage: <usage>` on stderr and exit 1,
  * before the op takes any lock.
@@ -201,11 +255,11 @@ function exitWithUsage(usage) {
   process.exit(1);
 }
 
-/** The most stdin a learning op reads: far above any valid input, so a runaway writer is refused, not parsed. */
+/** The most stdin a curation op reads: far above any valid input, so a runaway writer is refused, not parsed. */
 const STDIN_JSON_MAX_BYTES = 64 * 1024;
 
 /**
- * A learning op's stdin as one JSON object: the one way text reaches a learning
+ * A curation op's stdin as one JSON object: the one way text reaches a curation
  * op, so no field of it ever passes through argv or a shell word. Never throws.
  *
  * @param {string} opName - for the message
@@ -234,30 +288,30 @@ const PUT_MODES = new Map([['--create', 'create'], ['--update', 'update'], ['--r
 const ENTRY_TYPES = new Set(['decision', 'pitfall']);
 
 /**
- * The learning ops whose run sends the claim heartbeat first (D-OWNED-CLAIM).
+ * The curation ops whose run sends the claim heartbeat first (D-OWNED-CLAIM).
  * claim-queue and release-claim manage the claim themselves, and the generic ops
- * never touch it. A new learning op joins this set.
+ * never touch it. A new curation op joins this set.
  */
-const LEARNING_OPS = new Set([
+const CURATION_OPS = new Set([
   'assign-anchor', 'retire-anchor', 'restore-anchor', 'refresh-anchor', 'rotate-observations',
   'put-observation', 'list', 'show', 'claim-due',
 ]);
 
 /** Send the claim heartbeat; a failure is reported on stderr and never stops the op. */
 function heartbeat(root) {
-  const beat = learning().store.touchClaim(root);
+  const beat = curation().store.touchClaim(root);
   if (!beat.ok) process.stderr.write(`${beat.error.message}\n`);
 }
 
-// The learning ops run from the project root and take no path to a learning file:
+// The curation ops run from the project root and take no path to a curation file:
 // each builds its paths from the current directory. Every op that writes takes the
-// store's one learning lock through withDecisionsLock (D-ONE-LEARNING-LOCK) and
-// refuses, creating nothing, when .devflow/learning/ is absent (D-NO-STRAY-TREE)
+// store's one curation lock through withDecisionsLock (D-ONE-LEARNING-LOCK) and
+// refuses, creating nothing, when .devflow/curation/ is absent (D-NO-STRAY-TREE)
 // or when it, or .devflow, is a symbolic link (D-NO-LINKED-TREE).
 // A locked body returns its Result; emit prints it once the lock is released.
 if (require.main === module) {
 try {
-  if (LEARNING_OPS.has(op)) heartbeat(process.cwd());
+  if (CURATION_OPS.has(op)) heartbeat(process.cwd());
   switch (op) {
     case 'get-field': {
       const input = JSON.parse(readStdin());
@@ -280,6 +334,16 @@ try {
       break;
     }
 
+    case 'array-length': {
+      // The count of an array field: digits for an array, the word `unknown` for an
+      // absent field or any other type, so a caller can tell none from not reported.
+      // jq's `length` on an array agrees (json-parse json_array_length_file).
+      const input = JSON.parse(readStdin());
+      const val = getNestedField(input, args[0]);
+      console.log(Array.isArray(val) ? String(val.length) : 'unknown');
+      break;
+    }
+
     case 'extract-cwd-field': {
       // Extract cwd and an arbitrary top-level field from hook JSON in one pass.
       // Outputs: cwd + ASCII SOH (0x01) + field value (no trailing newline).
@@ -327,7 +391,6 @@ try {
       console.log(JSON.stringify({
         timestamp: data.ts || '',
         trigger: 'pre-compact',
-        memory_snapshot: data.memory || '',
         git: {
           branch: data.branch || '',
           status: data.status || '',
@@ -342,12 +405,12 @@ try {
     // assign-anchor <decision|pitfall> <obs_id>
     // Promote a v2 observation no ledger row carries to the next entry of its
     // type, skipping each number a tracked file cites (assignAnchor,
-    // learning-store.cjs: D-LEDGER-REGISTRY, D-E4-SKIP). It never writes the log.
+    // curation-store.cjs: D-LEDGER-REGISTRY, D-E4-SKIP). It never writes the log.
     // stdout: the anchor; stderr: `assign-anchor: skipped <anchor>, cited in
     // <path>:<line>` for each number skipped
     // -------------------------------------------------------------------------
     case 'assign-anchor': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 2 || !ENTRY_TYPES.has(args[0]) || !store.OBS_ID_RE.test(args[1])) {
         exitWithUsage('assign-anchor <decision|pitfall> <obs_id> (run from the project root)');
       }
@@ -366,12 +429,12 @@ try {
     // Make an active entry inactive with the one JSON object on stdin its status
     // takes: { reason } for Retired and Deprecated, { by } for Superseded, and
     // { at, quote } for Encoded, the quote checked at the verify ref
-    // (retireAnchor, learning-store.cjs: D-ENCODED-QUOTE).
+    // (retireAnchor, curation-store.cjs: D-ENCODED-QUOTE).
     // stdout: the new status in lower case and the anchor, then `repointed
     // <anchor>` for each entry re-pointed to the successor
     // -------------------------------------------------------------------------
     case 'retire-anchor': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 2 || !store.ANCHOR_ID_RE.test(args[0]) || !store.INACTIVE_STATUSES.includes(args[1])) {
         exitWithUsage('retire-anchor <anchor> <Encoded|Superseded|Retired|Deprecated> (one JSON object on stdin; run from the project root)');
       }
@@ -389,11 +452,11 @@ try {
     // Make an inactive entry active again, its notes, last_verified and
     // last_attempt cleared so it is due for maintenance again, ordered after
     // integrity problems and legacy entries, or among them when it is one
-    // (restoreAnchor, learning-store.cjs: D-DUE-ORDER).
+    // (restoreAnchor, curation-store.cjs: D-DUE-ORDER).
     // stdout: restored <anchor>
     // -------------------------------------------------------------------------
     case 'restore-anchor': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 1 || !store.ANCHOR_ID_RE.test(args[0])) {
         exitWithUsage('restore-anchor <anchor> (run from the project root)');
       }
@@ -404,12 +467,12 @@ try {
     // -------------------------------------------------------------------------
     // refresh-anchor <anchor> [<anchor>...] [--verified]
     // Re-project active v2 entries from their log rows, or under --verified stamp
-    // them verified today; all or nothing (refreshAnchors, learning-store.cjs).
+    // them verified today; all or nothing (refreshAnchors, curation-store.cjs).
     // stdout: `reprojected <anchor>` or `unchanged <anchor>` per anchor, or
     // `verified <anchor>` under --verified, in the order given
     // -------------------------------------------------------------------------
     case 'refresh-anchor': {
-      const { store } = learning();
+      const { store } = curation();
       const verifiedFlags = args.filter(arg => arg === '--verified').length;
       const anchors = args.filter(arg => arg !== '--verified');
       if (verifiedFlags > 1 || anchors.length === 0 || !anchors.every(arg => store.ANCHOR_ID_RE.test(arg))) {
@@ -424,13 +487,13 @@ try {
     // rotate-observations
     // Archive the log rows no ledger row carries once 30 days have passed since
     // their last activity, and delete the usage telemetry's leftovers
-    // (D-ROTATE-UNREFERENCED, learning-store.cjs). Takes no argument: the log and
+    // (D-ROTATE-UNREFERENCED, curation-store.cjs). Takes no argument: the log and
     // the archive are the project root's.
     // stdout: rotated <N> observations
     // -------------------------------------------------------------------------
     case 'rotate-observations': {
       if (args.length > 0) exitWithUsage('rotate-observations (no arguments; run from the project root)');
-      const result = learning().store.rotateObservations(process.cwd());
+      const result = curation().store.rotateObservations(process.cwd());
       process.exitCode = emit(result, ({ rotated }) => `rotated ${rotated} observations`);
       break;
     }
@@ -438,7 +501,7 @@ try {
     // -------------------------------------------------------------------------
     // put-observation --create|--update|--reinforce
     // Store one observation from the JSON object on stdin (D-PUT-NOT-MERGE,
-    // D-PUT-REPROJECTS, learning-store.cjs). Exactly one mode flag; no other argv.
+    // D-PUT-REPROJECTS, curation-store.cjs). Exactly one mode flag; no other argv.
     // stdout: created <id> | updated <id> | unchanged <id> | reinforced <id> <n>,
     // then one `reprojected <anchor>` line per entry re-projected
     // -------------------------------------------------------------------------
@@ -448,7 +511,7 @@ try {
         exitWithUsage('put-observation --create|--update|--reinforce (one JSON object on stdin; run from the project root)');
       }
       const input = readStdinJson('put-observation');
-      const result = input.ok ? learning().store.putObservation(process.cwd(), mode, input.value) : input;
+      const result = input.ok ? curation().store.putObservation(process.cwd(), mode, input.value) : input;
       process.exitCode = emit(result, put => [
         put.outcome === 'reinforced' ? `reinforced ${put.id} ${put.observations}` : `${put.outcome} ${put.id}`,
         ...put.reprojected.map(anchorId => `reprojected ${anchorId}`),
@@ -459,25 +522,25 @@ try {
     // -------------------------------------------------------------------------
     // list
     // Print the ledger and the log by section, read-only (readListing and
-    // formatListing, learning-store.cjs). Takes no argument.
+    // formatListing, curation-store.cjs). Takes no argument.
     // stdout: the ACTIVE, INACTIVE, OBSERVATIONS and INTEGRITY sections, then
     // MALFORMED when lines were skipped
     // -------------------------------------------------------------------------
     case 'list': {
       if (args.length > 0) exitWithUsage('list (no arguments; run from the project root)');
-      const { store } = learning();
+      const { store } = curation();
       process.exitCode = emit(store.readListing(process.cwd()), store.formatListing);
       break;
     }
 
     // -------------------------------------------------------------------------
     // show <anchor|obs_id>
-    // Print one entry, read-only (showByKey, learning-store.cjs).
+    // Print one entry, read-only (showByKey, curation-store.cjs).
     // stdout: pretty JSON { key, ledger, log, history_versions, flags }, plus
     // malformed when lines were skipped
     // -------------------------------------------------------------------------
     case 'show': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 1 || !(store.ANCHOR_ID_RE.test(args[0]) || store.OBS_ID_RE.test(args[0]))) {
         exitWithUsage('show <anchor|obs_id> (run from the project root)');
       }
@@ -488,13 +551,13 @@ try {
     // -------------------------------------------------------------------------
     // claim-due
     // Hand out the entries due for maintenance and lease each for a day
-    // (claimDue, learning-store.cjs: D-DUE-ORDER, D-VERIFY-REF). Takes no argument.
+    // (claimDue, curation-store.cjs: D-DUE-ORDER, D-VERIFY-REF). Takes no argument.
     // stdout: ref <origin/HEAD|HEAD> <sha12>, or ref none; then one
     // `<anchor> <reason> <bytes>` line per entry handed out, or due none
     // -------------------------------------------------------------------------
     case 'claim-due': {
       if (args.length > 0) exitWithUsage('claim-due (no arguments; run from the project root)');
-      const { store } = learning();
+      const { store } = curation();
       process.exitCode = emit(store.claimDue(process.cwd()), ({ ref, due }) => [
         ref === null ? 'ref none' : `ref ${ref.ref} ${ref.commit.slice(0, 12)}`,
         ...(due.length > 0 ? due.map(entry => `${store.singleLine(entry.anchor_id)} ${entry.reason} ${entry.bytes}`) : ['due none']),
@@ -504,13 +567,13 @@ try {
 
     // -------------------------------------------------------------------------
     // claim-queue
-    // Claim the learning queue for this run (D-OWNED-CLAIM, learning-store.cjs).
+    // Claim the curation queue for this run (D-OWNED-CLAIM, curation-store.cjs).
     // Takes no argument; mints the token itself.
     // stdout: claimed <token> | claimed <token> takeover | busy | none
     // -------------------------------------------------------------------------
     case 'claim-queue': {
       if (args.length > 0) exitWithUsage('claim-queue (no arguments; run from the project root)');
-      const result = learning().store.claimQueue(process.cwd());
+      const result = curation().store.claimQueue(process.cwd());
       process.exitCode = emit(result, claim => (claim.state === 'claimed'
         ? `claimed ${claim.token}${claim.takeover ? ' takeover' : ''}`
         : claim.state));
@@ -519,11 +582,11 @@ try {
 
     // -------------------------------------------------------------------------
     // release-claim <token>
-    // Release the claim the token owns (D-OWNED-CLAIM, learning-store.cjs).
+    // Release the claim the token owns (D-OWNED-CLAIM, curation-store.cjs).
     // stdout: released | not-owner | gone
     // -------------------------------------------------------------------------
     case 'release-claim': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 1 || !store.CLAIM_TOKEN_RE.test(args[0])) {
         exitWithUsage('release-claim <token> (the 16 hex characters claim-queue printed)');
       }
@@ -531,12 +594,43 @@ try {
       break;
     }
 
+    // -------------------------------------------------------------------------
+    // move-ledger <root>
+    // Move the project's old ledger folder to the new name, once (moveLedger,
+    // curation-move.cjs). Not a curation op: it sends no heartbeat, because a
+    // heartbeat would refresh a claim the move has to judge stale. Unlike the
+    // curation ops it takes the root as an argument, so a caller outside the project
+    // root can name it; the root stays one argv word, never a shell word. The two
+    // folder names are the path helpers' own: no argument names them.
+    // stdout: none | busy | busy claim | skipped tracked | skipped unknown | moved <mode>,
+    // then `backup <name>` when a backup was made, `cause <word>` for `skipped unknown`
+    // (one fixed word that says why git did not answer), and one `note <text>` line for
+    // each note. `busy claim` means a fresh queue claim holds the move, which can last 15
+    // minutes; plain `busy` means a lock does. `skipped tracked` means git tracks files in
+    // a curation data folder, `skipped unknown` that git did not answer: nothing changed.
+    // Every line is scrubbed here (singleLine):
+    // a note may name a file the repository holds, and no line may carry a control
+    // character or break into two.
+    // -------------------------------------------------------------------------
+    case 'move-ledger': {
+      if (args.length !== 1) exitWithUsage('move-ledger <root> (the root is an absolute path)');
+      const { store } = curation();
+      process.exitCode = emit(curationMove().moveLedger(args[0]), moved => [
+        moveAnswerWord(moved),
+        ...(moved.state === 'moved' && moved.backup !== null ? [`backup ${moved.backup}`] : []),
+        ...(moved.state === 'skipped' && moved.cause !== undefined ? [`cause ${moved.cause}`] : []),
+        ...moved.notes.map(note => `note ${note}`),
+      ].map(line => store.singleLine(line)).join('\n'));
+      break;
+    }
+
     default:
       process.stderr.write(`json-helper: unknown operation "${op}"\n`);
       process.exit(1);
   }
 } catch (err) {
-  process.stderr.write(`json-helper error: ${err && err.message ? err.message : String(err)}\n`);
+  const reason = err && err.message ? err.message : String(err);
+  process.stderr.write(`json-helper error: ${curationModules === null ? reason : curationModules.store.singleLine(reason)}\n`);
   process.exit(1);
 }
 } // end if (require.main === module)

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

@@ -69,6 +69,21 @@ json_string_field_file() {
   fi
 }
 
+# The element count of an array field in a JSON file. Usage: json_array_length_file "/path/to/file.json" "field"
+# Prints the count as digits when the field is an array, and the word `unknown` for an
+# absent field or any other type (a number, string, object, boolean or null), so a
+# caller can tell "none" from "not reported". Prints nothing, and fails, when the file
+# cannot be read or parsed. Silent on stderr and read the same way on both backends
+# (the node path reads the file on stdin, with its stderr redirected first).
+json_array_length_file() {
+  local file="$1" field="$2"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -r "(try .$field catch null) | if type == \"array\" then length else \"unknown\" end" "$file" 2>/dev/null
+  else
+    node "$_JSON_HELPER" array-length "$field" 2>/dev/null < "$file"
+  fi
+}
+
 # --- Multi-field batched extraction ---
 
 # Extract cwd and an arbitrary top-level field from stdin JSON in a single
@@ -103,9 +118,9 @@ json_extract_cwd_prompt() {
 # 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:
+# envelope holds the context alone, byte for byte (ensure-proxy and
+# session-start-orchestrator pass one; session-start-context and session-start-memory
+# pass two). 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.
@@ -155,7 +170,7 @@ json_prompt_output() {
 # Build pre-compact backup JSON. Usage: json_backup_construct --arg ts X --arg branch Y ...
 json_backup_construct() {
   if [ "$_HAS_JQ" = "true" ]; then
-    jq -n "$@" '{timestamp: $ts, trigger: "pre-compact", memory_snapshot: $memory, git: {branch: $branch, status: $status, log: $log, diff_stat: $diff}}'
+    jq -n "$@" '{timestamp: $ts, trigger: "pre-compact", git: {branch: $branch, status: $status, log: $log, diff_stat: $diff}}'
   else
     node "$_JSON_HELPER" backup-construct "$@"
   fi