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

package/src/modules/access/admin-locked-commit.ts

@@ -49,19 +49,19 @@ import path from 'node:path';
 import { logger } from '../../shared/logging.js';
 
 import { type WriteValidator, LockingFilesystem } from '../kb-fs/index.js';
-import type { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IWorkspaceService, IVersionControlService } from '@bevel-software/platform-shared';
 
 export interface LockedCommitDeps {
   workspaceService: IWorkspaceService;
-  workflowService: IWorkflowService;
+  versionControlService: IVersionControlService;
   kbDirName: string;
   /** Live-binding thunk — DEFAULT_BRANCH stays empty until setup. */
   defaultBranchOf: () => string;
   /** Domain-error constructor (RolesAdminError / GroupsAdminError). */
-  makeError: (message: string, status: number, payload?: Record<string, unknown>) => WorkflowDomainError;
+  makeError: (message: string, status: number, payload?: Record<string, unknown>) => VersionControlDomainError;
   /** Log prefix, e.g. 'roles-admin' / 'groups-admin'. */
   logTag: string;
   /** Contention wording: what is "being edited by <holder>". */
@@ -133,7 +133,7 @@ export class AdminLockedCommits {
     return new LockingFilesystem(
       { basePath, contained: true },
       {
-        workflow: this.deps.workflowService,
+        versionControl: this.deps.versionControlService,
         workspaceId,
         branch: this.defaultBranch,
         user: actor,
@@ -171,7 +171,7 @@ export class AdminLockedCommits {
    * module doc for the release semantics.
    *
    * `opts.coordinationFiles` names files locked ONLY to serialize with their
-   * writer — `fn` never writes them. They're acquired with the workflow
+   * writer — `fn` never writes them. They're acquired with the version-control
    * service's coordination flag (a pure mutex that skips the per-path write
    * gate — required for machine-owned files like `synced-groups.yaml`, which
    * a human actor may not, and need not, write) and always released with
@@ -197,7 +197,7 @@ export class AdminLockedCommits {
     let unrestored: Set<string> | null = null;
     try {
       for (const p of paths) {
-        const res = await this.deps.workflowService.acquireLock(
+        const res = await this.deps.versionControlService.acquireLock(
           workspaceId,
           this.defaultBranch,
           p,
@@ -248,13 +248,13 @@ export class AdminLockedCommits {
             // pointless commit whose enqueue failure strands a known-clean
             // lock until TTL. Or known-partial bytes (restore failed —
             // discarding to HEAD beats committing them).
-            await this.deps.workflowService.releaseLockNoCommit(workspaceId, this.defaultBranch, h, actor);
+            await this.deps.versionControlService.releaseLockNoCommit(workspaceId, this.defaultBranch, h, actor);
           } else {
             // Push-retry (the enqueued commit retries the share), the
             // restored-failure path, and any held path the batch never
             // committed (commit-on-release: a prior holder's still-queued
             // work must be preserved, never discarded).
-            await this.deps.workflowService.releaseLock(workspaceId, this.defaultBranch, h, actor);
+            await this.deps.versionControlService.releaseLock(workspaceId, this.defaultBranch, h, actor);
           }
         } catch (releaseErr) {
           logger(this.deps.logTag).warn(
@@ -278,7 +278,7 @@ export class AdminLockedCommits {
     files: LockedWrite[],
     summary: string,
   ): Promise<void> {
-    const { workspaceService, workflowService, logTag } = this.deps;
+    const { workspaceService, versionControlService, logTag } = this.deps;
     try {
       for (const f of files) {
         if (f.content === null) {
@@ -293,7 +293,7 @@ export class AdminLockedCommits {
           await workspaceService.writeFile(workspaceId, this.wsRel(f.repoRel), f.content);
         }
       }
-      await workflowService.commitChanges(workspaceId, actor, summary, files.map((f) => this.wsRel(f.repoRel)));
+      await versionControlService.commitChanges(workspaceId, actor, summary, files.map((f) => this.wsRel(f.repoRel)));
       // Commit landed AND pushed — the tree at these paths is clean. Mark
       // them so withFileLocks releases them WITHOUT enqueueing a release
       // commit (see the module doc — an enqueue failure would strand the

package/src/modules/access/admin-route-helpers.ts

@@ -3,7 +3,7 @@
  * groups-admin.routes) — one error shape, one input-coercion rule, so the two
  * surfaces can't drift apart again.
  *
- * Error shape: a sub-500 `WorkflowDomainError` renders as its own status +
+ * Error shape: a sub-500 `VersionControlDomainError` renders as its own status +
  * message + payload; everything else — a raw error OR a 500-status domain
  * error (e.g. AccessMutationService wraps unexpected raw errors in a 500
  * AccessMutationError, message included) — is an INTERNAL error: logged
@@ -14,7 +14,7 @@
 
 import type express from 'express';
 import { logger } from '../../shared/logging.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 
 /** One error shape for every access-family route. */
@@ -22,11 +22,11 @@ export function toHttpError(
   err: unknown,
   logTag: string,
 ): { status: number; body: Record<string, unknown> } {
-  if (err instanceof WorkflowDomainError && err.status < 500) {
+  if (err instanceof VersionControlDomainError && err.status < 500) {
     return { status: err.status, body: domainErrorBody(err) };
   }
   logger(logTag).error('route failure:', { err });
-  const status = err instanceof WorkflowDomainError ? err.status : 500;
+  const status = err instanceof VersionControlDomainError ? err.status : 500;
   return { status, body: { error: 'Internal error.' } };
 }
 
@@ -49,7 +49,7 @@ export function requireNonEmptyString(
   opts?: { trim?: boolean },
 ): string {
   if (typeof value !== 'string' || value.trim() === '') {
-    throw new WorkflowDomainError(`${field} must be a non-empty string`, 400);
+    throw new VersionControlDomainError(`${field} must be a non-empty string`, 400);
   }
   return opts?.trim ? value.trim() : value;
 }

package/src/modules/access/change-read-gate.ts

@@ -1,6 +1,6 @@
 /**
  * Read-before-write: the gate every change passes on its way to the lock
- * (`WorkflowService.acquireLock`), on every branch. Contract and rationale in
+ * (`VersionControlService.acquireLock`), on every branch. Contract and rationale in
  * `access-model/change-gate.ts`; this is the service that answers.
  *
  * The verdict is taken against the WORKING TREE, not `HEAD` as the write gate

package/src/modules/access/groups-admin.service.ts

@@ -28,9 +28,9 @@
  */
 
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
+import type { AuthUser, IWorkspaceService, IVersionControlService } from '@bevel-software/platform-shared';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
@@ -63,7 +63,7 @@ const ROLES_YAML = 'roles.yaml';
 
 /** A group mutation that cannot proceed. `payload.kind` distinguishes the
  *  mode refusal (`'idp-mode'`) for the UI. */
-export class GroupsAdminError extends WorkflowDomainError {
+export class GroupsAdminError extends VersionControlDomainError {
   constructor(message: string, status = 422, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'GroupsAdminError';
@@ -118,18 +118,18 @@ export class GroupsAdminService {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
-    private readonly workflowService: IWorkflowService,
+    private readonly versionControlService: IVersionControlService,
     private readonly accessControl: IAccessControl,
     /** The composition root's walk — the one the resolver finds access rules with. */
     disk: ITreeWalker,
     private readonly kbDirName: string,
     /** Live-binding thunk — see RolesAdminService's identical note. */
     private readonly defaultBranchOf: () => string,
-    private readonly eventBus?: WorkflowEventBus,
+    private readonly eventBus?: VersionControlEventBus,
   ) {
     this.locked = new AdminLockedCommits({
       workspaceService,
-      workflowService,
+      versionControlService,
       kbDirName,
       defaultBranchOf,
       makeError: (message, status, payload) => new GroupsAdminError(message, status, payload),

package/src/modules/access/reference-scan.ts

@@ -507,7 +507,7 @@ export function readableReferences(
 const SCAN_TTL_MS = 30_000;
 
 /**
- * The slice of the workflow event bus the scanner taps for cache
+ * The slice of the version-control event bus the scanner taps for cache
  * invalidation. Structural (not the concrete class) so test doubles and the
  * services' optional bus stay compatible.
  */

package/src/modules/access/roles-admin.service.ts

@@ -36,9 +36,9 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('roles.recover');
-import type { WorkflowEventBus } from '../workflow/index.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
+import type { AuthUser, IWorkspaceService, IVersionControlService } from '@bevel-software/platform-shared';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
@@ -77,7 +77,7 @@ import { AdminLockedCommits } from './admin-locked-commit.js';
 import { KbReferenceScanner, readableReferences } from './reference-scan.js';
 
 /** A mutation that cannot proceed (invariant violation, contention, not found). */
-export class RolesAdminError extends WorkflowDomainError {
+export class RolesAdminError extends VersionControlDomainError {
   constructor(message: string, status = 422, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'RolesAdminError';
@@ -185,7 +185,7 @@ export class RolesAdminService {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
-    private readonly workflowService: IWorkflowService,
+    private readonly versionControlService: IVersionControlService,
     private readonly accessControl: IAccessControl,
     /** The composition root's walk — the one the resolver finds access rules with. */
     disk: ITreeWalker,
@@ -205,7 +205,7 @@ export class RolesAdminService {
      * a roles.yaml / access.md change is an access change, and without this an
      * open tab keeps a now-stale read verdict until a manual reload.
      */
-    private readonly eventBus?: WorkflowEventBus,
+    private readonly eventBus?: VersionControlEventBus,
     /**
      * This deployment's configured admins (`ADMIN_EMAIL`) — the same list the
      * resolver treats as `deploymentOwners`, so it serves two purposes here:
@@ -218,7 +218,7 @@ export class RolesAdminService {
   ) {
     this.locked = new AdminLockedCommits({
       workspaceService,
-      workflowService,
+      versionControlService,
       kbDirName,
       defaultBranchOf,
       makeError: (message, status, payload) => new RolesAdminError(message, status, payload),
@@ -293,7 +293,7 @@ export class RolesAdminService {
    * error is status-less and would surface as 500).
    */
   private async assertRolesUnlocked(workspaceId: string, actor: AuthUser): Promise<void> {
-    const held = await this.workflowService.getLock(
+    const held = await this.versionControlService.getLock(
       workspaceId,
       this.defaultBranch,
       `${this.kbDirName}/${ROLES_YAML}`,
@@ -422,7 +422,7 @@ export class RolesAdminService {
     // the fix never reaches it). Best-effort: if origin is unreachable we fall
     // back to the local state and still attempt the local fix.
     try {
-      await this.workflowService.resetToRemote(workspaceId, this.defaultBranch);
+      await this.versionControlService.resetToRemote(workspaceId, this.defaultBranch);
       this.accessControl.invalidate(workspaceId);
     } catch (err) {
       log.warn('could not sync with origin before recovery; proceeding with local state:', { err });

package/src/modules/access/synced-groups-committer.ts

@@ -2,14 +2,14 @@ import path from 'node:path';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('directory-sync');
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { AccessControlService } from './access-control.service.js';
 import { SYNCED_GROUPS_YAML } from '../access-model/index.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
 import { LockingFilesystem } from '../kb-fs/index.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import { PushNeedsAgentResolutionError, VersionControlDomainError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';
 
@@ -27,9 +27,9 @@ import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';
  */
 export function createSyncedGroupsCommitter(deps: {
   workspaceService: WorkspaceService;
-  workflowService: IWorkflowService;
+  versionControlService: IVersionControlService;
   accessControl: AccessControlService;
-  eventBus: WorkflowEventBus;
+  eventBus: VersionControlEventBus;
   kbDirName: string;
   bot: AuthUser;
   /** Thunk — DEFAULT_BRANCH is a live binding that stays empty until setup. */
@@ -37,7 +37,7 @@ export function createSyncedGroupsCommitter(deps: {
 }): Pick<SyncedGroupsWriterDeps, 'readCurrent' | 'persist' | 'onWritten'> {
   const {
     workspaceService,
-    workflowService,
+    versionControlService,
     accessControl,
     eventBus,
     kbDirName,
@@ -77,7 +77,7 @@ export function createSyncedGroupsCommitter(deps: {
       // roles admin's atomic writes use.
       const fsys = new LockingFilesystem(
         { basePath, contained: true },
-        { workflow: workflowService, workspaceId, branch, user: bot, kbDirName },
+        { versionControl: versionControlService, workspaceId, branch, user: bot, kbDirName },
       );
       try {
         await fsys.writeFiles(
@@ -115,19 +115,19 @@ export function createSyncedGroupsCommitter(deps: {
           // an operator (or any later write on the branch) pushes it.
           let armed = false;
           try {
-            await workflowService.releaseLock(workspaceId, branch, wsRelPath, bot);
+            await versionControlService.releaseLock(workspaceId, branch, wsRelPath, bot);
             armed = true;
           } catch (armErr) {
             const lockAlreadyReleased =
-              armErr instanceof WorkflowDomainError && armErr.payload?.kind === 'lock-not-held';
+              armErr instanceof VersionControlDomainError && armErr.payload?.kind === 'lock-not-held';
             if (lockAlreadyReleased) {
               try {
-                armed = await workflowService.hasQueuedCommit(workspaceId, branch, wsRelPath);
+                armed = await versionControlService.hasQueuedCommit(workspaceId, branch, wsRelPath);
                 if (!armed) {
                   // The row may already be gone because the worker WON the
                   // race: drained it and pushed. A branch with nothing left
                   // unpushed cannot be holding our landed commit hostage.
-                  armed = !(await workflowService.hasUnpushedCommits(workspaceId));
+                  armed = !(await versionControlService.hasUnpushedCommits(workspaceId));
                 }
               } catch (queueErr) {
                 log.warn('could not verify the pending-commit queue:', { err: queueErr });

package/src/modules/access/user-access-removal.service.ts

@@ -37,9 +37,9 @@
  */
 
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
+import type { AuthUser, IWorkspaceService, IVersionControlService } from '@bevel-software/platform-shared';
+import { PushNeedsAgentResolutionError, VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
   ADMIN_CANONICAL,
@@ -92,7 +92,7 @@ async function mapPooled<T, R>(items: readonly T[], limit: number, fn: (item: T)
 }
 
 /** A removal this service refuses (guard) or cannot run. */
-export class UserAccessRemovalError extends WorkflowDomainError {
+export class UserAccessRemovalError extends VersionControlDomainError {
   constructor(message: string, status = 422, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'UserAccessRemovalError';
@@ -343,7 +343,7 @@ export class UserAccessRemovalService {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
-    workflowService: IWorkflowService,
+    versionControlService: IVersionControlService,
     private readonly accessControl: IAccessControl,
     /**
      * The resolver's own walk. NOT `workspaceService.listFiles`: that honours
@@ -354,13 +354,13 @@ export class UserAccessRemovalService {
     private readonly kbDirName: string,
     /** Live-binding thunk — DEFAULT_BRANCH stays empty until setup. */
     private readonly defaultBranchOf: () => string,
-    private readonly eventBus?: WorkflowEventBus,
+    private readonly eventBus?: VersionControlEventBus,
     /** The deployment owner(s) (`ADMIN_EMAIL`) — never removed this way. */
     private readonly deploymentOwners: readonly string[] = [],
   ) {
     this.locked = new AdminLockedCommits({
       workspaceService,
-      workflowService,
+      versionControlService,
       kbDirName,
       defaultBranchOf,
       makeError: (message, status, payload) => new UserAccessRemovalError(message, status, payload),

package/src/modules/access-model/__tests__/access-grammar.test.ts

@@ -145,7 +145,7 @@ describe('the access-frontmatter extension set', () => {
   it('throws on a malformed extension rather than skipping it', () => {
     // A typo would otherwise leave capability-granting files ungoverned, at
     // boot, with nothing to distinguish it from a successful registration.
-    expect(() => registerAccessFrontmatterExtensions(['pipeline'])).toThrow(/malformed/);
+    expect(() => registerAccessFrontmatterExtensions(['workflow'])).toThrow(/malformed/);
     expect(() => registerAccessFrontmatterExtensions(['.two.dots'])).toThrow(/malformed/);
     expect(() => registerAccessFrontmatterExtensions([''])).toThrow(/malformed/);
     expect(hasAccessFrontmatterExtension('x.pipeline_typo_guard')).toBe(false);
@@ -186,7 +186,7 @@ describe('the access-frontmatter extension set', () => {
 });
 
 describe('parseOwnAccessEntries — whole-document YAML the subset parser cannot read', () => {
-  // A `.tool` / `.pipeline` / `.agent` is one `---` fenced YAML document, and
+  // A `.tool` / `.workflow` / `.agent` is one `---` fenced YAML document, and
   // real ones use folded and literal scalars and nested maps. The subset
   // parser stops at the first such line; the verbs must still be read.
   const doc = [

package/src/modules/access-model/access-errors.ts

@@ -1,4 +1,4 @@
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';
 
 export interface AccessDeniedDetails {
@@ -55,7 +55,7 @@ export function unreadableRefusalSentence(repoRelative: string): string {
  * "you don't have permission to write to <path>; eligible: <roles + users>"
  * without a follow-up roundtrip.
  */
-export class AccessDeniedError extends WorkflowDomainError {
+export class AccessDeniedError extends VersionControlDomainError {
   readonly access: AccessDeniedDetails;
 
   constructor(details: AccessDeniedDetails) {
@@ -89,7 +89,7 @@ export class AccessDeniedError extends WorkflowDomainError {
  * 503 and the caller retries. Distinct from AccessConfigError (the config is
  * there and wrong) and AccessDeniedError (a real permission decision).
  */
-export class AccessUnreadableError extends WorkflowDomainError {
+export class AccessUnreadableError extends VersionControlDomainError {
   constructor(ref: string, relativePath: string) {
     super(
       `Access rules at ${ref} could not be read (git failed on ${relativePath}); nothing was decided. Try again.`,
@@ -105,7 +105,7 @@ export class AccessUnreadableError extends WorkflowDomainError {
  * or malformed at runtime — distinct from AccessDeniedError because the cause
  * is a config bug, not a permission decision.
  */
-export class AccessConfigError extends WorkflowDomainError {
+export class AccessConfigError extends VersionControlDomainError {
   readonly errors: string[];
 
   constructor(errors: string[]) {

package/src/modules/access-model/access-grammar.ts

@@ -285,8 +285,8 @@ const accessFrontmatterExtensions = new Set<string>(CORE_ACCESS_FRONTMATTER_EXTE
  */
 export function registerAccessFrontmatterExtensions(extensions: readonly string[]): void {
   // Validate EVERYTHING first, then apply. These registrations decide which
-  // files' edits carry enforced access grants, so a typo (`pipeline` for
-  // `.pipeline`) must THROW rather than be skipped — a silent skip makes a
+  // files' edits carry enforced access grants, so a typo (`workflow` for
+  // `.workflow`) must THROW rather than be skipped — a silent skip makes a
   // failed registration indistinguishable from a successful one, at boot,
   // where nobody is looking. And it must throw before the registry changes:
   // a list that is half-applied when it throws leaves later scans governing a
@@ -295,7 +295,7 @@ export function registerAccessFrontmatterExtensions(extensions: readonly string[
     const n = ext.trim().toLowerCase();
     if (!/^\.[a-z0-9]+$/.test(n)) {
       throw new Error(
-        `access frontmatter extension "${ext}" is malformed — expected a leading dot, e.g. ".pipeline"`,
+        `access frontmatter extension "${ext}" is malformed — expected a leading dot, e.g. ".workflow"`,
       );
     }
     return n;
@@ -313,7 +313,7 @@ export function accessFrontmatterExtensionList(): string[] {
  *
  * Case-SENSITIVE on the path, as it always was: `doc.MD` is not a node and
  * carries no enforced grant. Registered extensions are normalized to lowercase
- * so `.Pipeline` and `.pipeline` register the same thing, but which FILES are
+ * so `.Workflow` and `.workflow` register the same thing, but which FILES are
  * governed must not change because the set became registrable — widening it to
  * `X.MD` silently in a release would be an access-model change nobody asked
  * for, made in a refactor.

package/src/modules/access-model/change-gate.ts

@@ -2,7 +2,7 @@
  * The contract of the READ-BEFORE-WRITE gate: nothing is created, changed or
  * removed at a place its author cannot read. The service that answers
  * (filesystem stats, access checks) is `modules/access/change-read-gate.ts`;
- * this file carries only the types, so the workflow, kb-fs and tool modules
+ * this file carries only the types, so the version-control, kb-fs and tool modules
  * depend on the contract and never on the access module.
  *
  * Why `read`, when every write already needs `write`: on a draft branch no

package/src/modules/access-model/roles-yaml-guard.ts

@@ -24,7 +24,7 @@
 import type { FileContent } from '@mastra/core/workspace';
 import { GROUP_REF_PREFIX, canonicalRoleName, parseRolesYaml, parseYamlSubset } from './access-grammar.js';
 import type { GroupsIndex } from './group-files.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { WriteValidator } from '../kb-fs/index.js';
 
 /** Repo-relative basename of the roles file (it lives at the KB repo root). */
@@ -35,7 +35,7 @@ export const ROLES_YAML_BASENAME = 'roles.yaml';
  * the edit is refused and nothing is written. Carries the parser errors so the
  * editor / agent can show exactly what's wrong.
  */
-export class RolesYamlInvalidError extends WorkflowDomainError {
+export class RolesYamlInvalidError extends VersionControlDomainError {
   readonly errors: string[];
   constructor(errors: string[]) {
     super(
@@ -102,7 +102,7 @@ export const NEW_ROLE_GUIDANCE =
  * self-contained because a tool error reaches the agent as its message alone,
  * and the agent relays it to its user.
  */
-export class RolesYamlNewRoleError extends WorkflowDomainError {
+export class RolesYamlNewRoleError extends VersionControlDomainError {
   readonly roleNames: string[];
   constructor(roleNames: string[]) {
     const quoted = roleNames.map((n) => `'${n}'`).join(', ');
@@ -171,7 +171,7 @@ interface GroupEntry {
  * entry with only a log warning — the role silently reaches nobody — so it is
  * refused up front, naming each entry, in the same 422 shape as the others.
  */
-export class RolesYamlUnknownGroupError extends WorkflowDomainError {
+export class RolesYamlUnknownGroupError extends VersionControlDomainError {
   readonly entries: { role: string; entry: string }[];
   constructor(entries: { role: string; entry: string }[], sourceFile: string) {
     const listed = entries.map((e) => `'- ${e.entry}' under role '${e.role}'`).join(', ');

package/src/modules/agent-guide/__tests__/agent-guide.test.ts

@@ -43,7 +43,7 @@ describe('the guide is composed from the platform\'s sections', () => {
     const sections = await coreAgentGuideSections(DEFAULT_KB_LAYOUT);
     expect(sections.map((s) => s.id)).toEqual(CORE_SECTION_IDS);
     const rules = sections.find((s) => s.id === WORKING_WITH_FILES_SECTION_ID)!;
-    expect(rules.body).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    expect(rules.body).toBe(sharedFileRulesSection(DEFAULT_KB_LAYOUT, ''));
     expect(rules.literal).toBe(true);
     // Every section begins with its heading, so the guide reads as one document.
     for (const s of sections) expect(s.body.startsWith('## '), s.id).toBe(true);
@@ -66,7 +66,7 @@ describe('the guide is composed from the platform\'s sections', () => {
     // never passed through the renderer again: a folder literally named like a
     // placeholder comes out as the folder it is.
     const odd = await composeAgentGuide({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' });
-    expect(odd).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' }));
+    expect(odd).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: '{{skillsDir}}', skillsDir: 'Playbooks' }, ''));
   });
 
   it('says it is served, not written, and names the one file it is read as', async () => {
@@ -127,7 +127,7 @@ describe('the guide is composed from the platform\'s sections', () => {
     expect(section(guide, '## Words used here')).toContain('Ask the graph.');
     expect(section(guide, '## Words used here')).not.toContain('Plugin');
     expect(guide.trimEnd().endsWith('Nodes live under `Docs/<Ontology>/Knowledge/`.')).toBe(true);
-    expect(guide).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' }));
+    expect(guide).toContain(sharedFileRulesSection({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' }, ''));
     // An async hook is awaited, and the layout it is handed is the resolved one.
     const seen: string[] = [];
     await composeAgentGuide({ knowledgeBaseDir: ' Docs ', skillsDir: 'Skills', pluginsDir: 'Plugins' }, async (sections, layout) => {
@@ -192,6 +192,21 @@ describe('the guide is composed from the platform\'s sections', () => {
     expect(guideStartText(without)).toBe(joinGuideSections(without));
   });
 
+  it("refuses a hook that drops or empties the onboarding section, which the platform's onboard prompt points at", async () => {
+    await expect(
+      composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) => sections.filter((s) => s.id !== 'onboarding')),
+    ).rejects.toThrow(/dropped the "onboarding" section, which the platform's `onboard` prompt points at/);
+    await expect(
+      composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) => sections.map((s) => (s.id === 'onboarding' ? { id: s.id, body: ' \n' } : s))),
+    ).rejects.toThrow(/emptied the "onboarding" section/);
+    // Replacing it under the same id is the hook's right: an organisation
+    // ships its own onboarding.
+    const own = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
+      sections.map((s) => (s.id === 'onboarding' ? { id: s.id, body: '## Welcome\n\nOur own flow.' } : s)),
+    );
+    expect(own).toContain('Our own flow.');
+  });
+
   it('refuses a hook that drops or empties the shared file rules, which every file tool points at', async () => {
     await expect(
       composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) => sections.filter((s) => s.id !== WORKING_WITH_FILES_SECTION_ID)),
@@ -211,7 +226,7 @@ describe('the guide is composed from the platform\'s sections', () => {
       { id: WORKING_WITH_FILES_SECTION_ID, body: '' },
       ...sections,
     ]);
-    expect(twice).toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT));
+    expect(twice).toContain(sharedFileRulesSection(DEFAULT_KB_LAYOUT, ''));
     // Replacing it under the same id is the hook's right.
     const replaced = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
       sections.map((s) => (s.id === WORKING_WITH_FILES_SECTION_ID ? { id: s.id, body: '## Working with files\n\nOurs.\n' } : s)),

package/src/modules/agent-guide/__tests__/agent-guide.tools.test.ts

@@ -44,7 +44,7 @@ describe('get_agent_guide', () => {
         source: 'internal',
         abortSignal: new AbortController().signal,
         workspaceService: {} as never,
-        workflowService: {} as never,
+        versionControlService: {} as never,
         events: {} as never,
         getFilesystem: async () => {
           throw new Error('the guide reads no file');

package/src/modules/agent-guide/__tests__/guide-matches-code.test.ts

@@ -7,7 +7,7 @@ import {
   HEXIS_EXTENSION_NS,
   HEXIS_TOOLS_DIR,
   PERSONAL_PLUGIN_PREFIX,
-  PIPELINES_DIR,
+  WORKFLOWS_DIR,
   PLUGIN_MANIFEST_FILE,
   PLUGIN_MCP_FILE,
   PLUGIN_SKILLS_DIR,
@@ -217,7 +217,7 @@ describe('the guide names the folders and files kb-layout.ts defines', () => {
 
   it('names the platform files and reserved folders by their defined names', async () => {
     const guide = (await agentGuideSections(DEFAULT_KB_LAYOUT)).map((s) => s.body).join('\n');
-    for (const name of [...FIXED_PLATFORM_FILE_NAMES, GROUPS_YAML, SYNCED_GROUPS_YAML, PREAMBLE_FILE, BUNDLE_FILE, DATA_DIR, AGENTS_DIR, PIPELINES_DIR]) {
+    for (const name of [...FIXED_PLATFORM_FILE_NAMES, GROUPS_YAML, SYNCED_GROUPS_YAML, PREAMBLE_FILE, BUNDLE_FILE, DATA_DIR, AGENTS_DIR, WORKFLOWS_DIR]) {
       expect(guide, name).toContain(name);
     }
     // A lowercase `.yaml` or `.json` file the guide names is one of the