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

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

@@ -232,55 +232,6 @@ describe('GitService — commit gate uses HEAD (not working tree)', () => {
   });
 });
 
-describe('GitService — revert gate uses HEAD', () => {
-  let root: string;
-  const workspaceId = 'ws-revert-gate';
-
-  beforeEach(async () => {
-    root = await mkTmpRoot();
-  });
-  afterEach(async () => {
-    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
-  });
-
-  it('passes ref=HEAD when gating a revert', async () => {
-    const { ac, calls } = recordingAccessControl();
-    const { svc, repo } = await makeSvc(root, workspaceId, ac);
-    await commitFile(repo, 'Knowledge/Foo.md', 'a\n', 'seed');
-    await commitFile(repo, 'Knowledge/Foo.md', 'b\n', 'second');
-    const { stdout: sha } = await execFileAsync('git', ['-C', repo, 'rev-parse', 'HEAD'], {
-      encoding: 'utf-8',
-    });
-
-    // We only care that the gate is invoked with `HEAD`; downstream
-    // behaviour of `git revert` (which may or may not succeed for unrelated
-    // environmental reasons — author parsing, signing config, etc.) is out
-    // of scope for this test.
-    await svc.revertCommit(workspaceId, USER, sha.trim()).catch(() => undefined);
-
-    const gateCalls = calls.filter((c) => c.method === 'canWriteBatchAtRef');
-    expect(gateCalls).toHaveLength(1);
-    expect(gateCalls[0].ref).toBe('HEAD');
-    expect(gateCalls[0].paths).toContain('Knowledge/Foo.md');
-  });
-
-  it('refuses with AccessDeniedError when the gate denies', async () => {
-    const { ac } = recordingAccessControl({
-      canWriteBatchAtRef: (_ref, _email, paths) => new Map(paths.map((p) => [p, false])),
-    });
-    const { svc, repo } = await makeSvc(root, workspaceId, ac);
-    await commitFile(repo, 'Knowledge/Foo.md', 'a\n', 'seed');
-    await commitFile(repo, 'Knowledge/Foo.md', 'b\n', 'second');
-    const { stdout: sha } = await execFileAsync('git', ['-C', repo, 'rev-parse', 'HEAD'], {
-      encoding: 'utf-8',
-    });
-
-    await expect(svc.revertCommit(workspaceId, USER, sha.trim())).rejects.toBeInstanceOf(
-      AccessDeniedError,
-    );
-  });
-});
-
 describe('GitService — push gate uses origin/<branch> (not HEAD or working tree)', () => {
   let root: string;
   const workspaceId = 'ws-push-gate';
@@ -327,6 +278,15 @@ describe('GitService — push gate uses origin/<branch> (not HEAD or working tre
     expect(gateCalls[0].paths).toContain('Knowledge/Foo.md');
   });
 
+  it('systemAuthorized skips the gate entirely, and the push still lands', async () => {
+    // The group-provisioning path: its endpoint IS the authorization (any
+    // signed-in user may claim an unused name under Groups/), and the gate
+    // could only read the new folder's chain at origin as `write: Admin`.
+    const { svc, calls } = await setupWithOrigin();
+    await svc.push(workspaceId, USER, { systemAuthorized: true });
+    expect(calls.filter((c) => c.method === 'canWriteBatchAtRef')).toHaveLength(0);
+  });
+
   it('refuses the push when origin/<branch> rules deny the caller', async () => {
     const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
     const originDir = path.join(root, 'origin.git');

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

@@ -38,6 +38,14 @@ async function seedWorkspace(root: string, workspaceId: string) {
   const repo = path.join(workspaceDir, 'knowledge-base');
   await fs.mkdir(workspaceDir, { recursive: true });
   await runGit(root, ['clone', upstream, repo]);
+  // Repo-local identity, because `GitService` spawns its own git children
+  // with the AMBIENT env — `runGit`'s `GIT_COMMITTER_*` vars never reach
+  // them. A dev machine hides this behind a global git config; a CI runner
+  // has none, so anything committing through the service (here:
+  // `commitFile`) fails with "Committer identity unknown". Same reason
+  // `git.service.commitFile.test.ts` configures its fixture this way.
+  await runGit(repo, ['config', 'user.email', 'test@bevel.local']);
+  await runGit(repo, ['config', 'user.name', 'Test Runner']);
   return { upstream, repo };
 }
 
@@ -121,4 +129,97 @@ describe('GitService.changedFilesForPr / resolvePrShas', () => {
     expect(headSha).toMatch(/^[0-9a-f]{40}$/);
     expect(baseSha).not.toBe(headSha);
   });
+
+  /**
+   * roles.yaml can never change through a merge — `preserveBaseRolesYaml`
+   * restores the base copy onto the source before every merge — so the review
+   * surface must not list it as changed: the claim would be false, the empty
+   * diff reads as a bug, and its per-file approval would gate the merge on a
+   * change that cannot land. Counts stay aligned with the surviving files.
+   */
+  it('excludes roles.yaml from the changed-file list and the touched paths', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    await runGit(repo, ['checkout', '-b', 'mallory/self-promote']);
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - mallory@x.com\n');
+    await fs.writeFile(path.join(repo, 'honest.md'), 'real change\nsecond line\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'work + attempted escalation']);
+    await runGit(repo, ['push', '-u', 'origin', 'mallory/self-promote']);
+
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+
+    const files = await git.changedFilesForPr(
+      workspaceId,
+      'current-company-state',
+      'mallory/self-promote',
+    );
+    expect(files.map((f) => f.path)).toEqual(['honest.md']);
+    // The counts filter moved in step with the statuses filter.
+    expect(files[0].additions).toBe(2);
+
+    const paths = await git.changedPathsForPr(
+      workspaceId,
+      'current-company-state',
+      'mallory/self-promote',
+    );
+    expect(paths).toEqual(['honest.md']);
+  });
+
+  /**
+   * The per-file revert's two primitives: the merge-base a revert restores
+   * from, and the restore itself — byte-exact via git, with "absent at the
+   * merge-base" meaning deletion (the revert of an added file).
+   */
+  it('mergeBaseForPr + restorePathFromRef restore a modified file and delete an added one', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    await runGit(repo, ['checkout', '-b', 'alice/feature']);
+    await fs.writeFile(path.join(repo, 'base.md'), 'rewritten\n');
+    await fs.writeFile(path.join(repo, 'added.md'), 'brand new\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'feature work']);
+    await runGit(repo, ['push', '-u', 'origin', 'alice/feature']);
+
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+
+    const mergeBase = await git.mergeBaseForPr(workspaceId, 'current-company-state', 'alice/feature');
+    expect(mergeBase).toMatch(/^[0-9a-f]{40}$/);
+
+    await git.restorePathFromRef(workspaceId, mergeBase!, 'base.md');
+    // Normalized: a Windows dev box with core.autocrlf smudges the checkout
+    // to CRLF; the blob git commits back is what matters, not the smudge.
+    const restored = await fs.readFile(path.join(repo, 'base.md'), 'utf8');
+    expect(restored.replace(/\r\n/g, '\n')).toBe('base\n');
+
+    // Simulate the wreckage a previously-failed attempt leaves behind: a
+    // STAGED deletion (index entry gone). The restore must self-heal it —
+    // without the index realignment, the commit below fatals on `git add`.
+    await runGit(repo, ['rm', '--force', '--quiet', '--', 'added.md']);
+
+    await git.restorePathFromRef(workspaceId, mergeBase!, 'added.md');
+    await expect(fs.access(path.join(repo, 'added.md'))).rejects.toThrow();
+
+    // The chain that actually failed in production: committing the DELETION
+    // through commitFile, whose `git add -- <path>` can only stage it while
+    // the index still tracks the path — a `git rm`-based restore broke here
+    // with "pathspec did not match any files".
+    const committed = await git.commitFile(
+      workspaceId,
+      { id: 'u1', email: 'reviewer@x.com', name: 'Reviewer' },
+      'added.md',
+      'Revert added.md (declined in change request #1)',
+      true,
+    );
+    expect(committed).not.toBeNull();
+    await expect(
+      execFileAsync('git', ['-C', repo, 'cat-file', '-e', 'HEAD:added.md']),
+    ).rejects.toThrow();
+  });
 });

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

@@ -1,211 +1,219 @@
-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);
-  });
-});
+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']);
+  // Repo-local so GitService's own git children (which run with the ambient
+  // env) see them too: autocrlf off keeps `git checkout` (discardPath) from
+  // rewriting the LF fixtures as CRLF under Git-for-Windows' system-level
+  // `core.autocrlf=true`; longpaths lifts Windows' 260-char MAX_PATH, which
+  // the deep-KB-path subject-truncation test exceeds. Both are no-ops on
+  // Linux/CI — they pin the repo to the behaviour the assertions assume.
+  await runGit(repo, ['config', 'core.autocrlf', 'false']);
+  await runGit(repo, ['config', 'core.longpaths', 'true']);
+  // 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);
+  });
+});