forge-workflow 0.1.0-beta.3 → 0.1.0-beta.5

package/lib/kernel/sqlite-driver.js

@@ -17,6 +17,7 @@ const { buildMemoryProjectionMigration, memoryFtsDdl } = require('./migrations')
 const { rankForPriorityLabel } = require('./taxonomy-validator');
 const { isLeaseExpired } = require('./lease-enforcer');
 const { CONFLICT_SIGNAL, classifyConflictSignal } = require('./conflict-signal');
+const { normalizeRecallHit } = require('../memory-recall');
 
 const BUILTIN_SQLITE_RUNTIME_ORDER = Object.freeze(['bun:sqlite', 'node:sqlite']);
 let probeCounter = 0;
@@ -800,6 +801,28 @@ function listKernelEventRows(runtime, db, entityType, entityId) {
 	);
 }
 
+// Bulk activity read (Slice C2, additive + read-only) across ALL entities, newest first,
+// for `forge insights`. `since` is an optional ISO cutoff (created_at >= since); `limit`
+// bounds the row count (default 1000). Imported beads interactions live here as
+// `beads.interaction.<kind>` events, so insights derives interaction patterns from this
+// instead of the retired legacy interactions log. Creates/migrates nothing.
+function listRecentKernelEventRows(runtime, db, since, limit) {
+	const params = [];
+	let where = '';
+	if (since) {
+		where = 'WHERE created_at >= ?';
+		params.push(since);
+	}
+	const cap = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.floor(Number(limit)) : 1000;
+	params.push(cap);
+	return allParams(
+		runtime,
+		db,
+		`SELECT * FROM kernel_events ${where} ORDER BY created_at DESC LIMIT ?`,
+		params,
+	);
+}
+
 // Look up the committed event for an idempotency key (the duplicate-replay probe).
 // The broker calls this unconditionally inside a Promise.all even for keyless
 // events, so guard a falsy key up front rather than binding undefined.
@@ -2049,6 +2072,17 @@ function buildMemoryFtsMatch(query) {
 	return tokens.map(token => `"${token}"`).join(' AND ');
 }
 
+// Like buildMemoryFtsMatch but OR-joins the tokens: a natural-language prompt matches a note
+// containing ANY of its keywords, not EVERY one. Used ONLY by the relevance-only SCORED read
+// (the per-turn recall hook) — a raw prompt ("why is my forge push taking so long") token-ANDed
+// required every word in one note and matched nothing (0% recall). Each token is double-quoted
+// for FTS5 safety (tokens may be non-Latin unicode). Returns '' when the query has no tokens.
+function buildMemoryFtsMatchOr(query) {
+	const tokens = String(query ?? '').match(/[\p{L}\p{N}]+/gu);
+	if (!tokens || tokens.length === 0) return '';
+	return tokens.map(token => `"${token}"`).join(' OR ');
+}
+
 // BM25 top-N recall over the kernel_memories_fts index (migration 008). Joins the FTS
 // rowid back to the memory row and orders by bm25 (lower = better match). An empty/tokenless
 // query falls back to recent entries so `recall` never returns a bare full dump.
@@ -2070,6 +2104,105 @@ function searchMemoryRowsRanked(runtime, db, query, limit) {
 	).map(memoryRowToEntry);
 }
 
+// Relevance-ONLY BM25 recall that exposes the raw bm25 score on each entry. The
+// per-turn auto-recall hook needs the score to apply a relevance FLOOR (inject nothing
+// when nothing clears the bar) — ordinal rank can't express "nothing was relevant".
+// Unlike searchMemoryRowsRanked, a no-match (or empty) query returns [] with NO recency
+// fallback: the whole point is to avoid surfacing recent-but-irrelevant notes. bm25()
+// returns more-negative for stronger matches, so rows come back best (lowest) first.
+function confirmedMemorySql(alias) {
+	return `(EXISTS (
+		SELECT 1 FROM json_each(${alias}.tags_json)
+		WHERE lower(json_each.value) = 'trust:confirmed'
+	) OR (${alias}.source_agent = 'forge remember'
+		AND json_type(${alias}.value_json) = 'text'
+		AND NOT EXISTS (
+			SELECT 1 FROM json_each(${alias}.tags_json)
+			WHERE lower(json_each.value) LIKE 'trust:%'
+				OR lower(json_each.value) = 'forge:auto-capture'
+		)))`;
+}
+
+function projectMemoryScopeSql(alias) {
+	return `(${alias}.scope IS NULL OR ${alias}.scope = 'project' OR ${alias}.scope = ?)`;
+}
+
+function suggestedFreshnessCutoff(now) {
+	const timestamp = Date.parse(now || new Date().toISOString());
+	return new Date(timestamp - (7 * 24 * 60 * 60 * 1000)).toISOString();
+}
+
+function searchMemoryRowsRankedScored(runtime, db, query, limit, options = {}) {
+	const capped = Number.isInteger(limit) && limit > 0 ? limit : 20;
+	// keyword-OR (NOT the token-AND of searchMemoryRowsRanked): this relevance-only read backs
+	// the per-turn recall hook, where a natural-language prompt must match on ANY keyword.
+	const match = buildMemoryFtsMatchOr(query);
+	if (!match) {
+		return [];
+	}
+	const projectId = options.projectId;
+	if (typeof projectId !== 'string' || !projectId) return [];
+	const cutoff = suggestedFreshnessCutoff(options.now);
+	const excludeKeys = Array.isArray(options.excludeKeys)
+		? [...new Set(options.excludeKeys.filter(key => typeof key === 'string'))].slice(0, 256)
+		: [];
+	const seenSql = excludeKeys.length > 0
+		? `AND m.key NOT IN (${excludeKeys.map(() => '?').join(', ')})`
+		: '';
+	const confirmed = confirmedMemorySql('m');
+	const supersederConfirmed = confirmedMemorySql('s');
+	// Expand eligible supersession edges once. A correlated json_each scan repeated the
+	// entire memory table for every FTS candidate and dominated the 1,000-row prompt path.
+	// Recall temporarily waits less than the connection default so a real lock cannot outlive
+	// the prompt hook; the finally block restores the caller's normal connection behavior.
+	const previousBusyTimeout = Number(queryOne(runtime, db, 'PRAGMA busy_timeout;').timeout) || 0;
+	const requestedBusyTimeout = Number(options.busyTimeoutMs);
+	const busyTimeout = Number.isFinite(requestedBusyTimeout) && requestedBusyTimeout >= 0
+		? Math.floor(requestedBusyTimeout)
+		: Math.min(previousBusyTimeout, 2_500);
+	if (busyTimeout !== previousBusyTimeout) {
+		execSql(runtime, db, `PRAGMA busy_timeout=${busyTimeout};`);
+	}
+	try {
+		return allParams(
+			runtime,
+			db,
+			`WITH eligible_superseders AS MATERIALIZED (
+				SELECT superseded.value AS memory_key,
+					CASE WHEN ${supersederConfirmed} THEN 1 ELSE 0 END AS is_confirmed
+				FROM kernel_memories s,
+					json_each(COALESCE(s.supersedes_json, '[]')) superseded
+				WHERE ${projectMemoryScopeSql('s')}
+				AND (${supersederConfirmed} OR s.updated_at >= ?)
+			)
+			SELECT m.*, bm25(kernel_memories_fts) AS __score FROM kernel_memories m
+			JOIN kernel_memories_fts ON kernel_memories_fts.rowid = m.rowid
+			WHERE kernel_memories_fts MATCH ?
+			AND ${projectMemoryScopeSql('m')}
+			AND (${confirmed} OR m.updated_at >= ?)
+			${seenSql}
+			AND NOT EXISTS (
+				SELECT 1
+				FROM eligible_superseders superseder
+				WHERE superseder.memory_key = m.key
+				AND (superseder.is_confirmed = 1 OR NOT ${confirmed})
+			)
+			ORDER BY bm25(kernel_memories_fts),
+				CASE WHEN ${confirmed} THEN 0 ELSE 1 END,
+				m.source_agent ASC, m.updated_at DESC, m.key ASC
+			LIMIT ?`,
+			[projectId, cutoff, match, projectId, cutoff, ...excludeKeys, capped],
+		).map(row => normalizeRecallHit(
+			{ ...memoryRowToEntry(row), score: row.__score },
+			projectId,
+		));
+	} finally {
+		if (busyTimeout !== previousBusyTimeout) {
+			execSql(runtime, db, `PRAGMA busy_timeout=${previousBusyTimeout};`);
+		}
+	}
+}
+
 function closeDatabase(db) {
 	if (db && typeof db.close === 'function') {
 		db.close();
@@ -2085,12 +2218,17 @@ function createDriver(runtime, configuredDatabasePath) {
 	// synchronous project-memory facade writes WITHOUT first running migrations. Lazily
 	// ensure the table (idempotent CREATE IF NOT EXISTS, rendered from the same migration)
 	// plus a busy_timeout for the second connection the issue backend may hold open.
-	function ensureMemorySchema(database) {
+	function ensureMemorySchema(database, busyTimeoutMs) {
 		if (memorySchemaEnsured) return;
-		execSql(runtime, database, 'PRAGMA busy_timeout=5000;');
-		for (const statement of buildMemoryProjectionMigration().apply) {
-			execSql(runtime, database, statement);
-		}
+		const requestedBusyTimeout = Number(busyTimeoutMs);
+		const busyTimeout = Number.isFinite(requestedBusyTimeout) && requestedBusyTimeout >= 0
+			? Math.floor(requestedBusyTimeout)
+			: 5_000;
+		execSql(runtime, database, `PRAGMA busy_timeout=${busyTimeout};`);
+		try {
+			for (const statement of buildMemoryProjectionMigration().apply) {
+				execSql(runtime, database, statement);
+			}
 		// FTS5 recall index (migration 008): create the virtual table + sync triggers
 		// idempotently so a synchronous memory write stays indexed without a prior
 		// broker.initialize(). When the index is NEWLY created, rebuild once to backfill any
@@ -2101,20 +2239,25 @@ function createDriver(runtime, configuredDatabasePath) {
 		// Staleness is detected by TABLE EXISTENCE (sqlite_master), never by count(*): on an
 		// external-content FTS5 table `count(*)` returns the CONTENT row count, not the
 		// indexed-doc count, so it can never reveal an un-backfilled index.
-		const ftsDdl = memoryFtsDdl();
-		const ftsExisted = Number(queryOne(
-			runtime,
-			database,
-			"SELECT count(*) AS count FROM sqlite_master WHERE type = 'table' AND name = 'kernel_memories_fts'",
-		).count) > 0;
-		execSql(runtime, database, ftsDdl.create);
-		for (const trigger of ftsDdl.triggers) {
-			execSql(runtime, database, trigger);
-		}
-		if (!ftsExisted) {
-			execSql(runtime, database, ftsDdl.rebuild);
+			const ftsDdl = memoryFtsDdl();
+			const ftsExisted = Number(queryOne(
+				runtime,
+				database,
+				"SELECT count(*) AS count FROM sqlite_master WHERE type = 'table' AND name = 'kernel_memories_fts'",
+			).count) > 0;
+			execSql(runtime, database, ftsDdl.create);
+			for (const trigger of ftsDdl.triggers) {
+				execSql(runtime, database, trigger);
+			}
+			if (!ftsExisted) {
+				execSql(runtime, database, ftsDdl.rebuild);
+			}
+			memorySchemaEnsured = true;
+		} finally {
+			if (busyTimeout !== 5_000) {
+				execSql(runtime, database, 'PRAGMA busy_timeout=5000;');
+			}
 		}
-		memorySchemaEnsured = true;
 	}
 
 	function resolveDatabasePath(config) {
@@ -2181,6 +2324,124 @@ function createDriver(runtime, configuredDatabasePath) {
 				[`${escaped}%`, limit],
 			);
 		},
+		// Open PRs under shepherd for one repo (autonomous-shepherd design §3.4): the
+		// reconciler's "open PRs in this repo" read, keyed by git_common_dir so every
+		// worktree shares one view. Parameterized (git_common_dir is a filesystem path —
+		// never interpolate it), covered by idx_pr_common_dir_state_repo_number. Ordered so
+		// the result is deterministic. `context` is part of the broker contract but unused
+		// by this direct SELECT (prefixed `_` for eslint no-unused-vars).
+		async listOpenPrs(gitCommonDir, _context = {}, config = {}) {
+			return allParams(
+				runtime, getDatabase(config),
+				"SELECT * FROM kernel_pr WHERE git_common_dir = ? AND state = 'open' ORDER BY repo ASC, number ASC",
+				[gitCommonDir],
+			);
+		},
+		// --- kernel_pr WRITE path (autonomous-shepherd design §5a). pr rows are DERIVED
+		// reconcile state (reconstructable from GitHub), not audit-critical issue authority,
+		// so they take a DIRECT idempotent upsert — NOT the event-sourced guarded path
+		// (applyAcceptedIssueMutation). All target the physical `kernel_pr` table (matching
+		// the listOpenPrs read) and are parameterized (git_common_dir/branch/head_sha are
+		// externally-influenced values — never interpolate). `context` is part of the broker
+		// contract but unused by these direct writes (prefixed `_` for eslint no-unused-vars).
+		//
+		// Register/refresh a PR row keyed by (git_common_dir, repo, number). Idempotent via
+		// ON CONFLICT on the unique idx_pr_common_dir_repo_number: a re-upsert updates the
+		// mutable columns and coalesces soft links (a later null never clobbers an existing
+		// issue_id/worktree_id). registered_at is set on INSERT only; state defaults 'open'.
+		async upsertPr(row, _context = {}, config = {}) {
+			const id = row.id || randomUUID();
+			const registeredAt = row.registered_at || new Date().toISOString();
+			const state = row.state || 'open';
+			runParams(
+				runtime, getDatabase(config),
+				`INSERT INTO kernel_pr
+					(id, git_common_dir, repo, number, issue_id, worktree_id, branch, head_sha, journal_ptr, state, registered_at)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+				 ON CONFLICT(git_common_dir, repo, number) DO UPDATE SET
+					head_sha = excluded.head_sha,
+					branch = excluded.branch,
+					issue_id = coalesce(excluded.issue_id, kernel_pr.issue_id),
+					worktree_id = coalesce(excluded.worktree_id, kernel_pr.worktree_id),
+					-- journal_ptr is a soft link: coalesce it (like issue_id/worktree_id) so a
+					-- head-only refresh that omits journalPtr never severs the ledger↔journal
+					-- link with NULL. (Codex review, PR #426.)
+					journal_ptr = coalesce(excluded.journal_ptr, kernel_pr.journal_ptr),
+					-- REOPEN semantics: upsertPr is only ever called for PRs GitHub reports as
+					-- OPEN, so re-registering a previously retired row (a reopened PR) must flip
+					-- it back to open and clear retired_at — else listOpenPrs (state='open') would
+					-- keep the reopened PR invisible forever. (Codex review, PR #426.)
+					state = 'open',
+					retired_at = NULL,
+					-- A new commit INVALIDATES the prior verdict: when the head advances to a
+					-- different non-null sha, clear verdict/source/at so a verdict computed
+					-- against the OLD head is never presented as fresh for the new head (and the
+					-- freshest-head guard in updatePrVerdict keeps intact evidence). IS NOT is the
+					-- null-safe distinctness test; a headless refresh (excluded.head_sha NULL)
+					-- never clears. (Codex review, PR #426.)
+					verdict = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict END,
+					verdict_source = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict_source END,
+					verdict_at = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict_at END`,
+				[
+					id,
+					row.git_common_dir,
+					row.repo,
+					row.number,
+					row.issue_id ?? null,
+					row.worktree_id ?? null,
+					row.branch ?? null,
+					row.head_sha ?? null,
+					row.journal_ptr ?? null,
+					state,
+					registeredAt,
+				],
+			);
+			return { ok: true, id };
+		},
+		// The ONE verdict authority WRITE (design §1.2 rule 2) — FRESHEST-HEAD-SHA
+		// PRECEDENCE enforced in the WHERE so a verdict computed against a SUPERSEDED head is
+		// DISCARDED, not written (kills stale 9d35c14b at the write). A non-local (Actions
+		// backstop) write lands only when its head_sha matches the row's current head (or the
+		// row has none yet); a `local` verdict is computed live against the current head and
+		// is always authoritative, so it bypasses the head match.
+		async updatePrVerdict(key, patch = {}, _context = {}, config = {}) {
+			const headSha = patch.head_sha ?? null;
+			const source = patch.verdict_source ?? null;
+			runParams(
+				runtime, getDatabase(config),
+				`UPDATE kernel_pr SET verdict = ?, verdict_source = ?, verdict_at = ?, head_sha = ?
+				 WHERE git_common_dir = ? AND repo = ? AND number = ?
+					AND (head_sha IS NULL OR head_sha = ? OR ? = 'local')`,
+				[
+					patch.verdict ?? null,
+					source,
+					patch.verdict_at ?? null,
+					headSha,
+					key.git_common_dir,
+					key.repo,
+					key.number,
+					headSha,
+					source,
+				],
+			);
+			return { ok: true };
+		},
+		// Retire a PR row (merged/closed): flip state + stamp retired_at so it drops out of
+		// the open-PR read while the reconcile history is retained.
+		async retirePr(key, patch = {}, _context = {}, config = {}) {
+			runParams(
+				runtime, getDatabase(config),
+				'UPDATE kernel_pr SET state = ?, retired_at = ? WHERE git_common_dir = ? AND repo = ? AND number = ?',
+				[
+					patch.state ?? 'closed',
+					patch.retired_at ?? new Date().toISOString(),
+					key.git_common_dir,
+					key.repo,
+					key.number,
+				],
+			);
+			return { ok: true };
+		},
 		// --- Event-store primitives (Wave 2) — composed by broker.runGuardedEvent.
 		// `context` is part of the broker contract but unused by these direct SQL
 		// reads/writes (prefixed `_` for eslint no-unused-vars).
@@ -2193,6 +2454,11 @@ function createDriver(runtime, configuredDatabasePath) {
 		async listKernelEvents(entityType, entityId, _context = {}, config = {}) {
 			return listKernelEventRows(runtime, getDatabase(config), entityType, entityId);
 		},
+		// Additive bulk read for `forge insights` (Slice C2). Read-only; NOT part of the
+		// GUARDED_DRIVER_METHODS write-path contract, so existing driver stubs stay valid.
+		async listRecentKernelEvents({ since = null, limit = null } = {}, _context = {}, config = {}) {
+			return listRecentKernelEventRows(runtime, getDatabase(config), since, limit);
+		},
 		async loadKernelEventByIdempotencyKey(idempotencyKey, _context = {}, config = {}) {
 			return loadKernelEventByIdempotencyKeyRow(runtime, getDatabase(config), idempotencyKey);
 		},
@@ -2313,6 +2579,14 @@ function createDriver(runtime, configuredDatabasePath) {
 			ensureMemorySchema(database);
 			return searchMemoryRowsRanked(runtime, database, query, limit);
 		},
+		// Relevance-only BM25 recall that also returns the raw bm25 `score` per entry, so a
+		// caller can apply a relevance floor. A no-match/empty query returns [] (no recency
+		// fallback). Used by the per-turn memory-recall hook.
+		searchMemoriesRankedScored(query, limit, config = {}) {
+			const database = getDatabase(config);
+			ensureMemorySchema(database, config.busyTimeoutMs);
+			return searchMemoryRowsRankedScored(runtime, database, query, limit, config);
+		},
 		// The newest `limit` entries (default recall with no query). `options.agents` scopes
 		// the read to a source_agent allow-list (e.g. human `remember` notes only).
 		recentMemories(limit, options = {}, config = {}) {

package/lib/lefthook-wiring.js

@@ -55,6 +55,20 @@ pre-push:
       run: npm test --if-present
 `;
 
+// The same config MINUS the TDD pre-commit job, written when the project already has its own
+// pre-commit TDD/coupling gate (kernel 5b425a85 / 2699b234). Stacking a second gate on the same
+// commit is the reported bug, so Forge defers on pre-commit but still wires pre-push.
+const FORGE_USER_LEFTHOOK_YML_NO_TDD = `# Forge git hooks — installed by \`forge setup\` / \`forge init\`.
+# Your project already has its own pre-commit TDD/coupling gate, so Forge did NOT add a second
+# one here. To use Forge's gate instead, remove yours and run: forge gate enable rail.tdd_intent
+# Edit freely to add your own checks — Forge only replaces a fully-commented stub.
+
+pre-push:
+  commands:
+    tests:
+      run: npm test --if-present
+`;
+
 /**
  * A fresh `lefthook install` (run by lefthook's own npm postinstall) drops a stock
  * EXAMPLE lefthook.yml with every hook commented out. That disposable stub used to
@@ -221,10 +235,13 @@ npm test --if-present || exit 1
  * `skipped`) rather than destroyed.
  *
  * @param {string} projectRoot - Absolute path to the project root.
+ * @param {{ skipHooks?: string[] }} [options] - Hook names to leave alone entirely. `forge setup`
+ *   passes `['pre-commit']` when the project already has its own pre-commit TDD/coupling gate,
+ *   so Forge defers instead of stacking a second one (kernel 5b425a85 / 2699b234).
  * @returns {{ installed: boolean, method?: string, hooksDir?: string,
  *   written?: string[], skipped?: string[], reason?: string }}
  */
-function installNativeGitHooks(projectRoot) {
+function installNativeGitHooks(projectRoot, options = {}) {
   const hooksDir = resolveGitHooksDir(projectRoot);
   if (!hooksDir) {
     return { installed: false, reason: 'not-a-git-repo' };
@@ -235,9 +252,11 @@ function installNativeGitHooks(projectRoot) {
     return { installed: false, reason: `hooks-dir-unwritable: ${error.message}` };
   }
 
+  const skipHooks = new Set(Array.isArray(options.skipHooks) ? options.skipHooks : []);
   const written = [];
   const skipped = [];
   for (const [name, body] of Object.entries(NATIVE_HOOK_BODIES)) {
+    if (skipHooks.has(name)) continue;
     const outcome = writeNativeHook(path.join(hooksDir, name), body);
     (outcome === 'written' ? written : skipped).push(name);
   }
@@ -406,6 +425,7 @@ function verifyHooksActive(projectRoot) {
 module.exports = {
   FORGE_NATIVE_HOOK_SENTINEL,
   FORGE_USER_LEFTHOOK_YML,
+  FORGE_USER_LEFTHOOK_YML_NO_TDD,
   forgeShouldWriteLefthookConfig,
   resolveGitHooksDir,
   installNativeGitHooks,

package/lib/memory/router.js

@@ -242,6 +242,21 @@ function legacyJsonlPath(projectRoot) {
   return path.join(projectRoot, ...LEGACY_JSONL_RELATIVE);
 }
 
+function legacyTags(parsed) {
+  const tags = Array.isArray(parsed.tags)
+    ? parsed.tags.filter(tag => typeof tag === 'string')
+    : [];
+  if (
+    typeof parsed.type === 'string'
+    && /^[a-z0-9][a-z0-9-]{0,63}$/i.test(parsed.type)
+    && !tags.some(tag => tag.startsWith('type:'))
+  ) {
+    tags.push(`type:${parsed.type.toLowerCase()}`);
+  }
+  if (!tags.some(tag => tag.startsWith('trust:'))) tags.push('trust:suggested');
+  return tags;
+}
+
 // A STABLE key for a legacy record that lacks an `id`, derived from its content — so a
 // re-run (or a failed rename) upserts the same row instead of double-inserting under a
 // fresh random UUID.
@@ -292,7 +307,7 @@ function migrateJsonlNotesOnce(projectRoot, options = {}) {
       key: typeof parsed.id === 'string' && parsed.id ? parsed.id : legacyContentKey(parsed),
       value: parsed.note,
       sourceAgent: IMPORT_SOURCE_AGENT,
-      tags: Array.isArray(parsed.tags) ? parsed.tags.filter(tag => typeof tag === 'string') : [],
+      tags: legacyTags(parsed),
     };
     if (typeof parsed.timestamp === 'string' && parsed.timestamp && !Number.isNaN(Date.parse(parsed.timestamp))) {
       entry.timestamp = parsed.timestamp;

package/lib/memory-digest.js

@@ -22,6 +22,7 @@
 const { applyBudget, buildSection, estimateTokens } = require('./orientation');
 const { fenceUntrusted } = require('./untrusted-content');
 const { collectInbox, inboxSection } = require('./inbox');
+const { memoryTrustStatus } = require('./memory-recall');
 
 const DEFAULT_DIGEST_BUDGET_TOKENS = 400;
 const DEFAULT_NOTE_LIMIT = 5;
@@ -103,7 +104,13 @@ async function collectDigestData(projectRoot, opts = {}) {
 /** `- [date ]note` for a recall note. */
 function formatNoteLine(note) {
   const date = typeof note.timestamp === 'string' && note.timestamp ? `${note.timestamp.slice(0, 10)} ` : '';
-  return `- ${date}${note.note}`;
+  const trust = memoryTrustStatus({
+    tags: note.tags,
+    sourceAgent: note.sourceAgent,
+    value: note.machine ? {} : note.note,
+  });
+  const sourceAgent = note.sourceAgent || 'unknown';
+  return `- [source=${sourceAgent} trust=${trust} updated=${date.trim() || 'unknown'}] ${note.note}`;
 }
 
 /** `- [label] title` for an issue row (title/id defensively resolved). */
@@ -112,18 +119,39 @@ function formatIssueLine(label, issue) {
   return `- [${label}] ${title}`;
 }
 
-/** Build the notes section, or null when there are no notes. */
-function notesSection(notes) {
-  if (!notes.length) return null;
-  return buildSection({
-    id: 'digest_notes',
-    title: 'Remembered notes',
-    content: notes.map(formatNoteLine).join('\n'),
-    priority: 10,
-    preserve: false,
-    // Untrusted: a planted note is DATA, not instructions. Fenced after truncation.
-    untrustedSource: 'memory',
-  });
+/** Build separate confirmed/suggested note sections, skipping entries too large to fit. */
+function notesSections(notes, budgetTokens) {
+  const eligible = notes
+    .map(note => ({ note, line: formatNoteLine(note) }))
+    .filter(entry => estimateTokens(entry.line) <= budgetTokens);
+  const groups = [
+    { id: 'digest_notes', title: 'Confirmed memory', trust: 'confirmed', priority: 10 },
+    {
+      id: 'digest_suggested_memory',
+      title: 'Suggested memory — verify before relying',
+      trust: 'suggested',
+      priority: 11,
+    },
+  ];
+  return groups.map(group => {
+    const content = eligible
+      .filter(({ note }) => memoryTrustStatus({
+        tags: note.tags,
+        sourceAgent: note.sourceAgent,
+        value: note.machine ? {} : note.note,
+      }) === group.trust)
+      .map(entry => entry.line)
+      .join('\n');
+    if (!content) return null;
+    return buildSection({
+      id: group.id,
+      title: group.title,
+      content,
+      priority: group.priority,
+      preserve: false,
+      untrustedSource: 'memory',
+    });
+  }).filter(Boolean);
 }
 
 /**
@@ -161,13 +189,17 @@ function buildMemoryDigest(data = {}, options = {}) {
   const ready = Array.isArray(data.ready) ? data.ready : [];
   const claimed = Array.isArray(data.claimed) ? data.claimed : [];
   const inbox = Array.isArray(data.inbox) ? data.inbox : [];
+  const budgetTokens = options.budgetTokens || DEFAULT_DIGEST_BUDGET_TOKENS;
 
   // Inbox (priority 5) is a THIRD section beside notes + issues; a fresh human directive
   // outranks stale notes (10) and the agent's own issue list (20) under budget pressure.
-  const sections = [inboxSection(inbox), notesSection(notes), issuesSection(ready, claimed)].filter(Boolean);
+  const sections = [
+    inboxSection(inbox),
+    ...notesSections(notes, budgetTokens),
+    issuesSection(ready, claimed),
+  ].filter(Boolean);
   if (!sections.length) return { text: '', empty: true, tokens: 0 };
 
-  const budgetTokens = options.budgetTokens || DEFAULT_DIGEST_BUDGET_TOKENS;
   const budgeted = applyBudget(sections, budgetTokens);
   const body = budgeted.sections
     .filter(section => section.content)