@bevel-software/platform-core-backend 0.10.0 → 0.11.0

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

@@ -0,0 +1,288 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import type { FileTreeEntry, IWorkspaceService } from '@bevel-software/platform-shared';
+import {
+  KbReferenceScanner,
+  findRoleRefsInText,
+  rewriteRoleTokensInText,
+} from '../reference-scan.js';
+
+/**
+ * Unit tests for the shared reference scanner's parse rules (comments,
+ * nested-mapping verb keys) and its candidate/freshness machinery (`.tool`
+ * frontmatter coverage, event-bus cache invalidation).
+ */
+
+describe('findRoleRefsInText / rewriteRoleTokensInText — comment handling', () => {
+  it('a trailing comment is stripped for MATCHING (the resolver’s rule)', () => {
+    const md = '---\nread:\n  - GTM Team  # sales folks\n---\n';
+    // The token is `gtm team`, never `gtm team # sales folks`.
+    expect(findRoleRefsInText(md)).toEqual([{ role: 'gtm team', verb: 'read' }]);
+  });
+
+  it('a trailing comment is PRESERVED by the rewrite', () => {
+    const md = '---\nread:\n  - GTM Team  # sales folks\nwrite:\n  - deny GTM Team # blocked\n---\n';
+    const out = rewriteRoleTokensInText(md, 'gtm team', 'Go To Market');
+    expect(out).toContain('  - Go To Market  # sales folks');
+    expect(out).toContain('  - deny Go To Market # blocked');
+  });
+
+  it('an inline scalar with a trailing comment matches and rewrites (comment kept)', () => {
+    const md = '---\nowner: Sales # the owning team\n---\n';
+    expect(findRoleRefsInText(md)).toEqual([{ role: 'sales', verb: 'owner' }]);
+    const out = rewriteRoleTokensInText(md, 'sales', 'Revenue');
+    expect(out).toContain('owner: Revenue # the owning team');
+  });
+
+  it('a full-line comment inside a block neither ends the block nor is an entry', () => {
+    const md = '---\nread:\n  - Sales\n  # a note between items\n  - Support\n---\n';
+    expect(findRoleRefsInText(md)).toEqual([
+      { role: 'sales', verb: 'read' },
+      { role: 'support', verb: 'read' },
+    ]);
+  });
+
+  it('a verb key whose value is only a comment is not a reference', () => {
+    const md = '---\nread:  # to be filled in\n  - Sales\n---\n';
+    expect(findRoleRefsInText(md)).toEqual([{ role: 'sales', verb: 'read' }]);
+  });
+});
+
+describe('findRoleRefsInText / rewriteRoleTokensInText — nested-mapping verb keys are not rules', () => {
+  // The resolver only parses verbs at the rule mapping's ROOT (indent 0) —
+  // an indented `read:` inside some unrelated config mapping must never be
+  // scanned as a rule or rewritten during a rename.
+  const md = [
+    '---',
+    'read:',
+    '  - Sales',
+    'someConfig:',
+    '  nested:',
+    '    read:',
+    '      - Sales',
+    '---',
+    '',
+  ].join('\n');
+
+  it('scan skips the nested verb-looking key’s items', () => {
+    expect(findRoleRefsInText(md)).toEqual([{ role: 'sales', verb: 'read' }]);
+  });
+
+  it('rename rewrites only the root-level rule, never the nested config', () => {
+    const out = rewriteRoleTokensInText(md, 'sales', 'Revenue');
+    const lines = out.split('\n');
+    expect(lines).toContain('  - Revenue'); // the real rule, rewritten
+    expect(lines).toContain('      - Sales'); // the nested config, untouched
+  });
+});
+
+describe('findRoleRefsInText / rewriteRoleTokensInText — indented ROOT mappings are live rules', () => {
+  // The resolver's YAML-subset parser accepts a root mapping at ANY indent
+  // (its root frame sits at indent -1), so `  read:` at column 2 with nothing
+  // enclosing it is a rule the resolver ENFORCES. A column-zero-only scanner
+  // would skip it — and a rename would strand the live grant.
+  const md = ['---', '  read:', '    - Sales', '---', ''].join('\n');
+
+  it('scan sees a uniformly-indented root verb key', () => {
+    expect(findRoleRefsInText(md)).toEqual([{ role: 'sales', verb: 'read' }]);
+  });
+
+  it('rename rewrites the indented root rule, preserving indentation', () => {
+    const out = rewriteRoleTokensInText(md, 'sales', 'Revenue');
+    expect(out.split('\n')).toContain('    - Revenue');
+    expect(out).not.toContain('Sales');
+  });
+
+  it('an indented root inline scalar matches and rewrites', () => {
+    const scalar = '---\n  owner: Sales # team\n---\n';
+    expect(findRoleRefsInText(scalar)).toEqual([{ role: 'sales', verb: 'owner' }]);
+    expect(rewriteRoleTokensInText(scalar, 'sales', 'Revenue')).toContain(
+      '  owner: Revenue # team',
+    );
+  });
+
+  it('a verb key nested under an INDENTED root mapping is still not a rule', () => {
+    // `config:` owns the root at indent 2; `read:` at indent 4 is ITS nested
+    // key, not a root verb — the resolver never parses it as a rule.
+    const nested = ['---', '  config:', '    read:', '      - Sales', '---', ''].join('\n');
+    expect(findRoleRefsInText(nested)).toEqual([]);
+    expect(rewriteRoleTokensInText(nested, 'sales', 'Revenue')).toBe(nested);
+  });
+
+  it('a structurally-broken region (the resolver rejects it) yields no refs and no rewrites', () => {
+    // `- Sales` at the SAME indent as its key is a parse error to the subset
+    // parser ("list item with no enclosing list") — the resolver enforces
+    // nothing from this file, so the scan must not report a live grant.
+    const broken = '---\nread:\n- Sales\n---\n';
+    expect(findRoleRefsInText(broken)).toEqual([]);
+    expect(rewriteRoleTokensInText(broken, 'sales', 'Revenue')).toBe(broken);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// KbReferenceScanner — candidates + freshness
+// ---------------------------------------------------------------------------
+
+const KB = 'knowledge-base';
+
+function stubWorkspace(workspaceDir: string): IWorkspaceService {
+  const buildTree = async (absDir: string): Promise<FileTreeEntry> => {
+    const rel = path.relative(workspaceDir, absDir).replace(/\\/g, '/');
+    const children: FileTreeEntry[] = [];
+    for (const e of await fs.readdir(absDir, { withFileTypes: true })) {
+      if (e.name === '.git') continue;
+      const childAbs = path.join(absDir, e.name);
+      if (e.isDirectory()) children.push(await buildTree(childAbs));
+      else if (e.isFile()) {
+        children.push({
+          name: e.name,
+          relativePath: path.relative(workspaceDir, childAbs).replace(/\\/g, '/'),
+          type: 'file',
+        });
+      }
+    }
+    return { name: path.basename(absDir), relativePath: rel || '.', type: 'directory', children };
+  };
+  return {
+    getWorkspacePath: async () => workspaceDir,
+    listFiles: async () => buildTree(workspaceDir),
+  } as unknown as IWorkspaceService;
+}
+
+async function write(repo: string, rel: string, contents: string): Promise<void> {
+  const abs = path.join(repo, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, contents);
+}
+
+describe('KbReferenceScanner — .tool frontmatter is scanned and rewritten like .md', () => {
+  it('finds a .tool frontmatter grant and a rename rewrites it (body untouched)', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-'));
+    try {
+      const repo = path.join(root, KB);
+      const toolBody = 'name: crm\ntype: mcp\n# not frontmatter below\n';
+      await write(repo, 'Plugins/GTM/crm.tool', `---\nread:\n  - GTM Team\n---\n${toolBody}`);
+      await write(repo, 'Plugins/GTM/notes.md', '---\nowner: GTM Team\n---\n# notes\n');
+      const scanner = new KbReferenceScanner(stubWorkspace(root), KB);
+
+      const byToken = await scanner.scan('ws-1');
+      const hits = (byToken.get('gtm team') ?? []).map((h) => h.path).sort();
+      expect(hits).toEqual(['Plugins/GTM/crm.tool', 'Plugins/GTM/notes.md']);
+
+      const writes = await scanner.rewriteReferences('ws-1', 'gtm team', 'Go To Market', (m) => new Error(m));
+      const toolWrite = writes.find((w) => w.repoRelativePath === 'Plugins/GTM/crm.tool')!;
+      expect(toolWrite.content).toContain('  - Go To Market');
+      // The .tool body below the frontmatter is byte-for-byte intact.
+      expect(toolWrite.content).toContain(toolBody);
+      expect(writes.some((w) => w.repoRelativePath === 'Plugins/GTM/notes.md')).toBe(true);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('KbReferenceScanner — event-bus cache invalidation', () => {
+  it('drops the cached scan when a scanned-extension file changes in the workspace', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-bus-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      const listeners: ((e: { kind: string; workspaceId?: string; path?: string }) => void)[] = [];
+      const bus = { onEmit: (l: (typeof listeners)[number]) => (listeners.push(l), () => undefined) };
+      const scanner = new KbReferenceScanner(stubWorkspace(root), KB, bus);
+
+      expect((await scanner.scan('ws-1')).get('sales')).toHaveLength(1);
+
+      // A grant lands through the share dialog (outside the admin services):
+      // the write itself, then its file-changed event.
+      await write(repo, 'team/access.md', '---\nread:\n  - Sales\n  - Support\n---\n');
+      // Without invalidation the cached scan (30s TTL) would still miss Support.
+      expect((await scanner.scan('ws-1')).get('support')).toBeUndefined();
+
+      for (const l of listeners) {
+        l({ kind: 'file-changed', workspaceId: 'ws-1', path: `${KB}/team/access.md` });
+      }
+      expect((await scanner.scan('ws-1')).get('support')).toHaveLength(1);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('an invalidation landing MID-SCAN keeps the stale snapshot out of the cache', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-race-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      // The workspace stub invalidates DURING the first scan's tree listing —
+      // modelling a write that lands after the scan started reading.
+      const base = stubWorkspace(root);
+      let armed = true;
+      const ws = {
+        ...base,
+        listFiles: async (id: string) => {
+          const tree = await base.listFiles(id);
+          if (armed) {
+            armed = false;
+            scanner.invalidate('ws-1');
+          }
+          return tree;
+        },
+      } as unknown as IWorkspaceService;
+      const scanner = new KbReferenceScanner(ws, KB);
+
+      // The caller still gets the snapshot it asked for...
+      expect((await scanner.scan('ws-1')).get('sales')).toHaveLength(1);
+      // ...but the snapshot must not have STUCK in the cache: the write the
+      // invalidation announced is visible on the very next scan, well inside
+      // the TTL and with no further events.
+      await write(repo, 'team/access.md', '---\nread:\n  - Sales\n  - Support\n---\n');
+      expect((await scanner.scan('ws-1')).get('support')).toHaveLength(1);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('ignores a scanned-extension change OUTSIDE the KB directory', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-bus3-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      const listeners: ((e: { kind: string; workspaceId?: string; path?: string }) => void)[] = [];
+      const bus = { onEmit: (l: (typeof listeners)[number]) => (listeners.push(l), () => undefined) };
+      const scanner = new KbReferenceScanner(stubWorkspace(root), KB, bus);
+
+      const first = await scanner.scan('ws-1');
+      for (const l of listeners) {
+        // Right extension, wrong tree: not scan material.
+        l({ kind: 'file-changed', workspaceId: 'ws-1', path: 'scratch/notes.md' });
+      }
+      expect(await scanner.scan('ws-1')).toBe(first);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('ignores events for non-scanned extensions and other kinds', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-bus2-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      const listeners: ((e: { kind: string; workspaceId?: string; path?: string }) => void)[] = [];
+      const bus = { onEmit: (l: (typeof listeners)[number]) => (listeners.push(l), () => undefined) };
+      const scanner = new KbReferenceScanner(stubWorkspace(root), KB, bus);
+
+      const first = await scanner.scan('ws-1');
+      for (const l of listeners) {
+        l({ kind: 'file-changed', workspaceId: 'ws-1', path: `${KB}/roles.yaml` });
+        l({ kind: 'fs-tree-changed', workspaceId: 'ws-1' });
+      }
+      // Cache retained — same map instance served.
+      expect(await scanner.scan('ws-1')).toBe(first);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -9,7 +9,9 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { FileTreeEntry, WorkflowEventPayload } from '@bevel-software/platform-shared';
 import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
-import { RolesAdminService, rewriteRoleTokensInText, findRoleRefsInText } from '../roles-admin.service.js';
+import { RolesAdminService } from '../roles-admin.service.js';
+import { rewriteRoleTokensInText, findRoleRefsInText } from '../reference-scan.js';
+import { PushNeedsAgentResolutionError } from '../../workflow/workflow.errors.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 
@@ -89,24 +91,30 @@ function stubWorkspace(workspaceDir: string): WorkspaceService {
 function stubWorkflow() {
   const commits: { summary: string }[] = [];
   const resets: string[] = [];
-  /** Current holder of the roles.yaml lock, or null. */
-  let holder: AuthUser | null = null;
+  /** Per-path lock rows with STRICT acquire — mirrors FileLockService: a
+   *  live lock is contended EVEN FOR THE SAME USER (only expired rows are
+   *  reclaimed), so a service nesting a second acquire under its own hold
+   *  fails here exactly like production. */
+  const locks = new Map<string, AuthUser>();
   const lockRow = (h: AuthUser) => ({ holderUserId: h.id, holderName: h.name });
   const svc = {
-    getLock: async () => (holder ? lockRow(holder) : null),
-    acquireLock: async (...a: unknown[]) => {
-      const user = a[3] as AuthUser;
-      return holder && holder.id !== user.id
-        ? { acquired: false, lock: lockRow(holder) }
-        : ((holder = user), { acquired: true, lock: lockRow(user) });
+    getLock: async (_w: string, _b: string, p: string) => {
+      const h = locks.get(p);
+      return h ? lockRow(h) : null;
+    },
+    acquireLock: async (_w: string, _b: string, p: string, user: AuthUser) => {
+      const h = locks.get(p);
+      if (h) return { acquired: false, lock: lockRow(h) };
+      locks.set(p, user);
+      return { acquired: true, lock: lockRow(user) };
     },
     // LockingFilesystem's success path: the LocalFilesystem write already hit
     // disk, so releasing just drops the lock (the "commit" is a no-op in-memory).
-    releaseLock: async () => {
-      holder = null;
+    releaseLock: async (_w: string, _b: string, p: string) => {
+      locks.delete(p);
     },
-    releaseLockNoCommit: async () => {
-      holder = null;
+    releaseLockNoCommit: async (_w: string, _b: string, p: string) => {
+      locks.delete(p);
     },
     // The rename's atomic batch flows through LockingFilesystem.writeFiles, which
     // writes every file to disk (real LocalFilesystem) then calls commitChanges
@@ -237,8 +245,10 @@ describe('RolesAdminService', () => {
     await write(repo, 'roles.yaml', corrupt);
     access.invalidate(WS);
     const adminless = new RolesAdminService(ws, workflow.svc, access, KB, () => DEFAULT_BRANCH, bus.bus);
+    // 409, not 500: the route helper hides >=500 bodies behind a generic
+    // message, and this break-glass refusal must reach the operator verbatim.
     await expect(adminless.recover(ADMIN)).rejects.toMatchObject({
-      status: 500,
+      status: 409,
       payload: { kind: 'no-recovery-admins' },
     });
     // Nothing parked, nothing overwritten.
@@ -292,42 +302,29 @@ describe('RolesAdminService', () => {
     expect(await readRoles()).not.toContain('juan@bevel.software');
   });
 
-  it('createRole rejects reserved/duplicate; deleteRole refuses Admin', async () => {
-    await expect(svc.createRole(ADMIN, 'everyone')).rejects.toMatchObject({ status: 422 });
-    await expect(svc.createRole(ADMIN, 'Sales')).rejects.toMatchObject({ status: 422 });
-    await expect(svc.deleteRole(ADMIN, 'admin')).rejects.toMatchObject({ status: 422 });
-    await svc.createRole(ADMIN, 'Marketing');
-    expect(await readRoles()).toContain('Marketing: []');
-  });
-
-  it('rename: Admin canonical change is refused (400); casing-only allowed', async () => {
-    await expect(svc.renameRole(ADMIN, 'admin', 'Administrators')).rejects.toMatchObject({ status: 400 });
-    await svc.renameRole(ADMIN, 'admin', 'ADMIN'); // casing-only OK
-    const roster = await svc.getRoster();
-    expect(roster.find((r) => r.canonical === 'admin')!.displayName).toBe('ADMIN');
+  it('role CRUD is GONE from the service — roles are app-defined capabilities', () => {
+    // The editors were removed outright, not just un-routed: legacy roles stay
+    // membership-editable, but nothing can mint/rename/delete a role anymore.
+    const anySvc = svc as unknown as Record<string, unknown>;
+    expect(anySvc.createRole).toBeUndefined();
+    expect(anySvc.renameRole).toBeUndefined();
+    expect(anySvc.deleteRole).toBeUndefined();
   });
 
-  it('rename (identity change) rewrites access.md AND node frontmatter in ONE commit', async () => {
-    await write(repo, 'Sales/access.md', `---\nwrite:\n  - Sales\n  - Other Team\n---\n# Sales folder\n`);
-    await write(repo, 'Sales/Deal.md', `---\nowner: Sales\n---\n# A deal\n`);
-    access.invalidate(WS);
-    const commitsBefore = workflow.commits.length;
-
-    await svc.renameRole(ADMIN, 'sales', 'Sales Team');
-
-    // roles.yaml + both referencing files, all in a single commit (verified by
-    // commits.length += 1; the per-file content is asserted on disk below).
-    expect(workflow.commits.length).toBe(commitsBefore + 1);
-    expect(await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8')).toContain('- Sales Team');
-    expect(await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8')).toContain('- Other Team'); // untouched
-    expect(await fs.readFile(path.join(repo, 'Sales/Deal.md'), 'utf-8')).toContain('owner: Sales Team');
-    expect(await readRoles()).toContain('Sales Team:');
+  it("addMember refuses a 'group:'-prefixed member with an actionable message", async () => {
+    await expect(svc.addMember(ADMIN, 'sales', 'group:lee@x.io')).rejects.toMatchObject({
+      status: 422,
+    });
+    await expect(svc.addMember(ADMIN, 'sales', 'group:gtm team')).rejects.toThrow(/group assignment/);
+    expect(await readRoles()).not.toContain('group:');
   });
 
   it('LOCKOUT-IMPOSSIBILITY: the validator rejects garbage in isolation', async () => {
     expect(access.validateRolesYaml('roles:\n  : []\n').ok).toBe(false);
+    // Group-only Admin is garbage too — the kept invariant.
+    expect(access.validateRolesYaml('roles:\n  Admin:\n    - group:ops\n').ok).toBe(false);
     // Happy path still keeps admins resolving (sanity baseline for the gate).
-    await svc.createRole(ADMIN, 'Marketing');
+    await svc.addMember(ADMIN, 'sales', 'marketing@example.com');
     expect(await access.canWrite(WS, 'razvan@bevel.software', 'roles.yaml')).toBe(true);
   });
 
@@ -342,7 +339,7 @@ describe('RolesAdminService', () => {
     const realValidate = access.validateRolesYaml.bind(access);
     access.validateRolesYaml = () => ({ ok: false, errors: ['forced parse failure'] });
     try {
-      await expect(svc.createRole(ADMIN, 'Marketing')).rejects.toMatchObject({ status: 422 });
+      await expect(svc.addMember(ADMIN, 'sales', 'x@example.com')).rejects.toMatchObject({ status: 422 });
     } finally {
       access.validateRolesYaml = realValidate;
     }
@@ -351,31 +348,30 @@ describe('RolesAdminService', () => {
     expect(await access.canWrite(WS, 'razvan@bevel.software', 'roles.yaml')).toBe(true);
   });
 
-  it('rename fails closed when a candidate cannot be read (no partial rewrite)', async () => {
-    // A referenced file that the rewrite cannot read must abort the WHOLE atomic
-    // rename — committing roles.yaml + the readable files while silently skipping
-    // the unreadable one would leave a half-renamed role pointing at the old name
-    // (lost access). Assert: the op throws, nothing is committed, roles.yaml is
-    // unchanged, and the role keeps its old identity.
-    await write(repo, 'Sales/access.md', `---\nwrite:\n  - Sales\n---\n# Sales\n`);
-    access.invalidate(WS);
-    const before = await readRoles();
-    const commitsBefore = workflow.commits.length;
-    // Point the candidate list at a path that does not exist on disk, so the
-    // rewrite's readFile throws and the fail-closed guard fires.
-    (ws as unknown as { listFiles: () => Promise<FileTreeEntry> }).listFiles = async () => ({
-      name: WS,
-      relativePath: '.',
-      type: 'directory',
-      children: [
-        { name: 'does-not-exist.md', relativePath: `${KB}/Sales/does-not-exist.md`, type: 'file' },
-      ],
+  it('a post-commit push failure does NOT revert the landed edit (saved; retried later)', async () => {
+    // workflowService.commitChanges throwing PushNeedsAgentResolutionError
+    // means the COMMIT landed and only the push needs help. The old twins
+    // restored pre-edit bytes here — publishing a compensating revert of a
+    // landed commit. The shared helper must keep the new bytes and surface
+    // the typed 409 as-is.
+    const failing = workflow.svc as unknown as {
+      commitChanges: (...args: unknown[]) => Promise<unknown>;
+    };
+    const realCommit = failing.commitChanges.bind(workflow.svc);
+    failing.commitChanges = async (...args: unknown[]) => {
+      await realCommit(...args); // the commit records — it "landed"
+      throw new PushNeedsAgentResolutionError(DEFAULT_BRANCH, 'roles.yaml', 'rejected', 'conflict');
+    };
+    await expect(svc.addMember(ADMIN, 'sales', 'pushed@example.com')).rejects.toMatchObject({
+      status: 409,
+      payload: { kind: 'push-needs-resolution' },
     });
-
-    await expect(svc.renameRole(ADMIN, 'sales', 'Sales Team')).rejects.toMatchObject({ status: 422 });
-
-    expect(workflow.commits.length).toBe(commitsBefore); // nothing committed
-    expect(await readRoles()).toBe(before); // roles.yaml untouched — role keeps old identity
+    // The edit SURVIVES on disk — no compensating restore of pre-edit bytes.
+    expect(await readRoles()).toContain('pushed@example.com');
+    // And the lock was released normally (a follow-up edit works).
+    failing.commitChanges = realCommit;
+    await svc.addMember(ADMIN, 'sales', 'after@example.com');
+    expect(await readRoles()).toContain('after@example.com');
   });
 
   it('concurrent edit is serialized — a mutation 409s while another admin holds the lock', async () => {
@@ -399,21 +395,6 @@ describe('RolesAdminService', () => {
     expect(bus.events).toHaveLength(0);
   });
 
-  it('rename emits file-changed for EVERY rewritten file (roles.yaml + refs)', async () => {
-    await write(repo, 'Sales/access.md', `---\nwrite:\n  - Sales\n---\n# Sales\n`);
-    await write(repo, 'Sales/Deal.md', `---\nowner: Sales\n---\n# A deal\n`);
-    access.invalidate(WS);
-
-    await svc.renameRole(ADMIN, 'sales', 'Sales Team');
-
-    const paths = bus.events
-      .filter((e) => e.kind === 'file-changed')
-      .map((e) => (e as { path: string }).path)
-      .sort();
-    expect(paths).toEqual(
-      [`${KB}/roles.yaml`, `${KB}/Sales/access.md`, `${KB}/Sales/Deal.md`].sort(),
-    );
-  });
 });
 
 describe('rewriteRoleTokensInText (reference-aware, frontmatter-only)', () => {
@@ -476,6 +457,57 @@ describe('rewriteRoleTokensInText (reference-aware, frontmatter-only)', () => {
   });
 });
 
+describe('rewriteRoleTokensInText — body-governed access.md (isAccessMd)', () => {
+  it('rewrites BODY rules and frontmatter self-rules of a body-governed access.md', () => {
+    const text = [
+      '---',
+      'write:',
+      '  - Sales', // self-rule: who may edit access.md itself
+      '---',
+      'read:',
+      '  - Sales', // the FOLDER rule the resolver enforces
+      '  - deny Sales',
+      'write:',
+      '  - Admin',
+    ].join('\n');
+    const out = rewriteRoleTokensInText(text, 'sales', 'Sales Team', true, true);
+    const lines = out.split('\n');
+    expect(lines[2]).toBe('  - Sales Team'); // frontmatter self-rule
+    expect(lines[5]).toBe('  - Sales Team'); // body rule
+    expect(lines[6]).toBe('  - deny Sales Team'); // deny preserved in body
+    expect(out).toContain('  - Admin'); // other roles untouched
+  });
+
+  it('a LEGACY access.md (prose body) keeps its body untouched even with isAccessMd', () => {
+    const text = [
+      '---',
+      'read:',
+      '  - Sales',
+      '---',
+      '# About this folder',
+      '- Sales', // prose bullet, not a rule — the body does not parse as rules
+    ].join('\n');
+    const out = rewriteRoleTokensInText(text, 'sales', 'Sales Team', true, true);
+    const lines = out.split('\n');
+    expect(lines[2]).toBe('  - Sales Team'); // legacy frontmatter rules rewritten
+    expect(lines[5]).toBe('- Sales'); // prose untouched
+  });
+
+  it('a fence-less access.md is untouched — the resolver hard-errors it, so it is no rule source', () => {
+    const text = 'read:\n  - Sales\n';
+    expect(rewriteRoleTokensInText(text, 'sales', 'Sales Team', true, true)).toBe(text);
+  });
+
+  it('findRoleRefsInText sees body rules of a body-governed access.md', () => {
+    const text = ['---', 'write:', '  - Admin', '---', 'read:', '  - Sales'].join('\n');
+    const refs = findRoleRefsInText(text, true, true);
+    expect(refs).toContainEqual({ role: 'sales', verb: 'read' });
+    expect(refs).toContainEqual({ role: 'admin', verb: 'write' });
+    // Without the access.md flag the body stays invisible (node files, prose).
+    expect(findRoleRefsInText(text, true, false)).not.toContainEqual({ role: 'sales', verb: 'read' });
+  });
+});
+
 describe('findRoleRefsInText (sound reference scan — shared with the rewrite)', () => {
   it('reports every genuine role ref with its enclosing verb, ignoring users/prose', () => {
     const text = [
@@ -501,3 +533,49 @@ describe('findRoleRefsInText (sound reference scan — shared with the rewrite)'
     expect(findRoleRefsInText('# Doc\nread:\n  - Sales\n')).toEqual([]);
   });
 });
+
+describe('roster referencedBy under group shadowing', () => {
+  let root: string;
+  let repo: string;
+  let svc: RolesAdminService;
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+    const workspaceDir = path.join(root, WS);
+    repo = path.join(workspaceDir, KB);
+    await write(repo, 'roles.yaml', ROLES);
+    const ws = stubWorkspace(workspaceDir);
+    svc = new RolesAdminService(
+      ws,
+      stubWorkflow().svc,
+      new AccessControlService(ws, KB),
+      KB,
+      () => DEFAULT_BRANCH,
+      stubEventBus().bus,
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('a bare-token hit is the GROUP’s when a group shadows the role name; role/<name> hits stay the role’s', async () => {
+    // A group named Sales shadows the Sales role: bare tokens resolve to the
+    // GROUP, so the roles roster must not claim them as role references.
+    await write(repo, 'groups.yaml', 'groups:\n  Sales:\n    - pat@x.io\n');
+    await write(repo, 'team/access.md', '---\nread:\n  - Sales\nwrite:\n  - role/Sales\n---\n');
+
+    const sales = (await svc.getRoster()).find((r) => r.canonical === 'sales')!;
+    // Only the explicit spelling counts for the ROLE.
+    expect(sales.referencedBy).toEqual([{ path: 'team/access.md', verb: 'write' }]);
+  });
+
+  it('unshadowed: bare hits still count for the role (both spellings)', async () => {
+    await write(repo, 'team/access.md', '---\nread:\n  - Sales\nwrite:\n  - role/Sales\n---\n');
+    const sales = (await svc.getRoster()).find((r) => r.canonical === 'sales')!;
+    expect(sales.referencedBy).toEqual([
+      { path: 'team/access.md', verb: 'read' },
+      { path: 'team/access.md', verb: 'write' },
+    ]);
+  });
+});