Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

Merge branch 'split/6-wiring' into split/7-learnings-skills

Shrish Dwivedi1bbdf0e300cc
diff --cc test/skills-follow-learnings.test.ts
index d62a554b,00000000..7f64f8e1
mode 100644,000000..100644
--- a/test/skills-follow-learnings.test.ts
+++ b/test/skills-follow-learnings.test.ts
@@@ -1,223 -1,0 +1,248 @@@
+/**
+ * Part 7: learnings and skills never repeat or contradict each other in what
+ * the agent hears. Which learnings count (live ones only), how a save
+ * follows them and names it in one line, how a run block says each once,
+ * and how the update offer proposes the change. Made-up acme/shop only.
+ */
+process.env.TZ = "UTC";
+import { after, test } from "node:test";
+import assert from "node:assert/strict";
- import { mkdirSync, writeFileSync } from "node:fs";
++import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
++import { spawnSync } from "node:child_process";
++import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { compileRun, type CompileOpts } from "../src/skills/compile.js";
+import { skillSha } from "../src/skills/offer-moment.js";
+import { parseSkillMd, renderSkillMd } from "../src/skills/skillmd.js";
+import { callKind } from "../src/trace/checks.js";
+import { renderNote, type Note } from "../src/notes/notes.js";
+import { writeEveryRepo } from "../src/notes/every-repo.js";
+import { repoNotesDir } from "../src/notes/repo-notes-dir.js";
+import { runBlock } from "../src/skills/runblock.js";
+import {
+ followAtSave, markLines, onlyRepeats, recallMarks, saidIn, stepLearningOf, stepLearnings, withFixes, withFollowLine, type StepLearning,
+} from "../src/skills/follow-learnings.js";
+import type { RunCall, RunSheet } from "../src/trace/types.js";
+import { cand } from "./skills-recall-fixtures.js";
+import { box, SHOP } from "./skills-store-fixtures.js";
+import { rmSync } from "node:fs";
+
+const homes: string[] = [];
+after(() => { for (const h of homes) rmSync(h, { recursive: true, force: true }); });
+
+let seq = 0;
+const call = (cmd: string, o: Partial<RunCall> = {}): RunCall => {
+ seq++;
+ return { id: `toolu_f${seq}`, at: new Date(Date.UTC(2026, 9, 27, 10, 0, 0) + seq * 20_000).toISOString(), cmd, key: SHOP, cwd: "", bg: false, failed: false,
+ isError: false, kind: callKind(cmd, "tests"), src: { use: seq * 1000, result: seq * 1000 + 400 }, ...o };
+};
+/** The test suite, the way the person's agent ran it: a failed run first, then install, build and the passing suite. */
+function testsSheet(cmds = ["npm ci", "npm run build"], check = "npm test"): RunSheet {
+ const calls = [call(check, { failed: true, isError: true, errorLine: "Tests: 1 failed" }), ...cmds.map((c) => call(c)),
+ call(check, { check: { family: "tests", passed: true, facts: { passedCount: 12 } } })];
+ return {
+ v: 1, id: "r-1027-7c1d", session: "e76b4ca7f1a0", repoKey: SHOP, branch: "main", host: "claude", tier: "A", epoch: 0,
+ startedAt: calls[0]!.at, endedAt: calls.at(-1)!.at, job: "tests", jobWords: ["test"], sharedWords: [], promptParams: {}, calls,
+ checkIndex: calls.length - 1, checked: true, end: "done", counts: { commands: calls.length, failed: 1, toolCalls: calls.length, edits: 0 }, helpers: [], skillId: null,
+ };
+}
+const OPTS: CompileOpts = { repoRoot: "/home/dev/shop", home: "/home/dev", platform: "linux", moment: "repeated", applies: SHOP, taken: () => false, name: "run-tests" };
+const learning = (title: string, o: Partial<Note> = {}): StepLearning => stepLearningOf({ id: "l-1a2b3c4d", kind: "preference", scope: "personal", title, body: title, ...o })!;
+const PNPM = learning("use pnpm, not npm");
+const SCHEMA = learning("don't edit _schema.py by hand, run scripts/gen_schema.py");
+
+function compiled(sheet: RunSheet, ls: StepLearning[] = []) {
+ const r = compileRun(sheet, { ...OPTS, learnings: ls });
+ if (!r.ok) assert.fail(`refused ${r.reason}: ${r.detail}`);
+ return r.skill;
+}
+
+/* ------------------------------------------------------------ which learnings count */
+
+function note(dir: string, file: string, title: string, o: Partial<Note> = {}): void {
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(join(dir, file), renderNote({ title, author: "", date: "2026-10-20", touches: [], body: title, id: "l-00000000", ...o }));
+}
+
+test("only live learnings count: retired, replaced, held and lesson ones never do, nor another repo's", () => {
+ const b = box("follow-live");
+ homes.push(b.home);
+ const mine = repoNotesDir(SHOP, b.env);
+ note(mine, "a.md", "use pnpm, not npm", { id: "l-aaaaaaa1", kind: "preference", applies: SHOP });
+ note(mine, "b.md", "never run npx prisma db push", { id: "l-aaaaaaa2", kind: "decision", status: "retired" });
+ note(mine, "c.md", "use yarn, not npm", { id: "l-aaaaaaa3", kind: "preference", date: "2026-10-01" });
+ note(mine, "d.md", "use bun, not npm", { id: "l-aaaaaaa4", kind: "preference", date: "2026-10-02", replaces: "l-aaaaaaa3" });
+ note(mine, "e.md", "don't use npx", { id: "l-aaaaaaa5", kind: "preference", status: "held" });
+ note(mine, "f.md", "never run make deploy", { id: "l-aaaaaaa6", kind: "lesson" });
+ note(mine, "g.md", "never run make clean", { id: "l-aaaaaaa7", kind: "preference", applies: "github.com/acme/other" });
+ note(mine, "h.md", "The staging database is read-only on Fridays.", { id: "l-aaaaaaa8", kind: "decision" });
+ note(join(b.checkout, ".trail", "learnings"), "r.md", "always run make lint before git push", { id: "l-bbbbbbb1", kind: "decision" });
+ writeEveryRepo({ title: "run `pytest -q` instead of `npm test`", body: "run `pytest -q` instead of `npm test`", author: "", date: "2026-10-20", kind: "preference" }, "pref-pytest.md", b.env);
+ const got = stepLearnings({ repoKeys: [SHOP], checkout: b.checkout, env: b.env });
+ assert.deepEqual(got.map((l) => [l.quote, l.kind, l.scope]).sort(), [
+ ["always run make lint before git push", "decision", "repo"],
+ ["run `pytest -q` instead of `npm test`", "preference", "personal"],
+ ["use bun, not npm", "preference", "personal"],
+ ["use pnpm, not npm", "preference", "personal"],
+ ]);
+ // Nothing to read is no learning, never an error.
+ assert.deepEqual(stepLearnings({ repoKeys: ["github.com/acme/none"], checkout: "", env: { HOME: b.home, TRAIL_HOME: join(b.home, "nowhere") } }), []);
+});
+
+test("a learning's tried-and-ruled-out part is never read as what to do", () => {
+ const l = stepLearningOf({ id: "l-1", kind: undefined, scope: "repo", title: "Test setup", body: "## Decided\nuse pnpm, not npm\n## Tried and ruled out\nuse yarn instead of pnpm" });
+ assert.deepEqual(l?.rules, [{ t: "swap", use: { prog: "pnpm", args: [] }, not: { prog: "npm", args: [] } }]);
+ assert.equal(l?.whole, false, "the quote is the title, not the whole learning");
+});
+
+/* ------------------------------------------------------------ at a save */
+
+test("pnpm vs npm at a save: the steps follow the preference, the check too, and one line says so", () => {
+ const sheet = testsSheet();
+ const plain = compiled(sheet);
+ assert.deepEqual(plain.steps.map((s) => s.cmd), ["npm ci", "npm run build", "npm test"]);
+ assert.equal(plain.followed, undefined);
+ const c = compiled(sheet, [PNPM]);
+ assert.deepEqual(c.steps.map((s) => s.cmd), ["pnpm install --frozen-lockfile", "pnpm run build", "pnpm test"]);
+ assert.equal(c.check, "pnpm test");
+ assert.equal(c.checkIsStep, true);
+ assert.equal(c.meta.needs, "pnpm");
+ assert.deepEqual(c.steps.map((s) => s.from), plain.steps.map((s) => s.from), "each step still points at the call it was copied from");
+ assert.equal(c.followed, 'Steps 1, 2 and 3 follow your preference "use pnpm, not npm" rather than this run\'s commands.');
+ // The same learnings give the same skill: both halves of a save agree on what the yes was to.
+ assert.equal(skillSha(compiled(sheet, [PNPM])), skillSha(c));
+ assert.notEqual(skillSha(c), skillSha(plain));
+ const back = parseSkillMd(renderSkillMd(c), c.name)!;
+ assert.deepEqual(back.steps.map((s) => s.cmd), c.steps.map((s) => s.cmd));
+});
+
+test("a step that can't follow safely is left out, and the line says which and why", () => {
+ const c = compiled(testsSheet(["npm ci", "npx prisma db push", "npm run build"]), [learning("never run npx prisma db push", { kind: "decision" })]);
+ assert.deepEqual(c.steps.map((s) => s.cmd), ["npm ci", "npm run build", "npm test"]);
+ assert.equal(c.followed, "Trail left out 'npx prisma db push': it goes against your decision \"never run npx prisma db push\", and Trail can't change it safely.");
+ // The check itself can't be left out: no skill.
+ const r = compileRun(testsSheet(), { ...OPTS, learnings: [learning("never run npm test", { scope: "repo" })] });
+ assert.equal(r.ok, false);
+ assert.match(!r.ok ? r.detail : "", /^goes against this repo's preference "never run npm test", and it is the check$/);
+});
+
+test("a learning that only repeats a step changes nothing at a save", () => {
+ const c = compiled(testsSheet(["python scripts/gen_schema.py", "npm run build"]), [SCHEMA]);
+ assert.deepEqual(c.steps.map((s) => s.cmd), ["python scripts/gen_schema.py", "npm run build", "npm test"]);
+ assert.equal(c.followed, undefined);
+});
+
+test("the offer names it at the end of line 1; line 2 is the question as always", () => {
+ const lines: [string, string] = ["Tests pass (12 passed). That's the 3rd day I've worked out the tests from scratch (5 commands this time, 1 failed).", "Keep the 3 that worked as a skill, just for you in this repo? (yes / show me / no)"];
+ const f = 'Steps 1, 2 and 3 follow your preference "use pnpm, not npm" rather than this run\'s commands.';
+ assert.deepEqual(withFollowLine(lines, f), [`${lines[0]} ${f}`, lines[1]]);
+ assert.deepEqual(withFollowLine(lines, undefined), lines);
+ const long = withFollowLine(lines, "x".repeat(300));
+ assert.equal(long[0], `${lines[0]} Some steps follow your learnings rather than this run; say show me to see them.`);
+ assert.ok(long[0].length <= 400);
+});
+
+test("followAtSave keeps a gated step as it is: it never rewrites a step that can't be undone", () => {
+ const f = followAtSave([{ cmd: "npm run build", gated: false, isCheck: false }, { cmd: "npm publish --access public", gated: true, isCheck: false }], [PNPM]);
+ assert.deepEqual(f.keep, [{ i: 0, cmd: "pnpm run build" }]);
+ // Both sentences are too long for an offer's line 1 together: the counts instead.
+ assert.equal(f.line, "To follow your learnings, Trail changed 1 step and left out 1 step; say show me to see them.");
+ const short = learning("use bun, not npm");
+ assert.equal(followAtSave([{ cmd: "npm test", gated: false, isCheck: false }, { cmd: "npm pack", gated: false, isCheck: false }], [short]).line,
+ "Step 1 runs 'bun run test' rather than this run's 'npm test', as your preference \"use bun, not npm\" says. Trail left out 'npm pack': it goes against your preference \"use bun, not npm\", and Trail can't change it safely.");
+});
+
+/* ------------------------------------------------------------ at recall */
+
+const skillOf = (cmds: string[]) => cand(compiled(testsSheet(cmds)), { lastWorked: "2026-10-27" });
+const blockCtx = { values: {}, notes: [], probes: [], canAsk: true, header: "job" as const, lastFail: null, lessons: [], gone: [] };
+
+test("recall, a repeat: the block says the preference once, under its steps, and the prompt leaves it out", () => {
+ const c = skillOf(["python scripts/gen_schema.py", "npm run build"]);
+ const marks = recallMarks(c.skill.steps, [SCHEMA]);
+ const block = runBlock(c, { ...blockCtx, marks });
+ assert.deepEqual(block.split("\n"), [
+ "[trail] Skill run-tests fits (yours, v1, last worked Oct 27). Start from these exact steps, in order:",
+ " 1 python scripts/gen_schema.py",
+ " 2 npm run build",
+ " 3 npm test",
+ " check: step 3 passing is the check.",
+ " Step 1 follows your preference: \"don't edit _schema.py by hand, run scripts/gen_schema.py\".",
+ " If a step fails, fix that step and say so. End with \"Used skill run-tests\".",
+ ]);
+ assert.deepEqual(saidIn(block, marks), ["l-1a2b3c4d"]);
+});
+
+test("recall, a contradiction: the preference wins, the block marks each step and shows it the preference's way", () => {
+ const c = skillOf(["npm ci", "npm run build"]);
+ const marks = recallMarks(c.skill.steps, [PNPM]);
+ const block = runBlock(c, { ...blockCtx, marks });
+ assert.deepEqual(block.split("\n").slice(1), [
+ " 1 pnpm install --frozen-lockfile (your preference's way; the skill has npm ci)",
+ " 2 pnpm run build (your preference's way; the skill has npm run build)",
+ " 3 pnpm test (your preference's way; the skill has npm test)",
+ " check: step 3 passing is the check.",
+ " Your preference wins over the skill: \"use pnpm, not npm\". Steps 1, 2 and 3 are written its way; run them as shown.",
+ " If a step fails, fix that step and say so. End with \"Used skill run-tests\".",
+ ]);
+ // What credit and fidelity read: the steps as the block showed them.
+ const shown = withFixes(c.skill, marks);
+ assert.deepEqual(shown.steps.map((s) => s.cmd), ["pnpm install --frozen-lockfile", "pnpm run build", "pnpm test"]);
+ assert.equal(shown.check, "pnpm test");
+ assert.deepEqual(saidIn(block, marks), ["l-1a2b3c4d"]);
+});
+
+test("recall, a step to leave out: marked on its line, and why after the steps", () => {
+ const c = skillOf(["npm ci", "npx prisma db push"]);
+ const never = learning("never run npx prisma db push", { kind: "decision", scope: "repo", id: "l-2b3c4d5e" });
+ const lines = runBlock(c, { ...blockCtx, marks: recallMarks(c.skill.steps, [never]) }).split("\n");
+ assert.equal(lines[2], " 2 npx prisma db push (against this repo's decision: see below)");
+ assert.ok(lines.includes(" This repo's decision \"never run npx prisma db push\" goes against step 2: leave it out, do that part its way, and tell the person."), lines.join("\n"));
+});
+
+test("a contradiction wins over a repeat; a plain learning quoted only in part repeats nothing; at most 3 learnings", () => {
+ const c = skillOf(["npm ci", "npm run build"]);
+ const marks = recallMarks(c.skill.steps, [learning("use npm"), PNPM]);
+ assert.deepEqual(marks.map((m) => [m.l.quote, m.against, m.steps]), [["use pnpm, not npm", true, [1, 2, 3]]]);
+ const partly = learning("use npm. Also the staging database is read-only.");
+ assert.equal(partly.whole, false);
+ assert.deepEqual(recallMarks(c.skill.steps, [partly]), []);
+ const guard = learning("always run npm ci", { kind: "guardrail" });
+ assert.deepEqual(recallMarks(c.skill.steps, [guard]), [], "a guardrail is enforced where the command runs; a repeat of one is not said here");
+ const many = ["use npm", "always run npm ci", "always run npm test", "always run npm run build"].map((t, k) => learning(t, { id: `l-0000000${k}` }));
+ assert.equal(recallMarks(c.skill.steps, many).length, 3);
+ assert.deepEqual(markLines([]), []);
+});
+
+/* ------------------------------------------------------------ init's fold */
+
+test("onlyRepeats: what init folds into a kept skill as a lesson", () => {
+ const steps = ["python scripts/gen_schema.py", "pytest -q"];
+ assert.equal(onlyRepeats("don't edit _schema.py by hand, run scripts/gen_schema.py", steps), true);
+ assert.equal(onlyRepeats("run scripts/gen_schema.py, then tell me what changed", steps), false, "part of it isn't a step");
+ assert.equal(onlyRepeats("use pnpm, not npm", ["npm test"]), false, "a contradiction is no repeat");
+ assert.equal(onlyRepeats("explain it simply", steps), false);
+});
++
++test("a learning saved by trail note, through #663's gate, is one part 7 reads: same store, live, and its steps follow it", () => {
++ const repo = mkdtempSync(join(tmpdir(), "follow-663-"));
++ const home = mkdtempSync(join(tmpdir(), "follow-663-home-"));
++ homes.push(repo, home);
++ spawnSync("git", ["init", "-q"], { cwd: repo });
++ spawnSync("git", ["config", "user.name", "Priya S"], { cwd: repo });
++ writeFileSync(join(repo, "package.json"), '{ "scripts": { "test": "vitest" } }\n');
++ spawnSync("git", ["add", "package.json"], { cwd: repo });
++ spawnSync("git", ["-c", "[email protected]", "commit", "-qm", "init"], { cwd: repo });
++ const body = "## Decided\n- Use pnpm, not npm.\n- Because npm rewrites the pnpm-lock.yaml that package.json is installed from.\n";
++ const r = spawnSync(process.execPath, ["--import", "tsx", join(process.cwd(), "src", "bin", "trail.ts"), "note", repo, "--title", "Use pnpm, not npm", "--touches", "package.json"], {
++ input: body,
++ encoding: "utf8",
++ env: { ...process.env, HOME: home, USERPROFILE: home, TRAIL_HOME: join(home, ".trail"), DO_NOT_TRACK: "1", CLAUDECODE: undefined, TRAIL_INVOKED_AS: undefined },
++ });
++ assert.equal(r.status, 0, r.stderr);
++ const ls = stepLearnings({ repoKeys: [], checkout: repo, env: { ...process.env, TRAIL_HOME: join(home, ".trail") } });
++ assert.deepEqual(ls.map((l) => l.quote), ["Use pnpm, not npm"]);
++ const c = compiled(testsSheet(), ls);
++ assert.deepEqual(c.steps.map((st) => st.cmd), ["pnpm install --frozen-lockfile", "pnpm run build", "pnpm test"]);
++ assert.match(c.followed ?? "", /this repo's learning "Use pnpm, not npm"/);
++});