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
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
DEFAULT_BEGIN_MARKER,
DEFAULT_END_MARKER,
} from "../../../src/core/install/managed-block.ts";
import { RULES_BLOCK_MARKERS } from "../../../src/core/install/rules-block.ts";
import {
AGENT_INSTRUCTION_FILES,
CANONICAL_WRITEBACK_BLOCK_BODY,
HOST_INSTRUCTION_PRECEDENCE,
WRITEBACK_CONTRACT_FINDING,
WRITEBACK_CONTRACT_REQUIREMENTS,
WRITEBACK_CONTRACT_RECOVERY,
auditWorkspaceWritebackContract,
auditWritebackContractFile,
locateAgentInstructionFiles,
missingWritebackGateClauses,
referencedImportPaths,
resolveShadowedInstructionContracts,
} from "../../../src/core/brain/writeback-contract.ts";
let tmp: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-writeback-"));
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
/** A managed block whose body carries every contract clause. */
const CONFORMING_BLOCK = [
"# >>> open-second-brain managed >>>",
"Memory write gate: write every durable fact you learn to the Open Second",
"Brain in the same turn, as an atomic fact, through the note tools;",
"@osb set mutations require guardrails.marker_writeback in _brain.yaml.",
"# <<< open-second-brain managed <<<",
].join("\n");
describe("missingWritebackGateClauses", () => {
test("a body carrying every clause has no missing clauses", () => {
expect(missingWritebackGateClauses(CONFORMING_BLOCK)).toEqual([]);
});
test("the clause patterns tolerate hyphen, spacing and case variants", () => {
expect(missingWritebackGateClauses("Same-Turn writes; ATOMIC FACTS; marker_writeback")).toEqual(
[],
);
expect(missingWritebackGateClauses("same\tturn; atomic\nfact; marker_writeback")).toEqual([]);
});
test("a body missing clauses names exactly the failing requirements", () => {
const missing = missingWritebackGateClauses("only mentions marker_writeback");
expect(missing).toEqual([
WRITEBACK_CONTRACT_REQUIREMENTS[1]!.label,
WRITEBACK_CONTRACT_REQUIREMENTS[2]!.label,
]);
});
test("the guardrail clause is keyed on the runtime's own flag name", () => {
// A block that paraphrases the guardrail without naming it does not
// pass: check and runtime refuse in the same words.
expect(missingWritebackGateClauses("same turn atomic fact write-back guardrail")).toContain(
WRITEBACK_CONTRACT_REQUIREMENTS[0]!.label,
);
});
});
describe("auditWritebackContractFile", () => {
test("a file with a conforming block passes, naming file and gate", () => {
const path = join(tmp, "AGENTS.md");
writeFileSync(path, `# Workspace\n\n${CONFORMING_BLOCK}\n`);
const audit = auditWritebackContractFile(path);
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.conforming);
expect(audit.missing).toEqual([]);
expect(audit.detail).toContain(path);
expect(audit.detail).toContain("atomic-fact");
});
test("a file without the block names it as not installed, with the recovery line", () => {
const path = join(tmp, "AGENTS.md");
writeFileSync(path, "# Workspace\n\nplain instructions, no managed block\n");
const audit = auditWritebackContractFile(path);
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.missingBlock);
expect(audit.detail).toContain(path);
expect(audit.detail).toContain("no Open Second Brain managed block");
expect(audit.detail).toContain("not installed");
expect(audit.detail).toContain(WRITEBACK_CONTRACT_RECOVERY);
});
test("a lone marker is a broken block, not a missing one", () => {
const path = join(tmp, "AGENTS.md");
writeFileSync(path, `# Workspace\n\n${DEFAULT_BEGIN_MARKER}\nhalf a block\n`);
const audit = auditWritebackContractFile(path);
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.malformedBlock);
expect(audit.detail).toContain(path);
expect(audit.detail).toContain(WRITEBACK_CONTRACT_RECOVERY);
});
test("the recovery line names the surface and the markers, never a board id", () => {
expect(WRITEBACK_CONTRACT_RECOVERY).toContain("ambient write-back managed block");
expect(WRITEBACK_CONTRACT_RECOVERY).toContain(DEFAULT_BEGIN_MARKER);
expect(WRITEBACK_CONTRACT_RECOVERY).toContain(DEFAULT_END_MARKER);
expect(WRITEBACK_CONTRACT_RECOVERY).not.toMatch(/\bt_[0-9a-f]{8}\b/);
});
test("a block present but without the gate clauses fails naming the pieces", () => {
const path = join(tmp, "AGENTS.md");
writeFileSync(
path,
[
"# >>> open-second-brain managed >>>",
"use the open-second-brain note tools",
"# <<< open-second-brain managed <<<",
].join("\n"),
);
const audit = auditWritebackContractFile(path);
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.missingClauses);
expect(audit.missing.length).toBe(WRITEBACK_CONTRACT_REQUIREMENTS.length);
expect(audit.detail).toContain(WRITEBACK_CONTRACT_REQUIREMENTS[0]!.label);
expect(audit.detail).toContain(WRITEBACK_CONTRACT_RECOVERY);
});
test("a read file records the basenames its @import lines reference", () => {
// Claude Code's memory-import syntax: a line starting with `@` followed
// by a path. The audit only records what it matched - the referenced
// basenames - and the shadow resolver compares those against the
// contract file's basename.
const path = join(tmp, "CLAUDE.md");
writeFileSync(path, ["# Claude", "", "@AGENTS.md", "", "@GEMINI.md"].join("\n"));
const audit = auditWritebackContractFile(path);
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.missingBlock);
expect([...audit.imports]).toEqual(["AGENTS.md", "GEMINI.md"]);
});
test("a file with no @import line records an empty imports list", () => {
const path = join(tmp, "CLAUDE.md");
writeFileSync(path, "# Claude\n\nplain instructions\n");
const audit = auditWritebackContractFile(path);
expect([...audit.imports]).toEqual([]);
});
test("refused reads carry no imports: absent, symlink", () => {
const real = join(tmp, "real.md");
writeFileSync(real, "@AGENTS.md\n");
const link = join(tmp, "CLAUDE.md");
symlinkSync(real, link);
expect([...auditWritebackContractFile(link).imports]).toEqual([]);
expect([...auditWritebackContractFile(join(tmp, "GEMINI.md")).imports]).toEqual([]);
});
test("an absent file is a named absent verdict, not an error", () => {
const audit = auditWritebackContractFile(join(tmp, "AGENTS.md"));
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.absent);
expect(audit.detail).toContain("AGENTS.md");
expect(audit.detail.length).toBeGreaterThan(0);
});
test("a symlink is refused without reading through it", () => {
const real = join(tmp, "real-instructions.md");
// The real file has NO managed block: if the audit followed the link
// it would report missing-block; refusing reports the symlink itself.
writeFileSync(real, "no block here\n");
const link = join(tmp, "AGENTS.md");
symlinkSync(real, link);
const audit = auditWritebackContractFile(link);
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.symlink);
expect(audit.detail).toContain("symbolic link");
expect(audit.finding).not.toBe(WRITEBACK_CONTRACT_FINDING.missingBlock);
});
test("a path that exists but cannot be read as a file is unreadable with the reason", () => {
const dir = join(tmp, "AGENTS.md");
mkdirSync(dir);
const audit = auditWritebackContractFile(dir);
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.unreadable);
expect(audit.detail).toContain(dir);
expect(audit.detail.length).toBeGreaterThan(dir.length);
});
});
describe("workspace audit", () => {
test("AGENTS.md leads the candidate list, then the tracked peers", () => {
expect(AGENT_INSTRUCTION_FILES[0]).toBe("AGENTS.md");
expect(AGENT_INSTRUCTION_FILES).toContain("CLAUDE.md");
expect(AGENT_INSTRUCTION_FILES).toContain("GEMINI.md");
const paths = locateAgentInstructionFiles(tmp);
expect(paths).toEqual(AGENT_INSTRUCTION_FILES.map((name) => join(tmp, name)));
});
test("every candidate is audited in priority order", () => {
writeFileSync(join(tmp, "AGENTS.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
writeFileSync(join(tmp, "CLAUDE.md"), "no block\n");
const audits = auditWorkspaceWritebackContract(tmp);
expect(audits.map((a) => a.finding)).toEqual([
WRITEBACK_CONTRACT_FINDING.conforming,
WRITEBACK_CONTRACT_FINDING.missingBlock,
WRITEBACK_CONTRACT_FINDING.absent,
]);
});
test("an empty workspace reports every candidate absent", () => {
const audits = auditWorkspaceWritebackContract(tmp);
expect(audits.length).toBe(AGENT_INSTRUCTION_FILES.length);
for (const audit of audits) {
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.absent);
}
});
});
describe("HOST_INSTRUCTION_PRECEDENCE", () => {
test("keys each host family on the instruction file it reads at the workspace root", () => {
expect(HOST_INSTRUCTION_PRECEDENCE["claude-code"]).toEqual(["CLAUDE.md"]);
expect(HOST_INSTRUCTION_PRECEDENCE.codex).toEqual(["AGENTS.md"]);
expect(HOST_INSTRUCTION_PRECEDENCE.cursor).toEqual(["AGENTS.md"]);
expect(HOST_INSTRUCTION_PRECEDENCE.opencode).toEqual(["AGENTS.md"]);
expect(HOST_INSTRUCTION_PRECEDENCE.aider).toEqual(["AGENTS.md"]);
expect(HOST_INSTRUCTION_PRECEDENCE["gemini-cli"]).toEqual(["GEMINI.md"]);
});
test("the table and every per-host list are frozen", () => {
expect(Object.isFrozen(HOST_INSTRUCTION_PRECEDENCE)).toBe(true);
for (const files of Object.values(HOST_INSTRUCTION_PRECEDENCE)) {
expect(Object.isFrozen(files)).toBe(true);
}
});
});
describe("referencedImportPaths", () => {
/**
* The host memory-import facts this tree implements, recorded where the
* matcher lives: an `@` at a word boundary anywhere on a line (Claude
* Code accepts mid-line and list-item imports; Gemini CLI documents
* `@./file`), followed by a path-shaped token ending at whitespace or
* end of line. Imports inside code spans and fenced blocks are NOT
* imports - no host evaluates them - and `~/`, absolute and
* workspace-escaping paths are refused outright. Anything looser would
* suppress a shadow and hide a live gate.
*/
test("a line-start @ followed by a basename records that basename", () => {
expect([...referencedImportPaths("@AGENTS.md\n")]).toEqual(["AGENTS.md"]);
expect([...referencedImportPaths("@AGENTS.md trailing prose\n")]).toEqual(["AGENTS.md"]);
expect([...referencedImportPaths("# header\n\n@CLAUDE.md\nbody\n")]).toEqual(["CLAUDE.md"]);
});
test("CRLF line endings are normalized before the match", () => {
expect([...referencedImportPaths("@AGENTS.md\r\nnext\r\n")]).toEqual(["AGENTS.md"]);
});
test("the documented mid-line and list-item spellings are imports too", () => {
expect([...referencedImportPaths("Read @AGENTS.md before answering\n")]).toEqual(["AGENTS.md"]);
expect([...referencedImportPaths("- @AGENTS.md\n")]).toEqual(["AGENTS.md"]);
expect([...referencedImportPaths(" @AGENTS.md\n")]).toEqual(["AGENTS.md"]);
});
test("a leading ./ is stripped: the relative spelling names the same file", () => {
// Gemini CLI documents `@./file.md`.
expect([...referencedImportPaths("@./AGENTS.md\n")]).toEqual(["AGENTS.md"]);
expect([...referencedImportPaths("@./AGENTS.md\n@AGENTS.md\n")]).toEqual(["AGENTS.md"]);
});
test("workspace-relative paths are recorded verbatim", () => {
expect([...referencedImportPaths("@docs/AGENTS.md\n")]).toEqual(["docs/AGENTS.md"]);
});
test("tilde, absolute and workspace-escaping paths are refused", () => {
expect([...referencedImportPaths("@~/AGENTS.md\n")]).toEqual([]);
expect([...referencedImportPaths("@~/notes/AGENTS.md\n")]).toEqual([]);
expect([...referencedImportPaths("@/etc/AGENTS.md\n")]).toEqual([]);
expect([...referencedImportPaths("@../AGENTS.md\n")]).toEqual([]);
expect([...referencedImportPaths("@../shared/AGENTS.md\n")]).toEqual([]);
expect([...referencedImportPaths("@AGENTS.md/../../escape.md\n")]).toEqual([]);
});
test("doubled sigils and email addresses are not imports", () => {
expect([...referencedImportPaths("@@AGENTS.md\n")]).toEqual([]);
expect([...referencedImportPaths("contact me at [email protected]\n")]).toEqual([]);
expect([...referencedImportPaths("email me at [email protected] @AGENTS.md\n")]).toEqual([
"AGENTS.md",
]);
});
test("imports inside code spans and fenced blocks are not imports", () => {
// No host evaluates an import inside inline code or a fence: a
// fenced `@AGENTS.md` renders as literal text, so it must not excuse
// a shadow.
expect([...referencedImportPaths("the import is `@AGENTS.md` here\n")]).toEqual([]);
expect([...referencedImportPaths("```md\n@AGENTS.md\n```\n")]).toEqual([]);
expect([...referencedImportPaths("~~~\n@AGENTS.md\n~~~\n")]).toEqual([]);
expect([...referencedImportPaths("```md\nfenced\n```\n\n@AGENTS.md\n")]).toEqual(["AGENTS.md"]);
});
test("a token that only looks like the basename is recorded verbatim, never truncated", () => {
expect([...referencedImportPaths("@AGENTS.md.bak\n")]).toEqual(["AGENTS.md.bak"]);
expect([...referencedImportPaths("@AGENTS.MD\n")]).toEqual(["AGENTS.MD"]);
});
test("the same path twice is recorded once, in first-appearance order", () => {
expect([...referencedImportPaths("@AGENTS.md\n\n@./AGENTS.md\n@GEMINI.md\n")]).toEqual([
"AGENTS.md",
"GEMINI.md",
]);
});
});
describe("resolveShadowedInstructionContracts", () => {
/**
* The resolver is pure over the workspace audit rows: these tests drive
* it through `auditWorkspaceWritebackContract` on real temp files and,
* for the purity case, through synthetic audits of paths that exist
* nowhere on disk.
*/
test("a bare CLAUDE.md beside a conforming AGENTS.md shadows claude-code, naming both paths", () => {
const claude = join(tmp, "CLAUDE.md");
writeFileSync(claude, "# Claude\n\nplain instructions, no managed block\n");
const agents = join(tmp, "AGENTS.md");
writeFileSync(agents, `# W\n\n${CONFORMING_BLOCK}\n`);
const shadows = resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp));
expect(shadows).toEqual([
{
host: "claude-code",
readsPath: claude,
contractPath: agents,
contractFinding: WRITEBACK_CONTRACT_FINDING.conforming,
},
]);
});
test("the shadow triple carries the contract side's finding", () => {
// The row's advice depends on the contract side's condition: a block
// that was installed and then broken must not be worded as a contract
// worth copying.
const claude = join(tmp, "CLAUDE.md");
writeFileSync(claude, "plain\n");
const agents = join(tmp, "AGENTS.md");
writeFileSync(agents, `${DEFAULT_BEGIN_MARKER}\nhalf a block\n`);
const malformed = resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp));
expect(malformed.map((s) => s.contractFinding)).toEqual([
WRITEBACK_CONTRACT_FINDING.malformedBlock,
]);
});
test("a block in any carried state shadows: conforming, malformed and clause-incomplete", () => {
const claude = join(tmp, "CLAUDE.md");
writeFileSync(claude, "plain\n");
const agents = join(tmp, "AGENTS.md");
writeFileSync(
agents,
[
"# >>> open-second-brain managed >>>",
"use the open-second-brain note tools",
"# <<< open-second-brain managed <<<",
].join("\n"),
);
const clauseIncomplete = resolveShadowedInstructionContracts(
auditWorkspaceWritebackContract(tmp),
);
expect(clauseIncomplete.map((s) => s.host)).toEqual(["claude-code"]);
expect(clauseIncomplete[0]).toEqual({
host: "claude-code",
readsPath: claude,
contractPath: agents,
contractFinding: WRITEBACK_CONTRACT_FINDING.missingClauses,
});
writeFileSync(agents, `${DEFAULT_BEGIN_MARKER}\nhalf a block\n`);
const malformed = resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp));
expect(malformed.map((s) => s.host)).toEqual(["claude-code"]);
expect(malformed[0]!.contractPath).toBe(agents);
});
test("GEMINI.md-only and AGENTS.md-only workspaces yield no shadow", () => {
writeFileSync(join(tmp, "GEMINI.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
expect(resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp))).toEqual([]);
rmSync(join(tmp, "GEMINI.md"));
writeFileSync(join(tmp, "AGENTS.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
expect(resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp))).toEqual([]);
// And a bare AGENTS.md alone: nothing carries the block to shadow with.
writeFileSync(join(tmp, "AGENTS.md"), "plain\n");
expect(resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp))).toEqual([]);
});
test("a workspace whose every existing file carries the block yields no shadow", () => {
writeFileSync(join(tmp, "AGENTS.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
writeFileSync(join(tmp, "CLAUDE.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
expect(resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp))).toEqual([]);
});
test("shadowing is host-symmetric: a bare AGENTS.md shadows the agents.md family, not claude-code", () => {
writeFileSync(join(tmp, "CLAUDE.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
writeFileSync(join(tmp, "AGENTS.md"), "plain\n");
const shadows = resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp));
expect(shadows.map((s) => s.host)).toEqual(["codex", "cursor", "opencode", "aider"]);
expect(shadows.every((s) => s.readsPath === join(tmp, "AGENTS.md"))).toBe(true);
expect(shadows.every((s) => s.contractPath === join(tmp, "CLAUDE.md"))).toBe(true);
});
test("several hosts can be shadowed at once, in table order", () => {
writeFileSync(join(tmp, "CLAUDE.md"), "plain\n");
writeFileSync(join(tmp, "GEMINI.md"), "plain\n");
writeFileSync(join(tmp, "AGENTS.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
const shadows = resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp));
expect(shadows.map((s) => s.host)).toEqual(["claude-code", "gemini-cli"]);
expect(shadows[0]).toEqual({
host: "claude-code",
readsPath: join(tmp, "CLAUDE.md"),
contractPath: join(tmp, "AGENTS.md"),
contractFinding: WRITEBACK_CONTRACT_FINDING.conforming,
});
expect(shadows[1]).toEqual({
host: "gemini-cli",
readsPath: join(tmp, "GEMINI.md"),
contractPath: join(tmp, "AGENTS.md"),
contractFinding: WRITEBACK_CONTRACT_FINDING.conforming,
});
});
test("absent-only workspaces yield nothing", () => {
expect(resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp))).toEqual([]);
});
test("a symlink candidate is refused evidence: never read, never a shadow side", () => {
const real = join(tmp, "real-agents.md");
writeFileSync(real, `# W\n\n${CONFORMING_BLOCK}\n`);
symlinkSync(real, join(tmp, "AGENTS.md"));
writeFileSync(join(tmp, "CLAUDE.md"), "plain\n");
const shadows = resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp));
expect(shadows).toEqual([]);
});
test("the resolver is pure: synthetic audits of paths that exist nowhere still resolve", () => {
const synthetic = [
{
path: "/nowhere/o2b-purity/AGENTS.md",
finding: WRITEBACK_CONTRACT_FINDING.conforming,
detail: "synthetic",
missing: [],
imports: [],
},
{
path: "/nowhere/o2b-purity/CLAUDE.md",
finding: WRITEBACK_CONTRACT_FINDING.missingBlock,
detail: "synthetic",
missing: [],
imports: [],
},
{
path: "/nowhere/o2b-purity/GEMINI.md",
finding: WRITEBACK_CONTRACT_FINDING.absent,
detail: "synthetic",
missing: [],
imports: [],
},
];
const shadows = resolveShadowedInstructionContracts(synthetic);
expect(shadows).toEqual([
{
host: "claude-code",
readsPath: "/nowhere/o2b-purity/CLAUDE.md",
contractPath: "/nowhere/o2b-purity/AGENTS.md",
contractFinding: WRITEBACK_CONTRACT_FINDING.conforming,
},
]);
// The resolver ran entirely on the given data: it created nothing and
// never touched the filesystem its input paths name.
expect(existsSync("/nowhere")).toBe(false);
});
test("a CLAUDE.md that only imports the conforming AGENTS.md is not shadowed", () => {
// The common real setup: Claude Code's import syntax renders the
// imported file - managed block included - into the surface the host
// reads, so the contract is NOT shadowed away and the readiness gate
// must stay green.
const claude = join(tmp, "CLAUDE.md");
writeFileSync(claude, "# Claude\n\n@AGENTS.md\n");
const agents = join(tmp, "AGENTS.md");
writeFileSync(agents, `# W\n\n${CONFORMING_BLOCK}\n`);
expect(resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp))).toEqual([]);
});
test("an import only excuses the file it names: a bare CLAUDE.md is still shadowed", () => {
// The same workspace as above minus the import line: the shadow is
// exactly what the gate exists to report.
const claude = join(tmp, "CLAUDE.md");
writeFileSync(claude, "# Claude\n\nplain instructions, no managed block\n");
const agents = join(tmp, "AGENTS.md");
writeFileSync(agents, `# W\n\n${CONFORMING_BLOCK}\n`);
expect(
resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp)).map((s) => s.host),
).toEqual(["claude-code"]);
});
test("the documented import spellings all excuse the shadow", () => {
// Claude Code accepts mid-line and list-item imports and Gemini CLI
// documents the `@./file` spelling: every one of these renders the
// contract file into the surface the host reads, so none may false-
// fail readiness.
const spellings = [
"@./AGENTS.md\n", // Gemini CLI's relative spelling
"Read @AGENTS.md first\n", // mid-line
"- @AGENTS.md\n", // list item
"see @AGENTS.md for details\n", // mid-line prose
" @AGENTS.md\n", // indented
];
for (const body of spellings) {
writeFileSync(join(tmp, "CLAUDE.md"), body);
writeFileSync(join(tmp, "AGENTS.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
const shadows = resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp));
expect(shadows, body).toEqual([]);
}
});
test("a GEMINI.md importing @./AGENTS.md is not shadowed either", () => {
// gemini-cli's preferred file misses the block but renders the
// contract through its documented relative-import spelling; CLAUDE.md
// is absent, so only the gemini-cli row is at stake.
writeFileSync(join(tmp, "GEMINI.md"), "@./AGENTS.md\n");
writeFileSync(join(tmp, "AGENTS.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
expect(resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp))).toEqual([]);
});
test("malformed import lookalikes do not suppress the shadow", () => {
const lookalikes = [
"@@AGENTS.md\n", // doubled sigil
"@AGENTS.md.bak\n", // a different file
"@docs/AGENTS.md\n", // resolves elsewhere in the workspace
"@AGENTS.MD\n", // a different file by case
"@~/AGENTS.md\n", // refused: outside the workspace
"@../AGENTS.md\n", // refused: escapes the workspace
"```md\n@AGENTS.md\n```\n", // fenced: no host evaluates imports there
"the import is `@AGENTS.md` in code\n", // a code span is not an import
];
for (const body of lookalikes) {
writeFileSync(join(tmp, "CLAUDE.md"), body);
writeFileSync(join(tmp, "AGENTS.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
const shadows = resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp));
expect(
shadows.map((s) => s.host),
body,
).toEqual(["claude-code"]);
}
});
test("an import excuses only the named contract file, not every candidate", () => {
// CLAUDE.md imports GEMINI.md, but the contract lives in AGENTS.md:
// the host still never sees the block, so the shadow stands.
writeFileSync(join(tmp, "CLAUDE.md"), "@GEMINI.md\n");
writeFileSync(join(tmp, "AGENTS.md"), `# W\n\n${CONFORMING_BLOCK}\n`);
expect(
resolveShadowedInstructionContracts(auditWorkspaceWritebackContract(tmp)).map((s) => s.host),
).toEqual(["claude-code"]);
});
});
describe("CANONICAL_WRITEBACK_BLOCK_BODY", () => {
test("satisfies every gate clause, so the installer can never ship a non-conforming block", () => {
expect([...missingWritebackGateClauses(CANONICAL_WRITEBACK_BLOCK_BODY)]).toEqual([]);
});
test("merges the cross-project-pointer usage content with the gate clauses", () => {
// The four usage surfaces K2 names, in the checker's own vocabulary.
expect(CANONICAL_WRITEBACK_BLOCK_BODY).toContain("brain_context");
expect(CANONICAL_WRITEBACK_BLOCK_BODY).toContain("brain_feedback");
expect(CANONICAL_WRITEBACK_BLOCK_BODY).toContain("brain_apply_evidence");
expect(CANONICAL_WRITEBACK_BLOCK_BODY).toContain("dream");
});
test("is static text: no template placeholders, no vault path, no memory content", () => {
expect(CANONICAL_WRITEBACK_BLOCK_BODY).not.toMatch(/\{\{?/);
expect(CANONICAL_WRITEBACK_BLOCK_BODY).not.toContain("<absolute");
expect(CANONICAL_WRITEBACK_BLOCK_BODY).not.toMatch(/\/(home|Users|mnt)\//);
// Agent-facing text names tools, never the legacy tree's paths.
expect(CANONICAL_WRITEBACK_BLOCK_BODY).not.toMatch(/Brain\//);
});
test("a file carrying only the lessons pair still grades missing-block", () => {
// The audit reads only the settled default markers; a sibling block
// with its own spelling is invisible to the contract by design.
const lessonsOnly = [
RULES_BLOCK_MARKERS.lessons.begin,
"- prefer small commits",
RULES_BLOCK_MARKERS.lessons.end,
].join("\n");
const path = join(tmp, "AGENTS.md");
writeFileSync(path, `# W\n\n${lessonsOnly}\n`);
expect(auditWritebackContractFile(path).finding).toBe(WRITEBACK_CONTRACT_FINDING.missingBlock);
});
test("a file with both blocks is graded by its own pair alone", () => {
const both = [
CONFORMING_BLOCK,
RULES_BLOCK_MARKERS.lessons.begin,
"- prefer small commits",
RULES_BLOCK_MARKERS.lessons.end,
].join("\n");
const path = join(tmp, "AGENTS.md");
writeFileSync(path, `# W\n\n${both}\n`);
expect(auditWritebackContractFile(path).finding).toBe(WRITEBACK_CONTRACT_FINDING.conforming);
});
test("the canonical body renders a conforming block through the settled markers", () => {
const document = [
DEFAULT_BEGIN_MARKER,
CANONICAL_WRITEBACK_BLOCK_BODY,
DEFAULT_END_MARKER,
].join("\n");
const path = join(tmp, "AGENTS.md");
writeFileSync(path, `${document}\n`);
const audit = auditWritebackContractFile(path);
expect(audit.finding).toBe(WRITEBACK_CONTRACT_FINDING.conforming);
expect(audit.missing).toEqual([]);
});
});