Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* Cue misses and 60 days unused (design 1.3, 4.19, R30, J14 d and e): an
* asks phrase whose block went unused twice in a row leaves `metadata.asks`
* (never the last one, never in a file edited by hand), counted and logged by
* its sha only; a skill unused for 60 days is said once. Synthetic skills in
* a sandbox TRAIL_HOME.
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import { readFileSync, renameSync, symlinkSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import type { SkillState } from "../src/skills/types.js";
import { cueFlush, dropPhrase, markMissingSaid, markUnusedSaid, noteCueResult, phraseSha, unusedSince } from "../src/skills/staleness.js";
import { listAllPersonal, savePersonal } from "../src/skills/store.js";
import { getSkillState, skillsStatePath } from "../src/skills/state.js";
import { appendLedger, readLedger } from "../src/skills/ledger.js";
import { parseSkillMd, skillHash } from "../src/skills/skillmd.js";
import { box, compiled } from "./skills-store-fixtures.js";
const ID = "s-7f3a2c";
const NOW = new Date("2026-10-20T10:00:00.000Z");
const PHRASE = "redo the acme publish";
function saved(asks = `publish, release, ${PHRASE}`) {
const b = box("stale");
const ref = savePersonal(compiled("release-npm", { trail: ID, asks }), { from: "repeated", runId: "r-1001-0001", consent: "offer-yes", stepsVerified: 2, env: b.env, now: NOW });
return { ...b, ref };
}
const st = (extra: Partial<SkillState> = {}): SkillState => ({
name: "release-npm", scope: "personal", status: "active", from: "repeated", runId: null, addedAt: "2026-07-01T10:00:00.000Z", lastWorked: null,
lastUsedAt: null, lastUsedRepo: null, uses: 0, checkedUses: 0, hash: "sha256:x", source: null, lastFails: [], promoteOffers: {}, ...extra,
});
test("phraseSha: 8 hex of sha256, the same for the same phrase however it is spaced or cased", () => {
assert.match(phraseSha(PHRASE), /^[0-9a-f]{8}$/);
assert.equal(phraseSha(` Redo the ACME publish `), phraseSha(PHRASE));
assert.notEqual(phraseSha("publish"), phraseSha("release"));
});
test("noteCueResult: a miss counts, a followed block resets, the 2nd miss in a row drops; no sha changes nothing", () => {
const s = st();
const sha = phraseSha(PHRASE);
assert.deepEqual(noteCueResult(s, sha, false), { drop: false });
assert.equal(s.cueMisses?.[sha], 1);
assert.deepEqual(noteCueResult(s, sha, true), { drop: false });
assert.equal(s.cueMisses?.[sha] ?? 0, 0, "followed: back to 0");
noteCueResult(s, sha, false);
assert.deepEqual(noteCueResult(s, sha, false), { drop: true });
const before = JSON.stringify(s);
assert.deepEqual(noteCueResult(s, null, false), { drop: false });
assert.equal(JSON.stringify(s), before);
const bad = st({ cueMisses: "x" as unknown as Record<string, number> });
assert.deepEqual(noteCueResult(bad, sha, false), { drop: false });
assert.deepEqual(bad.cueMisses, { [sha]: 1 }, "a hand-mangled count starts again");
});
test("dropPhrase: removes the phrase with that sha, keeps the file a valid skill, and moves st.hash", () => {
const b = saved();
const s = getSkillState(ID, b.env)!;
assert.equal(dropPhrase(b.ref, s, phraseSha(PHRASE)), true);
const text = readFileSync(b.ref.file, "utf8");
const parsed = parseSkillMd(text, "release-npm")!;
assert.equal(parsed.meta.asks, "publish, release");
assert.equal(parsed.meta.trail, ID);
assert.equal(s.hash, skillHash(text));
assert.equal(dropPhrase(b.ref, s, phraseSha(PHRASE)), false, "gone already");
});
test("dropPhrase: never the last phrase, never a file edited by hand, never through a link", () => {
const one = saved(PHRASE);
assert.equal(dropPhrase(one.ref, getSkillState(ID, one.env)!, phraseSha(PHRASE)), false, "the last phrase stays");
const edited = saved();
writeFileSync(edited.ref.file, readFileSync(edited.ref.file, "utf8").replace("## Run", "## Run\n<!-- mine -->"));
const s = getSkillState(ID, edited.env)!;
const hash = s.hash;
assert.equal(dropPhrase(edited.ref, s, phraseSha(PHRASE)), false);
assert.equal(s.hash, hash);
assert.match(readFileSync(edited.ref.file, "utf8"), new RegExp(PHRASE));
const linked = saved();
const away = join(linked.home, "kept-elsewhere");
renameSync(linked.ref.dir, away);
symlinkSync(away, linked.ref.dir);
assert.equal(dropPhrase(linked.ref, getSkillState(ID, linked.env)!, phraseSha(PHRASE)), false);
assert.match(readFileSync(join(away, "SKILL.md"), "utf8"), new RegExp(PHRASE));
});
test("cueFlush: two unfollowed blocks drop the phrase, state follows the file, one ledger cue line; the phrase is in no file but SKILL.md (R30)", () => {
const b = saved();
const sha = phraseSha(PHRASE);
assert.deepEqual(cueFlush(ID, sha, false, b.env, NOW), { dropped: false });
assert.equal(getSkillState(ID, b.env)!.cueMisses?.[sha], 1);
assert.deepEqual(cueFlush(ID, sha, false, b.env, NOW), { dropped: true });
const s = getSkillState(ID, b.env)!;
assert.equal(s.hash, skillHash(readFileSync(b.ref.file, "utf8")), "the hash in state follows the file");
assert.equal(s.cueMisses?.[sha] ?? 0, 0);
assert.equal(parseSkillMd(readFileSync(b.ref.file, "utf8"), "release-npm")!.meta.asks, "publish, release");
const cue = readLedger(ID, b.env).filter((l) => l.event === "cue");
assert.deepEqual(cue, [{ at: NOW.toISOString(), event: "cue", skill: ID, phraseSha: sha, change: "dropped" }]);
assert.doesNotMatch(readFileSync(skillsStatePath(b.env), "utf8"), /acme publish/);
assert.doesNotMatch(readFileSync(join(b.trail, "ledger", `${ID}.jsonl`), "utf8"), /acme publish/);
// A followed block, or no phrase, writes nothing new.
const ledger = readFileSync(join(b.trail, "ledger", `${ID}.jsonl`), "utf8");
assert.deepEqual(cueFlush(ID, null, false, b.env, NOW), { dropped: false });
assert.deepEqual(cueFlush(ID, phraseSha("publish"), true, b.env, NOW), { dropped: false });
assert.equal(readFileSync(join(b.trail, "ledger", `${ID}.jsonl`), "utf8"), ledger);
assert.deepEqual(cueFlush("s-000000", sha, false, b.env, NOW), { dropped: false }, "no such skill");
});
test("cueFlush: a hand-edited skill is never edited; the count just stays", () => {
const b = saved();
const sha = phraseSha(PHRASE);
writeFileSync(b.ref.file, `${readFileSync(b.ref.file, "utf8")}\n<!-- edited -->\n`);
cueFlush(ID, sha, false, b.env, NOW);
assert.deepEqual(cueFlush(ID, sha, false, b.env, NOW), { dropped: false });
assert.equal(getSkillState(ID, b.env)!.cueMisses?.[sha], 2);
assert.match(readFileSync(b.ref.file, "utf8"), new RegExp(PHRASE));
assert.deepEqual(readLedger(ID, b.env).filter((l) => l.event === "cue"), []);
assert.equal(listAllPersonal(b.env).length, 1);
});
test("the ledger keeps lesson and cue lines with their own fields only", () => {
const b = saved();
appendLedger(ID, { at: NOW.toISOString(), event: "lesson", skill: ID, lessonId: "ls-3c9e1a", src: "correction", consent: "offer-yes", text: "push the tag" } as never, b.env);
appendLedger(ID, { at: NOW.toISOString(), event: "cue", skill: ID, phraseSha: PHRASE, change: "dropped" } as never, b.env);
const lines = readLedger(ID, b.env).slice(-2);
assert.deepEqual(lines[0], { at: NOW.toISOString(), event: "lesson", skill: ID, lessonId: "ls-3c9e1a", src: "correction", consent: "offer-yes" });
assert.deepEqual(lines[1], { at: NOW.toISOString(), event: "cue", skill: ID, phraseSha: "", change: "dropped" }, "a phrase passed where a sha goes is never written");
assert.doesNotMatch(readFileSync(join(b.trail, "ledger", `${ID}.jsonl`), "utf8"), /acme publish|push the tag/);
});
test("unusedSince: 60+ days since the last use, else since saved; null before", () => {
const now = new Date(2026, 9, 20, 12);
assert.equal(unusedSince(st({ addedAt: new Date(2026, 7, 1, 9).toISOString() }), now), "2026-08-01");
assert.equal(unusedSince(st({ addedAt: new Date(2026, 7, 22, 9).toISOString() }), now), null, "59 days");
assert.equal(unusedSince(st({ addedAt: new Date(2026, 4, 1).toISOString(), lastUsedAt: new Date(2026, 9, 1).toISOString() }), now), null, "used this month");
assert.equal(unusedSince(st({ addedAt: "", lastUsedAt: null }), now), null);
});
test("markUnusedSaid once per unused stretch; markMissingSaid once a day", () => {
const b = saved();
const later = new Date(NOW.getTime() + 61 * 86400000);
assert.equal(markUnusedSaid(ID, b.env, NOW), false, "not unused yet");
assert.equal(markUnusedSaid(ID, b.env, later), true);
assert.equal(markUnusedSaid(ID, b.env, new Date(later.getTime() + 86400000)), false, "said once");
assert.equal(markMissingSaid(ID, b.env, NOW), true);
assert.equal(markMissingSaid(ID, b.env, new Date(NOW.getTime() + 3600000)), false, "same day");
assert.equal(markMissingSaid(ID, b.env, new Date(NOW.getTime() + 86400000)), true, "the next day");
assert.equal(markMissingSaid("s-000000", b.env, NOW), false);
});