@bevel-software/platform-core-backend 0.1.0

package/src/modules/workflow/git/__tests__/git.service.commitFile.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+
+/**
+ * `GitService.commitFile` — the `skipValidator` flag. The reject flow passes
+ * `skipValidator: true` because it re-commits a pre-agent baseline that was
+ * already validated when first written; running the (advisory) KB validator
+ * there is pure latency.
+ */
+
+const execFileAsync = promisify(execFile);
+const PROCESS_MAP_DIR = 'knowledge-base';
+const USER = { id: 'u-alice', name: 'Alice', email: 'alice@bevel.software' };
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test',
+      GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test',
+      GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+async function seedWorkspace(
+  root: string,
+  workspaceId: string,
+): Promise<{ workspaceDir: string; repo: string }> {
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+  await fs.mkdir(repo, { recursive: true });
+  // A feature branch — not a protected branch — so `commitFile` skips the
+  // protected-branch access gate; this test is only about the validator.
+  await runGit(repo, ['init', '-b', 'feature-test']);
+  await runGit(repo, ['config', 'user.email', 'test@bevel.local']);
+  await runGit(repo, ['config', 'user.name', 'Test Runner']);
+  // An initial commit so HEAD exists.
+  await fs.writeFile(path.join(repo, 'seed.md'), 'seed\n');
+  await runGit(repo, ['add', 'seed.md']);
+  await runGit(repo, ['commit', '-m', 'seed']);
+  return { workspaceDir, repo };
+}
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+function makeValidator(): { hooks: WorkflowHooks; runValidation: ReturnType<typeof vi.fn> } {
+  const report = { ok: true, mustFix: [], warnings: [], rawOutput: '' };
+  const runValidation = vi.fn(async () => report);
+  // Registered as a commit-validation hook — the seam GitService consults
+  // where it used to call the injected validator.
+  const hooks = new WorkflowHooks();
+  hooks.onCommitValidation(() => runValidation());
+  return { hooks, runValidation };
+}
+
+describe('GitService.commitFile — skipValidator', () => {
+  let root: string;
+  const workspaceId = 'ws-commitfile-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-commitfile-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  it('skipValidator=true commits the file WITHOUT running the KB validator', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const { hooks, runValidation } = makeValidator();
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      hooks,
+      'knowledge-base',
+    );
+
+    await fs.writeFile(path.join(repo, 'Foo.md'), 'reverted content\n');
+    const change = await svc.commitFile(workspaceId, USER, 'Foo.md', 'Revert agent change', true);
+
+    expect(runValidation).not.toHaveBeenCalled();
+    expect(change?.sha).toBeTruthy();
+    expect(change?.subject).toBe('Revert agent change');
+  });
+
+  it('runs the KB validator when skipValidator is omitted', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const { hooks, runValidation } = makeValidator();
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      hooks,
+      'knowledge-base',
+    );
+
+    await fs.writeFile(path.join(repo, 'Bar.md'), 'new content\n');
+    const change = await svc.commitFile(workspaceId, USER, 'Bar.md', 'normal commit');
+
+    expect(runValidation).toHaveBeenCalledTimes(1);
+    expect(change?.sha).toBeTruthy();
+  });
+
+  // Regression: filenames with bracketed prefixes (`[Approved] …`, `[New] …`,
+  // `[Updated 03.09.2025] …`) used to be rejected at `assertValidRelativePath`
+  // because their `[` / `]` characters would be interpreted by `git add -- <path>`
+  // as pathspec globs. The fix is `GIT_LITERAL_PATHSPECS=1` on the subprocess
+  // env (set in `GitService.git()`), which forces literal matching. This test
+  // commits one of the user-reported offenders end-to-end through real git so
+  // a regression in the env-var plumbing would surface as a subprocess failure
+  // here rather than as a 400 on the upload route.
+  it('commits a filename containing pathspec glob characters (regression: [Approved] / [New] prefixes)', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const { hooks } = makeValidator();
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      hooks,
+      'knowledge-base',
+    );
+
+    const relPath = 'Purchasing/[Updated 03.09.2025] Purchasing_How to search_Product detail page.md';
+    await fs.mkdir(path.join(repo, 'Purchasing'), { recursive: true });
+    await fs.writeFile(path.join(repo, relPath), 'content\n');
+
+    const change = await svc.commitFile(workspaceId, USER, relPath);
+
+    expect(change?.sha).toBeTruthy();
+    // Working tree must end up clean — `git add -- <path>` literally matched
+    // the bracketed name, so there's no leftover untracked file ghost on disk.
+    const { stdout: status } = await execFileAsync('git', ['-C', repo, 'status', '--porcelain'], {
+      env: { ...process.env, GIT_LITERAL_PATHSPECS: '1' },
+    });
+    expect(status.trim()).toBe('');
+  });
+
+  // Regression: deep KB paths (≥194 chars) made the default `Update <path>`
+  // subject exceed the 200-char limit, so the lock-release auto-commit
+  // propagated `commit summary must be ≤ 200 characters` back through the
+  // agent's write tool. The default now falls back to the basename when the
+  // full path doesn't fit.
+  it('truncates the default subject when the path makes "Update <path>" exceed 200 chars', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const { hooks } = makeValidator();
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      hooks,
+      'knowledge-base',
+    );
+
+    const deepDir = path.join(
+      'Product',
+      'Knowledge',
+      '1. Service Commitment Management',
+      '1.1 In - Architecture Layering (AL)',
+      '0-Governance',
+      '0.5-Layer-Group-Specific-Governance-Principles',
+    );
+    const fileName = '0.5.5-Buyer-Side-Commercial-Agreement-Governance.md';
+    const relPath = path.posix.join(deepDir.split(path.sep).join('/'), fileName);
+    expect(`Update ${relPath}`.length).toBeGreaterThan(200);
+
+    await fs.mkdir(path.join(repo, deepDir), { recursive: true });
+    await fs.writeFile(path.join(repo, deepDir, fileName), 'content\n');
+
+    const change = await svc.commitFile(workspaceId, USER, relPath);
+
+    expect(change?.subject).toBe(`Update ${fileName}`);
+    expect(change?.subject.length).toBeLessThanOrEqual(200);
+  });
+
+  // Regression: pathspec literal handling. `git checkout HEAD -- '[Approved] x.md'`
+  // and `git ls-files --error-unmatch -- '[Approved] x.md'` would interpret the
+  // brackets as a character-class glob, so discardPath would either silently
+  // no-op or fail to revert the on-disk content. Belongs alongside the
+  // commitFile regression because no dedicated discardPath test file exists
+  // yet — its full surface is covered transitively elsewhere.
+  it('discardPath reverts an unstaged modification to a bracketed-name file', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    const { hooks } = makeValidator();
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, workspaceDir),
+      hooks,
+      'knowledge-base',
+    );
+
+    const relPath = '[Approved] config.md';
+    const committed = 'committed content\n';
+    await fs.writeFile(path.join(repo, relPath), committed);
+    await svc.commitFile(workspaceId, USER, relPath, 'add bracketed config');
+
+    // Dirty the working tree.
+    await fs.writeFile(path.join(repo, relPath), 'dirty content\n');
+    await svc.discardPath(workspaceId, relPath);
+
+    const restored = await fs.readFile(path.join(repo, relPath), 'utf-8');
+    expect(restored).toBe(committed);
+  });
+});

package/src/modules/workflow/git/__tests__/git.service.createBranch.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+
+const execFileAsync = promisify(execFile);
+
+async function mkTmpRoot(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-createBranch-'));
+}
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+async function gitOut(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', args, { cwd });
+  return stdout.trim();
+}
+
+/**
+ * Seeds a bare upstream + a single clone on `target-company-state`, mirroring
+ * the prod layout: `<root>/<workspaceId>/knowledge-base`. The clone has
+ * `origin` wired to the bare upstream so any push from `GitService` can land
+ * on a real remote that downstream `git clone` / `ls-remote` can observe.
+ */
+async function seedWorkspace(root: string, workspaceId: string): Promise<{
+  upstream: string;
+  repo: string;
+}> {
+  const upstream = path.join(root, 'upstream.git');
+  await runGit(root, ['init', '--bare', '-b', 'target-company-state', upstream]);
+
+  const seed = path.join(root, '.seed');
+  await fs.mkdir(seed);
+  await runGit(seed, ['init', '-b', 'target-company-state']);
+  await runGit(seed, ['remote', 'add', 'origin', upstream]);
+  await runGit(seed, ['commit', '--allow-empty', '-m', 'init']);
+  await runGit(seed, ['push', 'origin', 'target-company-state']);
+  await runGit(upstream, ['symbolic-ref', 'HEAD', 'refs/heads/target-company-state']);
+
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, 'knowledge-base');
+  await fs.mkdir(workspaceDir, { recursive: true });
+  await runGit(root, ['clone', upstream, repo]);
+  return { upstream, repo };
+}
+
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+describe('GitService.createBranch', () => {
+  let root: string;
+  const workspaceId = 'target-company-state';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  // Bug 1: the per-branch workspace bootstrap (`WorkspaceService.getOrCreateForBranch`)
+  // clones with `git clone -b <name>` from origin, so the new draft's ref MUST exist on
+  // origin before any user navigates to its URL. If `createBranch` leaves the branch
+  // local-only, the next workspace bootstrap fails with "Remote branch not found in
+  // upstream origin" and the user lands on a dead URL.
+  it('publishes the new draft to origin so a fresh clone -b <name> can find it', async () => {
+    const { upstream } = await seedWorkspace(root, workspaceId);
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, path.join(root, workspaceId)),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+
+    const info = await svc.createBranch(workspaceId, 'alice/new-draft');
+
+    // The draft must be on origin — `BranchInfo.hasRemote` is the contract
+    // signalling to the workspace-bootstrap path that the ref is reachable.
+    expect(info.hasRemote).toBe(true);
+
+    // And `git ls-remote` against the bare upstream must actually see it,
+    // because the bootstrap shells out to `git clone -b <name>` against
+    // exactly this remote — assertion-on-disk, not just on the return value.
+    const lsRemote = await gitOut(path.join(root, workspaceId, 'knowledge-base'), [
+      'ls-remote', '--heads', upstream, 'alice/new-draft',
+    ]);
+    expect(lsRemote).toMatch(/refs\/heads\/alice\/new-draft$/);
+
+    // End-to-end safeguard: a fresh, independent clone with `-b <name>` must
+    // succeed. This is the exact command `cloneProcessMapForBranch` runs when
+    // the user navigates to the new draft's URL — if it fails here, Bug 1 is
+    // still live regardless of what `hasRemote` says.
+    const newWorkspace = path.join(root, 'new-workspace');
+    await fs.mkdir(newWorkspace);
+    await runGit(root, ['clone', '-b', 'alice/new-draft', upstream, path.join(newWorkspace, 'knowledge-base')]);
+    const checkedOut = await gitOut(
+      path.join(newWorkspace, 'knowledge-base'),
+      ['rev-parse', '--abbrev-ref', 'HEAD'],
+    );
+    expect(checkedOut).toBe('alice/new-draft');
+  });
+
+  // Regression: createBranch must NOT leave a local `refs/heads/<name>` in the
+  // creating workspace's clone. Under the per-branch workspace model the new
+  // draft lives in its own workspace; a stray local head here survives
+  // `fetch --prune` after the draft is deleted from another workspace, so it
+  // resurfaces in the picker as a phantom orphan that "won't delete". The draft
+  // must exist only as a remote-tracking ref in this clone.
+  it('leaves no local head in the creating clone — only a remote-tracking ref', async () => {
+    await seedWorkspace(root, workspaceId);
+    const repo = path.join(root, workspaceId, 'knowledge-base');
+    const svc = new GitService(
+      stubWorkspaceService(workspaceId, path.join(root, workspaceId)),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+
+    await svc.createBranch(workspaceId, 'alice/new-draft');
+
+    // No local head for the draft (the bug left one here).
+    const localHead = await gitOut(repo, [
+      'for-each-ref', '--format=%(refname)', 'refs/heads/alice/new-draft',
+    ]);
+    expect(localHead).toBe('');
+
+    // But it IS reachable as a remote-tracking ref, so the picker still lists it
+    // and `fetch --prune` can clean it up when origin drops it.
+    const remoteTracking = await gitOut(repo, [
+      'for-each-ref', '--format=%(refname)', 'refs/remotes/origin/alice/new-draft',
+    ]);
+    expect(remoteTracking).toBe('refs/remotes/origin/alice/new-draft');
+  });
+});

package/src/modules/workflow/git/__tests__/git.service.deleteBranch.test.ts

@@ -0,0 +1,320 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+import { GitService } from '../git.service.js';
+import {
+  BranchAuthorshipError,
+  ProtectedBranchError,
+  WorkflowValidationError,
+} from '../../workflow.errors.js';
+
+const execFileAsync = promisify(execFile);
+
+async function mkTmpRoot(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-deleteBranch-'));
+}
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+async function gitOut(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', args, { cwd });
+  return stdout.trim();
+}
+
+async function remoteHasRef(upstream: string, ref: string): Promise<boolean> {
+  const out = await gitOut(upstream, ['for-each-ref', `refs/heads/${ref}`, '--format', '%(refname)']);
+  return out.length > 0;
+}
+
+/**
+ * Seeds a bare upstream + a clone with three pushed branches:
+ *   - target-company-state (protected, the workspace's HEAD)
+ *   - alice/my-draft (owned by alice@example.com)
+ *   - bob/other-draft (owned by someone else)
+ */
+async function seedWorkspace(root: string, workspaceId: string): Promise<{
+  upstream: string;
+  repo: string;
+}> {
+  const upstream = path.join(root, 'upstream.git');
+  await runGit(root, ['init', '--bare', '-b', 'target-company-state', upstream]);
+
+  const seed = path.join(root, '.seed');
+  await fs.mkdir(seed);
+  await runGit(seed, ['init', '-b', 'target-company-state']);
+  await runGit(seed, ['remote', 'add', 'origin', upstream]);
+  await runGit(seed, ['commit', '--allow-empty', '-m', 'init']);
+  await runGit(seed, ['branch', 'alice/my-draft']);
+  await runGit(seed, ['branch', 'bob/other-draft']);
+  await runGit(seed, ['push', 'origin', 'target-company-state', 'alice/my-draft', 'bob/other-draft']);
+  await runGit(upstream, ['symbolic-ref', 'HEAD', 'refs/heads/target-company-state']);
+
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, 'knowledge-base');
+  await fs.mkdir(workspaceDir, { recursive: true });
+  await runGit(root, ['clone', upstream, repo]);
+  // Realistic production state: the user has worked on alice/my-draft from
+  // this workspace at some point, so a local tracking ref exists alongside
+  // the remote ref. bob/other-draft is remote-only (alice has never opened
+  // it). This forces deleteBranch to handle the "delete both refs" case.
+  await runGit(repo, ['branch', 'alice/my-draft', 'origin/alice/my-draft']);
+  return { upstream, repo };
+}
+
+
+function stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+const ALICE: AuthUser = {
+  id: 'u-alice',
+  email: 'alice@example.com',
+  name: 'Alice Test',
+};
+
+const CAROL: AuthUser = {
+  id: 'u-carol',
+  email: 'carol@example.com',
+  name: 'Carol Admin',
+};
+
+/**
+ * Minimal `IAccessControl` stub. `deleteBranch` only consults `canWrite` with
+ * a `relativePath` of `'roles.yaml'` — which the production service already
+ * uses as the admin-membership signal. Returns true for that path iff the
+ * caller's email is in the admin allowlist; every other method throws so an
+ * unexpected dependency surfaces loudly in the test rather than silently
+ * passing through.
+ */
+function fakeAccessControl(adminEmails: string[]): IAccessControl {
+  const admins = new Set(adminEmails.map((e) => e.trim().toLowerCase()));
+  const notImpl = () => {
+    throw new Error('IAccessControl method not stubbed for this test');
+  };
+  return {
+    canWrite: async (_ws, email, relativePath) => {
+      if (relativePath !== 'roles.yaml') {
+        throw new Error(`unexpected canWrite path "${relativePath}" in deleteBranch test`);
+      }
+      return admins.has(email.trim().toLowerCase());
+    },
+    canWriteBatch: async () => notImpl(),
+    eligibleWriters: async () => notImpl(),
+    eligibleOwners: async () => notImpl(),
+    eligibleDownloaders: async () => notImpl(),
+    eligibleWriterEmails: async () => notImpl(),
+    eligibleOwnerEmails: async () => notImpl(),
+    grantSources: async () => notImpl(),
+    canDownload: async () => notImpl(),
+    canRead: async () => notImpl(),
+    canReadBatch: async () => notImpl(),
+    eligibleReaders: async () => notImpl(),
+    canReadAtRef: async () => notImpl(),
+    canOwner: async () => notImpl(),
+    invalidate: () => {},
+    findEmailByHash: async () => null,
+    kbPrincipals: async () => ({ groups: [], people: [] }),
+    validateRolesYaml: () => ({ ok: true }),
+    referencesToRole: async () => [],
+    canWriteAtRef: async () => null,
+    canWriteBatchAtRef: async () => null,
+    eligibleWritersAtRef: async () => null,
+    eligibleWritersForPathsAtRef: async () => null,
+  };
+}
+
+describe('GitService.deleteBranch — authorship + remote delete', () => {
+  let root: string;
+  const workspaceId = 'target-company-state';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  function makeService(): GitService {
+    return new GitService(
+      stubWorkspaceService(workspaceId, path.join(root, workspaceId)),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+  }
+
+  it('lets the author delete their own draft — removes both local and remote refs', async () => {
+    const { upstream } = await seedWorkspace(root, workspaceId);
+    const svc = makeService();
+
+    await svc.deleteBranch(workspaceId, 'alice/my-draft', ALICE);
+
+    // Local ref gone — `for-each-ref` returns empty when ref is missing
+    const localRefs = await gitOut(
+      path.join(root, workspaceId, 'knowledge-base'),
+      ['for-each-ref', 'refs/heads/alice/my-draft', '--format', '%(refname)'],
+    );
+    expect(localRefs).toBe('');
+
+    // Remote ref ALSO gone — this is the new behaviour, the original
+    // implementation only deleted locally and left the orphan on origin.
+    expect(await remoteHasRef(upstream, 'alice/my-draft')).toBe(false);
+  });
+
+  it("refuses when the user isn't the author — leaves the remote ref intact", async () => {
+    const { upstream } = await seedWorkspace(root, workspaceId);
+    const svc = makeService();
+
+    await expect(
+      svc.deleteBranch(workspaceId, 'bob/other-draft', ALICE),
+    ).rejects.toBeInstanceOf(BranchAuthorshipError);
+
+    // Refused delete must not push to origin — bob's draft must still be
+    // there for him.
+    expect(await remoteHasRef(upstream, 'bob/other-draft')).toBe(true);
+  });
+
+  it('refuses to delete a branch with no recognisable author prefix', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    // Create a `fix/...` style branch (no email prefix) locally + push.
+    await runGit(repo, ['branch', 'fix/no-author']);
+    await runGit(repo, ['push', 'origin', 'fix/no-author']);
+
+    const svc = makeService();
+    await expect(
+      svc.deleteBranch(workspaceId, 'fix/no-author', ALICE),
+    ).rejects.toBeInstanceOf(BranchAuthorshipError);
+  });
+
+  it('still rejects protected branches with ProtectedBranchError (regression guard)', async () => {
+    await seedWorkspace(root, workspaceId);
+    const svc = makeService();
+
+    await expect(
+      svc.deleteBranch(workspaceId, 'target-company-state', ALICE),
+    ).rejects.toBeInstanceOf(ProtectedBranchError);
+  });
+
+  it('still rejects deleting the currently-checked-out branch (regression guard)', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    // Switch to alice's draft so it's the checked-out branch.
+    await runGit(repo, ['checkout', 'alice/my-draft']);
+
+    const svc = makeService();
+    await expect(
+      svc.deleteBranch(workspaceId, 'alice/my-draft', ALICE),
+    ).rejects.toBeInstanceOf(WorkflowValidationError);
+  });
+
+  it('onlyIfNoRemote: true bypasses the authorship check (orphan-tidy-up path stays open)', async () => {
+    const { repo, upstream } = await seedWorkspace(root, workspaceId);
+    // Simulate an orphan: branch exists locally but its remote counterpart
+    // was already pruned (e.g. PR merged + remote head deleted on GitHub).
+    await runGit(repo, ['branch', 'someone-else/orphan']);
+    // Don't push it — so origin never had it.
+
+    const svc = makeService();
+    await svc.deleteBranch(workspaceId, 'someone-else/orphan', ALICE, { onlyIfNoRemote: true });
+
+    const localRefs = await gitOut(repo, [
+      'for-each-ref', 'refs/heads/someone-else/orphan', '--format', '%(refname)',
+    ]);
+    expect(localRefs).toBe('');
+    // Origin never had it; sanity check the workspace clone's remote cache too.
+    expect(await remoteHasRef(upstream, 'someone-else/orphan')).toBe(false);
+  });
+
+  it('refuses orphan delete when remote still has the ref (onlyIfNoRemote contract)', async () => {
+    // Regression: even with onlyIfNoRemote, if origin still has the ref the
+    // delete is refused — preserves the existing safety property.
+    await seedWorkspace(root, workspaceId);
+    const svc = makeService();
+
+    await expect(
+      svc.deleteBranch(workspaceId, 'alice/my-draft', ALICE, { onlyIfNoRemote: true }),
+    ).rejects.toBeInstanceOf(WorkflowValidationError);
+  });
+
+  // Admin-can-delete: when the user is in the `Admin` role per `roles.yaml`
+  // (detected via canWrite on that file — its existing source of truth), the
+  // gate opens for any non-protected, non-current branch, including teammates'
+  // drafts and unprefixed CLI branches with no recognisable author.
+  function makeServiceWithAccess(ac: IAccessControl): GitService {
+    return new GitService(
+      stubWorkspaceService(workspaceId, path.join(root, workspaceId)),
+      new WorkflowHooks(),
+      'knowledge-base',
+      undefined,
+      ac,
+    );
+  }
+
+  it("lets an admin delete another user's draft — removes both local and remote refs", async () => {
+    const { repo, upstream } = await seedWorkspace(root, workspaceId);
+    // Realistic state: carol has opened bob's draft from this workspace at
+    // some point, so a local tracking ref exists. deleteBranch must clean
+    // both sides.
+    await runGit(repo, ['branch', 'bob/other-draft', 'origin/bob/other-draft']);
+    const svc = makeServiceWithAccess(fakeAccessControl([CAROL.email]));
+
+    await svc.deleteBranch(workspaceId, 'bob/other-draft', CAROL);
+
+    const localRefs = await gitOut(repo, [
+      'for-each-ref', 'refs/heads/bob/other-draft', '--format', '%(refname)',
+    ]);
+    expect(localRefs).toBe('');
+    expect(await remoteHasRef(upstream, 'bob/other-draft')).toBe(false);
+  });
+
+  it('lets an admin delete an unprefixed CLI branch (no recognisable author)', async () => {
+    const { repo, upstream } = await seedWorkspace(root, workspaceId);
+    await runGit(repo, ['branch', 'fix/no-author']);
+    await runGit(repo, ['push', 'origin', 'fix/no-author']);
+
+    const svc = makeServiceWithAccess(fakeAccessControl([CAROL.email]));
+    await svc.deleteBranch(workspaceId, 'fix/no-author', CAROL);
+
+    expect(await remoteHasRef(upstream, 'fix/no-author')).toBe(false);
+  });
+
+  it("still refuses a non-admin non-author — the gate didn't widen for everyone", async () => {
+    const { upstream } = await seedWorkspace(root, workspaceId);
+    // Alice is not admin and not bob's author → must still reject.
+    const svc = makeServiceWithAccess(fakeAccessControl([CAROL.email]));
+
+    await expect(
+      svc.deleteBranch(workspaceId, 'bob/other-draft', ALICE),
+    ).rejects.toBeInstanceOf(BranchAuthorshipError);
+    expect(await remoteHasRef(upstream, 'bob/other-draft')).toBe(true);
+  });
+
+  it('admin power does NOT extend to protected branches', async () => {
+    await seedWorkspace(root, workspaceId);
+    const svc = makeServiceWithAccess(fakeAccessControl([CAROL.email]));
+
+    await expect(
+      svc.deleteBranch(workspaceId, 'target-company-state', CAROL),
+    ).rejects.toBeInstanceOf(ProtectedBranchError);
+  });
+});