@bevel-software/platform-shared 0.25.0 → 0.26.0

package/src/git/pr.types.ts

@@ -41,8 +41,33 @@ export interface PullRequestSummary {
   base: string;
   state: PullRequestState;
   createdAt: string;
+  /**
+   * The latest moment the change-request ROW records: the latest of its
+   * creation time, its `updated_at` stamp (written when the row itself
+   * changes — a merge, a close, a recorded apply failure) and its close time.
+   * GitHub's `updated_at` on a pull request means "when anything about it
+   * last changed"; comments and approvals carry their own times here and do
+   * not move this one, so this is as close as the row can honestly answer —
+   * never a time guessed from elsewhere. Absent only on a summary built by
+   * something other than a change-request row (test doubles).
+   */
+  updatedAt?: string;
   /** Relative paths within `knowledge-base/`. Empty if not yet computed. */
   touchedNodePaths: string[];
+  /**
+   * The same changed files as {@link touchedNodePaths}, paired with the path
+   * each was renamed from — what a READ gate has to decide over, since
+   * `touchedNodePaths` reports a rename under its new name alone and so cannot
+   * say that a readable-looking file came out of a folder its reader cannot
+   * open.
+   *
+   * Absent when no summary builder filled it (a test double, a caller that
+   * constructs a summary by hand). A read gate must treat absence as "nothing
+   * proven" rather than falling back to `touchedNodePaths` — that fallback is
+   * precisely the disagreement between a list and a detail this field exists to
+   * remove, and it would come back silently.
+   */
+  touchedNodeFiles?: ChangedPathPair[];
   review: PullRequestReviewStatus;
   /**
    * Link to the change request: absolute (`<public frontend address>/change-requests/<number>`)
@@ -79,6 +104,69 @@ export interface ChangeRequestApplyFailure {
   byName: string;
 }
 
+/**
+ * One changed file of a change request, named on both sides: where it is now
+ * and, for a rename, where it came from.
+ *
+ * The minimum a READ gate needs. A plain path list says a rename's new name and
+ * (with `forAccessCheck`) its old one, but not that the two are the same file —
+ * and the diff of a rename shows the old side's content, so a file moved out of
+ * a folder its reader cannot open must not be offered under its new name
+ * either. Both the list of change requests and the detail of one decide
+ * readability over these, so the two cannot disagree about whether a request is
+ * visible.
+ */
+export interface ChangedPathPair {
+  path: string;
+  previousPath?: string;
+}
+
+/**
+ * An APPLIED change request, named by BOTH the commit its row records and the
+ * number that row carries — because reading the commit's own change is only
+ * sound if the commit really is that request's merge commit, and the number is
+ * what proves it (the merge commit's subject ends with `(#<number>)`).
+ *
+ * The pair travels together so no read can ask for a commit without saying which
+ * request it must belong to. `merged_sha` is not reliably a commit the request
+ * created: a merge with nothing to merge used to record the TARGET TIP, which in
+ * a deployment that lands everything through change requests is usually ANOTHER
+ * request's merge commit.
+ */
+export interface AppliedChangeRef {
+  /** The change request's number, as its merge commit's subject names it. */
+  number: number;
+  /** The `merged_sha` the row records. */
+  mergeSha: string;
+  /**
+   * The request's stored title, which lets a merge commit written by an
+   * earlier release — the title not yet flattened, so a blank line in it put
+   * the number after git's subject — be recognised as the request's own.
+   */
+  title?: string;
+}
+
+/**
+ * What applying a change request did.
+ *
+ * Two different commits, which is why they are two fields:
+ *
+ *   `sha` is the state the target is left at — the tip at which the request
+ *   counts as merged. When there was nothing to merge it is whatever landed on
+ *   the target last, usually ANOTHER request's merge commit, so it must never be
+ *   recorded as this request's own: a reader would answer with that other
+ *   request's files under this number.
+ *
+ *   `mergeCommit` is the commit this request OWNS, and the only sha a row may
+ *   record as its `merged_sha` — the commit this merge wrote, or the one an
+ *   earlier attempt wrote and left on the target when it failed to finalize the
+ *   row. Null when the request has none, which is the genuinely empty case: its
+ *   file list is empty anyway, so nothing readable is lost.
+ */
+export type AppliedMergeResult =
+  | { kind: 'merged'; sha: string; mergeCommit: string | null }
+  | { kind: 'conflicts'; paths: string[] };
+
 export type PrFileStatus =
   | 'added'
   | 'modified'
@@ -368,6 +456,17 @@ export interface IPullRequestService {
    * via `gh pr create`) and the user expects to see the update immediately.
    */
   listOpenPrs(opts?: { fresh?: boolean }): Promise<PullRequestSummary[]>;
+  /**
+   * PRs in ANY of `states`, newest first — what `listOpenPrs` answers for the
+   * open ones, widened to the closed and merged rows it filters out. Only the
+   * `['open']` case goes through that method's 30s list cache; a read that
+   * asks for closed rows is rare (a reader catching up on what happened) and
+   * is served straight from the table.
+   */
+  listPrsByState(
+    states: PullRequestState[],
+    opts?: { fresh?: boolean; workspaceId?: string },
+  ): Promise<PullRequestSummary[]>;
   listPrsAuthoredBy(githubLoginOrEmail: string): Promise<PullRequestSummary[]>;
   /**
    * PRs whose touched paths have an owner with the given email.

package/src/git/types.ts

@@ -1,5 +1,5 @@
 import type { AuthUser } from '../auth/types.js';
-import type { PullRequestFile } from './pr.types.js';
+import type { AppliedChangeRef, ChangedPathPair, PullRequestFile } from './pr.types.js';
 
 export interface BranchInfo {
   name: string;
@@ -278,6 +278,81 @@ export interface IGitService {
     opts?: { fetch?: boolean },
   ): Promise<string[]>;
 
+  /**
+   * `changedPathsForPr`'s answer AND the same diff left as rename-aware pairs,
+   * from ONE `git diff`.
+   *
+   * The flat list cannot pair a rename's two paths: git reports a rename under
+   * its new name, and `forAccessCheck` adds the old name to the same
+   * undifferentiated set. That union is enough to authorize a WRITE ("may they
+   * touch everything this lands?"), but not to decide a READ — a file renamed
+   * out of a folder the caller cannot open is readable under neither of its
+   * names, since the diff of a rename shows the old side's content, and
+   * deciding that needs to know which old path belongs to which new file. The
+   * change-request read tools gate their file lists on exactly this, and the
+   * list of requests must reach the same verdict as the detail of one.
+   */
+  changedPathsAndPairsForPr(
+    workspaceId: string,
+    baseBranch: string,
+    headBranch: string,
+    opts?: { fetch?: boolean },
+  ): Promise<{ paths: string[]; pairs: ChangedPathPair[] }>;
+
+  /**
+   * The changed-file list an APPLIED change request landed, read from its merge
+   * commit against that commit's first parent.
+   *
+   * Its source branch is retired, so the branch pair the other two methods want
+   * no longer exists; what is left is the merge commit the row records. Its
+   * first parent is the target as it stood before the merge, so the two-dot diff
+   * between them is precisely what the request applied — and immutable, which
+   * the branch pair never was.
+   *
+   * The commit is VERIFIED to be that request's own, which is why the ref
+   * carries the number as well as the sha: a merge with nothing to merge used to
+   * record the target tip, and reading that commit's change would answer with
+   * another request's files. It must be in the clone, have a second parent, and
+   * carry a subject naming this request; anything else rejects with
+   * `WorkflowValidationError`, which every caller reads as "the file set could
+   * not be resolved" and answers fail-closed (no files, so author-only) rather
+   * than reaching for a fetch per request.
+   *
+   * No network, either way.
+   */
+  changedFilesOfAppliedChange(
+    workspaceId: string,
+    applied: AppliedChangeRef,
+    opts?: { patchCap?: number },
+  ): Promise<PullRequestFile[]>;
+
+  /**
+   * The same applied change as the two path views a change-request SUMMARY
+   * needs, out of one `git diff` — `changedPathsAndPairsForPr` for an applied
+   * request instead of a branch pair, with the same verification and the same
+   * no-network contract as {@link changedFilesOfAppliedChange}.
+   */
+  changedPathsAndPairsOfAppliedChange(
+    workspaceId: string,
+    applied: AppliedChangeRef,
+  ): Promise<{ paths: string[]; pairs: ChangedPathPair[] }>;
+
+  /**
+   * The two commits an APPLIED change request spanned, recovered from its merge
+   * commit: the target before the merge (`^1`) and the source tip that was
+   * merged (`^2`).
+   *
+   * The head matters beyond being informative: an approval is called stale when
+   * the head it was given against is not the detail's `headSha`, so answering
+   * the merge commit there would report every approval a merged request ever
+   * collected as stale. Same verification, same no-network contract and the same
+   * `WorkflowValidationError` as {@link changedFilesOfAppliedChange}.
+   */
+  appliedChangeShas(
+    workspaceId: string,
+    applied: AppliedChangeRef,
+  ): Promise<{ baseSha: string; headSha: string }>;
+
   /**
    * A change request's fork point (merge base of the two resolved commits)
    * and whether the target has commits the proposal does not contain. No

package/src/workflow/interface.ts

@@ -437,6 +437,17 @@ export interface IWorkflowService {
   // ── Change Requests ───────────────────────────────────────────────────────
 
   listChangeRequests(opts?: { fresh?: boolean }): Promise<ChangeRequest[]>;
+  /**
+   * Change requests in ANY of `states`, newest first. `listChangeRequests`
+   * answers the open ones only — the app's lists are all about what is still
+   * being decided — so a reader catching up on what HAPPENED (the agent read
+   * tools' `state: closed` / `state: all`) needs this one.
+   */
+  listChangeRequestsByState(
+    states: ChangeRequestState[],
+    /** `workspaceId`: the clone to read file lists in; any clone will do, and a caller that resolved one passes it so the list and the by-number reads agree. */
+    opts?: { fresh?: boolean; workspaceId?: string },
+  ): Promise<ChangeRequest[]>;
   /** Change requests authored by the given user (matched on stored author identity). */
   listChangeRequestsAuthoredBy(
     emailOrLogin: string,

package/src/workspace/kb-layout.ts

@@ -111,31 +111,30 @@ export let SKILLS_DIR = 'Skills';
 export let PLUGINS_DIR = 'Plugins';
 
 /**
- * The file name of the platform's MANAGED agent guide at the repository root —
- * the document every connected agent is told to read first, written and
- * refreshed from the packaged template on every start.
- *
- * Configurable for one reason: `AGENTS.md` is the name coding agents look for
- * by convention, so a customer arriving with a repository of their own very
- * often already HAS one, and under the default name the platform would
- * overwrite it on the first boot and on every boot after. Renaming the managed
- * guide (`HEXIS.md`, say) hands that name back: `AGENTS.md` becomes ordinary
- * content the platform never writes, never refreshes and never hides, and the
- * customer's file is the one that points at ours (see
- * {@link agentsFilePointerSentence}).
- *
- * A live binding like the three roots above — read it inside a function body,
- * never capture it at module scope.
+ * The name the platform's agent guide is READ BY at the repository root — the
+ * document every connected agent is told to read first.
+ *
+ * The guide is no longer a file: the backend composes it from text the code
+ * owns and serves it through `get_agent_guide` and through a `read_file` of
+ * this name (see core-backend's `modules/agent-guide`), after the knowledge
+ * base's own file of that name when it has one. ONE name on every
+ * deployment: the setting that let a deployment rename the written guide is
+ * gone, and the settings layer no longer reads a value it saved — the layout
+ * it produces carries this name. The field stays on the layout for the shape
+ * every consumer reads, and the helpers here (`agentsFileOf`,
+ * `configureKbLayout`) still apply whatever a caller puts in it, so the one
+ * name is the producer's doing, not this module's.
  */
 export let AGENTS_FILE = 'AGENTS.md';
 
 /**
- * The name the managed guide had when it was the only name it could have.
+ * The name the guide had when it was the only name it could have, and the
+ * name it is always read by now.
  *
  * Referenced ONLY by the code that has to tell OUR file from THEIRS — the
- * boot-time removal of a platform-written `AGENTS.md`, the ignore rule that
- * stops hiding it, the instruction telling an agent to read the customer's
- * file too. In the spirit of {@link LEGACY_GROUPS_DIR}: a second live spelling
+ * boot-time removal of the guide copies earlier releases wrote, the ignore
+ * rule that stops hiding them, the instruction telling an agent what to read
+ * first. In the spirit of {@link LEGACY_GROUPS_DIR}: a second live spelling
  * of the CURRENT name is how two layouts start being supported by accident, so
  * this one is a constant and means exactly one thing.
  */
@@ -143,11 +142,11 @@ export const LEGACY_AGENTS_FILE = 'AGENTS.md';
 
 /**
  * The platform files whose names are FIXED — the ones no deployment renames.
- * The guide is the fourth platform file and is deliberately absent here: its
- * name is {@link AGENTS_FILE}, and `platform-files.ts` composes the two into
- * the set every gate reads.
+ * The guide is NOT a platform file: nothing is written under its name, so a
+ * root `AGENTS.md` (or whatever the deployment once called the guide) is the
+ * organisation's own conventions page, movable and deletable like any other.
  *
- * It lives in this module rather than beside that composition because the
+ * It lives in this module rather than beside `platform-files.ts` because the
  * LAYOUT has to validate against it (a guide may not be called `access.md`),
  * and `platform-files.ts` already reads this module — the other direction
  * would be a cycle.
@@ -196,139 +195,13 @@ export function agentsFileOf(layout: KbLayout): string {
  * a leading `#` is a comment and a leading `!` a negation (the rule would
  * silently hide nothing), `[`, `]`, `*` and `?` are globs, and a backslash is
  * the escape itself. Each is escaped so the pattern names exactly the file.
+ * Read by the startup step that takes the platform's own rule for the guide
+ * OUT of an ignore file an earlier release wrote it into.
  */
 export function gitignoreLiteral(name: string): string {
   return name.replace(/[[\]*?\\]/g, '\\$&').replace(/^([#!])/, '\\$1');
 }
 
-/**
- * The ONE sentence the platform offers to keep in a customer's own
- * `AGENTS.md`, pointing at the managed guide beside it.
- *
- * Defined here, once, because two surfaces must produce the identical text:
- * the deployment-settings field previews it before the admin consents, and the
- * startup step appends it. A sentence written twice is a sentence that drifts,
- * and a drifted one appends a SECOND copy to every customer file on the boot
- * after the drift — which is the one thing this whole feature exists to stop.
- *
- * A guide name is a FILE NAME, not an identifier: everything `validateFilename`
- * admits can appear in it — spaces, brackets, parentheses, `#`, `%` — and each
- * of those means something in an inline link. So the link is BUILT rather than
- * interpolated: the label backslash-escaped ({@link markdownLinkLabel}), the
- * destination percent-encoded ({@link agentsFileLinkPath}). A name that only
- * parenthesised would break the destination; `#` would turn the rest of the
- * name into a URL fragment, and the link would point at the customer's own
- * file.
- *
- * Neither spelling need match the name as it is on disk, so nothing may ask
- * whether this sentence is present by searching for the RAW name — see
- * {@link mentionsAgentsFile}, which is how the startup step asks.
- */
-export function agentsFilePointerSentence(agentsFile: string): string {
-  return `Read [${markdownLinkLabel(agentsFile)}](${agentsFileLinkPath(agentsFile)})${POINTER_SENTENCE_TAIL}`;
-}
-
-/**
- * Everything of the sentence that does NOT depend on the guide's name — split
- * out so the one definition above can also be RECOGNISED, by the pattern below,
- * when the name it was written with is no longer the name in effect.
- */
-const POINTER_SENTENCE_TAIL =
-  " before working in this knowledge base — it is the platform's guide to its layout, files and rules.";
-
-/**
- * A pointer sentence the platform wrote, naming ANY guide.
- *
- * The label admits a backslash escape (`\[`, `\]`) because that is what
- * {@link markdownLinkLabel} puts there; the destination cannot contain a `)`
- * or a newline because {@link agentsFileLinkPath} encodes both. Anchored at
- * both ends by text the platform fixed, so the shape is the provenance —
- * a customer would have to reproduce our sentence word for word to be taken
- * for us, which is the same bar the managed-guide header sets.
- */
-const POINTER_SENTENCE_PATTERN = new RegExp(
-  `Read \\[(?:[^\\]\\n\\\\]|\\\\[\\s\\S])*\\]\\(\\.\\/[^)\\n]*\\)${escapeRegExp(POINTER_SENTENCE_TAIL)}`,
-  'g',
-);
-
-/** `text` as a literal inside a regular expression. */
-function escapeRegExp(text: string): string {
-  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * `text` with every pointer sentence THE PLATFORM WROTE aimed at `agentsFile`
- * — or null when it holds none of ours.
- *
- * This is what a SECOND rename needs. The guide's name is a setting an admin
- * may change again: a knowledge base whose `AGENTS.md` was given a sentence
- * pointing at `HEXIS.md` and is then renamed to `GUIDE.md` must have that
- * sentence aimed at the new file, not a second one appended beneath a first
- * that now points at nothing. Asking only whether the NEW name is mentioned
- * cannot see that — the old sentence does not mention it.
- *
- * Returning the text unchanged (rather than null) when the sentence is already
- * right is deliberate: "ours and correct" and "not ours at all" are different
- * answers, and only the caller knows that the second one means "consider
- * appending".
- */
-export function retargetAgentsFilePointer(text: string, agentsFile: string): string | null {
-  let found = false;
-  const wanted = agentsFilePointerSentence(agentsFile);
-  const updated = text.replace(POINTER_SENTENCE_PATTERN, () => {
-    found = true;
-    return wanted;
-  });
-  return found ? updated : null;
-}
-
-/**
- * `text` as an inline link's LABEL: the characters that would end the label or
- * start emphasis or code inside it, backslash-escaped. Nothing else is touched
- * — a filename is read by people, and `AGENTS\.md` helps no one.
- */
-function markdownLinkLabel(text: string): string {
-  return text.replace(/[\\[\]`*_]/g, (c) => `\\${c}`);
-}
-
-/**
- * The guide as an inline link's DESTINATION: `./` and the name, percent-encoded.
- *
- * `encodeURI` does most of it (a space, a bracket, and `%` itself, so an
- * already-encoded-looking name is not decoded by a reader). Three more are
- * encoded by hand because `encodeURI` leaves them and each one ENDS the path
- * early: `#` opens a fragment, and `(`/`)` close the destination in
- * CommonMark's bare form. `?` and the rest of the URL-significant set are
- * already refused by {@link validateFilename}.
- *
- * An ordinary name has none of these and comes out exactly as it went in.
- */
-function agentsFileLinkPath(agentsFile: string): string {
-  return `./${encodeURI(agentsFile).replace(/[#()]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}`;
-}
-
-/**
- * Whether `text` already points at the guide — the ONE question the startup
- * step asks before appending {@link agentsFilePointerSentence} to a customer's
- * own `AGENTS.md`.
- *
- * The plain name is the answer that matters: a mention in the customer's own
- * words, a heading, a link they wrote, all count, and the platform stays out
- * of a file it does not own. The other two spellings are the platform's OWN,
- * and they are here for idempotence: the sentence writes the name escaped in
- * the label and encoded in the destination, so on a punctuated name the file
- * the last boot wrote need not contain the raw name at all. Asking only for
- * that one would append a second copy on the next boot, and a third on the
- * one after — the exact failure this feature exists to prevent.
- */
-export function mentionsAgentsFile(text: string, agentsFile: string): boolean {
-  return (
-    text.includes(agentsFile) ||
-    text.includes(markdownLinkLabel(agentsFile)) ||
-    text.includes(agentsFileLinkPath(agentsFile))
-  );
-}
-
 /**
  * What is wrong with one root name, or null. A root is joined onto the repo
  * root and onto `<dir>/.gitkeep`, so a separator or `..` would write outside
@@ -350,22 +223,16 @@ export function validateKbRootName(name: string): string | null {
 }
 
 /**
- * What is wrong with the agent guide's file name, or null.
- *
- * The rules, and what each one is for:
+ * What is wrong with the agent guide's name, or null. The rules date from when
+ * the guide was written to disk under this name; a saved name still has to be
+ * one the read tools can answer to, so they stand:
  *
- *  - ONE FILE NAME. The name is joined onto the repository root and read from
- *    there and nowhere else, so a separator would name a file the platform
- *    would write but never read back.
- *  - A MARKDOWN NAME. The guide is a markdown document that people open in the
- *    app and agents read as text; `.md` is also what the per-file access rules
- *    apply to, so a guide under any other extension would take its folder's
- *    rules and stop being readable by everyone.
- *  - NOT `CLAUDE.md`. That is the guide's own pre-rename name; knowledge bases
- *    seeded before the rename still carry one, and it stays legacy content
- *    rather than becoming a second managed file.
- *  - NOT ANOTHER PLATFORM FILE. Two platform roles on one path means whichever
- *    writer runs last wins, silently.
+ *  - ONE FILE NAME. The name is read at the repository root and nowhere else.
+ *  - A MARKDOWN NAME. The guide is markdown that agents read as text.
+ *  - NOT `CLAUDE.md`. That is the guide's own pre-rename name; a knowledge
+ *    base seeded before the rename may still carry one of its own.
+ *  - NOT ANOTHER PLATFORM FILE. A read of `access.md` must answer with the
+ *    access rules, not the guide.
  *  - NOT A ROOT FOLDER'S NAME, compared case-insensitively like the roots are
  *    to each other: the workspaces live on case-insensitive filesystems, where
  *    a file `Docs.md` and a folder `docs.md` are one entry.
@@ -530,13 +397,13 @@ export function isDefaultKbLayout(layout: KbLayout): boolean {
 }
 
 /**
- * Render the layout placeholders a managed template carries —
+ * Render the layout placeholders a managed text carries —
  * `{{knowledgeBaseDir}}`, `{{skillsDir}}`, `{{pluginsDir}}`, `{{agentsFile}}`
- * — with the names in effect. The packaged guide and `.bevelignore` are
- * written this way so a deployment that renamed its roots hands the agent a
- * guide that names the folders it will actually find, and a deployment that
- * renamed the guide gets a guide naming the file it lives in. Text without
- * placeholders passes through unchanged.
+ * — with the names in effect. The agent guide's sections and the packaged
+ * `.bevelignore` are written this way so a deployment that renamed its roots
+ * hands the agent a guide that names the folders it will actually find, and
+ * one that gave the guide a name of its own gets a guide naming it. Text
+ * without placeholders passes through unchanged.
  */
 export function renderKbLayoutPlaceholders(text: string, layout: KbLayout): string {
   // Replacer FUNCTIONS: a string replacement would interpret `$&`, `$$` and

package/src/workspace/platform-files.ts

@@ -1,7 +1,6 @@
 import {
   DEFAULT_KB_LAYOUT,
   FIXED_PLATFORM_FILE_NAMES,
-  agentsFileOf,
   reservedRootDirNames,
   type KbLayout,
 } from './kb-layout.js';
@@ -9,28 +8,26 @@ import {
 /**
  * The files the platform reads as configuration, not content. `access.md`
  * governs the folder it sits in and `.bevelignore` layers like `.gitignore`,
- * so both count at any depth; `roles.yaml` and the agent guide are read from
- * the repository root only, so a nested file of either name is ordinary
- * content. Moving one changes what the platform enforces, so moves refuse them.
+ * so both count at any depth; `roles.yaml` is read from the repository root
+ * only, so a nested file of that name is ordinary content. Moving one changes
+ * what the platform enforces, so moves refuse them.
  *
- * A FUNCTION OF THE LAYOUT, not a constant, and that is the whole of the
- * configurable-guide change on this side: the guide's name is a deployment
- * setting, so the fourth platform file is `HEXIS.md` on one deployment and
- * `AGENTS.md` on the next — and on the first, a root `AGENTS.md` is the
- * CUSTOMER'S own conventions file, which has to move and delete like any page.
- * Every gate asks this with the layout it serves rather than reading a list
- * captured at module load.
+ * The agent guide is NOT among them. It was, while the platform wrote it to
+ * the repository root; the backend serves it from code now (core-backend's
+ * `modules/agent-guide`), and a root `AGENTS.md` — or a file under whatever
+ * name a deployment once gave the guide — is the organisation's own
+ * conventions page, which moves and deletes like any other.
+ *
+ * Still a FUNCTION OF THE LAYOUT, so every gate asks the question the same
+ * way it asks the others, and a file the layout makes a platform file again
+ * one day needs no caller to change.
  */
-export function platformFileNames(layout: KbLayout): readonly string[] {
-  return [...FIXED_PLATFORM_FILE_NAMES, agentsFileOf(layout)];
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- the layout is the question's shape, kept for every caller (see above)
+export function platformFileNames(_layout: KbLayout): readonly string[] {
+  return [...FIXED_PLATFORM_FILE_NAMES];
 }
 
-/**
- * The platform file names under the DEFAULT layout — what they were before the
- * guide could be renamed. Kept for callers that want the default answer rather
- * than this deployment's; anything judging a real path asks
- * {@link platformFileNames}, which knows what this deployment called its guide.
- */
+/** The platform file names under the DEFAULT layout — the same three on every deployment. */
 export const PLATFORM_FILE_NAMES: readonly string[] = Object.freeze(
   platformFileNames(DEFAULT_KB_LAYOUT),
 );
@@ -41,8 +38,8 @@ const PLATFORM_FILES_AT_ANY_DEPTH = new Set(['access.md', '.bevelignore']);
 /**
  * The platform files split by the DEPTH they count at, which is the half of
  * {@link isPlatformFile} that a name alone does not tell you: `access.md` and
- * `.bevelignore` are platform files in any folder, `roles.yaml` and the agent
- * guide only in the repository root.
+ * `.bevelignore` are platform files in any folder, `roles.yaml` only in the
+ * repository root.
  *
  * Exported because the agent-facing rules state that split in prose, and a
  * prose list written by hand drifts from the predicate that actually refuses
@@ -111,7 +108,7 @@ export function platformFileCreationRefusal(pathOrName: string): string {
 /**
  * The sentence an UPLOAD is refused with when one of its paths would land a
  * platform file — a zip carrying an `access.md`, a `.bevelignore`, a
- * `roles.yaml` or the agent guide, or a single file sent under one of those
+ * `roles.yaml`, or a single file sent under one of those
  * names.
  *
  * Its own sentence rather than the move's, because the thing being kept out is
@@ -151,7 +148,7 @@ export function platformFolderRefusal(repoRelativeDir: string): string {
 
 /**
  * Whether the platform file at `repoRelativePath` sits directly in the
- * repository root — the copy every one of the four is read from there, and so
+ * repository root — the copy every one of the three is read from there, and so
  * never the misplaced one: it is the copy a restore puts back. A nested
  * `access.md` or `.bevelignore` is a platform file too, but it layers on top
  * of the root's rather than standing in for it, which is why moving the
@@ -165,7 +162,7 @@ export function isRootPlatformFile(repoRelativePath: string, layout: KbLayout):
  * The place a misplaced platform file is allowed to be put back, when
  * `repoRelativeDestination` names one, and null when it does not.
  *
- * `roles.yaml` and the agent guide are read from the repository root and
+ * `roles.yaml` is read from the repository root and
  * nowhere else, so their one required location is the root. A nested `.bevelignore` is
  * read too (it layers, see `BevelIgnoreStack`), yet a restore of one lands at
  * the root only — a deliberate narrowing of the exception, not a claim about
@@ -204,8 +201,8 @@ export function platformRestoreDestination(
  * Three things make the shape, and all three are about the move rather than
  * about the source's current standing:
  *
- *  - the source is NAMED like a platform file. A nested `roles.yaml`, or a
- *    nested copy of the agent guide, is ordinary content where it sits
+ *  - the source is NAMED like a platform file. A nested `roles.yaml` is
+ *    ordinary content where it sits
  *    (`isPlatformFile` says so, and moving it needs no exception), but it is
  *    still the copy a restore carries back to the root — judging the shape on
  *    `isPlatformFile` would skip the exception for exactly the two files the