devflow-kit 2.2.0 → 2.3.0

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

@@ -9,12 +9,13 @@
 //
 // BYTE-COMPAT CONTRACT (must not change without updating all consumers):
 //   Decision heading:  \n## {anchorId}: {title}\n
-//   Decision fields:   - **Date**: YYYY-MM-DD\n
+//   Decision fields:   - **Date**: YYYY-MM-DD\n          (empty string when absent — render purity, ADR-022: never clock-read in a formatter)
 //                      - **Status**: Accepted\n
 //                      - **Context**: ...\n
 //                      - **Decision**: ...\n
 //                      - **Consequences**: ...\n
 //                      - **Source**: self-learning:{obsId}\n
+//                      - **Amendments**: text1; text2\n   (omitted when absent or empty)
 //   Pitfall heading:   \n## {anchorId}: {title}\n
 //   Pitfall fields:    - **Area**: ...\n
 //                      - **Issue**: ...\n
@@ -22,11 +23,36 @@
 //                      - **Resolution**: ...\n
 //                      - **Status**: Active\n
 //                      - **Source**: self-learning:{obsId}\n
+//                      - **Amendments**: text1; text2\n   (omitted when absent or empty)
 //   TL;DR line:        <!-- TL;DR: N {decisions|pitfalls}. Key: id1, id2 -->
 //   File headers:
 //     decisions.md: "<!-- TL;DR: 0 decisions. Key: -->\n# Architectural Decisions\n\nAppend-only. Status changes allowed; deletions prohibited.\n"
 //     pitfalls.md:  "<!-- TL;DR: 0 pitfalls. Key: -->\n# Known Pitfalls\n\nArea-specific gotchas, fragile areas, and past bugs.\n"
 //
+// Field parsing: both formatters use segmentDetails() which splits on ';' and
+// anchors key detection to the START of each trimmed segment — so 'reissue:'
+// does NOT match 'issue:', and embedded semicolons inside a field value are
+// preserved (the segment is treated as a continuation of the prior field).
+// Recovery pass: for any key the anchored pass left unset, an unanchored
+// regex ('(?:^|[.;\\s])key:\\s*([^;]+)') is tried against the full details
+// string — handles legacy corpus rows written before the ';'-delimited grammar
+// was documented, where fields are separated by '. ' rather than ';' (applies
+// PF-044). The recovery pass never overrides an anchored match.
+// LineTerminators (\r, \n, \u2028, \u2029) in field values are collapsed to a
+// single space at all five collapse sites (segmentDetails ×2, amendmentToString
+// ×3) — guards the single-line field contract against the full JS LineTerminator
+// set, not just \n.
+//
+// Index extraction: extractEntryFromBlock uses line-anchored regexes
+// (/^- \*\*Status\*\*:/m, /^- \*\*Area\*\*:/m) to guard against amendment
+// text that accidentally contains those patterns as substrings.
+//
+// Amendments shape: the row's `amendments` array accepts BOTH the
+// { date, note } objects declared by LearningObservation/LedgerRow in
+// src/core/observations.ts (rendered as `[date] note`) and pre-rendered
+// strings.  formatAmendmentsLine normalises per entry — never a bare join,
+// which would emit `[object Object]` for the schema-declared shape.
+//
 // Consumers of these strings:
 //   - session-start-context (line 57): reads TL;DR comment via sed
 //   - devflow:apply-decisions: reads ## ADR-NNN: / ## PF-NNN: headings
@@ -35,6 +61,170 @@
 
 'use strict';
 
+/** JS LineTerminator set — /m `^` matches after each of these and `.` excludes them. */
+const LINE_TERMINATORS = /[\r\n\u2028\u2029]/g;
+
+/**
+ * Segment-parse a details string into key→value pairs using anchored key
+ * detection.  Splits on ';' and checks whether each trimmed segment begins
+ * with one of the recognised keys (e.g. 'area:').  If a segment does NOT
+ * begin with a recognised key it is treated as a continuation of the
+ * previous field — this preserves embedded semicolons inside a field value.
+ *
+ * Key detection is anchored to the START of the trimmed segment so that
+ * 'reissue:' does NOT match 'issue:', 'precontext:' does NOT match
+ * 'context:', etc.  All matching is case-insensitive.
+ *
+ * JS LineTerminators (\r, \n,  ,  ) inside values are collapsed to a
+ * single space so the formatted output lines remain single-line (guards the
+ * full LineTerminator set, not only \n).
+ *
+ * DUPLICATE KEY POLICY: if the same key appears more than once in the
+ * details string the LAST occurrence wins — each new segment-start match
+ * overwrites the prior value. This is last-match-wins, not priority-ordered
+ * first-match-wins.
+ *
+ * RECOVERY PASS: after the anchored segment pass, any key still unset is
+ * searched for with an unanchored regex ('(?:^|[.;\\s])key:\\s*([^;]+)') so
+ * that legacy corpus rows written before the ';'-delimited grammar was
+ * documented (which embed field keys mid-segment after '. ') are still
+ * parsed correctly. The recovery pass never overrides a value the anchored
+ * pass already set. applies PF-044 (divergence/migration: legacy rows exist
+ * written under the old contract that embedded keys after '. ').
+ *
+ * D002 (details-parsing): This is the SINGLE parser for structured details
+ * strings — both formatDecisionBody and formatPitfallBody delegate here.
+ * applies PF-042 (delimiter-regex truncation).
+ *
+ * @param {string} detailsStr - raw details string from an observation row
+ * @param {readonly string[]} keys - recognised field names
+ * @returns {Record<string, string>} map of field name → extracted value
+ */
+function segmentDetails(detailsStr, keys) {
+  /** @type {Record<string, string>} */
+  const result = {};
+  if (!detailsStr) return result;
+
+  const segments = detailsStr.split(';');
+  let currentKey = null;
+
+  for (const seg of segments) {
+    const trimmed = seg.trim();
+    // Hoist toLowerCase — avoids one allocation per key per segment (PERF-3).
+    const lowered = trimmed.toLowerCase();
+    let matched = false;
+
+    for (const key of keys) {
+      const prefix = key + ':';
+      // Anchored: does the trimmed segment START with '<key>:'?
+      // Lower-casing both sides gives case-insensitive matching without regex.
+      if (lowered.startsWith(prefix)) {
+        currentKey = key;
+        result[key] = trimmed.slice(prefix.length).trim().replace(LINE_TERMINATORS, ' ');
+        matched = true;
+        break;
+      }
+    }
+
+    if (!matched && currentKey !== null) {
+      // Continuation of the previous field's value (embedded semicolons)
+      result[currentKey] = result[currentKey] + '; ' + trimmed.replace(LINE_TERMINATORS, ' ');
+    }
+  }
+
+  // Recovery pass: a key the anchored pass never matched may still appear
+  // mid-segment in legacy corpus rows (written before the ';'-delimited
+  // grammar was documented) where fields are separated by '. ' rather than
+  // ';'. The unanchored regex requires the key to be preceded by a
+  // word-boundary character (^, '.', ';', or whitespace) so that 'reissue:'
+  // still does NOT match 'issue:', and it only fills keys the anchored pass
+  // left unset — never overrides an anchored match. applies PF-044.
+  for (const key of keys) {
+    if (result[key] !== undefined) continue;
+    const m = detailsStr.match(new RegExp('(?:^|[.;\\s])' + key + ':\\s*([^;]+)', 'i'));
+    if (m) result[key] = m[1].trim().replace(LINE_TERMINATORS, ' ');
+  }
+
+  return result;
+}
+
+/**
+ * Normalise one amendment entry to its rendered string form.
+ *
+ * TWO SHAPES are accepted because two authorities define this field:
+ *   - `{ date, note }` — the shape declared by LearningObservation /
+ *     LedgerRow in src/core/observations.ts, and the ONLY shape its
+ *     isLearningObservation type guard accepts. Renders as `[date] note`
+ *     (bare `note` when date is absent/blank).
+ *   - `string` — a pre-rendered `[date] note` line, the convenience form.
+ *
+ * A plain `join` over the object shape would emit `[object Object]`, so the
+ * normalisation is load-bearing rather than defensive. Unrecognised or
+ * note-less entries collapse to '' and are dropped by the caller — a
+ * formatter running under the .decisions.lock must never throw.
+ *
+ * Newlines are collapsed to spaces to preserve the single-line field contract.
+ *
+ * @param {unknown} entry
+ * @returns {string} rendered amendment, or '' when unrenderable
+ */
+function amendmentToString(entry) {
+  if (typeof entry === 'string') return entry.replace(LINE_TERMINATORS, ' ').trim();
+  if (entry && typeof entry === 'object') {
+    const note = typeof entry.note === 'string' ? entry.note.replace(LINE_TERMINATORS, ' ').trim() : '';
+    if (!note) return '';
+    const date = typeof entry.date === 'string' ? entry.date.replace(LINE_TERMINATORS, ' ').trim() : '';
+    return date ? `[${date}] ${note}` : note;
+  }
+  return '';
+}
+
+/**
+ * Format the Amendments line for a decision or pitfall body.
+ * Returns an empty string when the amendments array is absent, empty, or
+ * contains nothing renderable, so callers can concatenate unconditionally
+ * without leaving a blank line.
+ *
+ * Format: `- **Amendments**: text1; text2\n`
+ * A single amendment has no trailing semicolon.
+ *
+ * @param {Array<string | { date?: string, note?: string }> | undefined | null} amendments
+ * @returns {string} formatted line with trailing newline, or '' if empty
+ */
+function formatAmendmentsLine(amendments) {
+  if (!Array.isArray(amendments) || amendments.length === 0) return '';
+  const parts = amendments.map(amendmentToString).filter(Boolean);
+  if (parts.length === 0) return '';
+  return `- **Amendments**: ${parts.join('; ')}\n`;
+}
+
+/**
+ * Guard against raw_body payloads that could forge a second entry heading or
+ * claim a different anchor ID. Accepts only a string whose `^## (ADR|PF)-\d+:`
+ * headings number exactly one AND match `## ${anchorId}:`.
+ *
+ * A rejected raw_body is DROPPED from the row — the entry then renders through
+ * the sanitised formatDecisionBody/formatPitfallBody — the sanctioned fallback when raw_body is absent or rejected (ADR-022).
+ *
+ * Per PF-023: validate at the sink so all callers (assign-anchor, refresh-anchor,
+ * any future op) inherit the guard without repeating it.
+ *
+ * @param {unknown} body
+ * @param {string} anchorId - e.g. 'ADR-001' or 'PF-023'
+ * @returns {boolean}
+ */
+function isSafeRawBody(body, anchorId) {
+  if (typeof body !== 'string') return false;
+  const headings = body.match(/^## (?:ADR|PF)-\d+:/gm) || [];
+  return headings.length === 1 && headings[0] === `## ${anchorId}:`;
+}
+
+/** Recognised field keys for decision entries. */
+const ADR_KEYS = /** @type {const} */ (['context', 'decision', 'rationale']);
+
+/** Recognised field keys for pitfall entries. */
+const PF_KEYS = /** @type {const} */ (['area', 'issue', 'impact', 'resolution']);
+
 /**
  * Return the initial header content for a new decisions or pitfalls file.
  * Byte-identical to the initDecisionsContent function in json-helper.cjs.
@@ -59,22 +249,23 @@ function initDecisionsContent(kind) {
 function formatDecisionBody(row) {
   const detailsStr = row.details || '';
   const obsId = row.id || 'unknown';
-  const artDate = row.date || new Date().toISOString().slice(0, 10);
+  // Render purity (ADR-022): never clock-read inside a formatter.  Absent date
+  // renders as an empty string so the output is deterministic and idempotent.
+  const artDate = row.date || '';
   const anchorId = row.anchor_id || '';
   const pattern = row.pattern || '';
 
-  const contextM = detailsStr.match(/context:\s*([^;]+)/i);
-  const decisionM = detailsStr.match(/decision:\s*([^;]+)/i);
-  const rationaleM = detailsStr.match(/rationale:\s*([^;]+)/i);
+  const fields = segmentDetails(detailsStr, ADR_KEYS);
 
   return (
     `\n## ${anchorId}: ${pattern}\n\n` +
     `- **Date**: ${artDate}\n` +
     `- **Status**: Accepted\n` +
-    `- **Context**: ${(contextM || [])[1] || detailsStr}\n` +
-    `- **Decision**: ${(decisionM || [])[1] || pattern}\n` +
-    `- **Consequences**: ${(rationaleM || [])[1] || ''}\n` +
-    `- **Source**: self-learning:${obsId}\n`
+    `- **Context**: ${fields.context || detailsStr}\n` +
+    `- **Decision**: ${fields.decision || pattern}\n` +
+    `- **Consequences**: ${fields.rationale || ''}\n` +
+    `- **Source**: self-learning:${obsId}\n` +
+    formatAmendmentsLine(row.amendments)
   );
 }
 
@@ -92,19 +283,17 @@ function formatPitfallBody(row) {
   const anchorId = row.anchor_id || '';
   const pattern = row.pattern || '';
 
-  const areaM = detailsStr.match(/area:\s*([^;]+)/i);
-  const issueM = detailsStr.match(/issue:\s*([^;]+)/i);
-  const impactM = detailsStr.match(/impact:\s*([^;]+)/i);
-  const resM = detailsStr.match(/resolution:\s*([^;]+)/i);
+  const fields = segmentDetails(detailsStr, PF_KEYS);
 
   return (
     `\n## ${anchorId}: ${pattern}\n\n` +
-    `- **Area**: ${(areaM || [])[1] || detailsStr}\n` +
-    `- **Issue**: ${(issueM || [])[1] || detailsStr}\n` +
-    `- **Impact**: ${(impactM || [])[1] || ''}\n` +
-    `- **Resolution**: ${(resM || [])[1] || ''}\n` +
+    `- **Area**: ${fields.area || detailsStr}\n` +
+    `- **Issue**: ${fields.issue || detailsStr}\n` +
+    `- **Impact**: ${fields.impact || ''}\n` +
+    `- **Resolution**: ${fields.resolution || ''}\n` +
     `- **Status**: Active\n` +
-    `- **Source**: self-learning:${obsId}\n`
+    `- **Source**: self-learning:${obsId}\n` +
+    formatAmendmentsLine(row.amendments)
   );
 }
 
@@ -122,23 +311,48 @@ function formatPitfallBody(row) {
  * add-path (assign-anchor) and the migration's preserve-verbatim path produce
  * byte-identical committed shapes. applies ADR-008.
  *
+ * Validation at the SINK (per PF-023 — validate at convergence so all callers inherit):
+ *   - expectType: if provided, obs.type must match or this function throws; prevents
+ *     re-projecting across entry types (PF-NNN into decisions.md or vice versa).
+ *   - pattern: JS LineTerminators collapsed to a single space — the heading is
+ *     single-line by construction; a newline in pattern would forge '- **Status**:'
+ *     lines or second '## ADR-NNN:' headings that line-anchored index regexes match first.
+ *   - raw_body: gated by isSafeRawBody — accepts only a body with exactly one heading
+ *     matching anchorId; a rejected body is dropped so the entry renders through the
+ *     sanitised formatDecisionBody/formatPitfallBody instead.
+ *
  * @param {object} obs - Full observation row from decisions-log.jsonl
- * @param {{ anchorId: string, status: string, date?: string }} opts
+ * @param {{ anchorId: string, status: string, date?: string, expectType?: string }} opts
  * @returns {object} Canonical ledger row
  */
-function toLedgerRow(obs, { anchorId, status, date }) {
+function toLedgerRow(obs, { anchorId, status, date, expectType }) {
+  // Type guard — per PF-023: validate at the sink so all callers (assign-anchor,
+  // refresh-anchor, any future op) inherit the check without repeating it.
+  if (expectType !== undefined && obs.type !== expectType) {
+    throw new Error(
+      `toLedgerRow: type mismatch for ${anchorId} — ledger has '${expectType}', log has '${obs.type}'`
+    );
+  }
   /** @type {Record<string, unknown>} */
   const row = {
     id: obs.id,
     type: obs.type,
-    pattern: obs.pattern,
-    details: obs.details,
+    // Heading is single-line by construction — collapse any LLM-injected line terminators
+    // so a newline in pattern cannot forge '- **Status**:' lines or second '## ADR-NNN:'
+    // headings inside the rendered body (those would be matched first by the line-anchored
+    // index regexes in extractEntryFromBlock). applies PF-023.
+    pattern: typeof obs.pattern === 'string' ? obs.pattern.replace(LINE_TERMINATORS, ' ').trim() : obs.pattern,
+    details: obs.details,  // segmentDetails already collapses line terminators at read time
     anchor_id: anchorId,
     decisions_status: status,
   };
   // Optional fields — include only when present in the observation or explicitly provided
   if (date !== undefined) row.date = date;
-  if (obs.raw_body !== undefined) row.raw_body = obs.raw_body;
+  // log-sourced raw_body (ADR-022) — a log row that lost raw_body un-freezes the
+  // entry to formatter-rendered output by design. Gate through isSafeRawBody (PF-023).
+  if (obs.raw_body !== undefined && isSafeRawBody(obs.raw_body, anchorId)) {
+    row.raw_body = obs.raw_body;
+  }
   if (obs.amendments !== undefined) row.amendments = obs.amendments;
   return row;
 }
@@ -210,18 +424,25 @@ function formatIndexEntryLine(entry) {
  * Empty corpus (both arrays empty) → '(none)'.
  * No trailing newline (caller adds '\n' before writing).
  *
- * Strategy: for each row, obtain its rendered block (truthy raw_body || format*Body(row)),
- * then extract heading/Status/Area with the same regexes.
+ * Strategy: for each row, obtain its rendered block (pre-rendered block when
+ * provided, else truthy raw_body || format*Body(row)), then extract
+ * heading/Status/Area with the same regexes.
  * This preserves byte-compat for migrated rows that carry Area/Status only in raw_body.
  * Note: raw_body === "" is treated as absent (falsy); both predicates align with the
  * truthy check in renderDecisionsFile so index and body files never drift on this edge.
  *
  * @param {object[]} activeDecisionRows - Active decision rows (type='decision', sorted by anchor)
  * @param {object[]} activePitfallRows - Active pitfall rows (type='pitfall', sorted by anchor)
- * @param {{ decisionsFilePath: string, pitfallsFilePath: string }} opts - absolute file paths for footer
+ * @param {{ decisionsFilePath: string, pitfallsFilePath: string, decisionBlocks?: string[], pitfallBlocks?: string[] }} opts
+ *   decisionsFilePath / pitfallsFilePath — absolute file paths for footer.
+ *   decisionBlocks / pitfallBlocks — optional pre-rendered per-row blocks (one entry per
+ *   active row, same order as the row arrays). When provided, each block is used directly
+ *   instead of re-rendering the row, so callers that already built blocks for the body
+ *   files avoid a second full render pass (PERF-2). The fallback expression
+ *   (raw_body || format*Body(row)) is used when the arrays are absent.
  * @returns {string} compact index string, or '(none)'
  */
-function buildIndexContent(activeDecisionRows, activePitfallRows, { decisionsFilePath, pitfallsFilePath }) {
+function buildIndexContent(activeDecisionRows, activePitfallRows, { decisionsFilePath, pitfallsFilePath, decisionBlocks, pitfallBlocks }) {
   /**
    * Extract an index entry from a rendered block string.
    * @param {string} block
@@ -232,25 +453,30 @@ function buildIndexContent(activeDecisionRows, activePitfallRows, { decisionsFil
     if (!headingMatch) return null;
     const id = headingMatch[1];
     const rawTitle = headingMatch[2].trim();
-    const statusMatch = block.match(/- \*\*Status\*\*: (.+)/);
+    // Line-anchored regexes prevent amendment text that contains "- **Status**:"
+    // or "- **Area**:" as a substring from hijacking the extracted values.
+    // The /m (multiline) flag makes ^ match at the start of any line in the block.
+    const statusMatch = block.match(/^- \*\*Status\*\*: (.+)/m);
     const status = statusMatch ? statusMatch[1].trim() : null;
-    const areaMatch = block.match(/- \*\*Area\*\*: (.+)/);
+    const areaMatch = block.match(/^- \*\*Area\*\*: (.+)/m);
     const area = areaMatch ? areaMatch[1].trim() : null;
     return { id, title: rawTitle, status, area };
   }
 
   /** @type {Array<{ id: string, title: string, status: string|null, area: string|null }>} */
   const adrEntries = [];
-  for (const row of activeDecisionRows) {
-    const block = row.raw_body ? row.raw_body : formatDecisionBody(row);
+  for (let i = 0; i < activeDecisionRows.length; i++) {
+    const row = activeDecisionRows[i];
+    const block = decisionBlocks ? decisionBlocks[i] : (row.raw_body ? row.raw_body : formatDecisionBody(row));
     const entry = extractEntryFromBlock(block);
     if (entry) adrEntries.push(entry);
   }
 
   /** @type {Array<{ id: string, title: string, status: string|null, area: string|null }>} */
   const pfEntries = [];
-  for (const row of activePitfallRows) {
-    const block = row.raw_body ? row.raw_body : formatPitfallBody(row);
+  for (let i = 0; i < activePitfallRows.length; i++) {
+    const row = activePitfallRows[i];
+    const block = pitfallBlocks ? pitfallBlocks[i] : (row.raw_body ? row.raw_body : formatPitfallBody(row));
     const entry = extractEntryFromBlock(block);
     if (entry) pfEntries.push(entry);
   }
@@ -260,19 +486,11 @@ function buildIndexContent(activeDecisionRows, activePitfallRows, { decisionsFil
   const blocks = [];
 
   if (adrEntries.length > 0) {
-    const lines = [`Decisions (${adrEntries.length}):`];
-    for (const entry of adrEntries) {
-      lines.push(formatIndexEntryLine(entry));
-    }
-    blocks.push(lines.join('\n'));
+    blocks.push([`Decisions (${adrEntries.length}):`, ...adrEntries.map(formatIndexEntryLine)].join('\n'));
   }
 
   if (pfEntries.length > 0) {
-    const lines = [`Pitfalls (${pfEntries.length}):`];
-    for (const entry of pfEntries) {
-      lines.push(formatIndexEntryLine(entry));
-    }
-    blocks.push(lines.join('\n'));
+    blocks.push([`Pitfalls (${pfEntries.length}):`, ...pfEntries.map(formatIndexEntryLine)].join('\n'));
   }
 
   // Footer: explain how to read full bodies
@@ -293,9 +511,12 @@ function buildIndexContent(activeDecisionRows, activePitfallRows, { decisionsFil
 
 module.exports = {
   initDecisionsContent,
+  segmentDetails,
+  formatAmendmentsLine,
   formatDecisionBody,
   formatPitfallBody,
   buildTldrLine,
   toLedgerRow,
+  isSafeRawBody,
   buildIndexContent,
 };

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

@@ -48,7 +48,7 @@ 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 (assign-anchor, retire-anchor, render CLI) perform
+ * ledger writes. Current callers (assign-anchor, retire-anchor, refresh-anchor, 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

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

@@ -131,21 +131,23 @@ function selectActiveRows(rows, kind) {
 }
 
 /**
- * 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.
+ * Build per-row body blocks from already-filtered + sorted active rows.
+ * 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
  *
+ * Extracted so renderAndWriteAll can compute blocks once and reuse them
+ * for both the body files and buildIndexContent, avoiding a second full
+ * render pass (PERF-2).
+ *
  * @param {object[]} activeRows - already-filtered + sorted active rows
  * @param {'decisions'|'pitfalls'} kind
- * @returns {string} complete file content
+ * @returns {string[]} per-row rendered blocks
  */
-function renderBodyFromActive(activeRows, kind) {
-  // Build per-row blocks
-  const blocks = activeRows.map(row => {
+function buildBodyBlocks(activeRows, kind) {
+  return activeRows.map(row => {
     if (row.raw_body) {
       // Migrated entry: emit verbatim. raw_body must start with \n## so
       // it fits seamlessly after the header preamble.
@@ -155,7 +157,18 @@ function renderBodyFromActive(activeRows, kind) {
       ? formatDecisionBody(row)
       : formatPitfallBody(row);
   });
+}
 
+/**
+ * Assemble the full file content from pre-computed blocks and active rows.
+ * 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
+ * @returns {string} complete file content
+ */
+function buildFileFromBlocks(activeRows, blocks, kind) {
   // Build TL;DR line (uses active + sorted rows so last-5 are stable)
   const tldr = buildTldrLine(kind, activeRows);
 
@@ -170,6 +183,23 @@ function renderBodyFromActive(activeRows, kind) {
   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);
+}
+
 /**
  * Pure render function. Produces the full content of a decisions.md or
  * pitfalls.md file from the given ledger rows.
@@ -224,9 +254,9 @@ function writeAtomic(filePath, content) {
 
 /**
  * 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)
- * must already hold .decisions.lock. The standalone `render` CLI takes the lock
- * before calling this function.
+ * 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.
  *
@@ -246,8 +276,13 @@ function renderAndWriteAll(worktreePath, rows) {
   const activeDecisionRows = selectActiveRows(rows, 'decisions');
   const activePitfallRows = selectActiveRows(rows, 'pitfalls');
 
-  const decisionsContent = renderBodyFromActive(activeDecisionRows, 'decisions');
-  const pitfallsContent = renderBodyFromActive(activePitfallRows, 'pitfalls');
+  // Build per-row blocks once — reused for body files and index so
+  // buildIndexContent does not re-render every entry a second time (PERF-2).
+  const decisionBlocks = buildBodyBlocks(activeDecisionRows, 'decisions');
+  const pitfallBlocks = buildBodyBlocks(activePitfallRows, 'pitfalls');
+
+  const decisionsContent = buildFileFromBlocks(activeDecisionRows, decisionBlocks, 'decisions');
+  const pitfallsContent = buildFileFromBlocks(activePitfallRows, pitfallBlocks, 'pitfalls');
 
   // 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
@@ -258,15 +293,19 @@ function renderAndWriteAll(worktreePath, rows) {
   writeAtomic(pitfallsFilePath, pitfallsContent);
 
   // Build and write compact index (write-time artifact; consumed via plain Read)
-  // Reuses the pre-computed active rows — no additional selectActiveRows pass.
+  // 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,
   });
-  writeAtomic(indexFilePath, indexContent + '\n');
+  const indexLine = indexContent + '\n';
+  writeAtomic(indexFilePath, indexLine);
 
   process.stderr.write(
-    `[render-decisions] wrote decisions.md (${decisionsContent.length}B) + pitfalls.md (${pitfallsContent.length}B) + index.md (${indexContent.length}B)\n`
+    `[render-decisions] wrote decisions.md (${Buffer.byteLength(decisionsContent)}B) + pitfalls.md (${Buffer.byteLength(pitfallsContent)}B) + index.md (${Buffer.byteLength(indexLine)}B)\n`
   );
 }
 
@@ -277,14 +316,10 @@ function renderAndWriteAll(worktreePath, rows) {
 if (require.main === module) {
   const argv = process.argv.slice(2);
 
-  if (argv.length === 0) {
-    process.stderr.write(
-      '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'
-    );
-    process.exit(1);
-  }
+  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'
@@ -297,11 +332,7 @@ if (require.main === module) {
     mode = 'check';
     worktreePath = path.resolve(argv[1]);
   } else {
-    process.stderr.write(
-      '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'
-    );
+    process.stderr.write(USAGE);
     process.exit(1);
   }