devflow-kit 1.8.3 → 2.0.0

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

@@ -0,0 +1,243 @@
+#!/bin/bash
+
+# JSON parsing helper — tries jq, falls back to node json-helper.js
+# Usage: source "$SCRIPT_DIR/json-parse"
+#
+# After sourcing, check $_JSON_AVAILABLE before using json_* functions.
+# All functions read from stdin unless noted otherwise.
+
+_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_JSON_HELPER="$_SCRIPT_DIR/json-helper.cjs"
+
+_HAS_JQ=false
+_HAS_NODE=false
+command -v jq &>/dev/null && _HAS_JQ=true
+command -v node &>/dev/null && _HAS_NODE=true
+
+if [ "$_HAS_JQ" = "false" ] && [ "$_HAS_NODE" = "false" ]; then
+  _JSON_AVAILABLE=false
+  return 0 2>/dev/null || exit 0
+fi
+_JSON_AVAILABLE=true
+
+# --- Core field extraction ---
+
+# Extract a field from stdin JSON. Usage: echo '{"k":"v"}' | json_field "k" "default"
+json_field() {
+  local field="$1" default="${2:-}"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -r ".$field // \"$default\"" 2>/dev/null
+  else
+    node "$_JSON_HELPER" get-field "$field" "$default"
+  fi
+}
+
+# Extract a field from a JSON file. Usage: json_field_file "/path/to/file.json" "field" "default"
+# Note: uses if/then/else to preserve boolean false (jq // operator would replace false with default)
+json_field_file() {
+  local file="$1" field="$2" default="${3:-}"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -r "if (.$field | type) == \"null\" then \"$default\" else (.$field | tostring) end" "$file" 2>/dev/null
+  else
+    node "$_JSON_HELPER" get-field-file "$file" "$field" "$default"
+  fi
+}
+
+# --- Validation ---
+
+# Validate stdin as JSON (exit code 0/1). Usage: echo '{}' | json_valid
+json_valid() {
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -e . >/dev/null 2>&1
+  else
+    node "$_JSON_HELPER" validate
+  fi
+}
+
+# --- Compact ---
+
+# Compact stdin JSON to single line. Usage: echo '{ "k": "v" }' | json_compact
+json_compact() {
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -c '.' 2>/dev/null
+  else
+    node "$_JSON_HELPER" compact
+  fi
+}
+
+# --- Construction ---
+
+# Build a JSON object from --arg/--argjson pairs.
+# Usage: json_construct --arg key1 val1 --arg key2 val2
+json_construct() {
+  if [ "$_HAS_JQ" = "true" ]; then
+    # Build jq expression from args
+    local jq_args=()
+    local fields=""
+    local i=0
+    while [ $i -lt $# ]; do
+      local flag="${!((i+1))}"
+      if [ "$flag" = "--arg" ]; then
+        local name="${!((i+2))}"
+        local val="${!((i+3))}"
+        jq_args+=(--arg "$name" "$val")
+        if [ -n "$fields" ]; then fields="$fields, "; fi
+        fields="${fields}${name}: \$${name}"
+        i=$((i + 3))
+      elif [ "$flag" = "--argjson" ]; then
+        local name="${!((i+2))}"
+        local val="${!((i+3))}"
+        jq_args+=(--argjson "$name" "$val")
+        if [ -n "$fields" ]; then fields="$fields, "; fi
+        fields="${fields}${name}: \$${name}"
+        i=$((i + 3))
+      else
+        i=$((i + 1))
+      fi
+    done
+    jq -n -c "${jq_args[@]}" "{$fields}" 2>/dev/null
+  else
+    node "$_JSON_HELPER" construct "$@"
+  fi
+}
+
+# --- Field updates ---
+
+# Update a field on stdin JSON. Usage: echo '{"k":"v"}' | json_update_field "k" "new_v"
+json_update_field() {
+  local field="$1" value="$2"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -c --arg v "$value" ".$field = \$v" 2>/dev/null
+  else
+    node "$_JSON_HELPER" update-field "$field" "$value"
+  fi
+}
+
+# Update a field with a JSON value. Usage: echo '{}' | json_update_field_json "k" '42'
+json_update_field_json() {
+  local field="$1" value="$2"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -c --argjson v "$value" ".$field = \$v" 2>/dev/null
+  else
+    node "$_JSON_HELPER" update-field "$field" "$value" --json
+  fi
+}
+
+# --- Slurp operations ---
+
+# Slurp JSONL file, sort by field desc, output as JSONL (one line per entry).
+# Usage: json_slurp_cap "file.jsonl" "confidence" 100
+json_slurp_cap() {
+  local file="$1" field="$2" limit="${3:-100}"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -c '.' "$file" | jq -s "sort_by(.$field) | reverse | .[0:$limit][]" 2>/dev/null
+  else
+    node "$_JSON_HELPER" slurp-cap "$file" "$field" "$limit"
+  fi
+}
+
+# --- Array operations ---
+
+# Get length of array at path. Usage: echo '{"obs":[1,2]}' | json_array_length "observations"
+json_array_length() {
+  local path="$1"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq ".$path | length" 2>/dev/null
+  else
+    node "$_JSON_HELPER" array-length "$path"
+  fi
+}
+
+# Get item at index from array. Usage: echo '{"obs":[{},{}]}' | json_array_item "observations" 0
+json_array_item() {
+  local path="$1" index="$2"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -c ".${path}[$index]" 2>/dev/null
+  else
+    node "$_JSON_HELPER" array-item "$path" "$index"
+  fi
+}
+
+# --- Multi-field batched extraction ---
+
+# Extract cwd and an arbitrary top-level field from stdin JSON in a single
+# subprocess. Uses ASCII SOH (U+0001) as delimiter -- safe for field values
+# containing tabs or backslashes, and compatible with bash 3.2 parameter
+# expansion (unlike NUL byte). Always written as the \u0001 jq escape (never
+# a literal control byte) so the delimiter stays visible in source review.
+# Caller pattern (zero extra subprocesses for the split):
+#   FIELDS=$(printf '%s' "$INPUT" | json_extract_cwd_field "last_assistant_message")
+#   CWD="${FIELDS%%$'\001'*}"
+#   VALUE="${FIELDS#*$'\001'}"
+# This replaces the @tsv/@cut pattern, which corrupts tab chars in field values to "\t".
+json_extract_cwd_field() {
+  local field="$1"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -r --arg f "$field" '(.cwd // "") + "\u0001" + (.[$f] // "")' 2>/dev/null
+  else
+    node "$_JSON_HELPER" extract-cwd-field "$field"
+  fi
+}
+
+# Thin wrapper over json_extract_cwd_field -- kept as a named function since
+# it is the most common call site (capture-prompt, preamble).
+json_extract_cwd_prompt() {
+  json_extract_cwd_field "prompt"
+}
+
+# --- Transcript extraction ---
+
+# Extract text messages from Claude message JSON. Usage: printf '%s\n' '{"message":...}' | json_extract_messages
+json_extract_messages() {
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -r 'if .message.content then
+      if (.message.content | type) == "string" then .message.content
+      else [.message.content[] | select(.type == "text") | .text] | join("\n")
+      end
+    else "" end' 2>/dev/null
+  else
+    node "$_JSON_HELPER" extract-text-messages
+  fi
+}
+
+# --- Hook output envelopes ---
+
+# Build SessionStart output. Usage: json_session_output "$CONTEXT"
+json_session_output() {
+  local ctx="$1"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -n --arg ctx "$ctx" '{
+      "hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": $ctx
+      }
+    }'
+  else
+    node "$_JSON_HELPER" session-output "$ctx"
+  fi
+}
+
+# Build UserPromptSubmit output. Usage: json_prompt_output "$CONTEXT"
+json_prompt_output() {
+  local ctx="$1"
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -n --arg ctx "$ctx" '{
+      "hookSpecificOutput": {
+        "hookEventName": "UserPromptSubmit",
+        "additionalContext": $ctx
+      }
+    }'
+  else
+    node "$_JSON_HELPER" prompt-output "$ctx"
+  fi
+}
+
+# Build pre-compact backup JSON. Usage: json_backup_construct --arg ts X --arg branch Y ...
+json_backup_construct() {
+  if [ "$_HAS_JQ" = "true" ]; then
+    jq -n "$@" '{timestamp: $ts, trigger: "pre-compact", memory_snapshot: $memory, git: {branch: $branch, status: $status, log: $log, diff_stat: $diff}}'
+  else
+    node "$_JSON_HELPER" backup-construct "$@"
+  fi
+}
+

package/src/assets/scripts/hooks/learning-lock

@@ -0,0 +1,44 @@
+#!/bin/bash
+# mkdir-based locking, portable across BSD (macOS) and GNU (Linux) stat.
+#
+# Source-order requirement: source get-mtime (src/assets/scripts/hooks/get-mtime) BEFORE
+# sourcing this file so get_mtime() is defined and stale-lock detection uses a
+# real mtime. If get_mtime is not yet defined when a lock_dir already exists,
+# this file falls back to treating the lock as maximally stale (immediate
+# break) rather than crashing on a BSD-only stat flag — safe-by-construction,
+# never a hard failure, but source get-mtime first for accurate staleness.
+
+learning_lock_acquire() {
+  local lock_dir="$1"
+  local timeout="${2:-3}"
+  local stale_threshold=30
+  local waited=0
+
+  # Break stale locks
+  if [ -d "$lock_dir" ]; then
+    local lock_age lock_mtime
+    if declare -F get_mtime >/dev/null 2>&1; then
+      lock_mtime=$(get_mtime "$lock_dir")
+    else
+      lock_mtime=""
+    fi
+    lock_mtime="${lock_mtime:-0}"
+    lock_age=$(( $(date +%s) - lock_mtime ))
+    if [ "$lock_age" -gt "$stale_threshold" ]; then
+      rmdir "$lock_dir" 2>/dev/null || true
+    fi
+  fi
+
+  while [ "$waited" -lt "$timeout" ]; do
+    if mkdir "$lock_dir" 2>/dev/null; then
+      return 0
+    fi
+    sleep 1
+    waited=$(( waited + 1 ))
+  done
+  return 1
+}
+
+learning_lock_release() {
+  rmdir "$1" 2>/dev/null || true
+}

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

@@ -0,0 +1,301 @@
+// src/assets/scripts/hooks/lib/decisions-format.cjs
+//
+// Shared pure formatting helpers for decisions.md and pitfalls.md output.
+//
+// DESIGN: Shared pure formatting helpers used by assign-anchor (via json-helper.cjs)
+// and render-decisions.cjs so both 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.
+//
+// BYTE-COMPAT CONTRACT (must not change without updating all consumers):
+//   Decision heading:  \n## {anchorId}: {title}\n
+//   Decision fields:   - **Date**: YYYY-MM-DD\n
+//                      - **Status**: Accepted\n
+//                      - **Context**: ...\n
+//                      - **Decision**: ...\n
+//                      - **Consequences**: ...\n
+//                      - **Source**: self-learning:{obsId}\n
+//   Pitfall heading:   \n## {anchorId}: {title}\n
+//   Pitfall fields:    - **Area**: ...\n
+//                      - **Issue**: ...\n
+//                      - **Impact**: ...\n
+//                      - **Resolution**: ...\n
+//                      - **Status**: Active\n
+//                      - **Source**: self-learning:{obsId}\n
+//   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"
+//
+// Consumers of these strings:
+//   - session-start-context (line 57): reads TL;DR comment via sed
+//   - devflow:apply-decisions: reads ## ADR-NNN: / ## PF-NNN: headings
+//   - decisions-usage-scan: scans /(ADR|PF)-\d{3}/ anchors
+//   - buildIndexContent (below): parses ## heading, - **Status**:, - **Area**: lines from rendered blocks
+
+'use strict';
+
+/**
+ * Return the initial header content for a new decisions or pitfalls file.
+ * Byte-identical to the initDecisionsContent function in json-helper.cjs.
+ *
+ * @param {'decision'|'pitfall'} kind
+ * @returns {string}
+ */
+function initDecisionsContent(kind) {
+  return kind === 'decision'
+    ? '<!-- TL;DR: 0 decisions. Key: -->\n# Architectural Decisions\n\nAppend-only. Status changes allowed; deletions prohibited.\n'
+    : '<!-- TL;DR: 0 pitfalls. Key: -->\n# Known Pitfalls\n\nArea-specific gotchas, fragile areas, and past bugs.\n';
+}
+
+/**
+ * Format a decision entry block from structured details.
+ * Used when `raw_body` is absent (new entries authored post-migration).
+ * Returns the block starting with a leading newline so appends just work.
+ *
+ * @param {object} row - Ledger row with at minimum: anchor_id, pattern, id, details, date
+ * @returns {string}
+ */
+function formatDecisionBody(row) {
+  const detailsStr = row.details || '';
+  const obsId = row.id || 'unknown';
+  const artDate = row.date || new Date().toISOString().slice(0, 10);
+  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);
+
+  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`
+  );
+}
+
+/**
+ * Format a pitfall entry block from structured details.
+ * Used when `raw_body` is absent (new entries authored post-migration).
+ * Returns the block starting with a leading newline so appends just work.
+ *
+ * @param {object} row - Ledger row with at minimum: anchor_id, pattern, id, details
+ * @returns {string}
+ */
+function formatPitfallBody(row) {
+  const detailsStr = row.details || '';
+  const obsId = row.id || 'unknown';
+  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);
+
+  return (
+    `\n## ${anchorId}: ${pattern}\n\n` +
+    `- **Area**: ${(areaM || [])[1] || detailsStr}\n` +
+    `- **Issue**: ${(issueM || [])[1] || detailsStr}\n` +
+    `- **Impact**: ${(impactM || [])[1] || ''}\n` +
+    `- **Resolution**: ${(resM || [])[1] || ''}\n` +
+    `- **Status**: Active\n` +
+    `- **Source**: self-learning:${obsId}\n`
+  );
+}
+
+/**
+ * Project a full observation row into the canonical committed-ledger shape.
+ * Whitelists ONLY the fields that belong in decisions-ledger.jsonl:
+ *   { id, type, pattern, details, anchor_id, decisions_status, date?, raw_body?, amendments? }
+ *
+ * All observation-lifecycle fields (evidence, confidence, quality_ok, count,
+ * first_seen, last_seen, artifact_path, status, …) are intentionally excluded
+ * from the committed ledger — they are log-only state.
+ *
+ * D001: The projected shape is a DISTINCT COMMITTED shape, not a full obs copy.
+ * This function is the single source of truth for that projection so both the
+ * add-path (assign-anchor) and the migration's preserve-verbatim path produce
+ * byte-identical committed shapes. applies ADR-008.
+ *
+ * @param {object} obs - Full observation row from decisions-log.jsonl
+ * @param {{ anchorId: string, status: string, date?: string }} opts
+ * @returns {object} Canonical ledger row
+ */
+function toLedgerRow(obs, { anchorId, status, date }) {
+  /** @type {Record<string, unknown>} */
+  const row = {
+    id: obs.id,
+    type: obs.type,
+    pattern: obs.pattern,
+    details: obs.details,
+    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;
+  if (obs.amendments !== undefined) row.amendments = obs.amendments;
+  return row;
+}
+
+/**
+ * Build the TL;DR comment line for a rendered decisions or pitfalls file.
+ * Format: `<!-- TL;DR: N {decisions|pitfalls}. Key: id1, id2 -->`
+ *
+ * Key is the last 5 anchor IDs from the provided active rows (sorted by
+ * numeric anchor ascending — same order as the rendered file).
+ * When rows is empty, Key is empty string (no trailing space before -->).
+ *
+ * @param {'decisions'|'pitfalls'} kind - label used in the comment
+ * @param {object[]} rows - active anchored rows (already filtered + sorted)
+ * @returns {string} complete TL;DR comment line (no trailing newline)
+ */
+function buildTldrLine(kind, rows) {
+  const count = rows.length;
+  const last5 = rows.slice(-5).map(r => r.anchor_id);
+  const keyStr = last5.join(', ');
+  // Byte-compat: an empty key list must render `Key: -->` (single space) so the
+  // empty-corpus render is byte-identical to initDecisionsContent's header. A
+  // trailing space before `-->` would diverge from the documented contract and
+  // break the assertion that the render is the SOLE format authority.
+  if (!keyStr) return `<!-- TL;DR: ${count} ${kind}. Key: -->`;
+  return `<!-- TL;DR: ${count} ${kind}. Key: ${keyStr} -->`;
+}
+
+// ---------------------------------------------------------------------------
+// Index content builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Statuses recognised by the index formatter — everything else renders as
+ * [unknown]. Only Active (pitfalls) and Accepted (decisions) appear in
+ * rendered .md files; the renderer excludes Deprecated/Superseded/Retired
+ * before writing.
+ */
+const INDEX_KNOWN_STATUSES = ['Active', 'Accepted'];
+
+/**
+ * Truncate a string to maxLen characters, appending '…' if truncated.
+ *
+ * @param {string} str
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen) + '…';
+}
+
+/**
+ * Format a single index line for an ADR or PF entry.
+ * ADR entries have area: null, so the area suffix is naturally omitted.
+ *
+ * @param {{ id: string, title: string, status: string|null, area: string|null }} entry
+ * @returns {string}
+ */
+function formatIndexEntryLine(entry) {
+  const title = truncate(entry.title, 60);
+  const tag = entry.status && INDEX_KNOWN_STATUSES.includes(entry.status) ? `[${entry.status}]` : '[unknown]';
+  const areaSuffix = entry.area ? `  —  ${truncate(entry.area, 80)}` : '';
+  return `  ${entry.id}  ${title}  ${tag}${areaSuffix}`;
+}
+
+/**
+ * Build the compact index content from in-memory active ledger rows.
+ * 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.
+ * 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
+ * @returns {string} compact index string, or '(none)'
+ */
+function buildIndexContent(activeDecisionRows, activePitfallRows, { decisionsFilePath, pitfallsFilePath }) {
+  /**
+   * Extract an index entry from a rendered block string.
+   * @param {string} block
+   * @returns {{ id: string, title: string, status: string|null, area: string|null }|null}
+   */
+  function extractEntryFromBlock(block) {
+    const headingMatch = block.match(/^## ((?:ADR|PF)-\d+): (.+)/m);
+    if (!headingMatch) return null;
+    const id = headingMatch[1];
+    const rawTitle = headingMatch[2].trim();
+    const statusMatch = block.match(/- \*\*Status\*\*: (.+)/);
+    const status = statusMatch ? statusMatch[1].trim() : null;
+    const areaMatch = block.match(/- \*\*Area\*\*: (.+)/);
+    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);
+    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);
+    const entry = extractEntryFromBlock(block);
+    if (entry) pfEntries.push(entry);
+  }
+
+  if (adrEntries.length === 0 && pfEntries.length === 0) return '(none)';
+
+  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'));
+  }
+
+  if (pfEntries.length > 0) {
+    const lines = [`Pitfalls (${pfEntries.length}):`];
+    for (const entry of pfEntries) {
+      lines.push(formatIndexEntryLine(entry));
+    }
+    blocks.push(lines.join('\n'));
+  }
+
+  // Footer: explain how to read full bodies
+  const footerLines = [];
+  if (adrEntries.length > 0) {
+    footerLines.push(`ADR-NNN entries live in ${decisionsFilePath}`);
+  }
+  if (pfEntries.length > 0) {
+    footerLines.push(`PF-NNN  entries live in ${pitfallsFilePath}`);
+  }
+  footerLines.push(
+    'Read the relevant file and locate the matching `## ADR-NNN:` or `## PF-NNN:` heading for the full body.'
+  );
+  blocks.push(footerLines.join('\n'));
+
+  return blocks.join('\n\n');
+}
+
+module.exports = {
+  initDecisionsContent,
+  formatDecisionBody,
+  formatPitfallBody,
+  buildTldrLine,
+  toLedgerRow,
+  buildIndexContent,
+};

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

@@ -0,0 +1,106 @@
+// src/assets/scripts/hooks/lib/mkdir-lock.cjs
+//
+// Shared mkdir-based locking helpers used by json-helper.cjs, render-decisions.cjs,
+// and any other CJS hook that needs exclusive access to a shared resource.
+//
+// DESIGN: mkdir is atomic on POSIX — the kernel guarantees that only one caller
+// succeeds on a given path. On EEXIST we check staleness (mtime > staleMs) and
+// break the lock if it is stale, then retry with a 50 ms idle sleep between attempts.
+// Uses Atomics.wait when available (true CPU-idle blocking) or execSync('sleep 0.05')
+// as the idle fallback in restricted worker environments where SharedArrayBuffer is
+// unavailable. The fallback is allocated/looked-up once at module load to avoid
+// per-iteration overhead.
+
+'use strict';
+
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+// D001: Hoist SharedArrayBuffer/Int32Array allocation to module scope so the
+// Atomics.wait path never allocates per retry iteration. In environments where
+// SharedArrayBuffer is unavailable (restricted worker contexts) we fall back to
+// execSync('sleep 0.05') which is truly idle — no busy-wait.
+/** @type {Int32Array | null} */
+const _atomicsBuf = (() => {
+  try { return new Int32Array(new SharedArrayBuffer(4)); } catch { return null; }
+})();
+
+/**
+ * Sleep for ~50 ms in a truly-idle, CPU-friendly way.
+ * Prefers Atomics.wait (zero-overhead blocking) when SharedArrayBuffer is available.
+ * Falls back to execSync('sleep 0.05') in restricted contexts (e.g. background hook workers).
+ * Never busy-waits.
+ *
+ * @returns {void}
+ */
+function _idleSleep50() {
+  if (_atomicsBuf !== null) {
+    Atomics.wait(_atomicsBuf, 0, 0, 50);
+  } else {
+    execSync('sleep 0.05');
+  }
+}
+
+/**
+ * Acquire a mkdir-based lock. Returns true on success, false on timeout.
+ *
+ * Stale-break window (applies ADR-017): a lock directory older than `staleMs`
+ * (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
+ * 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.
+ *
+ * @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
+ * @returns {boolean}
+ */
+function acquireMkdirLock(lockDir, timeoutMs = 30000, staleMs = 60000) {
+  const start = Date.now();
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir, { recursive: false });
+      return true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const stat = fs.statSync(lockDir);
+        const age = Date.now() - stat.mtimeMs;
+        if (age > staleMs) {
+          try { fs.rmdirSync(lockDir); } catch { /* already gone */ }
+          continue;
+        }
+      } catch { /* lock gone between check and stat */ }
+      if (Date.now() - start >= timeoutMs) return false;
+      _idleSleep50();
+    }
+  }
+}
+
+/**
+ * Release a mkdir-based lock. No-op if already released.
+ *
+ * @param {string} lockDir
+ */
+function releaseLock(lockDir) {
+  try { fs.rmdirSync(lockDir); } catch { /* already released */ }
+}
+
+/**
+ * Refresh a held lock by touching its mtime, extending the stale-break deadline
+ * by another staleMs interval. Call periodically from long-running critical sections
+ * to prevent the lock from being stolen by a concurrent acquirer's stale-break check.
+ * No-op if the lock directory no longer exists (handles benign ENOENT races).
+ *
+ * @param {string} lockDir
+ */
+function refreshLock(lockDir) {
+  const now = new Date();
+  try { fs.utimesSync(lockDir, now, now); } catch { /* lock released or raced away — ignore */ }
+}
+
+module.exports = { acquireMkdirLock, releaseLock, refreshLock };