@lh8ppl/claude-memory-kit 0.4.2 → 0.4.3

package/src/index-rebuild.mjs

@@ -48,10 +48,12 @@ import chokidar from 'chokidar';
 import { INDEX_DB_SCHEMA } from './index-db.mjs';
 import { hashContent } from './content-hash.mjs';
 import { syncTranscriptChunks } from './transcript-index.mjs';
-import { readBullet, parseBulletProvenance } from './provenance.mjs';
+import { readBullet, parseBulletProvenance, isSeedProvenance } from './provenance.mjs';
 import { parse as parseFrontmatter } from './frontmatter.mjs';
+import { initTrustScore } from './trust-score.mjs';
 import {
   VALID_TIERS,
+  SCRATCHPADS_BY_TIER,
   resolveTierRoot,
   resolveFactDir,
   ID_PATTERN,
@@ -70,10 +72,19 @@ export function listObservationSources({ projectRoot, userDir }) {
   for (const tier of ['P', 'L', 'U']) {
     const root = resolveTierRoot({ tier, projectRoot, userDir });
     if (!existsSync(root)) continue;
-    // Scratchpad: <tier>/MEMORY.md
-    const scratchpad = join(root, 'MEMORY.md');
-    if (existsSync(scratchpad)) {
-      sources.push({ path: scratchpad, tier, kind: 'scratchpad' });
+    // Scratchpads: EVERY canonical scratchpad for the tier, not just MEMORY.md
+    // (Task 182 / D-247). Pre-182 this hardcoded `<tier>/MEMORY.md`, so the
+    // project-tier SOUL.md AND the entire user-tier persona (USER/HABITS/
+    // LESSONS.md — where `cmk lessons promote` writes) were never indexed, and
+    // a promoted persona fact was unsearchable even in-session. Iterating
+    // SCRATCHPADS_BY_TIER (the same allow-list the writer/cap layer uses) fixes
+    // all of them at once with no filename drift. They all share the
+    // bullet + provenance-comment shape the scratchpad parser already handles.
+    for (const scratchpadName of SCRATCHPADS_BY_TIER[tier] ?? []) {
+      const scratchpad = join(root, scratchpadName);
+      if (existsSync(scratchpad)) {
+        sources.push({ path: scratchpad, tier, kind: 'scratchpad' });
+      }
     }
     // Granular fact files: <tier>/memory/*.md (excluding INDEX.md)
     const factDir = resolveFactDir(tier, root);
@@ -132,10 +143,12 @@ function relativeSource(absPath, { projectRoot, userDir }) {
 // --- Parsing ----------------------------------------------------------
 
 /**
- * Parse a scratchpad MEMORY.md into observations.
+ * Parse a scratchpad (MEMORY.md / SOUL.md / USER.md / HABITS.md / LESSONS.md /
+ * machine-paths.md / overrides.md — any of SCRATCHPADS_BY_TIER) into observations.
  *
  * Walks line-by-line tracking the most recent h2 heading. For each
  * bullet+comment pair, calls readBullet() to extract id/text/provenance.
+ * Scaffold `(example)` seed bullets (all-zero sha1) are skipped (Task 183).
  * Returns one row per bullet conforming to the observations schema.
  *
  * Tolerant: bullets without a following provenance comment are skipped
@@ -174,6 +187,11 @@ export function parseObservationsFromScratchpad({
     const bullet = readBullet({ bulletLine: line, commentLine: next });
     if (!bullet) continue;
     const { id, text, provenance } = bullet;
+    // Task 183 (D-247): skip scaffold `(example)` seed bullets (all-zero sha1)
+    // — they must never enter the search index, else a fresh install returns
+    // only misleading placeholders. Mirrors the inject path's existing seed
+    // filter (shared `isSeedProvenance`, so both surfaces stay in agreement).
+    if (isSeedProvenance(provenance)) continue;
     const heading_path = currentHeading
       ? `${baseName} > ${currentHeading}`
       : baseName;
@@ -266,6 +284,14 @@ export function parseObservationsFromFactFile({
     body: (body ?? '').trim() || (frontmatter.title ?? ''),
     write_source: frontmatter.write_source,
     trust: frontmatter.trust,
+    // 151.8: the committed recurrence_count (151.1) seeds the trust_score's
+    // DURABLE restatement term — survives every reindex (reconstructed from this).
+    // Floor to 1 for a missing OR malformed (≤0) value — consistent with the other
+    // four recurrence readers (write-fact / assembleProjectCorpus / trust-score)
+    // which all treat <1 as the 1× baseline (the field starts at 1, only increments).
+    recurrence_count: Number.isFinite(frontmatter.recurrence_count) && frontmatter.recurrence_count > 0
+      ? frontmatter.recurrence_count
+      : 1,
     created_at: isoToEpochMs(frontmatter.created_at),
     superseded_by: frontmatter.superseded_by ?? null,
     deleted_at: frontmatter.deleted_at ? isoToEpochMs(frontmatter.deleted_at) : null,
@@ -332,19 +358,19 @@ const DELETE_OBSERVATION_BY_ID_SQL = `DELETE FROM observations WHERE id = ?`;
 const INSERT_OBSERVATION_SQL = `
 INSERT INTO observations
   (id, tier, source_file, source_line, source_sha1, heading_path, body,
-   write_source, trust, created_at, superseded_by, deleted_at)
+   write_source, trust, trust_score, created_at, superseded_by, deleted_at)
 VALUES
   (@id, @tier, @source_file, @source_line, @source_sha1, @heading_path, @body,
-   @write_source, @trust, @created_at, @superseded_by, @deleted_at)
+   @write_source, @trust, @trust_score, @created_at, @superseded_by, @deleted_at)
 `;
 
 const INSERT_SCRATCHPAD_OBSERVATION_SQL = `
 INSERT INTO observations
   (id, tier, source_file, source_line, source_sha1, heading_path, body,
-   write_source, trust, created_at, superseded_by, deleted_at)
+   write_source, trust, trust_score, created_at, superseded_by, deleted_at)
 VALUES
   (@id, @tier, @source_file, @source_line, @source_sha1, @heading_path, @body,
-   @write_source, @trust, @created_at, @superseded_by, @deleted_at)
+   @write_source, @trust, @trust_score, @created_at, @superseded_by, @deleted_at)
 ON CONFLICT(id) DO NOTHING
 `;
 
@@ -396,17 +422,37 @@ function replaceObservationsForFile(db, { source, observations, mtime, sha1, pro
   // safe: ids are content-addressed WITH the tier as a prefix (`P-`/`L-`/`U-`),
   // so a P-tier and U-tier fact can never share an id — no cross-tier delete is
   // possible. (Defended by the P/U-same-content tier test below.)
+  // 151.6/151.8: seed trust_score from the fact's committed signals — enum +
+  // source + the DURABLE recurrence term (151.8: a re-stated fact seeds higher,
+  // reconstructed from the committed recurrence_count so it survives every
+  // reindex). Computed here at insert (one place). `recurrence_count` is consumed
+  // by the seed but is NOT an `observations` column, so it's stripped from the
+  // bound row (better-sqlite3 rejects unknown named params). The asymmetric
+  // DAMPEN deltas (151.8 contradiction/supersession) stay as runtime overlays on
+  // the trust_score column — they survive a boot reindex (unchanged files skipped)
+  // and reseed only on a full rebuild (the local-protection-signal posture, D-237).
+  const withTrustScore = (obs) => {
+    const { recurrence_count, ...row } = obs;
+    return {
+      ...row,
+      trust_score: initTrustScore({
+        trust: obs.trust,
+        writeSource: obs.write_source,
+        recurrenceCount: recurrence_count,
+      }),
+    };
+  };
   if (source.kind === 'fact') {
     const deleteById = db.prepare(DELETE_OBSERVATION_BY_ID_SQL);
     const insert = db.prepare(INSERT_OBSERVATION_SQL);
     for (const obs of observations) {
       deleteById.run(obs.id);
-      insert.run(obs);
+      insert.run(withTrustScore(obs));
     }
   } else {
     const insert = db.prepare(INSERT_SCRATCHPAD_OBSERVATION_SQL);
     for (const obs of observations) {
-      insert.run(obs);
+      insert.run(withTrustScore(obs));
     }
   }
   db.prepare(UPSERT_FILE_SQL).run({
@@ -687,8 +733,15 @@ export function startRuntimeWatcher({
     const root = resolveTierRoot({ tier, projectRoot, userDir });
     if (!existsSync(root)) continue;
     tierRoots.push({ tier, root });
-    const scratchpad = join(root, 'MEMORY.md');
-    if (existsSync(scratchpad)) watchPaths.push(scratchpad);
+    // Watch EVERY canonical scratchpad for the tier (Task 182 / D-247), not
+    // just MEMORY.md — must stay in lockstep with listObservationSources above,
+    // else a live edit to SOUL.md / a `cmk lessons promote` into HABITS.md
+    // wouldn't trigger a runtime re-index (indexed on full reindex but not
+    // watched — the composition gap the caller-map rule catches).
+    for (const scratchpadName of SCRATCHPADS_BY_TIER[tier] ?? []) {
+      const scratchpad = join(root, scratchpadName);
+      if (existsSync(scratchpad)) watchPaths.push(scratchpad);
+    }
     const factDir = resolveFactDir(tier, root);
     if (existsSync(factDir)) watchPaths.push(factDir);
   }

package/src/inject-context.mjs

@@ -502,6 +502,12 @@ function truncateTierToBudget(blockText, budget, valueById = new Map()) {
   // Drop order: lowest aggregate trust first → oldest first → later-in-file
   // first (the legacy tail tiebreak, so equal-value blocks still drop from the
   // end). High-value sections are evicted only after everything cheaper is gone.
+  // 151.5: this IS the value-ordered sweep (high-trust survives, low-trust drops
+  // first) — the inject half of ADR-0016 §20.3. 151.6 re-eval RESOLVED (D-238):
+  // KEEP the `maxTrust` enum here — adding an index-db trust_score lookup would put
+  // DB I/O on the 500ms inject path + rank on an overlay that resets on full reindex
+  // (non-deterministic across repair). The evolved score is a FLOOR/protection
+  // signal, not a sweep-ranking driver (rank-by-score = the cautionary bug). §20.3.
   const dropOrder = [...sections].sort(
     (a, b) =>
       a.maxTrust - b.maxTrust ||

package/src/lessons-promote.mjs

@@ -29,6 +29,69 @@ const DEFAULT_SECTION = Object.freeze({
   'USER.md': 'Profile',
 });
 
+// Task 151.9 — the offline TOPIC-router (fixes Hole C, §20.4). Before this, every
+// no-arg `cmk lessons promote` funnelled into LESSONS § Cross-Project Lessons →
+// single-section overflow. routeTopic spreads promotes across the three user-tier
+// files by CONTENT, using auto-persona's taxonomy (USER=identity/preferences,
+// HABITS=working-style, LESSONS=cross-project lessons) — but OFFLINE + deterministic
+// (NO Haiku: the explicit command stays instant + network-free; the Haiku
+// classifier stays on the AUTOMATIC path, which already runs an LLM. The two paths
+// each topic-route, each by the router that fits — D-238-style two-mechanism split).
+// Ordered most-specific → fallback; LESSONS is the safe catch-all for a
+// cross-project fact. Each route's default section is per-file below.
+const ROUTE_RULES = [
+  // identity / preferences → USER.md
+  { target: 'USER.md', section: 'Preferences', re: /\b(i ?a?m a |i'?m a |my name|my role|i'?m an? |i prefer|i like|i dislike|i favou?r|i'?m the|as a developer|i work as)\b/i },
+  // working-style / process / cadence → HABITS.md
+  { target: 'HABITS.md', section: 'Working Style', re: /\b(i always|i never|from now on|going forward|how i work|my workflow|my process|my cadence|i (commit|branch|review|test|deploy|lint|format)|always .{0,30}before|never .{0,30}without)\b/i },
+  // cross-project lessons / tooling gotchas → LESSONS.md
+  { target: 'LESSONS.md', section: 'Tooling Lessons', re: /\b(learned|lesson|gotcha|til\b|the hard way|turns out|pitfall|caveat|watch out|footgun|bug:|broke)\b/i },
+];
+
+/**
+ * Route a promote to {target, section} by content (Task 151.9). Pure + offline +
+ * deterministic — no LLM. Falls back to LESSONS § Cross-Project Lessons (the safe
+ * cross-project catch-all) when nothing matches.
+ *
+ * @param {string} [text] the fact body
+ * @returns {{target:string, section:string}}
+ */
+export function routeTopic(text) {
+  const t = String(text ?? '');
+  for (const rule of ROUTE_RULES) {
+    if (rule.re.test(t)) return { target: rule.target, section: rule.section };
+  }
+  return { target: 'LESSONS.md', section: DEFAULT_SECTION['LESSONS.md'] };
+}
+
+// Task 151.11 — the recurrence at which a promotion is worth an optional MENTION.
+// A one-off promote stays silent; a fact that has RECURRED this many times earns a
+// fire-and-forget heads-up. Matches the promotion gate floor (heat.PROMOTE_THRESHOLD
+// = 3) — "seen ≥3× → durable enough to be worth a word."
+export const MENTION_RECURRENCE = 3;
+
+/**
+ * Build the optional in-conversation MENTION for a high-recurrence promotion
+ * (Task 151.11, awrshift warmth, §20.4). Returns a short heads-up STRING Claude
+ * MAY relay — or `null` below the recurrence threshold (stay silent). It is NOT a
+ * gate: it frames the post-hoc revert ("say so if wrong" / `cmk forget`), never
+ * asks a blocking question (D-169 — no human-in-the-loop). Pure.
+ *
+ * @param {object} o
+ * @param {string} [o.text]            the promoted fact text (trimmed into the note)
+ * @param {number} [o.recurrenceCount] how many times the fact has recurred
+ * @param {string} [o.target]          the user-tier file it landed in
+ * @returns {string|null}
+ */
+export function buildPromotionMention({ text, recurrenceCount, target } = {}) {
+  const n = Number.isFinite(recurrenceCount) ? recurrenceCount : 0;
+  if (n < MENTION_RECURRENCE) return null;
+  const snippet = String(text ?? '').replace(/\s+/g, ' ').trim().slice(0, 80);
+  const where = target ? ` (now in your ${target} persona)` : '';
+  // A statement + a revert offer — never a question (would re-introduce the gate).
+  return `Noticed "${snippet}" has recurred ${n}× across your work — promoted it to your cross-project persona${where}. Tell me to forget it if that's wrong.`;
+}
+
 /**
  * Promote a project-tier fact to the user tier through the safe path.
  *
@@ -41,11 +104,14 @@ const DEFAULT_SECTION = Object.freeze({
  * @param {string} [opts.now]       ISO timestamp override (tests)
  * @returns {{action:string, id?:string, target?:string, section?:string, ...}}
  */
-export function lessonsPromote({ id, projectRoot, userDir, to = 'LESSONS.md', section, now } = {}) {
+export function lessonsPromote({ id, projectRoot, userDir, to, section, now } = {}) {
   if (!userDir) {
     return errorResult({ category: 'schema', errors: ['userDir is required (lessons promote writes to the user tier)'] });
   }
-  if (!VALID_TARGETS.has(to)) {
+  // An EXPLICIT `to` is validated up front; an absent `to` is filled by the 151.9
+  // topic-router below (after the fact body is known), so the no-arg promote spreads
+  // across USER/HABITS/LESSONS by content instead of funnelling to one section.
+  if (to !== undefined && !VALID_TARGETS.has(to)) {
     return errorResult({ category: 'schema', errors: [`invalid target '${to}' (expected USER.md | HABITS.md | LESSONS.md)`] });
   }
   // `lessons promote` carries a PROJECT observation to the user tier. Reject a
@@ -92,9 +158,17 @@ export function lessonsPromote({ id, projectRoot, userDir, to = 'LESSONS.md', se
     return errorResult({ category: 'schema', errors: [`fact '${id}' has no body to promote`], id });
   }
 
+  // Task 151.9 — TOPIC-route when the user didn't pin a target (fixes Hole C).
+  // An explicit `--to` (and/or `--section`) always wins; otherwise the offline
+  // router picks target+section by content so no-arg promotes spread across
+  // USER/HABITS/LESSONS instead of piling into one section.
+  const routed = to === undefined ? routeTopic(text) : { target: to, section: DEFAULT_SECTION[to] };
+  const finalTarget = routed.target;
+  const finalSection = section || routed.section;
+
   const candidate = {
-    target: to,
-    section: section || DEFAULT_SECTION[to],
+    target: finalTarget,
+    section: finalSection,
     text,
     confidence: 'high', // explicit user action → clears the confidence gate (promotes, not queued)
   };
@@ -110,27 +184,36 @@ export function lessonsPromote({ id, projectRoot, userDir, to = 'LESSONS.md', se
     source: 'user-explicit',
   });
 
-  const promotedHit = res.promoted.find((p) => p.target === to);
+  // Task 151.11 — optional heads-up on a HIGH-RECURRENCE promotion. Fire-and-
+  // forget: it rides on the SUCCESS result for Claude to optionally relay; it
+  // never gates or blocks (null below the threshold → silent, the D-169 default).
+  const mention = buildPromotionMention({
+    text,
+    recurrenceCount: found.frontmatter?.recurrence_count,
+    target: finalTarget,
+  });
+
+  const promotedHit = res.promoted.find((p) => p.target === finalTarget);
   if (promotedHit) {
-    return { action: 'promoted', id, target: to, section: candidate.section, newId: promotedHit.id ?? null };
+    return { action: 'promoted', id, target: finalTarget, section: candidate.section, newId: promotedHit.id ?? null, ...(mention ? { mention } : {}) };
   }
   // A supersede is ALSO success: the promotion replaced an existing same-topic
   // lesson with this updated one (common when the user re-promotes a refined rule).
-  const supersededHit = res.superseded.find((s) => s.target === to);
+  const supersededHit = res.superseded.find((s) => s.target === finalTarget);
   if (supersededHit) {
-    return { action: 'promoted', id, target: to, section: candidate.section, newId: supersededHit.newId, superseded: supersededHit.oldId };
+    return { action: 'promoted', id, target: finalTarget, section: candidate.section, newId: supersededHit.newId, superseded: supersededHit.oldId, ...(mention ? { mention } : {}) };
   }
   // Routed to the conflict queue (e.g. it clashes with a hand-curated entry the
   // kit won't silently overwrite) or otherwise didn't land — surface honestly.
-  const conflictHit = res.conflicts.find((q) => q.target === to);
+  const conflictHit = res.conflicts.find((q) => q.target === finalTarget);
   if (conflictHit) {
-    return { action: 'queued', id, target: to, section: candidate.section, reason: 'conflict' };
+    return { action: 'queued', id, target: finalTarget, section: candidate.section, reason: 'conflict' };
   }
-  const queuedHit = res.queued.find((q) => q.target === to);
+  const queuedHit = res.queued.find((q) => q.target === finalTarget);
   return {
     action: 'queued',
     id,
-    target: to,
+    target: finalTarget,
     section: candidate.section,
     reason: queuedHit?.reason ?? 'not-promoted',
   };

package/src/mcp-server.mjs

@@ -411,7 +411,12 @@ function makeMkTrust({ projectRoot, userDir }) {
 
 function makeMkLessonsPromote({ projectRoot, userDir }) {
   return async ({ id, to }) => {
-    const r = lessonsPromote({ id, projectRoot, userDir, to: to ?? 'LESSONS.md' });
+    // 151.9: pass `to` THROUGH (undefined when the caller omits it) so the offline
+    // TOPIC-router spreads the promote across USER/HABITS/LESSONS by content. The
+    // old `to ?? 'LESSONS.md'` forced every MCP-driven promote into LESSONS,
+    // bypassing the router (Hole C) — and the MCP path is the PRIMARY one (Claude
+    // drives the kit via the tool, not the CLI). An explicit `to` still wins.
+    const r = lessonsPromote({ id, projectRoot, userDir, to });
     if (r.action !== 'promoted' && r.action !== 'queued') return mcpToolError(r);
     return {
       content: [{ type: 'text', text: JSON.stringify(
@@ -421,6 +426,10 @@ function makeMkLessonsPromote({ projectRoot, userDir }) {
           id: r.id,
           target: r.target,
           section: r.section,
+          // 151.11: surface the optional high-recurrence MENTION so Claude MAY
+          // relay it in conversation (a heads-up, NOT a gate — never blocks; only
+          // present when the fact recurred enough to be worth a word).
+          ...(r.mention ? { mention: r.mention } : {}),
           ...(r.action === 'queued'
             ? { status: 'queued', hint: 'Promotion routed to the user-tier review/conflict queue — it lands once resolved.' }
             : {}),

package/src/memory-write.mjs

@@ -59,6 +59,7 @@ import { checkPoisonGuard, logPoisonGuardRejection } from './poison-guard.mjs';
 import { detectConflicts, writeConflictEntry } from './conflict-queue.mjs';
 import { sanitizeHomePaths } from './sanitize.mjs';
 import { sanitizePrivacyTags } from './privacy.mjs';
+import { applyTrustSignal } from './trust-signal.mjs';
 
 const VALID_ACTIONS = new Set(['add', 'replace', 'remove']);
 
@@ -354,6 +355,11 @@ function doAdd(opts) {
     // named-args — Task 25 originally called it as an object.)
     const proposedId = generateId(addOpts.tier, addOpts.text);
     const ts = opts.now ?? nowIso();
+    // Task 151.8: a new write CONTRADICTING an existing fact (routed to the
+    // conflict queue) is the contradiction passive signal → DAMPEN the existing
+    // fact's trust_score. Best-effort overlay on the rebuildable index; the queue
+    // routing is unaffected.
+    applyTrustSignal({ projectRoot: opts.projectRoot, id: conflict.existingId, event: 'dampen' });
     return writeConflictEntry({
       tier: opts.tier,
       projectRoot: opts.projectRoot,
@@ -499,6 +505,18 @@ function doReplace(opts) {
     extra: { oldId: match.id, newId: addResult.id, scratchpad: opts.scratchpad },
   });
 
+  // Task 151.8: a replace SUPERSEDES the old fact → DAMPEN its trust_score (the
+  // supersession passive signal). Covers the REPLACE path (direct + auto-persona's
+  // persona-supersede, which calls memoryWrite({action:'replace'}) → here).
+  // KNOWN GAP (honest scope): two OTHER supersession writers set `superseded_by`
+  // WITHOUT routing through doReplace and therefore do NOT dampen yet —
+  // conflict-queue.mjs::mergeScratchpadBullets (merge-both) and
+  // merge-facts.mjs::moveToSuperseded. Wiring those is deferred to Task 151.12
+  // (the supersede-hooks sub-task), where a single `superseded_by`-write chokepoint
+  // is the right place. Best-effort overlay on the rebuildable index — never breaks
+  // the replace.
+  applyTrustSignal({ projectRoot: opts.projectRoot, id: match.id, event: 'dampen' });
+
   return {
     action: 'replaced',
     oldId: match.id,

package/src/merge-facts.mjs

@@ -27,6 +27,8 @@ import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult, notFoundResult } from './result-shapes.mjs';
 import { writeFact } from './write-fact.mjs';
 import { reindex } from './reindex.mjs';
+import { applyTrustSignal } from './trust-signal.mjs';
+import { openIndexDb } from './index-db.mjs';
 
 function listLiveFactFiles(factDir) {
   if (!existsSync(factDir)) return [];
@@ -205,6 +207,23 @@ export function mergeFacts(opts = {}) {
     // index rebuild is best-effort; the merge already succeeded
   }
 
+  // Task 151.12 — a merge SUPERSEDES the two originals → DAMPEN their trust_score
+  // (the supersession passive signal; 151.8 wired the replace path, this closes
+  // the merge-path gap). Best-effort overlay — never breaks the merge; a superseded
+  // fact's row may already be filtered, in which case applyTrustSignal no-ops.
+  // Share ONE index-db handle across the two dampens (avoid open/close per id).
+  try {
+    const sigDb = openIndexDb({ projectRoot });
+    try {
+      applyTrustSignal({ id: idA, event: 'dampen', db: sigDb });
+      applyTrustSignal({ id: idB, event: 'dampen', db: sigDb });
+    } finally {
+      sigDb.close();
+    }
+  } catch {
+    // best-effort: the trust dampen must never break the merge.
+  }
+
   const ts = now ?? nowIso();
   appendAuditEntry(tierRoot, {
     ts,

package/src/poison-guard.mjs

@@ -36,6 +36,25 @@ import {
 } from 'node:fs';
 import { join, dirname } from 'node:path';
 
+// Task 70.4 — the invisible / zero-width / bidi code points, listed EXPLICITLY
+// (no literal invisible chars in source — those are unreadable + editor-mangleable).
+// Built into a regex char-class via `String.fromCodePoint` at module load.
+const INVISIBLE_UNICODE_CODEPOINTS = [
+  0x00ad, // soft hyphen
+  0x061c, // Arabic letter mark
+  0x180e, // Mongolian vowel separator
+  0x200b, 0x200c, 0x200d, // zero-width space / non-joiner / joiner
+  0x2060, // word joiner
+  0x2066, 0x2067, 0x2068, 0x2069, // bidi isolates: LRI / RLI / FSI / PDI
+  0x202a, 0x202b, 0x202c, 0x202d, 0x202e, // bidi embeds/overrides: LRE/RLE/PDF/LRO/RLO
+  0xfeff, // BOM / zero-width no-break space
+];
+function buildInvisibleUnicodeRe() {
+  const cls = INVISIBLE_UNICODE_CODEPOINTS.map((cp) => `\\u${cp.toString(16).padStart(4, '0')}`).join('');
+  return new RegExp(`[${cls}]`);
+}
+const INVISIBLE_UNICODE_RE = buildInvisibleUnicodeRe();
+
 // --- Pattern catalog -------------------------------------------------
 // Each pattern is { id, re, category }. The id is the stable
 // machine-parseable name that shows up in poison-guard.log NDJSON +
@@ -204,6 +223,29 @@ const INJECTION_PATTERNS = [
     category: 'injection',
     re: /disregard the above/i,
   },
+  // Task 70.4 — invisible / zero-width / bidi Unicode. A hidden-instruction
+  // vector: characters invisible to a human reviewer can smuggle text past the
+  // eye AND past the other patterns, then ship with `git clone` in committed
+  // memory. The set (Hermes parity + the Trojan-Source bidi class — kiro-design
+  // §699 / kiro-requirements):
+  //   • zero-width: U+200B ZWSP, U+200C ZWNJ, U+200D ZWJ, U+2060 word-joiner,
+  //     U+FEFF BOM/ZWNBSP
+  //   • bidi controls (Trojan-Source): U+202A–U+202E (LRE/RLE/PDF/LRO/RLO),
+  //     U+2066–U+2069 (LRI/RLI/FSI/PDI)
+  //   • other invisibles: U+00AD soft hyphen, U+061C Arabic letter mark,
+  //     U+180E Mongolian vowel separator
+  // NOT included: ordinary whitespace (space/tab/newline) — those are visible
+  // structure, not a hidden vector, so legitimate prose never false-positives.
+  // Implemented as a Unicode-property + explicit-codepoint class via the
+  // `buildInvisibleUnicodeRe()` helper below (NOT literal invisible chars inline,
+  // which would be unreadable + editor-mangleable). Verified to match exactly the
+  // 17 code points listed above with zero false positives on whitespace / ASCII /
+  // accents / CJK / emoji.
+  {
+    id: 'injection_invisible_unicode',
+    category: 'injection',
+    re: INVISIBLE_UNICODE_RE,
+  },
 ];
 
 const ALL_PATTERNS = [...SECRET_PATTERNS, ...INJECTION_PATTERNS];

package/src/provenance.mjs

@@ -237,3 +237,30 @@ export function readBullet(opts = {}) {
   if (!provenance) return null;
   return { id, text, provenance };
 }
+
+// The template-seed sentinel (Task 183 / D-247): every scaffolded `(example)`
+// placeholder bullet (SOUL/USER/HABITS/LESSONS/machine-paths/overrides) ships
+// with an all-zero content sha1 (`0{40}`) + `at: 2020-01-01T…`. A REAL captured
+// fact always has a real content hash, so the all-zero sha1 is an unambiguous
+// "scaffolding the user never replaced" marker. Shared here (the module that
+// owns bullet provenance) so the indexer and inject-context agree — a seed the
+// inject path already skips must not sneak into the search index either.
+export const SEED_SENTINEL_SHA1 = '0'.repeat(40);
+
+/**
+ * True if a parsed provenance object is a scaffold seed (all-zero sha1).
+ *
+ * NOTE (Task 183 review M1): inject-context.mjs has a BROADER local check —
+ * all-zero-sha1 OR the literal `(P-XXX) (example)` text shape. The two agree on
+ * the load-bearing sha1 sentinel (a real seed always carries both markers), so
+ * they don't diverge in practice. A v0.4.x follow-up may unify them (have
+ * inject import this + layer its text check on top — one sentinel, two
+ * consumers); deliberately NOT done here to avoid churning a working inject
+ * security-path filter right before the v0.4.3 release.
+ *
+ * @param {object|null} provenance  a parseBulletProvenance() result
+ * @returns {boolean}
+ */
+export function isSeedProvenance(provenance) {
+  return !!provenance && provenance.sha1 === SEED_SENTINEL_SHA1;
+}