Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
35.3 KB
Raw Blame
import { describe, test, expect } from "bun:test";
import { join } from "path";
import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "fs";
import { tmpdir } from "os";
import {
  checkResolvable,
  parseResolverEntries,
  extractDelegationTargets,
  extractTriggers,
} from "../src/core/check-resolvable.ts";

const SKILLS_DIR = join(import.meta.dir, "..", "skills");

describe("parseResolverEntries", () => {
  test('an orphan skills-index begin marker does not hide the resolver entries after it', () => {
    const content = '## Brain\n<!-- gbrain:skills:begin -->\n- a stale line\n| "query the brain" | `skills/query/SKILL.md` |\n';
    expect(parseResolverEntries(content).map((e) => e.skillPath)).toContain('skills/query/SKILL.md');
  });

  test("extracts skill paths from markdown table rows", () => {
    const content = `## Brain operations
| Trigger | Skill |
|---------|-------|
| "What do we know about" | \`skills/query/SKILL.md\` |
| Creating a person page | \`skills/enrich/SKILL.md\` |`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(2);
    expect(entries[0].skillPath).toBe("skills/query/SKILL.md");
    expect(entries[0].section).toBe("Brain operations");
    expect(entries[1].skillPath).toBe("skills/enrich/SKILL.md");
  });

  test("handles GStack entries (external skills)", () => {
    const content = `## Thinking skills
| Trigger | Skill |
|---------|-------|
| "Brainstorm" | GStack: office-hours |`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(1);
    expect(entries[0].isGStack).toBe(true);
  });

  test("handles identity/access rows (non-skill references)", () => {
    const content = `## Identity
| Trigger | Skill |
|---------|-------|
| Non-owner sends a message | Check \`ACCESS_POLICY.md\` before responding |`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(1);
    expect(entries[0].isGStack).toBe(true);
  });

  test("skips separator and header rows", () => {
    const content = `| Trigger | Skill |
|---------|-------|
| "query" | \`skills/query/SKILL.md\` |`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(1);
  });

  test("tracks section headings", () => {
    const content = `## Always-on
| Trigger | Skill |
|---------|-------|
| Every message | \`skills/signal-detector/SKILL.md\` |

## Brain operations
| Trigger | Skill |
|---------|-------|
| "What do we know" | \`skills/query/SKILL.md\` |`;
    const entries = parseResolverEntries(content);
    expect(entries[0].section).toBe("Always-on");
    expect(entries[1].section).toBe("Brain operations");
  });

  // ──────────────────────────────────────────────────────────────────────
  // v0.41.7.0 — Compact list-format support (OpenClaw-native shape)
  //
  // The list branch was added so `gbrain doctor` no longer reports every
  // skill as unreachable on agents that write the compact `- **name**: t1 | t2`
  // shape instead of the markdown table. The OpenClaw 306-skill regression
  // was 238 FAIL errors → 0 errors after this fix.
  // ──────────────────────────────────────────────────────────────────────

  test("[list] bold-name single trigger", () => {
    const content = `## Personal
- **gift-advisor**: gift idea`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(1);
    expect(entries[0].trigger).toBe("gift idea");
    expect(entries[0].skillPath).toBe("skills/gift-advisor/SKILL.md");
    expect(entries[0].isGStack).toBe(false);
    expect(entries[0].section).toBe("Personal");
  });

  test("[list] bold-name multi-trigger fan-out", () => {
    const content = `- **flight-tracker**: track my flight | flight status | when does my flight land`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(3);
    expect(entries.map(e => e.trigger)).toEqual([
      "track my flight",
      "flight status",
      "when does my flight land",
    ]);
    expect(entries.every(e => e.skillPath === "skills/flight-tracker/SKILL.md")).toBe(true);
  });

  test("[list] plain-name fallback (no bold markers)", () => {
    const content = `- gift-advisor: gift idea | birthday gift`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(2);
    expect(entries[0].skillPath).toBe("skills/gift-advisor/SKILL.md");
    expect(entries[1].trigger).toBe("birthday gift");
  });

  test("[list] D3: path suffix with Unicode → is stripped, not captured", () => {
    // D3 walkback: downstream consumers (routing-eval.ts skillSlugFromPath
    // and check-resolvable.ts:367 manifest derivation) assume the
    // skills/<name>/SKILL.md shape. Capturing the explicit path would
    // produce silent orphan_trigger warnings + routing-eval coverage
    // gaps for that skill. So the suffix is stripped and the path is
    // always derived from the name.
    const content = "- **quality**: lint the page → `skills/conventions/quality.md`";
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(1);
    expect(entries[0].trigger).toBe("lint the page");
    expect(entries[0].skillPath).toBe("skills/quality/SKILL.md"); // derived, NOT the captured path
  });

  test("[list] F4: path suffix with ASCII -> is also stripped", () => {
    const content = "- **quality**: lint the page -> `skills/conventions/quality.md`";
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(1);
    expect(entries[0].trigger).toBe("lint the page");
    expect(entries[0].skillPath).toBe("skills/quality/SKILL.md");
  });

  test("[list] ellipsis placeholder is dropped", () => {
    const content = `- **foo-skill**: bar | ... | baz`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(2);
    expect(entries.map(e => e.trigger)).toEqual(["bar", "baz"]);
  });

  test("[list] empty pipe segments are dropped", () => {
    const content = `- **foo-skill**: bar | | baz`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(2);
    expect(entries.map(e => e.trigger)).toEqual(["bar", "baz"]);
  });

  test("[mixed] table and list rows in the same file", () => {
    const content = `## Always-on
| Trigger | Skill |
|---------|-------|
| Every message | \`skills/signal-detector/SKILL.md\` |

## Personal
- **gift-advisor**: gift idea | what should I bring`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(3);
    expect(entries[0].skillPath).toBe("skills/signal-detector/SKILL.md");
    expect(entries[0].section).toBe("Always-on");
    expect(entries[1].skillPath).toBe("skills/gift-advisor/SKILL.md");
    expect(entries[1].section).toBe("Personal");
    expect(entries[2].section).toBe("Personal");
  });

  test("[list] section tracking across list entries", () => {
    const content = `## Personal
- **gift-advisor**: gift idea

## Travel
- **flight-tracker**: track my flight`;
    const entries = parseResolverEntries(content);
    expect(entries[0].section).toBe("Personal");
    expect(entries[1].section).toBe("Travel");
  });

  test("[list] D4 REGRESSION: prose bullets do not match as skill rows", () => {
    // The kebab-lowercase name regex deliberately rejects bold names
    // starting with an uppercase letter. This kills the noise class where
    // real AGENTS.md files have prose bullets like `- **Note**: …` that
    // would otherwise be parsed as fake skill rows pointing at
    // `skills/Note/SKILL.md`. Codex F2; D4 decision.
    const content = `- **Note**: this is a prose bullet
- **Convention**: see [some convention link]
- **TODO**: fix this later
- **Important**: read this carefully`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(0);
  });

  test("[list] D4 negative: convention-violating uppercase names are silently skipped", () => {
    // Documents the trade: a real skill named `MyTool` would not parse.
    // The user would notice on the first `gbrain doctor` run and lowercase it.
    const content = `- **MyTool**: this trigger silently disappears
- **camelCase**: also silently dropped`;
    const entries = parseResolverEntries(content);
    expect(entries.length).toBe(0);
  });
});

describe("extractTriggers", () => {
  const LF_FRONTMATTER =
    "---\nname: query\ndescription: Test\ntriggers:\n  - \"what do we know\"\n  - \"tell me about\"\ntools:\n  - search\n---\n\n# Body\n";

  test("parses triggers from LF-terminated frontmatter", () => {
    const triggers = extractTriggers(LF_FRONTMATTER);
    expect(triggers).toEqual(["what do we know", "tell me about"]);
  });

  test("parses triggers from CRLF-terminated frontmatter (Windows checkouts)", () => {
    // Regression: `core.autocrlf=true` is the Windows default. Without
    // CRLF→LF normalization, every Windows skill is reported as a false
    // mece_gap warning because the `^---\n` regex never matches `---\r\n`.
    const crlf = LF_FRONTMATTER.replace(/\n/g, "\r\n");
    const triggers = extractTriggers(crlf);
    expect(triggers).toEqual(["what do we know", "tell me about"]);
  });

  test("parses triggers from a single-line YAML flow sequence", () => {
    const fm = [
      "---",
      "name: transcript-insights",
      'triggers: ["analyze this transcript", podcast takeaways]',
      "---",
      "",
    ].join("\n");
    expect(extractTriggers(fm)).toEqual([
      "analyze this transcript",
      "podcast takeaways",
    ]);
  });

  test("parses triggers from a wrapped YAML flow sequence (#3887)", () => {
    const fm = [
      "---",
      "name: transcript-insights",
      "triggers: [analyze this transcript, podcast takeaways, video transcript insights, interview",
      "    takeaways, policy mechanisms from transcript]",
      "---",
      "",
    ].join("\n");
    expect(extractTriggers(fm)).toEqual([
      "analyze this transcript",
      "podcast takeaways",
      "video transcript insights",
      "interview takeaways",
      "policy mechanisms from transcript",
    ]);
  });

  test("returns [] when frontmatter is missing", () => {
    expect(extractTriggers("# Just a body, no frontmatter\n")).toEqual([]);
  });

  test("returns [] when triggers field is absent from frontmatter", () => {
    const fm = "---\nname: query\ndescription: Test\ntools:\n  - search\n---\n";
    expect(extractTriggers(fm)).toEqual([]);
  });

  test("strips surrounding quotes from trigger values", () => {
    const fm = "---\nname: x\ntriggers:\n  - \"double quoted\"\n  - 'single quoted'\n  - unquoted\n---\n";
    expect(extractTriggers(fm)).toEqual(["double quoted", "single quoted", "unquoted"]);
  });
});

describe("checkResolvable — real skills directory", () => {
  const report = checkResolvable(SKILLS_DIR);

  test("produces a report with summary", () => {
    expect(report.summary.total_skills).toBeGreaterThan(0);
    expect(typeof report.ok).toBe("boolean");
    expect(Array.isArray(report.issues)).toBe(true);
  });

  test("action strings are specific (contain file paths)", () => {
    for (const issue of report.issues) {
      expect(issue.action.length).toBeGreaterThan(10);
      // Action should mention a file or a specific fix
      expect(
        issue.action.includes("RESOLVER.md") ||
        issue.action.includes("SKILL.md") ||
        issue.action.includes("manifest") ||
        issue.action.includes("conventions/")
      ).toBe(true);
    }
  });

  test("unreachable issues have structured fix objects", () => {
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    for (const issue of unreachable) {
      expect(issue.fix).toBeDefined();
      expect(issue.fix!.type).toBe("add_trigger");
      expect(issue.fix!.file).toContain("RESOLVER.md");
    }
  });

  test("whitelisted skills (ingest, signal-detector, brain-ops) don't trigger MECE overlap", () => {
    const overlaps = report.issues.filter(i => i.type === "mece_overlap");
    for (const issue of overlaps) {
      // The skill field lists the overlapping skills
      expect(issue.skill).not.toContain("signal-detector");
      expect(issue.skill).not.toContain("brain-ops");
    }
  });

  test("summary counts are consistent", () => {
    expect(report.summary.reachable + report.summary.unreachable).toBe(report.summary.total_skills);
  });
});

// ---------------------------------------------------------------------------
// DRY detection — proximity-based suppression
// ---------------------------------------------------------------------------

function makeSkillsFixture(files: Record<string, string>): string {
  const dir = mkdtempSync(join(tmpdir(), "gbrain-dry-"));
  // Minimal RESOLVER.md and manifest.json so checkResolvable doesn't bail.
  const skillNames = Object.keys(files);
  const resolverRows = skillNames.map(n => `| "${n}" | \`skills/${n}/SKILL.md\` |`).join("\n");
  writeFileSync(join(dir, "RESOLVER.md"), `## Test\n| Trigger | Skill |\n|-----|-----|\n${resolverRows}\n`);
  writeFileSync(
    join(dir, "manifest.json"),
    JSON.stringify({ skills: skillNames.map(n => ({ name: n, path: `${n}/SKILL.md` })) }, null, 2)
  );
  for (const [name, body] of Object.entries(files)) {
    mkdirSync(join(dir, name), { recursive: true });
    // Skill conformance tests (elsewhere) check for frontmatter + triggers;
    // checkResolvable itself only needs the body.
    const frontmatter = `---\nname: ${name}\ndescription: test\ntriggers:\n  - "${name}"\n---\n`;
    writeFileSync(join(dir, name, "SKILL.md"), frontmatter + body);
  }
  return dir;
}

describe("extractDelegationTargets", () => {
  test("parses > **Convention:** callouts", () => {
    const refs = extractDelegationTargets(
      "> **Convention:** See `skills/conventions/quality.md` for citation rules.\n"
    );
    expect(refs).toEqual([{ convention: "conventions/quality.md", line: 1 }]);
  });

  test("parses > **Filing rule:** callouts", () => {
    const refs = extractDelegationTargets(
      "> **Filing rule:** Read `skills/_brain-filing-rules.md` before any new page.\n"
    );
    expect(refs).toEqual([{ convention: "_brain-filing-rules.md", line: 1 }]);
  });

  test("parses inline backtick references", () => {
    const refs = extractDelegationTargets(
      "some prose.\nSee `skills/conventions/quality.md` for details.\n"
    );
    expect(refs).toEqual([{ convention: "conventions/quality.md", line: 2 }]);
  });

  test("accepts a #anchor after .md and drops it from the path (#6704)", () => {
    const refs = extractDelegationTargets(
      "See `skills/conventions/quality.md#citations` and `skills/_brain-filing-rules.md#the-rule`.\n"
    );
    expect(refs).toEqual([
      { convention: "conventions/quality.md", line: 1 },
      { convention: "_brain-filing-rules.md", line: 1 },
    ]);
  });

  test("accepts an anchor with dots and non-ASCII letters (#6704)", () => {
    const refs = extractDelegationTargets("See `skills/conventions/quality.md#v1.2-引用`.\n");
    expect(refs).toEqual([{ convention: "conventions/quality.md", line: 1 }]);
  });

  test("ignores backticks pointing outside known delegation targets", () => {
    const refs = extractDelegationTargets(
      "See `skills/random/README.md` for unrelated notes.\n"
    );
    expect(refs).toHaveLength(0);
  });

  test("handles frontmatter-only skill (no body matches)", () => {
    const refs = extractDelegationTargets("---\nname: foo\n---\n");
    expect(refs).toHaveLength(0);
  });
});

describe("DRY detection — checkResolvable", () => {
  let dir: string;
  afterEachCleanup(() => dir && rmSync(dir, { recursive: true, force: true }));

  test("flags inlined notability rule with no reference", () => {
    dir = makeSkillsFixture({
      bad: "# BadSkill\n\nCheck the notability gate every time.\n",
    });
    const report = checkResolvable(dir);
    const dry = report.issues.filter(i => i.type === "dry_violation");
    expect(dry).toHaveLength(1);
    expect(dry[0].skill).toBe("bad");
  });

  test("suppresses DRY when > **Convention:** callout points at quality.md (notability)", () => {
    dir = makeSkillsFixture({
      good: `# GoodSkill\n\n> **Convention:** See \`skills/conventions/quality.md\` for rules.\n\nCheck the notability gate.\n`,
    });
    const report = checkResolvable(dir);
    const dry = report.issues.filter(i => i.type === "dry_violation");
    expect(dry).toHaveLength(0);
  });

  test("suppresses DRY when _brain-filing-rules.md is referenced for notability", () => {
    dir = makeSkillsFixture({
      good: `# GoodSkill\n\n> **Filing rule:** Read \`skills/_brain-filing-rules.md\`.\n\nCheck the notability gate.\n`,
    });
    const report = checkResolvable(dir);
    const dry = report.issues.filter(i => i.type === "dry_violation");
    expect(dry).toHaveLength(0);
  });

  test("does NOT suppress when reference is >40 lines from the match", () => {
    const filler = Array(50).fill("padding paragraph with no match.").join("\n");
    dir = makeSkillsFixture({
      distant: `> **Convention:** See \`skills/conventions/quality.md\`.\n\n${filler}\n\nCheck the notability gate now.\n`,
    });
    const report = checkResolvable(dir);
    const dry = report.issues.filter(i => i.type === "dry_violation");
    expect(dry).toHaveLength(1);
  });

  test("DOES suppress when reference is ~30 lines from the match", () => {
    const filler = Array(20).fill("padding paragraph with no match.").join("\n");
    dir = makeSkillsFixture({
      near: `> **Convention:** See \`skills/conventions/quality.md\`.\n\n${filler}\n\nCheck the notability gate now.\n`,
    });
    const report = checkResolvable(dir);
    const dry = report.issues.filter(i => i.type === "dry_violation");
    expect(dry).toHaveLength(0);
  });

  test("iron-law pattern does NOT accept _brain-filing-rules.md as delegation", () => {
    // iron-law's only accepted target is conventions/quality.md
    dir = makeSkillsFixture({
      filing: `> **Filing rule:** Read \`skills/_brain-filing-rules.md\`.\n\n## Iron Law: Back-Linking (MANDATORY)\n`,
    });
    const report = checkResolvable(dir);
    const dry = report.issues.filter(i => i.type === "dry_violation");
    expect(dry.length).toBeGreaterThanOrEqual(1);
  });
});

describe("v0.22.4 regression — actual repo skills/ has 0 errors", () => {
  test("repo skills/ pass check-resolvable cleanly (zero errors AND zero warnings)", () => {
    // The v0.22.4 (Part A) contract was zero warnings AND zero errors.
    // The v0.25.1 update relaxed it to allow `routing_miss` warnings as
    // informational — a stop-gap because the structural matcher
    // required substring-match against narrow triggers in RESOLVER.md
    // and natural paraphrases legitimately missed.
    //
    // v0.41.11 #1451 closes the drift bug class structurally:
    // frontmatter triggers + RESOLVER.md rows merge with UNION
    // semantics via `loadSkillTriggerIndex`. The 7 residual
    // `routing_miss` warnings on skillpack-harvest (and any future
    // drift on other skills) MUST be addressed at write time, not
    // tolerated at test time. The CI gate `bun run check:resolver`
    // (--strict, exit-1 on any warning) enforces this for PRs.
    //
    // The test now asserts the FULL contract: zero errors, zero
    // warnings. If a routing_miss reappears, the fix is to broaden
    // the skill's frontmatter `triggers:` so the realistic fixture
    // intent contains a trigger substring.
    const report = checkResolvable(SKILLS_DIR);
    const errors = report.issues.filter(i => i.severity === "error");
    const warnings = report.issues.filter(i => i.severity === "warning");
    expect(errors).toEqual([]);
    expect(warnings).toEqual([]);
  });
});

// bun:test has no beforeEach/afterEach at module scope cleanly interacting
// with closures; a small helper keeps cleanup readable and per-test.
function afterEachCleanup(fn: () => void) {
  const { afterEach } = require("bun:test");
  afterEach(fn);
}

// ---------------------------------------------------------------------------
// Low-confidence foreign skills dir: cwd_walk_up (tier 1b) is ungated, so it
// can land on a directory belonging to a different tool. One skill there
// coincidentally shipping a `triggers:` field used to flip every OTHER
// triggerless sibling from the soft "uninitialized" fallback into hard
// `unreachable` errors. Severity is softened only when ALL hold: found via
// cwd_walk_up, no resolver file contributes rows, unreachable outnumber
// reachable, and no manifest.json on disk. Everything else stays strict.
// ---------------------------------------------------------------------------

function makeSkillWithoutTriggers(dir: string, name: string): void {
  mkdirSync(join(dir, name), { recursive: true });
  writeFileSync(
    join(dir, name, "SKILL.md"),
    "---\n" +
    `name: ${name}\n` +
    "description: belongs to a different tool, no triggers field\n" +
    "---\n" +
    "body\n"
  );
}

function makeSkillWithTriggers(dir: string, name: string): void {
  mkdirSync(join(dir, name), { recursive: true });
  writeFileSync(
    join(dir, name, "SKILL.md"),
    "---\n" +
    `name: ${name}\n` +
    "description: also unrelated, but happens to declare triggers\n" +
    "triggers:\n" +
    "  - \"some phrase\"\n" +
    "---\n" +
    "body\n"
  );
}

// Sparse trigger coverage (3 triggerless : 1 with triggers) -- matches the
// real-world repro (1 of 26 skills coincidentally had triggers:). No
// RESOLVER.md, no AGENTS.md, no manifest.json -- deriveManifest() walks
// the directory listing instead, same as a real foreign tool's skills/
// dir with no gbrain awareness whatsoever.
function makeSparseForeignSkillsFixture(): string {
  const dir = mkdtempSync(join(tmpdir(), "gbrain-foreign-skills-"));
  makeSkillWithoutTriggers(dir, "some-unrelated-tool-skill");
  makeSkillWithoutTriggers(dir, "another-unrelated-skill");
  makeSkillWithoutTriggers(dir, "yet-another-unrelated-skill");
  // The one coincidental trigger-bearing skill that defeats the
  // triggerEntries.length===0 fallback in real-world repros.
  makeSkillWithTriggers(dir, "coincidentally-has-triggers");
  return dir;
}

// Dense trigger coverage (3 with triggers : 1 triggerless) -- a mostly-
// migrated real skillpack whose RESOLVER.md/AGENTS.md was merely deleted
// by accident. Must NOT be softened even via cwd_walk_up with no
// resolver file present (resolver-absence alone isn't proof of "foreign").
function makeDenseSkillpackFixture(): string {
  const dir = mkdtempSync(join(tmpdir(), "gbrain-dense-skillpack-"));
  makeSkillWithTriggers(dir, "migrated-skill-one");
  makeSkillWithTriggers(dir, "migrated-skill-two");
  makeSkillWithTriggers(dir, "migrated-skill-three");
  makeSkillWithoutTriggers(dir, "not-yet-migrated-skill");
  return dir;
}

describe("checkResolvable — low-confidence foreign skills dir", () => {
  let dir: string;
  afterEachCleanup(() => {
    if (dir) rmSync(dir, { recursive: true, force: true });
  });

  test("cwd_walk_up + no RESOLVER.md + sparse triggers: unreachable is downgraded to warning", () => {
    dir = makeSparseForeignSkillsFixture();
    const report = checkResolvable(dir, { skillsDirSource: "cwd_walk_up" });
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    expect(unreachable.length).toBe(3);
    expect(unreachable.map(i => i.skill).sort()).toEqual([
      "another-unrelated-skill",
      "some-unrelated-tool-skill",
      "yet-another-unrelated-skill",
    ]);
    for (const issue of unreachable) {
      expect(issue.severity).toBe("warning");
    }
    // Downgraded severity must actually move the issues out of errors[]
    // and into warnings[] (checkResolvable filters on .severity at the
    // end) -- otherwise health_score still takes the -20 hit.
    expect(report.errors.some(i => i.type === "unreachable")).toBe(false);
    expect(report.warnings.some(i => i.type === "unreachable")).toBe(true);
  });

  test("no skillsDirSource (higher-confidence tiers): unreachable stays a hard error", () => {
    dir = makeSparseForeignSkillsFixture();
    const report = checkResolvable(dir);
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    expect(unreachable.length).toBe(3);
    for (const issue of unreachable) {
      expect(issue.severity).toBe("error");
    }
    expect(report.errors.some(i => i.type === "unreachable")).toBe(true);
  });

  test("cwd_walk_up but RESOLVER.md present: stays a hard error (real skillpack, not foreign)", () => {
    dir = makeSparseForeignSkillsFixture();
    writeFileSync(
      join(dir, "RESOLVER.md"),
      "## Brain operations\n| Trigger | Skill |\n|---------|-------|\n"
    );
    const report = checkResolvable(dir, { skillsDirSource: "cwd_walk_up" });
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    expect(unreachable.length).toBeGreaterThan(0);
    for (const issue of unreachable) {
      expect(issue.severity).toBe("error");
    }
  });

  test("cwd_walk_up + no RESOLVER.md but DENSE trigger coverage: unreachable stays a hard error", () => {
    // A mostly-migrated real skillpack whose RESOLVER.md/AGENTS.md was
    // merely deleted by accident (majority already reachable via
    // triggers:) must still fail loudly.
    dir = makeDenseSkillpackFixture();
    const report = checkResolvable(dir, { skillsDirSource: "cwd_walk_up" });
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    expect(unreachable.length).toBe(1);
    expect(unreachable[0].skill).toBe("not-yet-migrated-skill");
    expect(unreachable[0].severity).toBe("error");
    expect(report.errors.some(i => i.type === "unreachable")).toBe(true);
  });

  test("cwd_walk_up + no RESOLVER.md + sparse triggers BUT explicit manifest.json: unreachable stays a hard error", () => {
    // An explicit manifest.json is itself a deliberate "this is a gbrain
    // skillpack" declaration -- a foreign tool's directory never ships
    // one. Its presence keeps enforcement strict.
    dir = makeSparseForeignSkillsFixture();
    writeFileSync(
      join(dir, "manifest.json"),
      JSON.stringify({
        skills: [
          { name: "some-unrelated-tool-skill", path: "some-unrelated-tool-skill/SKILL.md" },
          { name: "another-unrelated-skill", path: "another-unrelated-skill/SKILL.md" },
          { name: "yet-another-unrelated-skill", path: "yet-another-unrelated-skill/SKILL.md" },
          { name: "coincidentally-has-triggers", path: "coincidentally-has-triggers/SKILL.md" },
        ],
      })
    );
    const report = checkResolvable(dir, { skillsDirSource: "cwd_walk_up" });
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    expect(unreachable.length).toBe(3);
    for (const issue of unreachable) {
      expect(issue.severity).toBe("error");
    }
    expect(report.errors.some(i => i.type === "unreachable")).toBe(true);
  });

  test("cwd_walk_up + no RESOLVER.md + sparse triggers BUT MALFORMED manifest.json: unreachable stays a hard error", () => {
    // loadOrDeriveManifest's `derived` flag is true both when manifest.json
    // is absent AND when it exists but fails to parse. A corrupted
    // manifest.json on a real skillpack is exactly what doctor exists to
    // catch, so the downgrade keys on on-disk absence, not `derived`.
    dir = makeSparseForeignSkillsFixture();
    writeFileSync(join(dir, "manifest.json"), "{ this is not valid json");
    const report = checkResolvable(dir, { skillsDirSource: "cwd_walk_up" });
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    expect(unreachable.length).toBe(3);
    for (const issue of unreachable) {
      expect(issue.severity).toBe("error");
    }
    expect(report.errors.some(i => i.type === "unreachable")).toBe(true);
  });

  test("cwd_walk_up + generic AGENTS.md with no resolver rows + sparse triggers: unreachable is STILL downgraded to warning", () => {
    // `resolverPathOrNull` is filename-only, not content-aware. A foreign
    // tool's generic prose AGENTS.md contributes zero resolver rows, so it
    // must not disable the downgrade; the check keys on a resolver_md-
    // sourced entry, not `entries.length`.
    dir = makeSparseForeignSkillsFixture();
    writeFileSync(
      join(dir, "AGENTS.md"),
      "# Agent Instructions\n\nThis is a generic agent configuration file for an unrelated tool. " +
        "It has no resolver routing table -- just prose.\n"
    );
    const report = checkResolvable(dir, { skillsDirSource: "cwd_walk_up" });
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    expect(unreachable.length).toBe(3);
    expect(unreachable.map(i => i.skill).sort()).toEqual([
      "another-unrelated-skill",
      "some-unrelated-tool-skill",
      "yet-another-unrelated-skill",
    ]);
    for (const issue of unreachable) {
      expect(issue.severity).toBe("warning");
    }
    expect(report.errors.some(i => i.type === "unreachable")).toBe(false);
    expect(report.warnings.some(i => i.type === "unreachable")).toBe(true);
  });

  test("cwd_walk_up + AGENTS.md WITH real resolver rows + sparse triggers elsewhere: unreachable stays a hard error", () => {
    // Inverse of the above: when the found AGENTS.md actually carries a
    // resolver table (source: 'resolver_md'), it's real routing intent,
    // not a foreign convention collision -- must NOT be downgraded.
    dir = makeSparseForeignSkillsFixture();
    writeFileSync(
      join(dir, "AGENTS.md"),
      "## Routing\n\n| trigger | skill |\n| --- | --- |\n" +
        "| some real trigger | `skills/some-unrelated-tool-skill/SKILL.md` |\n"
    );
    const report = checkResolvable(dir, { skillsDirSource: "cwd_walk_up" });
    const unreachable = report.issues.filter(i => i.type === "unreachable");
    expect(unreachable.length).toBeGreaterThan(0);
    for (const issue of unreachable) {
      expect(issue.severity).toBe("error");
    }
    expect(report.errors.some(i => i.type === "unreachable")).toBe(true);
  });

  test("OpenClaw workspace discovery + prose AGENTS.md at the root + third-party skills: unreachable is a warning; a manifest.json keeps it an error", () => {
    // An OpenClaw workspace's skills/ can hold only another tool's skills
    // (OpenClaw loads them natively) under its default prose AGENTS.md.
    dir = mkdtempSync(join(tmpdir(), "gbrain-openclaw-workspace-"));
    writeFileSync(join(dir, "AGENTS.md"), "# AGENTS.md\n\nWorkspace instructions, no routing table.\n");
    const skills = join(dir, "skills");
    for (const name of ["third-party-one", "third-party-two", "third-party-three", "third-party-four"]) makeSkillWithoutTriggers(skills, name);
    for (const source of ["openclaw_workspace_home_root", "openclaw_workspace_env_root", "openclaw_workspace_home", "openclaw_workspace_env"] as const) {
      const report = checkResolvable(skills, { skillsDirSource: source });
      expect(report.issues.filter(i => i.type === "unreachable").length).toBe(4);
      expect(report.errors.some(i => i.type === "unreachable")).toBe(false);
    }
    writeFileSync(join(skills, "manifest.json"), JSON.stringify({ skills: ["third-party-one", "third-party-two", "third-party-three", "third-party-four"].map(name => ({ name, path: `${name}/SKILL.md` })) }));
    const strict = checkResolvable(skills, { skillsDirSource: "openclaw_workspace_home_root" });
    expect(strict.errors.some(i => i.type === "unreachable")).toBe(true);
  });
});

describe("missing_file is reported once per skill path, not once per trigger row (wave review)", () => {
  test("three trigger rows for one absent skill file → one missing_file issue", () => {
    const dir = mkdtempSync(join(tmpdir(), "gbrain-missing-file-"));
    try {
      writeFileSync(
        join(dir, "RESOLVER.md"),
        "## Test\n| Trigger | Skill |\n|-----|-----|\n" +
          '| "first" | `skills/ghost-skill/SKILL.md` |\n' +
          '| "second" | `skills/ghost-skill/SKILL.md` |\n' +
          '| "third" | `skills/ghost-skill/SKILL.md` |\n',
      );
      writeFileSync(join(dir, "manifest.json"), JSON.stringify({ skills: [] }));
      const report = checkResolvable(dir);
      const missing = report.issues.filter(i => i.type === "missing_file");
      expect(missing).toHaveLength(1);
      expect(missing[0].skill).toBe("skills/ghost-skill/SKILL.md");
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

// ---------------------------------------------------------------------------
// Fixture trees for the unreachable-skill fix shape and the MECE whitelist.
// The real skills/ tree has no unreachable skills and no overlaps, so these
// contracts need their own inputs.
// ---------------------------------------------------------------------------

function writeSkillTree(skills: { name: string; triggers: string[]; resolverRow?: string }[]): string {
  const dir = mkdtempSync(join(tmpdir(), "gbrain-resolvable-"));
  const rows = skills.filter(s => s.resolverRow).map(s => `| "${s.resolverRow}" | \`skills/${s.name}/SKILL.md\` |`).join("\n");
  writeFileSync(join(dir, "RESOLVER.md"), `## Brain operations\n| Trigger | Skill |\n|-----|-----|\n${rows}\n`);
  writeFileSync(join(dir, "manifest.json"), JSON.stringify({ skills: skills.map(s => ({ name: s.name, path: `${s.name}/SKILL.md` })) }, null, 2));
  for (const s of skills) {
    mkdirSync(join(dir, s.name), { recursive: true });
    const triggers = s.triggers.length ? `triggers:\n${s.triggers.map(t => `  - "${t}"`).join("\n")}\n` : "";
    writeFileSync(join(dir, s.name, "SKILL.md"), `---\nname: ${s.name}\ndescription: fixture\n${triggers}---\n# ${s.name}\n`);
  }
  return dir;
}

describe("checkResolvable — fixture trees", () => {
  test("a manifest skill with no trigger anywhere is an unreachable error carrying an add_trigger fix for RESOLVER.md", () => {
    const dir = writeSkillTree([
      { name: "alpha-notes", triggers: ["file an alpha note"] },
      { name: "orphan-skill", triggers: [] },
    ]);
    try {
      const report = checkResolvable(dir);
      const unreachable = report.issues.filter(i => i.type === "unreachable");
      expect(unreachable.map(i => i.skill)).toEqual(["orphan-skill"]);
      expect(unreachable[0].severity).toBe("error");
      expect(unreachable[0].fix).toEqual({
        type: "add_trigger",
        file: join(dir, "RESOLVER.md"),
        section: "Brain operations",
        skill_path: "skills/orphan-skill/SKILL.md",
      });
      expect(report.ok).toBe(false);
      expect(report.summary).toMatchObject({ total_skills: 2, reachable: 1, unreachable: 1 });
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test("shared triggers report a MECE overlap among non-whitelisted skills only; whitelisted skills need no triggers", () => {
    const dir = writeSkillTree([
      { name: "alpha-notes", triggers: ["capture this", "save a note"] },
      { name: "beta-notes", triggers: ["capture this"] },
      { name: "brain-ops", triggers: ["capture this", "save a note"] },
      { name: "signal-detector", triggers: ["save a note"] },
      { name: "ingest", triggers: [], resolverRow: "ingest anything" },
    ]);
    try {
      const report = checkResolvable(dir);
      const overlaps = report.issues.filter(i => i.type === "mece_overlap");
      expect(overlaps.map(i => [i.skill, i.message])).toEqual([
        ["alpha-notes, beta-notes", "Trigger 'capture this' matches multiple skills: alpha-notes, beta-notes"],
      ]);
      expect(report.summary.overlaps).toBe(1);
      expect(report.issues.filter(i => i.type === "mece_gap")).toEqual([]);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});