@aligndottech/cli 0.48.0 → 0.50.0

package/dist/lib/local-gateway-client.js

@@ -1,111 +1,25 @@
-import { createLocalDb, normaliseDecidedAt } from './local-db.js';
+import { createLocalDb, identifyingSourceUrl, normaliseDecidedAt } from './local-db.js';
 import { deriveDeciderKind } from './decider-kind.js';
+import { provenanceOf } from './local-provenance.js';
 import { currentRepoIdentity, repoFromSourceUrl } from './repo-identity.js';
 import { cosineSimilarity, EMBEDDING_MODEL_ID, getEmbedding } from './local-embeddings.js';
 import { classifyRelationship } from './local-relationship-classifier.js';
-import { hasConfiguredProvider, noProviderHintInline, RECOMMENDED_OLLAMA_PULL } from './local-llm.js';
+import { noProviderHintInline, RECOMMENDED_OLLAMA_PULL } from './local-llm.js';
 import { repositoryOf } from './decision-links.js';
 import { localCitationFor } from './commit-cite.js';
 import { extractRefs, refIdentityFor } from './decision-refs.js';
 import { contentWordQuery } from './search-query.js';
-/**
- * Cosine floor for linking two decisions as related on ingest.
- *
- * Named CONFLICT_THRESHOLD until ALI-503, which was the same category error as the code
- * it governed: the value decides similarity, and similarity is not opposition. The
- * classifier prompt in local-relationship-classifier.ts says so directly - "high textual
- * similarity alone is NOT a conflict" - and the link written here is `relates` because an
- * embedding cannot tell agreement from opposition. Only a classifier reading both can, and
- * its verdict is never persisted as a link.
- */
-export const SIMILARITY_THRESHOLD = 0.65;
-/**
- * Relevance floor for align_ask / align_search.
- *
- * Was an inline 0.1, the only unnamed threshold in this file and less than a quarter of
- * its neighbours. It let align_ask answer "what happens when the brain service is down"
- * with two unrelated decisions at 0.18 and 0.14 - noise the agent had to recognise by
- * reading the decimals itself, and an audience cannot.
- *
- * 0.25 matches the gateway's own /decisions/smart-search floor, so the same question gets
- * the same relevance bar in local and cloud mode. Lower than the 0.45 used for relatedness
- * on purpose: search is a human asking a natural-language question, where a looser match is
- * still worth showing, while relatedness is machinery acting on its own.
- *
- * An honest empty result is the point. "The graph has nothing on this" is a better answer
- * than two wrong decisions, because the caller can act on it.
- */
-export const SEARCH_THRESHOLD = 0.25;
-/**
- * Candidate floor for ADJUDICATION - the path that then pays an LLM per candidate.
- *
- * Deliberately higher than the retrieval floor below, because this surface is expensive in
- * three ways the hook is not: up to 5 sequential calls to the user's own provider, ~11s of
- * latency, and an exit code. A keyless CI runner that gets `no-context` today exits 0; the
- * moment retrieval finds anything it gets `unknown` and exits 2. And the classifier cannot
- * reject a candidate - its vocabulary is ten positive relations with no "unrelated" - so a
- * loose candidate that reaches it is reported rather than filtered.
- *
- * Deliberately NOT recalibrated with the retrieval floor. Measured on the corpus, 0.30 would
- * recover four more related pairs here too, and that trade is a separate decision with a
- * separate blast radius (see relatedness-calibration.test.ts).
- */
-export const RELATES_THRESHOLD = 0.45;
-/**
- * Candidate floor for RETRIEVAL ONLY (`depth: 'related'`, the agent editor hook).
- *
- * Measured, not chosen. Against fixtures/relatedness-corpus.json: 0.45 recovered 3 of 8 related
- * pairs, 0.30 recovers 7 of 8, and neither admits a single unrelated pair. 0.25 scores the same
- * 7 of 8, so the tie-break is margin over the worst false positive (0.2051): 0.30 clears it by
- * 0.095 against 0.25's 0.045.
- *
- * 0.30 is also where this constant sat until commit 0cbef08 raised it to 0.45 inside a rename,
- * unmentioned and unmeasured. So this is a revert with evidence attached rather than a new
- * guess, and the evidence is a test that fails if the corpus stops supporting it.
- *
- * Safe to be looser here precisely because this path is cheap and honest: it returns above
- * Stage 2, so it makes no provider call, and what the hook prints declines to assert anything
- * ("related by content search and have NOT been adjudicated"). That is the same posture as
- * `align search`, which has run at 0.25 all along - as has MCP `align_get_related_decisions`.
- */
-export const RETRIEVAL_RELATES_THRESHOLD = 0.3;
-// ALI-785: the ABSOLUTE floor above is unreachable for cross-register pairs on
-// MiniLM-L6 - measured on a 403-decision six-source corpus, near-duplicates score
-// ~0.95, genuine cross-tool paraphrases 0.45-0.62, background noise 0.28-0.40, and
-// 0 of 1,729 links crossed a platform. So linking also takes each item's top few
-// neighbours RELATIVE to its own ranking, floored where the noise band ends. 0.45 is
-// the adjudication floor the product already uses elsewhere; text-cleaning schemes
-// were lab-tested first and moved nothing (title+cleaned scored 0.274 vs 0.286 raw).
-export const RELATED_TOP_K = 3;
-export const RELATED_FLOOR = RELATES_THRESHOLD;
-/**
- * ALI-1065: the capture-time classification budget. Only the high-confidence tier
- * (score >= SIMILARITY_THRESHOLD) is ever classified - the lower related-only tier stays
- * a plain cosine `relates` edge, because typing a merely-related pair is exactly the
- * manufactured-detection failure ALI-503 removed from the conflict counters.
- *
- * Capped at 3 regardless of how many candidates clear the high-confidence bar, and skipped
- * entirely (0 calls) with no provider configured - see ingestOne. Worst case: 3 classifier
- * calls per capture, each a single LLM round trip. Typical capture (0-1 near-duplicates)
- * costs 0-1 calls.
- */
-export const CAPTURE_CLASSIFY_TOP_K = 3;
-// Below this similarity between a decision and new content, the content is
-// considered to have drifted from the decision.
-export const DRIFT_THRESHOLD = 0.5;
-/**
- * ALI-831: the provenance every decision payload carries, in wire spelling, so an agent
- * reading this server can tell a claim from a rule. `ratified` is a boolean beside the
- * stamp rather than instead of it: a consumer branches on the boolean and cites the stamp.
- * A NULL column (a row from before the column existed) reads 'unknown', never a guess.
- */
-function provenanceOf(row) {
-    return {
-        decider_kind: row.deciderKind ?? 'unknown',
-        ratified: row.ratifiedAt !== null,
-        ...(row.ratifiedAt ? { ratified_at: row.ratifiedAt, ratified_by: row.ratifiedBy } : {}),
-    };
-}
+import { linkPass } from './local-link-pass.js';
+import { EmbeddingMatrix, MATRIX_MAX_ROWS } from './similarity/embedding-matrix.js';
+import { captureFieldsForUrl, ingestStep } from './local-ingest.js';
+import { annotatePairs, anyJudgements, reviewConflicts } from './curation/guardrail.js';
+import { defaultJudge } from './curation/judge.js';
+import { bannerFor, checkNotes, emptyCheck, offeredFiles, splitRetrieved } from './curation/check-marks.js';
+import { notADecisionMarks } from './curation/judgements-db.js';
+import { contextKeyFor, filesFromDiff } from './curation/mark.js';
+import { DRIFT_THRESHOLD, RELATED_FLOOR, RELATED_TOP_K, RELATES_THRESHOLD, RETRIEVAL_RELATES_THRESHOLD, SEARCH_THRESHOLD, SIMILARITY_THRESHOLD, } from './local-thresholds.js';
+export { DRIFT_THRESHOLD, RELATED_FLOOR, RELATED_TOP_K, RELATES_THRESHOLD, RETRIEVAL_RELATES_THRESHOLD, SEARCH_THRESHOLD, SIMILARITY_THRESHOLD, };
+export { CAPTURE_CLASSIFY_TOP_K } from './local-ingest.js';
 export function createLocalGatewayClient(dbPath, clientOpts = {}) {
     const db = createLocalDb(dbPath);
     // Memoized: every retrieval call in one command invocation (a single `align ask`, one
@@ -120,6 +34,14 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
         }
         return cachedCurrentRepo;
     }
+    /** LM: whose marks apply. Resolved only when the file holds any judgement, so a graph nobody marked never touches config. */
+    let cachedJudgeId;
+    async function activeJudge() {
+        if (!anyJudgements(dbPath))
+            return undefined;
+        cachedJudgeId ??= clientOpts.judgeId ?? (await defaultJudge()).judgeId;
+        return cachedJudgeId;
+    }
     /**
      * Resolves a `--repo <name>` argument against what actually exists, so a user can type
      * the short repo name ("align-cli") or "owner/repo" instead of memorising the full
@@ -266,7 +188,28 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
         }
         return {};
     }
-    async function ingestOne(input, platform, opts = {}) {
+    /** What ranks a new item against the graph. Normally the in-memory matrix of every stored
+     *  embedding, read from SQLite on first use and kept for the run (`session`) so N items read
+     *  the table once. A kept matrix is trusted only while nothing under it moved: rowSetEpoch
+     *  (this connection deleted or replaced rows, whichever code path did it) and dataVersion
+     *  (ANOTHER connection committed) must both match what it was built at, else it is rebuilt.
+     *  Above the row cap there is no matrix and each item streams the table, as before.
+     *  Model-filtered exactly as findSimilar is: a stale-model vector must not be scored. */
+    function rankerFor(session) {
+        const epoch = db.rowSetEpoch();
+        const dataVersion = db.dataVersion();
+        if (session.matrix === undefined || session.epoch !== epoch || session.dataVersion !== dataVersion) {
+            session.matrix = undefined;
+            if (db.countEmbeddings() > (clientOpts.matrixMaxRows ?? MATRIX_MAX_ROWS)) {
+                return { topK: (q, k, o) => findSimilar(q, k, o?.threshold ?? 0, o?.excludeId) };
+            }
+            session.matrix = EmbeddingMatrix.fromRows(db.getAllEmbeddings({ model: EMBEDDING_MODEL_ID }));
+            session.epoch = epoch;
+            session.dataVersion = dataVersion;
+        }
+        return session.matrix;
+    }
+    async function ingestOne(input, platform, opts = {}, session = {}) {
         let title = input.slice(0, 80);
         let summary = input;
         let sourceUrl = opts.sourceUrlOverride ?? null;
@@ -275,14 +218,17 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
             try {
                 const url = new URL(input);
                 sourceUrl = url.href;
-                title = url.pathname.split('/').filter(Boolean).pop() ?? url.hostname;
-                summary = `Captured from ${url.hostname}`;
+                ({ title, summary } = captureFieldsForUrl(url));
                 capturedAsUrl = true;
             }
             catch { /* plain text - use as-is */ }
         }
         if (opts.titleOverride)
             title = opts.titleOverride.slice(0, 80);
+        // L2: a capture of a URL whose item a connector already imported adds nothing to it.
+        const heldRow = capturedAsUrl ? db.noteCaptureOfHeldItem(sourceUrl) : null;
+        if (heldRow)
+            return { id: heldRow.id, title: heldRow.title, summary: heldRow.summary, sourceUrl: heldRow.sourceUrl, platform: heldRow.platform, related: [], created: false, changed: false };
         // ALI-792: what the text points at, stored beside the decision. When the whole
         // input IS the URL being captured, there is nothing to point at - and comparing
         // the extracted ref against the WHATWG-normalized href leaks on every
@@ -302,80 +248,78 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
         // refreshed, so this is the only moment the difference is visible. Without it a
         // re-import reports every decision as imported while the graph does not move, which
         // reads as having imported twice (ALI-770).
-        const created = db.findIdBySource(sourceUrl, title) === null;
+        //
         // ALI-829: a Slack thread arriving under a real title replaces the tombstone-titled row
-        // an older fetcher may have written for the same source_url (see local-db.ts).
+        // an older fetcher may have written for the same source_url (see local-db.ts). Removed
+        // BEFORE the lookup: L2 finds a Slack thread by its source_key, which the tombstone shares.
+        //
+        // One normalisation, used by both folds: the tombstone delete and insertDecision's own fold
+        // already trim, and a raw url here made the two disagree about which twin they were looking at.
+        const identity = identifyingSourceUrl(sourceUrl);
         if (platform === 'slack')
-            db.deleteSlackTombstoneTwin(sourceUrl);
+            db.deleteSlackTombstoneTwin(identity);
+        if (opts.keyed)
+            db.foldPendingTwin(identity, title, platform, true);
+        const existingId = db.findIdBySource(sourceUrl, title, platform, opts.keyed);
+        // L3: an items-first arrival over a complete row merges onto the stored discussion; the row stays complete.
+        let pending = opts.detailPending;
+        if (opts.keyed && existingId !== null) {
+            const kept = db.keepProtectedText(existingId, title, summary, opts.detailPending);
+            ({ title, summary } = kept);
+            if (kept.keptDiscussion)
+                pending = false;
+        }
+        const created = existingId === null;
         // ALI-829: the source's own date, normalised once. An unparseable date drops the FIELD,
         // never the item: the summary is the thing the user came for.
         const decidedAt = normaliseDecidedAt(opts.createdAt);
+        // L1/L2: connector imports (classify:false) only - capture re-ranks every time. Only the
+        // missing steps run (Decision 30): nothing for a finished row, the link pass alone for a
+        // row whose ingest died after storing its embedding. Refs stay current and citations INTO
+        // the row resolve either way: both are local and cheap.
+        if (opts.classify === false && existingId !== null) {
+            const step = ingestStep(db.getDecisionById(existingId), { title, summary, platform, repo, decidedAt }, db.getEmbeddingModel(existingId), EMBEDDING_MODEL_ID, db.getEnrichedAt(existingId));
+            const stored = step === 'full' ? null : db.getEmbedding(existingId);
+            if (stored !== null) {
+                db.replaceRefs(existingId, refs);
+                db.resolveRefs(existingId, refIdentityFor(platform, sourceUrl));
+                const related = step === 'relink' ? await linkPass(db, rankerFor(session), existingId, stored, title, summary, opts.classify) : [];
+                if (step === 'relink')
+                    db.markEnriched(existingId);
+                return { id: existingId, title, summary, sourceUrl, platform, related, created: false, changed: false };
+            }
+        }
+        // Embed title + summary so URL captures (whose summary is just "Captured
+        // from <host>") still carry the path-derived title's semantic content. Embedded BEFORE the
+        // row is rewritten: a failed embed then leaves the row (and its enriched_at) as it was,
+        // rather than new text beside the old text's vector.
+        const embedText = title === summary ? summary : `${title}. ${summary}`;
+        const embedding = await getEmbedding(embedText);
         // ALI-831: origin, from the platform - the same rule the cloud applies on insert.
         const deciderKind = deriveDeciderKind(platform);
-        const id = db.insertDecision({ title, summary, sourceUrl, platform, repo, decidedAt, deciderKind });
+        const id = db.insertDecision({ title, summary, sourceUrl, platform, repo, decidedAt, deciderKind, keyed: opts.keyed, detailPending: pending });
         db.replaceRefs(id, refs);
         // ALI-796's payoff: if some earlier decision already cited THIS one (a git commit
         // citing a Jira key before Jira was ever connected), resolve that gap into a real
         // link now that the cited item has arrived. Harmless no-op for platforms with no
         // citable identity (refIdentityFor returns [] for a plain git/slack/cli capture).
         db.resolveRefs(id, refIdentityFor(platform, sourceUrl));
-        // Embed title + summary so URL captures (whose summary is just "Captured
-        // from <host>") still carry the path-derived title's semantic content.
-        const embedText = title === summary ? summary : `${title}. ${summary}`;
-        const embedding = await getEmbedding(embedText);
+        const epochBefore = db.rowSetEpoch();
         db.setEmbedding(id, embedding, EMBEDDING_MODEL_ID);
-        // One ranked pass, two rules united. Absolute (>= SIMILARITY_THRESHOLD, cap 10)
-        // as before, PLUS the top RELATED_TOP_K overall when they clear RELATED_FLOOR -
-        // the cross-tool edges live between those two lines (see RELATED_FLOOR's note).
-        // If the top-K are all absolute matches the relative rule adds nothing, which is
-        // the correct degenerate case rather than a special one.
-        const ranked = await findSimilar(embedding, 10, 0, id);
-        const candidates = ranked.filter((c, i) => c.score >= SIMILARITY_THRESHOLD || (i < RELATED_TOP_K && c.score >= RELATED_FLOOR));
-        // ALI-1065: classify only the high-confidence tier, capped, and only with a provider
-        // configured - hasConfiguredProvider is an env-only check, so this costs nothing when
-        // no key exists (the common case for a fresh clone). chainStopped mirrors
-        // checkAlignment's own short-circuit: once one candidate's classification fails with a
-        // stopped provider, further calls in THIS capture are skipped rather than repeated.
-        const toClassify = hasConfiguredProvider()
-            ? candidates.filter(c => c.score >= SIMILARITY_THRESHOLD).slice(0, CAPTURE_CLASSIFY_TOP_K)
-            : [];
-        const classifyIds = new Set(toClassify.map(c => c.decisionId));
-        const newDecision = { title, summary };
-        let chainStopped = false;
-        for (const c of candidates) {
-            if (classifyIds.has(c.decisionId) && !chainStopped) {
-                // The EXISTING decision is the subject (A); the new capture is the candidate (B) -
-                // "how does B relate to A" reads naturally as "does this new thing supersede/conflict
-                // with what's already there", which is the direction a capture-time check asks in.
-                const existingRow = db.getDecisionById(c.decisionId);
-                const outcome = existingRow
-                    ? await classifyRelationship({ title: existingRow.title, summary: existingRow.summary }, newDecision)
-                    : { ok: false, reason: 'classifier_error' };
-                if (!outcome.ok && outcome.failure?.kind === 'provider_stopped')
-                    chainStopped = true;
-                if (outcome.ok) {
-                    // replaceLink, not insertLink: this upgrades the cosine `relates` edge findSimilar
-                    // would otherwise also write below into a typed one, rather than leaving both on
-                    // the pair (local-db.ts's unique index is per-relation, so both would coexist).
-                    db.replaceLink({
-                        sourceId: id,
-                        targetId: c.decisionId,
-                        relation: outcome.relationship.type,
-                        confidence: outcome.relationship.confidence,
-                    });
-                    continue;
-                }
-                // Falls through to the untyped write below on any classifier failure - a candidate
-                // still worth surfacing as related even when nothing could type it.
-            }
-            // ALI-503: `relates`, not `conflicts_with`. This is a cosine score with no judgement
-            // behind it, and labelling it a conflict made `align local status` and the
-            // align_get_conflicts MCP tool report manufactured findings as detections.
-            db.insertLink({ sourceId: id, targetId: c.decisionId, relation: 'relates', confidence: c.score });
+        // This run's own write: the matrix learns it by append, so the bump setEmbedding makes when
+        // it REPLACES a vector is not a graph that moved under the copy. But only a matrix that was
+        // current before the write may absorb it; one the insert's own fold already outdated is
+        // left alone and rebuilt by rankerFor.
+        if (session.matrix !== undefined && session.epoch === epochBefore) {
+            session.matrix.add(id, embedding);
+            session.epoch = db.rowSetEpoch();
         }
-        return { id, title, summary, sourceUrl, platform, related: candidates, created };
+        const candidates = await linkPass(db, rankerFor(session), id, embedding, title, summary, opts.classify);
+        // L2, Decision 30: the LAST write. Only now is the ingest done.
+        db.markEnriched(id);
+        return { id, title, summary, sourceUrl, platform, related: candidates, created, changed: true };
     }
-    return {
+    const client = {
         /** Release the underlying SQLite handle (required on Windows before deleting the file). */
         close() {
             db.close();
@@ -395,17 +339,20 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                 ...(row ? provenanceOf(row) : {}),
             };
         },
-        async ingestBatch(items) {
+        async ingestBatch(items, opts = {}) {
             const snapshots = [];
+            const session = {};
             for (const item of items) {
                 const r = await ingestOne(item.raw_text, item.platform ?? 'cli', {
                     titleOverride: item.title,
                     sourceUrlOverride: item.source_url ?? null,
                     createdAt: item.created_at,
-                });
+                    classify: opts.classify, keyed: opts.keyed, detailPending: item.detail_pending,
+                }, session);
                 snapshots.push({
                     id: r.id,
                     created: r.created,
+                    changed: r.changed,
                     title: r.title,
                     summary: r.summary,
                     analysis: {
@@ -422,6 +369,39 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
             }
             return { snapshots };
         },
+        /**
+         * L5, Decision 30: finish ingests that never finished (`enriched_at` NULL: every row after the
+         * v7 upgrade, or one that died between its embedding and its link pass). Runs only the
+         * missing step, the way ingestOne does for a connector re-ingest: a row that already holds a
+         * current-model embedding gets the link pass alone (no embed call); one that does not is
+         * re-ingested from its own stored text. A row with no URL and no embedding cannot be
+         * re-ingested without inserting a twin, so it is counted and left. Never classifies.
+         */
+        async relinkUnfinished(rows) {
+            const session = {};
+            const out = { linked: 0, embedded: 0, skipped: 0 };
+            for (const { id, keyed, pending } of rows) {
+                const row = db.getDecisionById(id);
+                if (!row)
+                    continue;
+                const stored = db.getEmbeddingModel(id) === EMBEDDING_MODEL_ID ? db.getEmbedding(id) : null;
+                if (stored !== null) {
+                    await linkPass(db, rankerFor(session), id, stored, row.title, row.summary, false);
+                    db.markEnriched(id);
+                    out.linked += 1;
+                }
+                else if (row.sourceUrl === null) {
+                    out.skipped += 1;
+                }
+                else {
+                    await ingestOne(row.summary, row.platform, { titleOverride: row.title, sourceUrlOverride: row.sourceUrl, createdAt: row.decidedAt ?? undefined, classify: false, keyed,
+                        // The stored flag, passed through: a re-ingest that says nothing resets a row still waiting for its discussion.
+                        detailPending: pending === true }, session);
+                    out.embedded += 1;
+                }
+            }
+            return out;
+        },
         /**
          * ALI-808: the confirm-each session importer's one write path. Ingests exactly like
          * ingestBatch does above (same ingestOne, so platform 'agent-session' derives
@@ -560,7 +540,16 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
             const { dbFilter, effectiveRepo } = await resolveScope(scope);
             const boundedFilter = { ...dbFilter, createdBefore };
             const embedding = await getEmbedding(query);
-            let similar = await findSimilar(embedding, limit, SEARCH_THRESHOLD, undefined, boundedFilter);
+            // LM: decisions this person marked not-a-decision are skipped, so ask for that many extra.
+            const judge = await activeJudge();
+            const hidden = judge ? notADecisionMarks(dbPath, judge) : new Map();
+            const dropNotes = [];
+            const visible = (rows) => {
+                const split = splitRetrieved(rows, hidden, limit, (id) => db.getDecisionById(id)?.title, 'answer');
+                dropNotes.splice(0, dropNotes.length, ...split.notes);
+                return split.kept;
+            };
+            let similar = visible(await findSimilar(embedding, limit + hidden.size, SEARCH_THRESHOLD, undefined, boundedFilter));
             // A natural-language question embeds less densely than its subject does, so on a
             // small graph it can miss a decision that its own content words hit. Retry once,
             // only on an empty result, mirroring the gateway's own keyword-to-semantic
@@ -569,7 +558,7 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
             if (!similar.length) {
                 const reduced = contentWordQuery(query);
                 if (reduced) {
-                    similar = await findSimilar(await getEmbedding(reduced), limit, SEARCH_THRESHOLD, undefined, boundedFilter);
+                    similar = visible(await findSimilar(await getEmbedding(reduced), limit + hidden.size, SEARCH_THRESHOLD, undefined, boundedFilter));
                 }
             }
             const results = similar
@@ -603,7 +592,7 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                 };
             })
                 .filter((d) => d !== null);
-            return { results, count: results.length, strategy: 'semantic', scope: effectiveRepo };
+            return { results, count: results.length, strategy: 'semantic', scope: effectiveRepo, ...(dropNotes.length ? { notes: dropNotes } : {}) };
         },
         async checkAlignment(diff, _context, 
         // 'exhaustive' deliberately collapses into 'full' here: local mode has no gateway
@@ -620,7 +609,10 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
             // the stricter bar. One constant could not serve both.
             const threshold = opts.depth === 'related' ? RETRIEVAL_RELATES_THRESHOLD : RELATES_THRESHOLD;
             const embedding = await getEmbedding(diff);
-            const similar = await findSimilar(embedding, 5, threshold);
+            const judge = await activeJudge();
+            const hidden = judge ? notADecisionMarks(dbPath, judge) : new Map();
+            const retrieved = splitRetrieved(await findSimilar(embedding, 5 + hidden.size, threshold), hidden, 5, (id) => db.getDecisionById(id)?.title);
+            const similar = retrieved.kept;
             const candidates = similar
                 .map(s => {
                 const row = db.getDecisionById(s.decisionId);
@@ -628,7 +620,7 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
             })
                 .filter((d) => d !== null);
             if (!candidates.length) {
-                return { status: 'no-context', confidence: 0, relevant_decisions: [], conflicts: [], message: 'No related decisions found in your local graph.' };
+                return emptyCheck(retrieved);
             }
             // `depth:'related'` means retrieval only, and honouring it matters more here than in the
             // cloud client. The editor hook asks for it to fit a <=10s budget (check.ts), but in
@@ -656,6 +648,7 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                         ...provenanceOf(c),
                     })),
                     conflicts: [],
+                    ...(retrieved.notes.length ? { notes: [...bannerFor(retrieved.agentApplied), ...retrieved.notes] } : {}),
                     message: `Found ${candidates.length} related decision(s) - retrieval only, not adjudicated.`,
                 };
             }
@@ -700,8 +693,13 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                     similarity: c.score,
                 });
             }
-            const relevant_decisions = typed.map(t => ({ id: t.id, title: t.title, summary: t.summary, similarity: t.similarity, url: t.url, ...t.provenance }));
-            const conflicts = typed
+            // LM: a decision a person said was replaced is named as replaced, with its successor.
+            const replacedBy = (id) => {
+                const r = relationFieldsFor(id);
+                return r.status === 'superseded' ? { status: r.status, successor: r.successor } : {};
+            };
+            const relevant_decisions = typed.map(t => ({ id: t.id, title: t.title, summary: t.summary, similarity: t.similarity, url: t.url, ...t.provenance, ...replacedBy(t.id) }));
+            const rawConflicts = typed
                 .filter(t => t.relationship === 'conflicts_with' || t.relationship === 'contradicts')
                 .map(t => ({
                 decision_id: t.id,
@@ -712,6 +710,13 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                 reason: t.reason ?? 'Conflicts with an existing decision in your local graph',
                 severity: (t.confidence >= 0.8 ? 'critical' : 'warning'),
             }));
+            // LM: this person's false-alarm marks hide a hit for exactly this set of files, or annotate it.
+            const files = filesFromDiff(diff);
+            const reviewed = judge ? reviewConflicts(dbPath, judge, rawConflicts, contextKeyFor(files), files) : { conflicts: rawConflicts, notes: [], agentApplied: [] };
+            const conflicts = reviewed.conflicts;
+            // LM: say what a mark changed - a decision left out, a decision a person declared replaced.
+            const allNotes = checkNotes(dbPath, judge, retrieved, relevant_decisions, reviewed, files);
+            const notes = allNotes.length ? { notes: allNotes } : {};
             // ALI-414: a candidate we retrieved but could not classify is exactly the case
             // where we do not know - it could be the conflict. Reporting `aligned` there is
             // a fail-open, and an agent reads `aligned` as permission to proceed. A conflict
@@ -724,6 +729,8 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                     confidence,
                     relevant_decisions,
                     conflicts,
+                    ...notes,
+                    ...(offeredFiles(files) ? { checked_files: files } : {}),
                     message: `This change conflicts with ${conflicts.length} existing decision(s) in your local graph - review before proceeding.`,
                 };
             }
@@ -747,6 +754,7 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                     confidence: 0,
                     relevant_decisions,
                     conflicts: [],
+                    ...notes,
                     message: `Could not check ${relevant_decisions.length} related decision(s) - the relationship classifier did not run. ` +
                         `This is NOT a pass: treat it as unchecked and review these decisions before proceeding.${hint}`,
                 };
@@ -756,6 +764,7 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                 confidence,
                 relevant_decisions,
                 conflicts,
+                ...notes,
                 message: `Found ${relevant_decisions.length} related decision(s) to review.`,
             };
         },
@@ -800,8 +809,10 @@ export function createLocalGatewayClient(dbPath, clientOpts = {}) {
                 ...db.listLinks({ relation: 'conflicts_with' }),
                 ...db.listLinks({ relation: 'contradicts' }),
             ];
-            return { links, conflict_count: links.length };
+            const judge = await activeJudge();
+            return { links: judge ? annotatePairs(dbPath, judge, links) : links, conflict_count: links.length };
         },
     };
+    return client;
 }
 //# sourceMappingURL=local-gateway-client.js.map