fix(plugin-security): stop clobbering admin-edited capability scope (#2909 T3)

scope is an admin-editable classification select on sys_capability, but the
curated seeder refreshed it every boot — silently reverting admin
reclassifications. Make it seed-once (insert only); label/description remain
platform-owned and keep refreshing. Lock both sides with tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017bJWtKmZ2mFpRFAmmmoeqe

Author: claude

.changeset/security-2909-capability-scope.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/plugin-security': patch
+---
+
+fix(plugin-security): stop clobbering admin-edited capability `scope` on boot (#2909 T3). `scope` is an admin-editable classification select on sys_capability, but the curated seeder refreshed it on every boot alongside label/description — silently reverting admin reclassifications. It is now seed-once: written on insert, never refreshed (a curated scope change in a new platform version requires a data migration; recorded in the ADR-0094 addendum).

packages/plugins/plugin-security/src/bootstrap-system-capabilities.test.ts

@@ -65,6 +65,29 @@ describe('bootstrapSystemCapabilities (ADR-0066 D1 back-compat seed)', () => {
     expect(ql.rows.find((x: any) => x.name === 'approve_invoice')).toBeDefined();
   });
 
+  // [#2909 T3] `scope` is an admin-editable classification face — seed-once.
+  it('does NOT clobber an admin-edited scope on re-seed (label/description still refresh)', async () => {
+    const ql = makeQl();
+    await bootstrapSystemCapabilities(ql, []);
+    const cap = KNOWN_CAPABILITIES[0];
+    const row = ql.rows.find((x) => x.name === cap.name)!;
+    // Admin reclassifies the capability and tweaks nothing else.
+    row.scope = row.scope === 'org' ? 'platform' : 'org';
+    const adminScope = row.scope;
+    row.label = 'stale label';
+    await bootstrapSystemCapabilities(ql, []);
+    expect(row.scope).toBe(adminScope); // admin's edit survives the boot
+    expect(row.label).toBe(cap.label); // platform display fields refreshed
+  });
+
+  it('still writes scope on first insert', async () => {
+    const ql = makeQl();
+    await bootstrapSystemCapabilities(ql, []);
+    for (const cap of KNOWN_CAPABILITIES) {
+      expect(ql.rows.find((x) => x.name === cap.name)?.scope).toBe(cap.scope);
+    }
+  });
+
   it('marks manage_org_users as org-scoped and the rest platform', () => {
     const org = KNOWN_CAPABILITIES.find((c) => c.name === 'manage_org_users');
     expect(org?.scope).toBe('org');

packages/plugins/plugin-security/src/bootstrap-system-capabilities.ts

@@ -100,9 +100,13 @@ export async function bootstrapSystemCapabilities(
   for (const def of byName.values()) {
     const existing = await tryFind(ql, 'sys_capability', { name: def.name }, 1);
     if (existing[0]?.id) {
-      // Keep label/description/scope fresh, but do NOT clobber admin edits to
-      // managed_by/active — only platform-owned fields are reconciled.
-      if (await tryUpdate(ql, 'sys_capability', { id: existing[0].id, label: def.label, description: def.description, scope: def.scope })) {
+      // Keep label/description fresh, but do NOT clobber admin edits — only
+      // platform-owned display fields are reconciled. `scope` is an
+      // admin-editable classification face (plain select on sys_capability),
+      // so it is seed-once: written on insert, never refreshed (#2909 T3).
+      // A curated scope change in a new platform version needs a data
+      // migration — recorded in the ADR-0094 addendum.
+      if (await tryUpdate(ql, 'sys_capability', { id: existing[0].id, label: def.label, description: def.description })) {
         updated += 1;
       }
     } else {