@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/tool-registry/__tests__/tool-description-length.test.ts

@@ -4,7 +4,9 @@ import {
   CALL_TOOL_CHAIN_NAME,
   CHAIN_FAILURES_RULE,
   CHAIN_LARGE_RESULTS_RULE,
+  callLine,
   codeModeMetaTools,
+  splitCallLine,
 } from '@bevel-software/platform-mcp-core';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../../tool-manuals/tool-manuals.contract.js';
@@ -23,13 +25,13 @@ import { UuidSessionSink } from '../../workspace/session-sink.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { CLIENT_SHORT_CUT, TOOL_DESCRIPTION_CAP, clientVisibleLength, firstSentenceEnd } from '../description-length.js';
 import {
-  POINTER_GUIDE_NAME_BUDGET,
-  SHARED_RULES_POINTER_MAX,
   TOOL_PREFIX_CAP,
   sharedFileRules,
-  sharedRulesPointer,
 } from '../../agent-instructions/index.js';
 import { isPlatformFile, platformFilesByDepth } from '@bevel-software/platform-shared';
+import { GET_AGENT_GUIDE_TOOL, GUIDE_FIRST_SENTENCE, guideFirstDescription } from '../guide-first.js';
+import { registerAgentGuideTool } from '../../agent-guide/agent-guide.tools.js';
+import { agentGuideSections } from '../../agent-guide/agent-guide.js';
 
 /**
  * The cap exists because clients cut a long tool description, and they cut it
@@ -62,16 +64,18 @@ const emptySkills = { listSkills: async () => [] } as unknown as Parameters<type
 /**
  * The meta-tools as the hosted endpoint builds them (`mcp.service.ts`):
  * examples written against the namespace it registers the knowledge-base tools
- * under and against the catalog it serves, and the chain ending in the pointer.
- * So the chain description measured here carries the worked call a client is
- * really sent, which is its longest form.
+ * under and against the catalog it serves, and the chain without the rules it
+ * states only in the shared places. So the chain description measured here
+ * carries the worked call a client is really sent, which is its longest form.
  */
-function servedMetaTools(external: readonly UtcpTool[], pointer = sharedRulesPointer(testKbContext().layout)) {
+function servedMetaTools(external: readonly UtcpTool[]) {
   return codeModeMetaTools(
     EXTERNAL_KB_MANUAL_NAME,
     external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
-    { sharedRulesPointer: pointer },
-  );
+    { sharedRulesPointer: '' },
+    // As the hosted endpoint serves them: opening with the guide-first
+    // sentence, through the one helper the endpoint itself uses.
+  ).map((t) => ({ ...t, description: guideFirstDescription(t.description) }));
 }
 
 /** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
@@ -101,20 +105,27 @@ async function hexisTools(): Promise<UtcpTool[]> {
     // every real composition supplies one: without it they would be the two
     // descriptions this suite never measured.
     unused(),
+    // The guide reader, not needed to build defs; then the download store,
+    // mounted on the same terms as the upload one.
+    undefined,
+    unused(),
   );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb);
-  registerPluginsTools(registry);
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true);
+  registerPluginsTools(registry, kb);
   registerSkillsTools(registry, router, toolAuth, toolHandler, emptySkills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {
     accessControl: unused(),
     variableStatus: unused(),
     kb,
   });
+  // The guide's own tool, with the platform's sections: the one description
+  // that lists the sections is measured with the list it really carries.
+  registerAgentGuideTool(registry, router, toolAuth, toolHandler, () => agentGuideSections(kb.layout));
 
   const byName = new Map<string, UtcpTool>();
-  // The meta-tools as a client is served them: the chain carries its pointer
-  // (`mcp.service.ts` appends it at the mount), so the catalog measured here is
-  // the catalog that goes out rather than the unpointed constant.
+  // The meta-tools as a client is served them (`mcp.service.ts` opens each
+  // with the guide-first sentence at the mount), so the catalog measured here
+  // is the catalog that goes out rather than the bare constant.
   const external = (await registry.listExternal()) as UtcpTool[];
   const metaTools = servedMetaTools(external);
   for (const tool of [...(await registry.listInternal()), ...external, ...metaTools]) {
@@ -141,9 +152,11 @@ describe('no Hexis tool description is long enough to be cut', () => {
     // The cap does not answer the ~500-character cut; the ORDER of the text
     // does, and this is where that claim is checked rather than asserted in a
     // comment. A client that stops at 500 must still have the sentence saying
-    // what the tool does — what it loses is the pointer tail, and the file the
-    // pointer names is stated in the handshake instructions and in the guide
-    // anyway. Lowering the cap to 500 would not buy this; only order does.
+    // what the tool does — what it loses is the tail. The shared rules are
+    // stated in the guide (which the opener sends every client to, including
+    // the description-only ones this cut is about) and, for the clients that
+    // honour it, in the handshake instructions as well. Lowering
+    // the cap to 500 would not buy this; only order does.
     const late = (await hexisTools())
       .map((t) => ({ tool: t.name, endsAt: firstSentenceEnd(t) }))
       .filter((m) => m.endsAt > CLIENT_SHORT_CUT)
@@ -156,30 +169,28 @@ describe('no Hexis tool description is long enough to be cut', () => {
     ).toEqual([]);
   });
 
-  it('holds the cap on a deployment that renamed its guide, not only under the default', async () => {
-    // The pointer ends every file tool's description and its length moves with
-    // a deployment setting, so a cap checked only against the nine characters
-    // of `AGENTS.md` guarantees nothing about the catalog a renamed deployment
-    // serves. Two things make it hold: the pointer is bounded by construction
-    // (past `POINTER_GUIDE_NAME_BUDGET` the guide is named by its role), and
-    // `clientVisibleLength` charges the worst case rather than this layout's.
+  it('opens every tool but the guide\'s own with the guide-first sentence, and fits with it', async () => {
+    // The sentence is in the description the registry lists, so the catalog
+    // measured here is the catalog a client gets, sentence included.
     const tools = await hexisTools();
-    const atWorst = tools
-      .map((t) => ({ tool: t.name, chars: clientVisibleLength(t) }))
-      .filter((m) => m.chars > TOOL_DESCRIPTION_CAP);
-    expect(atWorst, atWorst.map((m) => `${m.tool}: ${m.chars}`).join('\n')).toEqual([]);
-
-    // And measured literally, under the longest guide name a deployment can
-    // actually configure: every description still fits.
-    const longest = `${'x'.repeat(252)}.md`;
-    const pointerHere = sharedRulesPointer(testKbContext().layout);
-    const pointerThere = sharedRulesPointer({ ...testKbContext().layout, agentsFile: longest });
-    expect(pointerThere.length).toBeLessThanOrEqual(SHARED_RULES_POINTER_MAX);
-    for (const tool of tools) {
-      if (!tool.description?.endsWith(pointerHere)) continue;
-      const asRenamed = tool.description.slice(0, -pointerHere.length) + pointerThere;
-      const chars = clientVisibleLength({ name: tool.name, description: asRenamed });
-      expect(chars, `${tool.name} on a renamed deployment`).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    // ONE predicate for both halves, so no description falls between them: a
+    // tool whose own description is empty is served the sentence alone, and
+    // one with text after it has whitespace between — not `here.Read`.
+    // Behind the `Call:` line, when the description already carries one (the
+    // meta-tools are built with theirs): that line comes first on every tool.
+    const opensWithGuide = (t: UtcpTool): boolean => {
+      const description = splitCallLine(t.description ?? '').rest;
+      if (description === GUIDE_FIRST_SENTENCE) return true;
+      return description.startsWith(GUIDE_FIRST_SENTENCE) && /^\s/.test(description.slice(GUIDE_FIRST_SENTENCE.length));
+    };
+    const opened = tools.filter(opensWithGuide);
+    expect(opened.length).toBeGreaterThan(0);
+    // The guide's own tool is the one exception: it is what the sentence
+    // points at, and it is in the catalog measured here so the cap holds on
+    // it too (see the first test).
+    expect(tools.filter((t) => !opensWithGuide(t)).map((t) => t.name)).toEqual([GET_AGENT_GUIDE_TOOL]);
+    for (const tool of opened) {
+      expect(clientVisibleLength(tool), tool.name).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
     }
   });
 
@@ -190,23 +201,24 @@ describe('no Hexis tool description is long enough to be cut', () => {
     // the catalog the agent reads was over it by 300.
     const read = (await hexisTools()).find((t) => t.name === 'read_file');
     expect(read).toBeDefined();
-    // Its own text, with the pointer charged at its worst case rather than at
-    // this layout's, plus the prefix at ITS cap and the blank line between.
-    const pointer = sharedRulesPointer();
-    const ownAtWorstPointer = read!.description!.length - pointer.length + SHARED_RULES_POINTER_MAX;
-    expect(clientVisibleLength(read!)).toBe(ownAtWorstPointer + TOOL_PREFIX_CAP + 2);
-    expect(ownAtWorstPointer + TOOL_PREFIX_CAP + 2).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
+    // Its own text (the guide-first sentence included), plus the prefix at
+    // ITS cap and the blank line between, must fit — measured as the client
+    // sees it.
+    expect(clientVisibleLength(read!)).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
   });
 
   it('fails, naming the tool, when a paragraph takes a description over the cap', () => {
     const padded = { name: 'write_file', description: 'x'.repeat(TOOL_DESCRIPTION_CAP + 1) } as UtcpTool;
     expect(clientVisibleLength(padded)).toBeGreaterThan(TOOL_DESCRIPTION_CAP);
-    // A tool with no description at all is not over the cap.
-    expect(clientVisibleLength({ name: 'nothing' } as UtcpTool)).toBe(0);
-    // Unless it is a PREFIXED one: the prefix is sent on its own then (no
-    // description, so no blank line either), and that text is what the client
-    // was handed. Measuring it as nothing would hide the only thing it got.
-    expect(clientVisibleLength({ name: 'read_file' } as UtcpTool)).toBe(TOOL_PREFIX_CAP);
+    // A tool with no description at all is handed its `Call:` line alone —
+    // the example counts toward the cap like any other text a client gets.
+    const nothingCall = callLine(`${EXTERNAL_KB_MANUAL_NAME}.nothing`, undefined);
+    expect(clientVisibleLength({ name: 'nothing' } as UtcpTool)).toBe(nothingCall.length);
+    // A PREFIXED one is handed the prefix too, behind the line (no
+    // description, so no blank line after the prefix), and that text is what
+    // the client was handed. Measuring it as nothing would hide what it got.
+    const readCall = callLine(`${EXTERNAL_KB_MANUAL_NAME}.read_file`, undefined);
+    expect(clientVisibleLength({ name: 'read_file' } as UtcpTool)).toBe(readCall.length + 2 + TOOL_PREFIX_CAP);
   });
 
   it('measures the catalog, which is what a client lists — and says what is outside it', async () => {
@@ -228,7 +240,7 @@ describe('no Hexis tool description is long enough to be cut', () => {
   });
 });
 
-describe('every file tool ends with the pointer and carries no shared paragraph', () => {
+describe('every file tool opens with the guide-first sentence and carries no shared paragraph', () => {
   /** The tools that used to carry the shared paragraphs — every `mount`ed one. */
   const FILE_TOOLS = [
     'read_file',
@@ -248,13 +260,12 @@ describe('every file tool ends with the pointer and carries no shared paragraph'
     'apply_file_upload',
   ];
 
-  it('ends each description with the one sentence naming the shared rules', async () => {
+  it('opens each description with the sentence sending the agent to the guide, and ends it as a sentence', async () => {
     const tools = await hexisTools();
-    const pointer = sharedRulesPointer(testKbContext().layout);
     for (const name of FILE_TOOLS) {
       const def = tools.find((t) => t.name === name);
       expect(def, name).toBeDefined();
-      expect(def!.description!.endsWith(pointer), `${name} must end with: ${pointer}`).toBe(true);
+      expect(def!.description!.startsWith(`${GUIDE_FIRST_SENTENCE} `), `${name} must open with: ${GUIDE_FIRST_SENTENCE}`).toBe(true);
       // Ends with a full sentence, so nothing reads as cut off mid-thought.
       expect(def!.description!.trimEnd().endsWith('.'), name).toBe(true);
     }
@@ -283,25 +294,29 @@ describe('every file tool ends with the pointer and carries no shared paragraph'
 });
 
 describe('the shared rules describe the tools they name', () => {
-  it('ends the chain description with the pointer too, under the cap', async () => {
+  it('opens the chain description with the guide-first sentence too, under the cap', async () => {
     // What a chain does with a failure, a large result or an image is true of
     // every call, so it is stated in the shared rules — and the clients that
     // drop the handshake `instructions` see only descriptions, so the chain
-    // gets the same pointer every file tool ends with. Composed at the mount,
-    // because `mcp-core` may not spell a guide name that is a deployment
-    // setting.
-    const pointer = sharedRulesPointer(testKbContext().layout);
+    // opens with the same sentence every tool of the platform's own opens
+    // with, and ends with no second pointer: the one at the front is the way
+    // to the rules. Composed at the mount, because `mcp-core` builds the
+    // constant without knowing where this deployment states them.
     const served = (await hexisTools()).find((t) => t.name === CALL_TOOL_CHAIN_NAME)!;
-    expect(served.description!.endsWith(pointer)).toBe(true);
+    // Behind its `Call:` line, which is the first line of every description.
+    expect(served.description!.startsWith('Call: call_tool_chain(')).toBe(true);
+    expect(splitCallLine(served.description!).rest.startsWith(`${GUIDE_FIRST_SENTENCE} `)).toBe(true);
+    expect(served.description!.split(GUIDE_FIRST_SENTENCE)).toHaveLength(2);
+    expect(served.description!.trimEnd().endsWith('.')).toBe(true);
     expect(clientVisibleLength(served)).toBeLessThanOrEqual(TOOL_DESCRIPTION_CAP);
-    // The other two describe the registry, not what a call does: no pointer.
+    // The other two open the same way: the guide comes before the registry too.
     for (const tool of servedMetaTools([]).filter((t) => t.name !== CALL_TOOL_CHAIN_NAME)) {
-      expect(tool.description).not.toContain(pointer);
+      expect(splitCallLine(tool.description!).rest.startsWith(`${GUIDE_FIRST_SENTENCE} `), tool.name).toBe(true);
     }
   });
 
   it('states what a chain does in the shared rules, and not a second time on the chain', async () => {
-    // The pointer is only honest if the rules it points at are THERE. These
+    // The opener is only honest if the rules it points at are THERE. These
     // two were paragraphs of the chain's description; they moved, whole, and a
     // description that kept them as well would be the long one a client cuts.
     const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'tool-chain')!;
@@ -317,7 +332,7 @@ describe('the shared rules describe the tools they name', () => {
 
   it('keeps the rules on the chain itself where no shared rules are served', () => {
     // The standalone bridge proxies a deployment whose guide it cannot name, so
-    // it passes no pointer — and an agent there must still be told what a chain
+    // it passes no pointer at all — and an agent there must still be told what a chain
     // that timed out, or answered too much, or read an image, does.
     const [chain] = codeModeMetaTools('hexis', []).filter((t) => t.name === CALL_TOOL_CHAIN_NAME);
     expect(chain.description).toContain(CHAIN_FAILURES_RULE);

package/src/modules/tool-registry/description-length.ts

@@ -5,14 +5,17 @@
  * where the text specific to the tool sits, after whatever shared preamble it
  * carried. Agents reported `file_stat`, `read_file`, `write_file` and
  * `write_files` arriving ending in "[truncated]". The rules those descriptions
- * shared now live in one place (see `agent-instructions/shared-file-rules.ts`)
- * and each description ends with one sentence pointing there, which is what
- * makes the cap below reachable rather than aspirational.
+ * shared now live in one place (see `agent-instructions/shared-file-rules.ts`,
+ * served in the guide `get_agent_guide` returns) and each description OPENS
+ * with the one sentence sending the agent there (`guide-first.ts`), which is
+ * what makes the cap below reachable rather than aspirational.
  */
 
+import { callLine, splitCallLine } from '@bevel-software/platform-mcp-core';
 import { TOOL_PREFIX_CAP } from '@bevel-software/platform-shared';
 import { PREFIXED_TOOLS } from '../agent-instructions/compose.js';
-import { SHARED_RULES_POINTER_MAX, sharedRulesPointer } from '../agent-instructions/shared-file-rules.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
+import { GUIDE_FIRST_SENTENCE } from './guide-first.js';
 import type { UtcpTool } from './tool.contract.js';
 
 /**
@@ -25,8 +28,10 @@ import type { UtcpTool } from './tool.contract.js';
  * could answer: no useful description of `move_file` fits in 500. What answers
  * that one is the ORDER of the text, which is why the deployment's purpose line
  * is prepended rather than appended (see `prefixToolDescription`) and why every
- * description now leads with what the tool does and ends with the pointer: a
- * cut at 500 then takes the pointer and leaves the tool. The other cut is the
+ * description now opens with the guide-first sentence and then what the tool
+ * does, with the tool's own detail last: a cut at 500 keeps the sentence and
+ * the tool's first sentence (see `firstSentenceEnd`) and takes the detail,
+ * which the guide states in full anyway. The other cut is the
  * four-figure one agents reported on `file_stat`, `read_file`, `write_file` and
  * `write_files`, and 1,200 sits below it with room to spare.
  *
@@ -58,23 +63,48 @@ export const TOOL_DESCRIPTION_CAP = 1_200;
  */
 export const CLIENT_SHORT_CUT = 500;
 
+/** What these measurements read of a tool: its name, its text and the schema its `Call:` line is generated from. */
+export type MeasuredTool = Pick<UtcpTool, 'name' | 'description'> & { inputs?: unknown };
+
+/**
+ * The `Call:` line a client is handed ahead of everything else, and the blank
+ * line after it — counted, because it is part of what a client cuts. Taken
+ * from the description when it already opens with one (a meta-tool is built
+ * with its line), generated from the tool's inputs under the namespace the
+ * hosted endpoint serves otherwise, as mcp-core's `withCallExample` does at
+ * listing time. The rest of the description comes back beside it.
+ */
+function splitServedCallLine(tool: MeasuredTool): { callChars: number; rest: string } {
+  const { call, rest } = splitCallLine(tool.description ?? '');
+  const line = call ?? callLine(`${EXTERNAL_KB_MANUAL_NAME}.${tool.name}`, tool.inputs);
+  // The blank line after it only when something follows it.
+  const followed = rest !== '' || PREFIXED_TOOLS.has(tool.name);
+  return { callChars: line.length + (followed ? 2 : 0), rest };
+}
+
 /**
  * Where the tool's OWN opening sentence ends in the text a client is handed:
- * the purpose prefix counted at its cap, as in {@link clientVisibleLength}, and
- * the pointer not counted at all, since it is the part a short cut is meant to
- * take.
+ * the purpose prefix counted at its cap, as in {@link clientVisibleLength},
+ * and the guide-first sentence every listed tool opens with counted as the
+ * text it is — a client that cuts at 500 must still reach the sentence saying
+ * what the tool does, past that one.
  *
  * A description with no sentence-ending punctuation counts whole — the honest
  * answer for text that never finishes a sentence.
  */
-export function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>): number {
-  const prefix = PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP + 2 : 0;
-  const description = tool.description ?? '';
+export function firstSentenceEnd(tool: MeasuredTool): number {
+  const { callChars, rest: description } = splitServedCallLine(tool);
+  const prefix = callChars + (PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP + 2 : 0);
   if (description === '') return prefix;
-  const pointer = sharedRulesPointer();
-  const own = description.endsWith(pointer) ? description.slice(0, -pointer.length) : description;
+  // The opener and whatever whitespace follows it: `guideFirstDescription`
+  // joins with one space, and leaves a description that already opens with
+  // the sentence as it came — a newline after it is still the opener's.
+  const opener = description.startsWith(GUIDE_FIRST_SENTENCE)
+    ? GUIDE_FIRST_SENTENCE.length + (description.slice(GUIDE_FIRST_SENTENCE.length).match(/^\s*/)?.[0].length ?? 0)
+    : 0;
+  const own = description.slice(opener);
   const firstSentence = own.match(/^[\s\S]*?[.!?](?=\s|$)/)?.[0] ?? own;
-  return prefix + firstSentence.length;
+  return prefix + opener + firstSentence.length;
 }
 
 /**
@@ -85,27 +115,22 @@ export function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>):
  * the cap is what an admin may grow their text to without being told, so a
  * description that only fits beside a short prefix does not really fit.
  *
- * The pointer sentence is measured the same way, for the same reason. It ends
- * every file tool's description and its length moves with a DEPLOYMENT SETTING
- * — the guide's file name — so a description measured beside the nine
- * characters of `AGENTS.md` would pass here and arrive cut on a deployment
- * that renamed its guide. Whatever pointer a description actually carries is
- * discounted and charged at {@link SHARED_RULES_POINTER_MAX} instead.
+ * The guide-first sentence every listed tool opens with is already in the
+ * description the registry lists, so it is measured as the text it is.
  */
-export function clientVisibleLength(tool: Pick<UtcpTool, 'name' | 'description'>): number {
-  const own = tool.description?.length ?? 0;
+export function clientVisibleLength(tool: MeasuredTool): number {
+  const { callChars, rest } = splitServedCallLine(tool);
+  return callChars + ownVisibleLength(tool.name, rest);
+}
+
+/** {@link clientVisibleLength} without the `Call:` line: the purpose prefix and the tool's own text. */
+function ownVisibleLength(name: string, description: string): number {
+  const own = description.length;
   // A prefixed tool with no description of its own is still handed the prefix,
   // and nothing else — `prefixToolDescription` sends the prefix alone, with no
   // blank line after it. Measuring that as zero would under-report the only
   // text the client got.
-  if (own === 0) return PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP : 0;
-  // The pointer at its worst case rather than at this layout's: swap the one
-  // it carries for the longest it could be. A description that does not end
-  // with it (`start_session`, the proxied tools) is charged nothing.
-  const pointer = sharedRulesPointer();
-  const atWorstPointer = tool.description!.endsWith(pointer)
-    ? own - pointer.length + SHARED_RULES_POINTER_MAX
-    : own;
+  if (own === 0) return PREFIXED_TOOLS.has(name) ? TOOL_PREFIX_CAP : 0;
   // `+ 2` for the blank line `prefixToolDescription` puts between the two.
-  return PREFIXED_TOOLS.has(tool.name) ? atWorstPointer + TOOL_PREFIX_CAP + 2 : atWorstPointer;
+  return PREFIXED_TOOLS.has(name) ? own + TOOL_PREFIX_CAP + 2 : own;
 }

package/src/modules/tool-registry/guide-first.ts

@@ -0,0 +1,41 @@
+import { splitCallLine } from '@bevel-software/platform-mcp-core';
+import type { UtcpTool } from './tool.contract.js';
+
+/** The one tool that returns the platform's guide (see `modules/agent-guide`). */
+export const GET_AGENT_GUIDE_TOOL = 'get_agent_guide';
+
+/**
+ * The sentence every tool of the platform's own OPENS with: what to do before
+ * anything else here. At the front, not the end, because clients cut a long
+ * description from the end and the one instruction that must survive is this
+ * one. The guide's own tool is the one that does not carry it — it IS what
+ * the sentence points at.
+ */
+export const GUIDE_FIRST_SENTENCE = `Call \`${GET_AGENT_GUIDE_TOOL}\` first and read the platform's guide before anything else here.`;
+
+/**
+ * `description` as a client is handed it: the sentence ahead of it, once. A
+ * description that already opens with the sentence is returned as it is, and
+ * an absent or empty one becomes the sentence alone. The ONE place the
+ * sentence is put in front of a description — the registry for the tools it
+ * lists, the MCP service for the meta-tools it builds itself — so the two
+ * cannot drift apart on what "once" means.
+ *
+ * Behind a `Call:` line, never ahead of it: the call example is the first
+ * line of every description (see mcp-core's `withCallExample`), and the
+ * sentence opens what follows it.
+ */
+export function guideFirstDescription(description: string | undefined): string {
+  const { call, rest } = splitCallLine(description ?? '');
+  if (call !== null) return `${call}\n\n${guideFirstDescription(rest)}`;
+  const own = rest;
+  if (own.startsWith(GUIDE_FIRST_SENTENCE)) return own;
+  return own ? `${GUIDE_FIRST_SENTENCE} ${own}` : GUIDE_FIRST_SENTENCE;
+}
+
+/** `tool` as the catalog lists it: the sentence ahead of its own description, except on the guide's own tool. */
+export function withGuideFirst(tool: UtcpTool): UtcpTool {
+  if (tool.name === GET_AGENT_GUIDE_TOOL) return tool;
+  const description = guideFirstDescription(tool.description);
+  return description === tool.description ? tool : { ...tool, description };
+}

package/src/modules/tool-registry/tool-registry.ts

@@ -5,6 +5,7 @@ import type {
   ToolProvider,
   UtcpTool,
 } from './tool.contract.js';
+import { withGuideFirst } from './guide-first.js';
 
 /**
  * The tool catalog. Modules call `registerExternalTool` / `registerInternalTool`
@@ -13,6 +14,12 @@ import type {
  * catalog only aggregates and lists them — the two manual endpoints serialize
  * each list per request. Insertion order is preserved (static tools first, then
  * provider-built ones); a duplicate static name within a surface throws.
+ *
+ * Every listed tool but the guide's own (`get_agent_guide`, which is what the
+ * sentence points at) opens with the one sentence saying what to do before
+ * any of them (`guide-first.ts`): applied here, at the one place both
+ * surfaces list from, so no module that registers a tool has to remember it
+ * and no surface can serve a tool without it.
  */
 export class ToolRegistry implements IToolRegistry {
   private readonly external = new Map<string, UtcpTool>();
@@ -37,13 +44,13 @@ export class ToolRegistry implements IToolRegistry {
 
   async listExternal(ctx: ToolManualContext = {}): Promise<UtcpTool[]> {
     const dynamic = await Promise.all(this.externalProviders.map((p) => p(ctx)));
-    return [...this.external.values(), ...dynamic];
+    return [...this.external.values(), ...dynamic].map(withGuideFirst);
   }
 
   async listInternal(ctx: ToolManualContext = {}): Promise<UtcpTool[]> {
     const dynamic = await Promise.all(this.internalProviders.map((p) => p(ctx)));
     const lists = await Promise.all(this.internalListProviders.map((p) => p(ctx)));
-    return [...this.internal.values(), ...dynamic, ...lists.flat()];
+    return [...this.internal.values(), ...dynamic, ...lists.flat()].map(withGuideFirst);
   }
 
   private add(into: Map<string, UtcpTool>, tool: UtcpTool, surface: string): void {

package/src/modules/workflow/__tests__/apply-failure.test.ts

@@ -954,7 +954,12 @@ describe('PullRequestService — a recorded or cleared refusal reaches cached li
         ensureRemotesFetched: async () => undefined,
       } as unknown as WorkspaceService,
       {} as unknown as IAccessControl,
-      { changedPathsForPr: async () => ['Plugins/x/SKILL.md'] } as unknown as GitService,
+      {
+        changedPathsAndPairsForPr: async () => ({
+          paths: ['Plugins/x/SKILL.md'],
+          pairs: [{ path: 'Plugins/x/SKILL.md' }],
+        }),
+      } as unknown as GitService,
     );
 
     expect((await svc.listOpenPrs())[0]!.lastApplyFailure).toBeNull();

package/src/modules/workflow/__tests__/file-lock.service.deletion-gate.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { Database } from '../../database/connection.js';
+import { FileLockService } from '../file-lock.service.js';
+import { WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { makeFakeLockDb, type FakeLockDb } from './fake-file-lock-db.js';
+
+/**
+ * A deletion runs its last "is any save landing?" check inside
+ * `whileNoneAcquired`, and a save starts by taking its file lock. An acquire
+ * that passed the gate before the deletion began, but whose row was still
+ * being written, must be seen by that check — not land after it.
+ */
+
+const ALICE: AuthUser = { id: '11111111-1111-4111-8111-111111111111', email: 'alice@example.com', name: 'Alice' };
+const WS = 'alice%2Fdraft';
+const BRANCH = 'alice/draft';
+const PATH = 'knowledge-base/a.md';
+
+/** The fake lock db, with every INSERT held until `release()`. */
+function withHeldInserts(fake: FakeLockDb): { db: Database; release: () => void } {
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const base = fake.db as unknown as { insert: () => { values: (row: unknown) => Record<string, unknown> } };
+  const db = {
+    ...base,
+    insert: () => ({
+      values: (row: unknown) => {
+        const chain = base.insert().values(row) as {
+          onConflictDoUpdate: (arg: unknown) => unknown;
+          returning: () => Promise<unknown>;
+        };
+        const held = {
+          onConflictDoUpdate: (arg: unknown) => {
+            chain.onConflictDoUpdate(arg);
+            return held;
+          },
+          returning: async () => {
+            await gate;
+            return chain.returning();
+          },
+        };
+        return held;
+      },
+    }),
+  } as unknown as Database;
+  return { db, release };
+}
+
+describe('FileLockService deletion gate', () => {
+  let fake: FakeLockDb;
+
+  beforeEach(() => {
+    fake = makeFakeLockDb();
+  });
+
+  it('waits for an acquire already under way, so the check inside sees its lock', async () => {
+    const { db, release } = withHeldInserts(fake);
+    const locks = new FileLockService(db);
+
+    const acquire = locks.acquire(WS, BRANCH, PATH, ALICE);
+    let sawLock: boolean | null = null;
+    const deletion = locks.whileNoneAcquired(BRANCH, async () => {
+      sawLock = await locks.hasAnyActive(WS);
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+    // The acquire's row is not written yet, so the check has not run.
+    expect(sawLock).toBeNull();
+
+    release();
+    await expect(acquire).resolves.toMatchObject({ acquired: true });
+    await deletion;
+    expect(sawLock).toBe(true);
+  });
+
+  it('refuses an acquire that starts while the deletion runs', async () => {
+    const locks = new FileLockService(fake.db);
+    let refused: unknown = null;
+    await locks.whileNoneAcquired(BRANCH, async () => {
+      refused = await locks.acquire(WS, BRANCH, PATH, ALICE).catch((err: unknown) => err);
+    });
+    expect(refused).toBeInstanceOf(WorkflowValidationError);
+    expect(fake.rows()).toHaveLength(0);
+    // And grants it again once the deletion is over.
+    await expect(locks.acquire(WS, BRANCH, PATH, ALICE)).resolves.toMatchObject({ acquired: true });
+  });
+
+  it('does not wait for an acquire on another branch', async () => {
+    const { db, release } = withHeldInserts(fake);
+    const locks = new FileLockService(db);
+
+    const other = locks.acquire('bob%2Fdraft', 'bob/draft', PATH, ALICE);
+    let ran = false;
+    await locks.whileNoneAcquired(BRANCH, async () => {
+      ran = true;
+    });
+    expect(ran).toBe(true);
+    release();
+    await other;
+  });
+});