devflow-kit 3.7.0 → 3.9.0

package/src/assets/scripts/hooks/lib/{learning-store.cjs → curation-store.cjs}

@@ -1,55 +1,65 @@
-// src/assets/scripts/hooks/lib/learning-store.cjs
+// src/assets/scripts/hooks/lib/curation-store.cjs
 //
-// The v2 learning store: the one place the learning plumbing reads, validates,
+// The v2 curation store: the one place the curation plumbing reads, validates,
 // projects and writes the decisions log, the ledger and their side files.
 //
 // DESIGN: plumbing only. No function here prints or calls process.exit. Work that
 // can fail on its input or on the lock returns a Result — { ok: true, value } or
 // { ok: false, error: { kind, message } } — and its caller prints it: json-helper.cjs
-// for the ops, or the `devflow learning` CLI through src/core/learning-store.ts. A throw
+// for the ops, or the `devflow curation` CLI through src/core/curation-store.ts. A throw
 // means a broken invariant or an I/O failure, never an expected outcome; a lock
 // held by withDecisionsLock is released on every path, the throw included.
 //
-// Loading: node built-ins and three sibling libs only. This module never requires
+// Loading: node built-ins and four sibling libs only (the path helpers, the lock, the
+// path guard and the tracked-areas check). This module never requires
 // decisions-format.cjs or render-decisions.cjs at load time: both require it, for
 // the status list and the one-line and inactive-note text they share with `list`.
 //
-// Files under <root>/.devflow/learning/:
+// The one-time move of the old ledger folder to its new name is not here: it lives in
+// curation-move.cjs, which requires this module. The store holds only the guard that
+// keeps its writers off an unfinished move (withDecisionsLock reads the move journal),
+// so a store write loads no move code.
+//
+// Files under <root>/.devflow/curation/:
 //   decisions-log.jsonl          observation rows — the content authority
 //   decisions-ledger.jsonl       anchored rows — projections of log rows
 //   decisions-log.archive.jsonl  rotated-out observation rows (D-ROTATE-UNREFERENCED)
 //   decisions-history.jsonl      prior content versions (D-CONTENT-HISTORY)
 //   *.rejected.jsonl             quarantined malformed lines (D-QUARANTINE-MALFORMED)
 //   *.pre-v2.jsonl               one-time copies of the v1 files (D-V1-BACKUP-ONCE)
-//   .decisions.lock/             the one learning lock (D-ONE-LEARNING-LOCK)
+//   .decisions.lock/             the one curation lock (D-ONE-LEARNING-LOCK)
 //   .pending-turns.jsonl         the queue the capture hooks append to
 //   .pending-turns.processing    the claimed batch, and .pending-turns.owner its
 //                                owner's token (D-OWNED-CLAIM)
 //
 // TS COUNTERPARTS: src/core/observations.ts mirrors the status lists (D201), and
-// src/core/learning-store.ts transcribes the functions the CLI calls from their
+// src/core/curation-store.ts transcribes the functions the CLI calls from their
 // JSDoc here (D-LEARNING-STORE-SEAM) — change both together.
 
 'use strict';
 
 const crypto = require('crypto');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
 const {
-  getLearningDir,
-  getLearningPendingTurnsPath,
-  getLearningPendingTurnsProcessingPath,
-  getLearningClaimOwnerPath,
+  LEGACY_NAMES,
+  getCurationDir,
+  getCurationPendingTurnsPath,
+  getCurationPendingTurnsProcessingPath,
+  getCurationClaimOwnerPath,
   getDecisionsLedgerPath,
   getDecisionsLogPath,
   getDecisionsArchivePath,
   getDecisionsHistoryPath,
   getDecisionsLockDir,
+  curationMoveJournalPath,
 } = require('./project-paths.cjs');
 const { acquireMkdirLock, releaseLock } = require('./mkdir-lock.cjs');
 const { safePath } = require('./safe-path.cjs');
+const { inspectTrackedAreaOnce } = require('./tracked-areas.cjs');
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -401,17 +411,17 @@ function readTextUnlinked(file, { maxBytes = Infinity } = {}) {
  * delete them without a trace, and a reader that quarantined would make list,
  * show and the HUD write files.
  *
- * D-NO-LINKED-READ: a learning file that is itself a symbolic link reads as
+ * D-NO-LINKED-READ: a curation file that is itself a symbolic link reads as
  * missing, and nothing is read through it; the pre-v2 backup skips one the same
  * way (ensurePreV2Backup), and release-claim reads the claim's owner file the same
  * way, and only up to CLAIM_OWNER_MAX_BYTES (readClaimOwner). readJsonl and
  * readClaimOwner read a regular file alone (readTextUnlinked): a directory, a FIFO
  * or a device where the file belongs reads as missing too, and neither waits on
- * one. Reason: a repository can commit any learning file as a link to a file
+ * one. Reason: a repository can commit any curation file as a link to a file
  * elsewhere on the machine, and a read that followed it would put that file's
  * lines into list and show and, through a rewrite, the quarantine or a render,
- * into the project's learning folder; a read that followed one to a FIFO or to
- * /dev/zero would wait forever or fill memory, holding the learning lock when a
+ * into the project's curation folder; a read that followed one to a FIFO or to
+ * /dev/zero would wait forever or fill memory, holding the curation lock when a
  * writer or release-claim reads. The writers never write through a link either:
  * a rename replaces one, and an append refuses one.
  *
@@ -448,11 +458,16 @@ function rejectedPathFor(file) {
 
 /**
  * Append to `file`, creating it when absent. O_NOFOLLOW refuses a symlink planted
- * at `file` (ELOOP) instead of writing through it.
+ * at `file` (ELOOP) instead of writing through it. A file this call creates gets
+ * `mode`, as an explicit open mode (the process umask can only remove bits from it).
+ *
+ * @param {string} file
+ * @param {string} content
+ * @param {number} [mode] - the mode of a created file (default 0o666, as the umask leaves it)
  */
-function appendNoFollow(file, content) {
+function appendNoFollow(file, content, mode = 0o666) {
   const flags = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | (fs.constants.O_NOFOLLOW || 0);
-  const fd = fs.openSync(file, flags, 0o666);
+  const fd = fs.openSync(file, flags, mode);
   try {
     fs.writeFileSync(fd, content);
   } finally {
@@ -467,17 +482,18 @@ function appendNoFollow(file, content) {
  *
  * @param {string} file - the file the lines were read from
  * @param {Array<{ line: number, text: string }>} rejected
- * @param {{ now?: number }} [opts] - now: epoch ms (default Date.now())
+ * @param {{ now?: number, mode?: number }} [opts] - now: epoch ms (default Date.now());
+ *   mode: the mode of a quarantine file this call creates (default as the umask leaves it)
  * @returns {number} the number of records appended
  */
-function quarantineRejected(file, rejected, { now = Date.now() } = {}) {
+function quarantineRejected(file, rejected, { now = Date.now(), mode } = {}) {
   if (rejected.length === 0) return 0;
   const rejectedAt = new Date(now).toISOString();
   const source = path.basename(file);
   const content = rejected
     .map(r => JSON.stringify({ rejected_at: rejectedAt, source, line: r.line, text: r.text }))
     .join('\n') + '\n';
-  appendNoFollow(rejectedPathFor(file), content);
+  appendNoFollow(rejectedPathFor(file), content, mode);
   return rejected.length;
 }
 
@@ -545,14 +561,14 @@ function writeJsonlAtomic(file, rows) {
 // ---------------------------------------------------------------------------
 
 /**
- * True when `<root>/.devflow/learning` exists and is a directory.
+ * True when `<root>/.devflow/curation` exists and is a directory.
  *
  * @param {string} root - project root
  * @returns {boolean}
  */
-function hasLearningDir(root) {
+function hasCurationDir(root) {
   try {
-    return fs.statSync(getLearningDir(root)).isDirectory();
+    return fs.statSync(getCurationDir(root)).isDirectory();
   } catch (err) {
     if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return false;
     throw err;
@@ -560,17 +576,17 @@ function hasLearningDir(root) {
 }
 
 /**
- * The error Result of an op run where `<root>/.devflow/learning/` is absent
+ * The error Result of an op run where `<root>/.devflow/curation/` is absent
  * (D-NO-STRAY-TREE).
  *
  * @param {string} opName - operation name, for the message
  * @param {string} root - project root
- * @returns {{ ok: false, error: { kind: 'no-learning-dir', message: string } }}
+ * @returns {{ ok: false, error: { kind: 'no-curation-dir', message: string } }}
  */
-function noLearningDir(opName, root) {
+function noCurationDir(opName, root) {
   return {
     ok: false,
-    error: { kind: 'no-learning-dir', message: `${opName}: no .devflow/learning/ under ${root} — run from the project root` },
+    error: { kind: 'no-curation-dir', message: `${opName}: no .devflow/curation/ under ${root} — run from the project root` },
   };
 }
 
@@ -585,22 +601,22 @@ function isSymbolicLink(file) {
 }
 
 /**
- * The first of `<root>/.devflow` and `<root>/.devflow/learning` that is itself a
+ * The first of `<root>/.devflow` and `<root>/.devflow/curation` that is itself a
  * symbolic link, or null when neither is (D-NO-LINKED-TREE).
  *
  * @param {string} root - project root
  * @returns {string|null}
  */
-function linkedLearningFolder(root) {
-  const learningDir = getLearningDir(root);
-  for (const dir of [path.dirname(learningDir), learningDir]) {
+function linkedCurationFolder(root) {
+  const curationDir = getCurationDir(root);
+  for (const dir of [path.dirname(curationDir), curationDir]) {
     if (isSymbolicLink(dir)) return dir;
   }
   return null;
 }
 
 /**
- * The error Result of an op run where `.devflow` or `.devflow/learning` under its
+ * The error Result of an op run where `.devflow` or `.devflow/curation` under its
  * root is a symbolic link (D-NO-LINKED-TREE).
  *
  * @param {string} opName - operation name, for the message
@@ -614,6 +630,112 @@ function linkedFolder(opName, dir) {
   };
 }
 
+/**
+ * The refusal of an op run where git tracks files in the curation data folders under
+ * `root` (the curation folder, the old ledger folder and the backup folders), or does
+ * not say whether it does, or null where git tracks none. A folder that git tracks is the
+ * repository's content, so the curation feature is paused there: the op reads and writes
+ * nothing. The messages state the fact and name no command; the root is shown so the
+ * folder can be found. The check asks git about the index, not the disk, so it holds
+ * whether or not the folder is on disk, and it makes no git call for a root with no `.git`
+ * entry. It comes first in every op, before a ledger file is read, a lock is taken or a git
+ * call of the op's own is made. The answer is asked once per root for the life of the
+ * process (inspectTrackedAreaOnce), so the heartbeat, the op and its lock share one call.
+ *
+ * The refusal carries `reason`, `tracked` where git tracks files and `unknown` where it
+ * did not answer, so a caller that picks a notice reads the field, never the message.
+ *
+ * @param {string} opName - operation name, for the message
+ * @param {string} root - project root
+ * @returns {{ ok: false, error: { kind: 'tracked', reason: 'tracked'|'unknown', message: string } } | null}
+ */
+function trackedCurationArea(opName, root) {
+  const { answer } = inspectTrackedAreaOnce(root, 'curation');
+  if (answer === 'untracked') return null;
+  const reason = answer === 'tracked' ? 'tracked' : 'unknown';
+  const fact = reason === 'tracked' ? 'git tracks files' : 'git did not answer whether it tracks files';
+  return {
+    ok: false,
+    error: { kind: 'tracked', reason, message: `${opName}: ${fact} in the curation data folders under ${root}; nothing was written` },
+  };
+}
+
+/** The Stats of `file` without following a link, or null when nothing is there. */
+function lstatOrNull(file) {
+  try {
+    return fs.lstatSync(file);
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return null;
+    throw err;
+  }
+}
+
+/** The physical path of `target`, or its resolved path when it does not exist yet. */
+function physicalPath(target) {
+  try {
+    return fs.realpathSync(target);
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return path.resolve(target);
+    throw err;
+  }
+}
+
+/** The home directory: `HOME`, else the passwd entry, else null. */
+function homeDirOrNull() {
+  if (process.env.HOME) return process.env.HOME;
+  try {
+    return os.homedir() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Where a root's move journal is, resolved the way moveLedger resolves its machine
+ * directory (`$HOME/.devflow`) and the root's key (the root's physical path); null when
+ * no home directory is known.
+ */
+function moveJournalPathOrNull(root) {
+  const home = homeDirOrNull();
+  if (home === null) return null;
+  return curationMoveJournalPath(path.join(home, '.devflow'), physicalPath(path.resolve(root)));
+}
+
+/**
+ * Remove a machine-side journal whose old folder is gone: it has no set left to
+ * finish. Only a regular file is removed, never a link or any other entry, and nothing
+ * is followed. It never throws: a journal that cannot be removed (EACCES, EPERM, EROFS
+ * on the machine directory) stays, and the writer goes on, because the journal holds
+ * no writer once its old folder is gone. A later write tries again.
+ *
+ * @param {string} journal
+ */
+function dropStaleMoveJournal(journal) {
+  try {
+    const stat = lstatOrNull(journal);
+    if (stat === null || !stat.isFile()) return;
+    removeIfPresent(journal);
+  } catch {
+    // Best effort only: see the note above.
+  }
+}
+
+/**
+ * Whether the journal at `journal` holds store writers off: it exists and the old
+ * folder it belongs to still exists. A journal whose old folder is gone is stale and is
+ * dropped (dropStaleMoveJournal), and the writer goes on.
+ *
+ * @param {string} journal
+ * @param {string} oldFolder
+ * @returns {boolean}
+ */
+function moveJournalHoldsWriters(journal, oldFolder) {
+  if (lstatOrNull(journal) === null) return false;
+  if (lstatOrNull(oldFolder) !== null) return true;
+  dropStaleMoveJournal(journal);
+  return false;
+}
+
 /** True for a Result: `{ ok: true, … }` or `{ ok: false, error: { … } }`. */
 function isResult(value) {
   return isPlainObject(value) && (value.ok === true || (value.ok === false && isPlainObject(value.error)));
@@ -624,50 +746,71 @@ function isResult(value) {
  * The lock is released on every path, a throw from `fn` included; the throw then
  * reaches the caller.
  *
- * D-ONE-LEARNING-LOCK: learning writers take one lock, `.decisions.lock`, through
+ * D-ONE-LEARNING-LOCK: curation writers take one lock, `.decisions.lock`, through
  * this wrapper — every write to the log, the ledger, their side files and the
  * rendered files happens under it. Reason: two writers under two locks can each
  * read one file, change it and rename their copy over it, and the second rename
  * silently discards the first one's change.
  *
- * D-NO-STRAY-TREE: a learning writer refuses with `no-learning-dir` when
- * `.devflow/learning/` is absent under its root, and the store never creates that
+ * D-NO-STRAY-TREE: a curation writer refuses with `no-curation-dir` when
+ * `.devflow/curation/` is absent under its root, and the store never creates that
  * directory or its parent — the lock directory is the only thing made inside it.
- * Reason: a writer run from the wrong directory would otherwise create a learning
+ * Reason: a writer run from the wrong directory would otherwise create a curation
  * tree there and write a ledger that no session ever reads.
  *
- * D-NO-LINKED-TREE: a learning writer refuses with `not-a-directory`, changing
- * nothing, when `.devflow` or `.devflow/learning` under its root is a symbolic
+ * An unfinished ledger move (a move journal in the machine directory, next to the move
+ * lock, see moveLedger in curation-move.cjs) makes every writer answer `busy` without taking the lock, so no
+ * write lands between two renames of the move's ledger set. The journal is checked
+ * again once the lock is held: a move can start, and stop part way through the set,
+ * while the writer waits for the lock. Only the machine-side file counts, and only
+ * while the old folder it belongs to exists (moveJournalHoldsWriters): a file in the
+ * repository's old folder is repository content and is never read. With no home
+ * directory no move can have started (moveLedger refuses without a machine directory),
+ * so there is no journal to find and the writer goes on.
+ *
+ * D-NO-LINKED-TREE: a curation writer refuses with `not-a-directory`, changing
+ * nothing, when `.devflow` or `.devflow/curation` under its root is a symbolic
  * link. Reason: a repository can commit either one as a link to a folder elsewhere
  * on the machine, and a writer that followed it would take its lock there and
  * rewrite, quarantine, archive, render or delete files in whatever folder the link
  * names. Refused here, before the lock is taken, so every writer refuses in one
  * place; the claim heartbeat makes the same check, and read-only paths still read.
  *
+ * A writer also refuses with `tracked`, changing nothing, where git tracks files in the
+ * curation data folders under its root, or does not say whether it does
+ * (trackedCurationArea). That check follows the link check and comes before the journal,
+ * the folder check and the lock, so a paused project gets no lock folder.
+ *
  * @param {string} opName - operation name, for messages
  * @param {string} root - project root
  * @param {() => { ok: boolean }} fn - the locked body; it must return a Result
  * @param {{ timeoutMs?: number, staleMs?: number }} [opts]
  * @returns {{ ok: true, value?: unknown } | { ok: false, error: { kind: string, message: string } }}
- *   fn's Result, or an error of kind `not-a-directory`, `no-learning-dir` or `busy`.
+ *   fn's Result, or an error of kind `not-a-directory`, `tracked`, `no-curation-dir` or `busy`.
  */
 function withDecisionsLock(opName, root, fn, { timeoutMs = LOCK_ACQUIRE_TIMEOUT_MS, staleMs = LOCK_STALE_MS } = {}) {
-  const linked = linkedLearningFolder(root);
+  const linked = linkedCurationFolder(root);
   if (linked !== null) return linkedFolder(opName, linked);
-  if (!hasLearningDir(root)) return noLearningDir(opName, root);
+  const paused = trackedCurationArea(opName, root);
+  if (paused !== null) return paused;
+  const journal = moveJournalPathOrNull(root);
+  const oldFolder = path.join(root, '.devflow', LEGACY_NAMES.folder);
+  if (journal !== null && moveJournalHoldsWriters(journal, oldFolder)) return unfinishedMove(opName, journal);
+  if (!hasCurationDir(root)) return noCurationDir(opName, root);
   const lockDir = getDecisionsLockDir(root);
   let acquired;
   try {
     acquired = acquireMkdirLock(lockDir, timeoutMs, staleMs);
   } catch (err) {
-    // The learning directory went away between the check and the mkdir.
-    if (err && err.code === 'ENOENT') return noLearningDir(opName, root);
+    // The curation directory went away between the check and the mkdir.
+    if (err && err.code === 'ENOENT') return noCurationDir(opName, root);
     throw err;
   }
   if (!acquired) {
     return { ok: false, error: { kind: 'busy', message: `${opName}: timeout acquiring lock at ${lockDir}` } };
   }
   try {
+    if (journal !== null && moveJournalHoldsWriters(journal, oldFolder)) return unfinishedMove(opName, journal);
     const result = fn();
     if (!isResult(result)) {
       throw new TypeError(`${opName}: the locked body must return a Result ({ ok: true, value } or { ok: false, error })`);
@@ -678,6 +821,14 @@ function withDecisionsLock(opName, root, fn, { timeoutMs = LOCK_ACQUIRE_TIMEOUT_
   }
 }
 
+/** The `busy` Result of a writer that finds an unfinished ledger move's journal. */
+function unfinishedMove(opName, journal) {
+  return {
+    ok: false,
+    error: { kind: 'busy', message: `${opName}: an unfinished ledger move is recorded at ${journal}; it finishes at the next session start or devflow init` },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // State and the ledger registry
 // ---------------------------------------------------------------------------
@@ -690,7 +841,7 @@ function withDecisionsLock(opName, root, fn, { timeoutMs = LOCK_ACQUIRE_TIMEOUT_
  * @param {string} root - project root
  * @returns {{ ledgerRows: object[], logRows: object[], rejected: { ledger: Array<{ line: number, text: string }>, log: Array<{ line: number, text: string }> } }}
  */
-function readLearningState(root) {
+function readCurationState(root) {
   const ledger = readJsonl(getDecisionsLedgerPath(root));
   const log = readJsonl(getDecisionsLogPath(root));
   return {
@@ -1191,7 +1342,7 @@ function ensurePreV2Backup(root, { logRows = [], ledgerRows = [] } = {}) {
 /** Days of inactivity after which an observation no ledger row carries leaves the log (D-ROTATE-UNREFERENCED). */
 const ROTATE_AGE_DAYS = 30;
 
-/** What an older install's usage telemetry left in the learning directory: a file and a lock directory. */
+/** What an older install's usage telemetry left in the curation directory: a file and a lock directory. */
 const USAGE_LEFTOVERS = Object.freeze(['.decisions-usage.json', '.decisions-usage.lock']);
 
 /**
@@ -1221,7 +1372,7 @@ function lastActivityMs(row) {
  * anchor_id copied onto a log row can say what to keep, and a dedup by id dropped
  * the newer version of a row whose older version was already archived.
  *
- * Under the learning lock it first deletes the usage leftovers. When no row is
+ * Under the curation lock it first deletes the usage leftovers. When no row is
  * due it writes nothing else. When rows are due it backs up a v1 tree
  * (D-V1-BACKUP-ONCE) and quarantines the log's malformed lines
  * (D-QUARANTINE-MALFORMED) before it appends to the archive and rewrites the log;
@@ -1232,12 +1383,12 @@ function lastActivityMs(row) {
  * @param {{ now?: number, timeoutMs?: number }} [opts] - now: epoch ms (default Date.now())
  * @returns {{ ok: true, value: { rotated: number, appended: number } } | { ok: false, error: { kind: string, message: string } }}
  *   rotated: rows removed from the log; appended: rows added to the archive.
- *   Errors are withDecisionsLock's not-a-directory, no-learning-dir and busy.
+ *   Errors are withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  */
 function rotateObservations(root, { now = Date.now(), timeoutMs } = {}) {
   return withDecisionsLock('rotate-observations', root, () => {
     for (const name of USAGE_LEFTOVERS) {
-      fs.rmSync(path.join(getLearningDir(root), name), { recursive: true, force: true });
+      fs.rmSync(path.join(getCurationDir(root), name), { recursive: true, force: true });
     }
 
     const logPath = getDecisionsLogPath(root);
@@ -1276,7 +1427,7 @@ function rotateObservations(root, { now = Date.now(), timeoutMs } = {}) {
 // ---------------------------------------------------------------------------
 
 /**
- * Drop the observations no entry uses — `devflow learning --clear`.
+ * Drop the observations no entry uses — `devflow curation --clear`.
  *
  * D-CLEAR-UNREFERENCED: clearing removes from the log exactly the rows no ledger
  * row carries (D-LEDGER-REGISTRY), whatever their age or status, and keeps every
@@ -1286,7 +1437,7 @@ function rotateObservations(root, { now = Date.now(), timeoutMs } = {}) {
  * row that is its content authority, and refresh then refused them all — and a
  * malformed ledger line may be the one carrying a row clearing would drop.
  *
- * It runs under the learning lock (D-ONE-LEARNING-LOCK). When a row is dropped it
+ * It runs under the curation lock (D-ONE-LEARNING-LOCK). When a row is dropped it
  * backs up a v1 tree (D-V1-BACKUP-ONCE) and quarantines the log's malformed lines
  * (D-QUARANTINE-MALFORMED) before it rewrites the log; with nothing to drop it
  * writes nothing.
@@ -1295,7 +1446,7 @@ function rotateObservations(root, { now = Date.now(), timeoutMs } = {}) {
  * @param {{ now?: number, timeoutMs?: number }} [opts] - now: epoch ms (default Date.now())
  * @returns {{ ok: true, value: { cleared: number, kept: number } } | { ok: false, error: { kind: string, message: string } }}
  *   cleared: rows removed from the log; kept: rows left in it. Error kinds:
- *   ledger-malformed, and withDecisionsLock's not-a-directory, no-learning-dir and busy.
+ *   ledger-malformed, and withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  */
 function clearUnreferenced(root, { now = Date.now(), timeoutMs } = {}) {
   return withDecisionsLock('clear', root, () => {
@@ -1340,11 +1491,11 @@ function removeEmptyDir(dir) {
 }
 
 /**
- * Remove every learning file — `devflow learning --reset`: the log, the ledger
+ * Remove every curation file — `devflow curation --reset`: the log, the ledger
  * and their side files, the rendered files, the tuning config, and the queue
- * with its claim and owner file — and then the learning directory itself.
+ * with its claim and owner file — and then the curation directory itself.
  *
- * D-RESET-UNDER-LOCK: reset empties the learning directory under the learning
+ * D-RESET-UNDER-LOCK: reset empties the curation directory under the curation
  * lock, sparing only the lock directory, and removes the emptied directory once
  * the lock is released, and only if nothing has arrived in it. Reason: the lock
  * is released by its path, so removing it with the directory would let this
@@ -1352,8 +1503,8 @@ function removeEmptyDir(dir) {
  * and what arrives once the lock is free — a captured turn, or the next writer's
  * lock — belongs to the next run.
  *
- * Like every learning writer it refuses without `.devflow/learning/` and creates
- * nothing (D-NO-STRAY-TREE), refuses a learning directory or a `.devflow` that is a
+ * Like every curation writer it refuses without `.devflow/curation/` and creates
+ * nothing (D-NO-STRAY-TREE), refuses a curation directory or a `.devflow` that is a
  * symbolic link and removes nothing (D-NO-LINKED-TREE), since emptying it would
  * empty whatever directory the link leads to, and waits at most `timeoutMs` for the
  * lock, breaking one a crashed run left behind (D-ONE-LEARNING-LOCK). A symbolic
@@ -1362,18 +1513,18 @@ function removeEmptyDir(dir) {
  * @param {string} root - project root
  * @param {{ timeoutMs?: number }} [opts]
  * @returns {{ ok: true, value: { removed: number } } | { ok: false, error: { kind: string, message: string } }}
- *   removed: the entries removed from the learning directory. Errors are
- *   withDecisionsLock's not-a-directory, no-learning-dir and busy.
+ *   removed: the entries removed from the curation directory. Errors are
+ *   withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  */
-function resetLearning(root, { timeoutMs } = {}) {
-  const learningDir = getLearningDir(root);
+function resetCuration(root, { timeoutMs } = {}) {
+  const curationDir = getCurationDir(root);
   const lockName = path.basename(getDecisionsLockDir(root));
   const reset = withDecisionsLock('reset', root, () => {
-    const entries = fs.readdirSync(learningDir).filter(name => name !== lockName);
-    for (const name of entries) fs.rmSync(path.join(learningDir, name), { recursive: true, force: true });
+    const entries = fs.readdirSync(curationDir).filter(name => name !== lockName);
+    for (const name of entries) fs.rmSync(path.join(curationDir, name), { recursive: true, force: true });
     return { ok: true, value: { removed: entries.length } };
   }, { timeoutMs });
-  if (reset.ok) removeEmptyDir(learningDir);
+  if (reset.ok) removeEmptyDir(curationDir);
   return reset;
 }
 
@@ -1391,7 +1542,7 @@ const CLAIM_STALE_SECS = 900;
 /** How long a claim waits for the queue's own lock (ms): the wait of queue-append's overflow truncation. */
 const QUEUE_LOCK_TIMEOUT_MS = 2000;
 
-/** Age after which the queue's own lock counts as abandoned (ms): learning-lock's threshold. */
+/** Age after which the queue's own lock counts as abandoned (ms): curation-lock's threshold. */
 const QUEUE_LOCK_STALE_MS = 30000;
 
 /** A claim token: 16 lowercase hex characters. */
@@ -1462,7 +1613,7 @@ function removeIfPresent(file) {
  * larger than CLAIM_OWNER_MAX_BYTES reads as absent (D-NO-LINKED-READ, at readJsonl).
  */
 function readClaimOwner(root) {
-  const text = readTextUnlinked(getLearningClaimOwnerPath(root), { maxBytes: CLAIM_OWNER_MAX_BYTES });
+  const text = readTextUnlinked(getCurationClaimOwnerPath(root), { maxBytes: CLAIM_OWNER_MAX_BYTES });
   if (text === null) return null;
   const token = text.trim();
   return CLAIM_TOKEN_RE.test(token) ? token : null;
@@ -1473,7 +1624,7 @@ function readClaimOwner(root) {
  * queue-append's overflow truncation takes, so a truncation can never rewrite the
  * queue from rows already claimed. link(2) refuses an existing claim; on a
  * filesystem without hard links a rename stands in, which is safe because the
- * caller found the claim path empty under the learning lock. A row a capture hook
+ * caller found the claim path empty under the curation lock. A row a capture hook
  * appends meanwhile lands in the claimed batch or in the queue formed after it,
  * never in neither.
  *
@@ -1516,22 +1667,23 @@ function moveQueueToClaim(queuePath, claimPath) {
 }
 
 /**
- * Claim the learning queue for one Curate run.
+ * Claim the curation queue for one Curate run.
  *
- * D-OWNED-CLAIM: the learning queue is claimed and released only through the
- * claim-queue and release-claim ops, under the learning lock. A claim moves the
+ * D-OWNED-CLAIM: the curation queue is claimed and released only through the
+ * claim-queue and release-claim ops, under the curation lock. A claim moves the
  * queue to .pending-turns.processing by link(2), under the queue's own lock (a
  * rename stands in only where the filesystem has no hard links), sets the claim's
  * mtime to now and records a fresh random token in .pending-turns.owner. A claim
  * younger than CLAIM_STALE_SECS is busy to every other claimant; an older one is
  * taken over with a new token, and the waiting queue is left for the next claim.
  * Release deletes the claim only for the token that owns it, and every json-helper
- * learning op refreshes an existing claim's mtime before it runs, without ever
+ * curation op refreshes an existing claim's mtime before it runs, without ever
  * creating one. Reason: a check-then-mv claim let two runs claim at once and
  * clobber a batch, mv kept the queue's old mtime so a fresh claim could look stale
  * at once, and an unconditional final unlink deleted another run's claim.
  *
- * Without .devflow/learning/ it answers none and creates nothing.
+ * Without .devflow/curation/ it answers none and creates nothing; where git tracks files
+ * in the curation data folders it refuses, kind `tracked`, before it looks (trackedCurationArea).
  *
  * @param {string} root - project root
  * @param {{ now?: number, token?: string, timeoutMs?: number }} [opts]
@@ -1542,17 +1694,19 @@ function moveQueueToClaim(queuePath, claimPath) {
  */
 function claimQueue(root, { now = Date.now(), token = newClaimToken(), timeoutMs } = {}) {
   assertClaimToken('claimQueue', token);
-  if (!hasLearningDir(root)) return { ok: true, value: { state: 'none' } };
+  const paused = trackedCurationArea('claim-queue', root);
+  if (paused !== null) return paused;
+  if (!hasCurationDir(root)) return { ok: true, value: { state: 'none' } };
   return withDecisionsLock('claim-queue', root, () => {
-    const claimPath = getLearningPendingTurnsProcessingPath(root);
-    const queuePath = getLearningPendingTurnsPath(root);
+    const claimPath = getCurationPendingTurnsProcessingPath(root);
+    const queuePath = getCurationPendingTurnsPath(root);
     const at = new Date(now);
 
     const claim = regularFileStat(claimPath);
     if (claim === false) return notRegularFile('claim-queue', claimPath);
     if (claim !== null) {
       if (now - claim.mtimeMs < CLAIM_STALE_SECS * 1000) return { ok: true, value: { state: 'busy' } };
-      writeFileAtomic(getLearningClaimOwnerPath(root), `${token}\n`);
+      writeFileAtomic(getCurationClaimOwnerPath(root), `${token}\n`);
       fs.utimesSync(claimPath, at, at);
       return { ok: true, value: { state: 'claimed', token, takeover: true } };
     }
@@ -1564,7 +1718,7 @@ function claimQueue(root, { now = Date.now(), token = newClaimToken(), timeoutMs
     const moved = moveQueueToClaim(queuePath, claimPath);
     if (moved !== 'moved') return { ok: true, value: { state: moved } };
     fs.utimesSync(claimPath, at, at);
-    writeFileAtomic(getLearningClaimOwnerPath(root), `${token}\n`);
+    writeFileAtomic(getCurationClaimOwnerPath(root), `${token}\n`);
     return { ok: true, value: { state: 'claimed', token, takeover: false } };
   }, { timeoutMs });
 }
@@ -1581,14 +1735,14 @@ function claimQueue(root, { now = Date.now(), token = newClaimToken(), timeoutMs
  * @param {string} token
  * @param {{ timeoutMs?: number }} [opts]
  * @returns {{ ok: true, value: { state: 'released'|'not-owner'|'gone' } } | { ok: false, error: { kind: string, message: string } }}
- *   errors include withDecisionsLock's not-a-directory, no-learning-dir and busy
+ *   errors include withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy
  * @throws {TypeError} when `token` is not a claim token
  */
 function releaseClaim(root, token, { timeoutMs } = {}) {
   assertClaimToken('releaseClaim', token);
   return withDecisionsLock('release-claim', root, () => {
-    const claimPath = getLearningPendingTurnsProcessingPath(root);
-    const ownerPath = getLearningClaimOwnerPath(root);
+    const claimPath = getCurationPendingTurnsProcessingPath(root);
+    const ownerPath = getCurationClaimOwnerPath(root);
     const owned = readClaimOwner(root) === token;
 
     const claim = regularFileStat(claimPath);
@@ -1607,18 +1761,21 @@ function releaseClaim(root, token, { timeoutMs } = {}) {
 /**
  * The claim heartbeat (D-OWNED-CLAIM): set an existing claim's mtime to now. It
  * never creates a claim and never follows a symlink at the claim path, and it
- * takes no lock — json-helper sends it before each learning op runs. A claim in a
- * learning tree reached through a symbolic link is left alone (D-NO-LINKED-TREE):
+ * takes no lock — json-helper sends it before each curation op runs. A claim in a
+ * curation tree reached through a symbolic link is left alone (D-NO-LINKED-TREE):
  * `lutimes` follows a linked folder above the claim, and the op that follows
- * refuses that tree anyway.
+ * refuses that tree anyway. A claim in a project whose curation data folders git
+ * tracks, or where git does not answer, is left alone as well (trackedCurationArea).
  *
  * @param {string} root - project root
  * @param {{ now?: number }} [opts] - now: epoch ms (default Date.now())
  * @returns {{ ok: true, value: { touched: boolean } } | { ok: false, error: { kind: 'heartbeat-failed', message: string } }}
  */
 function touchClaim(root, { now = Date.now() } = {}) {
-  if (linkedLearningFolder(root) !== null) return { ok: true, value: { touched: false } };
-  const claimPath = getLearningPendingTurnsProcessingPath(root);
+  if (linkedCurationFolder(root) !== null || trackedCurationArea('heartbeat', root) !== null) {
+    return { ok: true, value: { touched: false } };
+  }
+  const claimPath = getCurationPendingTurnsProcessingPath(root);
   const at = new Date(now);
   try {
     fs.lutimesSync(claimPath, at, at);
@@ -1950,16 +2107,17 @@ function resolveVerifyRef(root) {
 /**
  * Render decisions.md, pitfalls.md and index.md from `ledgerRows` and write each
  * atomically, the index last. The caller holds .decisions.lock
- * (D-ONE-LEARNING-LOCK), so the learning directory exists. render-decisions.cjs
+ * (D-ONE-LEARNING-LOCK), so the curation directory exists. render-decisions.cjs
  * requires this module at load time, so it is required here, on first use. Prints
  * nothing.
  *
  * @param {string} root - project root
  * @param {object[]} ledgerRows - every ledger row
+ * @param {string} [outputDir] - the folder the files belong in (default: the curation folder)
  */
-function renderAll(root, ledgerRows) {
-  const { renderLearningFiles } = require('./render-decisions.cjs');
-  for (const file of renderLearningFiles(root, ledgerRows)) writeFileAtomic(file.path, file.content);
+function renderAll(root, ledgerRows, outputDir = getCurationDir(root)) {
+  const { renderCurationFiles } = require('./render-decisions.cjs');
+  for (const file of renderCurationFiles(root, ledgerRows, outputDir)) writeFileAtomic(file.path, file.content);
 }
 
 // ---------------------------------------------------------------------------
@@ -2118,13 +2276,15 @@ function restoreFirst(id, carriers) {
  *   observations: the count the log row holds afterwards; reprojected: the
  *   anchors re-projected, in anchor order. Error kinds: invalid-input (with
  *   problems), duplicate-log-id, restore-first, cannot-reproject, and
- *   withDecisionsLock's not-a-directory, no-learning-dir and busy.
+ *   withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} when `mode` is not a put mode
  */
 function putObservation(root, mode, input, { now = Date.now(), timeoutMs, scopeMatches } = {}) {
   if (!VALIDATION_MODES.includes(mode)) {
     throw new TypeError(`putObservation: mode must be one of ${VALIDATION_MODES.join(', ')}, got '${mode}'`);
   }
+  const paused = trackedCurationArea('put-observation', root);
+  if (paused !== null) return paused;
   const matches = scopeMatches || gitScopeMatcher(root);
   return withDecisionsLock('put-observation', root, () => putUnderLock(root, mode, input, { now, scopeMatches: matches }), { timeoutMs });
 }
@@ -2190,16 +2350,19 @@ function putUnderLock(root, mode, input, { now, scopeMatches }) {
  * The data behind `list`, read-only: buildListing over the ledger and the log as
  * they are, every glob scope checked against the files git tracks. Malformed
  * lines are counted, never quarantined (D-QUARANTINE-MALFORMED). Refuses without
- * .devflow/learning/ (D-NO-STRAY-TREE).
+ * .devflow/curation/ (D-NO-STRAY-TREE), and, before it reads a file, where git tracks files
+ * in the curation data folders (trackedCurationArea).
  *
  * @param {string} root - project root
  * @param {{ scopeMatches?: (glob: string) => boolean }} [opts] - default gitScopeMatcher(root)
  * @returns {{ ok: true, value: { active: object[], inactive: object[], observations: object[], integrity: object[], malformed: { ledger: number, log: number } } }
- *   | { ok: false, error: { kind: 'no-learning-dir', message: string } }}
+ *   | { ok: false, error: { kind: 'tracked'|'no-curation-dir', message: string } }}
  */
 function readListing(root, { scopeMatches } = {}) {
-  if (!hasLearningDir(root)) return noLearningDir('list', root);
-  const { ledgerRows, logRows, rejected } = readLearningState(root);
+  const paused = trackedCurationArea('list', root);
+  if (paused !== null) return paused;
+  if (!hasCurationDir(root)) return noCurationDir('list', root);
+  const { ledgerRows, logRows, rejected } = readCurationState(root);
   return {
     ok: true,
     value: buildListing(ledgerRows, logRows, { scopeMatches: scopeMatches || gitScopeMatcher(root), rejected }),
@@ -2280,16 +2443,19 @@ function formatListing(listing) {
  * the log and the history as they are. When lines were skipped as malformed
  * (D-QUARANTINE-MALFORMED), a found entry gains `malformed: { ledger, log }` and
  * a not-found message says a skipped line may hold it. Refuses without
- * .devflow/learning/ (D-NO-STRAY-TREE).
+ * .devflow/curation/ (D-NO-STRAY-TREE), and, before it reads a file, where git tracks files
+ * in the curation data folders (trackedCurationArea).
  *
  * @param {string} root - project root
  * @param {string} key - an anchor id or an observation id
  * @returns {{ ok: true, value: { key: string, ledger: object[], log: object|null, history_versions: object[], flags: object[], malformed?: { ledger: number, log: number } } }
- *   | { ok: false, error: { kind: 'no-learning-dir'|'invalid-key'|'not-found', message: string } }}
+ *   | { ok: false, error: { kind: 'tracked'|'no-curation-dir'|'invalid-key'|'not-found', message: string } }}
  */
 function showByKey(root, key) {
-  if (!hasLearningDir(root)) return noLearningDir('show', root);
-  const { ledgerRows, logRows, rejected } = readLearningState(root);
+  const paused = trackedCurationArea('show', root);
+  if (paused !== null) return paused;
+  if (!hasCurationDir(root)) return noCurationDir('show', root);
+  const { ledgerRows, logRows, rejected } = readCurationState(root);
   const shown = showEntry(key, ledgerRows, logRows, { historyVersions: id => historyVersions(root, id) });
   const malformed = { ledger: rejected.ledger.length, log: rejected.log.length };
   const skipped = malformed.ledger + malformed.log;
@@ -2320,7 +2486,7 @@ function warmScopeMatcher(ledgerRows, scopeMatches) {
 /**
  * Hand out the entries maintenance works on next, and lease them.
  *
- * Under the learning lock it flags integrity problems and selects the due
+ * Under the curation lock it flags integrity problems and selects the due
  * entries (D-DUE-ORDER), then stamps each entry it hands out with
  * `last_attempt` = now: claim-due is the one writer of the field the lease
  * reads. A hand-out backs up a v1 tree first (D-V1-BACKUP-ONCE) and quarantines
@@ -2335,11 +2501,13 @@ function warmScopeMatcher(ledgerRows, scopeMatches) {
  *   now: epoch ms (default Date.now()); scopeMatches: default gitScopeMatcher(root)
  * @returns {{ ok: true, value: { ref: { ref: 'origin/HEAD'|'HEAD', commit: string } | null, due: Array<{ anchor_id: string, reason: string, bytes: number }> } }
  *   | { ok: false, error: { kind: string, message: string } }}
- *   due is selectDue's answer; errors are withDecisionsLock's not-a-directory,
- *   no-learning-dir and busy
+ *   due is selectDue's answer; errors are withDecisionsLock's tracked, not-a-directory,
+ *   no-curation-dir and busy
  */
 function claimDue(root, { now = Date.now(), timeoutMs, scopeMatches } = {}) {
-  if (!hasLearningDir(root)) return noLearningDir('claim-due', root);
+  const paused = trackedCurationArea('claim-due', root);
+  if (paused !== null) return paused;
+  if (!hasCurationDir(root)) return noCurationDir('claim-due', root);
   const matches = scopeMatches || gitScopeMatcher(root);
   const ref = resolveVerifyRef(root);
   warmScopeMatcher(readJsonl(getDecisionsLedgerPath(root)).rows, matches);
@@ -2413,7 +2581,7 @@ function nextAnchorFromLedger(ledgerRows, type) {
 
 /**
  * True when a project-relative path is one the cited-number scan never reads: the
- * learning tree, where every entry cites itself, or anything under an excluded
+ * curation tree, where every entry cites itself, or anything under an excluded
  * directory segment.
  *
  * @param {string} relPath - relative to the project root, either separator style
@@ -2421,7 +2589,7 @@ function nextAnchorFromLedger(ledgerRows, type) {
  */
 function isCitedScanExcluded(relPath) {
   const norm = relPath.split(path.sep).join('/');
-  if (norm === '.devflow/learning' || norm.startsWith('.devflow/learning/')) return true;
+  if (norm === '.devflow/curation' || norm.startsWith('.devflow/curation/')) return true;
   return norm.split('/').some(segment => CITED_SCAN_EXCLUDED_SEGMENTS.includes(segment));
 }
 
@@ -2432,7 +2600,7 @@ function isCitedScanExcluded(relPath) {
  * command a repository's config names in `core.fsmonitor` — code chosen by the
  * repository this hook runs inside. The call turns it off for itself
  * (`-c core.fsmonitor=false`), so the listing stays a pure read. Reason: the
- * learning ops run inside any repository a session opens, and a read that ran
+ * curation ops run inside any repository a session opens, and a read that ran
  * the repository's command would execute it with the user's privileges.
  *
  * @param {string} root - project root
@@ -2512,7 +2680,7 @@ function readScannedText(file) {
  * Every anchor the project's files cite as a whole word, each mapped to its first
  * citation: the scan behind D-E4-SKIP. It reads the files git tracks under `root`
  * (D-NO-FSMONITOR) or, outside a git working tree, the files a directory walk
- * finds — never the learning tree, an excluded directory, a symbolic link, a
+ * finds — never the curation tree, an excluded directory, a symbolic link, a
  * binary file or a file over the size cap. A file it cannot read is passed over.
  * It writes nothing and takes no lock.
  *
@@ -2584,10 +2752,10 @@ function mintAnchor(ledgerRows, type, citedAnchors) {
  * Promote a v2 observation to a new ledger entry of `type` — the assign-anchor op.
  *
  * D-E4-SKIP: assign-anchor scans the project's tracked files once, before it takes
- * the learning lock, for every anchor they cite as a whole word, and mints the
+ * the curation lock, for every anchor they cite as a whole word, and mints the
  * first number past the type's highest anchored number that no file cites; it
  * reports each number it skips, skips at most E4_MAX_SKIPS of them and refuses
- * when the next one is cited too. The scan reads neither the learning tree nor
+ * when the next one is cited too. The scan reads neither the curation tree nor
  * .git or a vendored or build directory (node_modules, target, dist), nor a
  * symbolic link, a binary file or a file over 5 MB. Reason: a document can cite a
  * number the ledger has not minted yet, and minting over it silently binds that
@@ -2598,7 +2766,7 @@ function mintAnchor(ledgerRows, type, citedAnchors) {
  * whatever its status (D-LEDGER-REGISTRY). The new row is its projection
  * (toLedgerRowV2) with the type's active status and today as both date and
  * last_verified; it is appended to the ledger and the files are re-rendered, all
- * under the learning lock. The log is never written. Like every writer it backs
+ * under the curation lock. The log is never written. Like every writer it backs
  * up a v1 tree first (D-V1-BACKUP-ONCE) and quarantines the ledger's malformed
  * lines before it rewrites the ledger (D-QUARANTINE-MALFORMED); a refusal writes
  * nothing.
@@ -2612,13 +2780,15 @@ function mintAnchor(ledgerRows, type, citedAnchors) {
  *   | { ok: false, error: { kind: string, message: string } }}
  *   Error kinds: not-in-log, duplicate-log-id, already-promoted, v1-observation,
  *   type-mismatch, cited-numbers-exhausted, and withDecisionsLock's
- *   not-a-directory, no-learning-dir and busy.
+ *   tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} for a type other than decision or pitfall, or a malformed obsId
  */
 function assignAnchor(root, type, obsId, { now = Date.now(), timeoutMs, citedAnchors } = {}) {
   if (anchorPrefixFor(type) === null) throw new TypeError(`assignAnchor: type must be 'decision' or 'pitfall', got '${type}'`);
   if (typeof obsId !== 'string' || !OBS_ID_RE.test(obsId)) throw new TypeError('assignAnchor: obsId must be an observation id');
-  if (!hasLearningDir(root)) return noLearningDir('assign-anchor', root);
+  const paused = trackedCurationArea('assign-anchor', root);
+  if (paused !== null) return paused;
+  if (!hasCurationDir(root)) return noCurationDir('assign-anchor', root);
   const cited = citedAnchors || collectCitedAnchorIds(root);
   return withDecisionsLock('assign-anchor', root, () => assignUnderLock(root, type, obsId, { now, cited }), { timeoutMs });
 }
@@ -2760,7 +2930,7 @@ function recordRefreshHistory(root, plans, ledgerRows, { now }) {
  * an inactive entry or a v1 one, and — when re-projecting — an entry with no
  * observation id or whose log row is missing, doubled, v1 or of a type it cannot
  * take refuses the whole batch, every refused anchor listed, nothing written. A
- * batch that changes no row writes nothing. Otherwise, under the learning lock,
+ * batch that changes no row writes nothing. Otherwise, under the curation lock,
  * it backs up a v1 tree (D-V1-BACKUP-ONCE), quarantines the ledger's malformed
  * lines (D-QUARANTINE-MALFORMED), then writes the ledger once and renders once.
  *
@@ -2771,7 +2941,7 @@ function recordRefreshHistory(root, plans, ledgerRows, { now }) {
  * @returns {{ ok: true, value: { refreshed: Array<{ anchor_id: string, state: 'verified'|'reprojected'|'unchanged' }> } }
  *   | { ok: false, error: { kind: string, message: string, problems?: Array<{ anchor_id: string, message: string }> } }}
  *   refreshed: each anchor once, in the order given. Error kinds: refused (with
- *   problems), and withDecisionsLock's not-a-directory, no-learning-dir and busy.
+ *   problems), and withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} when anchorIds is empty or holds anything but anchor ids
  */
 function refreshAnchors(root, anchorIds, { verified = false, now = Date.now(), timeoutMs } = {}) {
@@ -2954,9 +3124,11 @@ function restoreRefusal(kind, message) {
  * @param {{ verifyRef?: { ref: 'origin/HEAD'|'HEAD', commit: string } | null }} [opts]
  *   verifyRef: default resolveVerifyRef(root); null when there is no commit to check
  * @returns {{ ok: true, value: { path: string, quote: string, ref: string, commit: string } }
- *   | { ok: false, error: { kind: 'no-verify-ref'|'not-at-ref'|'git-failed'|'quote-not-found', message: string } }}
+ *   | { ok: false, error: { kind: 'tracked'|'no-verify-ref'|'not-at-ref'|'git-failed'|'quote-not-found', message: string } }}
  */
 function quoteAtRef(root, at, quote, { verifyRef } = {}) {
+  const paused = trackedCurationArea('retire-anchor', root);
+  if (paused !== null) return paused;
   const checkedAt = verifyRef === undefined ? resolveVerifyRef(root) : verifyRef;
   if (checkedAt === null) {
     return retireRefusal('no-verify-ref', 'there is no commit to check the quote at (not a git repository, or no commit yet); nothing was written');
@@ -2991,7 +3163,7 @@ function quoteAtRef(root, at, quote, { verifyRef } = {}) {
  * Each also sets retired_on to today and clears the other notes; the rest of the
  * row stays as it is, so a v1 entry stays v1. An entry already inactive, an
  * anchor the ledger does not hold or holds twice, and a successor absent or
- * inactive are refused. The input and the quote are checked before the learning
+ * inactive are refused. The input and the quote are checked before the curation
  * lock is taken; under it the ledger is written once and the files are rendered,
  * after a v1 tree is backed up (D-V1-BACKUP-ONCE) and malformed ledger lines are
  * quarantined (D-QUARANTINE-MALFORMED). A refusal writes nothing.
@@ -3008,7 +3180,7 @@ function quoteAtRef(root, at, quote, { verifyRef } = {}) {
  *   kinds: invalid-input (with problems), quoteAtRef's, not-found,
  *   duplicate-anchor, already-inactive, successor-not-found,
  *   successor-duplicate-anchor, successor-inactive, and withDecisionsLock's
- *   not-a-directory, no-learning-dir and busy.
+ *   tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} for a malformed anchorId or a status that is not inactive
  */
 function retireAnchor(root, anchorId, status, input, { now = Date.now(), timeoutMs, verifyRef } = {}) {
@@ -3016,7 +3188,9 @@ function retireAnchor(root, anchorId, status, input, { now = Date.now(), timeout
   if (!INACTIVE_STATUSES.includes(status)) {
     throw new TypeError(`retireAnchor: status must be one of ${INACTIVE_STATUSES.join(', ')}, got '${status}'`);
   }
-  if (!hasLearningDir(root)) return noLearningDir('retire-anchor', root);
+  const paused = trackedCurationArea('retire-anchor', root);
+  if (paused !== null) return paused;
+  if (!hasCurationDir(root)) return noCurationDir('retire-anchor', root);
   const problems = retireInputProblems(anchorId, status, input);
   if (problems.length > 0) return invalidInput('retire-anchor', problems);
   let note;
@@ -3078,7 +3252,7 @@ function retireUnderLock(root, anchorId, status, note, { now }) {
  * claim-due hands it out ahead of every verified entry (D-DUE-ORDER); its content
  * and its date stay, and the files are re-rendered. An entry already active, an
  * anchor the ledger does not hold or holds twice, and a row whose type its anchor
- * does not name are refused. It writes as retireAnchor does, under the learning
+ * does not name are refused. It writes as retireAnchor does, under the curation
  * lock; a refusal writes nothing.
  *
  * @param {string} root - project root
@@ -3087,7 +3261,7 @@ function retireUnderLock(root, anchorId, status, note, { now }) {
  * @returns {{ ok: true, value: { anchor_id: string, status: 'Accepted'|'Active' } }
  *   | { ok: false, error: { kind: string, message: string } }}
  *   Error kinds: not-found, duplicate-anchor, already-active, type-mismatch, and
- *   withDecisionsLock's not-a-directory, no-learning-dir and busy.
+ *   withDecisionsLock's tracked, not-a-directory, no-curation-dir and busy.
  * @throws {TypeError} for a malformed anchorId
  */
 function restoreAnchor(root, anchorId, { now = Date.now(), timeoutMs } = {}) {
@@ -3148,15 +3322,17 @@ module.exports = {
   readJsonl,
   rejectedPathFor,
   quarantineRejected,
+  appendNoFollow,
   readJsonlForWrite,
   writeExclusive,
   writeFileAtomic,
   writeJsonlAtomic,
   // Locking
-  hasLearningDir,
+  hasCurationDir,
+  trackedCurationArea,
   withDecisionsLock,
   // State and the ledger registry
-  readLearningState,
+  readCurationState,
   ledgerRegistry,
   // Validation
   validateObservationInput,
@@ -3171,7 +3347,7 @@ module.exports = {
   // Rotation, clearing and resetting
   rotateObservations,
   clearUnreferenced,
-  resetLearning,
+  resetCuration,
   // The queue claim
   CLAIM_STALE_SECS,
   CLAIM_TOKEN_RE,
@@ -3180,6 +3356,16 @@ module.exports = {
   claimQueue,
   releaseClaim,
   touchClaim,
+  // Primitives curation-move.cjs builds on
+  QUEUE_LOCK_STALE_MS,
+  NO_HARD_LINK_CODES,
+  isPlainObject,
+  readTextUnlinked,
+  removeIfPresent,
+  renderAll,
+  lstatOrNull,
+  physicalPath,
+  homeDirOrNull,
   // Integrity, listing, due selection and show
   integrityFlags,
   buildListing,