@dzhechkov/harness-core 0.3.142 → 0.3.144

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "68be78c9e65964e48cf4a9334c069f079b572f37367bc84404400eb6a5bc013a"
+          "content": "1b9db50b623f5737dd95a3b949d9ea85293387a010a09f4204e6a476f5127d57"
         }
       ]
     },
@@ -215,7 +215,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0e6b229ff5dfe8026018173f8bbc13398fe2a88411d9cedc0c4c679d6a1c2fc8"
+          "content": "3f3fbdb7a59c0152d0750291092b6453b0ae1ff6f6f910e99cb5facfd93b6e53"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "99520bcd3dc3045df2e678a2be16f925b7f0f858f88ca4cc60526290c8e7c1aa"
+          "content": "0c96dddbd4aebe4bf085b641fcfaaa0ad149b5572471449f984364c94f78c7b3"
         }
       ]
     },
@@ -235,7 +235,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f6c541c38343a7d7ac6e07e5bca60bb0910d83d1fe3c22089b2dae9ba41eadc9"
+          "content": "9208cce6400957bed310d8c0405a15128315fba59b447962e06e48fca11f6fe6"
         }
       ]
     },
@@ -245,7 +245,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d211992f2a33bd28a164b19f3e2a9da798ccf679c29e92748742de14d8f009ff"
+          "content": "1dfc72d3ba2c896a43504425d4fdeb6b34dccb7d7867bc2f9a792981a57a5c48"
         }
       ]
     },
@@ -615,7 +615,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ec191d943989b0c7d96acb31ab31eefc16a539751cd1c94e3af20105a152beff"
+          "content": "34eb7f1754a631ebe5f390dee53f1ea276a85e6cabd25806c384aeef23f64d3c"
         }
       ]
     },
@@ -625,7 +625,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7c78039462fbb3b4990907d8bcc7821b8d46b4962bc6b79397605eb195127f6b"
+          "content": "22cddbd67b5a6204cccc2bf100735c33e138f7400769ad073dc694df4fb0f2b2"
         }
       ]
     },
@@ -635,7 +635,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c0500edbd72a22e8850a231078849147a445956d3e9c5894c06d257a4dad5197"
+          "content": "dc8d3d48e8387391828175bff981016dfa449b19aa1a55e6420adbd688a112fb"
         }
       ]
     },
@@ -645,7 +645,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dfbf44a32606c8ad92fbd21a88ca615f9944802ff3d2d12de8fccbb1036dfad0"
+          "content": "afc564287b7a548b15051e64151c05687b8a45b66df7c964e7168591bb93414c"
         }
       ]
     },
@@ -889,6 +889,46 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "dist/epoch-replay.d.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "7b45f33f2948d102e09204dec03bdff93c70571d79c9466faf014126139cd0b9"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/epoch-replay.d.ts.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "155f1584c236ef7d805522377e20d651c01bd07ad96a6dcc17847d9f6b3885e2"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/epoch-replay.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "fbed667f04a07975915a35ed78d582c05a6669e744d457b3ac38a0cbb35d4539"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/epoch-replay.js.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "f0c5eb87cdc3727e7eb857e5d07f8fd376902c66c48a23af61998677ea48acda"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "dist/feature-adr-claim-gate.d.ts",
@@ -1015,7 +1055,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "de51710fa4c97f71bd835b77740634708ef1fb6791e946c0c1124f3800c93bd6"
+          "content": "7a1df1aa511a5d96669e660b99d29ba633393e1a20dc346e1dedfa9aec221260"
         }
       ]
     },
@@ -1025,7 +1065,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "65bc9e2e658380ecfb061377d88640569f5be259093ff619c99e5d9cc8db8869"
+          "content": "be03334a1746d3261afe69252f119c82f3718e0608957eebf5de311acf9d8a04"
         }
       ]
     },
@@ -1035,7 +1075,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "012b8841fa90e6f6b03059d3ef1ae201ba22c0c2f20cfd828ae636ba2057db7a"
+          "content": "dc20d0ea9ff7e1299b52ed3ce03dbd2f8bb13b1b86ee2799a49837f33ec33883"
         }
       ]
     },
@@ -1045,7 +1085,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "46a8ef893bfba84586883fbcabdf031e151cf59d3cb4947958549a5d451bc5b8"
+          "content": "1696212693b8cd400ff6d2af843e2901ad0e79679ddd09ea9831306aa75e342a"
         }
       ]
     },
@@ -1095,7 +1135,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "13e762f63d29519f51214c202498f25171781daaaa5e872bf93504590da14102"
+          "content": "88213a2320b2b99781919788883ab99da93c4043e7c235f14d7f97db034703e0"
         }
       ]
     },
@@ -1105,7 +1145,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7145736e767324ee5cc10ad8ffe0b58bc80bd8c186e91fd4693c9bfb350ae4a0"
+          "content": "e568286b5e7123dbd73a623268134af1b55555e61e90ea0271a9d4938184b6a0"
         }
       ]
     },
@@ -1115,7 +1155,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "875624dd956dd81671adc24d896798b5b162f7a1af468a58944e29f0f6ad8347"
+          "content": "a779d72721eb025257beee64dd6e29a8e54e1dde1f152a0887d94aa2f9c3f1be"
         }
       ]
     },
@@ -1125,7 +1165,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5a8b40115c9b4d9dd815a4b15d61d4fc5da502a1b8a71104743c3ed9e204ce2c"
+          "content": "7f3cd564e49f49d2fb6a736e98ce837f987994776730ff07f04cb71c7113c22e"
         }
       ]
     },
@@ -2575,7 +2615,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "22f5f6bac0cc06e227e205b14388ae2ca8dd17a1a6a3abfa8458a21d104df772"
+          "content": "2b12d89fc52919b1963d3bd655cf21312df2306e3b7b3ff09c6812675197c58c"
         }
       ]
     },
@@ -2625,7 +2665,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e5173f2eafa803a5aaf0be03e238b5bc567f876fcb3caed4bae2148173baa998"
+          "content": "7418f3809477f66b524d69f3f438aaaea818451396b360fe509285f52db21767"
         }
       ]
     },
@@ -2725,7 +2765,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "2f051ebc8d86b6de4d359a5482c25b8cee59261a790599ced85c20162e0c87b1"
+          "content": "7ccb87beb02047e78c192e544e5aa893eb4c95ab21542fc38fdd1e123e8fc2cd"
         }
       ]
     },
@@ -2789,6 +2829,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "src/epoch-replay.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "031c838e16e30617e5149ff16af75d8b4058922525d1851682323ba0bc0bb85f"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "src/feature-adr-claim-gate.ts",
@@ -2825,7 +2875,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c0c8e4a58aff130a35c60d5de694ab7de851ea518008b70ad0b14b76318ebefd"
+          "content": "f56d5f5e59e9ddecae339b054b9f888b81b3410c56d3a09eedd7be3c11d3438c"
         }
       ]
     },
@@ -2845,7 +2895,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "bf307ef27bca0ac2ad6dbb6e8c7301507b042469cacee3a9a183ef1be3e69df7"
+          "content": "98f3820a8d7eafeb6405e2c80b05513ddce58dfccec57612f1136cfa6abdf40e"
         }
       ]
     },
@@ -3265,7 +3315,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "551e107380c9be270770266ebb258495825d942150c12c305345970de7f666b5"
+          "content": "9b6bf3726a14f774913440ee3053276e88a4dcaf1265ae48d8015bc4985489f1"
         }
       ]
     },
@@ -3459,6 +3509,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/epoch-replay.test.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "5f1f87608f41587f54f0b071b49ec19e1242ef94edc5c2a9be191534661f8ec9"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "test/feature-adr-abs-paths.test.ts",
@@ -3565,7 +3625,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "faf423970912978594624a70674aa152605819aa3407fdbae45770f3006bdc0b"
+          "content": "49829d24440130cfe403a410b9068a76631c68e9baa2cfc978f5029df2d72f3a"
         }
       ]
     },

package/src/backlog.ts

@@ -76,11 +76,50 @@ export interface DedupVerdict {
   /** Top-1 raw cosine (ADR-002 — never an RRF score). `-1` when there is nothing to compare against. */
   readonly cosine: number;
   readonly matchedId: string | undefined;
+  /**
+   * The id of the TOP-1 candidate whatever band it landed in — the ADR-002 CALIBRATION surface (idea
+   * ce914ac2). `matchedId` is only set for a DUPLICATE, so a RELATED verdict used to report a cosine with
+   * no way to see WHICH idea produced it; a user calibrating the 0.92 band needs the pair, not the number.
+   * Purely observational: it never changes the verdict.
+   */
+  readonly topMatchId: string | undefined;
   readonly relatedIds: readonly string[];
   /** True when the embedder was unavailable and dedup degraded to exact-text (ADR-002 §degrade). */
   readonly exactTextOnly: boolean;
 }
 
+/* ── Effort parsing (idea 86096d6d): a clamp the user cannot see is a silent surprise. ── */
+
+/** The result of interpreting a `--effort` argument, with the note the CLI must ECHO when it altered it. */
+export interface EffortParse {
+  readonly effort: number;
+  /** True when the parsed value was altered (clamped, floored, or rejected) — the CLI prints `note`. */
+  readonly adjusted: boolean;
+  /** Human line, e.g. `effort 13 → clamped to 5 (scale 1-5)`. Present iff `adjusted`. */
+  readonly note?: string;
+}
+
+export const EFFORT_MIN = 1;
+export const EFFORT_MAX = 5;
+
+/**
+ * PURE `--effort` interpreter. `dz backlog add --effort 13` used to store 5 and say NOTHING, so the user
+ * kept a wrong mental model of the scale (idea 86096d6d). Every alteration now carries a printable note;
+ * an in-range integer is returned untouched with `adjusted:false` (no noise on the happy path).
+ */
+export function parseEffort(raw: string | undefined, fallback: number): EffortParse {
+  if (raw === undefined) return { effort: fallback, adjusted: false };
+  const v = Number(raw);
+  if (!Number.isFinite(v)) {
+    return { effort: fallback, adjusted: true, note: `effort ${JSON.stringify(raw)} → not a number, using ${fallback} (scale ${EFFORT_MIN}-${EFFORT_MAX})` };
+  }
+  if (v < EFFORT_MIN) return { effort: EFFORT_MIN, adjusted: true, note: `effort ${raw} → clamped to ${EFFORT_MIN} (scale ${EFFORT_MIN}-${EFFORT_MAX})` };
+  if (v > EFFORT_MAX) return { effort: EFFORT_MAX, adjusted: true, note: `effort ${raw} → clamped to ${EFFORT_MAX} (scale ${EFFORT_MIN}-${EFFORT_MAX})` };
+  const floored = Math.floor(v);
+  if (floored !== v) return { effort: floored, adjusted: true, note: `effort ${raw} → rounded down to ${floored} (scale ${EFFORT_MIN}-${EFFORT_MAX}, whole numbers)` };
+  return { effort: floored, adjusted: false };
+}
+
 /* ================================================================== */
 /*  CONFIG (readBacklogConfig) — defensive, Number.isFinite clamps.     */
 /* ================================================================== */
@@ -257,6 +296,117 @@ export function writeIdeas(projectRoot: string, ideas: readonly IdeaRecord[]): v
   renameSync(tmp, path);
 }
 
+/* ── Store privacy (idea ec4cd60d): raw ideas are prompt-class PRIVATE content, like recall-usage.jsonl. ── */
+
+export type GitignoreAction = 'created' | 'appended' | 'already-covered' | 'user-opted-out' | 'skipped';
+export interface GitignoreScaffold {
+  readonly action: GitignoreAction;
+  readonly path: string;
+  /** Set for `skipped` (the I/O reason) and `user-opted-out` (the negation line we obeyed). */
+  readonly reason?: string;
+}
+
+/** The entry + its one-line rationale, written verbatim so the file explains itself. */
+const BACKLOG_IGNORE_ENTRY = '.dz/backlog/';
+const BACKLOG_IGNORE_COMMENT = '# dz backlog — captured ideas are private prompt-class content';
+
+/**
+ * Normalise ONE .gitignore pattern to the bare path it targets, so the equally-valid spellings of the
+ * same rule compare equal: a leading `/` (repo-root anchor), a trailing `/**` or `/*` (recursive glob),
+ * and a trailing `/` (directory marker) are all decoration around the same path. Returns `undefined`
+ * for anything that is not a plain path pattern (a comment, an empty line, or a pattern carrying a
+ * wildcard we do NOT interpret) — an uninterpretable pattern must never be read as coverage.
+ */
+function normaliseIgnorePattern(body: string): string | undefined {
+  let p = body.trim();
+  if (p === '' || p.startsWith('#')) return undefined;
+  if (p.startsWith('/')) p = p.slice(1); // repo-root anchor: `/.dz/` ≡ `.dz/`
+  p = p.replace(/\/\*\*$/, '').replace(/\/\*$/, ''); // `.dz/**` / `.dz/*` ≡ `.dz`
+  p = p.replace(/\/+$/, ''); // trailing directory marker
+  if (p === '' || p.includes('*') || p.includes('?') || p.includes('[')) return undefined; // not a plain path
+  return p;
+}
+
+/** True when the pattern targets the backlog store (directly or via its `.dz` parent). */
+function targetsBacklogStore(pattern: string): boolean {
+  return pattern === '.dz' || pattern === '.dz/backlog';
+}
+
+export type BacklogIgnoreStatus = 'covered' | 'negated' | 'uncovered';
+
+/**
+ * PURE .gitignore verdict for the backlog store. Deliberately NOT a full gitignore engine — it
+ * recognises the plain-path spellings of the rule (`/.dz/`, `.dz/**`, `.dz/backlog`, …) and refuses to
+ * interpret anything else, because a wrong-but-clever matcher either double-appends or silently
+ * decides a store is private when it is not.
+ *
+ * `negated` wins over `covered`: a `!.dz/backlog/` line (anchored or not) is the user saying *"track
+ * this on purpose"*. We obey it — appending a rule that overrides the user's explicit opt-out would be
+ * this tool deciding it knows better.
+ */
+export function backlogIgnoreStatus(gitignoreText: string): BacklogIgnoreStatus {
+  let covered = false;
+  for (const raw of String(gitignoreText).split('\n')) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const negated = line.startsWith('!');
+    const pattern = normaliseIgnorePattern(negated ? line.slice(1) : line);
+    if (pattern === undefined || !targetsBacklogStore(pattern)) continue;
+    if (negated) return 'negated'; // explicit user intent — decided, no further scanning
+    covered = true;
+  }
+  return covered ? 'covered' : 'uncovered';
+}
+
+/** Back-compat shim: "is it ignored?" — a negation is NOT coverage (the store is tracked on purpose). */
+export function backlogIgnoreCovered(gitignoreText: string): boolean {
+  return backlogIgnoreStatus(gitignoreText) === 'covered';
+}
+
+/** The file's dominant line ending, so an append does not mix CRLF and LF in one file. */
+function dominantEol(text: string): '\r\n' | '\n' {
+  const crlf = (text.match(/\r\n/g) ?? []).length;
+  const lf = (text.match(/\n/g) ?? []).length - crlf;
+  return crlf > lf ? '\r\n' : '\n';
+}
+
+/** Atomic write (tmp + rename in the SAME dir) — the ideas.jsonl discipline: a crash never truncates. */
+function writeFileAtomic(path: string, body: string): void {
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, body);
+  renameSync(tmp, path);
+}
+
+/**
+ * Ensure the backlog store is gitignored, at the moment the feature FIRST creates it (idea ec4cd60d).
+ * Creates a `.gitignore` when there is none; appends the entry (+ its comment) when the project has one
+ * that does not cover the store; touches NOTHING when it is already covered OR when the user explicitly
+ * negated the rule. The write is ATOMIC and preserves the file's dominant EOL.
+ * Never throws — an unwritable .gitignore degrades to `skipped`, and the CALLER must say so out loud
+ * (a silently un-ignored store is exactly the privacy leak this function exists to prevent).
+ */
+export function ensureBacklogGitignored(projectRoot: string): GitignoreScaffold {
+  const path = join(projectRoot, '.gitignore');
+  try {
+    if (!existsSync(path)) {
+      writeFileAtomic(path, `${BACKLOG_IGNORE_COMMENT}\n${BACKLOG_IGNORE_ENTRY}\n`);
+      return { action: 'created', path };
+    }
+    const text = readFileSync(path, 'utf-8');
+    const status = backlogIgnoreStatus(text);
+    if (status === 'covered') return { action: 'already-covered', path };
+    if (status === 'negated') {
+      return { action: 'user-opted-out', path, reason: 'a "!" negation for the backlog store is present — respecting the explicit opt-out and adding nothing' };
+    }
+    const eol = dominantEol(text);
+    const sep = text === '' || text.endsWith('\n') ? '' : eol;
+    writeFileAtomic(path, `${text}${sep}${eol}${BACKLOG_IGNORE_COMMENT}${eol}${BACKLOG_IGNORE_ENTRY}${eol}`);
+    return { action: 'appended', path };
+  } catch (err) {
+    return { action: 'skipped', path, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 /** Pre-mutation snapshot (NFR-6) — mirrors `snapshotStore`. A failed snapshot returns `{error}` so
  *  the caller ABORTS the mutation (no partial merge). */
 export interface SnapshotResult {
@@ -303,15 +453,15 @@ export function classifyDedup(
   const sorted = candidates.filter((c) => Number.isFinite(c.cosine)).sort((a, b) => b.cosine - a.cosine);
   const top = sorted[0];
   const exactTextOnly = opts.exactTextOnly === true;
-  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, relatedIds: [], exactTextOnly };
+  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly };
   if (top.cosine >= cfg.duplicateThreshold) {
-    return { action: 'duplicate', cosine: top.cosine, matchedId: top.id, relatedIds: [], exactTextOnly };
+    return { action: 'duplicate', cosine: top.cosine, matchedId: top.id, topMatchId: top.id, relatedIds: [], exactTextOnly };
   }
   const related = sorted.filter((c) => c.cosine >= cfg.relatednessFloor && c.cosine < cfg.duplicateThreshold);
   if (related.length > 0) {
-    return { action: 'related', cosine: top.cosine, matchedId: undefined, relatedIds: related.map((c) => c.id), exactTextOnly };
+    return { action: 'related', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: related.map((c) => c.id), exactTextOnly };
   }
-  return { action: 'new', cosine: top.cosine, matchedId: undefined, relatedIds: [], exactTextOnly };
+  return { action: 'new', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: [], exactTextOnly };
 }
 
 /** Injectable deps so the production dedup path is testable without a live agentdb. */
@@ -354,8 +504,8 @@ export async function dedupIdea(projectRoot: string, text: string, cfg: BacklogC
     // EXACT-text safety net: identical text among existing ideas is still a DUPLICATE (content-addressed
     // idempotency, ADR-002 §degrade). Otherwise NEW — the RELATED band needs cosine and is skipped.
     const match = ideas.find((i) => i.text === text);
-    if (match !== undefined) return { action: 'duplicate', cosine: 1, matchedId: match.id, relatedIds: [], exactTextOnly: true };
-    return { action: 'new', cosine: -1, matchedId: undefined, relatedIds: [], exactTextOnly: result.error !== undefined };
+    if (match !== undefined) return { action: 'duplicate', cosine: 1, matchedId: match.id, topMatchId: match.id, relatedIds: [], exactTextOnly: true };
+    return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly: result.error !== undefined };
   }
   return classifyDedup(candidates, cfg.dedup);
 }
@@ -364,30 +514,135 @@ export async function dedupIdea(projectRoot: string, text: string, cfg: BacklogC
 /*  ALIGNMENT (AM-3 / ADR-003) — weighted-MAX cosine over the GoalMap.  */
 /* ================================================================== */
 
-/** Defensive GoalMap reader — never throws; a missing/corrupt file ⇒ empty compass. */
-export function readGoalMap(projectRoot: string): GoalMap {
+/** One goal entry the reader REFUSED, with the reason — the anti-vacuous-valid evidence (idea 960c9f26). */
+export interface DroppedGoal {
+  /** 0-based index of the entry in the file's `goals` array. */
+  readonly index: number;
+  /** Machine-stable reason, e.g. `missing "statement"`. */
+  readonly reason: string;
+}
+
+/**
+ * What the defensive read actually SAW. `readGoalMap` throws away the drops (correct for runtime paths —
+ * a corrupt compass must never break capture), but `goals --validate` needs them: a goals.json whose every
+ * entry was silently dropped previously reported *"valid (0 goal(s))"* — a vacuous pass that hid the user's
+ * typo (`text` instead of `statement`). This variant is the validate-facing reader.
+ */
+export interface GoalMapRead {
+  readonly goalMap: GoalMap;
+  /** Entries present in the file's `goals` array (kept + dropped). */
+  readonly present: number;
+  readonly dropped: readonly DroppedGoal[];
+  /**
+   * Fields the reader REPAIRED to keep the runtime safe. The clamp happens BEFORE any validation could
+   * see the original, so a `weight: 7` becomes a legal 1 and the validator's out-of-range branch is
+   * unreachable — a silent repair reported as "valid". These carry the RAW value so `goals --validate`
+   * can warn about what the user actually wrote while the runtime keeps the clamped value.
+   */
+  readonly repaired: readonly RepairedGoalField[];
+  /** Set when the file exists but could not be parsed / has no `goals` array. */
+  readonly parseError?: string;
+}
+
+/** One field the defensive reader clamped/replaced, with both the raw and the used value. */
+export interface RepairedGoalField {
+  readonly index: number;
+  readonly id: string;
+  readonly field: 'weight';
+  readonly raw: unknown;
+  readonly used: number;
+  /** Human reason, e.g. `weight 7 is out of (0,1]`. */
+  readonly reason: string;
+}
+
+/** Reason an entry cannot become a Goal — `undefined` when it is well-formed. */
+function goalDropReason(o: unknown): string | undefined {
+  if (o === null || typeof o !== 'object' || Array.isArray(o)) return 'not an object';
+  const r = o as Record<string, unknown>;
+  if (typeof r.id !== 'string') return 'missing "id"';
+  if (typeof r.statement !== 'string') return 'missing "statement"';
+  return undefined;
+}
+
+/**
+ * Detailed GoalMap read — never throws, and REPORTS what it dropped (idea 960c9f26). `readGoalMap` is the
+ * lossy runtime view of this; both share one parser so they can never disagree about what a goal is.
+ */
+export function readGoalMapDetailed(projectRoot: string): GoalMapRead {
   const path = goalsPath(projectRoot);
-  if (!existsSync(path)) return { version: 1, goals: [] };
+  if (!existsSync(path)) return { goalMap: { version: 1, goals: [] }, present: 0, dropped: [], repaired: [] };
+  let parsed: { version?: unknown; goals?: unknown };
   try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { version?: unknown; goals?: unknown };
-    const goals: Goal[] = Array.isArray(parsed.goals)
-      ? parsed.goals
-          .map((g): Goal | undefined => {
-            const o = g as Record<string, unknown>;
-            if (typeof o.id !== 'string' || typeof o.statement !== 'string') return undefined;
-            return {
-              id: o.id,
-              statement: o.statement,
-              weight: clampNum(o.weight, Number.MIN_VALUE, 1, 1),
-              keywords: Array.isArray(o.keywords) ? o.keywords.filter((k): k is string => typeof k === 'string') : [],
-            };
-          })
-          .filter((g): g is Goal => g !== undefined)
-      : [];
-    return { version: typeof parsed.version === 'number' ? parsed.version : 1, goals };
-  } catch {
-    return { version: 1, goals: [] };
+    parsed = JSON.parse(readFileSync(path, 'utf-8')) as { version?: unknown; goals?: unknown };
+  } catch (err) {
+    return {
+      goalMap: { version: 1, goals: [] },
+      present: 0,
+      dropped: [],
+      repaired: [],
+      parseError: `goals.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  // Valid JSON that is not an object (null, a number, an array) must not crash the never-throw
+  // reader: `parsed.version` on null is a TypeError (Codex re-QE HIGH).
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      goalMap: { version: 1, goals: [] },
+      present: 0,
+      dropped: [],
+      repaired: [],
+      parseError: 'goals.json is valid JSON but not an object',
+    };
   }
+  const version = typeof parsed.version === 'number' ? parsed.version : 1;
+  if (!Array.isArray(parsed.goals)) {
+    return {
+      goalMap: { version, goals: [] },
+      present: 0,
+      dropped: [],
+      repaired: [],
+      parseError: 'goals.json has no `goals` array',
+    };
+  }
+  const goals: Goal[] = [];
+  const dropped: DroppedGoal[] = [];
+  const repaired: RepairedGoalField[] = [];
+  parsed.goals.forEach((g, index) => {
+    const reason = goalDropReason(g);
+    if (reason !== undefined) {
+      dropped.push({ index, reason });
+      return;
+    }
+    const o = g as Record<string, unknown>;
+    const id = o.id as string;
+    // The clamp keeps the RUNTIME safe; the raw value is recorded so validation can still see what the
+    // user wrote (MED-7: clamping before validating made the validator's out-of-range branch dead code).
+    const weight = clampNum(o.weight, Number.MIN_VALUE, 1, 1);
+    if (o.weight !== undefined && o.weight !== weight) {
+      repaired.push({
+        index,
+        id,
+        field: 'weight',
+        raw: o.weight,
+        used: weight,
+        reason: typeof o.weight === 'number' && Number.isFinite(o.weight)
+          ? `weight ${o.weight} is out of (0,1]`
+          : `weight ${JSON.stringify(o.weight) ?? String(o.weight)} is not a number in (0,1]`,
+      });
+    }
+    goals.push({
+      id,
+      statement: o.statement as string,
+      weight,
+      keywords: Array.isArray(o.keywords) ? o.keywords.filter((k): k is string => typeof k === 'string') : [],
+    });
+  });
+  return { goalMap: { version, goals }, present: parsed.goals.length, dropped, repaired };
+}
+
+/** Defensive GoalMap reader — never throws; a missing/corrupt file ⇒ empty compass (the runtime path). */
+export function readGoalMap(projectRoot: string): GoalMap {
+  return readGoalMapDetailed(projectRoot).goalMap;
 }
 
 /** The text embedded for a goal: statement + keywords (same convention across cache + score). */