devflow-kit 3.7.0 → 3.9.0

package/src/assets/scripts/hooks/lib/decisions-format.cjs

@@ -3,7 +3,7 @@
 // Shared pure formatting helpers for decisions.md and pitfalls.md output.
 //
 // DESIGN: Shared pure formatting helpers for render-decisions.cjs, the one
-// renderer: its CLI and every learning-store writer render through it, so all of
+// renderer: its CLI and every curation-store writer render through it, so all of
 // them share the EXACT same format functions. This is the single source of truth
 // for the byte-compat output strings — any drift here will break the
 // renderer/session-start-context TL;DR parser.
@@ -82,7 +82,7 @@ const {
   isV2,
   singleLine,
   inactiveNote,
-} = require('./learning-store.cjs');
+} = require('./curation-store.cjs');
 
 /** JS LineTerminator set — /m `^` matches after each of these and `.` excludes them. */
 const LINE_TERMINATORS = /[\r\n\u2028\u2029]/g;
@@ -226,7 +226,7 @@ const PF_KEYS = /** @type {const} */ (['area', 'issue', 'impact', 'resolution'])
 
 /** The line under each rendered file's title: who writes the file and what it lists. */
 const GENERATED_NOTICE =
-  'Generated from the local learning ledger by devflow; do not edit. ' +
+  'Generated from the local curation ledger by devflow; do not edit. ' +
   'Active entries follow; retired ones are listed under Inactive.';
 
 /**

package/src/assets/scripts/hooks/lib/mkdir-lock.cjs

@@ -1,7 +1,7 @@
 // src/assets/scripts/hooks/lib/mkdir-lock.cjs
 //
-// Shared mkdir-based locking helpers used by learning-store.cjs — whose
-// withDecisionsLock every learning op that writes and the render CLI take, and
+// Shared mkdir-based locking helpers used by curation-store.cjs — whose
+// withDecisionsLock every curation op that writes and the render CLI take, and
 // whose queue claim also takes the queue's own lock — and any other CJS hook that
 // needs exclusive access to a shared resource.
 //
@@ -50,12 +50,16 @@ function _idleSleep50() {
  * (default 60 s) is forcibly removed and the caller retries. This protects against
  * crashed holders but creates a narrow TOCTOU window: if a holder is actively
  * working and takes longer than 60 s, its lock can be stolen — leading to concurrent
- * ledger writes. Current callers (the learning ops through withDecisionsLock, and the
+ * ledger writes. Current callers (the curation ops through withDecisionsLock, and the
  * render CLI) perform only synchronous file I/O + JSON parse and complete well under 60 s in practice,
  * so this window is not reachable under normal operation. For long-running callers
  * call refreshLock(lockDir) periodically to reset the mtime and push the deadline
  * out by another staleMs interval.
  *
+ * A stale lock that cannot be removed (it holds files, it is not a directory, or its
+ * folder refuses the rmdir) is waited on like a live one, so `timeoutMs` bounds the
+ * loop: with a timeout of 0 the call answers false at once.
+ *
  * @param {string} lockDir - path to lock directory
  * @param {number} [timeoutMs=30000] - max wait in milliseconds
  * @param {number} [staleMs=60000] - age after which lock is considered stale
@@ -72,10 +76,7 @@ function acquireMkdirLock(lockDir, timeoutMs = 30000, staleMs = 60000) {
       try {
         const stat = fs.statSync(lockDir);
         const age = Date.now() - stat.mtimeMs;
-        if (age > staleMs) {
-          try { fs.rmdirSync(lockDir); } catch { /* already gone */ }
-          continue;
-        }
+        if (age > staleMs && breakStaleLock(lockDir)) continue;
       } catch { /* lock gone between check and stat */ }
       if (Date.now() - start >= timeoutMs) return false;
       _idleSleep50();
@@ -83,6 +84,22 @@ function acquireMkdirLock(lockDir, timeoutMs = 30000, staleMs = 60000) {
   }
 }
 
+/**
+ * Remove a stale lock directory. True when it is gone (removed here, or already
+ * removed by another process); false when the rmdir failed for any other reason.
+ *
+ * @param {string} lockDir
+ * @returns {boolean}
+ */
+function breakStaleLock(lockDir) {
+  try {
+    fs.rmdirSync(lockDir);
+    return true;
+  } catch (err) {
+    return Boolean(err) && err.code === 'ENOENT';
+  }
+}
+
 /**
  * Release a mkdir-based lock. No-op if already released.
  *

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

@@ -13,8 +13,43 @@
 
 'use strict';
 
+const crypto = require('crypto');
 const path = require('path');
 
+// ---------------------------------------------------------------------------
+// The rename's names: the old names in one frozen block, the new ones beside it
+// ---------------------------------------------------------------------------
+
+/**
+ * The names the rename retires, kept in one place so the one-time ledger move, the
+ * backup readers and uninstall all spell them the same way. The TypeScript mirror
+ * and the shell move shim list the same names (tests/project-paths.test.ts pins both).
+ */
+const LEGACY_NAMES = Object.freeze({
+  /** The old ledger folder under .devflow/. */
+  folder: 'learning',
+  /** The prefix of the folder the move leaves behind: `<prefix><UTC stamp>-<random>`. */
+  backupPrefix: 'learning.backup-',
+  /** The old project tuning file, inside the old folder. */
+  tuningFile: 'learning.json',
+});
+
+/** The new ledger folder under .devflow/. */
+const CURATION_DIR_NAME = 'curation';
+
+/** The new project tuning file, inside the new folder. */
+const CURATION_TUNING_FILE_NAME = 'curation.json';
+
+/**
+ * The names of the ledger move's lock and journal in the machine directory (`~/.devflow`):
+ * `<prefix><16 hex characters of the root key><suffix>`, the journal beside the lock. The
+ * TypeScript mirror holds the same three values for uninstall (tests/project-paths.test.ts
+ * pins both).
+ */
+const MOVE_LOCK_PREFIX = '.curation-move-';
+const MOVE_LOCK_SUFFIX = '.lock';
+const MOVE_JOURNAL_SUFFIX = '.journal';
+
 // ---------------------------------------------------------------------------
 // Core directories
 // ---------------------------------------------------------------------------
@@ -24,9 +59,9 @@ function getMemoryDir(projectRoot) {
   return path.join(projectRoot, '.devflow', 'memory');
 }
 
-/** .devflow/learning/ — learning state root */
-function getLearningDir(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning');
+/** .devflow/curation/ — curation state root */
+function getCurationDir(projectRoot) {
+  return path.join(projectRoot, '.devflow', CURATION_DIR_NAME);
 }
 
 /** .devflow/features/ — per-feature knowledge bases */
@@ -39,8 +74,18 @@ function getDocsDir(projectRoot) {
   return path.join(projectRoot, '.devflow', 'docs');
 }
 
+/**
+ * The global curate-agent tuning file inside the machine directory (`~/.devflow`).
+ * The one place that names it: the configure writer, the TypeScript reader, the
+ * shell reader (`df_global_tuning_file` in the hooks' git-marker library) and the
+ * global-file lists all come through here.
+ */
+function getGlobalCurateTuningConfigPath(machineDir) {
+  return path.join(machineDir, CURATION_TUNING_FILE_NAME);
+}
+
 // ---------------------------------------------------------------------------
-// Feature config (neutral .devflow root — not inside learning/)
+// Feature config (neutral .devflow root — not inside curation/)
 // ---------------------------------------------------------------------------
 
 /** .devflow/config.json — per-repo facts {reviewPublication, tracker override} */
@@ -49,71 +94,71 @@ function getFeatureConfigPath(projectRoot) {
 }
 
 // ---------------------------------------------------------------------------
-// Learning queue files
+// Curation queue files
 // ---------------------------------------------------------------------------
 
-/** .devflow/learning/.pending-turns.jsonl — decisions detection queue */
-function getLearningPendingTurnsPath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.jsonl');
+/** .devflow/curation/.pending-turns.jsonl — decisions detection queue */
+function getCurationPendingTurnsPath(projectRoot) {
+  return path.join(getCurationDir(projectRoot), '.pending-turns.jsonl');
 }
 
-/** .devflow/learning/.pending-turns.processing — the claimed batch a Curate run holds while it processes it */
-function getLearningPendingTurnsProcessingPath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.processing');
+/** .devflow/curation/.pending-turns.processing — the claimed batch a Curate run holds while it processes it */
+function getCurationPendingTurnsProcessingPath(projectRoot) {
+  return path.join(getCurationDir(projectRoot), '.pending-turns.processing');
 }
 
-/** .devflow/learning/.pending-turns.owner — the token of the run that holds the claim (learning-store.cjs) */
-function getLearningClaimOwnerPath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.owner');
+/** .devflow/curation/.pending-turns.owner — the token of the run that holds the claim (curation-store.cjs) */
+function getCurationClaimOwnerPath(projectRoot) {
+  return path.join(getCurationDir(projectRoot), '.pending-turns.owner');
 }
 
 // ---------------------------------------------------------------------------
-// Learning content files
+// Curation content files
 // ---------------------------------------------------------------------------
 
-/** .devflow/learning/decisions.md */
+/** .devflow/curation/decisions.md */
 function getDecisionsFilePath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', 'decisions.md');
+  return path.join(getCurationDir(projectRoot), 'decisions.md');
 }
 
-/** .devflow/learning/pitfalls.md */
+/** .devflow/curation/pitfalls.md */
 function getPitfallsFilePath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', 'pitfalls.md');
+  return path.join(getCurationDir(projectRoot), 'pitfalls.md');
 }
 
-/** .devflow/learning/learning.json — project-level curate agent tuning config */
+/** .devflow/curation/curation.json — project-level curate agent tuning config */
 function getCurateTuningConfigPath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', 'learning.json');
+  return path.join(getCurationDir(projectRoot), CURATION_TUNING_FILE_NAME);
 }
 
-/** .devflow/learning/decisions-ledger.jsonl — anchored ledger rows (single source of truth for rendering) */
+/** .devflow/curation/decisions-ledger.jsonl — anchored ledger rows (single source of truth for rendering) */
 function getDecisionsLedgerPath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', 'decisions-ledger.jsonl');
+  return path.join(getCurationDir(projectRoot), 'decisions-ledger.jsonl');
 }
 
-/** .devflow/learning/decisions-log.jsonl */
+/** .devflow/curation/decisions-log.jsonl */
 function getDecisionsLogPath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', 'decisions-log.jsonl');
+  return path.join(getCurationDir(projectRoot), 'decisions-log.jsonl');
 }
 
-/** .devflow/learning/decisions-log.archive.jsonl — rotated-out stale observing rows (gitignored) */
+/** .devflow/curation/decisions-log.archive.jsonl — rotated-out stale observing rows (gitignored) */
 function getDecisionsArchivePath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', 'decisions-log.archive.jsonl');
+  return path.join(getCurationDir(projectRoot), 'decisions-log.archive.jsonl');
 }
 
-/** .devflow/learning/decisions-history.jsonl — prior content versions of rewritten entries (learning-store.cjs) */
+/** .devflow/curation/decisions-history.jsonl — prior content versions of rewritten entries (curation-store.cjs) */
 function getDecisionsHistoryPath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', 'decisions-history.jsonl');
+  return path.join(getCurationDir(projectRoot), 'decisions-history.jsonl');
 }
 
-/** .devflow/learning/.decisions.lock — mkdir-based lock directory */
+/** .devflow/curation/.decisions.lock — mkdir-based lock directory */
 function getDecisionsLockDir(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', '.decisions.lock');
+  return path.join(getCurationDir(projectRoot), '.decisions.lock');
 }
 
-/** .devflow/learning/index.md — pre-rendered compact index written by render-decisions.cjs */
+/** .devflow/curation/index.md — pre-rendered compact index written by render-decisions.cjs */
 function getDecisionsIndexPath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', 'index.md');
+  return path.join(getCurationDir(projectRoot), 'index.md');
 }
 
 // ---------------------------------------------------------------------------
@@ -164,22 +209,66 @@ function getResearchDir(projectRoot) {
   return path.join(projectRoot, '.devflow', 'docs', 'research');
 }
 
+// ---------------------------------------------------------------------------
+// The ledger move's machine-side names
+// ---------------------------------------------------------------------------
+//
+// Not project paths: the move lock and the move journal stand in the machine
+// directory (`$HOME/.devflow`), keyed by the ledger root, never inside a repository.
+// They sit here, and not in curation-move.cjs, because the store's write guard reads
+// the journal and must not load the move module to do it. CJS only: no TypeScript code
+// builds them (a named exception of the export parity test). Their names, which
+// uninstall also matches, are the three constants above.
+
+/**
+ * The key of a ledger root's move lock: the first 16 hex characters of the sha256 of
+ * the root's physical path. Two spellings of one root give one key, so two movers
+ * meet at one lock.
+ *
+ * @param {string} realRoot - the root's realpath
+ * @returns {string}
+ */
+function curationMoveLockKey(realRoot) {
+  return crypto.createHash('sha256').update(realRoot).digest('hex').slice(0, 16);
+}
+
+/** The move lock's directory, under the machine directory. */
+function curationMoveLockDir(machineDir, realRoot) {
+  return path.join(machineDir, `${MOVE_LOCK_PREFIX}${curationMoveLockKey(realRoot)}${MOVE_LOCK_SUFFIX}`);
+}
+
+/**
+ * The move journal's file, under the machine directory and keyed exactly like the move
+ * lock. While it exists every store write on the root returns busy.
+ */
+function curationMoveJournalPath(machineDir, realRoot) {
+  return path.join(machineDir, `${MOVE_LOCK_PREFIX}${curationMoveLockKey(realRoot)}${MOVE_JOURNAL_SUFFIX}`);
+}
+
 module.exports = {
+  // The rename's names
+  LEGACY_NAMES,
+  CURATION_DIR_NAME,
+  CURATION_TUNING_FILE_NAME,
+  MOVE_LOCK_PREFIX,
+  MOVE_LOCK_SUFFIX,
+  MOVE_JOURNAL_SUFFIX,
   // Core directories
   getMemoryDir,
-  getLearningDir,
+  getCurationDir,
   getFeaturesDir,
   getDocsDir,
   // Feature config
   getFeatureConfigPath,
-  // Learning queue files
-  getLearningPendingTurnsPath,
-  getLearningPendingTurnsProcessingPath,
-  getLearningClaimOwnerPath,
-  // Learning content files
+  // Curation queue files
+  getCurationPendingTurnsPath,
+  getCurationPendingTurnsProcessingPath,
+  getCurationClaimOwnerPath,
+  // Curation content files
   getDecisionsFilePath,
   getPitfallsFilePath,
   getCurateTuningConfigPath,
+  getGlobalCurateTuningConfigPath,
   getDecisionsLedgerPath,
   getDecisionsLogPath,
   getDecisionsArchivePath,
@@ -196,4 +285,8 @@ module.exports = {
   getReviewsDir,
   getDesignDir,
   getResearchDir,
+  // The ledger move's machine-side names
+  curationMoveLockKey,
+  curationMoveLockDir,
+  curationMoveJournalPath,
 };

package/src/assets/scripts/hooks/lib/render-decisions.cjs

@@ -12,11 +12,11 @@
 // Filtering rules (must match AC-F3):
 //   - anchor_id must be set (unanchored observing rows are excluded)
 //   - type must match kind: 'decision' rows → decisions.md; 'pitfall' rows → pitfalls.md
-//   - an active row (isActive from learning-store.cjs, the one status list) renders
+//   - an active row (isActive from curation-store.cjs, the one status list) renders
 //     its body; an inactive one is listed in the file's Inactive table instead
 //
-// Row shape: a v2 ledger row (schema 2) or a v1 one; see learning-store.cjs.
-// Ledger file: .devflow/learning/decisions-ledger.jsonl (anchored rows only).
+// Row shape: a v2 ledger row (schema 2) or a v1 one; see curation-store.cjs.
+// Ledger file: .devflow/curation/decisions-ledger.jsonl (anchored rows only).
 // If absent, treat as empty corpus.
 //
 // Byte-compat: formatDecisionBody / formatPitfallBody / formatEntryBodyV2 /
@@ -26,6 +26,7 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
 
 const {
   initDecisionsContent,
@@ -38,6 +39,7 @@ const {
 } = require('./decisions-format.cjs');
 
 const {
+  getCurationDir,
   getDecisionsFilePath,
   getPitfallsFilePath,
   getDecisionsIndexPath,
@@ -48,10 +50,11 @@ const {
   isActive,
   isV2,
   readJsonl,
-  hasLearningDir,
+  hasCurationDir,
+  trackedCurationArea,
   withDecisionsLock,
   writeFileAtomic,
-} = require('./learning-store.cjs');
+} = require('./curation-store.cjs');
 
 // ---------------------------------------------------------------------------
 // Ledger parsing
@@ -227,16 +230,26 @@ function renderDecisionsFile(rows, kind) {
 /**
  * Render decisions.md, pitfalls.md and index.md from the ledger rows, in memory,
  * in the order they are written: the body files first, the index last. `render`
- * and the learning store's writers write exactly these contents, and `--check`
+ * and the curation store's writers write exactly these contents, and `--check`
  * compares exactly these.
  *
+ * The files belong in `outputDir`, which the caller names: the index lists the
+ * absolute path of the decisions and pitfalls files, so it names the folder it is
+ * rendered for and no other. The file names are the path helpers'.
+ *
  * @param {string} worktreePath - Absolute path to the worktree root.
  * @param {object[]} rows - All rows from the ledger (unfiltered).
+ * @param {string} outputDir - Absolute path of the folder the three files belong in.
  * @returns {Array<{ path: string, content: string }>}
+ * @throws {TypeError} when `outputDir` is not an absolute path
  */
-function renderLearningFiles(worktreePath, rows) {
-  const decisionsFilePath = getDecisionsFilePath(worktreePath);
-  const pitfallsFilePath = getPitfallsFilePath(worktreePath);
+function renderCurationFiles(worktreePath, rows, outputDir) {
+  if (typeof outputDir !== 'string' || !path.isAbsolute(outputDir)) {
+    throw new TypeError('renderCurationFiles: outputDir must be an absolute path');
+  }
+  const inOutputDir = file => path.join(outputDir, path.basename(file));
+  const decisionsFilePath = inOutputDir(getDecisionsFilePath(worktreePath));
+  const pitfallsFilePath = inOutputDir(getPitfallsFilePath(worktreePath));
 
   // Hoist active-row selection: computed once per kind, reused for both the
   // body render and the index build — avoids two redundant selectActiveRows passes.
@@ -259,7 +272,7 @@ function renderLearningFiles(worktreePath, rows) {
     },
     {
       // Compact index: a write-time artifact consumed via plain Read.
-      path: getDecisionsIndexPath(worktreePath),
+      path: inOutputDir(getDecisionsIndexPath(worktreePath)),
       content: buildIndexContent(activeDecisionRows, activePitfallRows, {
         decisionsFilePath,
         pitfallsFilePath,
@@ -273,18 +286,18 @@ function renderLearningFiles(worktreePath, rows) {
 /**
  * Render decisions.md, pitfalls.md and index.md from the given ledger rows and
  * write them atomically. It takes no lock: the caller holds .decisions.lock
- * (D-ONE-LEARNING-LOCK). It writes only into an existing `.devflow/learning/`:
+ * (D-ONE-LEARNING-LOCK). It writes only into an existing `.devflow/curation/`:
  * without one it throws before writing anything (D-NO-STRAY-TREE).
  *
  * @param {string} worktreePath - Absolute path to the worktree root.
  * @param {object[]} rows - All rows from the ledger (unfiltered).
- * @throws when `<worktreePath>/.devflow/learning/` does not exist, or a write fails
+ * @throws when `<worktreePath>/.devflow/curation/` does not exist, or a write fails
  */
 function renderAndWriteAll(worktreePath, rows) {
-  if (!hasLearningDir(worktreePath)) {
-    throw new Error(`renderAndWriteAll: no .devflow/learning/ under ${worktreePath}`);
+  if (!hasCurationDir(worktreePath)) {
+    throw new Error(`renderAndWriteAll: no .devflow/curation/ under ${worktreePath}`);
   }
-  const [decisions, pitfalls, index] = renderLearningFiles(worktreePath, rows);
+  const [decisions, pitfalls, index] = renderCurationFiles(worktreePath, rows, getCurationDir(worktreePath));
 
   // Write body files first; index last. On a crash between body writes and the
   // index write: on the FIRST render the index is absent (reader falls back to
@@ -365,7 +378,7 @@ function readIfPresent(file) {
 /**
  * `render`: read the ledger under .decisions.lock and write the three files from
  * what it read (D-ONE-LEARNING-LOCK), so a ledger write that lands while it waits
- * is rendered rather than overwritten. Refuses without the learning directory
+ * is rendered rather than overwritten. Refuses without the curation directory
  * (D-NO-STRAY-TREE), and when it or `.devflow` is a symbolic link (D-NO-LINKED-TREE).
  *
  * @param {string} root
@@ -385,18 +398,25 @@ function renderCommand(root) {
  * `--check`: render in memory and compare with the files on disk, naming each
  * file that differs or is missing; exit 1 on any drift. It writes nothing and
  * takes no lock — taking it would create the lock directory — and refuses
- * without the learning directory (D-NO-STRAY-TREE).
+ * without the curation directory (D-NO-STRAY-TREE). Where git tracks files in the
+ * curation data folders, or does not say whether it does, it refuses first, exit 1:
+ * it reads no file there (trackedCurationArea).
  *
  * @param {string} root
  * @returns {number} exit code
  */
 function checkCommand(root) {
-  if (!hasLearningDir(root)) {
-    process.stderr.write(`${CLI_NAME}: no .devflow/learning/ under ${root} — run from the project root\n`);
+  const paused = trackedCurationArea(CLI_NAME, root);
+  if (paused !== null) {
+    process.stderr.write(`${paused.error.message}\n`);
+    return 1;
+  }
+  if (!hasCurationDir(root)) {
+    process.stderr.write(`${CLI_NAME}: no .devflow/curation/ under ${root} — run from the project root\n`);
     return 1;
   }
   let drift = false;
-  for (const file of renderLearningFiles(root, readLedgerRows(root))) {
+  for (const file of renderCurationFiles(root, readLedgerRows(root), getCurationDir(root))) {
     const onDisk = readIfPresent(file.path);
     if (onDisk !== file.content) {
       process.stderr.write(`[render-decisions] DRIFT: ${file.path}${onDisk === null ? ' (missing)' : ''}\n`);
@@ -408,7 +428,7 @@ function checkCommand(root) {
 
 /**
  * Run the CLI on its arguments and return the exit code. Neither mode creates the
- * learning directory (D-NO-STRAY-TREE).
+ * curation directory (D-NO-STRAY-TREE).
  *
  * @param {string[]} argv - the arguments after the script path
  * @returns {number}
@@ -446,7 +466,7 @@ if (require.main === module) {
 
 module.exports = {
   renderDecisionsFile,
-  renderLearningFiles,
+  renderCurationFiles,
   renderAndWriteAll,
   selectActiveRows,
   selectInactiveRows,