Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Write-back contract audit, CHECK-ONLY (t_7c01bb39).
*
* Asserts that the workspace's agent-instruction file(s) carry the
* same-turn atomic-fact memory write gate: a marker-delimited Open Second
* Brain managed block (`hasManagedBlock`/`extractManagedBlock`,
* `src/core/install/managed-block.ts`) whose body states the gate. The
* audit only READS; it never writes, installs or repairs anything.
*
* THE SETTLED MARKER CONTRACT - this section is the input the ambient
* write-back managed block must satisfy wherever it is installed:
*
* 1. Delimiters: the default managed-block markers
* (`DEFAULT_BEGIN_MARKER` / `DEFAULT_END_MARKER`,
* `src/core/install/managed-block.ts`) - exactly one pair, end after
* begin, anything outside preserved byte-for-byte.
* 2. Location: the workspace agent-instruction file(s)
* ({@link AGENT_INSTRUCTION_FILES}, AGENTS.md first, discovery by
* existence over the fixed list, never by pattern).
* 3. Body: a regex/keyword contract, expressed in the marker write-back
* guardrail's own vocabulary so the check and the runtime refuse in
* the same words ({@link WRITEBACK_CONTRACT_REQUIREMENTS}):
* - the `marker_writeback` guardrail flag name verbatim
* (`MARKER_WRITEBACK_GUARDRAIL`, `src/core/brain/marker-writeback.ts`);
* - the same-turn rule (memory is written in the same turn the
* fact is learned);
* - the atomic-fact rule (memory is written as atomic facts).
*
* This module is the checker that defines conformance. The installer
* lives in `src/core/install/instruction-block.ts` (sibling cards
* t_ba41a78a and t_1e952e43) and must keep satisfying this module's
* clauses: it writes exactly {@link CANONICAL_WRITEBACK_BLOCK_BODY},
* the canonical gate-and-usage body self-tested against
* {@link missingWritebackGateClauses}. A file with no block at all is
* still reported as `missing-block` (not installed, graded skipped by
* the readiness probe) while a block that is present but broken is
* `malformed-block` or `missing-clauses` (graded fail).
*
* Read posture: every candidate file is lstat'd first and a symbolic link
* is REFUSED, never followed - the upstream posture is that a reader that
* follows a link has already left the workspace, and no symlink guard
* existed anywhere on this lane before this module (premise report,
* t_7c01bb39). The refusal is written even though the write lane is out
* of scope: a check that silently reads through a link would audit a file
* the agent instruction surface does not contain.
*
* Shadowing (t_00b617b6): the candidates are audited in isolation, but a
* host reads exactly ONE of them - its entry in
* {@link HOST_INSTRUCTION_PRECEDENCE}. A workspace where the file a host
* reads carries no managed block while another candidate carries it is
* shadowed: the operative host never sees the contract no matter how
* conforming the other file is. {@link resolveShadowedInstructionContracts}
* resolves that from the audit rows alone - pure, no I/O, no writes - and
* the doctor-readiness probe grades each triple as a `fail`.
*
* One exception keeps the resolution honest about what a host actually
* sees: a file whose `@` import line names the contract file renders
* it - managed block included - into the surface the host reads. Claude
* Code's memory-import syntax is an `@` at a word boundary followed by a
* path - mid-line and list-item included - Gemini CLI documents the
* `@./file.md` spelling, and a CLAUDE.md that only says `@AGENTS.md`
* beside a conforming AGENTS.md is the common real setup; claiming a
* shadow there fails `o2b doctor --readiness` for a workspace whose
* operative host sees the gate. {@link auditWritebackContractFile}
* therefore records the workspace-relative paths such lines reference
* ({@link referencedImportPaths}, matched over a code-masked view -
* imports inside code spans or fences are not imports - with `~/`,
* absolute and workspace-escaping paths refused), and the resolver skips
* the shadow triple when the preferred file imports a path that resolves
* to the contract file.
*
* Findings are the closed {@link WRITEBACK_CONTRACT_FINDING} vocabulary:
* `conforming`, `malformed-block`, `missing-clauses` (a block is present
* and was measured - pass/fail material), `missing-block` (the file
* exists but the block was never installed - skip material), and
* `absent`, `symlink`, `unreadable` (the file was not measured -
* skip/unknown material; the doctor-readiness probe maps these). Every finding carries a non-empty
* detail naming the file and, when the contract fails, the missing piece.
*/
import { lstatSync, readFileSync } from "node:fs";
import { basename, dirname, join, resolve } from "node:path";
import {
DEFAULT_BEGIN_MARKER,
DEFAULT_END_MARKER,
extractManagedBlock,
hasManagedBlock,
} from "../install/managed-block.ts";
import { MARKER_WRITEBACK_GUARDRAIL } from "./marker-writeback.ts";
import { maskCodeRegions } from "./wikilink.ts";
// ----- Constants ------------------------------------------------------------
/**
* The workspace agent-instruction files this audit reads, in priority
* order, AGENTS.md first. Deliberately the same fixed, short, explicit
* list posture as the vault instruction-file ceiling: discovery is by
* existence over THIS list, not by glob - a pattern-discovered file is a
* second convention, and the contract must not drift per host.
*/
export const AGENT_INSTRUCTION_FILES: ReadonlyArray<string> = Object.freeze([
"AGENTS.md",
"CLAUDE.md",
"GEMINI.md",
]);
/**
* Host family to the ordered agent-instruction files the host reads at a
* workspace root, first existing entry wins per host (t_00b617b6). This is
* the PRECEDENCE table - which file an operative host actually reads - and
* is deliberately a different shape from {@link AGENT_INSTRUCTION_FILES},
* which is the existence-loop list this audit walks. The installer lane
* (sibling card t_af5e252f) is expected to share this definition, which is
* why each value is an ordered list even where the repo today names only
* one file per host.
*
* Evidence, entry by entry:
*
* - `claude-code` reads `CLAUDE.md` - REPO-CITED,
* `docs/cross-project-pointer.md:15`.
* - `codex`, `cursor`, `aider` read `AGENTS.md` - REPO-CITED,
* `docs/cross-project-pointer.md:16-17` ("Codex, Cursor, Aider, and
* other tools that follow the `agents.md` convention").
* - `opencode` reads `AGENTS.md` - REPO-CITED,
* `docs/brainstorm/opencode-native-integration/variants.md` ("opencode
* reads AGENTS.md natively").
* - `gemini-cli` reads `GEMINI.md` - NAME-IMPLIED ONLY. No repo document
* states it (the cross-project pointer predates the Gemini entry), and
* upstream `context.fileName` can rename the surface. Recorded as the
* open question the instruction-file-ceiling and removed-tool-sweep
* docblocks carry; the finding vocabulary stays honest because a
* shadow is claimed only from files this tree actually audited.
*
* There is no claude-code INSTALL target (the adapters write MCP configs
* only), so "which host is operative here" cannot be derived from an
* install manifest - detection keys on which candidate files co-exist plus
* this table, never on manifests.
*/
export const HOST_INSTRUCTION_PRECEDENCE = Object.freeze({
"claude-code": Object.freeze(["CLAUDE.md"]),
codex: Object.freeze(["AGENTS.md"]),
cursor: Object.freeze(["AGENTS.md"]),
opencode: Object.freeze(["AGENTS.md"]),
aider: Object.freeze(["AGENTS.md"]),
"gemini-cli": Object.freeze(["GEMINI.md"]),
} as const);
/** Closed union over {@link HOST_INSTRUCTION_PRECEDENCE} keys. */
export type HostInstructionName = keyof typeof HOST_INSTRUCTION_PRECEDENCE;
/**
* Recovery clause an audit carries when the block is missing or broken.
* It names the surface to add and the markers that delimit it; nothing
* here writes it.
*/
export const WRITEBACK_CONTRACT_RECOVERY =
"recovery: add the ambient write-back managed block between the " +
`"${DEFAULT_BEGIN_MARKER}" and "${DEFAULT_END_MARKER}" lines, stating the ` +
`${MARKER_WRITEBACK_GUARDRAIL} same-turn atomic-fact write gate`;
/** One clause of the gate contract: what it is called and how it matches. */
export interface WritebackContractRequirement {
/** Label used verbatim in findings, so the missing piece is named. */
readonly label: string;
/** Keyword/regex contract evaluated against the extracted block body. */
readonly pattern: RegExp;
}
/**
* The same-turn atomic-fact write-gate contract over an extracted managed
* block body. Clause order is reporting order: the guardrail flag first
* because it is the shared-vocabulary clause - the exact token
* `marker-writeback.ts` refuses with - followed by the two rules that
* make the gate a write gate at all.
*/
export const WRITEBACK_CONTRACT_REQUIREMENTS: ReadonlyArray<WritebackContractRequirement> =
Object.freeze([
{
label: `the '${MARKER_WRITEBACK_GUARDRAIL}' guardrail`,
pattern: new RegExp(MARKER_WRITEBACK_GUARDRAIL),
},
{
label: "the same-turn write rule",
pattern: /same[-\s]turn/i,
},
{
label: "the atomic-fact rule",
pattern: /atomic[-\s]fact/i,
},
]);
/**
* The canonical managed-block body the installer writes between the
* settled markers, and the body every audited file is graded against in
* practice: a block installed by `src/core/install/
* instruction-block.ts` carries exactly this text, so a drifted block is
* one that diverged from it.
*
* Content, by contract (t_ba41a78a K2): the same-turn atomic-fact write
* gate - the `marker_writeback` guardrail token verbatim, the same-turn
* rule, the atomic-fact rule - merged with the cross-project-pointer
* usage content (read the active preferences at session start, `brain_feedback`,
* `brain_apply_evidence`, the do-not-dream rule). One body, one block:
* the editor holds exactly one pair per spelling, so the docs' pointer
* block and the write gate must be the same block or they fight.
*
* Static by design. It names tools and commands, never a path (design
* D12), so the body is byte-identical in every vault and a vault move or
* a store-only switch never drifts an installed block. It quotes no vault memory
* content, ever: it is instructions, not memory.
*/
export const CANONICAL_WRITEBACK_BLOCK_BODY: string = [
"## Open Second Brain",
"",
"This project shares an Obsidian-compatible vault with an active",
"observing-memory layer. At session start, read the current preferences",
"with `brain_context` (MCP) or `o2b brain export --format llms-txt` (CLI).",
"",
"Record taste signals via `brain_feedback` (MCP) or `o2b brain feedback`",
"(CLI). After producing a durable artifact, call `brain_apply_evidence`",
"with `result: applied | violated | outdated` for any preference whose",
"`scope` matches.",
"",
"Do not run `o2b brain dream` here: the brain settings name its primary",
"dream-running agent (key `primary_agent`).",
"",
"Memory write gate: apply the marker_writeback guardrail. Record memory",
"as atomic facts in the same turn each fact is learned, never batched.",
].join("\n");
// ----- Types ----------------------------------------------------------------
/** Closed finding vocabulary of one audited instruction file. */
export const WRITEBACK_CONTRACT_FINDING = Object.freeze({
/** Block present, every contract clause present. */
conforming: "conforming",
/** The file exists but carries no managed-block marker at all: not installed. */
missingBlock: "missing-block",
/** A managed-block marker is present but not as one well-formed pair. */
malformedBlock: "malformed-block",
/** A managed block is present but the gate contract is not fully met. */
missingClauses: "missing-clauses",
/** No file at the candidate path: nothing installed. */
absent: "absent",
/** The candidate path is a symbolic link; the read was refused. */
symlink: "symlink",
/** The candidate path exists but could not be read as a file. */
unreadable: "unreadable",
} as const);
/** Closed union over {@link WRITEBACK_CONTRACT_FINDING}. */
export type WritebackContractFinding =
(typeof WRITEBACK_CONTRACT_FINDING)[keyof typeof WRITEBACK_CONTRACT_FINDING];
/** The audit verdict for one candidate instruction file. */
export interface WritebackContractFileAudit {
/** Absolute candidate path that was audited. */
readonly path: string;
readonly finding: WritebackContractFinding;
/** Never empty; names the file and the finding's evidence. */
readonly detail: string;
/** Labels of the unmet contract clauses; empty unless `missing-clauses`. */
readonly missing: ReadonlyArray<string>;
/**
* Workspace-relative import paths the file's `@`-style import lines
* reference, in first-appearance order, deduplicated (see
* {@link referencedImportPaths} for exactly what is matched and what
* is refused). Empty unless the file was actually read: the refused
* findings (`absent`, `symlink`, `unreadable`) measured no content, so
* they claim no imports.
*/
readonly imports: ReadonlyArray<string>;
}
// ----- Pure contract --------------------------------------------------------
/**
* The labels of the gate clauses `blockBody` does not satisfy; empty when
* the body carries the full same-turn atomic-fact write gate. This is the
* whole content contract - a keyword check over the extracted block, not
* a semantic assertion.
*/
export function missingWritebackGateClauses(blockBody: string): ReadonlyArray<string> {
const missing: string[] = [];
for (const requirement of WRITEBACK_CONTRACT_REQUIREMENTS) {
if (!requirement.pattern.test(blockBody)) missing.push(requirement.label);
}
return Object.freeze(missing);
}
// ----- File audit -----------------------------------------------------------
/**
* Audit one candidate instruction file. Reads with an lstat guard: a
* symbolic link is refused (`symlink`), an absent path is the named
* `absent` finding, anything else that cannot be read as a file is
* `unreadable` with the reason. Only an actually-read file gets a
* contract verdict. Never throws for filesystem conditions - refusals
* are findings, by name.
*/
export function auditWritebackContractFile(path: string): WritebackContractFileAudit {
let stat;
try {
stat = lstatSync(path);
} catch (err) {
if ((err as NodeJS.ErrnoException).code === "ENOENT") {
return {
path,
finding: WRITEBACK_CONTRACT_FINDING.absent,
detail: `${path} does not exist - nothing installed is not a contract violation`,
missing: [],
imports: [],
};
}
return {
path,
finding: WRITEBACK_CONTRACT_FINDING.unreadable,
detail: `${path} could not be stat'ed: ${reason(err)}`,
missing: [],
imports: [],
};
}
if (stat.isSymbolicLink()) {
return {
path,
finding: WRITEBACK_CONTRACT_FINDING.symlink,
detail:
`${path} is a symbolic link - the audit refuses to read through symlinks, ` +
"so the contract is unmeasured",
missing: [],
imports: [],
};
}
let content: string;
try {
content = readFileSync(path, "utf8");
} catch (err) {
return {
path,
finding: WRITEBACK_CONTRACT_FINDING.unreadable,
detail: `${path} could not be read: ${reason(err)}`,
missing: [],
imports: [],
};
}
const imports = referencedImportPaths(content);
const body = hasManagedBlock(content) ? extractManagedBlock(content) : null;
if (body === null) {
if (!carriesMarkerLine(content)) {
return {
path,
finding: WRITEBACK_CONTRACT_FINDING.missingBlock,
detail:
`${path} has no Open Second Brain managed block - the ambient write-back ` +
`managed block is not installed, so the write gate is not graded; ` +
WRITEBACK_CONTRACT_RECOVERY,
missing: [],
imports,
};
}
// A marker is there but not as one ordered pair (a lone, repeated or
// reversed marker), or the two helpers disagree on the same bytes:
// a block somebody installed and then broke, which is a file fault.
return {
path,
finding: WRITEBACK_CONTRACT_FINDING.malformedBlock,
detail:
`${path} carries an Open Second Brain managed-block marker but no well-formed ` +
`block - broken same-turn atomic-fact write gate; ${WRITEBACK_CONTRACT_RECOVERY}`,
missing: [],
imports,
};
}
const missing = missingWritebackGateClauses(body);
if (missing.length > 0) {
return {
path,
finding: WRITEBACK_CONTRACT_FINDING.missingClauses,
detail:
`${path} managed block is missing ${missing.join(", ")} - incomplete ` +
`same-turn atomic-fact write gate; ${WRITEBACK_CONTRACT_RECOVERY}`,
missing,
imports,
};
}
return {
path,
finding: WRITEBACK_CONTRACT_FINDING.conforming,
detail:
`${path} carries the managed block and the same-turn atomic-fact write gate ` +
`(${WRITEBACK_CONTRACT_REQUIREMENTS.length} clauses verified)`,
missing: [],
imports,
};
}
/** Whether any line of `content` is a default managed-block marker. */
function carriesMarkerLine(content: string): boolean {
return content
.replace(/\r\n/g, "\n")
.split("\n")
.some((line) => line === DEFAULT_BEGIN_MARKER || line === DEFAULT_END_MARKER);
}
/**
* The workspace-relative import paths `content`'s `@`-style import lines
* reference - the host memory-import shapes this tree implements, matched
* over a code-masked view of the text:
*
* - code regions (inline spans and fenced blocks, `maskCodeRegions`)
* are masked with a length-preserving fill BEFORE matching: no host
* evaluates an import inside code, so a fenced `@AGENTS.md` renders
* as literal text and must record nothing;
* - the `@` must sit at a word boundary but ANYWHERE on the line -
* Claude Code accepts mid-line and list-item imports and Gemini CLI
* documents `@./file.md`, so a line-start-only basename match would
* false-fail the documented spellings; an `@` preceded by a word
* character (email) or another `@` is not an import;
* - what follows is one path-shaped token (`A-Za-z0-9._~/-`, greedy)
* ending at whitespace or end of line - `@AGENTS.md.bak` records
* `AGENTS.md.bak` (never equal to a candidate path), and
* `@docs/AGENTS.md` records `docs/AGENTS.md` (a different workspace
* file than a root candidate);
* - a leading `./` is stripped (`@./AGENTS.md` names the same file as
* `@AGENTS.md`), while `~/...`, absolute paths and any token whose
* normalized form escapes the workspace (`..` past the root) are
* REFUSED outright and record nothing: such an import does not
* render a workspace file, so it excuses nothing - a deliberate,
* documented refusal kept conservative, because a lookalike that
* suppressed a shadow would hide a live gate.
*
* CRLF line endings are normalized before the per-line match. Pure; used
* by {@link auditWritebackContractFile} so the shadow resolver can tell a
* host that renders the contract file through an import from one that
* never sees it (the resolver resolves each recorded token against the
* workspace directory and compares to the contract path).
*/
/** The path-shaped token grammar one `@` import may carry. */
const IMPORT_TOKEN_RE = /(?<![A-Za-z0-9@])@([A-Za-z0-9._~/-]+)(?=\s|$)/g;
export function referencedImportPaths(content: string): ReadonlyArray<string> {
// Length-preserving fill: line structure (and CRLFs) survive intact.
const masked = maskCodeRegions(content, (region) => " ".repeat(region.length));
const found: string[] = [];
for (const line of masked.replace(/\r\n/g, "\n").split("\n")) {
for (const match of line.matchAll(IMPORT_TOKEN_RE)) {
const token = normalizeImportToken(match[1]!);
if (token === null) continue;
if (!found.includes(token)) found.push(token);
}
}
return Object.freeze(found);
}
/**
* Normalize one matched import token, or `null` when the reference is
* refused: leading `./` prefixes are stripped, then any path that leaves
* the workspace - `~`, an absolute path, or more `..` than the token has
* directory depth - is refused (documented; see
* {@link referencedImportPaths}). Pure string math, no I/O.
*/
function normalizeImportToken(token: string): string | null {
const stripped = token.replace(/^(?:\.\/)+/, "");
if (stripped.length === 0) return null;
if (stripped.startsWith("~") || stripped.startsWith("/")) return null;
let depth = 0;
for (const segment of stripped.split("/")) {
if (segment === "..") {
depth -= 1;
if (depth < 0) return null; // escapes the workspace
} else if (segment !== "." && segment !== "") {
depth += 1;
}
}
return stripped;
}
// ----- Workspace audit ------------------------------------------------------
/**
* The absolute candidate paths for `workspace`, in priority order. Pure
* path computation: existence is decided by the audit, not here.
*/
export function locateAgentInstructionFiles(workspace: string): ReadonlyArray<string> {
return Object.freeze(AGENT_INSTRUCTION_FILES.map((name) => join(workspace, name)));
}
/**
* Audit every workspace agent-instruction candidate, in priority order.
* One row per candidate, always - an absent candidate is a named finding,
* not a gap in the table.
*/
export function auditWorkspaceWritebackContract(
workspace: string,
): ReadonlyArray<WritebackContractFileAudit> {
const audits: WritebackContractFileAudit[] = [];
for (const path of locateAgentInstructionFiles(workspace)) {
audits.push(auditWritebackContractFile(path));
}
return Object.freeze(audits);
}
/** One-line an error message so a multi-line fs reason stays one detail. */
function reason(err: unknown): string {
const message = err instanceof Error ? err.message : String(err);
return message.replace(/\s+/g, " ").trim();
}
// ----- Shadow resolution (t_00b617b6) ---------------------------------------
/**
* One host reading a contract-free instruction file while another
* workspace candidate carries the write-back contract: the operative host
* never sees the gate. Pure data - resolved from audit rows, never from
* the filesystem.
*/
export interface WritebackContractShadow {
/** The host family whose preferred file misses the contract. */
readonly host: HostInstructionName;
/** Absolute path of the file the host reads, without the managed block. */
readonly readsPath: string;
/** Absolute path of another candidate that carries the contract. */
readonly contractPath: string;
/**
* The {@link WRITEBACK_CONTRACT_FINDING} of the contract side - what the
* advice on such a row depends on: a `conforming` contract file is a
* contract worth copying, while `malformed-block` or `missing-clauses`
* means the block the row points at is itself broken.
*/
readonly contractFinding: WritebackContractFinding;
}
/**
* The findings that prove a file CARRIES the managed block, in any state:
* conforming, or installed-then-broken (`malformed-block`,
* `missing-clauses`). A block that is present is evidence a host is being
* shadowed away from, whatever its condition; `missing-block` is the one
* present-file finding that does not carry it, and `absent`, `symlink`,
* `unreadable` never measured a block at all.
*/
const BLOCK_BEARING_FINDINGS: ReadonlySet<WritebackContractFinding> = new Set([
WRITEBACK_CONTRACT_FINDING.conforming,
WRITEBACK_CONTRACT_FINDING.malformedBlock,
WRITEBACK_CONTRACT_FINDING.missingClauses,
]);
/**
* Resolve which hosts the workspace's contract placement shadows, PURELY
* over the per-candidate audits (as {@link auditWorkspaceWritebackContract}
* produces them): no reads, no lstats, no writes - synthetic audits of
* paths that exist nowhere resolve exactly like audited ones.
*
* A host is shadowed when its preferred candidate - the first entry of its
* {@link HOST_INSTRUCTION_PRECEDENCE} list that exists - is a file WITHOUT
* the managed block while another candidate carries the block in any state.
* A host whose preferred file is absent reads nothing and is not shadowed;
* a host whose preferred file carries the block is not shadowed even when
* a peer carries a better-formed one; a symlink or unreadable preferred
* file is refused evidence, so no shadow is claimed from it (whether a
* link between candidates should be admitted as evidence is a recorded
* open question, not decided here). Nor is a host shadowed when its
* preferred file - however block-free itself - imports the contract file
* through a `@` line: the host renders that import into the surface it
* reads, managed block included, so the gate is seen (the audits'
* `imports` rows, {@link referencedImportPaths}; each recorded token is
* resolved against the workspace directory and compared to the contract
* file's path - the documented spellings (`@./AGENTS.md`, mid-line,
* list item) match, while refused tokens (`~/`, absolute,
* workspace-escaping) and tokens resolving to some OTHER workspace file
* excuse nothing). The contract side is
* the first block-bearing candidate in the audits' given order - the
* candidate list's priority order for a workspace audit.
*/
export function resolveShadowedInstructionContracts(
audits: ReadonlyArray<WritebackContractFileAudit>,
): ReadonlyArray<WritebackContractShadow> {
const contract = audits.find((audit) => BLOCK_BEARING_FINDINGS.has(audit.finding));
if (contract === undefined) return Object.freeze([]);
const byName = new Map<string, WritebackContractFileAudit>();
for (const audit of audits) byName.set(basename(audit.path), audit);
const shadows: WritebackContractShadow[] = [];
for (const [host, files] of Object.entries(HOST_INSTRUCTION_PRECEDENCE)) {
const preferred = files
.map((name) => byName.get(name))
.find((audit) => audit !== undefined && audit.finding !== WRITEBACK_CONTRACT_FINDING.absent);
if (preferred === undefined) continue;
if (preferred.finding !== WRITEBACK_CONTRACT_FINDING.missingBlock) continue;
// The host renders its preferred file's `@` imports into the surface
// it reads: an import RESOLVING to the contract file carries the
// block through, so there is no shadow to claim. Tokens are resolved
// against the workspace - the directory the candidates sit in - so
// `@./AGENTS.md`, a mid-line `@AGENTS.md` and a list-item
// `- @AGENTS.md` all match, while a refused token (`~/`, absolute,
// workspace-escaping) or one resolving to another workspace file
// (`docs/AGENTS.md`) excuses nothing.
const workspace = dirname(preferred.path);
if (preferred.imports.some((token) => resolve(workspace, token) === resolve(contract.path))) {
continue;
}
shadows.push(
Object.freeze({
host: host as HostInstructionName,
readsPath: preferred.path,
contractPath: contract.path,
contractFinding: contract.finding,
}),
);
}
return Object.freeze(shadows);
}