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

package/src/index.ts

@@ -1,69 +1,69 @@
-/**
- * @bevel-software/platform-core-backend — the open-source core of the Bevel platform:
- * git-backed knowledge workspace, workflow (branches / change requests /
- * locks / SSE), skills, tool manuals + registry + auth, secrets vault, access
- * control, diff/backup ledger, code-mode and the remote MCP surface.
- *
- * Composition entry points:
- *   - `new CoreConfig()`                     — env-driven core configuration
- *   - `createCoreServices(config, ports)`    — construct every core service
- *   - `createCoreServer(core, ext, opts)`    — the Express app (fixed mount order)
- *
- * Importing this package ALSO applies the global Express `Request`
- * augmentation (`req.userId` / `req.userEmail` / token payloads) — the
- * middleware modules re-exported below carry the `declare global` blocks, so
- * consumers get the augmented types without a side-effect import of their own.
- *
- * Finer-grained internals are available via the `./modules/*` subpath exports.
- */
-
-export { CoreConfig } from './core-config.js';
-export { createCoreServices, type CoreServices } from './core/create-core-services.js';
-export {
-  createCoreServer,
-  type ServerExtensions,
-  type ToolSurfaceCtx,
-} from './core/create-core-server.js';
-export { noopRecoveryAgent, type CorePorts } from './core/core-ports.js';
-
-// Packaged assets (migrations/, kb-template/) + the migration runners.
-export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
-export {
-  runCoreMigrations,
-  runEnterpriseMigrations,
-} from './modules/database/migrate.js';
-export { getDb, type Database } from './modules/database/connection.js';
-
-// Build identity surfaced by GET /api/health.
-export { GIT_SHA, resolveGitSha } from './version.js';
-
-// Express `Request` augmentation carriers (userId/userEmail — auth.middleware;
-// token payloads — tool-auth + external-api-key interface). Re-exported by
-// VALUE/type so the `declare global` blocks land in this package's public
-// declaration graph.
-export { createAuthMiddleware, AUTH_COOKIE_NAME } from './modules/auth/auth.middleware.js';
-export {
-  createToolAuthMiddleware,
-  createManualAuthMiddleware,
-} from './modules/tool-auth/tool-auth.middleware.js';
-export type {
-  IExternalApiKeyService,
-  ExternalApiKeySummary,
-} from './modules/tool-auth/external-api-key.interface.js';
-
-// Key port/seam types an overlay implements.
-export type { ISessionSink } from './modules/workspace/session-sink.js';
-export type {
-  ISystemNoticeSink,
-  RecoveryAgentRunner,
-} from './modules/workflow/pending-commits.worker.js';
-export type { ILlmUsageMeter } from './modules/tool-auth/llm-usage-meter.js';
-export type { AuthProviderPlugin } from './modules/auth/auth.routes.js';
-export type { IErasureParticipant } from './modules/auth/account-erasure.service.js';
-export {
-  WorkflowHooks,
-  type CommitValidationHook,
-  type CommitValidationContext,
-  type PreWriteHook,
-  type PreWriteContext,
-} from './modules/workflow/workflow-hooks.js';
+/**
+ * @bevel-software/platform-core-backend — the open-source core of the Bevel platform:
+ * git-backed knowledge workspace, workflow (branches / change requests /
+ * locks / SSE), skills, tool manuals + registry + auth, secrets vault, access
+ * control, diff/backup ledger, code-mode and the remote MCP surface.
+ *
+ * Composition entry points:
+ *   - `new CoreConfig()`                     — env-driven core configuration
+ *   - `createCoreServices(config, ports)`    — construct every core service
+ *   - `createCoreServer(core, ext, opts)`    — the Express app (fixed mount order)
+ *
+ * Importing this package ALSO applies the global Express `Request`
+ * augmentation (`req.userId` / `req.userEmail` / token payloads) — the
+ * middleware modules re-exported below carry the `declare global` blocks, so
+ * consumers get the augmented types without a side-effect import of their own.
+ *
+ * Finer-grained internals are available via the `./modules/*` subpath exports.
+ */
+
+export { CoreConfig } from './core-config.js';
+export { createCoreServices, type CoreServices } from './core/create-core-services.js';
+export {
+  createCoreServer,
+  type ServerExtensions,
+  type ToolSurfaceCtx,
+} from './core/create-core-server.js';
+export { noopRecoveryAgent, type CorePorts } from './core/core-ports.js';
+
+// Packaged assets (migrations/, kb-template/) + the migration runners.
+export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
+export {
+  runCoreMigrations,
+  runEnterpriseMigrations,
+} from './modules/database/migrate.js';
+export { getDb, type Database } from './modules/database/connection.js';
+
+// Build identity surfaced by GET /api/health.
+export { GIT_SHA, resolveGitSha } from './version.js';
+
+// Express `Request` augmentation carriers (userId/userEmail — auth.middleware;
+// token payloads — tool-auth + external-api-key interface). Re-exported by
+// VALUE/type so the `declare global` blocks land in this package's public
+// declaration graph.
+export { createAuthMiddleware, AUTH_COOKIE_NAME } from './modules/auth/auth.middleware.js';
+export {
+  createToolAuthMiddleware,
+  createManualAuthMiddleware,
+} from './modules/tool-auth/tool-auth.middleware.js';
+export type {
+  IExternalApiKeyService,
+  ExternalApiKeySummary,
+} from './modules/tool-auth/external-api-key.interface.js';
+
+// Key port/seam types an overlay implements.
+export type { ISessionSink } from './modules/workspace/session-sink.js';
+export type {
+  ISystemNoticeSink,
+  RecoveryAgentRunner,
+} from './modules/workflow/pending-commits.worker.js';
+export type { ILlmUsageMeter } from './modules/tool-auth/llm-usage-meter.js';
+export type { AuthProviderPlugin } from './modules/auth/auth.routes.js';
+export type { IErasureParticipant } from './modules/auth/account-erasure.service.js';
+export {
+  WorkflowHooks,
+  type CommitValidationHook,
+  type CommitValidationContext,
+  type PreWriteHook,
+  type PreWriteContext,
+} from './modules/workflow/workflow-hooks.js';

package/src/modules/access/__tests__/access-control.atref-batch.test.ts

@@ -1,98 +1,98 @@
-import { describe, it, expect, beforeAll, afterAll } 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 { AccessControlService } from '../access-control.service.js';
-
-const execFileAsync = promisify(execFile);
-const PROCESS_MAP_DIR = 'knowledge-base';
-
-/**
- * `canWriteBatchAtRef` / the batched at-ref own-entries read — backed by ONE
- * `git cat-file --batch` process whose length-prefixed output we parse by
- * hand, so exercise it against a REAL git repo: found blobs, a path missing
- * at the ref (the `<spec> missing` line), a path with spaces, and frontmatter
- * deny resolution — all in one batch, order-aligned.
- */
-describe('AccessControlService — at-ref batch reads (git cat-file --batch)', () => {
-  let root: string;
-  let repo: string;
-  let svc: AccessControlService;
-  const workspaceId = 'ws-atref-1';
-  const admin = 'razvan@bevel.software';
-
-  async function git(...args: string[]): Promise<void> {
-    await execFileAsync('git', ['-C', repo, ...args]);
-  }
-
-  beforeAll(async () => {
-    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-atref-'));
-    const workspaceDir = path.join(root, workspaceId);
-    repo = path.join(workspaceDir, PROCESS_MAP_DIR);
-    await fs.mkdir(path.join(repo, 'Knowledge'), { recursive: true });
-
-    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - razvan@bevel.software\n');
-    await fs.writeFile(path.join(repo, 'access.md'), '---\nwrite:\n  - Admin\n---\n');
-    await fs.writeFile(path.join(repo, 'Knowledge/plain.md'), '# plain\n');
-    await fs.writeFile(
-      path.join(repo, 'Knowledge/denied.md'),
-      '---\nwrite:\n  - deny razvan <razvan@bevel.software>\n---\n# denied\n',
-    );
-    await fs.writeFile(path.join(repo, 'Knowledge/with space.md'), '# spaced\n');
-
-    await execFileAsync('git', ['init', '-b', 'main', repo]);
-    await git('config', 'user.email', 'test@example.com');
-    await git('config', 'user.name', 'Test');
-    await git('add', '-A');
-    await git('commit', '-m', 'seed');
-
-    const stub = {
-      getWorkspacePath: async () => workspaceDir,
-      // Fixture repo has no remote; at-ref model loading fetches best-effort.
-      ensureRemotesFetched: async () => undefined,
-    } as unknown as WorkspaceService;
-    svc = new AccessControlService(stub, PROCESS_MAP_DIR);
-  });
-
-  afterAll(async () => {
-    await fs.rm(root, { recursive: true, force: true });
-  });
-
-  it('resolves a mixed batch in one pass: grants, frontmatter deny, spaces, and a missing path', async () => {
-    const paths = [
-      'Knowledge/plain.md', // dir-chain Admin grant → true
-      'Knowledge/denied.md', // own frontmatter deny → false
-      'Knowledge/with space.md', // found blob whose SPEC contains spaces → true
-      'Knowledge/not-there.md', // missing at the ref (`<spec> missing` line) → dir-chain verdict
-    ];
-    const map = await svc.canWriteBatchAtRef(workspaceId, 'main', admin, paths);
-    expect(map).not.toBeNull();
-    expect(map!.get('Knowledge/plain.md')).toBe(true);
-    expect(map!.get('Knowledge/denied.md')).toBe(false);
-    expect(map!.get('Knowledge/with space.md')).toBe(true);
-    expect(map!.get('Knowledge/not-there.md')).toBe(true);
-  });
-
-  it('matches the single-path at-ref resolution exactly', async () => {
-    // The batch is a pure performance change — verdicts must be identical to
-    // the per-path `git show` route the single-path helper still uses.
-    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/denied.md')).toBe(false);
-    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/plain.md')).toBe(true);
-  });
-
-  it('eligibleWritersForPathsAtRef honours the same batched own-entries', async () => {
-    const map = await svc.eligibleWritersForPathsAtRef(workspaceId, 'main', [
-      'Knowledge/plain.md',
-      'Knowledge/denied.md',
-    ]);
-    expect(map).not.toBeNull();
-    expect(map!.get('Knowledge/plain.md')!.roles).toContain('Admin');
-    // The per-user deny strips razvan from the expanded email set.
-    expect(map!.get('Knowledge/denied.md')!.emails.has(admin)).toBe(false);
-    expect(map!.get('Knowledge/plain.md')!.emails.has(admin)).toBe(true);
-  });
-});
+import { describe, it, expect, beforeAll, afterAll } 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 { AccessControlService } from '../access-control.service.js';
+
+const execFileAsync = promisify(execFile);
+const PROCESS_MAP_DIR = 'knowledge-base';
+
+/**
+ * `canWriteBatchAtRef` / the batched at-ref own-entries read — backed by ONE
+ * `git cat-file --batch` process whose length-prefixed output we parse by
+ * hand, so exercise it against a REAL git repo: found blobs, a path missing
+ * at the ref (the `<spec> missing` line), a path with spaces, and frontmatter
+ * deny resolution — all in one batch, order-aligned.
+ */
+describe('AccessControlService — at-ref batch reads (git cat-file --batch)', () => {
+  let root: string;
+  let repo: string;
+  let svc: AccessControlService;
+  const workspaceId = 'ws-atref-1';
+  const admin = 'razvan@bevel.software';
+
+  async function git(...args: string[]): Promise<void> {
+    await execFileAsync('git', ['-C', repo, ...args]);
+  }
+
+  beforeAll(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-atref-'));
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+    await fs.mkdir(path.join(repo, 'Knowledge'), { recursive: true });
+
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - razvan@bevel.software\n');
+    await fs.writeFile(path.join(repo, 'access.md'), '---\nwrite:\n  - Admin\n---\n');
+    await fs.writeFile(path.join(repo, 'Knowledge/plain.md'), '# plain\n');
+    await fs.writeFile(
+      path.join(repo, 'Knowledge/denied.md'),
+      '---\nwrite:\n  - deny razvan <razvan@bevel.software>\n---\n# denied\n',
+    );
+    await fs.writeFile(path.join(repo, 'Knowledge/with space.md'), '# spaced\n');
+
+    await execFileAsync('git', ['init', '-b', 'main', repo]);
+    await git('config', 'user.email', 'test@example.com');
+    await git('config', 'user.name', 'Test');
+    await git('add', '-A');
+    await git('commit', '-m', 'seed');
+
+    const stub = {
+      getWorkspacePath: async () => workspaceDir,
+      // Fixture repo has no remote; at-ref model loading fetches best-effort.
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    svc = new AccessControlService(stub, PROCESS_MAP_DIR);
+  });
+
+  afterAll(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('resolves a mixed batch in one pass: grants, frontmatter deny, spaces, and a missing path', async () => {
+    const paths = [
+      'Knowledge/plain.md', // dir-chain Admin grant → true
+      'Knowledge/denied.md', // own frontmatter deny → false
+      'Knowledge/with space.md', // found blob whose SPEC contains spaces → true
+      'Knowledge/not-there.md', // missing at the ref (`<spec> missing` line) → dir-chain verdict
+    ];
+    const map = await svc.canWriteBatchAtRef(workspaceId, 'main', admin, paths);
+    expect(map).not.toBeNull();
+    expect(map!.get('Knowledge/plain.md')).toBe(true);
+    expect(map!.get('Knowledge/denied.md')).toBe(false);
+    expect(map!.get('Knowledge/with space.md')).toBe(true);
+    expect(map!.get('Knowledge/not-there.md')).toBe(true);
+  });
+
+  it('matches the single-path at-ref resolution exactly', async () => {
+    // The batch is a pure performance change — verdicts must be identical to
+    // the per-path `git show` route the single-path helper still uses.
+    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/denied.md')).toBe(false);
+    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/plain.md')).toBe(true);
+  });
+
+  it('eligibleWritersForPathsAtRef honours the same batched own-entries', async () => {
+    const map = await svc.eligibleWritersForPathsAtRef(workspaceId, 'main', [
+      'Knowledge/plain.md',
+      'Knowledge/denied.md',
+    ]);
+    expect(map).not.toBeNull();
+    expect(map!.get('Knowledge/plain.md')!.roles).toContain('Admin');
+    // The per-user deny strips razvan from the expanded email set.
+    expect(map!.get('Knowledge/denied.md')!.emails.has(admin)).toBe(false);
+    expect(map!.get('Knowledge/plain.md')!.emails.has(admin)).toBe(true);
+  });
+});

package/src/modules/access/__tests__/access-declarations.test.ts

@@ -52,7 +52,7 @@ function makeWorkspace(files: Record<string, string>): IWorkspaceService {
   } as unknown as IWorkspaceService;
 }
 
-const scan = (files: Record<string, string>, folder = 'Groups/GTM') =>
+const scan = (files: Record<string, string>, folder = 'Plugins/GTM') =>
   listAccessDeclarationsUnder(makeWorkspace(files), WS, KB, folder);
 
 const fm = (body: string) => `---\n${body}\n---\n\n# Body\n`;
@@ -60,14 +60,14 @@ const fm = (body: string) => `---\n${body}\n---\n\n# Body\n`;
 describe('listAccessDeclarationsUnder', () => {
   it('reports a descendant access.md against the directory it governs', async () => {
     const { overrides, truncated } = await scan({
-      [`${KB}/Groups/GTM/battlecards/access.md`]: fm('write:\n  - GTM Team'),
+      [`${KB}/Plugins/GTM/battlecards/access.md`]: fm('write:\n  - GTM Team'),
     });
 
     expect(truncated).toBe(false);
     expect(overrides).toEqual([
       {
-        path: 'Groups/GTM/battlecards/access.md',
-        governs: 'Groups/GTM/battlecards',
+        path: 'Plugins/GTM/battlecards/access.md',
+        governs: 'Plugins/GTM/battlecards',
         source: 'access-md',
         entries: [{ verb: 'write', deny: false, principal: { kind: 'role', role: 'GTM Team' } }],
       },
@@ -76,23 +76,23 @@ describe('listAccessDeclarationsUnder', () => {
 
   it("excludes the target folder's own access.md — that is the summary, not an override", async () => {
     const { overrides } = await scan({
-      [`${KB}/Groups/GTM/access.md`]: fm('read:\n  - GTM Team'),
-      [`${KB}/Groups/GTM/battlecards/access.md`]: fm('read:\n  - Developer'),
+      [`${KB}/Plugins/GTM/access.md`]: fm('read:\n  - GTM Team'),
+      [`${KB}/Plugins/GTM/battlecards/access.md`]: fm('read:\n  - Developer'),
     });
 
-    expect(overrides.map((o) => o.path)).toEqual(['Groups/GTM/battlecards/access.md']);
+    expect(overrides.map((o) => o.path)).toEqual(['Plugins/GTM/battlecards/access.md']);
   });
 
   it('reads verbs out of SKILL.md and .tool frontmatter, governing the file itself', async () => {
     const { overrides } = await scan({
-      [`${KB}/Groups/GTM/outreach/SKILL.md`]: fm('nodeType: Skill\nowner: Ali <ali@bevel.software>'),
-      [`${KB}/Groups/GTM/slack.tool`]: fm('write:\n  - Developer'),
+      [`${KB}/Plugins/GTM/outreach/SKILL.md`]: fm('nodeType: Skill\nowner: Ali <ali@bevel.software>'),
+      [`${KB}/Plugins/GTM/slack.tool`]: fm('write:\n  - Developer'),
     });
 
     expect(overrides).toEqual([
       {
-        path: 'Groups/GTM/outreach/SKILL.md',
-        governs: 'Groups/GTM/outreach/SKILL.md',
+        path: 'Plugins/GTM/outreach/SKILL.md',
+        governs: 'Plugins/GTM/outreach/SKILL.md',
         source: 'frontmatter',
         entries: [
           {
@@ -103,8 +103,8 @@ describe('listAccessDeclarationsUnder', () => {
         ],
       },
       {
-        path: 'Groups/GTM/slack.tool',
-        governs: 'Groups/GTM/slack.tool',
+        path: 'Plugins/GTM/slack.tool',
+        governs: 'Plugins/GTM/slack.tool',
         source: 'frontmatter',
         entries: [{ verb: 'write', deny: false, principal: { kind: 'role', role: 'Developer' } }],
       },
@@ -113,7 +113,7 @@ describe('listAccessDeclarationsUnder', () => {
 
   it('ignores nodes whose frontmatter declares no access verb', async () => {
     const { overrides } = await scan({
-      [`${KB}/Groups/GTM/outreach/SKILL.md`]: fm('nodeType: Skill\ndescription: Runs outreach'),
+      [`${KB}/Plugins/GTM/outreach/SKILL.md`]: fm('nodeType: Skill\ndescription: Runs outreach'),
     });
 
     expect(overrides).toEqual([]);
@@ -121,7 +121,7 @@ describe('listAccessDeclarationsUnder', () => {
 
   it('preserves the deny prefix, collapses everyone, and carries user name + email', async () => {
     const { overrides } = await scan({
-      [`${KB}/Groups/GTM/battlecards/access.md`]: fm(
+      [`${KB}/Plugins/GTM/battlecards/access.md`]: fm(
         'read:\n  - everyone\n  - deny Bob Ruiz <bob@bevel.software>\nwrite:\n  - deny GTM Team',
       ),
     });
@@ -140,13 +140,13 @@ describe('listAccessDeclarationsUnder', () => {
   it('surfaces an unparseable access.md and silently skips an unparseable node', async () => {
     const { overrides } = await scan({
       // `read:` must be a LIST in an access.md — this file controls nothing.
-      [`${KB}/Groups/GTM/battlecards/access.md`]: fm('read: GTM Team'),
+      [`${KB}/Plugins/GTM/battlecards/access.md`]: fm('read: GTM Team'),
       // Unterminated frontmatter on a node — forgiven, exactly like the resolver.
-      [`${KB}/Groups/GTM/outreach/SKILL.md`]: '---\nowner: Ali <ali@bevel.software>\n\n# Body\n',
+      [`${KB}/Plugins/GTM/outreach/SKILL.md`]: '---\nowner: Ali <ali@bevel.software>\n\n# Body\n',
     });
 
     expect(overrides).toHaveLength(1);
-    expect(overrides[0].path).toBe('Groups/GTM/battlecards/access.md');
+    expect(overrides[0].path).toBe('Plugins/GTM/battlecards/access.md');
     expect(overrides[0].entries).toEqual([]);
     expect(overrides[0].parseError).toContain("'read:' must be a list");
   });
@@ -155,7 +155,7 @@ describe('listAccessDeclarationsUnder', () => {
     const files: Record<string, string> = {};
     for (let i = 0; i < DECLARATION_SCAN_FILE_CAP + 5; i++) {
       const n = String(i).padStart(4, '0');
-      files[`${KB}/Groups/GTM/n${n}/SKILL.md`] = fm('read:\n  - Developer');
+      files[`${KB}/Plugins/GTM/n${n}/SKILL.md`] = fm('read:\n  - Developer');
     }
 
     const { overrides, truncated } = await scan(files);
@@ -165,31 +165,31 @@ describe('listAccessDeclarationsUnder', () => {
   });
 
   it('returns an empty result for a folder with nothing in it', async () => {
-    expect(await scan({ [`${KB}/Groups/Product/roadmap/SKILL.md`]: fm('read:\n  - Developer') }))
+    expect(await scan({ [`${KB}/Plugins/Product/roadmap/SKILL.md`]: fm('read:\n  - Developer') }))
       .toEqual({ overrides: [], truncated: false });
   });
 
   it('returns an empty result for a folder that is not in the clone', async () => {
-    expect(await scan({}, 'Groups/Nope')).toEqual({ overrides: [], truncated: false });
+    expect(await scan({}, 'Plugins/Nope')).toEqual({ overrides: [], truncated: false });
   });
 
   it('refuses a target that is a file', async () => {
     await expect(
-      scan({ [`${KB}/Groups/GTM/slack.tool`]: fm('write:\n  - Developer') }, 'Groups/GTM/slack.tool'),
+      scan({ [`${KB}/Plugins/GTM/slack.tool`]: fm('write:\n  - Developer') }, 'Plugins/GTM/slack.tool'),
     ).rejects.toBeInstanceOf(AccessDeclarationsError);
   });
 
   it('sorts rows by declaring path', async () => {
     const { overrides } = await scan({
-      [`${KB}/Groups/GTM/zeta.tool`]: fm('write:\n  - Developer'),
-      [`${KB}/Groups/GTM/alpha/access.md`]: fm('read:\n  - Developer'),
-      [`${KB}/Groups/GTM/mid/SKILL.md`]: fm('owner:\n  - Developer'),
+      [`${KB}/Plugins/GTM/zeta.tool`]: fm('write:\n  - Developer'),
+      [`${KB}/Plugins/GTM/alpha/access.md`]: fm('read:\n  - Developer'),
+      [`${KB}/Plugins/GTM/mid/SKILL.md`]: fm('owner:\n  - Developer'),
     });
 
     expect(overrides.map((o) => o.path)).toEqual([
-      'Groups/GTM/alpha/access.md',
-      'Groups/GTM/mid/SKILL.md',
-      'Groups/GTM/zeta.tool',
+      'Plugins/GTM/alpha/access.md',
+      'Plugins/GTM/mid/SKILL.md',
+      'Plugins/GTM/zeta.tool',
     ]);
   });
 });

package/src/modules/access/__tests__/access-md-format.test.ts

@@ -19,7 +19,7 @@ import { spliceGrant, spliceRevoke } from '../access-splice.js';
  *    govern itself (its readability follows the folder chain).
  *  - NEW: the body carries the folder's rules; the frontmatter — like every
  *    other file's — is about the FILE itself. `read: everyone` there makes
- *    the group discoverable (anyone may open the access.md and see who runs
+ *    the plugin discoverable (anyone may open the access.md and see who runs
  *    the folder) while the folder's contents stay locked.
  *
  * Compat rule under test: a file whose body is NOT parsable as rules resolves
@@ -35,7 +35,7 @@ const ROLES_YAML = `roles:
     - felix@example.com
 `;
 
-/** New-format group access.md: discoverable by everyone, readable by GTM Team. */
+/** New-format plugin access.md: discoverable by everyone, readable by GTM Team. */
 const NEW_FORMAT = `---
 read:
   - everyone
@@ -58,7 +58,7 @@ Some prose explaining this folder.
 describe('access.md format detection + parsing', () => {
   it('detects body rules (new format) and parses the BODY for the folder', () => {
     expect(accessMdDeclaresBodyRules(NEW_FORMAT)).toBe(true);
-    const parsed = parseAccessFile(NEW_FORMAT, 'Groups/GTM/access.md');
+    const parsed = parseAccessFile(NEW_FORMAT, 'Plugins/GTM/access.md');
     expect(parsed.ok).toBe(true);
     if (!parsed.ok) return;
     expect(parsed.file.entries.read).toEqual([
@@ -89,7 +89,7 @@ describe('access.md format detection + parsing', () => {
     // (possibly `read: everyone`) self-rules — a typo must fail loudly.
     const typo = '---\nread:\n  - everyone\n---\nread: GTM Team\n';
     expect(accessMdDeclaresBodyRules(typo)).toBe(true);
-    const parsed = parseAccessFile(typo, 'Groups/GTM/access.md');
+    const parsed = parseAccessFile(typo, 'Plugins/GTM/access.md');
     expect(parsed.ok).toBe(false);
     if (parsed.ok) return;
     expect(parsed.errors.join(' ')).toContain("'read:' must be a list");
@@ -110,7 +110,7 @@ describe('access.md splice targeting', () => {
   it("target 'folder' on a new-format file lands the grant in the BODY", () => {
     const r = spliceGrant(NEW_FORMAT, 'read', FELIX, { target: 'folder' });
     expect(r.changed).toBe(true);
-    const parsed = parseAccessFile(r.text, 'Groups/GTM/access.md');
+    const parsed = parseAccessFile(r.text, 'Plugins/GTM/access.md');
     expect(parsed.ok && parsed.file.entries.read.some((e) => e.kind === 'user' && e.email === 'ali@x.eu')).toBe(true);
     // The self-frontmatter is untouched.
     expect(accessMdSelfEntries(r.text)?.read).toEqual([
@@ -132,7 +132,7 @@ describe('access.md splice targeting', () => {
     expect(r.changed).toBe(true);
     expect(accessMdSelfEntries(r.text)?.read.some((e) => e.kind === 'user' && e.email === 'ali@x.eu')).toBe(true);
     // Folder rules untouched.
-    const parsed = parseAccessFile(r.text, 'Groups/GTM/access.md');
+    const parsed = parseAccessFile(r.text, 'Plugins/GTM/access.md');
     expect(parsed.ok && parsed.file.entries.read.some((e) => e.kind === 'user')).toBe(false);
   });
 
@@ -140,14 +140,14 @@ describe('access.md splice targeting', () => {
     const granted = spliceGrant(NEW_FORMAT, 'read', FELIX, { target: 'folder' }).text;
     const revoked = spliceRevoke(granted, 'read', FELIX, { target: 'folder' });
     expect(revoked.changed).toBe(true);
-    const parsed = parseAccessFile(revoked.text, 'Groups/GTM/access.md');
+    const parsed = parseAccessFile(revoked.text, 'Plugins/GTM/access.md');
     expect(parsed.ok && parsed.file.entries.read.some((e) => e.kind === 'user')).toBe(false);
   });
 });
 
-describe('end-to-end resolution over a new-format group', () => {
+describe('end-to-end resolution over a new-format plugin', () => {
   let root: string;
-  const workspaceId = 'ws-groups-fmt';
+  const workspaceId = 'ws-plugins-fmt';
 
   beforeEach(async () => {
     root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-accessfmt-'));
@@ -159,12 +159,12 @@ describe('end-to-end resolution over a new-format group', () => {
   async function seed(): Promise<AccessControlService> {
     const workspaceDir = path.join(root, workspaceId);
     const repo = path.join(workspaceDir, KB);
-    await fs.mkdir(path.join(repo, 'Groups', 'GTM'), { recursive: true });
+    await fs.mkdir(path.join(repo, 'Plugins', 'GTM'), { recursive: true });
     await fs.writeFile(path.join(repo, 'roles.yaml'), ROLES_YAML);
     await fs.writeFile(path.join(repo, 'access.md'), '---\nwrite:\n  - Admin\n---\n');
-    await fs.writeFile(path.join(repo, 'Groups', 'GTM', 'access.md'), NEW_FORMAT);
-    await fs.mkdir(path.join(repo, 'Groups', 'GTM', 'outreach'), { recursive: true });
-    await fs.writeFile(path.join(repo, 'Groups', 'GTM', 'outreach', 'SKILL.md'), '# outreach\n');
+    await fs.writeFile(path.join(repo, 'Plugins', 'GTM', 'access.md'), NEW_FORMAT);
+    await fs.mkdir(path.join(repo, 'Plugins', 'GTM', 'outreach'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'Plugins', 'GTM', 'outreach', 'SKILL.md'), '# outreach\n');
     const stub = {
       getWorkspacePath: async (id: string) => {
         if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
@@ -177,15 +177,15 @@ describe('end-to-end resolution over a new-format group', () => {
   it('a NON-member can read the access.md itself (discovery) but nothing inside the folder', async () => {
     const svc = await seed();
     const outsider = 'sara@example.com';
-    expect(await svc.canRead(workspaceId, outsider, 'Groups/GTM/access.md')).toBe(true);
-    expect(await svc.canRead(workspaceId, outsider, 'Groups/GTM/outreach/SKILL.md')).toBe(false);
+    expect(await svc.canRead(workspaceId, outsider, 'Plugins/GTM/access.md')).toBe(true);
+    expect(await svc.canRead(workspaceId, outsider, 'Plugins/GTM/outreach/SKILL.md')).toBe(false);
   });
 
   it('a member reads both; body rules (not frontmatter) decide the folder', async () => {
     const svc = await seed();
     const member = 'felix@example.com';
-    expect(await svc.canRead(workspaceId, member, 'Groups/GTM/access.md')).toBe(true);
-    expect(await svc.canRead(workspaceId, member, 'Groups/GTM/outreach/SKILL.md')).toBe(true);
-    expect(await svc.canWrite(workspaceId, member, 'Groups/GTM/outreach/SKILL.md')).toBe(true);
+    expect(await svc.canRead(workspaceId, member, 'Plugins/GTM/access.md')).toBe(true);
+    expect(await svc.canRead(workspaceId, member, 'Plugins/GTM/outreach/SKILL.md')).toBe(true);
+    expect(await svc.canWrite(workspaceId, member, 'Plugins/GTM/outreach/SKILL.md')).toBe(true);
   });
 });

package/src/modules/access/__tests__/access-mutation.service.test.ts

@@ -80,11 +80,11 @@ describe('AccessMutationService', () => {
     expect(text).toContain('# Sales folder');
   });
 
-  it('kbPrincipals surfaces the built-in Everyone group alongside declared roles', async () => {
-    const { groups } = await access.kbPrincipals(WS);
-    expect(groups).toContain('Everyone');
-    expect(groups).toContain('Admin');
-    expect(groups).toContain('Product Team');
+  it('kbPrincipals surfaces the built-in Everyone plugin alongside declared roles', async () => {
+    const { plugins } = await access.kbPrincipals(WS);
+    expect(plugins).toContain('Everyone');
+    expect(plugins).toContain('Admin');
+    expect(plugins).toContain('Product Team');
   });
 
   it('grant everyone read makes the folder publicly readable (read: everyone)', async () => {

package/src/modules/access/__tests__/access-splice.test.ts

@@ -220,13 +220,13 @@ describe('validatePrincipal — injection guard', () => {
     expect(p.kind === 'user' && p.displayName).toBe('Ali');
   });
 
-  it('rejects a group name with a colon (would forge a key)', () => {
+  it('rejects a plugin name with a colon (would forge a key)', () => {
     expect(() => validatePrincipal({ kind: 'role', role: 'write:\n  - everyone' })).toThrow(
       AccessSpliceError,
     );
   });
 
-  it('rejects the reserved group name deny', () => {
+  it('rejects the reserved plugin name deny', () => {
     expect(() => validatePrincipal({ kind: 'role', role: 'deny' })).toThrow(AccessSpliceError);
   });