@bevel-software/platform-core-backend 0.4.1 → 0.5.0

package/src/modules/workspace/__tests__/workspace.tools.test.ts

@@ -338,25 +338,33 @@ describe('workspace file primitives', () => {
     expect(res.stdout.trim()).toBe('kb-seed');
   });
 
-  it('execute_command does not leak GIT_DIR into non-git commands', async () => {
+  // POSIX-only probes: `$GIT_DIR` expansion and `>/dev/null` are `sh`
+  // semantics, and `shell: true` on Windows runs cmd.exe, where the probe
+  // itself (not the scoping under test) is meaningless. CI runs Linux.
+  it.skipIf(process.platform === 'win32')('execute_command does not leak GIT_DIR into non-git commands', async () => {
     const base = await start();
     // The KB-clone GIT_DIR/GIT_WORK_TREE override is scoped to bare `git …`
     // only; a non-git command (e.g. npm/pip that shells git internally) must
     // NOT inherit it, or the nested git child would target the KB clone.
-    const res = (await (await post(`${base}/api/agent/tools/execute_command`, { branch: 'main', command: 'echo "GIT_DIR=[$GIT_DIR]"' })).json()) as { stdout: string; stderr: string; exitCode: number };
+    // Probe via `node -e` rather than shell expansion — the override lives in
+    // the spawn env, and `$GIT_DIR` syntax doesn't expand under cmd.exe.
+    const res = (await (await post(`${base}/api/agent/tools/execute_command`, { branch: 'main', command: `node -e "console.log('GIT_DIR=['+(process.env.GIT_DIR||'')+']')"` })).json()) as { stdout: string; stderr: string; exitCode: number };
     expect(res.exitCode).toBe(0);
     expect(res.stdout.trim()).toBe('GIT_DIR=[]');
   });
 
-  it('execute_command does not leak GIT_DIR into a chained step after git', async () => {
+  it.skipIf(process.platform === 'win32')('execute_command does not leak GIT_DIR into a chained step after git', async () => {
     const base = await start();
     // Runs under `shell: true`, so a command that merely STARTS with git but
     // chains another step must not export the KB git env to the whole shell —
     // otherwise `git … && npm ci` would leak the KB repo context into the npm/pip
-    // git subprocess. `git --version` needs no repo, so exit stays 0.
-    const res = (await (await post(`${base}/api/agent/tools/execute_command`, { branch: 'main', command: 'git --version >/dev/null && echo "leak=[$GIT_DIR]"' })).json()) as { stdout: string; stderr: string; exitCode: number };
+    // git subprocess. `git --version` needs no repo, so exit stays 0. The
+    // version line lands on stdout (`>/dev/null` isn't portable to cmd.exe),
+    // so the leak probe is asserted on the LAST line.
+    const res = (await (await post(`${base}/api/agent/tools/execute_command`, { branch: 'main', command: `git --version && node -e "console.log('leak=['+(process.env.GIT_DIR||'')+']')"` })).json()) as { stdout: string; stderr: string; exitCode: number };
     expect(res.exitCode).toBe(0);
-    expect(res.stdout.trim()).toBe('leak=[]');
+    const lines = res.stdout.trim().split(/\r?\n/);
+    expect(lines[lines.length - 1].trim()).toBe('leak=[]');
   });
 
   it('read scope refuses write tools (403) but allows reads', async () => {

package/src/modules/workspace/bevel-ignore.ts

@@ -1,62 +1,66 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import ignore, { type Ignore } from 'ignore';
-
-const IGNORE_FILENAME = '.bevelignore';
-
-/** One .bevelignore file's rules, scoped to the directory it lives in. */
-interface IgnoreLayer {
-  /** Absolute path of the directory where the .bevelignore lives. */
-  readonly root: string;
-  readonly matcher: Ignore;
-}
-
-/**
- * A hierarchical stack of `.bevelignore` rule sets.
- *
- * Each `.bevelignore` file applies to paths beneath the directory it lives in,
- * using standard gitignore syntax (negations, `**`, directory-only patterns, anchoring).
- * Deeper files combine with — and can override — rules from shallower files,
- * mirroring how git layers `.gitignore` files.
- */
-export class BevelIgnoreStack {
-  private constructor(private readonly layers: readonly IgnoreLayer[]) {}
-
-  static empty(): BevelIgnoreStack {
-    return new BevelIgnoreStack([]);
-  }
-
-  /**
-   * Return a new stack that additionally includes a `.bevelignore` from `dir`
-   * (if present). If no `.bevelignore` exists in `dir`, returns this stack unchanged.
-   */
-  async extendedWith(dir: string): Promise<BevelIgnoreStack> {
-    const file = path.join(dir, IGNORE_FILENAME);
-    let contents: string;
-    try {
-      contents = await fs.readFile(file, 'utf-8');
-    } catch {
-      return this;
-    }
-    const matcher = ignore().add(contents);
-    return new BevelIgnoreStack([...this.layers, { root: dir, matcher }]);
-  }
-
-  /**
-   * Whether the given entry should be hidden from the file tree.
-   * @param absolutePath absolute path of the entry
-   * @param isDirectory needed because gitignore patterns ending in `/` match directories only
-   */
-  isIgnored(absolutePath: string, isDirectory: boolean): boolean {
-    for (const layer of this.layers) {
-      const rel = path.relative(layer.root, absolutePath).replace(/\\/g, '/');
-      // Skip entries that aren't under this layer's root (shouldn't happen in normal
-      // recursion, but guards against absolute-path quirks on Windows).
-      if (!rel || rel.startsWith('..')) continue;
-      // Append trailing slash for directories so `foo/`-style rules match correctly.
-      const probe = isDirectory ? `${rel}/` : rel;
-      if (layer.matcher.ignores(probe)) return true;
-    }
-    return false;
-  }
-}
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import ignore, { type Ignore } from 'ignore';
+
+/**
+ * The ignore file's own name. Exported because the file-tree filter hides it
+ * from non-admins, and both places must agree on the spelling.
+ */
+export const IGNORE_FILENAME = '.bevelignore';
+
+/** One .bevelignore file's rules, scoped to the directory it lives in. */
+interface IgnoreLayer {
+  /** Absolute path of the directory where the .bevelignore lives. */
+  readonly root: string;
+  readonly matcher: Ignore;
+}
+
+/**
+ * A hierarchical stack of `.bevelignore` rule sets.
+ *
+ * Each `.bevelignore` file applies to paths beneath the directory it lives in,
+ * using standard gitignore syntax (negations, `**`, directory-only patterns, anchoring).
+ * Deeper files combine with — and can override — rules from shallower files,
+ * mirroring how git layers `.gitignore` files.
+ */
+export class BevelIgnoreStack {
+  private constructor(private readonly layers: readonly IgnoreLayer[]) {}
+
+  static empty(): BevelIgnoreStack {
+    return new BevelIgnoreStack([]);
+  }
+
+  /**
+   * Return a new stack that additionally includes a `.bevelignore` from `dir`
+   * (if present). If no `.bevelignore` exists in `dir`, returns this stack unchanged.
+   */
+  async extendedWith(dir: string): Promise<BevelIgnoreStack> {
+    const file = path.join(dir, IGNORE_FILENAME);
+    let contents: string;
+    try {
+      contents = await fs.readFile(file, 'utf-8');
+    } catch {
+      return this;
+    }
+    const matcher = ignore().add(contents);
+    return new BevelIgnoreStack([...this.layers, { root: dir, matcher }]);
+  }
+
+  /**
+   * Whether the given entry should be hidden from the file tree.
+   * @param absolutePath absolute path of the entry
+   * @param isDirectory needed because gitignore patterns ending in `/` match directories only
+   */
+  isIgnored(absolutePath: string, isDirectory: boolean): boolean {
+    for (const layer of this.layers) {
+      const rel = path.relative(layer.root, absolutePath).replace(/\\/g, '/');
+      // Skip entries that aren't under this layer's root (shouldn't happen in normal
+      // recursion, but guards against absolute-path quirks on Windows).
+      if (!rel || rel.startsWith('..')) continue;
+      // Append trailing slash for directories so `foo/`-style rules match correctly.
+      const probe = isDirectory ? `${rel}/` : rel;
+      if (layer.matcher.ignores(probe)) return true;
+    }
+    return false;
+  }
+}

package/src/modules/workspace/kb-seed.interface.ts

@@ -15,7 +15,7 @@ export interface IKbSeedService {
    * work runs at most once per process.
    *
    * - **Empty remote** → full seed: all template files (incl. the sample
-   *   ontology) committed to every protected branch. Requires `SEED_ADMIN_EMAILS`
+   *   ontology) committed to every protected branch. Uses `ADMIN_EMAIL`
    *   (a repo with no Admin is unusable), otherwise throws.
    * - **Existing remote** → create only the protected branches that don't exist
    *   yet, off an existing one. No file changes here — per-branch base files are

package/src/modules/workspace/kb-seed.service.ts

@@ -3,14 +3,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import {
-  AGENTS_DIR,
-  DATA_DIR,
-  KNOWLEDGE_BASE_DIR,
-  PIPELINES_DIR,
-  SKILLS_DIR,
-  TOOLS_DIR,
-} from '@bevel-software/platform-shared';
+import { KNOWLEDGE_BASE_DIR, GROUPS_DIR } from '@bevel-software/platform-shared';
+import { IGNORE_FILENAME } from './bevel-ignore.js';
 import type { IKbSeedService } from './kb-seed.interface.js';
 
 const execFileAsync = promisify(execFile);
@@ -29,24 +23,57 @@ const BOT_EMAIL = 'bevel-workflow@bevel.software';
  *
  * Two kinds:
  *  - {@link REQUIRED_FILES}: repo-root files added when the file is missing.
- *  - {@link REQUIRED_DIRS}: well-known root dirs the app expects to exist; when a
- *    dir is entirely absent it's created by adding its `<dir>/.gitkeep`. Keyed on
- *    the *directory's* existence, not the `.gitkeep` file — so a branch that
- *    already has content under `KnowledgeBase/` never gets a pointless placeholder.
+ *  - {@link CORE_REQUIRED_DIRS} (plus any `extraDirs`): well-known root dirs the
+ *    app expects to exist; when a dir is entirely absent it's created by adding
+ *    its `<dir>/.gitkeep`. Keyed on the *directory's* existence, not the
+ *    `.gitkeep` file — so a branch that already has content under
+ *    `KnowledgeBase/` never gets a pointless placeholder.
  *
  * `roles.yaml` is in neither, and is not part of the template at all: it is
- * generated from `SEED_ADMIN_EMAILS` (see {@link renderRolesYaml}) and written
+ * generated from `ADMIN_EMAIL` (see {@link renderRolesYaml}) and written
  * directly, so a repo can't be seeded with a stale hard-coded Admin list.
  */
-const REQUIRED_FILES: readonly string[] = ['access.md', 'CLAUDE.md', '.bevelignore', '.gitignore'];
-const REQUIRED_DIRS: readonly string[] = [
-  KNOWLEDGE_BASE_DIR,
-  DATA_DIR,
-  AGENTS_DIR,
-  PIPELINES_DIR,
-  SKILLS_DIR,
-  TOOLS_DIR,
-];
+const REQUIRED_FILES: readonly string[] = ['access.md', 'AGENTS.md', '.bevelignore', '.gitignore'];
+
+/**
+ * The two roots CORE gives a knowledge base: the ontologies, and the groups
+ * that hold skills and tools.
+ *
+ * `Data/`, `Agents/` and `Pipelines/` are deliberately absent. They scaffold
+ * the agentic execution layer, which is not part of this platform — a core
+ * deployment that created them would be handing every operator three empty
+ * folders it has no feature to fill. A distribution that DOES own that layer
+ * passes them as `extraDirs` (and ships a template carrying their READMEs);
+ * the names stay reserved in `kb-layout.ts` either way, so a KB that has them
+ * still renders them as roots rather than folding them into Knowledge.
+ */
+export const CORE_REQUIRED_DIRS: readonly string[] = [KNOWLEDGE_BASE_DIR, GROUPS_DIR];
+
+/**
+ * A reserved root must be ONE path segment — `Data`, not `Data/x`, `../x` or
+ * `/x`. The name is joined onto the repo root, so anything else writes outside
+ * the repo being seeded.
+ *
+ * Deliberately NOT a check against the reserved-root set in `kb-layout.ts`:
+ * `Data`, `Agents` and `Pipelines` are all in that set, and they are precisely
+ * what a distribution passes here. Being reserved is what makes a name worth
+ * claiming — the file tree renders it as its own root instead of folding it
+ * into Knowledge — so rejecting reserved names would reject the only real use.
+ */
+function assertRootSegment(dir: string): void {
+  if (
+    !dir ||
+    dir === '.' ||
+    dir === '..' ||
+    dir.includes('/') ||
+    dir.includes('\\') ||
+    path.isAbsolute(dir)
+  ) {
+    throw new Error(
+      `Reserved KB root must be a single path segment (no separators, no ".."); got "${dir}"`,
+    );
+  }
+}
 
 /** Redact the token from any string that might surface in a log or error. */
 function redact(s: string): string {
@@ -62,7 +89,7 @@ function renderRolesYaml(adminEmails: readonly string[]): string {
     '# Role names are case- and whitespace-insensitive. The `Admin` role is special:\n' +
     '# only Admins may edit this file, and at least one Admin must always exist.\n' +
     '#\n' +
-    '# Generated by the Bevel platform at KB-seed time from SEED_ADMIN_EMAILS.\n' +
+    '# Generated by the Bevel platform at KB-seed time from ADMIN_EMAIL.\n' +
     'roles:\n' +
     '  Admin:\n' +
     `${lines}\n`
@@ -96,15 +123,56 @@ export class KbSeedService implements IKbSeedService {
    *                         base when creating a missing protected branch.
    * @param seedAdminEmails  Admins written into the generated `roles.yaml`.
    * @param gitUsername      Basic-auth username for git-over-HTTPS (provider-specific).
+   * @param extraDirs        Additional root folders this distribution reserves,
+   *                         on top of {@link CORE_REQUIRED_DIRS}. Their
+   *                         `.gitkeep` is written directly rather than copied,
+   *                         so a distribution can claim a root without also
+   *                         shipping a template entry for it.
    */
   constructor(
-    private readonly kbRepoUrl: string,
+    kbRepoUrl: string | (() => string),
     private readonly kbTemplateDir: string,
-    private readonly protectedBranches: readonly string[],
-    private readonly defaultBranch: string,
+    protectedBranches: readonly string[] | (() => readonly string[]),
+    defaultBranch: string | (() => string),
     private readonly seedAdminEmails: readonly string[],
-    private readonly gitUsername: string = 'x-access-token',
-  ) {}
+    gitUsername: string | (() => string) = 'x-access-token',
+    extraDirs: readonly string[] = [],
+  ) {
+    // A getter is read per-operation, so a remote supplied through the setup
+    // screen is seeded against without restarting; a string is still accepted.
+    this.kbRepoUrl = typeof kbRepoUrl === 'function' ? kbRepoUrl : () => kbRepoUrl;
+    // Read when seeding, not at construction: the branch model can be supplied
+    // through the setup screen, which happens after this object exists.
+    this.protectedBranches =
+      typeof protectedBranches === 'function' ? protectedBranches : () => protectedBranches;
+    this.defaultBranch = typeof defaultBranch === 'function' ? defaultBranch : () => defaultBranch;
+    this.gitUsername = typeof gitUsername === 'function' ? gitUsername : () => gitUsername;
+    // NOT a getter, unlike its neighbours above: the reserved roots are named
+    // by the composition root in code, not collected on the setup screen, so
+    // there is nothing to re-read. Validated once, here — every entry is joined
+    // onto the repo root and onto `<dir>/.gitkeep`, so a separator or a `..`
+    // would write outside the repo being seeded, and a bad value should fail at
+    // boot beside the rest of the wiring rather than part-way through seeding
+    // somebody's knowledge base. Same contract as `KB_DIR_NAME` in `CoreConfig`.
+    for (const dir of extraDirs) {
+      assertRootSegment(dir);
+      // A root named after a required FILE is a typo with a silent outcome:
+      // the file is laid down first in both seed paths, so `ensureRequiredDirs`
+      // finds the path taken and skips it, and the directory the caller asked
+      // for never appears with nothing said about why.
+      if (REQUIRED_FILES.includes(dir)) {
+        throw new Error(`Reserved KB root "${dir}" collides with a required file of the same name`);
+      }
+    }
+    this.requiredDirs = [...CORE_REQUIRED_DIRS, ...extraDirs];
+  }
+
+  private readonly kbRepoUrl: () => string;
+  private readonly protectedBranches: () => readonly string[];
+  private readonly defaultBranch: () => string;
+  private readonly gitUsername: () => string;
+  /** Root folders this deployment guarantees — core's two plus any extras. */
+  private readonly requiredDirs: readonly string[];
 
   ensureRemoteSeeded(): Promise<void> {
     // Cache the promise, not just a boolean, so concurrent first-callers share
@@ -125,9 +193,11 @@ export class KbSeedService implements IKbSeedService {
     if (heads.size === 0) {
       if (this.seedAdminEmails.length === 0) {
         throw new Error(
-          `KB remote ${redact(this.kbRepoUrl)} is empty and cannot be seeded: ` +
-            'set SEED_ADMIN_EMAILS to the initial Admin email(s). A seeded KB with ' +
-            'no Admin is unusable (access resolution requires at least one Admin).',
+          `KB remote ${redact(this.kbRepoUrl())} is empty and cannot be seeded: ` +
+            'no initial Admin was supplied. A seeded KB with no Admin is unusable ' +
+            '(access resolution requires at least one Admin). Unreachable in ' +
+            'normal operation — ADMIN_EMAIL is required at boot — so this guards ' +
+            'a caller that constructed the seeder with an empty list.',
         );
       }
       await this.seedEmptyRemote();
@@ -138,7 +208,7 @@ export class KbSeedService implements IKbSeedService {
     // later `clone -b <branch>` succeeds. This creates the branch pointer only;
     // per-branch file top-up happens in `topUpWorkspace` when the branch loads.
     const base = this.pickBase(heads);
-    for (const branch of this.protectedBranches) {
+    for (const branch of this.protectedBranches()) {
       if (!heads.has(branch)) {
         await this.createBranchOnRemote(branch, base);
       }
@@ -155,21 +225,42 @@ export class KbSeedService implements IKbSeedService {
    * stays consistent with origin, and the top-up is retried on a future clone.
    */
   async topUpWorkspace(repoDir: string, branch: string): Promise<void> {
+    // Scaffolding lands on PROTECTED branches only. A draft or suggestions
+    // branch is somebody's change-in-waiting, and a seeder commit there
+    // surfaces as noise in their change request's diff against the default
+    // branch (a stray scaffolding file riding along in a skill proposal was
+    // exactly this). Whatever the protected branches are missing, they get
+    // when THEY load — and drafts fork from them.
+    if (!this.protectedBranches().includes(branch)) return;
     try {
       const added: string[] = [];
       for (const rel of REQUIRED_FILES) {
         if (!(await this.exists(path.join(repoDir, rel)))) {
           await this.copyTemplateFile(rel, repoDir);
           added.push(rel);
+          // Adding AGENTS.md to a knowledge base seeded before the rename
+          // leaves it VISIBLE: that repo's `.bevelignore` lists CLAUDE.md and
+          // knows nothing of the new name, so the conventions doc starts
+          // showing up in the file tree and the agent view. We created the
+          // mismatch by adding the file, so we close it here.
+          if (rel === 'AGENTS.md') added.push(...(await this.mergeIgnorePattern(repoDir, rel)));
         }
       }
-      for (const rootDir of REQUIRED_DIRS) {
-        if (!(await this.exists(path.join(repoDir, rootDir)))) {
-          const keep = `${rootDir}/.gitkeep`;
-          await this.copyTemplateFile(keep, repoDir);
-          added.push(keep);
-        }
+      // AGENTS.md is MANAGED, not merely seeded: the platform owns its
+      // content, and a stale copy is replaced with the packaged template's on
+      // every top-up (each fresh clone of a protected branch — in practice,
+      // every server restart). The file's own header says so, which is what
+      // makes overwriting edits a stated contract instead of a surprise.
+      let agentsRefreshed = false;
+      if (
+        !added.includes('AGENTS.md') &&
+        (await this.templateDiffers(repoDir, 'AGENTS.md'))
+      ) {
+        await this.copyTemplateFile('AGENTS.md', repoDir);
+        added.push('AGENTS.md');
+        agentsRefreshed = true;
       }
+      added.push(...(await this.ensureRequiredDirs(repoDir)));
       if (!(await this.exists(path.join(repoDir, 'roles.yaml')))) {
         if (this.seedAdminEmails.length > 0) {
           await fs.writeFile(
@@ -180,9 +271,9 @@ export class KbSeedService implements IKbSeedService {
           added.push('roles.yaml');
         } else {
           console.warn(
-            `[kb-seed] Branch "${branch}" is missing roles.yaml but SEED_ADMIN_EMAILS ` +
-              'is unset — leaving it absent. Access resolution will fail until an ' +
-              'Admin roles.yaml exists; set SEED_ADMIN_EMAILS or add roles.yaml manually.',
+            `[kb-seed] Branch "${branch}" is missing roles.yaml and ADMIN_EMAIL is ` +
+              'unset — leaving it absent. Access resolution will fail until an ' +
+              'Admin roles.yaml exists; set ADMIN_EMAIL or add roles.yaml manually.',
           );
         }
       }
@@ -194,7 +285,11 @@ export class KbSeedService implements IKbSeedService {
       // values, so this is a harmless no-op there).
       await this.stampIdentity(repoDir);
       await this.git(repoDir, ['add', '--', ...added]);
-      await this.git(repoDir, ['commit', '-m', `Add missing KB scaffolding: ${added.join(', ')}`]);
+      const message =
+        agentsRefreshed && added.length === 1
+          ? 'Update AGENTS.md to the current platform template'
+          : `Add missing KB scaffolding: ${added.join(', ')}`;
+      await this.git(repoDir, ['commit', '-m', message]);
       try {
         await this.git(repoDir, ['push', 'origin', `HEAD:refs/heads/${branch}`]);
         console.log(`[kb-seed] Topped up "${branch}" with: ${added.join(', ')}`);
@@ -220,8 +315,8 @@ export class KbSeedService implements IKbSeedService {
 
   /** Prefer the default branch as a base, else the first protected branch present, else any head. */
   private pickBase(heads: Set<string>): string {
-    if (heads.has(this.defaultBranch)) return this.defaultBranch;
-    const protectedPresent = this.protectedBranches.find((b) => heads.has(b));
+    if (heads.has(this.defaultBranch())) return this.defaultBranch();
+    const protectedPresent = this.protectedBranches().find((b) => heads.has(b));
     if (protectedPresent) return protectedPresent;
     // Deterministic pick so repeated runs behave identically.
     return [...heads].sort()[0];
@@ -236,7 +331,7 @@ export class KbSeedService implements IKbSeedService {
       // Username is provider-specific; the token is always the Basic-auth password.
       args.push(
         '-c',
-        `credential.helper=!f() { echo "username=${this.gitUsername}"; echo "password=$GITHUB_TOKEN"; }; f`,
+        `credential.helper=!f() { echo "username=${this.gitUsername()}"; echo "password=$GITHUB_TOKEN"; }; f`,
       );
     }
     return args;
@@ -260,7 +355,7 @@ export class KbSeedService implements IKbSeedService {
 
   /** Set of branch names on the remote (empty ⇒ uninitialised repo). */
   private async lsRemoteHeads(): Promise<Set<string>> {
-    const out = await this.git(null, [...this.credArgs(), 'ls-remote', '--heads', this.kbRepoUrl]);
+    const out = await this.git(null, [...this.credArgs(), 'ls-remote', '--heads', this.kbRepoUrl()]);
     const heads = new Set<string>();
     for (const line of out.split('\n')) {
       const m = line.match(/\srefs\/heads\/(.+)$/);
@@ -302,6 +397,20 @@ export class KbSeedService implements IKbSeedService {
   }
 
   /** Copy one template file (by repo-relative path) into `dest`, creating parents. */
+  /**
+   * Whether the repo's copy of `relPath` differs from the template's, modulo
+   * line endings — a CRLF checkout of identical content must read as "same",
+   * or the managed-file refresh would commit churn on every boot forever.
+   */
+  private async templateDiffers(repoDir: string, relPath: string): Promise<boolean> {
+    const norm = (text: string) => text.replace(/\r\n?/g, '\n');
+    const [current, template] = await Promise.all([
+      fs.readFile(path.join(repoDir, relPath), 'utf8'),
+      fs.readFile(path.join(this.kbTemplateDir, relPath), 'utf8'),
+    ]);
+    return norm(current) !== norm(template);
+  }
+
   private async copyTemplateFile(relPath: string, dest: string): Promise<void> {
     const from = path.join(this.kbTemplateDir, relPath);
     const to = path.join(dest, relPath);
@@ -309,11 +418,96 @@ export class KbSeedService implements IKbSeedService {
     await fs.copyFile(from, to);
   }
 
+  /**
+   * Ensure `.bevelignore` carries `pattern`, appending it when absent. Returns
+   * the paths changed, for the commit.
+   *
+   * APPENDS — never rewrites. The file is the operator's, and every rule
+   * already in it is theirs to keep; this adds one line under a comment saying
+   * where it came from. Absent file, or a file that already lists the pattern,
+   * is a no-op, so running it on every clone changes nothing after the first.
+   *
+   * Matched line-wise rather than by substring: a rule for `Groups/AGENTS.md`
+   * is not a rule for the root `AGENTS.md`, and treating it as one would leave
+   * the mismatch this exists to close.
+   */
+  private async mergeIgnorePattern(repoDir: string, pattern: string): Promise<string[]> {
+    const ignorePath = path.join(repoDir, IGNORE_FILENAME);
+    let current: string;
+    try {
+      current = await fs.readFile(ignorePath, 'utf8');
+    } catch {
+      return []; // No ignore file — the template's copy arrives with the pattern in it.
+    }
+    const lines = current.split('\n').map((l) => l.trim());
+    if (lines.includes(pattern)) return [];
+    const separator = current.endsWith('\n') ? '' : '\n';
+    await fs.appendFile(
+      ignorePath,
+      `${separator}\n# Added by the platform: the conventions doc is not node content.\n${pattern}\n`,
+      'utf8',
+    );
+    return [IGNORE_FILENAME];
+  }
+
+  /**
+   * Create any reserved root folder this repo is missing, as an empty
+   * `<dir>/.gitkeep`. Returns the paths added, for the commit message.
+   *
+   * WRITTEN, not copied from the template. A `.gitkeep` is empty by definition,
+   * and requiring a template entry per root would mean a distribution could not
+   * reserve one without forking the packaged template.
+   *
+   * Keyed on the DIRECTORY's existence, not the `.gitkeep` file — a branch that
+   * already has content under `KnowledgeBase/` never gets a pointless
+   * placeholder alongside it.
+   */
+  private async ensureRequiredDirs(repoDir: string): Promise<string[]> {
+    const added: string[] = [];
+    for (const rootDir of this.requiredDirs) {
+      const abs = path.join(repoDir, rootDir);
+      // `lstat`, not `exists`: `fs.access` answers "is there something here?",
+      // which is true of a FILE named `Groups` — and the old skip-if-present
+      // check then did nothing and reported success, leaving a knowledge base
+      // permanently missing a root it claims to guarantee. `lstat` rather than
+      // `stat` so a SYMLINK is rejected too: a link named `Groups` is not a KB
+      // layout, and one pointing outside the repo would make every later write
+      // into it land somewhere nobody asked for.
+      const found = await this.lstatOrNull(abs);
+      if (found) {
+        if (found.isDirectory()) continue;
+        throw new Error(
+          `KB root "${rootDir}" exists but is not a directory ` +
+            `(${found.isSymbolicLink() ? 'symlink' : 'file'}). Remove or rename it — ` +
+            'the platform requires this name to be a folder.',
+        );
+      }
+      await fs.mkdir(abs, { recursive: true });
+      await fs.writeFile(path.join(abs, '.gitkeep'), '', 'utf8');
+      added.push(`${rootDir}/.gitkeep`);
+    }
+    return added;
+  }
+
+  /** `lstat` without the throw — null when nothing is at `p`. */
+  private async lstatOrNull(p: string): Promise<import('node:fs').Stats | null> {
+    try {
+      return await fs.lstat(p);
+    } catch {
+      return null;
+    }
+  }
+
   /** `git init` a temp repo, lay down the full template + generated roles.yaml, commit. */
   private async buildSeedCommit(dir: string): Promise<void> {
-    await this.git(dir, ['init', '-b', this.defaultBranch]);
+    await this.git(dir, ['init', '-b', this.defaultBranch()]);
     await this.stampIdentity(dir);
     await this.copyTemplateTree(dir);
+    // Reserved roots the template does not carry. Without this the seed commit
+    // would hold only what the template has, and a distribution's own roots
+    // would appear a step later, when the first clone gets topped up — the same
+    // folders, arriving in a second commit for no reason.
+    await this.ensureRequiredDirs(dir);
     await fs.writeFile(path.join(dir, 'roles.yaml'), renderRolesYaml(this.seedAdminEmails), 'utf8');
     await this.git(dir, ['add', '-A']);
     await this.git(dir, ['commit', '-m', 'Seed knowledge base from Bevel template']);
@@ -325,17 +519,17 @@ export class KbSeedService implements IKbSeedService {
       await this.buildSeedCommit(dir);
       // Point every protected branch at the seed commit. The init branch is
       // already `defaultBranch`; create the rest as refs to HEAD.
-      for (const branch of this.protectedBranches) {
-        if (branch !== this.defaultBranch) {
+      for (const branch of this.protectedBranches()) {
+        if (branch !== this.defaultBranch()) {
           await this.git(dir, ['branch', branch]);
         }
       }
-      await this.git(dir, ['remote', 'add', 'origin', this.kbRepoUrl]);
+      await this.git(dir, ['remote', 'add', 'origin', this.kbRepoUrl()]);
       // Push only the protected branches — never the stray init branch if it
       // isn't itself protected.
-      await this.git(dir, [...this.credArgs(), 'push', '-u', 'origin', ...this.protectedBranches]);
+      await this.git(dir, [...this.credArgs(), 'push', '-u', 'origin', ...this.protectedBranches()]);
       console.log(
-        `[kb-seed] Seeded empty KB remote with branches: ${this.protectedBranches.join(', ')}`,
+        `[kb-seed] Seeded empty KB remote with branches: ${this.protectedBranches().join(', ')}`,
       );
     });
   }
@@ -343,7 +537,7 @@ export class KbSeedService implements IKbSeedService {
   /** Create a missing protected branch on the remote, pointed at `base`'s tip. */
   private async createBranchOnRemote(branch: string, base: string): Promise<void> {
     await this.withTempDir(async (dir) => {
-      await this.git(dir, [...this.credArgs(), 'clone', '--depth', '1', '-b', base, this.kbRepoUrl, dir]);
+      await this.git(dir, [...this.credArgs(), 'clone', '--depth', '1', '-b', base, this.kbRepoUrl(), dir]);
       // Push base's fetched tip up under the new branch name.
       await this.git(dir, [...this.credArgs(), 'push', 'origin', `HEAD:refs/heads/${branch}`]);
       console.log(`[kb-seed] Created missing protected branch "${branch}" from "${base}"`);