@bevel-software/platform-core-backend 0.8.0 → 0.9.0

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

@@ -1,584 +0,0 @@
-import fs from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { KNOWLEDGE_BASE_DIR, LEGACY_GROUPS_DIR, PLUGINS_DIR } from '@bevel-software/platform-shared';
-import { IGNORE_FILENAME } from './bevel-ignore.js';
-import { migrateGroupsToPlugins } from './plugins-migration.js';
-import type { IKbSeedService } from './kb-seed.interface.js';
-
-const execFileAsync = promisify(execFile);
-
-/**
- * Fallback committer identity for seed commits. Mirrors the workspace clone's
- * bot identity so seed commits attribute to the same bot in `git log`.
- */
-const BOT_NAME = 'Bevel Workflow';
-const BOT_EMAIL = 'bevel-workflow@bevel.software';
-
-/**
- * The **required scaffolding** — the minimum an operational KB needs. When a
- * branch is loaded, any of these that are missing are added to it; the sample
- * ontology is NOT (it only seeds a fully-empty repo).
- *
- * Two kinds:
- *  - {@link REQUIRED_FILES}: repo-root files added when the file is missing.
- *  - {@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 `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', 'AGENTS.md', '.bevelignore', '.gitignore'];
-
-/**
- * The two roots CORE gives a knowledge base: the ontologies, and the plugins
- * 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, PLUGINS_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 {
-  const token = process.env.GITHUB_TOKEN;
-  return token ? s.replaceAll(token, '***') : s;
-}
-
-/** Generate `roles.yaml` granting Admin to each seed email. */
-function renderRolesYaml(adminEmails: readonly string[]): string {
-  const lines = adminEmails.map((e) => `    - ${e}`).join('\n');
-  return (
-    '# Identity → role mapping for access control.\n' +
-    '# 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 ADMIN_EMAIL.\n' +
-    'roles:\n' +
-    '  Admin:\n' +
-    `${lines}\n`
-  );
-}
-
-/**
- * Seeds/tops-up the KB *remote* so the rest of the app's assumption — that the
- * repo it clones already carries the protected branches and base scaffolding —
- * holds even for a brand-new or partially-populated GitHub repo. The template
- * ships inside the platform (`kb-template/`); this reads from it.
- *
- * Split into two moments so the file-level top-up rides along with the clone the
- * app already performs, rather than doing its own extra clones:
- *  - {@link ensureRemoteSeeded} runs once before the first clone (an empty remote
- *    can't be `clone -b`'d): it seeds an empty repo and makes sure every
- *    protected branch *exists* as a ref.
- *  - {@link topUpWorkspace} runs on the freshly-cloned workspace of whatever
- *    branch a user loads: it fills in any missing base files on that branch.
- */
-export class KbSeedService implements IKbSeedService {
-  /** Single-flight: the first caller runs the remote pass; the rest await its result. */
-  private inFlight: Promise<void> | null = null;
-
-  /**
-   * @param kbRepoUrl        Clone/push URL of the KB remote.
-   * @param kbTemplateDir    Filesystem path to the `kb-template/` seed source.
-   * @param protectedBranches Branch names that must exist (e.g. current/target-company-state).
-   * @param defaultBranch    The branch new checkouts land on — used as the init
-   *                         branch of the empty-seed commit and the preferred
-   *                         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(
-    kbRepoUrl: string | (() => string),
-    private readonly kbTemplateDir: string,
-    protectedBranches: readonly string[] | (() => readonly string[]),
-    defaultBranch: string | (() => string),
-    private readonly seedAdminEmails: readonly string[],
-    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
-    // one run. On failure we clear it so a later call can retry (a transient
-    // network blip on ls-remote shouldn't wedge seeding for the whole process).
-    if (!this.inFlight) {
-      this.inFlight = this.run().catch((err) => {
-        this.inFlight = null;
-        throw err;
-      });
-    }
-    return this.inFlight;
-  }
-
-  private async run(): Promise<void> {
-    const heads = await this.lsRemoteHeads();
-
-    if (heads.size === 0) {
-      if (this.seedAdminEmails.length === 0) {
-        throw new Error(
-          `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();
-      return;
-    }
-
-    // Non-empty remote: make sure every protected branch exists as a ref so a
-    // 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()) {
-      if (!heads.has(branch)) {
-        await this.createBranchOnRemote(branch, base);
-      }
-    }
-  }
-
-  /**
-   * Add any missing base scaffolding to an already-cloned workspace of `branch`,
-   * then commit + push it. Called once per fresh clone (any branch a user loads),
-   * so the check reuses the clone the app already made instead of a dedicated one.
-   *
-   * Best-effort: never throws. If the push is rejected (e.g. a concurrent update
-   * to the branch), the local scaffolding commit is rolled back so the workspace
-   * 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[] = [];
-      // BEFORE the dir top-up: `ensureRequiredDirs` would otherwise create an
-      // empty `Plugins/` next to the `Plugins/` that is about to become it, and
-      // the migration refuses a destination that already exists — so the
-      // scaffolding would quietly block the very migration it precedes.
-      const migration = await migrateGroupsToPlugins(repoDir);
-      // Notes are logged unconditionally: an advisory note (a manual that
-      // refuses to convert) is exactly the run where the operator needs to
-      // hear about it, and such a run changes no files.
-      for (const note of migration.notes) console.log(`[plugins-migration] ${note}`);
-      // `migrated` means FILES CHANGED — a note-only run stages nothing, or
-      // the commit below would fail empty on every boot with a warning about
-      // a migration that did nothing.
-      if (migration.migrated) {
-        // Stage the legacy root ONLY when the rename happened this run: `git
-        // add -A -- Groups Plugins` fails outright on a pathspec that matches
-        // nothing, and a reorganisation inside an existing Plugins/ tree has
-        // no Groups/ to stage.
-        if (migration.renamed) added.push(LEGACY_GROUPS_DIR);
-        added.push(PLUGINS_DIR);
-        // The rename's companion edit to the repo-root ignore file — outside
-        // the two roots, so it needs its own pathspec to land in the commit.
-        if (migration.ignoreRewritten) added.push(IGNORE_FILENAME);
-      }
-      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)));
-        }
-      }
-      // 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(
-            path.join(repoDir, 'roles.yaml'),
-            renderRolesYaml(this.seedAdminEmails),
-            'utf8',
-          );
-          added.push('roles.yaml');
-        } else {
-          console.warn(
-            `[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.',
-          );
-        }
-      }
-
-      if (added.length === 0) return; // already fully scaffolded → no-op
-
-      // Stamp the bot identity so the commit has an author even if the clone
-      // wasn't configured with one (the workspace clone already sets the same
-      // values, so this is a harmless no-op there).
-      await this.stampIdentity(repoDir);
-      // `-A` so the migration's renames stage their DELETIONS as well; a plain
-      // `add` would commit the new tree while leaving `Plugins/` in the index.
-      await this.git(repoDir, ['add', '-A', '--', ...added]);
-      const message = migration.migrated
-        ? migration.renamed
-          ? `Move ${LEGACY_GROUPS_DIR}/ to ${PLUGINS_DIR}/ (Agent Plugins layout)`
-          : `Reorganise ${PLUGINS_DIR}/ to the Agent Plugins layout`
-        : 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(', ')}`);
-      } catch (err) {
-        // Roll the local branch back to origin so the workspace never sits ahead
-        // of the remote (which would confuse the workflow git layer). The files
-        // simply aren't present this session; a later fresh clone retries.
-        console.warn(
-          `[kb-seed] Could not push scaffolding to "${branch}", rolling back local commit:`,
-          err instanceof Error ? redact(err.message) : String(err),
-        );
-        await this.git(repoDir, ['reset', '--hard', `origin/${branch}`]).catch(() => {});
-      }
-    } catch (err) {
-      // Top-up is best-effort infrastructure — a failure here must not block the
-      // user from loading the branch.
-      console.warn(
-        `[kb-seed] Scaffolding top-up for "${branch}" failed (non-fatal):`,
-        err instanceof Error ? redact(err.message) : String(err),
-      );
-    }
-  }
-
-  /** 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 (protectedPresent) return protectedPresent;
-    // Deterministic pick so repeated runs behave identically.
-    return [...heads].sort()[0];
-  }
-
-  /** `-c` args that inject credentials + longpaths, mirroring the workspace clone. */
-  private credArgs(): string[] {
-    const args = ['-c', 'core.longpaths=true'];
-    const token = process.env.GITHUB_TOKEN;
-    if (token) {
-      // The helper reads GITHUB_TOKEN at runtime, so the value never appears in argv.
-      // 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`,
-      );
-    }
-    return args;
-  }
-
-  private async git(cwd: string | null, args: string[]): Promise<string> {
-    try {
-      const { stdout } = await execFileAsync('git', args, {
-        cwd: cwd ?? undefined,
-        env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
-        maxBuffer: 32 * 1024 * 1024,
-      });
-      return stdout.toString();
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      let i = 0;
-      while (i < args.length && args[i] === '-c') i += 2;
-      throw new Error(`git ${args[i] ?? args[0]} failed: ${redact(msg)}`);
-    }
-  }
-
-  /** 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 heads = new Set<string>();
-    for (const line of out.split('\n')) {
-      const m = line.match(/\srefs\/heads\/(.+)$/);
-      if (m) heads.add(m[1].trim());
-    }
-    return heads;
-  }
-
-  /** Run a block against a throwaway temp dir, always cleaned up. */
-  private async withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-seed-'));
-    try {
-      return await fn(dir);
-    } finally {
-      await fs.rm(dir, { recursive: true, force: true }).catch(() => {});
-    }
-  }
-
-  private async stampIdentity(repo: string): Promise<void> {
-    await this.git(repo, ['config', 'user.name', BOT_NAME]);
-    await this.git(repo, ['config', 'user.email', BOT_EMAIL]);
-  }
-
-  /** Copy the entire template tree into `dest` (roles.yaml isn't in it — it's generated). */
-  private async copyTemplateTree(dest: string): Promise<void> {
-    const walk = async (relDir: string): Promise<void> => {
-      const abs = path.join(this.kbTemplateDir, relDir);
-      const entries = await fs.readdir(abs, { withFileTypes: true });
-      for (const entry of entries) {
-        const rel = relDir ? path.join(relDir, entry.name) : entry.name;
-        if (entry.isDirectory()) {
-          await walk(rel);
-        } else {
-          await this.copyTemplateFile(rel, dest);
-        }
-      }
-    };
-    await walk('');
-  }
-
-  /** 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);
-    await fs.mkdir(path.dirname(to), { recursive: true });
-    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 `Plugins/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 `Plugins` — 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 `Plugins` 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.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']);
-  }
-
-  /** Empty remote → one seed commit pushed to every protected branch. */
-  private async seedEmptyRemote(): Promise<void> {
-    await this.withTempDir(async (dir) => {
-      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()) {
-          await this.git(dir, ['branch', branch]);
-        }
-      }
-      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()]);
-      console.log(
-        `[kb-seed] Seeded empty KB remote with branches: ${this.protectedBranches().join(', ')}`,
-      );
-    });
-  }
-
-  /** 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]);
-      // 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}"`);
-    });
-  }
-
-  private async exists(p: string): Promise<boolean> {
-    try {
-      await fs.access(p);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}