@chrisdudek/yg 5.2.1 → 5.2.3

package/dist/bin.js

@@ -337,21 +337,27 @@ it is enabled on types whose changes carry business intent worth capturing.
 Check the type in \`yg-architecture.yaml\` (or read the node's log state line
 in \`yg context --node\`) to know whether an entry is required.
 
-A fresh log entry is required BEFORE \`yg check --approve\` whenever BOTH hold:
-the node's type has \`log_required: true\` AND the node's mapped source changed
-since its last positive closure (the moment all the node's enforced pairs last
-went green), or this is the node's first verification and it owns source files.
-The entry must be newer than the one recorded at that closure \u2014
-one fresh entry per closure cycle. This requirement is INDEPENDENT of aspect
-status. A cascade-only re-verification (an aspect edited, the node's source
-untouched) needs no new entry.
+A fresh log entry is required whenever BOTH hold: the node's type has
+\`log_required: true\` AND the node's mapped source changed since its last
+positive closure (the moment all the node's enforced pairs last went green), or
+this is the node's first verification and it owns source files. The entry must be
+newer than the one recorded at that closure \u2014 one fresh entry per closure cycle.
+This requirement is a property of the node TYPE plus a source change: it is
+INDEPENDENT of aspect status AND of whether the node has any aspects or pairs at
+all. A node that owns source but has no effective (non-draft) aspects still needs
+an entry when its source changes. A cascade-only re-verification (an aspect
+edited, the node's source untouched) needs no new entry.
 
   1. Edit source files
   2. \`yg log add --node <path> --reason "<justification>"\`
   3. \`yg check --approve\`
 
-If you forget step 2: the gate raises a clear error and that node's pairs are
-skipped (other nodes proceed); add the entry and re-run.
+The requirement is enforced READ-ONLY: a missing entry is a blocking \`yg check\`
+error in its own right, not only a \`--approve\`-time gate \u2014 so plain \`yg check\`
+(and a CI run on it) catches an unlogged source change even on a node that
+produces no pairs. If you forget step 2: \`yg check\` flags that node; at
+\`--approve\` a node that has pairs has them skipped (other nodes proceed) and the
+run stays red until the entry exists. Add the entry and re-run.
 
 If a pair is refused, iterate on the code WITHOUT adding new log entries. One
 log entry covers all source edits until the node reaches positive closure \u2014
@@ -3294,7 +3300,7 @@ ${msg.next}`;
 }
 
 // src/io/lock-store.ts
-import { readFileSync } from "fs";
+import { readFileSync, unlinkSync } from "fs";
 import path11 from "path";
 
 // src/model/lock.ts
@@ -3589,11 +3595,24 @@ async function writeFileIfChanged(filePath, content20) {
   }
   await atomicWriteFile(filePath, content20);
 }
+function removeFileIfExists(filePath) {
+  try {
+    unlinkSync(filePath);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+}
+async function writeOrRemoveSplitFile(filePath, version, verdicts, nodes) {
+  if (Object.keys(verdicts).length === 0 && Object.keys(nodes).length === 0) {
+    removeFileIfExists(filePath);
+    return;
+  }
+  await writeFileIfChanged(filePath, serializeLock({ version, verdicts, nodes }));
+}
 async function writeLock(yggRoot, lock, opts = {}) {
   const scope = opts.scope ?? "all";
   if (scope === "logs") {
-    const content20 = serializeLock({ version: lock.version, verdicts: {}, nodes: lock.nodes });
-    await writeFileIfChanged(logsLockPath(yggRoot), content20);
+    await writeOrRemoveSplitFile(logsLockPath(yggRoot), lock.version, {}, lock.nodes);
     return;
   }
   const detIds = opts.deterministicAspectIds;
@@ -3602,13 +3621,12 @@ async function writeLock(yggRoot, lock, opts = {}) {
   }
   const { det, nondet } = partitionVerdicts(lock.verdicts, detIds);
   if (scope === "deterministic") {
-    const content20 = serializeLock({ version: lock.version, verdicts: det, nodes: {} });
-    await writeFileIfChanged(detLockPath(yggRoot), content20);
+    await writeOrRemoveSplitFile(detLockPath(yggRoot), lock.version, det, {});
     return;
   }
-  await writeFileIfChanged(nondetLockPath(yggRoot), serializeLock({ version: lock.version, verdicts: nondet, nodes: {} }));
-  await writeFileIfChanged(logsLockPath(yggRoot), serializeLock({ version: lock.version, verdicts: {}, nodes: lock.nodes }));
-  await writeFileIfChanged(detLockPath(yggRoot), serializeLock({ version: lock.version, verdicts: det, nodes: {} }));
+  await writeOrRemoveSplitFile(nondetLockPath(yggRoot), lock.version, nondet, {});
+  await writeOrRemoveSplitFile(logsLockPath(yggRoot), lock.version, {}, lock.nodes);
+  await writeOrRemoveSplitFile(detLockPath(yggRoot), lock.version, det, {});
 }
 
 // src/cli/preamble.ts
@@ -7868,12 +7886,33 @@ function parseLog(content20) {
 }
 
 // src/core/log/log-gate.ts
+async function logGateBlocksNode(graph, projectRoot, node, lock) {
+  const archType = graph.architecture.node_types[node.meta.type];
+  const logRequired = archType?.log_required ?? false;
+  if (!logRequired) return false;
+  let currentFingerprint;
+  try {
+    currentFingerprint = await computeSourceFingerprint(graph, node.path);
+  } catch (e) {
+    if (e instanceof FileUnreadableError) {
+      debugWrite(`[log-gate] logGate fingerprint for ${toPosixPath(node.path)}: ${e.message}`);
+      return true;
+    }
+    throw e;
+  }
+  if (currentFingerprint === void 0) return false;
+  const storedFingerprint = lock.nodes[node.path]?.source;
+  const drifted = currentFingerprint !== storedFingerprint;
+  if (!drifted) return false;
+  const logContent = await readLogContent(projectRoot, node.path);
+  return !hasFreshLogEntry(logContent, lock.nodes[node.path]?.log);
+}
 async function readLogContent(projectRoot, nodePath) {
   const logAbs = path22.join(projectRoot, ".yggdrasil", "model", nodePath, "log.md");
   try {
     return await readTextFile(logAbs);
   } catch (e) {
-    debugWrite(`[log-gate] readLogContent: could not read ${logAbs}: ${e instanceof Error ? e.message : String(e)}`);
+    debugWrite(`[log-gate] readLogContent: could not read ${toPosixPath(logAbs)}: ${e instanceof Error ? e.message : String(e)}`);
     return "";
   }
 }
@@ -14336,6 +14375,23 @@ ${violations.map((v) => `  line ${v.line}: ${v.reason} \u2014 ${v.detail}`).join
     }
   }
 }
+async function classifyLogRequirement(graph, projectRoot, lock, unreadableNodes, issues) {
+  for (const [nodePath, node] of graph.nodes) {
+    if (unreadableNodes.has(nodePath)) continue;
+    if (!await logGateBlocksNode(graph, projectRoot, node, lock)) continue;
+    issues.push({
+      severity: "error",
+      code: "log-entry-missing",
+      rule: "log-entry-missing",
+      messageData: {
+        what: `No fresh log entry for node '${toPosixPath(nodePath)}' \u2014 its source changed but no justification entry exists.`,
+        why: `Node type '${node.meta.type}' has log_required: true \u2014 every source change needs a log entry capturing WHY. The requirement is a property of the node type plus a source change, independent of aspects; yg check stays red until a fresh entry exists.`,
+        next: `yg log add --node ${toPosixPath(nodePath)} --reason '<justification>', then re-run: yg check --approve`
+      },
+      nodePath
+    });
+  }
+}
 function scanUncoveredFiles(graph, gitTrackedFiles) {
   const allMappings = [];
   for (const node of graph.nodes.values()) {
@@ -14443,6 +14499,8 @@ async function runCheck(graph, gitTrackedFiles) {
       });
     }
     await classifyLogStateFromLock(graph, projectRoot, lock, lockIssues);
+    const unreadableNodes = new Set(verification.unreadable.map((u) => u.nodePath));
+    await classifyLogRequirement(graph, projectRoot, lock, unreadableNodes, lockIssues);
   } catch (err) {
     if (err instanceof LockInvalidError) {
       lockIssues.push({
@@ -14521,6 +14579,8 @@ function computeSuggestedNext(issues) {
   }
   const lockInvalid = errors.find((i) => i.code === "lock-invalid");
   if (lockInvalid) return lockInvalid.messageData.next;
+  const logEntryMissing = errors.find((i) => i.code === "log-entry-missing");
+  if (logEntryMissing) return logEntryMissing.messageData.next;
   const unverified = errors.find((i) => i.code === "unverified");
   if (unverified) return unverified.messageData.next;
   const enforcedRefusal = errors.find((i) => i.code === "aspect-violation-enforced");
@@ -15343,27 +15403,6 @@ async function runPairPool(items, concurrency, fn) {
 }
 
 // src/core/fill-log-gate.ts
-async function logGateBlocksNode(graph, projectRoot, node, lock) {
-  const archType = graph.architecture.node_types[node.meta.type];
-  const logRequired = archType?.log_required ?? false;
-  if (!logRequired) return false;
-  let currentFingerprint;
-  try {
-    currentFingerprint = await computeSourceFingerprint(graph, node.path);
-  } catch (e) {
-    if (e instanceof FileUnreadableError) {
-      debugWrite(`[fill] logGate fingerprint for ${toPosixPath(node.path)}: ${e.message}`);
-      return true;
-    }
-    throw e;
-  }
-  if (currentFingerprint === void 0) return false;
-  const storedFingerprint = lock.nodes[node.path]?.source;
-  const drifted = currentFingerprint !== storedFingerprint;
-  if (!drifted) return false;
-  const logContent = await readLogContent(projectRoot, node.path);
-  return !hasFreshLogEntry(logContent, lock.nodes[node.path]?.log);
-}
 async function logGateBlocks(graph, projectRoot, node, lock, emitIssue) {
   const blocked = await logGateBlocksNode(graph, projectRoot, node, lock);
   if (!blocked) return false;
@@ -15386,6 +15425,12 @@ async function applyPositiveClosure(graph, projectRoot, lock, blockedNodes, pers
   }
   let mutated = false;
   for (const [nodePath, node] of graph.nodes) {
+    const archType = graph.architecture.node_types[node.meta.type];
+    const logRequired = archType?.log_required ?? false;
+    if (!logRequired) {
+      if (await reconcileNonLogRequiredEntry(projectRoot, nodePath, lock)) mutated = true;
+      continue;
+    }
     let currentFingerprint;
     try {
       currentFingerprint = await computeSourceFingerprint(graph, nodePath);
@@ -15397,8 +15442,7 @@ async function applyPositiveClosure(graph, projectRoot, lock, blockedNodes, pers
       throw e;
     }
     if (currentFingerprint === void 0) {
-      await closeLogBaselineOnly(projectRoot, nodePath, lock);
-      mutated = true;
+      if (await closeLogBaselineOnly(projectRoot, nodePath, lock)) mutated = true;
       continue;
     }
     const stored = lock.nodes[nodePath]?.source;
@@ -15417,12 +15461,32 @@ async function applyPositiveClosure(graph, projectRoot, lock, blockedNodes, pers
   }
   if (mutated) await persistLock();
 }
+function logBaselineEquals(a, b) {
+  if (!a || !b) return !a && !b;
+  return a.last_entry_datetime === b.last_entry_datetime && a.prefix_hash === b.prefix_hash;
+}
+async function reconcileNonLogRequiredEntry(projectRoot, nodePath, lock) {
+  const logBaseline = await computeLogBaselineForNode(projectRoot, nodePath);
+  const existing = lock.nodes[nodePath];
+  const desiredLog = logBaseline ?? existing?.log;
+  if (!desiredLog) {
+    if (existing === void 0) return false;
+    delete lock.nodes[nodePath];
+    return true;
+  }
+  if (existing !== void 0 && existing.source === void 0 && logBaselineEquals(existing.log, desiredLog)) {
+    return false;
+  }
+  lock.nodes[nodePath] = { log: desiredLog };
+  return true;
+}
 async function closeLogBaselineOnly(projectRoot, nodePath, lock) {
   const logBaseline = await computeLogBaselineForNode(projectRoot, nodePath);
-  if (!logBaseline) return;
-  const entry = lock.nodes[nodePath] ?? {};
-  entry.log = logBaseline;
-  lock.nodes[nodePath] = entry;
+  if (!logBaseline) return false;
+  const existing = lock.nodes[nodePath];
+  if (logBaselineEquals(existing?.log, logBaseline)) return false;
+  lock.nodes[nodePath] = { ...existing ?? {}, log: logBaseline };
+  return true;
 }
 
 // src/core/fill-gc.ts
@@ -15885,6 +15949,7 @@ function formatOutput(result, view = { kind: "full" }) {
 }
 var ERROR_CODE_PRIORITY = [
   "lock-invalid",
+  "log-entry-missing",
   "unverified",
   "aspect-violation-enforced",
   "prompt-too-large",
@@ -15999,7 +16064,7 @@ function renderErrorSection(errors) {
   const architecture = errors.filter((i) => ARCHITECTURE_CODES.has(i.code));
   const completeness = errors.filter((i) => COMPLETENESS_CODES.has(i.code));
   const strict = errors.filter((i) => STRICT_CODES.has(i.code));
-  const logErrors = errors.filter((i) => i.code === "log-conflict" || i.code === "log-integrity" || i.code === "log-format");
+  const logErrors = errors.filter((i) => i.code === "log-conflict" || i.code === "log-integrity" || i.code === "log-format" || i.code === "log-entry-missing");
   const aspectErrors = errors.filter((i) => i.code === "aspect-violation-enforced");
   const remaining = errors.filter(
     (i) => !verification.includes(i) && !unmapped.includes(i) && !structural.includes(i) && !architecture.includes(i) && !completeness.includes(i) && !strict.includes(i) && !logErrors.includes(i) && !aspectErrors.includes(i)
@@ -17762,9 +17827,12 @@ prefix (e.g. \`src/handlers\`) covers that file or all files beneath it.
 ## log_required \u2014 when to enable the log gate
 
 Each node type may set \`log_required\` (default \`false\`). When \`true\`, a node of
-that type demands a fresh log entry before \`yg check --approve\` whenever its
-mapped source changed since the node's last positive closure (the log gate, see
-\`yg knowledge read log-management\`).
+that type demands a fresh log entry whenever its mapped source changed since the
+node's last positive closure. The requirement is a property of the node TYPE plus
+a source change \u2014 independent of the node's aspects or pairs \u2014 and is enforced
+read-only: plain \`yg check\` flags a missing entry as a blocking error, so it
+bites even on a node that produces no pairs (the log gate, see \`yg knowledge read
+log-management\`).
 
 Enable it on types whose changes carry business intent worth capturing \u2014
 domain logic, command handlers, persistence adapters, anything where the WHY
@@ -19440,8 +19508,8 @@ pairs on that node \u2014 a legitimate vacuous pass, no verdict, no entry.
     }
   },
   "nodes": {
-    "billing/cancel": {
-      "source": "<sha256>",                  // source fingerprint \u2014 the log gate's basis
+    "billing/cancel": {                       // present ONLY when log_required and/or a log.md exists
+      "source": "<sha256>",                  // source fingerprint \u2014 log gate basis; ONLY for log_required nodes
       "log": { "last_entry_datetime": "<ISO>", "prefix_hash": "<sha256>" }
     }
   }
@@ -19463,6 +19531,16 @@ pairs on that node \u2014 a legitimate vacuous pass, no verdict, no entry.
   entirely.
 - \`nodes.<path>\` carries the source fingerprint (the log gate's contract,
   \`yg knowledge read log-management\`) and the append-only log integrity baseline.
+  The source fingerprint is the log gate's drift basis, so it is recorded ONLY for
+  \`log_required\` nodes \u2014 a non-log_required node gets a \`nodes\` entry only when it
+  owns a \`log.md\` (then holding just the \`log\` baseline, no \`source\`).
+- Empty section \u21D2 no file. Each of the three split files is written ONLY when its
+  section is non-empty; when empty it is not written at all (an existing empty husk
+  is removed). So a repo with no LLM aspects has no \`yg-lock.nondeterministic.json\`,
+  one with no \`log_required\` node and no \`log.md\` has no \`yg-lock.logs.json\`, and
+  one with no deterministic aspects has no \`.yg-lock.deterministic.json\`. readLock
+  treats an absent file as empty state, so this is transparent to every reader \u2014 a
+  repo only carries the lock files it actually needs.
 - The built-in relation-conformance check is NOT stored in the lock \u2014 it is
   recomputed live on every \`yg check\`. The lock holds only aspect \`verdicts\`
   and per-node \`nodes\` facts; there is no relation section. See "Relation
@@ -20074,9 +20152,12 @@ real \`--approve\` bills at most that many calls. The preview always exits 0, ev
 when enforced pairs are unverified; it never blocks. Only a broken
 configuration (the step-1 structural gate) aborts the preview \u2014 it surfaces the
 same blocker a real \`--approve\` would hit. A cost estimate never demands a fresh
-log entry, so the preview also bypasses the per-node log gate \u2014 it previews even
-on \`log_required\` nodes whose source changed since their last closure, where the
-real \`--approve\` would require the log entry first. \`--dry-run\` requires
+log entry, so the preview never HARD-STOPS on the per-node log gate \u2014 it previews
+the budget even on \`log_required\` nodes whose source changed since their last
+closure, where a real \`--approve\` would require the entry first. (The preview's
+trailing read-only check report still SURFACES that requirement as a
+\`log-entry-missing\` error, exactly as plain \`yg check\` does \u2014 it just exits 0
+and writes nothing.) \`--dry-run\` requires
 \`--approve\`; on its own it is a usage error (plain \`yg check\` is already a free,
 no-write read).
 
@@ -20319,7 +20400,7 @@ working-with-architecture\` is the home for that guidance). To know whether a no
 needs an entry, check its type in \`yg-architecture.yaml\`, or read the node's log
 state line in \`yg context --node\`.
 
-A fresh log entry is required BEFORE \`yg check --approve\` whenever BOTH hold:
+A fresh log entry is required whenever BOTH hold:
 
 - the node's type has \`log_required: true\`, AND
 - the node's mapped source changed since its last positive closure (or this is the
@@ -20327,10 +20408,21 @@ A fresh log entry is required BEFORE \`yg check --approve\` whenever BOTH hold:
 
 "Fresh" means newer than the entry recorded at that closure \u2014 one fresh entry per
 closure cycle. The requirement depends ONLY on the type flag and the source
-change. It is INDEPENDENT of aspect status. A node with no source change
+change. It is INDEPENDENT of aspect status AND of whether the node has any aspects
+or pairs at all \u2014 a node that owns source but has no effective (non-draft) aspects
+still needs an entry when its source changes. A node with no source change
 (cascade-only re-verification \u2014 an aspect was edited, the source untouched) needs
 no new entry.
 
+The requirement is enforced READ-ONLY. A missing entry is a blocking
+\`log-entry-missing\` error surfaced by plain \`yg check\` itself \u2014 computed live
+from each node's source fingerprint, like the relation-conformance check, at zero
+LLM cost \u2014 not merely a \`--approve\`-time gate. So a CI run on plain \`yg check\`
+catches an unlogged source change on a \`log_required\` node even when that node
+produces no pairs to fill. \`--approve\` only WRITES (records the closure baseline
+once the entry exists); it never gets a chance to bypass the requirement, because
+its own final re-check surfaces the same error.
+
 ## Positive closure \u2014 the cycle
 
 Positive closure is the moment a \`yg check --approve\` run ends with every ENFORCED
@@ -20340,7 +20432,9 @@ records the node's source fingerprint and the log freshness baseline.
 Corollaries:
 - Advisory refusals do NOT prevent closure.
 - A node with only advisory/deterministic aspects, or no pairs at all, closes
-  vacuously.
+  vacuously \u2014 BUT only once the log requirement is satisfied: a \`log_required\`
+  node whose source changed with no fresh entry does not close, and \`yg check\`
+  flags it red regardless of its (lack of) pairs.
 - A red enforced pair of either kind keeps the cycle OPEN \u2014 the same log entry
   stays valid through every retry until the node is actually green. Intent does
   not change between retries; only execution does.
@@ -20351,9 +20445,13 @@ The gate's "mapped source changed" test is computed from a per-node **source
 fingerprint** \u2014 one sha256 fold over the sorted \`[path, sha256(bytes)]\` list of
 ALL the node's mapped files (the full mapping, not the scope-filtered subject
 sets; binaries included by bytes). It lives in \`yg-lock.logs.json\` under
-\`nodes.<path>.source\`, written at positive closure. The append-only log integrity
-baseline (boundary datetime + prefix hash) lives beside it under
-\`nodes.<path>.log\`. There is no separate per-node state file.
+\`nodes.<path>.source\`, written at positive closure \u2014 but ONLY for \`log_required\`
+nodes, since the fingerprint is the gate's drift basis and the gate never runs
+elsewhere. A non-log_required node records no \`source\`; it gets a \`nodes\` entry
+only when it owns a \`log.md\`, holding just the append-only \`log\` baseline
+(boundary datetime + prefix hash). When the section is empty (no log_required
+node, no \`log.md\`), \`yg-lock.logs.json\` is not written at all \u2014 an empty committed
+husk is removed. There is no separate per-node state file.
 
 The basic workflow:
 
@@ -20361,10 +20459,12 @@ The basic workflow:
   2. \`yg log add --node <path> --reason "<justification>"\`
   3. \`yg check --approve\`
 
-If you forget step 2, the gate raises \`log-entry-missing\` and that node's pairs
-are skipped (other nodes proceed); add the entry and re-run. If a pair is refused,
-iterate on the code WITHOUT adding new log entries \u2014 one entry covers all edits
-until the node reaches closure.
+If you forget step 2, plain \`yg check\` raises a blocking \`log-entry-missing\`
+error for that node (caught read-only, regardless of whether the node has pairs);
+at \`--approve\` a node that has pairs additionally has them skipped while other
+nodes proceed, and the run stays red until the entry exists. Add the entry and
+re-run. If a pair is refused, iterate on the code WITHOUT adding new log entries \u2014
+one entry covers all edits until the node reaches closure.
 
 ## Self-contained entry \u2014 worked example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrisdudek/yg",
-  "version": "5.2.1",
+  "version": "5.2.3",
   "description": "Architecture rules your AI coding agent can't ignore. It gets the rules for a file before it edits, and every change is checked — by a free local script or an LLM reviewer — before it moves on. Works with Claude Code, Cursor, Copilot, Codex, Cline.",
   "type": "module",
   "bin": {