@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/src/modules/skills/skills.contract.ts

@@ -2,7 +2,10 @@
  * Skills are reusable specialist instructions living under `Plugins/<plugin>/<name>/SKILL.md`
  * in the KB repo. Discovery/loading is pinned to the DEFAULT branch — the catalog
  * is a single global, released set (a skill on a draft isn't discoverable until
- * merged). Progressive disclosure: `listSkills` = name + description (level 1),
+ * merged) — UNLESS the caller names a branch, which reads the skills as they are
+ * on that draft and marks the ones the default branch does not have yet (see
+ * {@link ListSkillsOptions} and `unmerged` below). Progressive disclosure:
+ * `listSkills` = name + description (level 1),
  * `getSkill` = full body + bundled-file paths (level 2), `getSkill(file)` = a
  * bundled file's content (level 3).
  */
@@ -38,6 +41,17 @@ export interface SkillSummary {
    * surfaces, which load skills by name and never by plugin.
    */
   plugins?: PluginMembership[];
+  /**
+   * Set only on an answer read from a branch OTHER than the default, and only
+   * on a skill whose folder DIFFERS there: it exists only on that branch, or
+   * its content was changed on it. Nobody has approved what such a skill says
+   * — it is not merged. A skill the branch shares byte-for-byte with the
+   * default branch carries no mark, because there is nothing unapproved about
+   * it.
+   */
+  unmerged?: true;
+  /** With `unmerged`: the branch the skill was read from. */
+  branch?: string;
 }
 
 export interface Skill extends SkillSummary {
@@ -57,6 +71,15 @@ export interface SkillFileContent {
   /** Repo-root-relative path of the file. */
   path: string;
   content: string;
+  /**
+   * As on {@link SkillSummary} — the file came off a branch whose copy of this
+   * skill differs from the default branch's. A note BESIDE the content, never
+   * inside it: a bundled file is a script or a data file, and a sentence
+   * prepended to one is a syntax error rather than a warning. A skill's body,
+   * which is prose an agent reads, carries the line instead.
+   */
+  unmerged?: true;
+  branch?: string;
 }
 
 export type GetSkillResult =
@@ -64,32 +87,76 @@ export type GetSkillResult =
   | { ok: true; kind: 'file'; file: SkillFileContent }
   | { ok: false; error: 'not_found' | 'forbidden' | 'invalid_file' }
   /**
-   * A `version` was asked for that no commit of the skill's `SKILL.md` on the
-   * default branch declared. `versions` is every version the history did
-   * declare, newest first — the caller picks from those or asks for the
-   * latest by leaving `version` out.
+   * A `version` was asked for that no commit of the skill's `SKILL.md`
+   * declared in the history searched — the default branch's, or `branch`'s own
+   * when a branch was named. `versions` is every version that history did
+   * declare, newest first, so it too is that branch's answer: the caller picks
+   * from those or asks for the latest by leaving `version` out.
    */
   | { ok: false; error: 'version_not_found'; versions: string[] };
 
+/**
+ * What `listSkills` may be asked beyond a caller.
+ *
+ * The branch is the ONE thing that moves the catalog off the default branch.
+ * Omitted (or naming the default branch itself), every answer is exactly the
+ * released one — the browser menu and the MCP prompts take that path and are
+ * unaffected by this option existing.
+ */
+export interface ListSkillsOptions {
+  /**
+   * Read the skills as they are on this branch instead of the default one: a
+   * skill that exists only there is listed, one changed there is listed with
+   * its changed description and version, one deleted there is absent. Access
+   * is judged on THAT branch, with that branch's access rules. A branch the
+   * platform has never heard of is a 404 naming it, as on the file tools.
+   *
+   * Everything listed from a non-default branch that differs from the default
+   * carries `unmerged: true` and this branch name: nobody approved it.
+   */
+  branch?: string;
+}
+
 /** What `getSkill` may be asked beyond a name and a file. */
 export interface GetSkillOptions {
   /**
    * The version the skill declared in the copy to load — its
    * `metadata.version`, else a top-level `version`, else `lifecycle.version`.
    * Omitted, the skill is loaded as it is now — the latest. Given, the
-   * default branch's history of the skill's `SKILL.md` is searched newest
-   * first for the most recent commit that declared exactly this version, and
-   * the skill (body, bundled files, or the one `file` asked for) is served as
-   * it was at that commit. Read access is the caller's access to the skill as
-   * it is now: a skill you may read, you may read the history of.
+   * history of the skill's `SKILL.md` is searched newest first for the most
+   * recent commit that declared exactly this version, and the skill (body,
+   * bundled files, or the one `file` asked for) is served as it was at that
+   * commit. Read access is the caller's access to the skill as it is now: a
+   * skill you may read, you may read the history of.
+   *
+   * The history searched is the one belonging to the branch being read: the
+   * default branch's, or — with `branch` — that branch's own, including the
+   * `versions` a `version_not_found` lists.
    */
   version?: string;
+  /**
+   * Load the skill as it is on this branch instead of the default one — see
+   * {@link ListSkillsOptions.branch}, which it mirrors exactly: same branch
+   * resolution, same 404, same access rules read on that branch. When the
+   * skill differs from the default branch's copy, the body returned BEGINS
+   * with one line saying so (a bundled file carries `unmerged` beside its
+   * content instead).
+   *
+   * With `version`, the history searched is that branch's own. The agent
+   * tools refuse the two together rather than make a caller reason about which
+   * branch a version came from; this service answers both, because the
+   * combination has exactly one sensible meaning.
+   */
+  branch?: string;
 }
 
 /**
- * The slice of git the skill service reads history through — the default
- * branch's own clone, never a caller's draft. Narrow on purpose: the catalog
- * is a disk scan and needs none of this; only a `version` asks for history.
+ * The slice of git the skill service reads history through. Every call names
+ * the workspace to read in, which is always the clone the skill itself was
+ * scanned out of — the default branch's, or the draft a `branch` named, so a
+ * version asked for on a branch is answered from that branch's history.
+ * Narrow on purpose: the catalog is a disk scan and needs none of this; only
+ * a `version` asks for history.
  */
 export interface SkillHistorySource {
   /** The commits (newest first) on `ref` that touched `repoRelativePath`, at most `limit`. */
@@ -133,17 +200,23 @@ export interface IPendingSkillService {
 
 export interface ISkillService {
   /**
-   * The default-branch skill catalog. When `userEmail` is given, filtered to
-   * skills that user may read (`canRead`); omit it for the global set (used to
-   * compose the tool descriptions in the manual).
+   * The default-branch skill catalog — or `options.branch`'s, when one is
+   * named. When `userEmail` is given, filtered to skills that user may read
+   * (`canRead`, judged on the branch being read); omit it for the global set
+   * (used to compose the tool descriptions in the manual, which always
+   * describe the default branch).
    */
-  listSkills(userEmail?: string): Promise<SkillSummary[]>;
+  listSkills(userEmail?: string, options?: ListSkillsOptions): Promise<SkillSummary[]>;
   /**
    * Load a skill's body (+ files), or a bundled file's content when `file` is
    * given — as it is now, or as it was at the commit that declared
    * `options.version` (see {@link GetSkillOptions}).
    */
   getSkill(userEmail: string, name: string, file?: string, options?: GetSkillOptions): Promise<GetSkillResult>;
-  /** Drop the cached catalog (call after a merge to the default branch). */
+  /**
+   * Drop the cached DEFAULT-branch catalog (call after a merge to it). A
+   * branch read is never cached, so an agent that writes a skill on its draft
+   * and lists it right after sees what it just wrote.
+   */
   invalidate(): void;
 }

package/src/modules/skills/skills.service.ts

@@ -3,6 +3,7 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('skills');
 import fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { parseDocument } from 'yaml';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
@@ -13,6 +14,7 @@ import { TtlCache } from '../../shared/ttl-cache.js';
 import type {
   GetSkillOptions,
   ISkillService,
+  ListSkillsOptions,
   GetSkillResult,
   Skill,
   SkillHistorySource,
@@ -37,12 +39,43 @@ interface ParsedSkill {
 }
 
 /**
- * Reads skills from the DEFAULT-branch workspace (never the caller's branch), so
- * the catalog is one global, released set. Results are cached briefly and on a
- * merge to default the cache should be dropped via `invalidate()`.
+ * One branch's skills and where they were read from. The workspace rides along
+ * because every later question — may this caller read the skill, what does its
+ * folder contain, what is in its history — has to be asked of the SAME clone
+ * the skills were scanned out of, never of whichever branch happens to be the
+ * default.
+ */
+interface Catalog {
+  wsId: string;
+  /** Absolute path of that workspace's KB clone; empty when there was none to read. */
+  kbRoot: string;
+  skills: ParsedSkill[];
+  /**
+   * Folder digests computed out of THIS catalog's clone, by skill folder —
+   * filled lazily by `digestOf`, so it lives exactly as long as the catalog
+   * does. On the released catalog that is the cache's TTL (and a merge to
+   * default drops both together); on a branch catalog, which is never cached,
+   * it is one call.
+   */
+  digests: Map<string, Promise<string | null>>;
+}
+
+/**
+ * Reads skills from the DEFAULT-branch workspace, so the catalog is one global,
+ * released set. Results are cached briefly and on a merge to default the cache
+ * should be dropped via `invalidate()`.
+ *
+ * A caller may instead NAME a branch (`branch` on either method) and read the
+ * skills as they are on that draft — what an agent needs to try a skill it has
+ * just written, before anyone has approved it. That read is deliberately
+ * austere: no cache (the draft changes under the agent's own hands), access
+ * judged in that branch's own clone with that branch's rules, a 404 for a
+ * branch nobody pushed, and everything the default branch does not already
+ * serve marked `unmerged` — with one line at the top of a body saying it is
+ * not approved.
  */
 export class SkillService implements ISkillService {
-  private readonly cache: TtlCache<ParsedSkill[]>;
+  private readonly cache: TtlCache<Catalog>;
   /**
    * Where a `version` is read from — git, attached by the composition root
    * once the git service exists (it is built after this one). Without it a
@@ -73,16 +106,21 @@ export class SkillService implements ISkillService {
     this.cache.invalidate();
   }
 
-  async listSkills(userEmail?: string): Promise<SkillSummary[]> {
-    const skills = await this.scan();
-    const summaries = skills.map((s) => s.summary);
-    if (!userEmail) return summaries;
-    const allowed = await this.readable(userEmail, summaries.map((s) => s.path));
-    // Fail closed: keep a skill only on an explicit `true` verdict — a missing
-    // entry counts as denied, matching the KB's default-deny read model (and the
-    // tool-manuals catalog). `!== false` would silently EXPOSE a skill any time
-    // the checker skips a path.
-    return summaries.filter((s) => allowed.get(`${s.path}/SKILL.md`) === true);
+  async listSkills(userEmail?: string, options: ListSkillsOptions = {}): Promise<SkillSummary[]> {
+    const { catalog, branch } = await this.catalogFor(options.branch);
+    const visible = userEmail ? await this.readableSkills(catalog, userEmail) : catalog.skills;
+    if (branch === undefined) return visible.map((s) => s.summary);
+    // Marking reads both copies of a folder, so it happens only here, on a
+    // branch read that asked for it — the released catalog every other surface
+    // takes never pays for it. The released catalog is resolved ONCE for the
+    // whole listing: per skill, a cold cache would start one scan of the
+    // default branch per skill.
+    const released = await this.defaultCatalog();
+    return Promise.all(
+      visible.map(async (s) =>
+        (await this.differs(released, catalog, s)) ? { ...s.summary, unmerged: true as const, branch } : s.summary,
+      ),
+    );
   }
 
   async getSkill(
@@ -92,10 +130,12 @@ export class SkillService implements ISkillService {
     options: GetSkillOptions = {},
   ): Promise<GetSkillResult> {
     if (!isSafeSkillName(name)) return { ok: false, error: 'not_found' };
-    const found = (await this.scan()).find((s) => s.summary.name === name);
+    const { catalog, branch } = await this.catalogFor(options.branch);
+    const found = catalog.skills.find((s) => s.summary.name === name);
+    // A skill the branch deleted is not a skill as far as this answer goes:
+    // the same `not_found` a name nobody ever used gets.
     if (!found) return { ok: false, error: 'not_found' };
 
-    const wsId = this.kb.defaultWorkspaceId();
     // Through `readable`, not a bare `canRead`: the two gates must never
     // disagree. `canRead` reads a file's own frontmatter rules off disk on
     // every call while `canReadBatch` resolves them through a per-workspace
@@ -109,19 +149,51 @@ export class SkillService implements ISkillService {
     // rules would be authorized against the previous verdict until the memo
     // expires. It is not: `registerCatalogCacheInvalidation` drops the gate on
     // the same default-branch signal that drops this catalog, so the listing
-    // and the load are refreshed by one event or by neither.
-    const allowed = await this.readable(userEmail, [found.summary.path]);
+    // and the load are refreshed by one event or by neither. A branch read
+    // caches no catalog of its own, so the same pair of gates still answers
+    // for it — in that branch's workspace, where its own rules live.
+    const allowed = await this.readable(catalog.wsId, userEmail, [found.summary.path]);
     if (allowed.get(`${found.summary.path}/SKILL.md`) !== true) {
-      return { ok: false, error: 'forbidden' };
+      // On the default branch: `forbidden` — the skill is released, everyone
+      // knows the catalog has it, and naming the refusal is what sends the
+      // caller to ask for access.
+      //
+      // On a draft: the same answer a name nobody ever used gets. A skill
+      // being written on a branch the caller cannot read there is one they
+      // must not learn exists either, and the listing already hides it — a
+      // load that answered `forbidden` would confirm it by the back door.
+      return { ok: false, error: branch === undefined ? 'forbidden' : 'not_found' };
     }
 
+    const result = await this.serve(catalog, found, name, file, options.version);
+    if (branch === undefined || !result.ok) return result;
+    // The mark and the line say "nobody approved this", so they go on exactly
+    // what the default branch does not already serve. A skill the branch never
+    // touched IS the released one — read through a draft's clone, but the same
+    // bytes — and claiming otherwise would teach agents to ignore the warning.
+    if (!(await this.differs(await this.defaultCatalog(), catalog, found))) return result;
+    return asUnmerged(result, branch);
+  }
+
+  /**
+   * The skill (or the one bundled file, or the copy a `version` names) out of
+   * the catalog it was found in. Everything the caller is allowed to see has
+   * been settled by `getSkill`; this only reads.
+   */
+  private async serve(
+    catalog: Catalog,
+    found: ParsedSkill,
+    name: string,
+    file: string | undefined,
+    version: string | undefined,
+  ): Promise<GetSkillResult> {
     // A version other than the one on disk now is read out of history —
     // after the access check above, which is the caller's access to the skill
     // as it is now. The version on disk IS the latest, whatever it is called,
     // so asking for it by name answers from disk like asking for nothing.
-    const wanted = options.version?.trim();
+    const wanted = version?.trim();
     if (wanted !== undefined && wanted.length > 0 && wanted !== found.summary.version) {
-      return this.getSkillAtVersion(wsId, found, name, wanted, file);
+      return this.getSkillAtVersion(catalog.wsId, found, name, wanted, file);
     }
 
     if (file !== undefined) {
@@ -131,7 +203,7 @@ export class SkillService implements ISkillService {
       // the ignore rules, so a path that is not in it is one they hid.
       if (!found.files.includes(repoPath)) return { ok: false, error: 'not_found' };
       try {
-        const content = await this.workspaceService.readFile(wsId, `${this.kbDirName}/${repoPath}`);
+        const content = await this.workspaceService.readFile(catalog.wsId, `${this.kbDirName}/${repoPath}`);
         return { ok: true, kind: 'file', file: { name, file, path: repoPath, content } };
       } catch {
         return { ok: false, error: 'not_found' };
@@ -150,8 +222,9 @@ export class SkillService implements ISkillService {
   // --- internal ---------------------------------------------------------------
 
   /**
-   * The skill as it was at the most recent default-branch commit whose
-   * `SKILL.md` declared `wanted` — walking that file's history newest first,
+   * The skill as it was at the most recent commit of `wsId`'s clone whose
+   * `SKILL.md` declared `wanted` — the default branch's history, or a named
+   * branch's own — walking that file's history newest first,
    * so a version that was published, superseded and republished answers with
    * its latest copy. Every version the walk met is collected on the way, so
    * a miss can say what there is to ask for.
@@ -213,40 +286,150 @@ export class SkillService implements ISkillService {
    * The ONE read gate both surfaces resolve through, keyed by each skill's
    * `SKILL.md`. Shared so `listSkills` and `getSkill` can only ever give the
    * same verdict about the same skill — see the note at the `getSkill` call.
+   *
+   * `wsId` is the workspace the skills were READ from, so a branch's answer is
+   * judged by the `roles.yaml`, groups and `access.md` tree that branch has —
+   * which is the point: a draft may be where a skill's access rules are being
+   * changed, and judging it by the default branch's rules would answer about a
+   * tree the caller is not reading.
    */
-  private async readable(userEmail: string, skillFolders: string[]): Promise<Map<string, boolean>> {
-    return this.accessControl.canReadBatch(
-      this.kb.defaultWorkspaceId(),
-      userEmail,
-      skillFolders.map((p) => `${p}/SKILL.md`),
-    );
+  private async readable(
+    wsId: string,
+    userEmail: string,
+    skillFolders: string[],
+  ): Promise<Map<string, boolean>> {
+    return this.accessControl.canReadBatch(wsId, userEmail, skillFolders.map((p) => `${p}/SKILL.md`));
+  }
+
+  /** The skills of `catalog` this caller may read, by the gate above. */
+  private async readableSkills(catalog: Catalog, userEmail: string): Promise<ParsedSkill[]> {
+    const allowed = await this.readable(catalog.wsId, userEmail, catalog.skills.map((s) => s.summary.path));
+    // Fail closed: keep a skill only on an explicit `true` verdict — a missing
+    // entry counts as denied, matching the KB's default-deny read model (and the
+    // tool-manuals catalog). `!== false` would silently EXPOSE a skill any time
+    // the checker skips a path.
+    return catalog.skills.filter((s) => allowed.get(`${s.summary.path}/SKILL.md`) === true);
   }
 
-  private async scan(): Promise<ParsedSkill[]> {
+  /**
+   * The catalog an answer comes out of, and the branch to MARK it with —
+   * `branch` undefined when the answer is the released one, so every surface
+   * that names no branch is answered exactly as it was before this input
+   * existed.
+   */
+  private async catalogFor(branch?: string): Promise<{ catalog: Catalog; branch?: string }> {
+    const named = branch?.trim();
+    // A blank branch is a missing one, and the safe reading of a missing
+    // branch is the released catalog: it serves only approved skills. A name
+    // that is REAL but unknown is not reinterpreted that way — it is the 404
+    // `readBranch` lets through. Naming the default branch is the same answer
+    // as naming nothing, mark included: there is nothing unmerged about it.
+    if (!named || named === this.kb.defaultBranch) return { catalog: await this.defaultCatalog() };
+    return { catalog: await this.readBranch(named), branch: named };
+  }
+
+  private async defaultCatalog(): Promise<Catalog> {
     const cached = this.cache.get();
     if (cached) return cached;
-    // Token first: a merge's `invalidate()` can land while `scanDisk` is still
+    // Token first: a merge's `invalidate()` can land while the scan is still
     // reading the pre-merge tree, and storing that read afterwards would undo
     // the drop for a full TTL.
     const token = this.cache.begin();
-    const skills = await this.scanDisk();
-    this.cache.set(skills, token);
-    return skills;
+    const catalog = await this.readDefault();
+    this.cache.set(catalog, token);
+    return catalog;
   }
 
-  private async scanDisk(): Promise<ParsedSkill[]> {
-    // Ensure the default-branch clone exists, then scan its Skills/ and
-    // Plugins/ roots. Any failure (no workspace, no such dir) degrades to an
-    // empty catalog — the manual/tools must never break because skills can't
-    // be read.
+  /**
+   * The default branch's catalog. A workspace that cannot be resolved degrades
+   * to an empty one — the manual/tools must never break because skills can't
+   * be read. A NAMED branch does not degrade: see `readBranch`.
+   */
+  private async readDefault(): Promise<Catalog> {
     let wsId: string;
     try {
       wsId = (await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch)).id;
     } catch {
-      return [];
+      return { wsId: this.kb.defaultWorkspaceId(), kbRoot: '', skills: [], digests: new Map() };
     }
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+    return { wsId, kbRoot, skills: await this.scanTree(kbRoot), digests: new Map() };
+  }
+
+  /**
+   * One branch's clone, scanned. Deliberately NOT cached and deliberately NOT
+   * degraded:
+   *  - no cache, because the caller of a branch read is usually the agent that
+   *    just wrote the skill, and a minute-old answer would hide its own work;
+   *  - no degrading, because a branch nobody ever pushed must answer the 404
+   *    the file tools answer (`BranchNotFoundError`, naming the branch) — an
+   *    empty list would read as "that branch has no skills", which is a
+   *    different and untrue statement.
+   *
+   * Resolving the workspace clones the branch on first use, so a call naming a
+   * branch for the first time waits for a clone.
+   */
+  private async readBranch(branch: string): Promise<Catalog> {
+    const wsId = (await this.workspaceService.getOrCreateForBranch(branch)).id;
+    const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+    return { wsId, kbRoot, skills: await this.scanTree(kbRoot), digests: new Map() };
+  }
+
+  /**
+   * Does this skill, as the branch has it, differ from the `released` copy —
+   * by the content of its FOLDER? It is absent from the released catalog (or
+   * listed there at another path), or one of the files the two catalogs list
+   * for it differs byte for byte.
+   *
+   * Reading both folders is the price of saying something true, and it is paid
+   * only on a branch read: a skill folder is instructions plus a few assets.
+   * A file that cannot be read on either side counts as a difference — unable
+   * to prove the branch's copy is the released one, the honest answer is that
+   * it is not approved.
+   *
+   * Both sides go through `digestOf`, so the RELEASED side is read once per
+   * cached catalog rather than once per skill per call: a listing of N skills
+   * used to re-hash all N released folders on every call, and each `getSkill`
+   * re-hashed one of them again.
+   */
+  private async differs(released: Catalog, branchCatalog: Catalog, skill: ParsedSkill): Promise<boolean> {
+    const mirror = released.skills.find((s) => s.summary.name === skill.summary.name);
+    if (!mirror || mirror.summary.path !== skill.summary.path) return true;
+    const [onBranch, onDefault] = await Promise.all([
+      this.digestOf(branchCatalog, skill),
+      this.digestOf(released, mirror),
+    ]);
+    return onBranch === null || onDefault === null || onBranch !== onDefault;
+  }
+
+  /**
+   * One skill folder's digest in one catalog's clone, computed at most once
+   * for that catalog. The folder path is a unique key within a catalog — a
+   * folder holds one `SKILL.md`, so it yields one skill — and the file list
+   * the digest covers comes from that same catalog's scan.
+   *
+   * Memoizing means a released folder's ASSETS are now as stale as the rest
+   * of the catalog that names them: both are refreshed by the TTL and dropped
+   * together by `invalidate()` on a merge to the default branch. A branch
+   * catalog is built per call and so is its memo, which is what a draft read
+   * needs — the agent's own last write must show.
+   */
+  private digestOf(catalog: Catalog, skill: ParsedSkill): Promise<string | null> {
+    const key = skill.summary.path;
+    const memo = catalog.digests.get(key);
+    if (memo) return memo;
+    // The promise, not the value: skills asked for at once share one read.
+    // A rejection is dropped rather than kept — `folderDigest` answers `null`
+    // for a file it cannot read, so a throw here is a defect, and holding it
+    // would answer with it for the catalog's whole life.
+    const pending = folderDigest(catalog.kbRoot, skill);
+    catalog.digests.set(key, pending);
+    pending.catch(() => catalog.digests.delete(key));
+    return pending;
+  }
 
+  /** Scan one clone's `Skills/` and `Plugins/` roots into a catalog's skills. */
+  private async scanTree(kbRoot: string): Promise<ParsedSkill[]> {
     // Skills may be grouped in category subfolders (each carrying its own
     // access.md), so a SKILL.md can live at any depth under either root. Walk
     // the tree and treat every folder that directly contains a SKILL.md as a
@@ -344,6 +527,60 @@ export class SkillService implements ISkillService {
 
 // --- helpers ------------------------------------------------------------------
 
+/**
+ * The one line a skill read from an unmerged branch begins with. Exported
+ * because the tool surface documents it and the tests assert it: there is one
+ * sentence, in one place, and an agent that has read it once recognises it.
+ */
+export function unmergedSkillNotice(branch: string): string {
+  return `This skill is read from the unmerged branch "${branch}" and is not approved.`;
+}
+
+/**
+ * Say, on the answer itself, that it came off a branch that changed this skill.
+ *
+ * The body gets the line because the body is what an agent reads and acts on;
+ * a bundled file gets the flags beside its content, never a sentence inside it
+ * (prepending prose to a script is a syntax error, not a warning).
+ */
+function asUnmerged(result: Extract<GetSkillResult, { ok: true }>, branch: string): GetSkillResult {
+  if (result.kind === 'file') {
+    return { ...result, file: { ...result.file, unmerged: true, branch } };
+  }
+  return {
+    ...result,
+    skill: {
+      ...result.skill,
+      unmerged: true,
+      branch,
+      body: `${unmergedSkillNotice(branch)}\n\n${result.skill.body}`,
+    },
+  };
+}
+
+/**
+ * A digest of a skill folder as its own catalog lists it: `SKILL.md` plus
+ * every bundled file, each hashed under its relative name so a renamed,
+ * added or dropped asset is a difference too — and so a file one branch's
+ * ignore rules hide is one as well. `null` when a listed file cannot be read,
+ * which the caller treats as "cannot prove it is the released copy".
+ */
+async function folderDigest(kbRoot: string, skill: ParsedSkill): Promise<string | null> {
+  if (!kbRoot) return null;
+  const folder = skill.summary.path;
+  const rels = ['SKILL.md', ...skill.files.map((f) => f.slice(folder.length + 1))].sort();
+  const hash = createHash('sha256');
+  for (const rel of rels) {
+    hash.update(`${rel}\0`);
+    try {
+      hash.update(await fs.readFile(path.join(kbRoot, folder, ...rel.split('/'))));
+    } catch {
+      return null;
+    }
+  }
+  return hash.digest('hex');
+}
+
 /**
  * Skill names are folder names; reject anything that could escape the folder.
  *