devflow-kit 3.0.1 → 3.2.0

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

@@ -6,30 +6,33 @@
 // DESIGN: Idempotent, clock-free render from anchored ledger rows. No timestamps
 // in output — render is a pure function of the ledger rows. Two consumers:
 //   1. renderDecisionsFile(rows, kind) — exported pure function for testing
-//   2. CLI: `render <worktree>` and `--check <worktree>` subcommands
+//   2. CLI: `render <worktree>` and `--check <worktree>` subcommands, run from the
+//      project root: <worktree> names the current directory
 //
 // 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
-//   - decisions_status: undefined|'Accepted'|'Active' → included
-//     'Deprecated'|'Superseded'|'Retired' → excluded
+//   - an active row (isActive from learning-store.cjs, the one status list) renders
+//     its body; an inactive one is listed in the file's Inactive table instead
 //
-// Row shape: see LearningObservation in src/core/observations.ts.
+// 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).
 // If absent, treat as empty corpus.
 //
-// Byte-compat: formatDecisionBody / formatPitfallBody / buildTldrLine /
-// initDecisionsContent — all from decisions-format.cjs (single source of truth).
+// Byte-compat: formatDecisionBody / formatPitfallBody / formatEntryBodyV2 /
+// formatInactiveTable / buildTldrLine / initDecisionsContent — all from
+// decisions-format.cjs (single source of truth).
 
 'use strict';
 
 const fs = require('fs');
-const path = require('path');
 
 const {
   initDecisionsContent,
   formatDecisionBody,
   formatPitfallBody,
+  formatEntryBodyV2,
+  formatInactiveTable,
   buildTldrLine,
   buildIndexContent,
 } = require('./decisions-format.cjs');
@@ -38,51 +41,32 @@ const {
   getDecisionsFilePath,
   getPitfallsFilePath,
   getDecisionsIndexPath,
-  getDecisionsLockDir,
+  getDecisionsLedgerPath,
 } = require('./project-paths.cjs');
-const { acquireMkdirLock, releaseLock } = require('./mkdir-lock.cjs');
 const { safePath } = require('./safe-path.cjs');
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Statuses that indicate an anchored entry should be HIDDEN from the render. */
-const INACTIVE_STATUSES = new Set(['Deprecated', 'Superseded', 'Retired']);
-
-/** Ledger filename relative to .devflow/learning/ */
-const LEDGER_FILENAME = 'decisions-ledger.jsonl';
+const {
+  isActive,
+  isV2,
+  readJsonl,
+  hasLearningDir,
+  withDecisionsLock,
+  writeFileAtomic,
+} = require('./learning-store.cjs');
 
 // ---------------------------------------------------------------------------
 // Ledger parsing
 // ---------------------------------------------------------------------------
 
 /**
- * Parse a JSONL ledger file into an array of row objects.
- * Skips empty or malformed lines. Returns [] if file is absent.
+ * Read a JSONL ledger file leniently: its rows, skipping any line that is not one
+ * JSON object, or [] when the file is absent. Read-only: a skipped line is never
+ * quarantined (the store's readJsonl reports it for a caller that counts them).
  *
  * @param {string} ledgerPath
  * @returns {object[]}
  */
 function parseLedger(ledgerPath) {
-  let raw;
-  try {
-    raw = fs.readFileSync(ledgerPath, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') return [];
-    throw err;
-  }
-  const rows = [];
-  for (const line of raw.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      rows.push(JSON.parse(trimmed));
-    } catch {
-      // Skip malformed lines
-    }
-  }
-  return rows;
+  return readJsonl(ledgerPath).rows;
 }
 
 // ---------------------------------------------------------------------------
@@ -90,19 +74,7 @@ function parseLedger(ledgerPath) {
 // ---------------------------------------------------------------------------
 
 /**
- * Determine whether a row is "active" for render purposes.
- * Active = decisions_status is undefined OR is one of 'Accepted'/'Active'.
- *
- * @param {object} row
- * @returns {boolean}
- */
-function isActive(row) {
-  if (!row.decisions_status) return true;
-  return !INACTIVE_STATUSES.has(row.decisions_status);
-}
-
-/**
- * Extract the numeric suffix from an anchor_id like "ADR-016" or "PF-007".
+ * Extract the numeric suffix from an anchor_id like "ADR-NNN" or "PF-NNN".
  * Returns Infinity for unparseable values so they sort to the end.
  *
  * @param {string} anchorId
@@ -114,6 +86,26 @@ function anchorNumeric(anchorId) {
   return m ? parseInt(m[0], 10) : Infinity;
 }
 
+/** The ledger row type a rendered file of `kind` holds. */
+function rowTypeOf(kind) {
+  return kind === 'decisions' ? 'decision' : 'pitfall';
+}
+
+/**
+ * The anchored rows of `kind` whose activity is `active`, sorted by numeric anchor.
+ *
+ * @param {object[]} rows - all rows from the ledger (unfiltered)
+ * @param {'decisions'|'pitfalls'} kind
+ * @param {boolean} active
+ * @returns {object[]}
+ */
+function selectRows(rows, kind, active) {
+  const type = rowTypeOf(kind);
+  return rows
+    .filter(r => r.type === type && r.anchor_id && isActive(r) === active)
+    .sort((a, b) => anchorNumeric(a.anchor_id) - anchorNumeric(b.anchor_id));
+}
+
 /**
  * Select active rows of a given kind from the ledger, sorted by numeric anchor.
  * Exported so callers (renderAndWriteAll, migrations) can build the index without
@@ -124,10 +116,19 @@ function anchorNumeric(anchorId) {
  * @returns {object[]} filtered + sorted active rows
  */
 function selectActiveRows(rows, kind) {
-  const type = kind === 'decisions' ? 'decision' : 'pitfall';
-  return rows
-    .filter(r => r.type === type && r.anchor_id && isActive(r))
-    .sort((a, b) => anchorNumeric(a.anchor_id) - anchorNumeric(b.anchor_id));
+  return selectRows(rows, kind, true);
+}
+
+/**
+ * Select the inactive rows of a given kind, sorted by numeric anchor: the rows a
+ * file lists in its Inactive table instead of rendering their bodies.
+ *
+ * @param {object[]} rows - all rows from the ledger (unfiltered)
+ * @param {'decisions'|'pitfalls'} kind
+ * @returns {object[]} filtered + sorted inactive rows
+ */
+function selectInactiveRows(rows, kind) {
+  return selectRows(rows, kind, false);
 }
 
 /**
@@ -135,8 +136,16 @@ function selectActiveRows(rows, kind) {
  * Each block starts with a leading newline (matching the format contract).
  *
  * Per-row content:
- *   - If row.raw_body is truthy → emit verbatim (migrated entries)
- *   - Otherwise → formatDecisionBody / formatPitfallBody from details
+ *   - a v2 row (schema 2) → formatEntryBodyV2 from its fields
+ *   - a v1 row with a truthy raw_body → raw_body verbatim (migrated entries)
+ *   - any other v1 row → formatDecisionBody / formatPitfallBody from details
+ *
+ * D-V1-BYTE-STABLE: a v1 ledger row — any row without schema 2 — renders byte for
+ * byte as it did before v2: its raw_body verbatim when truthy, else
+ * formatDecisionBody or formatPitfallBody, and its index line keeps the v1 shape;
+ * only a schema-2 row takes the v2 body and index line. Reason: the ledger stays
+ * v1 until each entry is rewritten, and a render that moved v1 bytes would show
+ * every untouched entry as changed and alter text nobody revised.
  *
  * Extracted so renderAndWriteAll can compute blocks once and reuse them
  * for both the body files and buildIndexContent, avoiding a second full
@@ -148,6 +157,7 @@ function selectActiveRows(rows, kind) {
  */
 function buildBodyBlocks(activeRows, kind) {
   return activeRows.map(row => {
+    if (isV2(row)) return formatEntryBodyV2(row);
     if (row.raw_body) {
       // Migrated entry: emit verbatim. raw_body must start with \n## so
       // it fits seamlessly after the header preamble.
@@ -160,44 +170,27 @@ function buildBodyBlocks(activeRows, kind) {
 }
 
 /**
- * Assemble the full file content from pre-computed blocks and active rows.
+ * Assemble the full file content: the header with the file's TL;DR line, the
+ * pre-computed active blocks, then the Inactive table.
  * Internal helper — avoids re-computing blocks when the caller already has them.
  *
  * @param {object[]} activeRows - already-filtered + sorted active rows
  * @param {string[]} blocks - pre-rendered per-row blocks (from buildBodyBlocks)
  * @param {'decisions'|'pitfalls'} kind
+ * @param {object[]} inactiveRows - already-filtered + sorted inactive rows
  * @returns {string} complete file content
  */
-function buildFileFromBlocks(activeRows, blocks, kind) {
-  // Build TL;DR line (uses active + sorted rows so last-5 are stable)
+function buildFileFromBlocks(activeRows, blocks, kind, inactiveRows) {
+  // The TL;DR line counts the active rows.
   const tldr = buildTldrLine(kind, activeRows);
 
-  // Build header: replace placeholder TL;DR in the init content with the real one.
-  // initDecisionsContent returns "<!-- TL;DR: 0 {kind}. Key: -->\n..." so we
-  // replace the TL;DR line at position 0.
-  const initKind = kind === 'decisions' ? 'decision' : 'pitfall';
-  const headerWithPlaceholder = initDecisionsContent(initKind);
+  // Build header: replace the zero-count TL;DR line that opens the init content
+  // ("<!-- TL;DR: 0 {kind} -->\n...") with the real one.
+  const headerWithPlaceholder = initDecisionsContent(rowTypeOf(kind));
   // Replace only the first line (the TL;DR comment)
   const header = headerWithPlaceholder.replace(/^<!-- TL;DR:[^\n]*-->/, tldr);
 
-  return header + blocks.join('');
-}
-
-/**
- * Build the full file content from already-filtered + sorted active rows.
- * Internal helper — callers that have already run selectActiveRows can pass
- * the result here directly to avoid re-filtering the ledger.
- *
- * Per-row content:
- *   - If row.raw_body is truthy → emit verbatim (migrated entries)
- *   - Otherwise → formatDecisionBody / formatPitfallBody from details
- *
- * @param {object[]} activeRows - already-filtered + sorted active rows
- * @param {'decisions'|'pitfalls'} kind
- * @returns {string} complete file content
- */
-function renderBodyFromActive(activeRows, kind) {
-  return buildFileFromBlocks(activeRows, buildBodyBlocks(activeRows, kind), kind);
+  return header + blocks.join('') + formatInactiveTable(inactiveRows);
 }
 
 /**
@@ -207,13 +200,14 @@ function renderBodyFromActive(activeRows, kind) {
  * Filtering:
  *   - row.type must match kind ('decision' → decisions.md, 'pitfall' → pitfalls.md)
  *   - row.anchor_id must be set
- *   - row must be active (decisions_status not in INACTIVE_STATUSES)
+ *   - an active row (isActive) renders its body; an inactive one is listed in the
+ *     Inactive table
  *
  * Output structure:
  *   TL;DR line (line 1)
  *   File header body (title + preamble)
  *   Per-row blocks (sorted by numeric anchor ASC)
- *   (no trailing newline beyond what the blocks naturally include)
+ *   Inactive table (sorted by numeric anchor ASC; omitted when empty)
  *
  * Idempotent and clock-free: no timestamps in output.
  *
@@ -222,54 +216,27 @@ function renderBodyFromActive(activeRows, kind) {
  * @returns {string} complete file content
  */
 function renderDecisionsFile(rows, kind) {
-  return renderBodyFromActive(selectActiveRows(rows, kind), kind);
+  const activeRows = selectActiveRows(rows, kind);
+  return buildFileFromBlocks(activeRows, buildBodyBlocks(activeRows, kind), kind, selectInactiveRows(rows, kind));
 }
 
 // ---------------------------------------------------------------------------
-// Atomic write helper
+// Render and write
 // ---------------------------------------------------------------------------
 
 /**
- * Write content atomically via a .tmp sibling + rename.
- * Uses O_EXCL to prevent TOCTOU symlink attacks, retries once on EEXIST.
- *
- * @param {string} filePath
- * @param {string} content
- */
-function writeAtomic(filePath, content) {
-  const tmp = filePath + '.tmp';
-  try {
-    fs.writeFileSync(tmp, content, { flag: 'wx' });
-  } catch (err) {
-    if (err.code !== 'EEXIST') throw err;
-    try { fs.unlinkSync(tmp); } catch { /* race */ }
-    fs.writeFileSync(tmp, content, { flag: 'wx' });
-  }
-  fs.renameSync(tmp, filePath);
-}
-
-// ---------------------------------------------------------------------------
-// Lock-free render+write helper (for callers that already hold .decisions.lock)
-// ---------------------------------------------------------------------------
-
-/**
- * Render both decisions.md and pitfalls.md from the given ledger rows and write
- * them atomically. Does NOT acquire any lock — callers (assign-anchor, retire-anchor,
- * refresh-anchor) must already hold .decisions.lock. The standalone `render` CLI takes
- * the lock before calling this function.
- *
- * Creates the decisionsDir if it does not exist.
+ * 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`
+ * compares exactly these.
  *
  * @param {string} worktreePath - Absolute path to the worktree root.
  * @param {object[]} rows - All rows from the ledger (unfiltered).
+ * @returns {Array<{ path: string, content: string }>}
  */
-function renderAndWriteAll(worktreePath, rows) {
-  const decisionsDir = path.join(worktreePath, '.devflow', 'learning');
-  fs.mkdirSync(decisionsDir, { recursive: true });
-
+function renderLearningFiles(worktreePath, rows) {
   const decisionsFilePath = getDecisionsFilePath(worktreePath);
   const pitfallsFilePath = getPitfallsFilePath(worktreePath);
-  const indexFilePath = getDecisionsIndexPath(worktreePath);
 
   // Hoist active-row selection: computed once per kind, reused for both the
   // body render and the index build — avoids two redundant selectActiveRows passes.
@@ -281,31 +248,53 @@ function renderAndWriteAll(worktreePath, rows) {
   const decisionBlocks = buildBodyBlocks(activeDecisionRows, 'decisions');
   const pitfallBlocks = buildBodyBlocks(activePitfallRows, 'pitfalls');
 
-  const decisionsContent = buildFileFromBlocks(activeDecisionRows, decisionBlocks, 'decisions');
-  const pitfallsContent = buildFileFromBlocks(activePitfallRows, pitfallBlocks, 'pitfalls');
+  return [
+    {
+      path: decisionsFilePath,
+      content: buildFileFromBlocks(activeDecisionRows, decisionBlocks, 'decisions', selectInactiveRows(rows, 'decisions')),
+    },
+    {
+      path: pitfallsFilePath,
+      content: buildFileFromBlocks(activePitfallRows, pitfallBlocks, 'pitfalls', selectInactiveRows(rows, 'pitfalls')),
+    },
+    {
+      // Compact index: a write-time artifact consumed via plain Read.
+      path: getDecisionsIndexPath(worktreePath),
+      content: buildIndexContent(activeDecisionRows, activePitfallRows, {
+        decisionsFilePath,
+        pitfallsFilePath,
+        decisionBlocks,
+        pitfallBlocks,
+      }) + '\n',
+    },
+  ];
+}
+
+/**
+ * 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/`:
+ * 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
+ */
+function renderAndWriteAll(worktreePath, rows) {
+  if (!hasLearningDir(worktreePath)) {
+    throw new Error(`renderAndWriteAll: no .devflow/learning/ under ${worktreePath}`);
+  }
+  const [decisions, pitfalls, index] = renderLearningFiles(worktreePath, rows);
 
   // 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
   // (none)); on a RE-render the index is stale — one generation behind the new
   // body files — never corrupt. Both cases are benign and self-heal on the next
   // successful render.
-  writeAtomic(decisionsFilePath, decisionsContent);
-  writeAtomic(pitfallsFilePath, pitfallsContent);
-
-  // Build and write compact index (write-time artifact; consumed via plain Read)
-  // Reuses the pre-computed active rows and pre-rendered blocks — no additional
-  // selectActiveRows or format pass.
-  const indexContent = buildIndexContent(activeDecisionRows, activePitfallRows, {
-    decisionsFilePath,
-    pitfallsFilePath,
-    decisionBlocks,
-    pitfallBlocks,
-  });
-  const indexLine = indexContent + '\n';
-  writeAtomic(indexFilePath, indexLine);
+  for (const file of [decisions, pitfalls, index]) writeFileAtomic(file.path, file.content);
 
   process.stderr.write(
-    `[render-decisions] wrote decisions.md (${Buffer.byteLength(decisionsContent)}B) + pitfalls.md (${Buffer.byteLength(pitfallsContent)}B) + index.md (${Buffer.byteLength(indexLine)}B)\n`
+    `[render-decisions] wrote decisions.md (${Buffer.byteLength(decisions.content)}B) + pitfalls.md (${Buffer.byteLength(pitfalls.content)}B) + index.md (${Buffer.byteLength(index.content)}B)\n`
   );
 }
 
@@ -313,106 +302,142 @@ function renderAndWriteAll(worktreePath, rows) {
 // CLI entry point
 // ---------------------------------------------------------------------------
 
-if (require.main === module) {
-  const argv = process.argv.slice(2);
-
-  const USAGE =
-    'Usage:\n' +
-    '  render-decisions.cjs render <worktree>          Write both .md files\n' +
-    '  render-decisions.cjs --check <worktree>         Diff without writing; exit 1 on drift\n';
-
-  // Parse: `render <worktree>` or `--check <worktree>`
-  let mode; // 'render' | 'check'
-  let worktreePath;
-
-  if (argv[0] === 'render' && argv[1]) {
-    mode = 'render';
-    worktreePath = path.resolve(argv[1]);
-  } else if (argv[0] === '--check' && argv[1]) {
-    mode = 'check';
-    worktreePath = path.resolve(argv[1]);
-  } else {
-    process.stderr.write(USAGE);
-    process.exit(1);
+/** The name the CLI's messages carry; the lock reports it as the op. */
+const CLI_NAME = 'render-decisions';
+
+const USAGE =
+  'Usage (run from the project root; <worktree> names the current directory, e.g. "."):\n' +
+  '  render-decisions.cjs render <worktree>          Write decisions.md, pitfalls.md and index.md\n' +
+  '  render-decisions.cjs --check <worktree>         Compare without writing; exit 1 on drift\n';
+
+/**
+ * The project root the CLI works in: the current directory, with symlinks
+ * resolved. The CLI runs from the project root, as the json-helper ops do, and
+ * `<worktree>` must name that same directory once resolved (safePath refuses a NUL
+ * byte). The argument is only compared: every path the CLI reads or writes is
+ * built from the current directory, never from argv.
+ *
+ * @param {string} arg - the `<worktree>` argument
+ * @returns {{ ok: true, value: string } | { ok: false, error: { kind: 'invalid-root', message: string } }}
+ */
+function resolveCliRoot(arg) {
+  const invalid = message => ({ ok: false, error: { kind: 'invalid-root', message: `${CLI_NAME}: ${message}` } });
+  let cwd;
+  let named;
+  try {
+    cwd = fs.realpathSync(process.cwd());
+    named = fs.realpathSync(safePath(arg));
+  } catch (err) {
+    return invalid(`invalid worktree path: ${err.message}`);
+  }
+  if (named !== cwd) {
+    return invalid(`${named} is not the current directory ${cwd} — run from the project root`);
   }
+  return { ok: true, value: cwd };
+}
+
+/** Report on stderr how many ledger lines were not one JSON object, when any were. */
+function reportMalformed(count, ledgerPath) {
+  if (count === 0) return;
+  process.stderr.write(
+    `[render-decisions] MALFORMED: ${count} ledger line${count === 1 ? '' : 's'} skipped (${ledgerPath})\n`
+  );
+}
 
-  // Validate path at trust boundary before any file operations.
-  // safePath rejects null bytes, which path.resolve preserves silently.
+/** The ledger's rows, reporting its malformed lines on stderr. Read-only. */
+function readLedgerRows(root) {
+  const ledgerPath = getDecisionsLedgerPath(root);
+  const { rows, rejected } = readJsonl(ledgerPath);
+  reportMalformed(rejected.length, ledgerPath);
+  return rows;
+}
+
+/** The file's content, or null when it does not exist. */
+function readIfPresent(file) {
   try {
-    worktreePath = safePath(worktreePath);
+    return fs.readFileSync(file, 'utf8');
   } catch (err) {
-    process.stderr.write(`render-decisions: invalid worktree path: ${err.message}\n`);
-    process.exit(1);
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
   }
+}
 
-  const decisionsDir = path.join(worktreePath, '.devflow', 'learning');
-  const ledgerPath = path.join(decisionsDir, LEDGER_FILENAME);
-  const decisionsFilePath = getDecisionsFilePath(worktreePath);
-  const pitfallsFilePath = getPitfallsFilePath(worktreePath);
-  const indexFilePath = getDecisionsIndexPath(worktreePath);
-  const lockDir = getDecisionsLockDir(worktreePath);
-
-  // Ensure decisionsDir exists (needed before lock acquisition and file reads)
-  fs.mkdirSync(decisionsDir, { recursive: true });
-
-  // Read ledger (empty corpus if absent)
-  const rows = parseLedger(ledgerPath);
-
-  if (mode === 'check') {
-    // Render all three files in memory and compare against on-disk content.
-    // Exit non-zero on drift.
-    // Hoist active-row selection (mirrors renderAndWriteAll): computed once per kind,
-    // reused for both body render and index build.
-    const activeDecisionRows = selectActiveRows(rows, 'decisions');
-    const activePitfallRows = selectActiveRows(rows, 'pitfalls');
-    const decisionsContent = renderBodyFromActive(activeDecisionRows, 'decisions');
-    const pitfallsContent = renderBodyFromActive(activePitfallRows, 'pitfalls');
-    const indexContent = buildIndexContent(activeDecisionRows, activePitfallRows, {
-      decisionsFilePath,
-      pitfallsFilePath,
-    }) + '\n';
-
-    let drift = false;
-    let existingDecisions = '';
-    let existingPitfalls = '';
-    let existingIndex = '';
-    try { existingDecisions = fs.readFileSync(decisionsFilePath, 'utf8'); } catch { drift = true; }
-    try { existingPitfalls = fs.readFileSync(pitfallsFilePath, 'utf8'); } catch { drift = true; }
-    // index.md missing is a drift condition (it should always be present after a render)
-    try { existingIndex = fs.readFileSync(indexFilePath, 'utf8'); } catch { drift = true; }
-
-    if (!drift) {
-      if (existingDecisions !== decisionsContent) {
-        process.stderr.write(`[render-decisions] DRIFT: ${decisionsFilePath}\n`);
-        drift = true;
-      }
-      if (existingPitfalls !== pitfallsContent) {
-        process.stderr.write(`[render-decisions] DRIFT: ${pitfallsFilePath}\n`);
-        drift = true;
-      }
-      if (existingIndex !== indexContent) {
-        process.stderr.write(`[render-decisions] DRIFT: ${indexFilePath}\n`);
-        drift = true;
-      }
-    }
+/**
+ * `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
+ * (D-NO-STRAY-TREE), and when it or `.devflow` is a symbolic link (D-NO-LINKED-TREE).
+ *
+ * @param {string} root
+ * @returns {number} exit code
+ */
+function renderCommand(root) {
+  const result = withDecisionsLock(CLI_NAME, root, () => {
+    renderAndWriteAll(root, readLedgerRows(root));
+    return { ok: true, value: null };
+  });
+  if (result.ok) return 0;
+  process.stderr.write(`${result.error.message}\n`);
+  return 1;
+}
 
-    process.exit(drift ? 1 : 0);
+/**
+ * `--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).
+ *
+ * @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`);
+    return 1;
+  }
+  let drift = false;
+  for (const file of renderLearningFiles(root, readLedgerRows(root))) {
+    const onDisk = readIfPresent(file.path);
+    if (onDisk !== file.content) {
+      process.stderr.write(`[render-decisions] DRIFT: ${file.path}${onDisk === null ? ' (missing)' : ''}\n`);
+      drift = true;
+    }
   }
+  return drift ? 1 : 0;
+}
 
-  // mode === 'render': write atomically under lock
-  if (!acquireMkdirLock(lockDir, 30000, 60000)) {
-    process.stderr.write(`render-decisions: timeout acquiring lock at ${lockDir}\n`);
-    process.exit(1);
+/**
+ * Run the CLI on its arguments and return the exit code. Neither mode creates the
+ * learning directory (D-NO-STRAY-TREE).
+ *
+ * @param {string[]} argv - the arguments after the script path
+ * @returns {number}
+ */
+function runCli(argv) {
+  const mode = argv[0] === 'render' || argv[0] === '--check' ? argv[0] : null;
+  if (mode === null || argv.length !== 2 || !argv[1]) {
+    process.stderr.write(USAGE);
+    return 1;
   }
+  const root = resolveCliRoot(argv[1]);
+  if (!root.ok) {
+    process.stderr.write(`${root.error.message}\n`);
+    return 1;
+  }
+  return mode === 'render' ? renderCommand(root.value) : checkCommand(root.value);
+}
 
+if (require.main === module) {
+  // The one exit, outside every lock: withDecisionsLock has released its lock
+  // before runCli returns or throws.
+  let exitCode;
   try {
-    // Use the lock-free helper — we already hold the lock.
-    renderAndWriteAll(worktreePath, rows);
-  } finally {
-    releaseLock(lockDir);
+    exitCode = runCli(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`${CLI_NAME}: ${err && err.message ? err.message : String(err)}\n`);
+    exitCode = 1;
   }
-
-  process.exit(0);
+  process.exit(exitCode);
 }
 
 // ---------------------------------------------------------------------------
@@ -421,8 +446,10 @@ if (require.main === module) {
 
 module.exports = {
   renderDecisionsFile,
+  renderLearningFiles,
   renderAndWriteAll,
   selectActiveRows,
+  selectInactiveRows,
   parseLedger,
   isActive,
   anchorNumeric,

package/src/assets/scripts/hooks/memory-worker

@@ -64,6 +64,16 @@ source "$SCRIPT_DIR/get-mtime" || { echo "memory-worker: failed to source get-mt
 # BEFORE spawning to prevent a second concurrent Stop hook from double-spawning
 # within the same 120s window.
 TRIGGER_FILE="$MEMORY_DIR/.working-memory-last-trigger"
+
+# D-HOOKS-NO-SYMLINK (git-marker): the stamp below is a `touch`, which follows
+# a symbolic link, so a linked stamp or memory folder is never stamped, and with no
+# stamp to throttle it no worker is spawned either.
+if ! df_no_symlink_below "$PROJECT_ROOT" "$TRIGGER_FILE"; then
+  log "SKIP: a symbolic link sits on the path to $TRIGGER_FILE; nothing written, worker not spawned"
+  dbg "EXIT: symbolic link on the throttle path"
+  exit 0
+fi
+
 NOW=$(date +%s)
 LAST_TRIGGER=0
 if [ -f "$TRIGGER_FILE" ]; then