@bevel-software/platform-core-backend 0.35.0 → 0.37.0

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -454,6 +454,20 @@ export class ToolManualService implements IToolManualService {
       }));
   }
 
+  async sharedSignInKeysForManual(
+    manualName: string,
+  ): Promise<{ key: string; name: string; label: string | null; oauthScopes?: string[] }[]> {
+    const manual = (await this.scan()).manuals.find((m) => m.name === manualName);
+    return (manual?.variables ?? [])
+      .filter((v) => v.scope === 'admin' && v.oauth != null)
+      .map((v) => ({
+        key: utcpNamespacedKey(manualName, v.name),
+        name: v.name,
+        label: v.label ?? null,
+        oauthScopes: v.oauth?.scopes,
+      }));
+  }
+
   async scopeOfVariable(effectiveKey: string): Promise<ToolVariableScope> {
     // UTCP looks up `<namespace-with-doubled-underscores>_<VAR>`. Find the manual
     // whose namespace prefixes this key; the declared var is the remainder. Match
@@ -802,6 +816,10 @@ export class ToolManualService implements IToolManualService {
       if (m.type !== 'mcp') continue;
       const oauthVar = (m.variables ?? []).find((v) => v.oauth != null);
       if (oauthVar) {
+        // A MANAGED sign-in has nothing for an owner to set up here: its
+        // client is the broker's, its endpoints are in the file. No setup
+        // kind, so no surface asks for a client secret it does not need.
+        if (oauthVar.oauth?.managed) continue;
         // An owner-registered client is `oauth-manual` by definition — whether
         // the declaration is complete or still needs its endpoints discovered.
         // Explicit wins over discovery: never registered over, never probed
@@ -909,8 +927,15 @@ export class ToolManualService implements IToolManualService {
       m.setup = { kind: 'oauth-manual', reason: `sign-in endpoint discovery is unavailable — ${declaredByHand}` };
       return;
     }
+    // A file-declared sign-in carries its client id unless it is managed, and
+    // a managed one has nothing to discover: its endpoints are in the file.
+    const clientId = v.oauth?.clientId;
+    if (!clientId) {
+      m.setup = { kind: 'oauth-manual', reason: `the sign-in names no client id — ${declaredByHand}` };
+      return;
+    }
     try {
-      const found = await discovery.providerForDeclaredClient(m.name, m.url!, v.oauth!.clientId);
+      const found = await discovery.providerForDeclaredClient(m.name, m.url!, clientId);
       if (found.status !== 'oauth') {
         m.setup = {
           kind: 'oauth-manual',
@@ -1579,8 +1604,11 @@ function normalizeVariables(raw: unknown): ToolVariable[] {
     const label = typeof e.label === 'string' && e.label.trim() ? e.label.trim() : undefined;
     const oauth = normalizeVariableOAuth(at, e.oauth);
     // OAuth is inherently per-caller — each user signs in for their own token. An
-    // admin-shared OAuth token would leak one user's token to all callers.
-    if (oauth && scope !== 'user') {
+    // admin-shared OAuth token would leak one user's token to all callers. The
+    // one exception is a MANAGED sign-in enabled as a workspace connection:
+    // there the shared token is the point (one CRM account for the company),
+    // and only an owner of the tool can make it.
+    if (oauth && scope !== 'user' && !oauth.managed) {
       throw new Error(`${at}\` has \`oauth\`, so its \`scope\` must be \`user\``);
     }
     return {
@@ -1640,8 +1668,27 @@ function normalizeVariableOAuth(at: string, raw: unknown): ToolVariableOAuth | u
   };
   const authorizationUrl = safeUrl(o.authorizationUrl, 'authorizationUrl');
   const tokenUrl = safeUrl(o.tokenUrl, 'tokenUrl');
+  // A managed sign-in names the platform connector it goes through instead
+  // of a client id: the client is the broker's. Both parts are ids of OURS
+  // (matched against the catalog later), so the shape check here is all the
+  // file gets — and neither value is repeated in a refusal.
+  let managed: { connectorId: string; scopeSet: string } | undefined;
+  if (o.managed !== undefined) {
+    const m = o.managed as Record<string, unknown> | null;
+    const connectorId = m && typeof m === 'object' && typeof m.connectorId === 'string' ? m.connectorId.trim() : '';
+    const scopeSet = m && typeof m === 'object' && typeof m.scopeSet === 'string' ? m.scopeSet.trim() : '';
+    if (!isValidId(connectorId) || !isValidId(scopeSet)) {
+      throw new Error(`${at}.oauth.managed\` must be { connectorId, scopeSet } (lowercase snake_case ids)`);
+    }
+    managed = { connectorId, scopeSet };
+  }
   const clientId = typeof o.clientId === 'string' && o.clientId.trim() ? o.clientId.trim() : '';
-  if (!clientId) throw new Error(`${at}.oauth.clientId\` is required`);
+  if (!clientId && !managed) throw new Error(`${at}.oauth.clientId\` is required`);
+  // One client or the other: a managed sign-in runs with the broker's app, and
+  // a client id beside it would be a declaration two flows claim.
+  if (clientId && managed) {
+    throw new Error(`${at}.oauth\` names both \`managed\` and a \`clientId\`; a managed sign-in has no client of its own`);
+  }
   let scopes: string[] | undefined;
   if (o.scopes !== undefined) {
     if (!Array.isArray(o.scopes) || !o.scopes.every((s) => typeof s === 'string')) {
@@ -1670,11 +1717,12 @@ function normalizeVariableOAuth(at: string, raw: unknown): ToolVariableOAuth | u
   return {
     authorizationUrl,
     tokenUrl,
-    clientId,
+    ...(clientId ? { clientId } : {}),
     ...(scopes ? { scopes } : {}),
     ...(authParams ? { authParams } : {}),
     ...(o.pkce === false ? { pkce: false } : {}),
     ...(resource ? { resource } : {}),
+    ...(managed ? { managed } : {}),
   };
 }
 

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -7,7 +7,7 @@ import type { IAccessControl } from '../access/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { ConnectorScope, IToolManualService } from './tool-manuals.contract.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
-import { userSecretGap } from '../secrets-vault/index.js';
+import { scopesCovered, userSecretGap } from '../secrets-vault/index.js';
 
 /**
  * What `list_tool_setup` needs from the secrets vault (structurally satisfied
@@ -29,6 +29,9 @@ export interface VariableStatusPort {
       adminKind?: 'static' | 'oauth' | null;
       userConfigured: boolean;
       userAuthorized?: boolean;
+      /** For a shared (workspace) sign-in: the owner's row holds tokens, and what they were granted. */
+      adminAuthorized?: boolean;
+      adminGrantedScopes?: string;
       userKind?: 'static' | 'oauth' | null;
       grantedScopes?: string;
     }[]
@@ -116,18 +119,15 @@ export function registerToolManualsTools(
     // hidden tool's entry CONTAINS is on the field below rather than here.
     description:
       'Configuration status of every `.tool` the current user can access: what each needs set up and what is ' +
-      'configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot ' +
-      'READ is absent, and every flag is the caller\'s own. ' +
-      'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool ' +
-      'editor; users sign in on /connect. ' +
-      'Setting a tool\'s shared secrets is gated by `canWrite` on the `.tool` FILE (its frontmatter ' +
-      '`write:`/`owner:` verbs and the access.md chain), NOT by a platform role: who manages the file configures ' +
-      'the tool. ' +
-      '`hiddenTools` names the tools Hexis hides from agents for an invalid schema. ' +
-      'The listing is the RELEASED catalog, built from the default branch only: a server or `.tool` you declared on a ' +
-      'draft is not listed, callable or signed-in-able until it is merged. Pass `branch` (the draft you wrote the ' +
-      'declaration on) and `onBranchOnly` names every tool declared there that the default branch does not serve ' +
-      'yet — open a change request and ask the user to merge it.',
+      'configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot READ is ' +
+      "absent, and a `user` variable's flags are the caller's own. An `admin` variable with `oauth` is a WORKSPACE " +
+      "connection: `authorized` is the owner's connection, which only a writer of the tool can make or remake. " +
+      'Secret VALUES are never returned or set through a tool: an admin enters them in the tool editor; users sign ' +
+      'in on /connect. Setting shared secrets is gated by `canWrite` on the `.tool` FILE (its frontmatter verbs and ' +
+      'the access.md chain), not by a platform role. `hiddenTools` names the tools Hexis hides for an invalid ' +
+      'schema. The listing is the RELEASED catalog (default branch only): a server or `.tool` declared on a draft is ' +
+      'not listed, callable or signed-in-able until merged. Pass `branch` and `onBranchOnly` names every tool ' +
+      'declared there that the default branch does not serve yet — open a change request and ask the user to merge it.',
     path: '/api/agent/tools/list_tool_setup',
     inputs: {
       type: 'object',
@@ -211,7 +211,22 @@ export function registerToolManualsTools(
                         'Shared value set (plain admin vars), or the owner finished provider setup (OAuth vars).',
                     },
                     userConfigured: { type: 'boolean' },
-                    authorized: { type: ['boolean', 'null'], description: 'OAuth vars: current user signed in.' },
+                    authorized: {
+                      type: ['boolean', 'null'],
+                      description:
+                        'OAuth vars: a token is stored that covers the declared scopes — the current user\'s for a `user` ' +
+                        'variable, the WORKSPACE connection an owner made for an `admin` one (a managed connector enabled ' +
+                        'as one shared connection; a reader cannot connect that, a writer of the tool can).',
+                    },
+                    managed: {
+                      type: 'object',
+                      description:
+                        'Present when the sign-in goes through a managed connector (the distribution\'s own OAuth app, a ' +
+                        'broker doing the round-trip): which connector and scope set. Members connect on /connect; an ' +
+                        'owner needs no client secret for it.',
+                      properties: { connectorId: { type: 'string' }, scopeSet: { type: 'string' } },
+                      required: ['connectorId', 'scopeSet'],
+                    },
                   },
                   required: ['name', 'scope', 'oauth', 'adminConfigured', 'userConfigured'],
                 },
@@ -304,6 +319,16 @@ export function registerToolManualsTools(
             variables: (m.variables ?? []).map((v) => {
               const st = statusByKey.get(varKey(m.name, v.name));
               const isOAuth = v.oauth != null;
+              // A sign-in counts as authorized when a token is stored AND it
+              // still covers what the tool declares — the one readiness rule,
+              // so this flag agrees with the sign-in note below. A shared
+              // sign-in (a managed workspace connection) reads the owner's
+              // row: it is everyone's once an owner has connected it.
+              const authorized = isOAuth
+                ? v.scope === 'admin'
+                  ? st?.adminAuthorized === true && scopesCovered(v.oauth?.scopes, st.adminGrantedScopes)
+                  : st?.userAuthorized === true && scopesCovered(v.oauth?.scopes, st.grantedScopes)
+                : null;
               return {
                 name: v.name,
                 scope: v.scope,
@@ -311,7 +336,8 @@ export function registerToolManualsTools(
                 oauth: isOAuth,
                 adminConfigured: st?.adminConfigured ?? false,
                 userConfigured: st?.userConfigured ?? false,
-                authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
+                authorized,
+                ...(v.oauth?.managed ? { managed: v.oauth.managed } : {}),
               };
             }),
           };

package/src/modules/tool-registry/__tests__/own-tool-schemas.test.ts

@@ -3,8 +3,8 @@ import express from 'express';
 import { describe, expect, it } from 'vitest';
 import { inputSchemaDefect } from '@bevel-software/platform-mcp-core';
 import { ToolRegistry } from '../tool-registry.js';
-import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
-import { registerChangeRequestReadTools } from '../../workflow/agent-tools/change-request-read.tools.js';
+import { registerVersionControlTools } from '../../version-control/agent-tools/version-control.tools.js';
+import { registerChangeRequestReadTools } from '../../version-control/agent-tools/change-request-read.tools.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { registerSkillsTools } from '../../skills/skills.tools.js';
 import { registerPluginsTools } from '../../plugins/plugins.tools.js';
@@ -58,8 +58,8 @@ const CORE_SERVER_SOURCE = new URL('../../../core/create-core-server.ts', import
 /** Every tool-registering module, by the name the server calls it under. */
 const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry) => void }> = [
   {
-    name: 'registerWorkflowTools',
-    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never),
+    name: 'registerVersionControlTools',
+    register: (registry) => registerVersionControlTools(registry, express.Router(), pass, handler, testKbContext(), async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never),
   },
   {
     name: 'registerChangeRequestReadTools',

package/src/modules/tool-registry/__tests__/read-only-hints.test.ts

@@ -13,8 +13,8 @@ import {
   createToolHintsRoutes,
 } from '../index.js';
 import { toolDef } from '../../tool-helpers/index.js';
-import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
-import { registerChangeRequestReadTools } from '../../workflow/agent-tools/change-request-read.tools.js';
+import { registerVersionControlTools } from '../../version-control/agent-tools/version-control.tools.js';
+import { registerChangeRequestReadTools } from '../../version-control/agent-tools/change-request-read.tools.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { registerSkillsTools } from '../../skills/index.js';
 import { registerPluginsTools } from '../../plugins/index.js';
@@ -98,7 +98,7 @@ const INTERNAL_ONLY = new Set(['switch_branch']);
 function platformRegistry(): ToolRegistry {
   const registry = new ToolRegistry();
   const kb = testKbContext();
-  registerWorkflowTools(registry, express.Router(), pass, handler, kb, async () => true);
+  registerVersionControlTools(registry, express.Router(), pass, handler, kb, async () => true);
   registerChangeRequestReadTools(registry, express.Router(), pass, handler, nothing, kb);
   registerWorkspaceTools(
     registry,

package/src/modules/tool-registry/__tests__/tool-description-length.test.ts

@@ -130,7 +130,7 @@ describe('no Hexis tool description is long enough to be cut', () => {
     // purpose, and this assertion is what keeps that a stated fact rather than
     // an oversight: if it ever reaches the catalog, the cap test above measures
     // it like everything else.
-    const { createCallToolChainTool } = await import('../../code-mode/code-mode.tool.js');
+    const { createCallToolChainTool } = await import('../../code-mode/index.js');
     const mastraTool = createCallToolChainTool(unused(), unused(), EXTERNAL_KB_MANUAL_NAME) as unknown as {
       description: string;
     };
@@ -218,14 +218,14 @@ describe('the shared rules describe the tools they name', () => {
     // The opener is only honest if the rules it points at are THERE. These
     // two were paragraphs of the chain's description; they moved, whole, and a
     // description that kept them as well would be the long one a client cuts.
-    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'tool-chain')!;
+    const rule = sharedFileRules(testKbContext().layout, testKbContext().defaultBranch).find((r) => r.id === 'tool-chain')!;
     expect(rule.body).toContain(CHAIN_FAILURES_RULE);
     expect(rule.body).toContain(CHAIN_LARGE_RESULTS_RULE);
     const served = (await hexisTools()).find((t) => t.name === CALL_TOOL_CHAIN_NAME)!;
     expect(served.description).not.toContain(CHAIN_FAILURES_RULE);
     expect(served.description).not.toContain(CHAIN_LARGE_RESULTS_RULE);
     // What a chained read does to an image was already one of the shared rules.
-    const content = sharedFileRules(testKbContext().layout).find((r) => r.id === 'content-kinds')!;
+    const content = sharedFileRules(testKbContext().layout, testKbContext().defaultBranch).find((r) => r.id === 'content-kinds')!;
     expect(content.body).toContain('image_omitted');
   });
 
@@ -244,7 +244,7 @@ describe('the shared rules describe the tools they name', () => {
     // rejects: `delete_file` has no `dryRun`, so an agent told to preflight a
     // single-file delete gets a validation error on the safe call and learns to
     // skip it. Read off the schemas rather than asserted by hand.
-    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'dry-run-confirm')!;
+    const rule = sharedFileRules(testKbContext().layout, testKbContext().defaultBranch).find((r) => r.id === 'dry-run-confirm')!;
     const tools = await hexisTools();
     // `toolDef` wraps a tool's own inputs under `body`, which is the schema a
     // client validates against — so that is where the argument either is or is not.
@@ -272,7 +272,7 @@ describe('the shared rules describe the tools they name', () => {
   });
 
   it('gives each platform file the depth it actually counts at', () => {
-    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'managed-items')!;
+    const rule = sharedFileRules(testKbContext().layout, testKbContext().defaultBranch).find((r) => r.id === 'managed-items')!;
     const { anyDepth, rootOnly } = platformFilesByDepth(testKbContext().layout);
     // The split is the half of the rule a list of names leaves out, and
     // `isPlatformFile` is the predicate the prose has to match.
@@ -283,7 +283,7 @@ describe('the shared rules describe the tools they name', () => {
   });
 
   it('says what unzip extracts, rather than that it takes any bytes', () => {
-    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'content-kinds')!;
+    const rule = sharedFileRules(testKbContext().layout, testKbContext().defaultBranch).find((r) => r.id === 'content-kinds')!;
     // `unzip` refuses anything but a `.zip` (`workspace.service.ts`: "Only .zip
     // files can be extracted"), so the byte-tool clause must not sweep it in.
     expect(rule.body).toContain('unzip extracts the entries of a `.zip`');

package/src/modules/{workflow → version-control}/__tests__/apply-failure.test.ts

@@ -5,7 +5,7 @@ import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import type { AuthUser, FileApprovalState, IWorkflowService, WorkflowEvent } from '@bevel-software/platform-shared';
+import type { AuthUser, FileApprovalState, IVersionControlService, VersionControlEvent } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
@@ -13,18 +13,18 @@ import type { Database } from '../../database/connection.js';
 import type { GitService } from '../git/git.service.js';
 import type { PullRequestService } from '../git/pull-request.service.js';
 import { PullRequestService as RealPullRequestService } from '../git/pull-request.service.js';
-import type { IReviewWorkflowService } from '../review-workflow/review-workflow.interface.js';
-import { ReviewWorkflowService } from '../review-workflow/review-workflow.service.js';
+import type { IChangeRequestReviewService } from '../change-request-review/change-request-review.interface.js';
+import { ChangeRequestReviewService } from '../change-request-review/change-request-review.service.js';
 import type { FileLockService } from '../file-lock.service.js';
 import type { PendingCommitsService } from '../pending-commits.service.js';
-import { WorkflowEventBus } from '../event-bus.js';
+import { VersionControlEventBus } from '../event-bus.js';
 import type { SQL } from 'drizzle-orm';
 import { PgDialect } from 'drizzle-orm/pg-core';
 import { changeRequests } from '../../database/schema.js';
 import { coreMigrationsDir } from '../../../assets.js';
-import { WorkflowService } from '../workflow.service.js';
-import { APPLY_FAILURE_REASON_WITHHELD, createWorkflowRoutes } from '../workflow.routes.js';
-import { WorkflowDomainError, WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { VersionControlService } from '../version-control.service.js';
+import { APPLY_FAILURE_REASON_WITHHELD, createVersionControlRoutes } from '../version-control.routes.js';
+import { VersionControlDomainError, VersionControlValidationError } from '../../../shared/domain-errors.js';
 import { openChangeGate } from '../../../__tests__/open-change-gate.js';
 
 /**
@@ -43,8 +43,8 @@ const ADMIN: AuthUser = { id: 'u-admin', email: 'admin@example.com', name: 'Ada
 interface RouteHarness {
   server: Server;
   baseUrl: string;
-  emitted: WorkflowEvent[];
-  workflow: {
+  emitted: VersionControlEvent[];
+  versionControl: {
     getChangeRequestDetail: ReturnType<typeof vi.fn>;
     mergeChangeRequest: ReturnType<typeof vi.fn>;
     beginApplyAttempt: ReturnType<typeof vi.fn>;
@@ -60,9 +60,9 @@ async function routeHarness(
     canReadBatch?: (paths: string[]) => Promise<Map<string, boolean>>;
   } = {},
 ): Promise<RouteHarness> {
-  const emitted: WorkflowEvent[] = [];
+  const emitted: VersionControlEvent[] = [];
   const canReadBatch = opts.canReadBatch ?? (async (paths: string[]) => new Map(paths.map((p) => [p, true])));
-  const workflow = {
+  const versionControl = {
     getChangeRequestDetail: vi.fn(async () => ({
       headSha: 'h',
       approvals: [],
@@ -84,11 +84,11 @@ async function routeHarness(
   });
   app.use(
     '/api',
-    createWorkflowRoutes(
-      workflow as unknown as IWorkflowService,
+    createVersionControlRoutes(
+      versionControl as unknown as IVersionControlService,
       { getOrCreateForUser: vi.fn(async () => ({ id: 'ws-admin' })) } as unknown as WorkspaceService,
       { getUserById: vi.fn(async () => ADMIN) } as unknown as AuthService,
-      { emit: (e: WorkflowEvent) => emitted.push(e) } as unknown as WorkflowEventBus,
+      { emit: (e: VersionControlEvent) => emitted.push(e) } as unknown as VersionControlEventBus,
       {
         canReadBatch: async (_ws: string, _email: string, paths: string[]) => canReadBatch(paths),
       } as unknown as IAccessControl,
@@ -99,7 +99,7 @@ async function routeHarness(
     const s = app.listen(0, () => resolve(s));
   });
   const addr = server.address() as AddressInfo;
-  return { server, baseUrl: `http://127.0.0.1:${addr.port}`, emitted, workflow };
+  return { server, baseUrl: `http://127.0.0.1:${addr.port}`, emitted, versionControl };
 }
 
 const closeServer = (s: Server) =>
@@ -123,22 +123,22 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
     h = await routeHarness(async () => {
       // The gate's own `MergeBlockedError` shape: a 422 carrying the reasons it
       // still waits on. Its message is what the route reports.
-      throw new WorkflowDomainError('Merge gate rejected: Waiting on approval for Plugins/x/SKILL.md', 422, {
+      throw new VersionControlDomainError('Merge gate rejected: Waiting on approval for Plugins/x/SKILL.md', 422, {
         mergeBlockedReasons: ['Waiting on approval for Plugins/x/SKILL.md'],
       });
     });
     const res = await post(h.baseUrl);
     expect(res.status).toBe(202);
 
-    await vi.waitFor(() => expect(h!.workflow.recordApplyFailure).toHaveBeenCalled());
-    expect(h.workflow.recordApplyFailure).toHaveBeenCalledWith(
+    await vi.waitFor(() => expect(h!.versionControl.recordApplyFailure).toHaveBeenCalled());
+    expect(h.versionControl.recordApplyFailure).toHaveBeenCalledWith(
       7,
       { reason: expect.stringContaining('Waiting on approval'), kind: 'gate', at: expect.any(Date) },
       ADMIN,
       1,
     );
     // The clicker's event and the persisted refusal name the same instant.
-    const [, { at }] = h.workflow.recordApplyFailure.mock.calls[0] as [number, { at: Date }];
+    const [, { at }] = h.versionControl.recordApplyFailure.mock.calls[0] as [number, { at: Date }];
     // The clicker's own answer is unchanged.
     expect(h.emitted).toContainEqual(
       expect.objectContaining({
@@ -153,16 +153,16 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
   it("the clicker's own answer is scoped like the stored one: a clicker who cannot read the files gets no reason", async () => {
     h = await routeHarness(
       async () => {
-        throw new WorkflowValidationError('Waiting on approval for Plugins/x/SKILL.md');
+        throw new VersionControlValidationError('Waiting on approval for Plugins/x/SKILL.md');
       },
       { canReadBatch: async (paths) => new Map(paths.map((p) => [p, false])) },
     );
     await post(h.baseUrl);
-    await vi.waitFor(() => expect(h!.workflow.recordApplyFailure).toHaveBeenCalled());
+    await vi.waitFor(() => expect(h!.versionControl.recordApplyFailure).toHaveBeenCalled());
     const answer = h.emitted.find((e) => e.kind === 'change-request-merge-failed') as { reason: string };
     expect(answer.reason).toBe(APPLY_FAILURE_REASON_WITHHELD);
     // The raw reason is still what is stored, for the viewers who may read it.
-    expect(h.workflow.recordApplyFailure).toHaveBeenCalledWith(
+    expect(h.versionControl.recordApplyFailure).toHaveBeenCalledWith(
       7,
       expect.objectContaining({ reason: expect.stringContaining('Plugins/x/SKILL.md') }),
       ADMIN,
@@ -173,7 +173,7 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
   it("a request with no resolved touched paths withholds the clicker's reason too", async () => {
     h = await routeHarness(
       async () => {
-        throw new WorkflowValidationError('Waiting on approval for Plugins/x/SKILL.md');
+        throw new VersionControlValidationError('Waiting on approval for Plugins/x/SKILL.md');
       },
       { touchedNodePaths: [] },
     );
@@ -187,7 +187,7 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
 
   it('a refusal of the caller reaches the caller alone and erases nobody\'s verdict', async () => {
     h = await routeHarness(async () => {
-      throw new WorkflowDomainError('Only admins can merge with bypass.', 403);
+      throw new VersionControlDomainError('Only admins can merge with bypass.', 403);
     });
     await post(h.baseUrl);
     await vi.waitFor(() =>
@@ -195,16 +195,16 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
         expect.objectContaining({ kind: 'change-request-merge-failed', forUserId: ADMIN.id }),
       ),
     );
-    expect(h.workflow.recordApplyFailure).not.toHaveBeenCalled();
+    expect(h.versionControl.recordApplyFailure).not.toHaveBeenCalled();
   });
 
   it('any other refusal is persisted as an error, which an approval does not answer', async () => {
     h = await routeHarness(async () => {
-      throw new WorkflowDomainError('Merge failed: push rejected', 502);
+      throw new VersionControlDomainError('Merge failed: push rejected', 502);
     });
     await post(h.baseUrl);
-    await vi.waitFor(() => expect(h!.workflow.recordApplyFailure).toHaveBeenCalled());
-    expect(h.workflow.recordApplyFailure).toHaveBeenCalledWith(
+    await vi.waitFor(() => expect(h!.versionControl.recordApplyFailure).toHaveBeenCalled());
+    expect(h.versionControl.recordApplyFailure).toHaveBeenCalledWith(
       7,
       expect.objectContaining({ kind: 'error' }),
       ADMIN,
@@ -215,8 +215,8 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
   it('a conflict is persisted as a conflict', async () => {
     h = await routeHarness(async () => ({ kind: 'conflicts-need-resolution', conflictedPaths: ['a.md'] }));
     await post(h.baseUrl);
-    await vi.waitFor(() => expect(h!.workflow.recordApplyFailure).toHaveBeenCalled());
-    expect(h.workflow.recordApplyFailure).toHaveBeenCalledWith(
+    await vi.waitFor(() => expect(h!.versionControl.recordApplyFailure).toHaveBeenCalled());
+    expect(h.versionControl.recordApplyFailure).toHaveBeenCalledWith(
       7,
       expect.objectContaining({ kind: 'conflicts' }),
       ADMIN,
@@ -238,21 +238,21 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
     await done;
     // One macrotask: the route's continuation after `mergeChangeRequest` resolves.
     await new Promise((r) => setImmediate(r));
-    expect(h.workflow.mergeChangeRequest).toHaveBeenCalledTimes(1);
-    expect(h.workflow.recordApplyFailure).not.toHaveBeenCalled();
+    expect(h.versionControl.mergeChangeRequest).toHaveBeenCalledTimes(1);
+    expect(h.versionControl.recordApplyFailure).not.toHaveBeenCalled();
     expect(h.emitted.filter((e) => e.kind === 'change-request-merge-failed')).toEqual([]);
     // The attempt ended, so the service holds no entry for it.
-    expect(h.workflow.endApplyAttempt).toHaveBeenCalledWith(7, 1);
+    expect(h.versionControl.endApplyAttempt).toHaveBeenCalledWith(7, 1);
   });
 
   it('a failed attempt ends too, after its refusal is recorded', async () => {
     h = await routeHarness(async () => {
-      throw new WorkflowValidationError('gate says no');
+      throw new VersionControlValidationError('gate says no');
     });
     await post(h.baseUrl);
-    await vi.waitFor(() => expect(h!.workflow.endApplyAttempt).toHaveBeenCalledWith(7, 1));
-    expect(h.workflow.recordApplyFailure.mock.invocationCallOrder[0]).toBeLessThan(
-      h.workflow.endApplyAttempt.mock.invocationCallOrder[0]!,
+    await vi.waitFor(() => expect(h!.versionControl.endApplyAttempt).toHaveBeenCalledWith(7, 1));
+    expect(h.versionControl.recordApplyFailure.mock.invocationCallOrder[0]).toBeLessThan(
+      h.versionControl.endApplyAttempt.mock.invocationCallOrder[0]!,
     );
   });
 
@@ -260,7 +260,7 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
     h = await routeHarness(async () => {
       throw new Error('gate says no');
     });
-    h.workflow.recordApplyFailure.mockRejectedValue(new Error('db down'));
+    h.versionControl.recordApplyFailure.mockRejectedValue(new Error('db down'));
     await post(h.baseUrl);
     await vi.waitFor(() =>
       expect(h!.emitted).toContainEqual(expect.objectContaining({ kind: 'change-request-merge-failed' })),
@@ -268,7 +268,7 @@ describe('POST /workflow/change-requests/:n/merge — a failed apply reaches eve
   });
 });
 
-// ── WorkflowService.recordApplyFailure ──────────────────────────────────────
+// ── VersionControlService.recordApplyFailure ──────────────────────────────────────
 
 function updateDb(openRows = 1) {
   const sets: Record<string, unknown>[] = [];
@@ -370,27 +370,27 @@ const refusal = (kind: 'gate' | 'conflicts' | 'error', at: Date): Partial<Row> =
 function service(
   db: Database,
   emit: (e: unknown) => void,
-  reviewWorkflow: Partial<IReviewWorkflowService> = {},
+  changeRequestReview: Partial<IChangeRequestReviewService> = {},
   deps: { git?: Partial<GitService>; prs?: Record<string, unknown> } = {},
 ) {
   const prs = { invalidateDetailCache: vi.fn(), ...deps.prs };
-  const svc = new WorkflowService(
+  const svc = new VersionControlService(
     db,
     (deps.git ?? {}) as GitService,
     prs as unknown as PullRequestService,
-    reviewWorkflow as IReviewWorkflowService,
+    changeRequestReview as IChangeRequestReviewService,
     {} as WorkspaceService,
     {} as IAccessControl,
     {} as FileLockService,
     {} as PendingCommitsService,
     testKbContext(),
     openChangeGate(),
-    { emit } as unknown as WorkflowEventBus,
+    { emit } as unknown as VersionControlEventBus,
   );
   return { svc, prs };
 }
 
-describe('WorkflowService — the persisted apply refusal', () => {
+describe('VersionControlService — the persisted apply refusal', () => {
   it('records the reason, evicts the cached lists, and announces it to everyone without the text', async () => {
     const { db, sets } = updateDb();
     const emitted: unknown[] = [];
@@ -522,7 +522,7 @@ describe('WorkflowService — the persisted apply refusal', () => {
 
 describe('change-request-apply-failed on the bus', () => {
   it('reaches every session — the author and other viewers, not only the clicker', () => {
-    const bus = new WorkflowEventBus();
+    const bus = new VersionControlEventBus();
     const sub = (sessionId: string, userId: string) => ({
       sessionId,
       userId,
@@ -544,11 +544,11 @@ describe('change-request-apply-failed on the bus', () => {
 
 // ── Read back through the summary ───────────────────────────────────────────
 
-describe('WorkflowService — a refusal clears when a change makes it obsolete', () => {
+describe('VersionControlService — a refusal clears when a change makes it obsolete', () => {
   const approveArgs = [7, 'Plugins/x/SKILL.md', ADMIN, [], 'h', 'main', null, 'ws'] as const;
   const EARLIER = new Date(Date.now() - 60_000);
 
-  /** A gate-bound markdown file's approval state, as the review workflow returns it. */
+  /** A gate-bound markdown file's approval state, as the change-request review returns it. */
   const fileState = (path: string, isApproved: boolean): FileApprovalState => ({
     path,
     eligibleApprovers: { roles: ['Plugin owners'], users: [] },
@@ -571,7 +571,7 @@ describe('WorkflowService — a refusal clears when a change makes it obsolete',
         return approvalsAfter;
       }),
       // The real gate: whether an approval answers the refusal is its verdict.
-      evaluateMergeGate: (input) => ReviewWorkflowService.prototype.evaluateMergeGate.call({}, input),
+      evaluateMergeGate: (input) => ChangeRequestReviewService.prototype.evaluateMergeGate.call({}, input),
     });
     return { ...store, svc, prs, emitted };
   }
@@ -695,7 +695,7 @@ describe('WorkflowService — a refusal clears when a change makes it obsolete',
     } as unknown as Database;
     const { svc } = service(db, () => {}, {
       approveFile: vi.fn(async () => ALL_APPROVED),
-      evaluateMergeGate: (input) => ReviewWorkflowService.prototype.evaluateMergeGate.call({}, input),
+      evaluateMergeGate: (input) => ChangeRequestReviewService.prototype.evaluateMergeGate.call({}, input),
     });
     await expect(svc.approveFile(...approveArgs)).resolves.toEqual(ALL_APPROVED);
   });
@@ -839,7 +839,7 @@ describe('GET change requests — the refusal reason reaches only viewers who ca
       touchedNodePaths: opts.touchedNodePaths ?? CR.touchedNodePaths,
       lastApplyFailure: { ...FAILURE },
     };
-    const workflow = {
+    const versionControl = {
       listChangeRequests: vi.fn(async () => [cached]),
       listChangeRequestsAuthoredBy: vi.fn(async () => [cached]),
       listChangeRequestsForUser: vi.fn(async () => [cached]),
@@ -855,11 +855,11 @@ describe('GET change requests — the refusal reason reaches only viewers who ca
     });
     app.use(
       '/api',
-      createWorkflowRoutes(
-        workflow as unknown as IWorkflowService,
+      createVersionControlRoutes(
+        versionControl as unknown as IVersionControlService,
         { getOrCreateForUser: vi.fn(async () => ({ id: 'ws-bo' })) } as unknown as WorkspaceService,
         { getUserById: vi.fn(async () => BO) } as unknown as AuthService,
-        { emit: () => {} } as unknown as WorkflowEventBus,
+        { emit: () => {} } as unknown as VersionControlEventBus,
         { canReadBatch } as unknown as IAccessControl,
         'knowledge-base',
       ),
@@ -1043,7 +1043,7 @@ describe('migration 0009 — refusals recorded before the kind existed are class
 
   it("the prefix it matches is the one the merge gate's refusal actually carries", () => {
     const gateSource = readFileSync(
-      path.join(coreMigrationsDir(), '..', 'src/modules/workflow/review-workflow/review-workflow.service.ts'),
+      path.join(coreMigrationsDir(), '..', 'src/modules/version-control/change-request-review/change-request-review.service.ts'),
       'utf8',
     );
     const prefix = /LIKE '([^%']*)%' THEN 'gate'/.exec(migration)![1]!;