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

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);
   });
 

package/src/modules/access/__tests__/access.routes.overrides.test.ts

@@ -113,9 +113,9 @@ function close(s: Server): Promise<void> {
 const fm = (body: string) => `---\n${body}\n---\n\n# Body\n`;
 
 const FILES = {
-  [`${KB}/Groups/GTM/access.md`]: fm('read:\n  - GTM Team'),
-  [`${KB}/Groups/GTM/battlecards/access.md`]: fm('read:\n  - deny everyone'),
-  [`${KB}/Groups/GTM/slack.tool`]: fm('owner: Ali <ali@bevel.software>'),
+  [`${KB}/Plugins/GTM/access.md`]: fm('read:\n  - GTM Team'),
+  [`${KB}/Plugins/GTM/battlecards/access.md`]: fm('read:\n  - deny everyone'),
+  [`${KB}/Plugins/GTM/slack.tool`]: fm('owner: Ali <ali@bevel.software>'),
 };
 
 describe('GET /access/overrides', () => {
@@ -133,20 +133,20 @@ describe('GET /access/overrides', () => {
   it('returns the declarations under a folder the caller can read', async () => {
     h = await makeHarness({ files: FILES });
 
-    const res = await get('Groups/GTM');
+    const res = await get('Plugins/GTM');
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({
       truncated: false,
       overrides: [
         {
-          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: 'read', deny: true, principal: { kind: 'everyone' } }],
         },
         {
-          path: 'Groups/GTM/slack.tool',
-          governs: 'Groups/GTM/slack.tool',
+          path: 'Plugins/GTM/slack.tool',
+          governs: 'Plugins/GTM/slack.tool',
           source: 'frontmatter',
           entries: [
             {
@@ -163,7 +163,7 @@ describe('GET /access/overrides', () => {
   it('403s a caller who cannot read the folder', async () => {
     h = await makeHarness({ files: FILES, canRead: () => false });
 
-    const res = await get('Groups/GTM');
+    const res = await get('Plugins/GTM');
     expect(res.status).toBe(403);
     expect(await res.json()).toEqual({ error: 'You do not have access to this folder.' });
   });
@@ -171,21 +171,21 @@ describe('GET /access/overrides', () => {
   it('drops rows governing something the caller cannot read', async () => {
     h = await makeHarness({
       files: FILES,
-      rowReadable: (p) => p !== 'Groups/GTM/battlecards',
+      rowReadable: (p) => p !== 'Plugins/GTM/battlecards',
     });
 
-    const res = await get('Groups/GTM');
+    const res = await get('Plugins/GTM');
     const body = (await res.json()) as { overrides: { path: string }[] };
-    expect(body.overrides.map((o) => o.path)).toEqual(['Groups/GTM/slack.tool']);
+    expect(body.overrides.map((o) => o.path)).toEqual(['Plugins/GTM/slack.tool']);
   });
 
   it('accepts a workspace-relative path exactly like a repo-relative one', async () => {
     h = await makeHarness({ files: FILES });
 
-    const repoRel = (await (await get('Groups/GTM')).json()) as unknown;
-    const wsRel = (await (await get(`${KB}/Groups/GTM`)).json()) as unknown;
+    const repoRel = (await (await get('Plugins/GTM')).json()) as unknown;
+    const wsRel = (await (await get(`${KB}/Plugins/GTM`)).json()) as unknown;
     expect(wsRel).toEqual(repoRel);
-    expect(h.canRead).toHaveBeenCalledWith(WS, USER.email, 'Groups/GTM');
+    expect(h.canRead).toHaveBeenCalledWith(WS, USER.email, 'Plugins/GTM');
   });
 
   it('400s a path that escapes the KB repo', async () => {
@@ -198,7 +198,7 @@ describe('GET /access/overrides', () => {
   it('400s a target that is a file, not a folder', async () => {
     h = await makeHarness({ files: FILES });
 
-    const res = await get('Groups/GTM/slack.tool');
+    const res = await get('Plugins/GTM/slack.tool');
     expect(res.status).toBe(400);
     expect(await res.json()).toEqual({ error: 'path must be a folder' });
   });

package/src/modules/access/__tests__/grant-sources.test.ts

@@ -109,19 +109,19 @@ describe('AccessControlService.grantSources', () => {
     expect(src.write).toEqual([{ kind: 'ancestor', path: 'Knowledge/access.md' }]);
   });
 
-  it('a USER who holds a verb only via a group they belong to has NO source (the group row carries it)', async () => {
+  it('a USER who holds a verb only via a plugin they belong to has NO source (the plugin row carries it)', async () => {
     await writeFile(repo, 'access.md', '---\nwrite:\n  - Engineer\n---\n');
-    // Ali is an Engineer (per roles.yaml) — his write flows through the GROUP, not
+    // Ali is an Engineer (per roles.yaml) — his write flows through the PLUGIN, not
     // a per-user file entry. He isn't named in any file, so there's nothing to
-    // remove for HIM here; the Engineering group is the removable principal.
+    // remove for HIM here; the Engineering plugin is the removable principal.
     const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', ALI);
     expect(src.write).toBeUndefined();
     expect(src).toEqual({}); // no verb resolves to a per-user file entry
   });
 
-  it('the GROUP principal itself resolves to its own file scope (direct/ancestor)', async () => {
+  it('the PLUGIN principal itself resolves to its own file scope (direct/ancestor)', async () => {
     // The same Engineer grant, asked about as the ROLE principal, IS a removable
-    // file entry — the group is named directly on Knowledge/access.md.
+    // file entry — the plugin is named directly on Knowledge/access.md.
     await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
     await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');
     const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
@@ -150,20 +150,20 @@ describe('AccessControlService.grantSources', () => {
     expect(src).toEqual({});
   });
 
-  it("a folder-target admin whose access is via the Admin GROUP has NO per-user source", async () => {
-    // Razvan's effective write comes from the `Admin` group grant, not a per-user
+  it("a folder-target admin whose access is via the Admin PLUGIN has NO per-user source", async () => {
+    // Razvan's effective write comes from the `Admin` plugin grant, not a per-user
     // entry — so as a USER principal he has no removable source here (the Admin
-    // group row carries it, exactly like any other group).
+    // plugin row carries it, exactly like any other plugin).
     await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
     const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', RAZVAN);
     expect(src.write).toBeUndefined();
     expect(src).toEqual({});
   });
 
-  it("a user named DIRECTLY in a file keeps a source even if they're also in a group", async () => {
-    // Razvan is in the Admin group AND named inline on Knowledge — the inline
+  it("a user named DIRECTLY in a file keeps a source even if they're also in a plugin", async () => {
+    // Razvan is in the Admin plugin AND named inline on Knowledge — the inline
     // entry is a removable file grant, so his source is direct (tier-1 email
-    // beats the group at the same scope).
+    // beats the plugin at the same scope).
     await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
     await writeFile(
       repo,
@@ -177,7 +177,7 @@ describe('AccessControlService.grantSources', () => {
   it('a role principal is matched by its own scope entry, not a role indirection', async () => {
     await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
     await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');
-    // The Engineer GROUP itself is granted on Knowledge — for the role principal that's a direct grant.
+    // The Engineer PLUGIN itself is granted on Knowledge — for the role principal that's a direct grant.
     const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
       kind: 'role',
       role: 'Engineer',

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

@@ -160,7 +160,9 @@ describe('RolesAdminService', () => {
     access = new AccessControlService(ws, KB);
     workflow = stubWorkflow();
     bus = stubEventBus();
-    svc = new RolesAdminService(ws, workflow.svc, access, KB, DEFAULT_BRANCH, bus.bus);
+    svc = new RolesAdminService(ws, workflow.svc, access, KB, () => DEFAULT_BRANCH, bus.bus, [
+      'recovery-admin@example.com',
+    ]);
   });
 
   afterEach(async () => {
@@ -174,6 +176,18 @@ describe('RolesAdminService', () => {
     expect(roster.find((r) => r.canonical === 'sales')!.members).toEqual(['felix@example.com']);
   });
 
+  it('resolves the default branch per call, not at construction', async () => {
+    // The deployment shape this guards: a service built during boot, before
+    // `configureBranchModel()` has applied the branch model, saw an empty
+    // `DEFAULT_BRANCH` and froze it — every roles route then failed branch
+    // validation with `Invalid branch name "": empty name` until a restart.
+    let branch = '';
+    const late = new RolesAdminService(ws, workflow.svc, access, KB, () => branch, bus.bus);
+    branch = DEFAULT_BRANCH;
+    const roster = await late.getRoster();
+    expect(roster.map((r) => r.canonical)).toEqual(['admin', 'sales']);
+  });
+
   it('getHealth reports ok for a valid file and corrupted for a broken one', async () => {
     expect(await svc.getHealth()).toEqual({ ok: true, errors: [] });
 
@@ -207,11 +221,31 @@ describe('RolesAdminService', () => {
     const restored = await readRoles();
     expect(access.validateRolesYaml(restored).ok).toBe(true);
     expect(roster.find((r) => r.canonical === 'admin')?.isAdmin).toBe(true);
-    expect(roster.find((r) => r.canonical === 'admin')!.members.length).toBeGreaterThan(0);
+    // The roster is THIS deployment's configured admin — never a list baked
+    // into the build (hard-coded emails would land one company's admins in
+    // every customer's recovered file).
+    expect(roster.find((r) => r.canonical === 'admin')!.members).toEqual([
+      'recovery-admin@example.com',
+    ]);
+    expect(restored).not.toContain('bevel.software');
     // And the file is now healthy.
     expect(await svc.getHealth()).toEqual({ ok: true, errors: [] });
   });
 
+  it('recover refuses when no admin is configured — an adminless roster is the disease, not the cure', async () => {
+    const corrupt = 'roles:\n  Admin:\n    - a@x.eu\n  Admin:\n    - b@x.eu\n';
+    await write(repo, 'roles.yaml', corrupt);
+    access.invalidate(WS);
+    const adminless = new RolesAdminService(ws, workflow.svc, access, KB, () => DEFAULT_BRANCH, bus.bus);
+    await expect(adminless.recover(ADMIN)).rejects.toMatchObject({
+      status: 500,
+      payload: { kind: 'no-recovery-admins' },
+    });
+    // Nothing parked, nothing overwritten.
+    await expect(fs.readFile(path.join(repo, 'old-roles.yaml'), 'utf-8')).rejects.toThrow();
+    expect(await fs.readFile(path.join(repo, 'roles.yaml'), 'utf-8')).toBe(corrupt);
+  });
+
   it("getRoster's referencedBy is sound — finds node-frontmatter refs, not just folder access.md", async () => {
     // A folder access.md grant (the only thing the old advisory scan saw)...
     await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');

package/src/modules/access/access-control.interface.ts

@@ -20,8 +20,8 @@
  *
  * Only a principal NAMED in a file (a direct user grant `Name <email>`, or a
  * group/role token) produces sources. A USER who merely RESOLVES to access via a
- * group they belong to, the built-in `everyone`, or admin-rescue is NOT a
- * per-target file entry and produces NO source (the group itself shows as its own
+ * plugin they belong to, the built-in `everyone`, or admin-rescue is NOT a
+ * per-target file entry and produces NO source (the plugin itself shows as its own
  * row instead).
  */
 export type GrantSource =
@@ -138,8 +138,8 @@ export interface IAccessControl {
 
   /**
    * Batched `canOwner` — one config load per call, same `owner:`-lists-only
-   * resolution (no admin rescue). Used by group enumeration to answer "which
-   * of these folders does the caller own?" without one model load per group.
+   * resolution (no admin rescue). Used by plugin enumeration to answer "which
+   * of these folders does the caller own?" without one model load per plugin.
    */
   canOwnerBatch(
     workspaceId: string,
@@ -281,8 +281,9 @@ export interface IAccessControl {
 
   /**
    * Enumerate the grantable principals known to the KB, for the share-dialog
-   * autocomplete. `groups` are the declared `roles.yaml` role display names
-   * (the built-in `everyone` is excluded — it isn't grantable from the UI).
+   * autocomplete. `plugins` are the built-in `everyone` role plus the declared
+   * `roles.yaml` role display names (`everyone` is surfaced so the UI can
+   * grant public read; the grant route gates it to the `read` verb only).
    * `people` are every email named in `roles.yaml` (name defaults to the local
    * part) unioned with every `Name <email>` grant in any `access.md` (named).
    * The login-only `users` table is unioned in by the caller — this method
@@ -290,7 +291,7 @@ export interface IAccessControl {
    */
   kbPrincipals(
     workspaceId: string,
-  ): Promise<{ groups: string[]; people: { name: string; email: string }[] }>;
+  ): Promise<{ plugins: string[]; people: { name: string; email: string }[] }>;
 
   /**
    * Reverse-lookup an email by its SHA-256 hash (per `hashEmail` semantics)

package/src/modules/access/access-control.service.ts

@@ -925,7 +925,7 @@ function scopeToGrantSource(
  * returning the WHOLE list of removable entries rather than just the winner.
  *
  * Only the principal's OWN named entry yields a source — a `user` by their email,
- * a `role` by its role token. A grant that reaches the user via a group they
+ * a `role` by its role token. A grant that reaches the user via a plugin they
  * belong to, the built-in `everyone`, or admin-rescue is NOT their entry, so it
  * never adds a source (the group/role shows as its own row instead). The list is:
  *   - `[]` (verb omitted by the caller) when the principal effectively holds no
@@ -941,7 +941,7 @@ function scopeToGrantSource(
  * under closest-wins), and the revoke flow needs the inherited remainder that
  * survives removing the direct entry. A group/everyone grant at some scope does
  * not add a source AND does not hide a farther own-entry the principal is named
- * in (removing it is still meaningful if the group grant is later removed).
+ * in (removing it is still meaningful if the plugin grant is later removed).
  */
 function resolveGrantSourcesForVerb(
   model: AccessModel,
@@ -1453,18 +1453,18 @@ export class AccessControlService implements IAccessControl {
 
   async kbPrincipals(
     workspaceId: string,
-  ): Promise<{ groups: string[]; people: { name: string; email: string }[] }> {
+  ): Promise<{ plugins: string[]; people: { name: string; email: string }[] }> {
     let model: AccessModel;
     try {
       model = await this.loadModel(workspaceId);
     } catch {
-      return { groups: [], people: [] };
+      return { plugins: [], people: [] };
     }
-    // Groups = the built-in `everyone` role plus every declared role's display
+    // Plugins = the built-in `everyone` role plus every declared role's display
     // name. `everyone` is surfaced so the share UI can grant public read; the
     // grant route gates it to the `read` verb only (write/owner/download
     // everyone stay a direct-access.md edit).
-    const groups = [
+    const plugins = [
       EVERYONE_DISPLAY,
       ...[...model.roles.byCanonical.values()].map((r) => r.displayName),
     ];
@@ -1487,7 +1487,7 @@ export class AccessControlService implements IAccessControl {
       name: name || email.split('@')[0],
       email,
     }));
-    return { groups, people };
+    return { plugins, people };
   }
 
   async findEmailByHash(

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

@@ -14,9 +14,9 @@ import {
  * WHERE access rules are DECLARED inside a folder — a read-only inventory, not
  * a second resolver.
  *
- * A group's `access.md` is never the whole story: resolution is closeness-first,
+ * A plugin's `access.md` is never the whole story: resolution is closeness-first,
  * so a rule written on a single skill or `.tool` inside the folder overrides the
- * folder's rule for the principals it names. An admin looking at a group's share
+ * folder's rule for the principals it names. An admin looking at a plugin's share
  * list and seeing "GTM Team can read" would otherwise have no way to know that
  * one battlecard underneath says `deny read: everyone`.
  *
@@ -66,9 +66,9 @@ export interface AccessDeclaration {
 }
 
 /**
- * How many files one scan will read. A group folder is small by construction;
+ * How many files one scan will read. A plugin folder is small by construction;
  * this cap exists so a pathological folder (a whole ontology moved under
- * `Groups/`) degrades into an honest partial answer instead of pinning the
+ * `Plugins/`) degrades into an honest partial answer instead of pinning the
  * event loop. Callers surface `truncated` to the user.
  */
 export const DECLARATION_SCAN_FILE_CAP = 400;
@@ -163,7 +163,7 @@ function toEntries(byVerb: Record<Verb, ParsedEntry[]>): DeclarationEntry[] {
  *
  * Failure modes are asymmetric on purpose, matching the resolver: a node whose
  * frontmatter is malformed is skipped silently (a typo in a skill's `owner:`
- * must not make the group's access page unreadable), while a malformed
+ * must not make the plugin's access page unreadable), while a malformed
  * `access.md` is REPORTED with its `parseError` (that file was written to
  * control access and currently controls nothing).
  *