@bevel-software/platform-core-backend 0.34.0 → 0.35.0

package/src/modules/agent-guide/agent-guide.tools.ts

@@ -3,13 +3,23 @@ import type { IToolRegistry, UtcpTool } from '../tool-registry/index.js';
 import { GET_AGENT_GUIDE_TOOL, TOOL_DESCRIPTION_CAP } from '../tool-registry/index.js';
 import { ToolError, toolDef } from '../tool-helpers/index.js';
 import type { ToolHandlerFactory } from '../tool-helpers/index.js';
-import { AGENT_GUIDE_FILE, joinGuideSections, type AgentGuideSectionsReader } from './agent-guide.js';
+import {
+  AGENT_GUIDE_FILE,
+  START_HERE_SECTION_ID,
+  WHOLE_GUIDE_SECTION,
+  joinGuideSections,
+  type AgentGuideSectionsReader,
+} from './agent-guide.js';
 
 export { GET_AGENT_GUIDE_TOOL };
 
 /**
- * The one tool that returns the guide on its own — whole, or one section by
- * id. It takes nothing else: the guide is the platform's text for this
+ * The one tool that returns the guide on its own: the start section when no
+ * section is named, one section by id, or the whole guide (`all`). Start
+ * section by default because this is the call every tool description tells
+ * an agent, and each sub-agent it starts, to make first: answering it with
+ * the whole guide made the most-read text the platform has also its longest.
+ * It takes nothing else: the guide is the platform's text for this
  * deployment, the same for every caller and every branch, and reading it
  * touches no file — so no `branch`, no `sessionId`, and no access gate. The
  * other way to the same text is a `read_file` of `AGENTS.md` at the
@@ -33,27 +43,30 @@ export function registerAgentGuideTool(
   const build = async (): Promise<UtcpTool> => {
     const list = await sections();
     const describe = (sectionList: string) =>
-      "The platform's guide to this knowledge base: its layout, where a new file goes, the rules every file tool " +
-      'shares, access control, skills and tool manuals. ALWAYS call this first and read the guide before you do ' +
-      'anything else in the platform. Returns `{ guide }` as markdown: the whole guide, or one section when ' +
-      '`section` names one. The same text comes back from `read_file` on `' +
+      "The platform's guide to this knowledge base. ALWAYS call this first, before anything else in the " +
+      'platform. With no `section` it returns the start section: the default branch every file tool takes, the ' +
+      'first-call rules, and which section answers which question. Then fetch only the section a task needs, by ' +
+      '`section`; only `"' +
+      WHOLE_GUIDE_SECTION +
+      '"` returns the whole guide. `read_file` on `' +
       AGENT_GUIDE_FILE +
-      "` at the KB root, after the knowledge base's own " +
+      "` at the KB root answers with the same start section (after the knowledge base's own " +
       AGENT_GUIDE_FILE +
-      ` when it has one. Sections: ${sectionList}.`;
+      ` when it has one). Returns \`{ guide }\` as markdown. Sections: ${sectionList}.`;
     // The description stays under the cap WHATEVER a distribution adds, in
     // three steps: every id with its title; every id alone; as many ids as
     // fit and a count of the rest. An id a client cut off the end would be a
     // section an agent cannot ask for — so nothing is ever cut: the one
-    // complete list of sections is `sections` on the whole-guide response,
-    // which the description names when it cannot carry them all itself.
+    // complete list of sections is `sections` on the answer to a call
+    // without one, which the description names when it cannot carry them
+    // all itself.
     const titled = describe(list.map((s) => `\`${s.id}\` (${s.title})`).join(', '));
     const ids = list.map((s) => `\`${s.id}\``);
     const counted = (shown: number) =>
       describe(
         shown === 0
-          ? `${ids.length}, named under \`sections\` in the whole-guide response`
-          : [...ids.slice(0, shown), `and ${ids.length - shown} more, all named under \`sections\` in the whole-guide response`].join(', '),
+          ? `${ids.length}, named under \`sections\` in the answer`
+          : [...ids.slice(0, shown), `and ${ids.length - shown} more, all named under \`sections\` in the answer`].join(', '),
       );
     let description = titled.length <= TOOL_DESCRIPTION_CAP ? titled : describe(ids.join(', '));
     for (let shown = ids.length; description.length > TOOL_DESCRIPTION_CAP && shown > 0; shown--) {
@@ -69,8 +82,10 @@ export function registerAgentGuideTool(
           section: {
             type: 'string',
             description:
-              'Optional: the id of one section to read instead of the whole guide (the ids are listed in this ' +
-              'description, and every one under `sections` in the whole-guide response). Omit it for the whole guide.',
+              'Optional: the id of one section to read (the ids are listed in this description, and every one under ' +
+              '`sections` in the answer), or `"' +
+              WHOLE_GUIDE_SECTION +
+              '"` for the whole guide. Omit it for the start section.',
           },
         },
         additionalProperties: false,
@@ -78,18 +93,18 @@ export function registerAgentGuideTool(
       outputs: {
         type: 'object',
         properties: {
-          guide: { type: 'string', description: 'The guide, or the one section asked for, as markdown.' },
+          guide: { type: 'string', description: 'The section asked for (the start section by default), or the whole guide, as markdown.' },
           sections: {
             type: 'array',
-            description: 'Without `section`: every section of the guide, in order, by id and heading — the complete list.',
+            description: `Without \`section\`, or with \`"${WHOLE_GUIDE_SECTION}"\`: every section of the guide, in order, by id and heading — the complete list.`,
             items: {
               type: 'object',
               properties: { id: { type: 'string' }, title: { type: 'string' } },
               required: ['id', 'title'],
             },
           },
-          section: { type: 'string', description: 'With `section`: the id of the section returned.' },
-          title: { type: 'string', description: 'With `section`: its heading.' },
+          section: { type: 'string', description: 'The id of the one section returned.' },
+          title: { type: 'string', description: 'Its heading.' },
         },
         required: ['guide'],
       },
@@ -104,24 +119,27 @@ export function registerAgentGuideTool(
     toolAuth,
     toolHandler(async (args, ctx) => {
       const list = await sections();
+      const index = list.map((s) => ({ id: s.id, title: s.title }));
       const wanted = typeof args.section === 'string' ? args.section.trim() : '';
-      // A connection made as an agent configuration is told so at the top of the
-      // whole guide: the catalog it describes is narrowed to that agent.
-      // Everything is told nothing new, so its guide is the same text.
+      // A distribution that dropped the start section gets the whole guide by
+      // default, as before there was one: never an answer with nothing in it.
+      const start = list.find((s) => s.id === START_HERE_SECTION_ID);
+      // A connection made as an agent configuration is told so at the top of
+      // the guide's first answer and of the whole guide: the catalog it
+      // describes is narrowed to that agent. Everything is told nothing new,
+      // so its guide is the same text.
       const connection = ctx.connectionScope?.describe() ?? null;
-      if (!wanted) {
-        const guide = joinGuideSections(list);
-        return {
-          guide: connection ? `> ${connection}\n\n${guide}` : guide,
-          sections: list.map((s) => ({ id: s.id, title: s.title })),
-          ...(connection ? { connection } : {}),
-        };
-      }
+      const told = (guide: string) => ({
+        guide: connection ? `> ${connection}\n\n${guide}` : guide,
+        ...(connection ? { connection } : {}),
+      });
+      if (wanted === WHOLE_GUIDE_SECTION || (!wanted && !start)) return { ...told(joinGuideSections(list)), sections: index };
+      if (!wanted) return { ...told(start!.body), section: start!.id, title: start!.title, sections: index };
       const one = list.find((s) => s.id === wanted);
       if (!one) {
         throw new ToolError(
           `The guide has no section "${wanted}". Sections: ${list.map((s) => `\`${s.id}\``).join(', ')}. ` +
-            'Omit `section` for the whole guide.',
+            `Omit \`section\` for the start section, or pass \`"${WHOLE_GUIDE_SECTION}"\` for the whole guide.`,
           400,
         );
       }

package/src/modules/agent-guide/agent-guide.ts

@@ -20,10 +20,17 @@
  * The sections ship as markdown files in the package's `agent-guide/` folder
  * (see `assets.ts`), one per section, with the layout placeholders the old
  * template carried (`{{knowledgeBaseDir}}`, `{{skillsDir}}`, `{{pluginsDir}}`,
- * `{{agentsFile}}`). ONE section is computed rather than read: the rules every
- * file tool shares, which the MCP handshake also sends — the same string in
- * both places, from `shared-file-rules.ts`, so a rule cannot be changed in one
- * and left stale in the other.
+ * `{{agentsFile}}`), the checkout folder's `{{kbDirName}}` and the default
+ * branch's `{{defaultBranch}}`. ONE section is computed rather than read: the
+ * rules every file tool shares, which the MCP handshake also sends — the same
+ * string in both places, from `shared-file-rules.ts`, so a rule cannot be
+ * changed in one and left stale in the other.
+ *
+ * The guide is LAYERED (see openspec/changes/agent-guide-layers/design.md):
+ * `get_agent_guide` with no section answers with the short start section
+ * ({@link START_HERE_SECTION_ID}), which says which section answers which
+ * question, and an agent fetches the others by id when a task needs them.
+ * Each section has a token budget (`guide-budget.ts`), held by a test.
  */
 
 import fs from 'node:fs/promises';
@@ -59,6 +66,13 @@ export interface AgentGuideSection {
    * could only misread a folder name it STATES as a placeholder.
    */
   literal?: boolean;
+  /**
+   * The question this section answers, as a row of the start section's
+   * "which section answers what" table. Core's sections are in that table
+   * already; a distribution sets it on a section it adds, so an agent that
+   * reads only the start section is routed to it.
+   */
+  asks?: string;
 }
 
 /**
@@ -86,21 +100,35 @@ export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
  */
 export const NEW_KNOWLEDGE_BASE_SECTION_ID = 'new-knowledge-base';
 
+/**
+ * The first-contact section: what `get_agent_guide` answers when no section is
+ * named. Short on purpose, and the one place that maps each question to the
+ * section answering it, so an agent fetches one section rather than the guide.
+ */
+export const START_HERE_SECTION_ID = 'start-here';
+
+/** The `section` that asks `get_agent_guide` for every section at once. */
+export const WHOLE_GUIDE_SECTION = 'all';
+
 /**
  * Core's sections, in reading order. Every id but the shared-rules one names
  * a file in the package's `agent-guide/` folder.
  */
 export const CORE_SECTION_IDS: readonly string[] = Object.freeze([
-  'introduction',
+  START_HERE_SECTION_ID,
+  'how-agents-find-things',
+  'for-git-users',
+  'glossary',
   'directory-structure',
   'where-a-new-file-goes',
   WORKING_WITH_FILES_SECTION_ID,
   'access-control',
+  'drafts-and-change-requests',
   'skills',
+  'tools',
   'tool-manuals',
   'html-views',
   'conventions',
-  'finding-things',
   NEW_KNOWLEDGE_BASE_SECTION_ID,
 ]);
 
@@ -174,11 +202,21 @@ export interface AgentGuideContext {
    * deployment's tools report back.
    */
   kbDirName?: string;
+  /**
+   * The knowledge base's default branch, rendered into `{{defaultBranch}}` so
+   * the start section names the branch every file tool's `branch` takes for
+   * what is live. Read when the guide is composed: a fresh deployment gets its
+   * branch model from the setup screen after the services are built.
+   */
+  defaultBranch?: string;
 }
 
 /** The checkout folder's name when none is given — core's own default. */
 const DEFAULT_KB_DIR_NAME = 'knowledge-base';
 
+/** What `{{defaultBranch}}` reads as when no branch is configured yet: a name no branch can have. */
+const UNCONFIGURED_DEFAULT_BRANCH = '<the default branch>';
+
 /** One section of the guide as an agent reads it: rendered, with the heading's text as its title. */
 export interface RenderedGuideSection {
   id: string;
@@ -197,7 +235,11 @@ export type AgentGuideSectionsReader = () => Promise<RenderedGuideSection[]>;
  * with its title. The whole guide is these joined (see
  * {@link composeAgentGuide}); `get_agent_guide` also serves one at a time.
  *
- * A hook may append, replace and drop sections, with ONE exception: the
+ * A hook may append, replace and drop sections. It replaces one by returning
+ * its own under the same id, beside core's or in its place: of two sections
+ * under one id the LAST is served, where the FIRST stood, so a distribution
+ * overrides core's `start-here` or `html-views` by adding its own and the
+ * guide keeps its order (see {@link oneSectionPerId}). ONE exception: the
  * shared file rules ({@link WORKING_WITH_FILES_SECTION_ID}) must come back
  * WITH TEXT IN THEM, as core's or as the hook's own replacement. A client
  * that drops the handshake instructions has the guide as the only place to
@@ -215,18 +257,25 @@ export async function agentGuideSections(
 ): Promise<RenderedGuideSection[]> {
   const resolved = resolveKbLayout(layout);
   const core = await coreAgentGuideSections(resolved);
-  const sections = hook ? await hook(core, resolved) : core;
+  const sections = withRoutes(oneSectionPerId(hook ? await hook(core, resolved) : core));
   const kbDirName = context.kbDirName?.trim() || DEFAULT_KB_DIR_NAME;
+  const defaultBranch = context.defaultBranch?.trim() || UNCONFIGURED_DEFAULT_BRANCH;
   const rendered = sections.map((section) => {
     const body = (
       section.literal
         ? section.body
-        : renderKbLayoutPlaceholders(section.body.replaceAll('{{kbDirName}}', () => kbDirName), resolved)
+        : renderKbLayoutPlaceholders(
+            section.body
+              .replaceAll('{{kbDirName}}', () => kbDirName)
+              .replaceAll('{{defaultBranch}}', () => defaultBranch),
+            resolved,
+          )
     ).trim();
     return { id: section.id, title: titleOf(body, section.id), body };
   });
-  // Judged over EVERY section under the id — a hook may return the id twice
-  // — on what survives the empty-body filter below: one with text is enough.
+  // One section per id by now (`oneSectionPerId`), so a hook's own version
+  // of the rules is what is judged, on what survives the empty-body filter
+  // below.
   const rules = rendered.filter((section) => section.id === WORKING_WITH_FILES_SECTION_ID);
   if (!rules.some((section) => section.body.length > 0)) {
     throw new Error(
@@ -237,6 +286,51 @@ export async function agentGuideSections(
   return rendered.filter((section) => section.body.length > 0);
 }
 
+/**
+ * One section per id. A hook that returns an id twice (its own version of a
+ * core section, added beside core's) means the later one: it is served in
+ * the earlier one's place, so a distribution overrides a section by adding
+ * its own under the same id, and the guide keeps core's order. Without this
+ * the whole guide carried both and `get_agent_guide` served the first, which
+ * was always core's.
+ */
+function oneSectionPerId(sections: readonly AgentGuideSection[]): readonly AgentGuideSection[] {
+  const at = new Map<string, number>();
+  const out: AgentGuideSection[] = [];
+  for (const section of sections) {
+    const index = at.get(section.id);
+    if (index === undefined) {
+      at.set(section.id, out.length);
+      out.push(section);
+    } else {
+      out[index] = section;
+    }
+  }
+  return out;
+}
+
+/**
+ * Adds a row to the start section's routing table for every section that
+ * says what it {@link AgentGuideSection.asks} and is not routed there yet.
+ * The rows go after the table's last row. A start section without the table
+ * (a distribution replaced it) is left as it is.
+ */
+function withRoutes(sections: readonly AgentGuideSection[]): readonly AgentGuideSection[] {
+  const start = sections.find((section) => section.id === START_HERE_SECTION_ID);
+  if (!start) return sections;
+  const routed = sections.filter((section) => section.asks?.trim() && !start.body.includes(`| \`${section.id}\` |`));
+  if (routed.length === 0) return sections;
+  const lines = start.body.split('\n');
+  const header = lines.findIndex((line) => /^\|\s*Question\s*\|\s*Section\s*\|/.test(line));
+  if (header < 0) return sections;
+  let last = header;
+  while (last + 1 < lines.length && lines[last + 1]!.startsWith('|')) last += 1;
+  const rows = routed.map((section) => `| ${section.asks!.trim().replaceAll('|', '\\|')} | \`${section.id}\` |`);
+  lines.splice(last + 1, 0, ...rows);
+  const body = lines.join('\n');
+  return sections.map((section) => (section === start ? { ...start, body } : section));
+}
+
 /**
  * The heading's text, or the id when the section opens with no heading. An
  * ATX heading may close with a run of `#` of its own (`## Custom ##`); that
@@ -260,6 +354,19 @@ export async function composeAgentGuide(
   return joinGuideSections(await agentGuideSections(layout, hook, context));
 }
 
+/**
+ * What a `read_file` of the guide's name answers: the start section and the
+ * list of every section, the same as `get_agent_guide` with no `section`, so
+ * no read hands an agent the whole guide unless it asks for it. A guide
+ * without a start section (a distribution dropped it) is answered whole.
+ */
+export function guideStartText(sections: readonly RenderedGuideSection[]): string {
+  const start = sections.find((section) => section.id === START_HERE_SECTION_ID);
+  if (!start) return joinGuideSections(sections);
+  const list = sections.map((section) => `- \`${section.id}\`: ${section.title}`).join('\n');
+  return `${start.body}\n\n### Every section\n\n${list}\n`;
+}
+
 /** The sections as one document, the way `composeAgentGuide` joins them. */
 export function joinGuideSections(sections: readonly RenderedGuideSection[]): string {
   return `${sections.map((section) => section.body).join('\n\n')}\n`;
@@ -268,12 +375,12 @@ export function joinGuideSections(sections: readonly RenderedGuideSection[]): st
 /**
  * What a `read_file` of the guide's name answers when the knowledge base has an
  * `AGENTS.md` of its own: their text first, whole, then a rule and one line
- * saying what follows, then the platform's guide. Theirs first because it is
+ * saying what follows, then the start of the platform's guide. Theirs first because it is
  * the more specific of the two, and the line between so neither is read as
  * part of the other.
  */
 export const PLATFORM_GUIDE_SEPARATOR =
-  "---\n\n_The text above is this knowledge base's own conventions file. The platform's guide follows; `get_agent_guide` returns it on its own._";
+  "---\n\n_The text above is this knowledge base's own conventions file. The start of the platform's guide follows; `get_agent_guide` with a `section` returns the rest._";
 
 export function withPlatformGuideAppended(ownText: string, guide: string): string {
   // Their text as they wrote it, line endings normalised and the trailing

package/src/modules/agent-guide/guide-budget.ts

@@ -0,0 +1,73 @@
+/**
+ * How much each layer of what an agent is told may cost, in tokens.
+ *
+ * Three layers (openspec/changes/agent-guide-layers/design.md): what every
+ * connection carries (the handshake instructions and the tool list), what an
+ * agent reads on first contact (the start section `get_agent_guide` answers
+ * with), and what it fetches only when a task needs it (every other section).
+ * A line in the first layer costs every conversation and every sub-agent; a
+ * line in the last costs only the tasks that fetch it. The budgets are what
+ * keeps the guide from growing into a document every agent loads whole and
+ * reads little of, which is what a customer's agent did fifteen times in one
+ * day.
+ *
+ * Counted with the `o200k_base` encoding by `__tests__/guide-budget.test.ts`.
+ * It is a real tokenizer that runs offline; it is not Claude's own, which
+ * usually counts somewhat more for the same text, so these are ceilings to
+ * compare against each other and over time rather than a model's bill.
+ *
+ * Every number is one a reviewer may move. The point of pinning them is that
+ * growing the guide is a decision someone takes, not a paragraph someone
+ * appends: a section that needs more room says why in the pull request that
+ * raises its line here.
+ */
+
+/** The encoding the budgets are counted in. */
+export const GUIDE_TOKEN_ENCODING = 'o200k_base';
+
+/** The platform's part of the handshake instructions: the header and the shared file rules. */
+export const INSTRUCTIONS_TOKEN_BUDGET = 2_000;
+
+/**
+ * The platform's own tools as the hosted endpoint lists them to an MCP client:
+ * each name, description (with its `Call:` line and, on the four
+ * knowledge-base tools, the purpose prefix) and input schema. Measured over
+ * every registrar the root mounts, the change-request readers and `open_page`
+ * included: 46 tools, 17,278 tokens at 0.35.0 (an earlier figure of 15,710
+ * left those five out).
+ */
+export const TOOL_LIST_TOKEN_BUDGET = 17_500;
+
+/** The ceiling for a section a distribution adds, which core's checks cannot see: the same as core's own. */
+export const SECTION_TOKEN_BUDGET = 2_500;
+
+/**
+ * Each core section's budget, by id. A section without a line here fails the
+ * budget test: a new section starts by saying what it may cost.
+ */
+export const SECTION_TOKEN_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
+  'start-here': 1_200,
+  'how-agents-find-things': SECTION_TOKEN_BUDGET,
+  'for-git-users': SECTION_TOKEN_BUDGET,
+  glossary: SECTION_TOKEN_BUDGET,
+  'directory-structure': SECTION_TOKEN_BUDGET,
+  'where-a-new-file-goes': SECTION_TOKEN_BUDGET,
+  'working-with-files': SECTION_TOKEN_BUDGET,
+  'access-control': SECTION_TOKEN_BUDGET,
+  'drafts-and-change-requests': SECTION_TOKEN_BUDGET,
+  skills: SECTION_TOKEN_BUDGET,
+  tools: SECTION_TOKEN_BUDGET,
+  'tool-manuals': SECTION_TOKEN_BUDGET,
+  // The page contract is long by nature (the frame, the bridge, the link
+  // rules, pages that load live data), and an agent fetches it only to build
+  // a page.
+  'html-views': 5_500,
+  conventions: SECTION_TOKEN_BUDGET,
+  'new-knowledge-base': SECTION_TOKEN_BUDGET,
+});
+
+/** Every core section at once: what `section: "all"` returns. */
+export const WHOLE_GUIDE_TOKEN_BUDGET = 21_500;
+
+/** One task: the start section plus the sections it routes the task to. */
+export const TASK_TOKEN_BUDGET = 6_000;

package/src/modules/agent-guide/index.ts

@@ -3,10 +3,13 @@ export {
   CORE_SECTION_IDS,
   NEW_KNOWLEDGE_BASE_SECTION_ID,
   PLATFORM_GUIDE_SEPARATOR,
+  START_HERE_SECTION_ID,
+  WHOLE_GUIDE_SECTION,
   WORKING_WITH_FILES_SECTION_ID,
   agentGuideSections,
   composeAgentGuide,
   coreAgentGuideSections,
+  guideStartText,
   isAgentGuidePath,
   isManagedGuide,
   joinGuideSections,
@@ -19,4 +22,13 @@ export {
   type RenderedGuideSection,
 } from './agent-guide.js';
 export { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from './agent-guide.tools.js';
+export {
+  GUIDE_TOKEN_ENCODING,
+  INSTRUCTIONS_TOKEN_BUDGET,
+  SECTION_TOKEN_BUDGET,
+  SECTION_TOKEN_BUDGETS,
+  TASK_TOKEN_BUDGET,
+  TOOL_LIST_TOKEN_BUDGET,
+  WHOLE_GUIDE_TOKEN_BUDGET,
+} from './guide-budget.js';
 export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/index.js';

package/src/modules/agent-instructions/__tests__/shared-file-rules.test.ts

@@ -1,6 +1,6 @@
 import { DEFAULT_KB_LAYOUT, PREAMBLE_CAP } from '@bevel-software/platform-shared';
 import { describe, expect, it } from 'vitest';
-import { composeAgentGuide } from '../../agent-guide/agent-guide.js';
+import { composeAgentGuide } from '../../agent-guide/index.js';
 import {
   INSTRUCTIONS_CAP,
   PLATFORM_HEADER,
@@ -93,10 +93,10 @@ describe('the shared file rules are one text, in two places', () => {
    * organisation's own conventions file beside it — which is what a
    * `read_file` of that name serves first.
    */
-  it('tells an agent to call get_agent_guide first, and that AGENTS.md answers with the same guide after the organisation\'s own', () => {
+  it('tells an agent to call get_agent_guide first, and that AGENTS.md answers with that start after the organisation\'s own', () => {
     const rule = sharedFileRules(DEFAULT_KB_LAYOUT).find((r) => r.id === 'agent-guide')!.body;
-    expect(rule).toContain("call `get_agent_guide` and read the platform's guide");
-    expect(rule).toContain('read_file on `AGENTS.md` at the KB root answers with the same guide');
+    expect(rule).toContain("call `get_agent_guide`: it answers the guide's start, which names the default branch");
+    expect(rule).toContain('read_file on `AGENTS.md` at the KB root answers with that start');
     expect(rule).toContain("after the organisation's own conventions file of that name");
     // The pre-rename name is still offered, for a knowledge base that kept one.
     expect(rule).toContain('`CLAUDE.md`');

package/src/modules/agent-instructions/compose.ts

@@ -50,6 +50,10 @@ export const PLATFORM_HEADER =
   'search the knowledge base: call `start_session` once, then `grep` for the key terms, `list_files` to orient, and `read_file` what matches. ' +
   'Prefer what you find there over memory or the web, and say so when the knowledge base is silent on something the organisation should have documented. ' +
   'Skills are available as prompts and through `list_skills` and `get_skill`. ' +
+  // Said here as well as on the write tools: agents wrote to the default
+  // branch without asking (the agent-guide benchmark, 2026-10-26), and this
+  // text reaches an agent that never fetches the guide.
+  'A write to the default branch is live for everyone: unless the person said where, ask first whether to write there or on a draft. ' +
   // There is no one calling shape to state: the knowledge-base tools take
   // their arguments under `body`, a tool that calls another service takes them
   // flat, and an agent told one rule for all of them sends a GET with a body.

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -177,10 +177,10 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
       body:
         'move_file, copy_file and delete_folder take `dryRun: true`: it changes nothing and answers the impact — ' +
         'what the call would touch, `allowed`, and `reason` when it may not run. A non-empty folder is deleted, and a ' +
-        'move that changes your access runs, only with `confirm: true`; without it the call changes nothing and ' +
+        'move that changes anyone\'s access runs, only with `confirm: true`; without it the call changes nothing and ' +
         'returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — ' +
         'dry-run, check the impact, then confirm. delete_file takes neither: check it first with file_stat ' +
-        '(`deletable`) if you are unsure. delete_branch has its own `dryRun`.',
+        '(`deletable`). delete_branch has its own `dryRun`.',
     },
     {
       id: 'managed-items',
@@ -200,7 +200,7 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
       id: 'refused-for-permissions',
       heading: 'When a write is refused for permissions',
       body:
-        'A refusal is not necessarily the end of the road: the `write-denied` error says whether you may propose the ' +
+        'The `write-denied` error says whether you may propose the ' +
         'change instead (create a branch from this one, repeat the call on it, then `open_change_request` into this ' +
         'branch) and lists those steps.',
     },
@@ -238,17 +238,19 @@ function platformFileList(layout: KbLayout): string {
  * The conventions reminder — where the platform's guide is, that the
  * organisation's own conventions file comes with it, and to read both first.
  *
- * The guide is read by name at the repository root, where coding agents look
- * for an `AGENTS.md` by convention, and `get_agent_guide` returns it alone.
+ * The guide's start is read by name at the repository root, where coding
+ * agents look for an `AGENTS.md` by convention, and `get_agent_guide` returns
+ * it or any one section.
  * One name on every deployment, so the rule takes no layout. `CLAUDE.md` is
  * named as a fallback because a knowledge base seeded before the rename may
  * still carry one its people edited.
  */
 function conventionsRule(): string {
   return (
-    "Before your first read or change in a workspace, call `get_agent_guide` and read the platform's guide " +
-    `(whole, or one section). read_file on \`${LEGACY_AGENTS_FILE}\` at the KB root answers with the same ` +
-    "guide, after the organisation's own conventions file of that name when it has one: follow both. A " +
+    "Before your first read or change in a workspace, call `get_agent_guide`: it answers the guide's start, " +
+    "which names the default branch and the section for each question. " +
+    `read_file on \`${LEGACY_AGENTS_FILE}\` at the KB root answers with ` +
+    "that start, after the organisation's own conventions file of that name when it has one: follow both. A " +
     `\`${PRE_RENAME_AGENTS_FILE}\` at the KB root is the organisation's own too; read it if it exists.`
   );
 }

package/src/modules/code-mode/code-mode.tool.ts

@@ -51,7 +51,7 @@ export function createCallToolChainTool(
       `There is NO single calling shape: some tools take their arguments under a \`body\` object, others take them flat. Call each tool as the \`Call:\` line at the top of its own description shows — it is generated from that tool's input schema, and every tool in \`${ns}\` has one. Every argument a tool declares REQUIRED must be present; for the knowledge-base tools that includes \`branch\`. Arguments that do not match the schema are refused before anything is sent or run, and the refusal carries the tool's interface.`,
       'Error handling inside the chain: a failing tool call THROWS, and the thrown error\'s `.message` holds the server\'s actual reason (e.g. a 403 with the explanation, not just a status code). If you catch it, surface `err.message` (and `err.status` / `err.data` when present) — NEVER `return { error: err }` or otherwise return the raw Error object, because an Error serializes to `{}` (its `message` is non-enumerable) and the reason is lost. If you don\'t need to handle it, just let it throw — the runtime already reports `err.message` back to you.',
       `Failures are answered, never dropped: a chain that throws comes back with \`success: false\` and the reason, and one that outlives \`timeout\` (default ${CHAIN_TIMEOUT_DEFAULT_MS} ms, maximum ${CHAIN_TIMEOUT_MAX_MS} ms) comes back saying it timed out — raise \`timeout\` or split the work and run it again. Either way your next tool call works as usual.`,
-      'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (its `branch` is ignored) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
+      'Large return values: if the returned value exceeds `max_output_size`, the full JSON is auto-spilled to a shared spill store (outside any workspace, never committed) and the response contains only a `__tool_chain_spill__/…` ref + a truncated marker. You can read the spill back with the regular `read_file` tool — pass that ref as `path` (any existing branch as `branch`; it is not used) plus `offset` / `limit` to slice it, never read a multi-MB file in full. Order of preference: (1) re-run `call_tool_chain` with a follow-up code chain that filters/maps the data inline and returns just what you need; (2) narrow the API call — shorter `fields`, tighter date window, lower `limit`; (3) last resort — `read_file` against the spill ref with `offset` / `limit`. The spill is read-only context only; do NOT use it as a way to persist KB content — for KB writes use the regular `write_file` / `edit_file` tools, which go through the lock/commit pipeline.',
     ].join('\n\n'),
     inputSchema: z.object({
       code: z
@@ -121,7 +121,7 @@ export function createCallToolChainTool(
           truncated: true,
           result_ref: ref,
           result_bytes: bytes,
-          message: `Combined result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON (both \`result\` and \`logs\`) saved to the shared spill store as \`${ref}\` (outside any workspace, uncommitted). Read it back with \`read_file\` — pass that ref as \`path\` (\`branch\` is ignored) plus \`offset\` / \`limit\` for a slice — or, usually better, narrow the next \`call_tool_chain\` call (smaller fields list, tighter date window, lower limit) so the result fits inline.`,
+          message: `Combined result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON (both \`result\` and \`logs\`) saved to the shared spill store as \`${ref}\` (outside any workspace, uncommitted). Read it back with \`read_file\` — pass that ref as \`path\` (any existing branch as \`branch\`; it is not used) plus \`offset\` / \`limit\` for a slice — or, usually better, narrow the next \`call_tool_chain\` call (smaller fields list, tighter date window, lower limit) so the result fits inline.`,
         };
       } catch (err) {
         // The chain itself SUCCEEDED and only its delivery failed, so the logs

package/src/modules/connection-probe/__tests__/connection-probe.service.test.ts

@@ -4,8 +4,8 @@ import type {
   IToolManualService,
   ToolHealthCheck,
   ToolProbeTarget,
-} from '../../tool-manuals/tool-manuals.contract.js';
-import type { ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
+} from '../../tool-manuals/index.js';
+import type { ISecretsVaultService } from '../../secrets-vault/index.js';
 
 /**
  * The three-way verdict is the whole point of this module, and the line that
@@ -33,7 +33,7 @@ vi.mock('@utcp/code-mode', () => ({
   CodeModeUtcpClient: { create: () => createClientMock() },
 }));
 
-const { ConnectionProbeService, readCapped } = await import('../connection-probe.service.js');
+const { ConnectionProbeService } = await import('../connection-probe.service.js');
 
 const DECLARED_PROBE: ToolHealthCheck = {
   url: 'https://api.acme.test/me',
@@ -739,25 +739,6 @@ describe('ConnectionProbeService: what the probe concludes', () => {
     expect(r?.detail!.length).toBeLessThan(400);
     expect(cancelled).toBe(true);
   });
-
-  /**
-   * The cap has to bound what is DECODED, not merely how many times we loop.
-   * Counting a chunk against the budget after decoding it lets a provider that
-   * answers in one huge chunk put the whole thing through the decoder — the
-   * bound bypassed by exactly the party it exists to bound. Asserted on
-   * `readCapped` directly because the caller's 200-character snippet is
-   * identical either way, which is how the first version of this passed.
-   */
-  it('holds one oversized chunk to the byte budget, not just the loop', async () => {
-    const oneHugeChunk = new ReadableStream<Uint8Array>({
-      start(controller) {
-        controller.enqueue(new TextEncoder().encode('x'.repeat(5_000_000)));
-        controller.close();
-      },
-    });
-
-    const out = await readCapped(new Response(oneHugeChunk), 8 * 1024);
-
-    expect(out.length).toBe(8 * 1024);
-  });
+  // The byte budget's own property (one oversized chunk held to the cap) is
+  // asserted on the shared reader in `shared/__tests__/read-capped.test.ts`.
 });