instar 1.3.970 → 1.3.971

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.970",
+  "version": "1.3.971",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/cartographer-freshness.mjs

@@ -123,7 +123,7 @@ function compute() {
       stateAuthored: false,
       nodeCount: 0, authorableCount: 0, freshCount: 0, staleCount: 0,
       neverAuthoredCount: 0, neverAuthoredWithinGrace: 0, neverAuthoredPastGrace: 0,
-      authorFailedCount: 0, freshRatio: 1,
+      authorFailedCount: 0, freshRatio: null,
     };
   }
 
@@ -163,7 +163,10 @@ function compute() {
     authorFailedCount: authorFailed,
     // Denominator EXCLUDES never-authored-within-grace (grace period before a new
     // node counts as debt): fresh + stale + never-authored-past-grace.
-    freshRatio: (fresh + stale + neverPast) === 0 ? 1 : Number((fresh / (fresh + stale + neverPast)).toFixed(4)),
+    // null (NOT 1) when there is nothing to divide by: an empty index has not
+    // earned a perfect score. Reporting 1 here made this ratchet structurally
+    // unable to fail on an empty map — the exact case it exists to catch.
+    freshRatio: (fresh + stale + neverPast) === 0 ? null : Number((fresh / (fresh + stale + neverPast)).toFixed(4)),
   };
 }
 
@@ -188,7 +191,19 @@ function main() {
 
   if (CHECK) {
     const failures = [];
-    if (report.freshRatio < FLOORS.freshRatio) {
+    if (report.freshRatio === null && report.stateAuthored && report.nodeCount === 0) {
+      // An index EXISTS and yielded nothing authorable. That is the dangerous
+      // empty: the ratchet was asked to assess and could not, which must never
+      // read as a pass (reporting 1 here is what made this check structurally
+      // unable to fail on an empty map — the exact case it exists to catch).
+      failures.push('fresh ratio UNKNOWN — an authored index exists but contains ZERO nodes, so freshness could NOT be assessed (this is not a pass)');
+    } else if (report.freshRatio === null) {
+      // Either no authored state at all (the documented CI case) or an index whose
+      // nodes are all still within grace — legitimately too early to assess. NOT a
+      // failure, but it is NOT a pass either: say so out loud rather than
+      // letting a vacuous check read as a green one.
+      if (!QUIET) console.error('[cartographer-freshness] NOT ASSESSED — no authored cartographer state; this check gated on nothing.');
+    } else if (report.freshRatio < FLOORS.freshRatio) {
       failures.push(`fresh ratio ${report.freshRatio} < floor ${FLOORS.freshRatio}`);
     }
     if (report.neverAuthoredPastGrace > FLOORS.neverAuthoredPastGraceCeiling) {

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-25T21:42:13.777Z",
-  "instarVersion": "1.3.970",
+  "generatedAt": "2026-07-25T22:32:03.310Z",
+  "instarVersion": "1.3.971",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -418,7 +418,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -426,7 +426,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -434,7 +434,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -442,7 +442,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -450,7 +450,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -458,7 +458,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -466,7 +466,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -474,7 +474,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -482,7 +482,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -490,7 +490,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -498,7 +498,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -506,7 +506,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -514,7 +514,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -522,7 +522,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -530,7 +530,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -538,7 +538,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -546,7 +546,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -554,7 +554,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -562,7 +562,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -570,7 +570,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -578,7 +578,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -586,7 +586,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -594,7 +594,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -602,7 +602,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -610,7 +610,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -618,7 +618,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -626,7 +626,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -634,7 +634,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -642,7 +642,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -650,7 +650,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -658,7 +658,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -666,7 +666,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -674,7 +674,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -682,7 +682,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -690,7 +690,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -698,7 +698,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -706,7 +706,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -714,7 +714,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -722,7 +722,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -730,7 +730,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -738,7 +738,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -746,7 +746,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -754,7 +754,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -770,7 +770,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "4fc659422651c32e9c1666c14a5f96fc071915314cf4da792b542127729242b5",
+      "contentHash": "c424f56d50da1f0b007be59271759c6276ac6e622cadd27d003e8fe9b6738071",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.3.971.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Two of our own checks were announcing results they had not earned. Both are now honest.
+
+**The commit gate was not blocking anything.** `.husky/pre-commit` ran its checks as a plain
+sequence with no `set -e`, so the hook's exit status was whatever the *last* command returned.
+`scripts/instar-dev-precommit.js` would correctly refuse a commit — printing its full
+`commit BLOCKED` banner and exiting 1 — and then three further checks ran after it, each exiting
+0, so git saw 0 and accepted the commit anyway. Every blocking check in that hook except the final
+one was effectively advisory. Fixed with `set -e`, with the reasoning recorded inline so it is not
+re-introduced.
+
+**A freshness score of 100% for having measured nothing.** `freshRatio` returned `1` when there
+was no denominator — an explicit choice in code (`ratioDenom === 0 ? 1`), not an oversight. Since
+the CI ratchet gates on `freshRatio < FLOOR`, a perfect 1 passed every possible floor, leaving the
+guard structurally unable to fail on an empty map — precisely the case it exists to catch. All
+five producers now return `null` when there is nothing to divide by, and the ratchet distinguishes
+*no authored state at all* (the legitimate case — still passes, but now prints
+`NOT ASSESSED — this check gated on nothing` instead of reporting success) from *an authored index
+containing zero nodes* (a hard failure). A freshly-scaffolded index whose nodes are still within
+their grace period remains a pass.
+
+## What to Tell Your User
+
+Nothing changes in how you work with your agent, and no action is needed.
+
+One small visible difference if you look at the documentation-map health figure: where it
+previously showed 100% freshness for a map with nothing in it, it now shows no figure at all,
+because "we have not measured anything" and "everything is fresh" are different answers and should
+not look identical.
+
+## Summary of New Capabilities
+
+No new capabilities. Both changes make existing machinery do what it already claimed to do —
+one restores a verdict that was being computed correctly and then discarded, the other stops a
+health figure from manufacturing a passing grade out of an absence of evidence.
+
+## Evidence
+
+- The defect was proved rather than inferred: a commit was deliberately landed through a printed
+  `commit BLOCKED` banner (`b2efded2f`, since reverted). After the fix, the identical commit is
+  refused with `husky - pre-commit script failed (code 1)`.
+- Every command in the pre-commit sequence was measured independently on a clean tree with real
+  dependencies: all exit 0, so making the hook honest does not turn a green repo red.
+- Freshness: pointing the ratchet at an index that exists and is empty now fails with
+  `could NOT be assessed (this is not a pass)`; with no authored state it still exits 0 but says
+  so out loud.
+- Three new regression tests cover both sides of the boundary, including one asserting that an
+  empty authored index cannot satisfy even a floor of 0. 103 cartographer tests pass; lint clean.
+- One pre-existing E2E assertion required `freshRatio` to be a *number* on an empty tree — it was
+  protecting the old behaviour and would have failed anyone fixing this honestly. It now asserts
+  the honest contract, with the reason recorded inline.

package/upgrades/side-effects/honest-denominators.md

@@ -0,0 +1,135 @@
+# Side-Effects Review — honest denominators: a gate that discards its verdict, and a ratio that reports 1 over nothing
+
+## Summary of the change
+
+Two related honesty defects, both found by the convergence-towards-coherence audit (2026-07-25).
+
+**A. `.husky/pre-commit` discarded its own blocking verdict.** The hook was a plain command
+sequence with no `set -e`, so its exit status was the LAST command's.
+`scripts/instar-dev-precommit.js` exits 1 and prints a full "commit BLOCKED" banner; three checks
+then run after it, each exiting 0, so git saw 0 and accepted the commit. Verified by landing a
+commit through a printed block (`b2efded2f`, reverted). Every blocking check in the hook except
+the final one was advisory. Fix: `set -e`, with the reasoning recorded inline.
+
+**B. `freshRatio` reported a perfect `1` when there was nothing to divide by.** Explicit in code
+(`ratioDenom === 0 ? 1`), not an oversight. The CI ratchet compares `freshRatio < FLOOR`, so 1
+passed every possible floor — the guard was structurally unable to fail on an empty map, the exact
+case it exists to catch. Fix: all five producers return `null` with no denominator; the ratchet
+distinguishes *no authored state* (legitimate CI case → still exit 0, but prints
+`NOT ASSESSED — this check gated on nothing`) from *an authored index with zero nodes*
+(→ hard failure).
+
+## Decision-point inventory
+
+- `.husky/pre-commit` — a commit-time authority. Change makes its existing verdict effective; it
+  adds no new verdict of its own.
+- `scripts/cartographer-freshness.mjs --check` — a CI-time authority. Change adds one failure
+  condition (authored index with zero nodes) and one explicit non-assessment notice.
+- The five `freshRatio` producers are pure reporters; no decision logic changed.
+
+## 1. Over-block
+
+**A.** `set -e` means the FIRST failing check aborts, so later checks do not run and a developer
+sees one problem at a time rather than all of them. Accepted: that is standard hook behaviour and
+strictly better than the previous state (no check could block at all). Every command in the
+sequence is intended to block; the only conditional (`if node -e … fi`) is a shell condition,
+which `set -e` deliberately does not trip on.
+
+**B.** The narrow risk was failing a legitimately-not-yet-assessable index. Caught during build:
+my first version failed a freshly-scaffolded tree whose nodes are all within grace, breaking two
+pre-existing tests. Narrowed to `nodeCount === 0`. A scaffold within grace is a pass, and the
+existing `neverAuthoredPastGrace` ceiling still guards the backlog case.
+
+## 2. Under-block
+
+**A.** `--no-verify` still bypasses everything — unchanged and out of scope; the skill already
+names bypass as an anti-pattern. Server-side CI remains the backstop.
+
+**B.** A *populated but stale* map is still governed only by the configured floor, which ships at
+`0` by default and therefore still gates weakly. This change does not raise that floor — doing so
+is a separate judgement about desired strictness, and bundling it would hide which change caused
+which effect. Named here rather than silently left.
+
+## 3. Level-of-abstraction fit
+
+Both fixes are at the layer that already owns the decision. **A** repairs how an existing verdict
+is propagated — it does not move authority. **B** repairs what a reporter reports and how its
+existing consumer reads "no evidence". Neither adds a parallel checker beside a smarter one.
+
+## 4. Signal vs authority compliance
+
+Compliant, and the change moves *toward* the principle.
+
+- **A** adds no new authority. The authority (`instar-dev-precommit.js`) already existed and
+  already computed the right answer; the defect was that its signal was discarded. Making an
+  existing verdict effective is the opposite of granting brittle logic new blocking power.
+- **B** the producers remain pure signals (`number | null`). The one authority (the CI ratchet)
+  gains a failure condition that is *deterministic and evidence-based* — it fires only on the
+  objective state "an index exists and contains zero nodes". Crucially it fails toward "cannot
+  assess", never toward a fabricated pass, which is the direction the principle asks for.
+
+## 4b. Judgment-point check
+
+No LLM judgement involved. Both are deterministic checks over objective state (exit codes; node
+counts). No string-matching heuristic gains authority.
+
+## 5. Interactions
+
+- **A** interacts with every check in the hook: `npm run lint`,
+  `lint-migration-consumer-completeness`, `instar-dev-precommit`, `check-rule3-coverage`,
+  `protect-migration-guarantee`, `check-e2e-pairing`. All six become genuinely blocking. Verified
+  each currently exits 0 on a clean tree with real dependencies installed, so this does not turn a
+  currently-green repo red. **This was checked only after a false alarm**: I first measured a lint
+  failure and reported that the fix would block every developer — that failure was an artifact of
+  my own worktree pointing at an 85-commit-stale `node_modules` that predated the `undici`
+  dependency. With a real `npm ci`, lint exits 0. The false alarm is recorded because the
+  generalisation-from-local-artifact is the more instructive error.
+- **B** does not shadow the `neverAuthoredPastGrace` or `authorFailed` ceilings; they are
+  evaluated independently and unchanged.
+
+## 6. External surfaces
+
+`GET /cartographer/health` now returns `freshness.freshRatio: null` instead of `1` in the
+no-data case. Any external consumer doing arithmetic on it must handle null. Type-checked across
+the tree: zero errors, because the only pipeline consumer is the `.mjs` ratchet, which is updated
+here. The dashboard renders the freshness block; `null` displays as absent rather than as a
+fabricated 100%, which is the intended user-visible effect.
+
+## 6b. Operator-surface quality
+
+The ratchet's new no-assessment line is plain English and states the consequence:
+`NOT ASSESSED — no authored cartographer state; this check gated on nothing.` The failure line
+says what could not be done and explicitly that it is not a pass, rather than emitting a bare
+code. No file paths or config syntax are surfaced to a user; both lines are developer/CI-facing.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local by design, both.** `.husky/pre-commit` is a per-checkout git hook — there is no
+cross-machine surface and no replication path is meaningful. The cartographer index is per-machine
+state and its freshness is a property of that machine's checkout; `GET /cartographer/health` is
+already a machine-local read. No durable state strands on topic transfer, no generated URL crosses
+a machine boundary, and no user-facing notice is emitted that would need one-voice gating.
+
+## 8. Rollback cost
+
+Cheap and total, for both. **A**: delete one line (`set -e`) — restores the previous behaviour
+exactly. **B**: revert the commit; the producers return to `1` and the ratchet to its prior
+comparison. No data migration, no agent state repair, no released artifact depends on the shape.
+The `null` value is additive to a type, not a schema change with stored records behind it.
+
+## Conclusion
+
+Both changes make an existing mechanism do what it already claimed to do. Neither adds authority;
+one restores authority that was being silently discarded, the other stops a reporter from
+manufacturing a passing grade out of an absence of evidence.
+
+The honest note for reviewers: I got the second one wrong twice during the build (over-broad
+failure condition caught by pre-existing tests; a false blast-radius claim caught by checking my
+own environment), and one existing E2E assertion had to be corrected because it was protecting
+the old behaviour. That history is in the commit message and the test comments so it cannot be
+quietly reverted.
+
+**Second-pass review: not required.** Per the skill's Phase 5 list, this touches no runtime
+agent-behaviour gate — no outbound/inbound message block/allow, no session lifecycle, no
+compaction/respawn, no coherence gate or trust level. It touches a git hook and a CI script, both
+build-time. The PR is the review surface, per Tier 1.