Skip to content

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
12.6 KB
Raw Blame
/**
 * Skill drafts from mature vault pages (salience-lifecycle-enrichment,
 * unit 4, t_abaec26b). Claims pinned here:
 *
 *  1. The maturity gate admits a page only when all three page-meta
 *     dimensions hold - core tier, non-stale lifecycle, high confidence -
 *     and each rejection is NAMED per page, never a silent absence.
 *  2. Observed reuse is the evidence floor: a page nothing has reused is
 *     skipped by name even with a perfect trio.
 *  3. An installed skill already covering a page skips it by name.
 *  4. Exactly one spine envelope is built per ADMITTED page, and none for
 *     a skipped one.
 *  5. A draft payload is refused structurally (blank fields) and
 *     semantically (a name that is not a valid skill directory name).
 *  6. A validated draft is staged as a PENDING proposal inside the vault
 *     under the new `mature_page` pattern kind, and nothing is written
 *     outside the vault before accept.
 *  7. Accept materializes a well-formed SKILL.md under the configured
 *     skills root through the WAL-protected accept path.
 *  8. Rejection is sticky: a rejected page does not resurface as a draft.
 *  9. A page path that climbs out of the vault is refused by name before
 *     anything is staged - the draft's provenance is confined like every
 *     other vault write.
 * 10. The name charset is re-applied at MATERIALIZE time: a pending
 *     proposal whose `skill_name` was edited to something that is not a
 *     directory name is refused on accept, and nothing lands under the
 *     skills root.
 */

import { afterEach, beforeEach, expect, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { basename, join } from "node:path";

import { appendContinuityRecord } from "../../../src/core/brain/continuity/store.ts";
import { writeSkillAcceptJournal } from "../../../src/core/brain/skill-accept-journal.ts";
import { NEEDS_LLM_STEP } from "../../../src/core/brain/llm-step.ts";
import { ResponseCheckError } from "../../../src/core/brain/response-checks.ts";
import { ResponseShapeError } from "../../../src/core/brain/response-shape.ts";
import {
  commitSkillPageDraft,
  MATURE_PAGE_REUSE_FLOOR,
  planSkillPageDrafts,
  SKILL_PAGE_SKIP_REASON,
  SkillPageDraftError,
} from "../../../src/core/brain/skill-page-drafts.ts";
import {
  acceptSkillProposal,
  listPendingSkillProposals,
  MATURE_PAGE_PATTERN_KIND,
  recoverSkillProposalAccepts,
  rejectSkillProposal,
} from "../../../src/core/brain/skill-proposals.ts";

let vault: string;
let skillsRoot: string;
const NOW = new Date("2026-08-22T10:00:00Z");
const FRESH = "2026-08-01T00:00:00Z";
const ANCIENT = "2020-01-01T00:00:00Z";

const MATURE_PAGE = "notes/release-ritual.md";

function writePage(
  rel: string,
  meta: { title: string; tier?: string; lifecycle?: string; confidence?: string; created?: string },
): void {
  const abs = join(vault, rel);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(
    abs,
    [
      "---",
      `title: ${meta.title}`,
      `tier: ${meta.tier ?? "core"}`,
      `_lifecycle: ${meta.lifecycle ?? "verified"}`,
      `_confidence: ${meta.confidence ?? "high"}`,
      `created_at: ${meta.created ?? FRESH}`,
      "---",
      "",
      "# Release ritual",
      "",
      "Name the theme, cut the branch, run the gates, tag the commit.",
      "",
    ].join("\n"),
  );
}

/** Record `used` verdicts for `path` so it clears the reuse floor. */
function recordReuse(path: string, used: number): void {
  appendContinuityRecord(vault, {
    kind: "recall_observed_use",
    createdAt: NOW.toISOString(),
    sourceRefs: [{ id: `reuse:${path}:${used}` }],
    payload: {
      session_id: "sess-reuse",
      entries: Array.from({ length: used }, () => ({ path, verdict: "USED" })),
    },
  });
}

function plan() {
  return planSkillPageDrafts(vault, { now: NOW, skillsDir: skillsRoot });
}

function skipReasonFor(rel: string): string | undefined {
  return plan().skipped.find((s) => s.path === rel)?.reason;
}

const DRAFT = {
  name: "release-ritual",
  description: "Cut a release the way this vault says releases are cut.",
  triggers: ["release", "tag", "changelog"],
  body: "1. Name the theme.\n2. Cut the branch.\n3. Run the gates.\n4. Tag the commit.",
};

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-skill-pages-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
  skillsRoot = join(vault, "..", `skills-${Math.random().toString(36).slice(2)}`);
  mkdirSync(skillsRoot, { recursive: true });
  writePage(MATURE_PAGE, { title: "Release ritual" });
  recordReuse(MATURE_PAGE, 4);
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
  rmSync(skillsRoot, { recursive: true, force: true });
});

test("a page clearing the trio and the reuse floor is admitted with one envelope", () => {
  const report = plan();
  expect(report.admitted.map((a) => a.path)).toEqual([MATURE_PAGE]);
  const candidate = report.admitted[0]!;
  expect(candidate.llmStep.status).toBe(NEEDS_LLM_STEP);
  expect(candidate.llmStep.prompt).toContain("Name the theme, cut the branch");
  expect(candidate.llmStep.schema_hints.length).toBeGreaterThan(0);
  expect(candidate.reuseScore).toBeGreaterThanOrEqual(MATURE_PAGE_REUSE_FLOOR);
});

test("each trio dimension rejects by name, and no envelope is built for it", () => {
  writePage("notes/low-tier.md", { title: "Low tier", tier: "supporting" });
  writePage("notes/stale.md", { title: "Stale", lifecycle: "stable", created: ANCIENT });
  writePage("notes/unsure.md", { title: "Unsure", confidence: "medium" });
  for (const rel of ["notes/low-tier.md", "notes/stale.md", "notes/unsure.md"]) recordReuse(rel, 4);

  expect(skipReasonFor("notes/low-tier.md")).toBe(SKILL_PAGE_SKIP_REASON.tier);
  expect(skipReasonFor("notes/stale.md")).toBe(SKILL_PAGE_SKIP_REASON.lifecycle);
  expect(skipReasonFor("notes/unsure.md")).toBe(SKILL_PAGE_SKIP_REASON.confidence);
  expect(plan().admitted.map((a) => a.path)).toEqual([MATURE_PAGE]);
});

test("a page nothing has reused is skipped by the evidence floor", () => {
  writePage("notes/unused.md", { title: "Unused" });
  expect(skipReasonFor("notes/unused.md")).toBe(SKILL_PAGE_SKIP_REASON.reuse);
});

test("a page an installed skill already covers is skipped, and the skip is named", () => {
  mkdirSync(join(skillsRoot, "release-ritual"), { recursive: true });
  writeFileSync(
    join(skillsRoot, "release-ritual", "SKILL.md"),
    ["---", "name: release-ritual", "description: Already installed.", "---", "", "Body.", ""].join(
      "\n",
    ),
  );
  const report = plan();
  expect(report.admitted).toEqual([]);
  const skip = report.skipped.find((s) => s.path === MATURE_PAGE);
  expect(skip?.reason).toBe(SKILL_PAGE_SKIP_REASON.covered);
  expect(skip?.detail).toContain("release-ritual");
});

test("a blank draft field is refused by the shape layer and stages nothing", () => {
  expect(() =>
    commitSkillPageDraft(vault, MATURE_PAGE, { ...DRAFT, description: "   " }, { now: NOW }),
  ).toThrow(ResponseShapeError);
  expect(listPendingSkillProposals(vault)).toEqual([]);
});

test("a name that is not a valid skill directory name is refused by the semantic check", () => {
  let caught: unknown;
  try {
    commitSkillPageDraft(vault, MATURE_PAGE, { ...DRAFT, name: "Release Ritual!" }, { now: NOW });
  } catch (err) {
    caught = err;
  }
  expect(caught).toBeInstanceOf(ResponseCheckError);
  expect((caught as Error).message).toContain("Release Ritual!");
  expect(listPendingSkillProposals(vault)).toEqual([]);
});

test("a page path escaping the vault is refused by name and stages nothing", () => {
  // The escape target exists, so only the confinement check can refuse it:
  // an existence probe alone would confirm it and stage the proposal.
  const outside = join(vault, "..", "outside-page.md");
  writeFileSync(outside, "# Not this vault's page\n");
  try {
    let caught: unknown;
    try {
      commitSkillPageDraft(vault, "../outside-page.md", DRAFT, { now: NOW });
    } catch (err) {
      caught = err;
    }
    expect(caught).toBeInstanceOf(SkillPageDraftError);
    expect((caught as Error).message).toContain("outside-page.md");
    expect(listPendingSkillProposals(vault)).toEqual([]);
  } finally {
    rmSync(outside, { force: true });
  }
});

test("an edited skill_name is refused at materialize time and nothing reaches the skills root", () => {
  const res = commitSkillPageDraft(vault, MATURE_PAGE, DRAFT, { now: NOW });
  // What a hand edit of the pending proposal can do that the draft-time
  // check cannot see: the accept write passes no vault confinement,
  // because the skills root may legitimately sit outside the vault.
  const pendingFile = readFileSync(res.path, "utf8");
  // Unique per run, so the assertion below cannot be satisfied - or
  // defeated - by a directory some other run left behind.
  const escapeName = `${basename(skillsRoot)}-escaped`;
  writeFileSync(
    res.path,
    pendingFile.replace(`skill_name: ${DRAFT.name}`, `skill_name: ../${escapeName}`),
  );
  const before = readdirSync(skillsRoot);
  const escapeTarget = join(skillsRoot, "..", escapeName);

  try {
    expect(() => acceptSkillProposal(vault, res.slug, { now: NOW, skillsRoot })).toThrow(
      "skill directory name",
    );
    expect(readdirSync(skillsRoot)).toEqual(before);
    // Not merely "outside the root the operator configured": before the
    // charset was re-applied here, this wrote a SKILL.md into the skills
    // root's PARENT directory.
    expect(existsSync(escapeTarget)).toBe(false);
  } finally {
    rmSync(escapeTarget, { recursive: true, force: true });
  }
});

test("a validated draft stages a pending mature_page proposal inside the vault", () => {
  const before = readdirSync(skillsRoot);
  const res = commitSkillPageDraft(vault, MATURE_PAGE, DRAFT, { now: NOW });
  expect(res.outcome).toBe("created");
  expect(res.path.startsWith(join(vault, "Brain"))).toBe(true);
  const pending = listPendingSkillProposals(vault);
  expect(pending.map((p) => p.patternKind)).toEqual([MATURE_PAGE_PATTERN_KIND]);
  // Nothing outside the vault moved before accept.
  expect(readdirSync(skillsRoot)).toEqual(before);
});

test("accept materializes a well-formed SKILL.md under the skills root", () => {
  const res = commitSkillPageDraft(vault, MATURE_PAGE, DRAFT, { now: NOW });
  const accepted = acceptSkillProposal(vault, res.slug, { now: NOW, skillsRoot });
  expect(accepted.status).toBe("accepted");
  const skillFile = join(skillsRoot, DRAFT.name, "SKILL.md");
  expect(accepted.skillPath).toBe(skillFile);
  expect(existsSync(skillFile)).toBe(true);
  const body = readFileSync(skillFile, "utf8");
  expect(body).toContain(`name: ${DRAFT.name}`);
  expect(body).toContain(DRAFT.description);
  expect(body).toContain("triggers:");
  expect(body).toContain("Cut the branch.");
  // The pending copy is gone and the accepted archive is in the vault.
  expect(listPendingSkillProposals(vault)).toEqual([]);
  expect(accepted.proposalPath.startsWith(join(vault, "Brain"))).toBe(true);
});

test("rejection is sticky: a rejected page does not resurface as a draft", () => {
  const res = commitSkillPageDraft(vault, MATURE_PAGE, DRAFT, { now: NOW });
  rejectSkillProposal(vault, res.slug, { note: "not a skill" });
  const again = commitSkillPageDraft(vault, MATURE_PAGE, DRAFT, { now: NOW });
  expect(again.outcome).toBe("suppressed");
  expect(listPendingSkillProposals(vault)).toEqual([]);
});

test("the accept journal records the SKILL.md path, so a rollback removes exactly it", () => {
  const res = commitSkillPageDraft(vault, MATURE_PAGE, DRAFT, { now: NOW });
  const skillDir = join(skillsRoot, DRAFT.name);
  const skillFile = join(skillDir, "SKILL.md");
  mkdirSync(skillDir, { recursive: true });
  writeFileSync(skillFile, "half-written\n");

  // A crash between the two writes leaves a journal naming the target the
  // sequence was about to create; the resolver has to follow that path,
  // not re-derive a procedure path from the slug.
  writeSkillAcceptJournal(vault, {
    slug: res.slug,
    id: res.id,
    phase: "materialize",
    startedAt: NOW.toISOString(),
    acceptedExisted: false,
    materializedExisted: false,
    materializedPath: skillFile,
  });
  const recovered = recoverSkillProposalAccepts(vault);

  expect(recovered).toEqual([{ slug: res.slug, action: "rolled_back" }]);
  expect(existsSync(skillFile)).toBe(false);
  // The now-empty directory the sequence created goes with it.
  expect(existsSync(skillDir)).toBe(false);
  // The pending draft survives untouched - nothing was committed.
  expect(listPendingSkillProposals(vault).map((p) => p.slug)).toEqual([res.slug]);
});