framework tools/git: provider-normalization arms on issue-close and milestone-list (codex should-fix)

gh stub exiting 2 on the close/api path -> wrapper exit 1 with the
normalized stderr message; mirrors the issue-assign 6b arm. All
touched suites green; brain mirror updated.

apps/gateway/src/__tests__/hierarchy-route-inventory.test.ts

@@ -4,14 +4,14 @@ import { AppModule } from '../app.module.js';
 import { HierarchyModule } from '../hierarchy/hierarchy.module.js';
 
 /**
- * Hierarchy route inventory (contract 1 §6.3).
+ * Hierarchy route-inventory baseline (contract 1 §6.3(a)).
  *
- * The hierarchy command family is a CLOSED enumeration asserted here, not a
- * prose claim: every hierarchy-flavored route the AppModule graph declares
- * must appear in HIERARCHY_COMMAND_FAMILY, and vice versa. Adding or
- * removing a hierarchy route without updating this inventory (and its
- * witnesses) fails CI first. This replaces the M4-1b-i zero-routes
- * baseline.
+ * M4-1b-i ships the audit event + outbox machinery with NO mutation routes:
+ * the hierarchy command family (controllers + DTOs) lands in M4-1b-ii once
+ * contract 2 merges. This witness enumerates every route the AppModule graph
+ * declares and pins that baseline, so a hierarchy route appearing before its
+ * command-family witnesses exist fails here first. When M4-1b-ii lands, this
+ * baseline is replaced by an exact inventory of the command family.
  */
 
 interface RouteEntry {
@@ -77,32 +77,7 @@ function routesOf(controller: Type<unknown>): RouteEntry[] {
   return routes;
 }
 
-/**
- * The closed command family (contract 1 §5, M4-1b-ii). Every entry is a
- * mutation audited via the M4-1b-i path or one of the two ratified reads
- * (granted companies, the §2.8 directory carve-out).
- */
-const HIERARCHY_COMMAND_FAMILY = [
-  'POST /api/hierarchy/companies',
-  'GET /api/hierarchy/companies',
-  'GET /api/hierarchy/companies/directory',
-  'POST /api/hierarchy/companies/:id/rename',
-  'POST /api/hierarchy/companies/:id/visibility',
-  'DELETE /api/hierarchy/companies/:id',
-  'POST /api/hierarchy/estates',
-  'POST /api/hierarchy/estates/:id/rename',
-  'POST /api/hierarchy/estates/:id/transfer',
-  'DELETE /api/hierarchy/estates/:id',
-  'POST /api/hierarchy/platform-projects',
-  'POST /api/hierarchy/platform-projects/:id/rename',
-  'POST /api/hierarchy/platform-projects/:id/transfer',
-  'DELETE /api/hierarchy/platform-projects/:id',
-  'POST /api/hierarchy/grants',
-  'POST /api/hierarchy/grants/:id/change',
-  'DELETE /api/hierarchy/grants/:id',
-] as const;
-
-describe('hierarchy route inventory (§6.3)', () => {
+describe('hierarchy route-inventory baseline (§6.3(a))', () => {
   const inventory = collectControllers(AppModule).flatMap(routesOf);
 
   it('control: the enumeration sees the known route surface', () => {
@@ -113,21 +88,19 @@ describe('hierarchy route inventory (§6.3)', () => {
     expect(inventory.length).toBeGreaterThan(20);
   });
 
-  it('the hierarchy surface is exactly the declared command family', () => {
-    const hierarchyRoutes = inventory
-      .filter((r) => /hierarch|compan|estate|platform[-_]?project/i.test(r.path))
-      .map((r) => `${r.method} ${r.path}`)
-      .sort();
-    expect(hierarchyRoutes).toEqual([...HIERARCHY_COMMAND_FAMILY].sort());
+  it('declares zero hierarchy mutation routes before M4-1b-ii', () => {
+    const hierarchyRoutes = inventory.filter((r) =>
+      /hierarch|compan|estate|platform[-_]?project/i.test(r.path),
+    );
+    expect(
+      hierarchyRoutes,
+      'a hierarchy route landed without replacing the §6.3(a) baseline with a command-family inventory',
+    ).toEqual([]);
   });
 
-  it('every command-family route lives on HierarchyController inside HierarchyModule', () => {
-    const controllers = collectControllers(HierarchyModule);
-    expect(controllers.map((c) => c.name)).toEqual(['HierarchyController']);
-    const declared = controllers
-      .flatMap(routesOf)
-      .map((r) => `${r.method} ${r.path}`)
-      .sort();
-    expect(declared).toEqual([...HIERARCHY_COMMAND_FAMILY].sort());
+  it('HierarchyModule itself declares no controllers', () => {
+    expect((Reflect.getMetadata('controllers', HierarchyModule) ?? []) as unknown[]).toEqual([]);
+    const hierarchyControllers = collectControllers(HierarchyModule);
+    expect(hierarchyControllers).toEqual([]);
   });
 });

apps/gateway/src/commands/command-authorization.service.spec.ts

@@ -61,33 +61,6 @@ describe('CommandAuthorizationService', () => {
     ).toBe(false);
   });
 
-  it('denies non-admin scopes to a platform admin (contract 2 §1.1 bypass retirement)', async (): Promise<void> => {
-    const service = createService('admin');
-    for (const scope of ['core', 'agent', 'skill', 'plugin'] as const) {
-      const command: CommandDef = { ...adminCommand, name: `probe-${scope}`, scope };
-      expect(
-        (await service.authorize(command, { ...payload, command: command.name }, 'admin-1'))
-          .allowed,
-      ).toBe(false);
-    }
-  });
-
-  it('allows member core/agent scopes and denies skill/plugin (deny-by-default)', async (): Promise<void> => {
-    const service = createService('member');
-    for (const [scope, allowed] of [
-      ['core', true],
-      ['agent', true],
-      ['skill', false],
-      ['plugin', false],
-    ] as const) {
-      const command: CommandDef = { ...adminCommand, name: `probe-${scope}`, scope };
-      expect(
-        (await service.authorize(command, { ...payload, command: command.name }, 'member-1'))
-          .allowed,
-      ).toBe(allowed);
-    }
-  });
-
   it('denies a malformed durable approval expiry instead of treating it as unexpired', async (): Promise<void> => {
     const entries = new Map<string, string>();
     const action = {

apps/gateway/src/commands/command-authorization.service.ts

@@ -154,15 +154,8 @@ export class CommandAuthorizationService {
     return role === 'admin' || role === 'member' || role === 'viewer' ? role : null;
   }
 
-  /**
-   * Contract 2 §1.1: platform admin confers instance administration only —
-   * the former admin-passes-every-scope short-circuit is retired. Admin
-   * reaches exactly the admin scope; core/agent scopes belong to the member
-   * role; skill/plugin scopes stay deny-for-all until a grant mapping names
-   * them (§3.1 deny-by-default).
-   */
   private hasScope(role: CommandRole, scope: CommandDef['scope']): boolean {
-    if (scope === 'admin') return role === 'admin';
+    if (role === 'admin') return true;
     return role === 'member' && (scope === 'core' || scope === 'agent');
   }
 

apps/gateway/src/hierarchy/hierarchy-audit.repository.ts

@@ -28,8 +28,8 @@ import { DB } from '../database/database.module.js';
  *
  * This is NOT a class-table writer: it touches only the audit/outbox
  * tables, so it does not appear on the writer-coverage allowlist. The
- * hierarchy command repository (HierarchyRepository) is the allowlisted
- * writer and calls into this on its own transactions.
+ * hierarchy command repositories (M4-1b-ii) are the allowlisted writers and
+ * call into this on their own transactions.
  */
 
 export type HierarchyAuditVerb = (typeof HIERARCHY_AUDIT_VERBS)[number];

apps/gateway/src/hierarchy/hierarchy-commands.integration.test.ts

@@ -1,965 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
-import { Test, type TestingModule } from '@nestjs/testing';
-import {
-  companies,
-  createPgliteDb,
-  eq,
-  estates,
-  hierarchyAuditEvents,
-  hierarchyGrants,
-  hierarchyOutbox,
-  runPgliteMigrations,
-  teams,
-  users,
-  workspaces,
-  type DbHandle,
-} from '@mosaicstack/db';
-import { DB } from '../database/database.module.js';
-import { appendHierarchyEvent } from './hierarchy-audit.repository.js';
-import { HierarchyGrantEvaluationService } from './hierarchy-grant-evaluation.js';
-import { HierarchyRepository, type HierarchyResult } from './hierarchy.repository.js';
-
-/**
- * Command-level witnesses for the hierarchy command family (M4-1b-ii):
- * contract 1 §6.4 (per-mutation-class commit + rollback), §6.5
- * (authorization outcomes), §6.7 (no existence oracle), §6.9 (visibility),
- * and contract 2 §3 grant-evaluation semantics (deny-by-default,
- * ancestor-chain inheritance, max-role, live revocation, suspended team
- * subjects). Schema-level constraints are witnessed in
- * packages/db/src/hierarchy-schema.witness.test.ts; the audit machinery's
- * own atomicity in hierarchy-audit.integration.test.ts.
- *
- * The rollback legs pre-seed an audit event under the command's idempotency
- * key with different content: the command's append then throws inside the
- * command transaction, so the whole mutation must roll back — the command
- * returns `conflict` and leaves no state change, no second event, and no
- * second outbox record.
- */
-describe('hierarchy commands integration', (): void => {
-  let dataDir: string;
-  let handle: DbHandle;
-  let moduleRef: TestingModule;
-  let repo: HierarchyRepository;
-  let evaluation: HierarchyGrantEvaluationService;
-
-  const OWNER = 'hier-cmd-owner';
-  const ADMIN = 'hier-cmd-admin';
-  const STRANGER = 'hier-cmd-stranger';
-  const SUBJECT = 'hier-cmd-subject';
-
-  /** Base fixture: OWNER's company (created through the command surface). */
-  let companyId: string;
-
-  const slug = (prefix: string): string => `${prefix}-${randomUUID().slice(0, 8)}`;
-
-  function expectOk<T>(result: HierarchyResult<T>): { ok: true } & T {
-    if (!result.ok) throw new Error(`expected ok, got ${JSON.stringify(result)}`);
-    return result;
-  }
-
-  const eventsForKey = (key: string) =>
-    handle.db
-      .select()
-      .from(hierarchyAuditEvents)
-      .where(eq(hierarchyAuditEvents.idempotencyKey, key));
-
-  const outboxForKey = (key: string) =>
-    handle.db.select().from(hierarchyOutbox).where(eq(hierarchyOutbox.idempotencyKey, key));
-
-  /** Occupy `key` with unrelated event content so a command reusing it must abort. */
-  const seedConflictingKey = async (key: string): Promise<void> => {
-    await handle.db.transaction(async (tx) =>
-      appendHierarchyEvent(tx, {
-        actorId: 'seed-actor',
-        verb: 'create',
-        targetKind: 'company',
-        targetId: randomUUID(),
-        targetSnapshot: { seeded: true },
-        correlationId: 'seed-correlation',
-        idempotencyKey: key,
-      }),
-    );
-  };
-
-  /**
-   * §6.4 rollback leg: the command must return `conflict` and leave exactly
-   * the seeded event/outbox pair under the key — nothing it wrote survives.
-   */
-  const expectRolledBack = async <T>(
-    key: string,
-    command: () => Promise<HierarchyResult<T>>,
-    assertUnchanged: () => Promise<void>,
-  ): Promise<void> => {
-    await seedConflictingKey(key);
-    const result = await command();
-    expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.error).toBe('conflict');
-    expect(await eventsForKey(key)).toHaveLength(1);
-    expect(await outboxForKey(key)).toHaveLength(1);
-    await assertUnchanged();
-  };
-
-  beforeAll(async (): Promise<void> => {
-    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-gateway-hierarchy-commands-'));
-    handle = createPgliteDb(dataDir);
-    await runPgliteMigrations(handle);
-    moduleRef = await Test.createTestingModule({
-      providers: [
-        HierarchyRepository,
-        HierarchyGrantEvaluationService,
-        { provide: DB, useValue: handle.db },
-      ],
-    }).compile();
-    repo = moduleRef.get(HierarchyRepository);
-    evaluation = moduleRef.get(HierarchyGrantEvaluationService);
-
-    await handle.db.insert(users).values([
-      { id: OWNER, name: 'Owner', email: `${OWNER}@example.com` },
-      { id: ADMIN, name: 'Admin', email: `${ADMIN}@example.com`, role: 'admin' },
-      { id: STRANGER, name: 'Stranger', email: `${STRANGER}@example.com` },
-      { id: SUBJECT, name: 'Subject', email: `${SUBJECT}@example.com` },
-    ]);
-    const created = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'Base Co', slug: slug('base') }),
-    );
-    companyId = created.company.id;
-  });
-
-  afterAll(async (): Promise<void> => {
-    await moduleRef.close();
-    await handle.close();
-    await rm(dataDir, { recursive: true, force: true });
-  });
-
-  // ── §6.4 commit legs ───────────────────────────────────────────────────────
-
-  it('createCompany commits company, owner grant, causation-linked events, and outbox atomically', async () => {
-    const key = `key-${randomUUID()}`;
-    const result = expectOk(
-      await repo.createCompany({
-        actorId: OWNER,
-        name: 'Atomic Co',
-        slug: slug('atomic'),
-        idempotencyKey: key,
-      }),
-    );
-    expect(result.company.visibility).toBe('private');
-    expect(result.grant.role).toBe('hierarchy:owner');
-    expect(result.grant.userId).toBe(OWNER);
-    expect(result.grant.grantedBy).toBe(OWNER);
-
-    const [createEvents, grantEvents] = await Promise.all([
-      eventsForKey(key),
-      eventsForKey(`${key}:grant`),
-    ]);
-    expect(createEvents).toHaveLength(1);
-    expect(createEvents[0]).toMatchObject({ verb: 'create', targetId: result.company.id });
-    expect(grantEvents).toHaveLength(1);
-    expect(grantEvents[0]).toMatchObject({ verb: 'grant_create', targetId: result.grant.id });
-    // The grant event is caused by the create event, same correlation (§4.3).
-    expect(grantEvents[0]!.causationId).toBe(createEvents[0]!.id);
-    expect(grantEvents[0]!.correlationId).toBe(createEvents[0]!.correlationId);
-    expect(await outboxForKey(key)).toHaveLength(1);
-    expect(await outboxForKey(`${key}:grant`)).toHaveLength(1);
-
-    const rows = await handle.db
-      .select()
-      .from(companies)
-      .where(eq(companies.id, result.company.id));
-    expect(rows).toHaveLength(1);
-  });
-
-  it('deleteCompany commits the delete with one audited grant_revoke per cascaded grant', async () => {
-    const created = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'Mortal Co', slug: slug('mortal') }),
-    );
-    const extraGrant = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'company',
-        targetId: created.company.id,
-        role: 'viewer',
-      }),
-    );
-    const key = `key-${randomUUID()}`;
-    expectOk(
-      await repo.deleteCompany({
-        actorId: OWNER,
-        companyId: created.company.id,
-        idempotencyKey: key,
-      }),
-    );
-    const deleteEvents = await eventsForKey(key);
-    expect(deleteEvents).toHaveLength(1);
-    expect(deleteEvents[0]).toMatchObject({ verb: 'delete', targetId: created.company.id });
-    for (const grantId of [created.grant.id, extraGrant.grant.id]) {
-      const revokeEvents = await eventsForKey(`${key}:revoke:${grantId}`);
-      expect(revokeEvents).toHaveLength(1);
-      expect(revokeEvents[0]).toMatchObject({ verb: 'grant_revoke', targetId: grantId });
-      expect(revokeEvents[0]!.causationId).toBe(deleteEvents[0]!.id);
-    }
-    expect(
-      await handle.db.select().from(companies).where(eq(companies.id, created.company.id)),
-    ).toHaveLength(0);
-  });
-
-  // ── §6.4 rollback legs (one per mutation class) ────────────────────────────
-
-  it('renameCompany commits the rename with an audited event carrying previousName', async () => {
-    const created = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'Old Name Co', slug: slug('rename') }),
-    );
-    const key = `key-${randomUUID()}`;
-    const renamed = expectOk(
-      await repo.renameCompany({
-        actorId: OWNER,
-        companyId: created.company.id,
-        name: 'New Name Co',
-        idempotencyKey: key,
-      }),
-    );
-    expect(renamed.company.name).toBe('New Name Co');
-
-    const events = await eventsForKey(key);
-    expect(events).toHaveLength(1);
-    expect(events[0]).toMatchObject({ verb: 'rename', targetId: created.company.id });
-    // §6.4: the audited rename carries the old and new names.
-    expect(events[0]!.targetSnapshot).toMatchObject({
-      name: 'New Name Co',
-      previousName: 'Old Name Co',
-    });
-    expect(await outboxForKey(key)).toHaveLength(1);
-
-    const rows = await handle.db
-      .select()
-      .from(companies)
-      .where(eq(companies.id, created.company.id));
-    expect(rows[0]!.name).toBe('New Name Co');
-  });
-
-  it('revokeGrant commits the row deletion with one audited grant_revoke event', async () => {
-    const grant = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'company',
-        targetId: companyId,
-        role: 'viewer',
-      }),
-    );
-    const key = `key-${randomUUID()}`;
-    const revoked = expectOk(
-      await repo.revokeGrant({ actorId: OWNER, grantId: grant.grant.id, idempotencyKey: key }),
-    );
-    expect(revoked.revokedId).toBe(grant.grant.id);
-
-    const events = await eventsForKey(key);
-    expect(events).toHaveLength(1);
-    expect(events[0]).toMatchObject({ verb: 'grant_revoke', targetId: grant.grant.id });
-    expect(await outboxForKey(key)).toHaveLength(1);
-
-    // §6 revocation = row deletion: the grant row is gone.
-    const rows = await handle.db
-      .select()
-      .from(hierarchyGrants)
-      .where(eq(hierarchyGrants.id, grant.grant.id));
-    expect(rows).toHaveLength(0);
-  });
-
-  it('rolls back a create: no estate row survives the aborted transaction', async () => {
-    const estateSlug = slug('rb-create');
-    const key = `key-${randomUUID()}`;
-    await expectRolledBack(
-      key,
-      () =>
-        repo.createEstate({
-          actorId: OWNER,
-          companyId,
-          name: 'Doomed Estate',
-          slug: estateSlug,
-          idempotencyKey: key,
-        }),
-      async () => {
-        expect(
-          await handle.db.select().from(estates).where(eq(estates.slug, estateSlug)),
-        ).toHaveLength(0);
-      },
-    );
-  });
-
-  it('rolls back a rename: the company keeps its name', async () => {
-    const before = (
-      await handle.db.select().from(companies).where(eq(companies.id, companyId))
-    )[0]!;
-    const key = `key-${randomUUID()}`;
-    await expectRolledBack(
-      key,
-      () => repo.renameCompany({ actorId: OWNER, companyId, name: 'Never', idempotencyKey: key }),
-      async () => {
-        const after = (
-          await handle.db.select().from(companies).where(eq(companies.id, companyId))
-        )[0]!;
-        expect(after.name).toBe(before.name);
-      },
-    );
-  });
-
-  it('rolls back a visibility change: the company stays private', async () => {
-    const key = `key-${randomUUID()}`;
-    await expectRolledBack(
-      key,
-      () =>
-        repo.changeCompanyVisibility({
-          actorId: ADMIN,
-          companyId,
-          visibility: 'directory',
-          idempotencyKey: key,
-        }),
-      async () => {
-        const after = (
-          await handle.db.select().from(companies).where(eq(companies.id, companyId))
-        )[0]!;
-        expect(after.visibility).toBe('private');
-      },
-    );
-  });
-
-  it('rolls back a transfer: the estate keeps its parent', async () => {
-    const estate = expectOk(
-      await repo.createEstate({ actorId: OWNER, companyId, name: 'RB-T', slug: slug('rb-t') }),
-    );
-    const other = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'RB Dest', slug: slug('rb-dest') }),
-    );
-    const key = `key-${randomUUID()}`;
-    await expectRolledBack(
-      key,
-      () =>
-        repo.transferEstate({
-          actorId: OWNER,
-          estateId: estate.estate.id,
-          destinationCompanyId: other.company.id,
-          idempotencyKey: key,
-        }),
-      async () => {
-        const after = (
-          await handle.db.select().from(estates).where(eq(estates.id, estate.estate.id))
-        )[0]!;
-        expect(after.companyId).toBe(companyId);
-      },
-    );
-  });
-
-  it('rolls back a delete: the estate row survives', async () => {
-    const estate = expectOk(
-      await repo.createEstate({ actorId: OWNER, companyId, name: 'RB-D', slug: slug('rb-d') }),
-    );
-    const key = `key-${randomUUID()}`;
-    await expectRolledBack(
-      key,
-      () => repo.deleteEstate({ actorId: OWNER, estateId: estate.estate.id, idempotencyKey: key }),
-      async () => {
-        expect(
-          await handle.db.select().from(estates).where(eq(estates.id, estate.estate.id)),
-        ).toHaveLength(1);
-      },
-    );
-  });
-
-  it('rolls back a grant create: no grant row survives', async () => {
-    const key = `key-${randomUUID()}`;
-    await expectRolledBack(
-      key,
-      () =>
-        repo.createGrant({
-          actorId: OWNER,
-          userId: STRANGER,
-          targetKind: 'company',
-          targetId: companyId,
-          role: 'viewer',
-          idempotencyKey: key,
-        }),
-      async () => {
-        const rows = await handle.db
-          .select()
-          .from(hierarchyGrants)
-          .where(eq(hierarchyGrants.userId, STRANGER));
-        expect(rows.filter((r) => r.companyId === companyId)).toHaveLength(0);
-      },
-    );
-  });
-
-  it('rolls back a grant change and a grant revoke: the grant keeps its role and its row', async () => {
-    const grant = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'company',
-        targetId: companyId,
-        role: 'viewer',
-      }),
-    );
-    const changeKey = `key-${randomUUID()}`;
-    await expectRolledBack(
-      changeKey,
-      () =>
-        repo.changeGrant({
-          actorId: OWNER,
-          grantId: grant.grant.id,
-          role: 'member',
-          idempotencyKey: changeKey,
-        }),
-      async () => {
-        const row = (
-          await handle.db
-            .select()
-            .from(hierarchyGrants)
-            .where(eq(hierarchyGrants.id, grant.grant.id))
-        )[0]!;
-        expect(row.role).toBe('viewer');
-      },
-    );
-    const revokeKey = `key-${randomUUID()}`;
-    await expectRolledBack(
-      revokeKey,
-      () =>
-        repo.revokeGrant({ actorId: OWNER, grantId: grant.grant.id, idempotencyKey: revokeKey }),
-      async () => {
-        expect(
-          await handle.db
-            .select()
-            .from(hierarchyGrants)
-            .where(eq(hierarchyGrants.id, grant.grant.id)),
-        ).toHaveLength(1);
-      },
-    );
-    expectOk(await repo.revokeGrant({ actorId: OWNER, grantId: grant.grant.id }));
-  });
-
-  it('replays a completed command idempotently through the audit machinery', async () => {
-    const key = `key-${randomUUID()}`;
-    const input = { actorId: OWNER, companyId, name: 'Replayed Estate', slug: slug('replay') };
-    const first = expectOk(await repo.createEstate({ ...input, idempotencyKey: key }));
-    // The retry's insert no-ops on the slug conflict — the command surfaces
-    // `conflict`, and crucially appends no second event under the key.
-    const retry = await repo.createEstate({ ...input, idempotencyKey: key });
-    expect(retry.ok).toBe(false);
-    expect(await eventsForKey(key)).toHaveLength(1);
-    expectOk(await repo.deleteEstate({ actorId: OWNER, estateId: first.estate.id }));
-  });
-
-  // ── §6.5 authorization ─────────────────────────────────────────────────────
-
-  it('deny-by-default: a user with no grant cannot mutate and sees not_found (§3.1)', async () => {
-    expect(await repo.renameCompany({ actorId: STRANGER, companyId, name: 'x' })).toEqual({
-      ok: false,
-      error: 'not_found',
-    });
-    expect(
-      await repo.createEstate({ actorId: STRANGER, companyId, name: 'x', slug: slug('deny') }),
-    ).toEqual({ ok: false, error: 'not_found' });
-    expect(await repo.deleteCompany({ actorId: STRANGER, companyId })).toEqual({
-      ok: false,
-      error: 'not_found',
-    });
-  });
-
-  it('grant management requires effective owner: member and viewer are refused (§4.1)', async () => {
-    const grant = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'company',
-        targetId: companyId,
-        role: 'member',
-      }),
-    );
-    expect(
-      await repo.createGrant({
-        actorId: SUBJECT,
-        userId: STRANGER,
-        targetKind: 'company',
-        targetId: companyId,
-        role: 'viewer',
-      }),
-    ).toEqual({ ok: false, error: 'not_found' });
-    expect(await repo.revokeGrant({ actorId: SUBJECT, grantId: grant.grant.id })).toEqual({
-      ok: false,
-      error: 'not_found',
-    });
-    // Member also cannot create children (owner-only, §4.1/§4.3).
-    expect(
-      await repo.createEstate({ actorId: SUBJECT, companyId, name: 'x', slug: slug('member') }),
-    ).toEqual({ ok: false, error: 'not_found' });
-    expectOk(await repo.revokeGrant({ actorId: OWNER, grantId: grant.grant.id }));
-  });
-
-  it('platform admin confers no tenant content access (§1.1): ungrated admin is a stranger', async () => {
-    expect(await repo.renameCompany({ actorId: ADMIN, companyId, name: 'x' })).toEqual({
-      ok: false,
-      error: 'not_found',
-    });
-    expect(
-      await repo.createGrant({
-        actorId: ADMIN,
-        userId: SUBJECT,
-        targetKind: 'company',
-        targetId: companyId,
-        role: 'viewer',
-      }),
-    ).toEqual({ ok: false, error: 'not_found' });
-    expect(await repo.listGrantedCompanies(ADMIN)).toEqual([]);
-    expect(await evaluation.effectiveRole(ADMIN, 'company', companyId)).toBeNull();
-  });
-
-  it('visibility change is platform-admin-only (§5.5): the owner is forbidden, the admin succeeds', async () => {
-    const owned = await repo.changeCompanyVisibility({
-      actorId: OWNER,
-      companyId,
-      visibility: 'directory',
-    });
-    expect(owned).toEqual({
-      ok: false,
-      error: 'forbidden',
-      message: 'visibility change is platform-admin-only',
-    });
-    const changed = expectOk(
-      await repo.changeCompanyVisibility({ actorId: ADMIN, companyId, visibility: 'directory' }),
-    );
-    expect(changed.company.visibility).toBe('directory');
-    // Restore for later witnesses.
-    expectOk(
-      await repo.changeCompanyVisibility({ actorId: ADMIN, companyId, visibility: 'private' }),
-    );
-  });
-
-  // ── §6.9 visibility ────────────────────────────────────────────────────────
-
-  it('directory lists exactly directory-class companies with closed fields (§2.8)', async () => {
-    const listed = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'Listed Co', slug: slug('listed') }),
-    );
-    const unlisted = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'Unlisted Co', slug: slug('unlisted') }),
-    );
-    const key = `key-${randomUUID()}`;
-    expectOk(
-      await repo.changeCompanyVisibility({
-        actorId: ADMIN,
-        companyId: listed.company.id,
-        visibility: 'directory',
-        idempotencyKey: key,
-      }),
-    );
-
-    const directory = await repo.listDirectory();
-    const ids = directory.map((entry) => entry.id);
-    expect(ids).toContain(listed.company.id);
-    expect(ids).not.toContain(unlisted.company.id);
-    expect(ids).not.toContain(companyId);
-    // Closed-field: existence, name, slug — nothing else (no visibility, no
-    // timestamps, no grant or membership data).
-    for (const entry of directory) {
-      expect(Object.keys(entry).sort()).toEqual(['id', 'name', 'slug']);
-    }
-
-    // §5.5: the audited event carries old and new values.
-    const events = await eventsForKey(key);
-    expect(events).toHaveLength(1);
-    expect(events[0]).toMatchObject({ verb: 'visibility_change', targetId: listed.company.id });
-    expect(events[0]!.targetSnapshot).toMatchObject({
-      previousVisibility: 'private',
-      visibility: 'directory',
-    });
-  });
-
-  it('directory disclosure confers no authority: a listed company still refuses non-granted callers (§6.9)', async () => {
-    const listed = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'Exposed Co', slug: slug('exposed') }),
-    );
-    expectOk(
-      await repo.changeCompanyVisibility({
-        actorId: ADMIN,
-        companyId: listed.company.id,
-        visibility: 'directory',
-      }),
-    );
-
-    // The company is directory-listed for the whole probe window...
-    expect((await repo.listDirectory()).map((entry) => entry.id)).toContain(listed.company.id);
-
-    // ...but the non-granted reader's granted-read surface still excludes it:
-    // directory disclosure adds existence/name/slug only, never content access.
-    expect(await repo.listGrantedCompanies(STRANGER)).toEqual([]);
-
-    // A stranger mutation of the listed company is refused exactly like a
-    // missing node — the §6.7 carve-out covers the listing, not commands.
-    const realProbe = await repo.renameCompany({
-      actorId: STRANGER,
-      companyId: listed.company.id,
-      name: 'x',
-    });
-    const missingProbe = await repo.renameCompany({
-      actorId: STRANGER,
-      companyId: randomUUID(),
-      name: 'x',
-    });
-    expect(realProbe).toEqual(missingProbe);
-    expect(await repo.deleteCompany({ actorId: STRANGER, companyId: listed.company.id })).toEqual({
-      ok: false,
-      error: 'not_found',
-    });
-  });
-
-  it('granted companies are the reader control: owner sees them, a stranger sees nothing (§2.8)', async () => {
-    const ownerCompanies = await repo.listGrantedCompanies(OWNER);
-    expect(ownerCompanies.map((c) => c.id)).toContain(companyId);
-    expect(await repo.listGrantedCompanies(STRANGER)).toEqual([]);
-  });
-
-  // ── §6.7 no existence oracle ───────────────────────────────────────────────
-
-  it('an unauthorized probe of a real node is indistinguishable from a missing node', async () => {
-    const realCompany = await repo.renameCompany({ actorId: STRANGER, companyId, name: 'x' });
-    const missingCompany = await repo.renameCompany({
-      actorId: STRANGER,
-      companyId: randomUUID(),
-      name: 'x',
-    });
-    expect(realCompany).toEqual(missingCompany);
-
-    const estate = expectOk(
-      await repo.createEstate({
-        actorId: OWNER,
-        companyId,
-        name: 'Oracle E',
-        slug: slug('oracle'),
-      }),
-    );
-    const realEstate = await repo.deleteEstate({ actorId: STRANGER, estateId: estate.estate.id });
-    const missingEstate = await repo.deleteEstate({ actorId: STRANGER, estateId: randomUUID() });
-    expect(realEstate).toEqual(missingEstate);
-
-    const grant = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'estate',
-        targetId: estate.estate.id,
-        role: 'viewer',
-      }),
-    );
-    const realGrant = await repo.revokeGrant({ actorId: STRANGER, grantId: grant.grant.id });
-    const missingGrant = await repo.revokeGrant({ actorId: STRANGER, grantId: randomUUID() });
-    expect(realGrant).toEqual(missingGrant);
-    expectOk(await repo.deleteEstate({ actorId: OWNER, estateId: estate.estate.id }));
-  });
-
-  // ── contract 2 §3 grant evaluation ─────────────────────────────────────────
-
-  it('a company grant confers its role down the whole chain, workspace included (§3.2)', async () => {
-    const estate = expectOk(
-      await repo.createEstate({ actorId: OWNER, companyId, name: 'Chain E', slug: slug('chain') }),
-    );
-    const project = expectOk(
-      await repo.createPlatformProject({
-        actorId: OWNER,
-        estateId: estate.estate.id,
-        name: 'Chain P',
-        slug: slug('chain-p'),
-      }),
-    );
-    // Workspaces are evaluable but not hierarchy commands; seed one directly.
-    const workspaceId = randomUUID();
-    await handle.db.insert(workspaces).values({
-      id: workspaceId,
-      name: 'Chain W',
-      slug: slug('chain-w'),
-      platformProjectId: project.platformProject.id,
-    });
-
-    for (const [kind, id] of [
-      ['company', companyId],
-      ['estate', estate.estate.id],
-      ['platform_project', project.platformProject.id],
-      ['workspace', workspaceId],
-    ] as const) {
-      expect(await evaluation.effectiveRole(OWNER, kind, id)).toBe('owner');
-      expect(await evaluation.effectiveRole(STRANGER, kind, id)).toBeNull();
-    }
-
-    // Max-role (§3.3): viewer on the company + owner on the estate → owner at
-    // and below the estate, viewer at the company.
-    const viewerGrant = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'company',
-        targetId: companyId,
-        role: 'viewer',
-      }),
-    );
-    const ownerGrant = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'estate',
-        targetId: estate.estate.id,
-        role: 'owner',
-      }),
-    );
-    expect(await evaluation.effectiveRole(SUBJECT, 'company', companyId)).toBe('viewer');
-    expect(await evaluation.effectiveRole(SUBJECT, 'estate', estate.estate.id)).toBe('owner');
-    expect(await evaluation.effectiveRole(SUBJECT, 'workspace', workspaceId)).toBe('owner');
-
-    // Revocation is row deletion and denies the very next evaluation (§6).
-    expectOk(await repo.revokeGrant({ actorId: OWNER, grantId: ownerGrant.grant.id }));
-    expect(await evaluation.effectiveRole(SUBJECT, 'estate', estate.estate.id)).toBe('viewer');
-    expectOk(await repo.revokeGrant({ actorId: OWNER, grantId: viewerGrant.grant.id }));
-    expect(await evaluation.effectiveRole(SUBJECT, 'company', companyId)).toBeNull();
-
-    await handle.db.delete(workspaces).where(eq(workspaces.id, workspaceId));
-    expectOk(
-      await repo.deletePlatformProject({
-        actorId: OWNER,
-        platformProjectId: project.platformProject.id,
-      }),
-    );
-    expectOk(await repo.deleteEstate({ actorId: OWNER, estateId: estate.estate.id }));
-  });
-
-  it('team grant subjects are suspended: a team row confers nothing and cannot be changed (§1.4)', async () => {
-    const teamId = randomUUID();
-    await handle.db.insert(teams).values({
-      id: teamId,
-      name: slug('team'),
-      slug: slug('team'),
-      ownerId: SUBJECT,
-      managerId: SUBJECT,
-    });
-    // Out-of-band team row (the command surface cannot create one).
-    const inserted = await handle.db
-      .insert(hierarchyGrants)
-      .values({ teamId, companyId, role: 'owner', grantedBy: OWNER })
-      .returning();
-    const teamGrantId = inserted[0]!.id;
-
-    // The team's own owner gains no effective role from it.
-    expect(await evaluation.effectiveRole(SUBJECT, 'company', companyId)).toBeNull();
-    // changeGrant refuses the row.
-    expect(
-      await repo.changeGrant({ actorId: OWNER, grantId: teamGrantId, role: 'viewer' }),
-    ).toEqual({
-      ok: false,
-      error: 'conflict',
-      message: 'team grant subjects are suspended',
-    });
-    await handle.db.delete(hierarchyGrants).where(eq(hierarchyGrants.id, teamGrantId));
-    await handle.db.delete(teams).where(eq(teams.id, teamId));
-  });
-
-  // ── command conflict semantics ─────────────────────────────────────────────
-
-  it('transfer needs owner on both parents in its own transaction, and refuses no-op and colliding transfers (§5)', async () => {
-    const source = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'Src Co', slug: slug('src') }),
-    );
-    const destination = expectOk(
-      await repo.createCompany({ actorId: SUBJECT, name: 'Dst Co', slug: slug('dst') }),
-    );
-    const estateSlug = slug('mv');
-    const estate = expectOk(
-      await repo.createEstate({
-        actorId: OWNER,
-        companyId: source.company.id,
-        name: 'Mv E',
-        slug: estateSlug,
-      }),
-    );
-
-    // OWNER owns the source but not the destination → not_found (§6.7-safe).
-    expect(
-      await repo.transferEstate({
-        actorId: OWNER,
-        estateId: estate.estate.id,
-        destinationCompanyId: destination.company.id,
-      }),
-    ).toEqual({ ok: false, error: 'not_found' });
-
-    // Same-parent transfer is refused.
-    const samePlace = await repo.transferEstate({
-      actorId: OWNER,
-      estateId: estate.estate.id,
-      destinationCompanyId: source.company.id,
-    });
-    expect(samePlace.ok).toBe(false);
-    if (!samePlace.ok) expect(samePlace.error).toBe('conflict');
-
-    // Grant OWNER the destination; a slug collision there is refused.
-    expectOk(
-      await repo.createGrant({
-        actorId: SUBJECT,
-        userId: OWNER,
-        targetKind: 'company',
-        targetId: destination.company.id,
-        role: 'owner',
-      }),
-    );
-    expectOk(
-      await repo.createEstate({
-        actorId: OWNER,
-        companyId: destination.company.id,
-        name: 'Collide',
-        slug: estateSlug,
-      }),
-    );
-    const collision = await repo.transferEstate({
-      actorId: OWNER,
-      estateId: estate.estate.id,
-      destinationCompanyId: destination.company.id,
-    });
-    expect(collision.ok).toBe(false);
-    if (!collision.ok) expect(collision.error).toBe('conflict');
-  });
-
-  it('a successful transfer records transfer_from and transfer_to (§6.4 three-leg witness)', async () => {
-    const from = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'From Co', slug: slug('from') }),
-    );
-    const to = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'To Co', slug: slug('to') }),
-    );
-    const estate = expectOk(
-      await repo.createEstate({
-        actorId: OWNER,
-        companyId: from.company.id,
-        name: 'Moved E',
-        slug: slug('moved'),
-      }),
-    );
-    const key = `key-${randomUUID()}`;
-    expectOk(
-      await repo.transferEstate({
-        actorId: OWNER,
-        estateId: estate.estate.id,
-        destinationCompanyId: to.company.id,
-        idempotencyKey: key,
-      }),
-    );
-    const moved = (
-      await handle.db.select().from(estates).where(eq(estates.id, estate.estate.id))
-    )[0]!;
-    expect(moved.companyId).toBe(to.company.id);
-    const events = await eventsForKey(key);
-    expect(events).toHaveLength(1);
-    expect(events[0]).toMatchObject({ verb: 'transfer', targetId: estate.estate.id });
-    expect(events[0]!.transferFrom).toMatchObject({ kind: 'company', id: from.company.id });
-    expect(events[0]!.transferTo).toMatchObject({ kind: 'company', id: to.company.id });
-    // The post-transfer snapshot's parent chain names the destination.
-    expect(events[0]!.targetSnapshot).toMatchObject({
-      parentChain: [{ kind: 'company', id: to.company.id, slug: to.company.slug }],
-    });
-  });
-
-  it('refuses duplicate slugs, deletes with children, and degenerate grant commands as conflicts', async () => {
-    const co = expectOk(
-      await repo.createCompany({ actorId: OWNER, name: 'Conflict Co', slug: slug('conf') }),
-    );
-    const dupSlug = await repo.createCompany({ actorId: OWNER, name: 'x', slug: co.company.slug });
-    expect(dupSlug.ok).toBe(false);
-    if (!dupSlug.ok) expect(dupSlug.error).toBe('conflict');
-
-    expectOk(
-      await repo.createEstate({
-        actorId: OWNER,
-        companyId: co.company.id,
-        name: 'Child',
-        slug: slug('child'),
-      }),
-    );
-    const withChildren = await repo.deleteCompany({ actorId: OWNER, companyId: co.company.id });
-    expect(withChildren.ok).toBe(false);
-    if (!withChildren.ok) expect(withChildren.error).toBe('conflict');
-
-    // Grant to a nonexistent subject is refused (the caller already holds
-    // owner, so the refusal discloses nothing new).
-    const ghost = await repo.createGrant({
-      actorId: OWNER,
-      userId: `missing-${randomUUID()}`,
-      targetKind: 'company',
-      targetId: co.company.id,
-      role: 'viewer',
-    });
-    expect(ghost.ok).toBe(false);
-    if (!ghost.ok) expect(ghost.error).toBe('conflict');
-
-    const grant = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'company',
-        targetId: co.company.id,
-        role: 'viewer',
-      }),
-    );
-    const duplicate = await repo.createGrant({
-      actorId: OWNER,
-      userId: SUBJECT,
-      targetKind: 'company',
-      targetId: co.company.id,
-      role: 'viewer',
-    });
-    expect(duplicate.ok).toBe(false);
-    if (!duplicate.ok) expect(duplicate.error).toBe('conflict');
-
-    const sameRole = await repo.changeGrant({
-      actorId: OWNER,
-      grantId: grant.grant.id,
-      role: 'viewer',
-    });
-    expect(sameRole.ok).toBe(false);
-    if (!sameRole.ok) expect(sameRole.error).toBe('conflict');
-
-    // A second grant with another role exists → changing the first onto that
-    // role would collide with the unique constraint; refused ahead of it.
-    const second = expectOk(
-      await repo.createGrant({
-        actorId: OWNER,
-        userId: SUBJECT,
-        targetKind: 'company',
-        targetId: co.company.id,
-        role: 'member',
-      }),
-    );
-    const collide = await repo.changeGrant({
-      actorId: OWNER,
-      grantId: grant.grant.id,
-      role: 'member',
-    });
-    expect(collide.ok).toBe(false);
-    if (!collide.ok) expect(collide.error).toBe('conflict');
-
-    // A clean change succeeds and records the previous role, namespaced (§4.5).
-    const changeKey = `key-${randomUUID()}`;
-    const changed = expectOk(
-      await repo.changeGrant({
-        actorId: OWNER,
-        grantId: second.grant.id,
-        role: 'owner',
-        idempotencyKey: changeKey,
-      }),
-    );
-    expect(changed.grant.role).toBe('hierarchy:owner');
-    const events = await eventsForKey(changeKey);
-    expect(events).toHaveLength(1);
-    expect(events[0]!.targetSnapshot).toMatchObject({
-      role: 'hierarchy:owner',
-      previousRole: 'hierarchy:member',
-    });
-  });
-});

apps/gateway/src/hierarchy/hierarchy-grant-evaluation.ts

@@ -1,242 +0,0 @@
-import { Inject, Injectable } from '@nestjs/common';
-import {
-  companies,
-  eq,
-  estates,
-  hierarchyGrants,
-  inArray,
-  or,
-  platformProjects,
-  workspaces,
-  and,
-  type Db,
-  HIERARCHY_GRANT_ROLES,
-} from '@mosaicstack/db';
-import { DB } from '../database/database.module.js';
-
-/**
- * Hierarchy grant evaluation (contract 2 §3).
- *
- * Deny-by-default (§3.1): a user's effective role on a node is null unless a
- * grant row explicitly confers one. Grants apply down the chain only (§3.2):
- * the effective role on a node is the maximum role over grants targeting the
- * node itself or any of its ancestors, maximum per the total order
- * viewer ⊂ member ⊂ owner (§2). Evaluation is live and per-decision — no
- * caching — so revocation (row deletion, §6) denies the next decision
- * inherently. A missing node evaluates to null, indistinguishable from
- * no-grant, which keeps unauthorized probes oracle-safe (contract 1 §6.7).
- *
- * Team grant subjects are SUSPENDED (§1.4): the command surface refuses to
- * create them and this evaluator considers user-subject grants only, so a
- * team row could not confer access even if one existed.
- *
- * Read-only module: it selects from the class tables but never writes them,
- * so it does not appear on the writer-coverage allowlist.
- */
-
-export type HierarchyGrantRole = (typeof HIERARCHY_GRANT_ROLES)[number];
-
-/** Node kinds a grant may target (§3.2; workspace is evaluable, not grantable). */
-export type GrantTargetKind = 'company' | 'estate' | 'platform_project';
-/** Node kinds an authorization decision may be evaluated at (§3.2: down to workspace). */
-export type EvaluableNodeKind = GrantTargetKind | 'workspace';
-
-type Tx = Pick<Db, 'select'>;
-
-/** Ancestor chain of a node, self included at its own level; ids only. */
-export interface AncestorChain {
-  readonly companyId: string;
-  readonly estateId?: string;
-  readonly platformProjectId?: string;
-  readonly workspaceId?: string;
-}
-
-export function roleStrength(role: HierarchyGrantRole): number {
-  return HIERARCHY_GRANT_ROLES.indexOf(role);
-}
-
-export function roleAtLeast(
-  role: HierarchyGrantRole | null,
-  required: HierarchyGrantRole,
-): boolean {
-  return role !== null && roleStrength(role) >= roleStrength(required);
-}
-
-/**
- * Serialized role strings are namespaced (§4.5): audit events and API
- * responses carry `hierarchy:owner`, never a bare `owner`.
- */
-export function namespacedHierarchyRole(role: HierarchyGrantRole): string {
-  return `hierarchy:${role}`;
-}
-
-/**
- * Resolve a node's ancestor chain (self included). Returns null when the
- * node does not exist — callers treat that exactly like no-grant (§3.1,
- * oracle-safe).
- */
-export async function resolveAncestorChain(
-  tx: Tx,
-  kind: EvaluableNodeKind,
-  id: string,
-): Promise<AncestorChain | null> {
-  if (kind === 'company') {
-    const rows = await tx
-      .select({ id: companies.id })
-      .from(companies)
-      .where(eq(companies.id, id))
-      .limit(1);
-    const row = rows[0];
-    return row ? { companyId: row.id } : null;
-  }
-  if (kind === 'estate') {
-    const rows = await tx
-      .select({ id: estates.id, companyId: estates.companyId })
-      .from(estates)
-      .where(eq(estates.id, id))
-      .limit(1);
-    const row = rows[0];
-    return row ? { companyId: row.companyId, estateId: row.id } : null;
-  }
-  if (kind === 'platform_project') {
-    const rows = await tx
-      .select({
-        id: platformProjects.id,
-        estateId: platformProjects.estateId,
-        companyId: estates.companyId,
-      })
-      .from(platformProjects)
-      .innerJoin(estates, eq(estates.id, platformProjects.estateId))
-      .where(eq(platformProjects.id, id))
-      .limit(1);
-    const row = rows[0];
-    return row
-      ? { companyId: row.companyId, estateId: row.estateId, platformProjectId: row.id }
-      : null;
-  }
-  const rows = await tx
-    .select({
-      id: workspaces.id,
-      platformProjectId: workspaces.platformProjectId,
-      estateId: platformProjects.estateId,
-      companyId: estates.companyId,
-    })
-    .from(workspaces)
-    .innerJoin(platformProjects, eq(platformProjects.id, workspaces.platformProjectId))
-    .innerJoin(estates, eq(estates.id, platformProjects.estateId))
-    .where(eq(workspaces.id, id))
-    .limit(1);
-  const row = rows[0];
-  return row
-    ? {
-        companyId: row.companyId,
-        estateId: row.estateId,
-        platformProjectId: row.platformProjectId,
-        workspaceId: row.id,
-      }
-    : null;
-}
-
-function maxRole(roles: readonly string[]): HierarchyGrantRole | null {
-  let best: HierarchyGrantRole | null = null;
-  for (const candidate of roles) {
-    // Fail-closed: a value outside the vocabulary confers nothing.
-    if (!(HIERARCHY_GRANT_ROLES as readonly string[]).includes(candidate)) continue;
-    const role = candidate as HierarchyGrantRole;
-    if (best === null || roleStrength(role) > roleStrength(best)) best = role;
-  }
-  return best;
-}
-
-/**
- * Effective role of a user on a node: maximum over the user's grants whose
- * target is the node or any ancestor (§3.2); null = deny (§3.1). Missing
- * node → null.
- */
-export async function evaluateEffectiveRole(
-  tx: Tx,
-  userId: string,
-  kind: EvaluableNodeKind,
-  id: string,
-): Promise<HierarchyGrantRole | null> {
-  const chain = await resolveAncestorChain(tx, kind, id);
-  if (!chain) return null;
-
-  const targetConditions = [eq(hierarchyGrants.companyId, chain.companyId)];
-  if (chain.estateId) targetConditions.push(eq(hierarchyGrants.estateId, chain.estateId));
-  if (chain.platformProjectId) {
-    targetConditions.push(eq(hierarchyGrants.platformProjectId, chain.platformProjectId));
-  }
-
-  const rows = await tx
-    .select({ role: hierarchyGrants.role })
-    .from(hierarchyGrants)
-    .where(and(eq(hierarchyGrants.userId, userId), or(...targetConditions)));
-  return maxRole(rows.map((r) => r.role));
-}
-
-/**
- * All companies on which the user holds any effective role, i.e. companies
- * with a grant on the company itself or on any descendant (contract 1 §2.8:
- * a grant anywhere in the subtree discloses the company's chain upward).
- */
-export async function grantedCompanyIds(tx: Tx, userId: string): Promise<string[]> {
-  const grants = await tx
-    .select({
-      companyId: hierarchyGrants.companyId,
-      estateId: hierarchyGrants.estateId,
-      platformProjectId: hierarchyGrants.platformProjectId,
-    })
-    .from(hierarchyGrants)
-    .where(eq(hierarchyGrants.userId, userId));
-
-  const companyIds = new Set<string>();
-  const estateIds = new Set<string>();
-  const platformProjectIds = new Set<string>();
-  for (const grant of grants) {
-    if (grant.companyId) companyIds.add(grant.companyId);
-    else if (grant.estateId) estateIds.add(grant.estateId);
-    else if (grant.platformProjectId) platformProjectIds.add(grant.platformProjectId);
-  }
-
-  if (platformProjectIds.size > 0) {
-    const rows = await tx
-      .select({ estateId: platformProjects.estateId })
-      .from(platformProjects)
-      .where(inArray(platformProjects.id, [...platformProjectIds]));
-    for (const row of rows) estateIds.add(row.estateId);
-  }
-  if (estateIds.size > 0) {
-    const rows = await tx
-      .select({ companyId: estates.companyId })
-      .from(estates)
-      .where(inArray(estates.id, [...estateIds]));
-    for (const row of rows) companyIds.add(row.companyId);
-  }
-  return [...companyIds];
-}
-
-@Injectable()
-export class HierarchyGrantEvaluationService {
-  constructor(@Inject(DB) private readonly db: Db) {}
-
-  /** Live per-decision evaluation; pass a tx to evaluate inside a command's transaction. */
-  effectiveRole(
-    userId: string,
-    kind: EvaluableNodeKind,
-    id: string,
-    tx?: Tx,
-  ): Promise<HierarchyGrantRole | null> {
-    return evaluateEffectiveRole(tx ?? this.db, userId, kind, id);
-  }
-
-  async hasRole(
-    userId: string,
-    kind: EvaluableNodeKind,
-    id: string,
-    required: HierarchyGrantRole,
-    tx?: Tx,
-  ): Promise<boolean> {
-    return roleAtLeast(await this.effectiveRole(userId, kind, id, tx), required);
-  }
-}

apps/gateway/src/hierarchy/hierarchy.controller.ts

@@ -1,297 +0,0 @@
-import {
-  Body,
-  Controller,
-  Delete,
-  Get,
-  HttpCode,
-  Param,
-  ParseUUIDPipe,
-  Post,
-  UseGuards,
-} from '@nestjs/common';
-import { AuthGuard } from '../auth/auth.guard.js';
-import { CurrentUser } from '../auth/current-user.decorator.js';
-import {
-  ChangeCompanyVisibilityDto,
-  ChangeGrantDto,
-  CreateCompanyDto,
-  CreateEstateDto,
-  CreateGrantDto,
-  CreatePlatformProjectDto,
-  DeleteNodeDto,
-  RenameNodeDto,
-  TransferEstateDto,
-  TransferPlatformProjectDto,
-} from './hierarchy.dto.js';
-import { HierarchyRepository } from './hierarchy.repository.js';
-import { HierarchyService } from './hierarchy.service.js';
-
-/**
- * The hierarchy command family (contract 1 §5, §6.3). This controller is the
- * closed HTTP surface over the hierarchy class tables: the route-inventory
- * witness asserts these routes and no others exist. Delete commands take an
- * optional body (idempotency key) via POST-style DTOs; every mutation is
- * audited on its own transaction by the repository.
- */
-@Controller('api/hierarchy')
-@UseGuards(AuthGuard)
-export class HierarchyController {
-  constructor(
-    private readonly repository: HierarchyRepository,
-    private readonly service: HierarchyService,
-  ) {}
-
-  // ── companies ────────────────────────────────────────────────────────────
-
-  @Post('companies')
-  async createCompany(@CurrentUser() user: { id: string }, @Body() dto: CreateCompanyDto) {
-    return this.service.unwrap(
-      await this.repository.createCompany({
-        actorId: user.id,
-        name: dto.name,
-        slug: dto.slug,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  /** Companies the caller holds a grant on (directly or via a descendant). */
-  @Get('companies')
-  listGrantedCompanies(@CurrentUser() user: { id: string }) {
-    return this.repository.listGrantedCompanies(user.id);
-  }
-
-  /** Directory-class companies, closed-field (§2.8). */
-  @Get('companies/directory')
-  listDirectory() {
-    return this.repository.listDirectory();
-  }
-
-  @Post('companies/:id/rename')
-  @HttpCode(200)
-  async renameCompany(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: RenameNodeDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.renameCompany({
-        actorId: user.id,
-        companyId: id,
-        name: dto.name,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Post('companies/:id/visibility')
-  @HttpCode(200)
-  async changeCompanyVisibility(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: ChangeCompanyVisibilityDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.changeCompanyVisibility({
-        actorId: user.id,
-        companyId: id,
-        visibility: dto.visibility,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Delete('companies/:id')
-  async deleteCompany(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: DeleteNodeDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.deleteCompany({
-        actorId: user.id,
-        companyId: id,
-        idempotencyKey: dto?.idempotencyKey,
-      }),
-    );
-  }
-
-  // ── estates ──────────────────────────────────────────────────────────────
-
-  @Post('estates')
-  async createEstate(@CurrentUser() user: { id: string }, @Body() dto: CreateEstateDto) {
-    return this.service.unwrap(
-      await this.repository.createEstate({
-        actorId: user.id,
-        companyId: dto.companyId,
-        name: dto.name,
-        slug: dto.slug,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Post('estates/:id/rename')
-  @HttpCode(200)
-  async renameEstate(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: RenameNodeDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.renameEstate({
-        actorId: user.id,
-        estateId: id,
-        name: dto.name,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Post('estates/:id/transfer')
-  @HttpCode(200)
-  async transferEstate(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: TransferEstateDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.transferEstate({
-        actorId: user.id,
-        estateId: id,
-        destinationCompanyId: dto.destinationCompanyId,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Delete('estates/:id')
-  async deleteEstate(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: DeleteNodeDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.deleteEstate({
-        actorId: user.id,
-        estateId: id,
-        idempotencyKey: dto?.idempotencyKey,
-      }),
-    );
-  }
-
-  // ── platform projects ────────────────────────────────────────────────────
-
-  @Post('platform-projects')
-  async createPlatformProject(
-    @CurrentUser() user: { id: string },
-    @Body() dto: CreatePlatformProjectDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.createPlatformProject({
-        actorId: user.id,
-        estateId: dto.estateId,
-        name: dto.name,
-        slug: dto.slug,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Post('platform-projects/:id/rename')
-  @HttpCode(200)
-  async renamePlatformProject(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: RenameNodeDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.renamePlatformProject({
-        actorId: user.id,
-        platformProjectId: id,
-        name: dto.name,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Post('platform-projects/:id/transfer')
-  @HttpCode(200)
-  async transferPlatformProject(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: TransferPlatformProjectDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.transferPlatformProject({
-        actorId: user.id,
-        platformProjectId: id,
-        destinationEstateId: dto.destinationEstateId,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Delete('platform-projects/:id')
-  async deletePlatformProject(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: DeleteNodeDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.deletePlatformProject({
-        actorId: user.id,
-        platformProjectId: id,
-        idempotencyKey: dto?.idempotencyKey,
-      }),
-    );
-  }
-
-  // ── grants ───────────────────────────────────────────────────────────────
-
-  @Post('grants')
-  async createGrant(@CurrentUser() user: { id: string }, @Body() dto: CreateGrantDto) {
-    return this.service.unwrap(
-      await this.repository.createGrant({
-        actorId: user.id,
-        userId: dto.userId,
-        targetKind: dto.targetKind,
-        targetId: dto.targetId,
-        role: dto.role,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Post('grants/:id/change')
-  @HttpCode(200)
-  async changeGrant(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: ChangeGrantDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.changeGrant({
-        actorId: user.id,
-        grantId: id,
-        role: dto.role,
-        idempotencyKey: dto.idempotencyKey,
-      }),
-    );
-  }
-
-  @Delete('grants/:id')
-  async revokeGrant(
-    @CurrentUser() user: { id: string },
-    @Param('id', ParseUUIDPipe) id: string,
-    @Body() dto: DeleteNodeDto,
-  ) {
-    return this.service.unwrap(
-      await this.repository.revokeGrant({
-        actorId: user.id,
-        grantId: id,
-        idempotencyKey: dto?.idempotencyKey,
-      }),
-    );
-  }
-}

apps/gateway/src/hierarchy/hierarchy.dto.ts

@@ -1,169 +0,0 @@
-import { COMPANY_VISIBILITY, HIERARCHY_GRANT_ROLES } from '@mosaicstack/db';
-import { IsIn, IsOptional, IsString, IsUUID, Matches, MaxLength, MinLength } from 'class-validator';
-
-/**
- * Hierarchy command DTOs (contract 1 §5, contract 2 §4/§7).
- *
- * The global ValidationPipe runs with whitelist + forbidNonWhitelisted, so a
- * payload field absent from these classes is a 400. That closure is itself
- * contract surface:
- *  - CreateCompanyDto declares NO visibility field — creation is always
- *    private (contract 1 §5.5); a visibility argument is refused by the pipe.
- *  - CreateGrantDto declares NO teamId field — team grant subjects are
- *    suspended (contract 2 §1.4/§7.5); a team subject is refused by the pipe.
- * Every class here must be registered in PIPE_GUARDED_DTOS so the boot-time
- * assertion proves the pipe sees the decorators.
- */
-
-const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
-const SLUG_MESSAGE = 'slug must be lowercase alphanumeric with interior hyphens';
-
-export class CreateCompanyDto {
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  name!: string;
-
-  @IsString()
-  @MaxLength(100)
-  @Matches(SLUG_PATTERN, { message: SLUG_MESSAGE })
-  slug!: string;
-
-  /** Client-supplied idempotency key (REQ-AUD-001 replay); server-generated when absent. */
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class RenameNodeDto {
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  name!: string;
-
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class ChangeCompanyVisibilityDto {
-  @IsIn(COMPANY_VISIBILITY)
-  visibility!: (typeof COMPANY_VISIBILITY)[number];
-
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class DeleteNodeDto {
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class CreateEstateDto {
-  @IsUUID()
-  companyId!: string;
-
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  name!: string;
-
-  @IsString()
-  @MaxLength(100)
-  @Matches(SLUG_PATTERN, { message: SLUG_MESSAGE })
-  slug!: string;
-
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class CreatePlatformProjectDto {
-  @IsUUID()
-  estateId!: string;
-
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  name!: string;
-
-  @IsString()
-  @MaxLength(100)
-  @Matches(SLUG_PATTERN, { message: SLUG_MESSAGE })
-  slug!: string;
-
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class TransferEstateDto {
-  @IsUUID()
-  destinationCompanyId!: string;
-
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class TransferPlatformProjectDto {
-  @IsUUID()
-  destinationEstateId!: string;
-
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class CreateGrantDto {
-  /** Subject user (better-auth text id). No teamId field — see module doc. */
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  userId!: string;
-
-  @IsIn(['company', 'estate', 'platform_project'])
-  targetKind!: 'company' | 'estate' | 'platform_project';
-
-  @IsUUID()
-  targetId!: string;
-
-  /** Bare vocabulary on requests; responses and audit events are namespaced (§4.5). */
-  @IsIn(HIERARCHY_GRANT_ROLES)
-  role!: (typeof HIERARCHY_GRANT_ROLES)[number];
-
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}
-
-export class ChangeGrantDto {
-  @IsIn(HIERARCHY_GRANT_ROLES)
-  role!: (typeof HIERARCHY_GRANT_ROLES)[number];
-
-  @IsOptional()
-  @IsString()
-  @MinLength(1)
-  @MaxLength(255)
-  idempotencyKey?: string;
-}

apps/gateway/src/hierarchy/hierarchy.module.ts

@@ -1,28 +1,17 @@
 import { Module } from '@nestjs/common';
 import { HierarchyAuditRepository } from './hierarchy-audit.repository.js';
-import { HierarchyGrantEvaluationService } from './hierarchy-grant-evaluation.js';
-import { HierarchyController } from './hierarchy.controller.js';
-import { HierarchyRepository } from './hierarchy.repository.js';
-import { HierarchyService } from './hierarchy.service.js';
 
 /**
  * Hierarchy (tenancy/authorization structure) feature module.
  *
- * M4-1b-i shipped the audit event + outbox machinery (contract 1 §5.2);
- * M4-1b-ii adds the command family — the closed route surface asserted by
- * the route-inventory witness — plus grant evaluation (contract 2 §3).
- * HierarchyRepository is the sole class-table writer (writer-coverage
- * allowlist); every mutation runs authorize → mutate → audit in one
- * transaction.
+ * M4-1b-i ships the audit event + outbox machinery only (contract 1 §5.2).
+ * The hierarchy command family — controllers, DTOs, and the allowlisted
+ * class-table repositories — lands in M4-1b-ii once contract 2 (RBAC grant
+ * model) merges; until then this module exposes no routes, which the
+ * route-inventory witness asserts.
  */
 @Module({
-  controllers: [HierarchyController],
-  providers: [
-    HierarchyAuditRepository,
-    HierarchyGrantEvaluationService,
-    HierarchyRepository,
-    HierarchyService,
-  ],
-  exports: [HierarchyAuditRepository, HierarchyGrantEvaluationService],
+  providers: [HierarchyAuditRepository],
+  exports: [HierarchyAuditRepository],
 })
 export class HierarchyModule {}

apps/gateway/src/hierarchy/hierarchy.repository.ts

@@ -1,935 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { Inject, Injectable } from '@nestjs/common';
-import {
-  and,
-  asc,
-  companies,
-  eq,
-  estates,
-  hierarchyGrants,
-  inArray,
-  platformProjects,
-  users,
-  workspaces,
-  type Db,
-} from '@mosaicstack/db';
-import { DB } from '../database/database.module.js';
-import {
-  appendHierarchyEvent,
-  buildNodeSnapshot,
-  HierarchyAuditIdempotencyConflictError,
-} from './hierarchy-audit.repository.js';
-import {
-  evaluateEffectiveRole,
-  grantedCompanyIds,
-  namespacedHierarchyRole,
-  roleAtLeast,
-  type GrantTargetKind,
-  type HierarchyGrantRole,
-} from './hierarchy-grant-evaluation.js';
-
-/**
- * Hierarchy command repository (contract 1 §5, contract 2 §4).
- *
- * The ONLY writer of the hierarchy class tables (companies, estates,
- * platform_projects, hierarchy_grants) — it is the writer-coverage
- * allowlist's sole entry. Every command runs one transaction that
- * authorizes (live grant evaluation inside the same transaction), mutates,
- * and appends the semantic audit event + outbox record via the M4-1b-i
- * machinery, so state, event, and outbox commit or roll back together
- * (REQ-AUD-001).
- *
- * Authorization failure and target-not-found both return `not_found`
- * (contract 1 §6.7: no existence oracle — an unauthorized caller learns
- * nothing a stranger would not). `forbidden` appears only where the caller
- * already knows the surface exists independent of any node: the admin-only
- * visibility change (§5.5). Serialized role strings are namespaced (§4.5).
- */
-
-export type HierarchyCommandFailure =
-  | { readonly ok: false; readonly error: 'not_found' }
-  | { readonly ok: false; readonly error: 'forbidden'; readonly message: string }
-  | { readonly ok: false; readonly error: 'conflict'; readonly message: string };
-
-export type HierarchyResult<T> = ({ readonly ok: true } & T) | HierarchyCommandFailure;
-
-export interface CompanyView {
-  readonly id: string;
-  readonly name: string;
-  readonly slug: string;
-  readonly visibility: string;
-}
-
-export interface NodeView {
-  readonly id: string;
-  readonly name: string;
-  readonly slug: string;
-}
-
-export interface GrantView {
-  readonly id: string;
-  readonly userId: string;
-  readonly targetKind: GrantTargetKind;
-  readonly targetId: string;
-  /** Namespaced (§4.5), e.g. `hierarchy:owner`. */
-  readonly role: string;
-  readonly grantedBy: string;
-}
-
-/** Directory rows are closed-field: existence, name, slug — nothing else (§2.8). */
-export interface DirectoryEntry {
-  readonly id: string;
-  readonly name: string;
-  readonly slug: string;
-}
-
-type Tx = Pick<Db, 'insert' | 'select' | 'update' | 'delete'>;
-type GrantRow = typeof hierarchyGrants.$inferSelect;
-
-const NOT_FOUND: HierarchyCommandFailure = { ok: false, error: 'not_found' };
-
-function conflict(message: string): HierarchyCommandFailure {
-  return { ok: false, error: 'conflict', message };
-}
-
-function grantTarget(row: GrantRow): { kind: GrantTargetKind; id: string } {
-  if (row.companyId) return { kind: 'company', id: row.companyId };
-  if (row.estateId) return { kind: 'estate', id: row.estateId };
-  return { kind: 'platform_project', id: row.platformProjectId as string };
-}
-
-/** Grant event snapshot (contract 2 §4.4): subject, target, namespaced role, grantor. */
-function grantSnapshot(row: GrantRow): Record<string, unknown> {
-  const target = grantTarget(row);
-  return {
-    id: row.id,
-    subject: { userId: row.userId },
-    target: { kind: target.kind, id: target.id },
-    role: namespacedHierarchyRole(row.role as HierarchyGrantRole),
-    grantedBy: row.grantedBy,
-  };
-}
-
-function grantView(row: GrantRow): GrantView {
-  const target = grantTarget(row);
-  return {
-    id: row.id,
-    userId: row.userId as string,
-    targetKind: target.kind,
-    targetId: target.id,
-    role: namespacedHierarchyRole(row.role as HierarchyGrantRole),
-    grantedBy: row.grantedBy,
-  };
-}
-
-function companyView(row: typeof companies.$inferSelect): CompanyView {
-  return { id: row.id, name: row.name, slug: row.slug, visibility: row.visibility };
-}
-
-interface CommandContext {
-  readonly actorId: string;
-  readonly idempotencyKey: string;
-  readonly correlationId: string;
-}
-
-@Injectable()
-export class HierarchyRepository {
-  constructor(@Inject(DB) private readonly db: Db) {}
-
-  private async run<T>(
-    idempotencyKey: string | undefined,
-    actorId: string,
-    body: (tx: Tx, ctx: CommandContext) => Promise<HierarchyResult<T>>,
-  ): Promise<HierarchyResult<T>> {
-    const ctx: CommandContext = {
-      actorId,
-      idempotencyKey: idempotencyKey ?? randomUUID(),
-      correlationId: randomUUID(),
-    };
-    try {
-      return await this.db.transaction(async (tx) => body(tx, ctx));
-    } catch (error) {
-      // A key replayed with different content aborts the whole command —
-      // the transaction (state change included) has rolled back (§6.4).
-      if (error instanceof HierarchyAuditIdempotencyConflictError) {
-        return conflict(error.message);
-      }
-      throw error;
-    }
-  }
-
-  private async requireOwner(
-    tx: Tx,
-    actorId: string,
-    kind: GrantTargetKind,
-    id: string,
-  ): Promise<boolean> {
-    return roleAtLeast(await evaluateEffectiveRole(tx, actorId, kind, id), 'owner');
-  }
-
-  private async isPlatformAdmin(tx: Tx, actorId: string): Promise<boolean> {
-    const rows = await tx
-      .select({ role: users.role })
-      .from(users)
-      .where(eq(users.id, actorId))
-      .limit(1);
-    return rows[0]?.role === 'admin';
-  }
-
-  // ── companies ────────────────────────────────────────────────────────────
-
-  /**
-   * Any authenticated user may create a company; the same audited operation
-   * writes the creator's initial owner grant (§4.3), causation-linked to the
-   * create event. Visibility is always 'private' — the command takes no
-   * visibility input (§5.5).
-   */
-  createCompany(input: {
-    actorId: string;
-    name: string;
-    slug: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ company: CompanyView; grant: GrantView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      const inserted = await tx
-        .insert(companies)
-        .values({ name: input.name, slug: input.slug })
-        .onConflictDoNothing()
-        .returning();
-      const company = inserted[0];
-      if (!company) return conflict('company slug already exists');
-
-      const grantRows = await tx
-        .insert(hierarchyGrants)
-        .values({
-          userId: ctx.actorId,
-          companyId: company.id,
-          role: 'owner',
-          grantedBy: ctx.actorId,
-        })
-        .returning();
-      const grant = grantRows[0] as GrantRow;
-
-      const snapshot = await buildNodeSnapshot(tx, 'company', company.id);
-      const created = await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'create',
-        targetKind: 'company',
-        targetId: company.id,
-        targetSnapshot: { ...snapshot },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'grant_create',
-        targetKind: 'grant',
-        targetId: grant.id,
-        targetSnapshot: grantSnapshot(grant),
-        correlationId: ctx.correlationId,
-        causationId: created.event.id,
-        idempotencyKey: `${ctx.idempotencyKey}:grant`,
-      });
-      return { ok: true, company: companyView(company), grant: grantView(grant) };
-    });
-  }
-
-  renameCompany(input: {
-    actorId: string;
-    companyId: string;
-    name: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ company: CompanyView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (!(await this.requireOwner(tx, ctx.actorId, 'company', input.companyId))) {
-        return NOT_FOUND;
-      }
-      const rows = await tx
-        .select()
-        .from(companies)
-        .where(eq(companies.id, input.companyId))
-        .limit(1);
-      const previous = rows[0];
-      if (!previous) return NOT_FOUND;
-
-      const updated = await tx
-        .update(companies)
-        .set({ name: input.name, updatedAt: new Date() })
-        .where(eq(companies.id, input.companyId))
-        .returning();
-      const company = updated[0] as typeof companies.$inferSelect;
-
-      const snapshot = await buildNodeSnapshot(tx, 'company', company.id);
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'rename',
-        targetKind: 'company',
-        targetId: company.id,
-        targetSnapshot: { ...snapshot, previousName: previous.name },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return { ok: true, company: companyView(company) };
-    });
-  }
-
-  /**
-   * Admin-only until the company-CRUD capability ratifies (§5.5) — the one
-   * hierarchy mutation a platform admin performs without a grant. A
-   * non-admin caller (owner included) gets `forbidden` before any company
-   * read: the refusal reveals nothing about the target's existence.
-   */
-  changeCompanyVisibility(input: {
-    actorId: string;
-    companyId: string;
-    visibility: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ company: CompanyView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (!(await this.isPlatformAdmin(tx, ctx.actorId))) {
-        return {
-          ok: false,
-          error: 'forbidden',
-          message: 'visibility change is platform-admin-only',
-        };
-      }
-      const rows = await tx
-        .select()
-        .from(companies)
-        .where(eq(companies.id, input.companyId))
-        .limit(1);
-      const previous = rows[0];
-      if (!previous) return NOT_FOUND;
-
-      const updated = await tx
-        .update(companies)
-        .set({ visibility: input.visibility, updatedAt: new Date() })
-        .where(eq(companies.id, input.companyId))
-        .returning();
-      const company = updated[0] as typeof companies.$inferSelect;
-
-      const snapshot = await buildNodeSnapshot(tx, 'company', company.id);
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'visibility_change',
-        targetKind: 'company',
-        targetId: company.id,
-        // Old and new values are event content (§5.5).
-        targetSnapshot: {
-          ...snapshot,
-          previousVisibility: previous.visibility,
-          visibility: company.visibility,
-        },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return { ok: true, company: companyView(company) };
-    });
-  }
-
-  deleteCompany(input: {
-    actorId: string;
-    companyId: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ deletedId: string }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (!(await this.requireOwner(tx, ctx.actorId, 'company', input.companyId))) {
-        return NOT_FOUND;
-      }
-      const children = await tx
-        .select({ id: estates.id })
-        .from(estates)
-        .where(eq(estates.companyId, input.companyId))
-        .limit(1);
-      if (children.length > 0) return conflict('company still has estates');
-
-      // Snapshot and grants are read before the delete; target FKs cascade
-      // the grant rows, and each cascaded deletion is audited (§5.2).
-      const snapshot = await buildNodeSnapshot(tx, 'company', input.companyId);
-      const grants = await tx
-        .select()
-        .from(hierarchyGrants)
-        .where(eq(hierarchyGrants.companyId, input.companyId));
-
-      await tx.delete(companies).where(eq(companies.id, input.companyId));
-
-      const deleted = await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'delete',
-        targetKind: 'company',
-        targetId: input.companyId,
-        targetSnapshot: { ...snapshot },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      for (const grant of grants) {
-        await appendHierarchyEvent(tx, {
-          actorId: ctx.actorId,
-          verb: 'grant_revoke',
-          targetKind: 'grant',
-          targetId: grant.id,
-          targetSnapshot: grantSnapshot(grant),
-          correlationId: ctx.correlationId,
-          causationId: deleted.event.id,
-          idempotencyKey: `${ctx.idempotencyKey}:revoke:${grant.id}`,
-        });
-      }
-      return { ok: true, deletedId: input.companyId };
-    });
-  }
-
-  // ── estates ──────────────────────────────────────────────────────────────
-
-  /** Child creation requires owner on the parent and confers no grant (§4.3). */
-  createEstate(input: {
-    actorId: string;
-    companyId: string;
-    name: string;
-    slug: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ estate: NodeView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (!(await this.requireOwner(tx, ctx.actorId, 'company', input.companyId))) {
-        return NOT_FOUND;
-      }
-      const inserted = await tx
-        .insert(estates)
-        .values({ companyId: input.companyId, name: input.name, slug: input.slug })
-        .onConflictDoNothing()
-        .returning();
-      const estate = inserted[0];
-      if (!estate) return conflict('estate slug already exists in company');
-
-      const snapshot = await buildNodeSnapshot(tx, 'estate', estate.id);
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'create',
-        targetKind: 'estate',
-        targetId: estate.id,
-        targetSnapshot: { ...snapshot },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return { ok: true, estate: { id: estate.id, name: estate.name, slug: estate.slug } };
-    });
-  }
-
-  renameEstate(input: {
-    actorId: string;
-    estateId: string;
-    name: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ estate: NodeView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', input.estateId))) {
-        return NOT_FOUND;
-      }
-      const rows = await tx.select().from(estates).where(eq(estates.id, input.estateId)).limit(1);
-      const previous = rows[0];
-      if (!previous) return NOT_FOUND;
-
-      const updated = await tx
-        .update(estates)
-        .set({ name: input.name })
-        .where(eq(estates.id, input.estateId))
-        .returning();
-      const estate = updated[0] as typeof estates.$inferSelect;
-
-      const snapshot = await buildNodeSnapshot(tx, 'estate', estate.id);
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'rename',
-        targetKind: 'estate',
-        targetId: estate.id,
-        targetSnapshot: { ...snapshot, previousName: previous.name },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return { ok: true, estate: { id: estate.id, name: estate.name, slug: estate.slug } };
-    });
-  }
-
-  /** Transfer requires effective owner on BOTH parents, evaluated in the transfer's own transaction (§5). */
-  transferEstate(input: {
-    actorId: string;
-    estateId: string;
-    destinationCompanyId: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ estate: NodeView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      const rows = await tx.select().from(estates).where(eq(estates.id, input.estateId)).limit(1);
-      const estate = rows[0];
-      if (!estate) return NOT_FOUND;
-      if (!(await this.requireOwner(tx, ctx.actorId, 'company', estate.companyId))) {
-        return NOT_FOUND;
-      }
-      if (!(await this.requireOwner(tx, ctx.actorId, 'company', input.destinationCompanyId))) {
-        return NOT_FOUND;
-      }
-      if (estate.companyId === input.destinationCompanyId) {
-        return conflict('estate already belongs to the destination company');
-      }
-      const collision = await tx
-        .select({ id: estates.id })
-        .from(estates)
-        .where(
-          and(eq(estates.companyId, input.destinationCompanyId), eq(estates.slug, estate.slug)),
-        )
-        .limit(1);
-      if (collision.length > 0) return conflict('destination company already has that estate slug');
-
-      const parents = await tx
-        .select({ id: companies.id, slug: companies.slug })
-        .from(companies)
-        .where(inArray(companies.id, [estate.companyId, input.destinationCompanyId]));
-      const source = parents.find((p) => p.id === estate.companyId);
-      const destination = parents.find((p) => p.id === input.destinationCompanyId);
-      if (!source || !destination) return NOT_FOUND;
-
-      await tx
-        .update(estates)
-        .set({ companyId: input.destinationCompanyId })
-        .where(eq(estates.id, input.estateId));
-
-      const snapshot = await buildNodeSnapshot(tx, 'estate', input.estateId);
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'transfer',
-        targetKind: 'estate',
-        targetId: input.estateId,
-        targetSnapshot: { ...snapshot },
-        transferFrom: { kind: 'company', id: source.id, slug: source.slug },
-        transferTo: { kind: 'company', id: destination.id, slug: destination.slug },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return { ok: true, estate: { id: estate.id, name: estate.name, slug: estate.slug } };
-    });
-  }
-
-  deleteEstate(input: {
-    actorId: string;
-    estateId: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ deletedId: string }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', input.estateId))) {
-        return NOT_FOUND;
-      }
-      const children = await tx
-        .select({ id: platformProjects.id })
-        .from(platformProjects)
-        .where(eq(platformProjects.estateId, input.estateId))
-        .limit(1);
-      if (children.length > 0) return conflict('estate still has platform projects');
-
-      const snapshot = await buildNodeSnapshot(tx, 'estate', input.estateId);
-      const grants = await tx
-        .select()
-        .from(hierarchyGrants)
-        .where(eq(hierarchyGrants.estateId, input.estateId));
-
-      await tx.delete(estates).where(eq(estates.id, input.estateId));
-
-      const deleted = await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'delete',
-        targetKind: 'estate',
-        targetId: input.estateId,
-        targetSnapshot: { ...snapshot },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      for (const grant of grants) {
-        await appendHierarchyEvent(tx, {
-          actorId: ctx.actorId,
-          verb: 'grant_revoke',
-          targetKind: 'grant',
-          targetId: grant.id,
-          targetSnapshot: grantSnapshot(grant),
-          correlationId: ctx.correlationId,
-          causationId: deleted.event.id,
-          idempotencyKey: `${ctx.idempotencyKey}:revoke:${grant.id}`,
-        });
-      }
-      return { ok: true, deletedId: input.estateId };
-    });
-  }
-
-  // ── platform projects ────────────────────────────────────────────────────
-
-  createPlatformProject(input: {
-    actorId: string;
-    estateId: string;
-    name: string;
-    slug: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ platformProject: NodeView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', input.estateId))) {
-        return NOT_FOUND;
-      }
-      const inserted = await tx
-        .insert(platformProjects)
-        .values({ estateId: input.estateId, name: input.name, slug: input.slug })
-        .onConflictDoNothing()
-        .returning();
-      const project = inserted[0];
-      if (!project) return conflict('platform project slug already exists in estate');
-
-      const snapshot = await buildNodeSnapshot(tx, 'platform_project', project.id);
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'create',
-        targetKind: 'platform_project',
-        targetId: project.id,
-        targetSnapshot: { ...snapshot },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return {
-        ok: true,
-        platformProject: { id: project.id, name: project.name, slug: project.slug },
-      };
-    });
-  }
-
-  renamePlatformProject(input: {
-    actorId: string;
-    platformProjectId: string;
-    name: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ platformProject: NodeView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (
-        !(await this.requireOwner(tx, ctx.actorId, 'platform_project', input.platformProjectId))
-      ) {
-        return NOT_FOUND;
-      }
-      const rows = await tx
-        .select()
-        .from(platformProjects)
-        .where(eq(platformProjects.id, input.platformProjectId))
-        .limit(1);
-      const previous = rows[0];
-      if (!previous) return NOT_FOUND;
-
-      const updated = await tx
-        .update(platformProjects)
-        .set({ name: input.name })
-        .where(eq(platformProjects.id, input.platformProjectId))
-        .returning();
-      const project = updated[0] as typeof platformProjects.$inferSelect;
-
-      const snapshot = await buildNodeSnapshot(tx, 'platform_project', project.id);
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'rename',
-        targetKind: 'platform_project',
-        targetId: project.id,
-        targetSnapshot: { ...snapshot, previousName: previous.name },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return {
-        ok: true,
-        platformProject: { id: project.id, name: project.name, slug: project.slug },
-      };
-    });
-  }
-
-  transferPlatformProject(input: {
-    actorId: string;
-    platformProjectId: string;
-    destinationEstateId: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ platformProject: NodeView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      const rows = await tx
-        .select()
-        .from(platformProjects)
-        .where(eq(platformProjects.id, input.platformProjectId))
-        .limit(1);
-      const project = rows[0];
-      if (!project) return NOT_FOUND;
-      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', project.estateId))) {
-        return NOT_FOUND;
-      }
-      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', input.destinationEstateId))) {
-        return NOT_FOUND;
-      }
-      if (project.estateId === input.destinationEstateId) {
-        return conflict('platform project already belongs to the destination estate');
-      }
-      const collision = await tx
-        .select({ id: platformProjects.id })
-        .from(platformProjects)
-        .where(
-          and(
-            eq(platformProjects.estateId, input.destinationEstateId),
-            eq(platformProjects.slug, project.slug),
-          ),
-        )
-        .limit(1);
-      if (collision.length > 0) {
-        return conflict('destination estate already has that platform project slug');
-      }
-
-      const parents = await tx
-        .select({ id: estates.id, slug: estates.slug })
-        .from(estates)
-        .where(inArray(estates.id, [project.estateId, input.destinationEstateId]));
-      const source = parents.find((p) => p.id === project.estateId);
-      const destination = parents.find((p) => p.id === input.destinationEstateId);
-      if (!source || !destination) return NOT_FOUND;
-
-      await tx
-        .update(platformProjects)
-        .set({ estateId: input.destinationEstateId })
-        .where(eq(platformProjects.id, input.platformProjectId));
-
-      const snapshot = await buildNodeSnapshot(tx, 'platform_project', input.platformProjectId);
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'transfer',
-        targetKind: 'platform_project',
-        targetId: input.platformProjectId,
-        targetSnapshot: { ...snapshot },
-        transferFrom: { kind: 'estate', id: source.id, slug: source.slug },
-        transferTo: { kind: 'estate', id: destination.id, slug: destination.slug },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return {
-        ok: true,
-        platformProject: { id: project.id, name: project.name, slug: project.slug },
-      };
-    });
-  }
-
-  deletePlatformProject(input: {
-    actorId: string;
-    platformProjectId: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ deletedId: string }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (
-        !(await this.requireOwner(tx, ctx.actorId, 'platform_project', input.platformProjectId))
-      ) {
-        return NOT_FOUND;
-      }
-      const children = await tx
-        .select({ id: workspaces.id })
-        .from(workspaces)
-        .where(eq(workspaces.platformProjectId, input.platformProjectId))
-        .limit(1);
-      if (children.length > 0) return conflict('platform project still has workspaces');
-
-      const snapshot = await buildNodeSnapshot(tx, 'platform_project', input.platformProjectId);
-      const grants = await tx
-        .select()
-        .from(hierarchyGrants)
-        .where(eq(hierarchyGrants.platformProjectId, input.platformProjectId));
-
-      await tx.delete(platformProjects).where(eq(platformProjects.id, input.platformProjectId));
-
-      const deleted = await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'delete',
-        targetKind: 'platform_project',
-        targetId: input.platformProjectId,
-        targetSnapshot: { ...snapshot },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      for (const grant of grants) {
-        await appendHierarchyEvent(tx, {
-          actorId: ctx.actorId,
-          verb: 'grant_revoke',
-          targetKind: 'grant',
-          targetId: grant.id,
-          targetSnapshot: grantSnapshot(grant),
-          correlationId: ctx.correlationId,
-          causationId: deleted.event.id,
-          idempotencyKey: `${ctx.idempotencyKey}:revoke:${grant.id}`,
-        });
-      }
-      return { ok: true, deletedId: input.platformProjectId };
-    });
-  }
-
-  // ── grants ───────────────────────────────────────────────────────────────
-
-  /** Grant management requires effective owner on the target (§4.1). */
-  createGrant(input: {
-    actorId: string;
-    userId: string;
-    targetKind: GrantTargetKind;
-    targetId: string;
-    role: HierarchyGrantRole;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ grant: GrantView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      if (!(await this.requireOwner(tx, ctx.actorId, input.targetKind, input.targetId))) {
-        return NOT_FOUND;
-      }
-      const subject = await tx
-        .select({ id: users.id })
-        .from(users)
-        .where(eq(users.id, input.userId))
-        .limit(1);
-      if (subject.length === 0) return conflict('subject user does not exist');
-
-      const inserted = await tx
-        .insert(hierarchyGrants)
-        .values({
-          userId: input.userId,
-          companyId: input.targetKind === 'company' ? input.targetId : null,
-          estateId: input.targetKind === 'estate' ? input.targetId : null,
-          platformProjectId: input.targetKind === 'platform_project' ? input.targetId : null,
-          role: input.role,
-          grantedBy: ctx.actorId,
-        })
-        .onConflictDoNothing()
-        .returning();
-      const grant = inserted[0];
-      if (!grant) return conflict('grant already exists');
-
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'grant_create',
-        targetKind: 'grant',
-        targetId: grant.id,
-        targetSnapshot: grantSnapshot(grant),
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return { ok: true, grant: grantView(grant) };
-    });
-  }
-
-  changeGrant(input: {
-    actorId: string;
-    grantId: string;
-    role: HierarchyGrantRole;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ grant: GrantView }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      const rows = await tx
-        .select()
-        .from(hierarchyGrants)
-        .where(eq(hierarchyGrants.id, input.grantId))
-        .limit(1);
-      const existing = rows[0];
-      if (!existing) return NOT_FOUND;
-      const target = grantTarget(existing);
-      if (!(await this.requireOwner(tx, ctx.actorId, target.kind, target.id))) {
-        return NOT_FOUND;
-      }
-      // Team subjects are suspended (§1.4); the command surface never
-      // creates them, so this only fires on out-of-band rows.
-      if (!existing.userId) return conflict('team grant subjects are suspended');
-      if (existing.role === input.role) return conflict('grant already holds that role');
-
-      const duplicate = await tx
-        .select({ id: hierarchyGrants.id })
-        .from(hierarchyGrants)
-        .where(
-          and(
-            eq(hierarchyGrants.userId, existing.userId),
-            target.kind === 'company'
-              ? eq(hierarchyGrants.companyId, target.id)
-              : target.kind === 'estate'
-                ? eq(hierarchyGrants.estateId, target.id)
-                : eq(hierarchyGrants.platformProjectId, target.id),
-            eq(hierarchyGrants.role, input.role),
-          ),
-        )
-        .limit(1);
-      if (duplicate.length > 0) {
-        return conflict('subject already holds that role on the target');
-      }
-
-      const updated = await tx
-        .update(hierarchyGrants)
-        .set({ role: input.role })
-        .where(eq(hierarchyGrants.id, input.grantId))
-        .returning();
-      const grant = updated[0] as GrantRow;
-
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'grant_change',
-        targetKind: 'grant',
-        targetId: grant.id,
-        targetSnapshot: {
-          ...grantSnapshot(grant),
-          previousRole: namespacedHierarchyRole(existing.role as HierarchyGrantRole),
-        },
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return { ok: true, grant: grantView(grant) };
-    });
-  }
-
-  /** Revocation is row deletion (§6): the next evaluation denies, nothing lingers. */
-  revokeGrant(input: {
-    actorId: string;
-    grantId: string;
-    idempotencyKey?: string;
-  }): Promise<HierarchyResult<{ revokedId: string }>> {
-    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
-      const rows = await tx
-        .select()
-        .from(hierarchyGrants)
-        .where(eq(hierarchyGrants.id, input.grantId))
-        .limit(1);
-      const existing = rows[0];
-      if (!existing) return NOT_FOUND;
-      const target = grantTarget(existing);
-      if (!(await this.requireOwner(tx, ctx.actorId, target.kind, target.id))) {
-        return NOT_FOUND;
-      }
-
-      await tx.delete(hierarchyGrants).where(eq(hierarchyGrants.id, input.grantId));
-
-      await appendHierarchyEvent(tx, {
-        actorId: ctx.actorId,
-        verb: 'grant_revoke',
-        targetKind: 'grant',
-        targetId: existing.id,
-        targetSnapshot: grantSnapshot(existing),
-        correlationId: ctx.correlationId,
-        idempotencyKey: ctx.idempotencyKey,
-      });
-      return { ok: true, revokedId: existing.id };
-    });
-  }
-
-  // ── reads ────────────────────────────────────────────────────────────────
-
-  /**
-   * The directory: every directory-class company, closed-field (§2.8). The
-   * sole ratified existence-disclosure carve-out (§6.7 / A2 §9.1.2).
-   */
-  async listDirectory(): Promise<DirectoryEntry[]> {
-    return this.db
-      .select({ id: companies.id, name: companies.name, slug: companies.slug })
-      .from(companies)
-      .where(eq(companies.visibility, 'directory'))
-      .orderBy(asc(companies.name));
-  }
-
-  /** Companies the user holds any grant on (company or descendant, §2.8). */
-  async listGrantedCompanies(userId: string): Promise<CompanyView[]> {
-    const ids = await grantedCompanyIds(this.db, userId);
-    if (ids.length === 0) return [];
-    const rows = await this.db
-      .select()
-      .from(companies)
-      .where(inArray(companies.id, ids))
-      .orderBy(asc(companies.name));
-    return rows.map(companyView);
-  }
-}

apps/gateway/src/hierarchy/hierarchy.service.ts

@@ -1,31 +0,0 @@
-import {
-  ConflictException,
-  ForbiddenException,
-  Injectable,
-  NotFoundException,
-} from '@nestjs/common';
-import type { HierarchyCommandFailure, HierarchyResult } from './hierarchy.repository.js';
-
-/**
- * Maps repository result unions onto HTTP exceptions. `not_found` carries
- * one fixed message for every cause — missing node and unauthorized caller
- * are indistinguishable on the wire (contract 1 §6.7).
- */
-@Injectable()
-export class HierarchyService {
-  unwrap<T>(result: HierarchyResult<T>): T {
-    if (result.ok) return result;
-    throw this.toException(result);
-  }
-
-  private toException(failure: HierarchyCommandFailure): Error {
-    switch (failure.error) {
-      case 'not_found':
-        return new NotFoundException('hierarchy node not found');
-      case 'forbidden':
-        return new ForbiddenException(failure.message);
-      case 'conflict':
-        return new ConflictException(failure.message);
-    }
-  }
-}

apps/gateway/src/mcp/mcp.service.spec.ts

@@ -176,18 +176,7 @@ describe('MCP actor identity and tool scope enforcement', () => {
     ).toBe(false);
     expect(
       deriveMcpToolScopesForUser({ role: 'platform-admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
-    ).toBe(false);
-  });
-
-  it('derives no scope elevation from any platform role (contract 2 §1.1 bypass retirement)', () => {
-    const memberScopes = deriveMcpToolScopesForUser({ role: 'member' });
-    for (const role of ['admin', 'platform-admin', 'super-admin', null, undefined]) {
-      const scopes = deriveMcpToolScopesForUser({ role });
-      expect([...scopes].sort()).toEqual([...memberScopes].sort());
-      expect(scopes.has(MCP_TOOL_SCOPES.brain_create_task)).toBe(false);
-      expect(scopes.has(MCP_TOOL_SCOPES.brain_update_task)).toBe(false);
-      expect(scopes.has(MCP_TOOL_SCOPES.coord_list_tasks)).toBe(false);
-    }
+    ).toBe(true);
   });
 
   it('fails closed when scopes are not supplied by the authenticated context policy', () => {
@@ -322,20 +311,14 @@ describe('MCP actor identity and tool scope enforcement', () => {
     ]);
   });
 
-  it('gives admin-role and platform-admin-role actors only owned content on brain reads (§1.1 retirement)', async () => {
-    // Contract 2 §1.1: users.role confers no content visibility. An actor whose
-    // role is 'admin', 'platform-admin', or 'super-admin' but who holds no
-    // ownership sees exactly what an unprivileged member with the same
-    // ownership would see — here, only the one project they own, and nothing
-    // tenant-wide or platform-wide.
-    const fixtures = {
+  it('enforces tenant boundaries for tenant-admin brain project, mission, and task reads', async () => {
+    const { service } = makeService({
       projects: [
-        { id: 'project-owned', ownerId: 'role-bearing-user', teamId: 'tenant-a', name: 'owned' },
         {
           id: 'project-tenant-a',
           ownerId: 'other-user-a',
           teamId: 'tenant-a',
-          name: 'same tenant, unowned',
+          name: 'same tenant',
         },
         {
           id: 'project-tenant-b',
@@ -345,50 +328,39 @@ describe('MCP actor identity and tool scope enforcement', () => {
         },
       ],
       missions: [
-        { id: 'mission-owned', projectId: 'project-owned' },
         { id: 'mission-tenant-a', tenantId: 'tenant-a', projectId: 'project-tenant-a' },
         { id: 'mission-tenant-b', tenantId: 'tenant-b', projectId: 'project-tenant-b' },
       ],
       tasks: [
-        { id: 'task-owned', projectId: 'project-owned', status: 'not-started' },
         { id: 'task-tenant-a', projectId: 'project-tenant-a', status: 'not-started' },
         { id: 'task-tenant-b', projectId: 'project-tenant-b', status: 'not-started' },
       ],
-    };
+    });
+    const { server, tools } = makeCapturingServer();
+    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
 
-    const actors = [
-      makeAdminActor('role-bearing-user', 'tenant-a'),
-      makePlatformAdminActor('role-bearing-user'),
-    ];
+    service.registerTools(server, actor);
 
-    for (const actor of actors) {
-      const { service } = makeService(fixtures);
-      const { server, tools } = makeCapturingServer();
-      service.registerTools(server, actor);
+    const projects = JSON.parse(
+      (await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
+    );
+    expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-tenant-a']);
 
-      const projects = JSON.parse(
-        (await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
-      );
-      expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-owned']);
+    const missions = JSON.parse(
+      (await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
+    );
+    expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-tenant-a']);
 
-      const missions = JSON.parse(
-        (await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
-      );
-      expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-owned']);
-
-      const tasks = JSON.parse(
-        (await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
-      );
-      expect(tasks.map((task: { id: string }) => task.id)).toEqual(['task-owned']);
-    }
+    const tasks = JSON.parse(
+      (await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
+    );
+    expect(tasks.map((task: { id: string }) => task.id)).toEqual(['task-tenant-a']);
   });
 
   it('denies tenant-admin task writes outside the authenticated tenant', async () => {
     const { service, brain } = makeService({
       projects: [
-        // §1.1 retirement: content visibility comes from ownership, not the
-        // tenant-admin role — the acting user owns the tenant-a project.
-        { id: 'project-tenant-a', ownerId: 'tenant-admin-user', teamId: 'tenant-a' },
+        { id: 'project-tenant-a', ownerId: 'other-user-a', teamId: 'tenant-a' },
         { id: 'project-tenant-b', ownerId: 'other-user-b', teamId: 'tenant-b' },
       ],
       missions: [
@@ -401,29 +373,7 @@ describe('MCP actor identity and tool scope enforcement', () => {
       ],
     });
     const { server, tools } = makeCapturingServer();
-    // Platform role no longer derives task-write scopes (§1.1 retirement):
-    // a role-derived admin actor is scope-denied before any tenant logic.
-    const roleDerivedAdmin = makeAdminActor('tenant-admin-user', 'tenant-a');
-    service.registerTools(server, roleDerivedAdmin);
-    await expect(
-      getTool(tools, 'brain_create_task').handler({ title: 'role-derived write' }),
-    ).rejects.toThrow('MCP tool scope denied');
-    expect(brain.tasks.create).not.toHaveBeenCalled();
-
-    // The tenant-scoping checks below sit behind the scope gate; exercise
-    // them with explicitly granted task-write scopes (how grant-mapped
-    // scopes will arrive), not with a platform role.
-    tools.clear();
-    const actor = createMcpActorContext({
-      userId: 'tenant-admin-user',
-      tenantId: 'tenant-a',
-      role: 'member',
-      scopes: [
-        ...deriveMcpToolScopesForUser({ role: 'member' }),
-        MCP_TOOL_SCOPES.brain_create_task,
-        MCP_TOOL_SCOPES.brain_update_task,
-      ],
-    });
+    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
 
     service.registerTools(server, actor);
 
@@ -466,7 +416,7 @@ describe('MCP actor identity and tool scope enforcement', () => {
     );
   });
 
-  it('denies coordination tools to every role-derived actor and keeps the granted path server-derived', async () => {
+  it('keeps admin-only coordination tools on server-derived paths', async () => {
     const { service, coord } = makeService();
     const { server, tools } = makeCapturingServer();
     const member = makeMemberActor('authenticated-user');
@@ -483,25 +433,10 @@ describe('MCP actor identity and tool scope enforcement', () => {
     const tenantAdminTool = getTool(tools, 'coord_list_tasks');
     await expect(tenantAdminTool.handler({})).rejects.toThrow('MCP tool scope denied: coord:read');
 
-    // §1.1 retirement: platform-admin no longer derives coord scopes either.
     tools.clear();
     service.registerTools(server, platformAdmin);
     const platformAdminTool = getTool(tools, 'coord_list_tasks');
-    await expect(platformAdminTool.handler({})).rejects.toThrow(
-      'MCP tool scope denied: coord:read',
-    );
-
-    // An explicitly granted coord:read scope reaches the server-derived
-    // path (caller-supplied projectPath is stripped by the schema).
-    tools.clear();
-    const grantedActor = createMcpActorContext({
-      userId: 'granted-user',
-      role: 'member',
-      scopes: [MCP_TOOL_SCOPES.coord_list_tasks],
-    });
-    service.registerTools(server, grantedActor);
-    const grantedTool = getTool(tools, 'coord_list_tasks');
-    await grantedTool.handler({ projectPath: '/tmp/victim' });
+    await platformAdminTool.handler({ projectPath: '/tmp/victim' });
     expect(coord.listTasks).toHaveBeenCalledWith(process.cwd());
   });
 

apps/gateway/src/mcp/mcp.service.ts

@@ -63,6 +63,20 @@ interface SessionEntry {
   actor: McpActorContext;
 }
 
+const GLOBAL_ADMIN_MCP_SCOPES = new Set<McpToolScope>(Object.values(MCP_TOOL_SCOPES));
+const TENANT_ADMIN_MCP_SCOPES = new Set<McpToolScope>([
+  MCP_TOOL_SCOPES.brain_list_projects,
+  MCP_TOOL_SCOPES.brain_get_project,
+  MCP_TOOL_SCOPES.brain_list_tasks,
+  MCP_TOOL_SCOPES.brain_create_task,
+  MCP_TOOL_SCOPES.brain_update_task,
+  MCP_TOOL_SCOPES.brain_list_missions,
+  MCP_TOOL_SCOPES.brain_list_conversations,
+  MCP_TOOL_SCOPES.memory_search,
+  MCP_TOOL_SCOPES.memory_get_preferences,
+  MCP_TOOL_SCOPES.memory_save_preference,
+  MCP_TOOL_SCOPES.memory_save_insight,
+]);
 const MEMBER_MCP_SCOPES = new Set<McpToolScope>([
   MCP_TOOL_SCOPES.brain_list_projects,
   MCP_TOOL_SCOPES.brain_get_project,
@@ -75,17 +89,15 @@ const MEMBER_MCP_SCOPES = new Set<McpToolScope>([
   MCP_TOOL_SCOPES.memory_save_insight,
 ]);
 
-/**
- * Contract 2 §1.1: platform role confers NO MCP scope elevation — the
- * former tenant-admin/global-admin scope sets keyed on users.role are
- * retired. Every authenticated user receives the base member set; task
- * writes and coordination scopes attach to explicit hierarchy grants when
- * the MCP grant mapping lands, never to a platform role. The role
- * parameter is kept for caller compatibility and deliberately ignored.
- */
-export function deriveMcpToolScopesForUser(_input: {
+export function deriveMcpToolScopesForUser(input: {
   role?: string | null;
 }): ReadonlySet<McpToolScope> {
+  if (input.role === 'platform-admin' || input.role === 'super-admin') {
+    return new Set(GLOBAL_ADMIN_MCP_SCOPES);
+  }
+  if (input.role === 'admin') {
+    return new Set(TENANT_ADMIN_MCP_SCOPES);
+  }
   return new Set(MEMBER_MCP_SCOPES);
 }
 
@@ -156,22 +168,41 @@ type TaskLike = TenantScopedLike & {
   userId?: string | null;
 };
 
-/**
- * Contract 2 §1.1: `users.role` confers NO content visibility — the former
- * global-admin/tenant-admin filter short-circuits keyed on the platform role
- * are retired along with the role-derived scope sets. Content reaches an MCP
- * actor through ownership only; widened access arrives as explicit hierarchy
- * grants when the MCP grant mapping lands.
- */
+function isGlobalAdminActor(actor: McpActorContext): boolean {
+  return actor.role === 'platform-admin' || actor.role === 'super-admin';
+}
+
+function isTenantAdminActor(actor: McpActorContext): boolean {
+  return actor.role === 'admin';
+}
+
+function matchesTenant(actor: McpActorContext, record: TenantScopedLike): boolean {
+  return (
+    record.tenantId === actor.tenantId ||
+    record.organizationId === actor.tenantId ||
+    record.teamId === actor.tenantId
+  );
+}
+
 function filterProjectsForActor<T extends ProjectLike>(actor: McpActorContext, projects: T[]): T[] {
-  return projects.filter((project) => project.ownerId === actor.userId);
+  if (isGlobalAdminActor(actor)) return projects;
+  return projects.filter(
+    (project) =>
+      project.ownerId === actor.userId ||
+      (isTenantAdminActor(actor) && matchesTenant(actor, project)),
+  );
 }
 
 function filterMissionsByDirectActorScope<T extends MissionLike>(
   actor: McpActorContext,
   missions: T[],
 ): T[] {
-  return missions.filter((mission) => mission.userId === actor.userId);
+  if (isGlobalAdminActor(actor)) return missions;
+  return missions.filter(
+    (mission) =>
+      mission.userId === actor.userId ||
+      (isTenantAdminActor(actor) && matchesTenant(actor, mission)),
+  );
 }
 
 function scopesEqual(left: ReadonlySet<McpToolScope>, right: ReadonlySet<McpToolScope>): boolean {
@@ -262,6 +293,7 @@ export class McpService implements OnModuleDestroy {
   }
 
   private async isProjectAuthorized(actor: McpActorContext, projectId: string): Promise<boolean> {
+    if (isGlobalAdminActor(actor)) return true;
     const project = (await this.brain.projects.findById(projectId)) as ProjectLike | undefined;
     return project ? filterProjectsForActor(actor, [project]).length === 1 : false;
   }
@@ -270,6 +302,8 @@ export class McpService implements OnModuleDestroy {
     actor: McpActorContext,
     missions: T[],
   ): Promise<T[]> {
+    if (isGlobalAdminActor(actor)) return missions;
+
     const projects = (await this.brain.projects.findAll()) as ProjectLike[];
     const projectIds = new Set(
       filterProjectsForActor(actor, projects).map((project) => project.id),
@@ -283,6 +317,7 @@ export class McpService implements OnModuleDestroy {
   }
 
   private async isMissionAuthorized(actor: McpActorContext, missionId: string): Promise<boolean> {
+    if (isGlobalAdminActor(actor)) return true;
     const mission = (await this.brain.missions.findById(missionId)) as MissionLike | undefined;
     if (!mission) return false;
     return (await this.filterMissionsForActor(actor, [mission])).length === 1;
@@ -304,7 +339,7 @@ export class McpService implements OnModuleDestroy {
     actor: McpActorContext,
     refs: { projectId?: string | null; missionId?: string | null },
   ): Promise<void> {
-    if (!refs.projectId && !refs.missionId) {
+    if (!isGlobalAdminActor(actor) && !refs.projectId && !refs.missionId) {
       throw new Error('MCP task scope denied');
     }
     await this.assertTaskReferencesAuthorized(actor, refs);
@@ -314,6 +349,8 @@ export class McpService implements OnModuleDestroy {
     actor: McpActorContext,
     tasks: T[],
   ): Promise<T[]> {
+    if (isGlobalAdminActor(actor)) return tasks;
+
     const [projects, missions] = await Promise.all([
       this.brain.projects.findAll(),
       this.brain.missions.findAll(),
@@ -330,6 +367,7 @@ export class McpService implements OnModuleDestroy {
     return tasks.filter(
       (task) =>
         task.userId === actor.userId ||
+        (isTenantAdminActor(actor) && matchesTenant(actor, task)) ||
         (typeof task.projectId === 'string' && projectIds.has(task.projectId)) ||
         (typeof task.missionId === 'string' && missionIds.has(task.missionId)),
     );

apps/gateway/src/validation-pipe-check.ts

@@ -1,18 +1,6 @@
 import 'reflect-metadata';
 import { getMetadataStorage } from 'class-validator';
 import { BootstrapSetupDto } from './admin/bootstrap.dto.js';
-import {
-  ChangeCompanyVisibilityDto,
-  ChangeGrantDto,
-  CreateCompanyDto,
-  CreateEstateDto,
-  CreateGrantDto,
-  CreatePlatformProjectDto,
-  DeleteNodeDto,
-  RenameNodeDto,
-  TransferEstateDto,
-  TransferPlatformProjectDto,
-} from './hierarchy/hierarchy.dto.js';
 
 /**
  * Boot-time self-check: the global ValidationPipe must be able to SEE the
@@ -55,56 +43,6 @@ export const PIPE_GUARDED_DTOS: Array<{
     target: BootstrapSetupDto,
     properties: ['name', 'email', 'password'],
   },
-  {
-    name: 'CreateCompanyDto',
-    target: CreateCompanyDto,
-    properties: ['name', 'slug', 'idempotencyKey'],
-  },
-  {
-    name: 'RenameNodeDto',
-    target: RenameNodeDto,
-    properties: ['name', 'idempotencyKey'],
-  },
-  {
-    name: 'ChangeCompanyVisibilityDto',
-    target: ChangeCompanyVisibilityDto,
-    properties: ['visibility', 'idempotencyKey'],
-  },
-  {
-    name: 'DeleteNodeDto',
-    target: DeleteNodeDto,
-    properties: ['idempotencyKey'],
-  },
-  {
-    name: 'CreateEstateDto',
-    target: CreateEstateDto,
-    properties: ['companyId', 'name', 'slug', 'idempotencyKey'],
-  },
-  {
-    name: 'CreatePlatformProjectDto',
-    target: CreatePlatformProjectDto,
-    properties: ['estateId', 'name', 'slug', 'idempotencyKey'],
-  },
-  {
-    name: 'TransferEstateDto',
-    target: TransferEstateDto,
-    properties: ['destinationCompanyId', 'idempotencyKey'],
-  },
-  {
-    name: 'TransferPlatformProjectDto',
-    target: TransferPlatformProjectDto,
-    properties: ['destinationEstateId', 'idempotencyKey'],
-  },
-  {
-    name: 'CreateGrantDto',
-    target: CreateGrantDto,
-    properties: ['userId', 'targetKind', 'targetId', 'role', 'idempotencyKey'],
-  },
-  {
-    name: 'ChangeGrantDto',
-    target: ChangeGrantDto,
-    properties: ['role', 'idempotencyKey'],
-  },
 ];
 
 export class PipeMetatypeCheckError extends Error {

docs/requirements/mode-conversion.md

@@ -1,279 +0,0 @@
-# Deployment Mode and Conversion Contract (D3)
-
-Status: DRAFT — awaiting ratification (webui-audit S2, contract 6 of 9).
-Authority: PRD D3 (Part I §3) — two modes chosen at install time,
-Standalone and Enterprise, with the mode table (brains, user-data
-isolation, secrets, conversion); Standalone → Enterprise conversion is
-**one-way** and Enterprise is a **terminal state**. PRD D14 (Part I §7)
-— the per-user brain split is optional in Standalone and keeping it is
-the recommended default because it preserves forward-compatibility with
-the one-way conversion. PRD D11 (Part I §9) — v1 ships the Standalone
-flow only; Enterprise conversion is explicitly deferred. PRD D3
-federation clause — federation is intentionally not fully designed,
-deferred, and nothing in v1 may foreclose it.
-
-Revision 2 (luna review F1–F7): the identity precondition restated in
-identity-contract terms with a conversion-local acknowledgment record
-this contract owns (F1); a durable, keyed preparation state with a
-Standalone-safe representation rule, an in-transaction re-check fence,
-and an exact flip boundary (F2); the §5.4 unknown-value rule stated
-directly without the contradictory non-exhaustiveness clause (F3); the
-D14 boundary bound here with a stable column-allowlist witness instead
-of delegated to an unratified layout (F4); the conversion witness
-matrix extended to every §4.2/§4.4 condition (F5); the mode-record
-writer coverage imported concretely from contract 1 §6.3 with a named
-schema, closed writer set, crafted-write probe, and mode-resolution
-assertion (F6); the mode read command flagged as a §12.1 drafting
-addition rather than a D8 mandate (F7). Ownership language aligned
-with contract 3 revision 2: mode is recorded at bootstrap and read by
-the wizard as input.
-
-This contract binds the mode as a canonical platform property (§2), the
-per-mode obligations and which contract owns each (§3), the conversion
-transition (§4), the v1 non-foreclosure obligations (§5), and their
-witnesses (§6). Domain semantics stay with their owning contracts:
-wizard branching (contract 3 §2), identity/SSO
-(`identity-lifecycle.md`), custody and per-user brain mechanics
-(contract 7, `custody-schema.md`), tool mapping
-(`tool-gateway-mapping.md`).
-
-## 1. Definitions
-
-1. **Mode**: the platform-wide deployment mode, exactly one of
-   `standalone` or `enterprise`. The vocabulary is closed in v1;
-   extension (e.g. a federation mode) is by amendment to this contract,
-   never ad hoc.
-2. **Conversion**: the one-way transition `standalone → enterprise`.
-   No other mode transition exists.
-3. **Conversion preconditions**: the verifiable conditions of §4.2 that
-   must all hold before the mode record may change.
-4. **Preparation unit**: one re-runnable piece of pre-conversion work —
-   the migration of one secret to the Vault backend, or the partition
-   of one user's brain content (§4.3).
-
-## 2. Mode is a canonical recorded property
-
-1. Mode is recorded canonically in the platform database at bootstrap
-   as the operator's install-time choice (D3: modes are "chosen at
-   install time"). The record is a single-row keyed record
-   (`platform_mode`: mode value, recorded-at timestamp, bootstrap epoch
-   reference); this contract owns it, the bootstrap writer performs the
-   one v1 write (§6.2), and the wizard reads it as input (contract 3
-   §2.3). Mode is never derived from feature state (presence of Vault,
-   count of brains, count of users), and no component may infer a
-   different mode than the record states.
-2. The record is readable by any authenticated user through a Gateway
-   command with CLI exposure. This read command is a **drafting
-   addition** ratified with this contract (PRD §12.1), not a D8
-   mandate: D8 binds only that any surface exposing the value goes
-   through official tooling. When a webUI surface consumes the read, a
-   mapping row is added to `tool-gateway-mapping.md` by amendment —
-   the same route §4.4 already binds for the conversion command.
-   Components branch on the read value only.
-3. The record is immutable except by the §4 conversion transition.
-   Editing it by direct database access, config file, environment
-   variable, or wizard re-run is non-conformant (contract 3 §2.3:
-   changing mode later is conversion, not a wizard re-run).
-
-## 3. Per-mode obligations (owner map)
-
-The PRD mode table binds four rows; this contract assigns each an
-owning contract so no obligation is unowned and none is bound twice:
-
-| Obligation          | Standalone                             | Enterprise                                         | Owner                                         |
-| ------------------- | -------------------------------------- | -------------------------------------------------- | --------------------------------------------- |
-| Brains              | one mosaic-brain (system + user files) | system brain for config + one brain per user       | contract 7 (custody/brain mechanics)          |
-| User-data isolation | single user                            | no user-data leakage between users; sharing opt-in | contract 7 (enforced by architecture, D14)    |
-| Secrets             | OpenBao/Vault or flat files            | OpenBao/Vault REQUIRED                             | this contract (§4.2 gate; steady-state check) |
-| Conversion          | may convert to Enterprise, one-way     | terminal state                                     | this contract (§4)                            |
-
-The Standalone brains row states the default layout, not the only
-valid one: the D14 per-user split is a MAY in Standalone with keeping
-it the recommended default (PRD §7, contract 7 §6), and Vault-backed
-secrets are equally valid Standalone configuration. Both prepared
-states are therefore themselves valid Standalone states — the fact
-§4.3 relies on.
-
-In Enterprise steady state, a flat-file secrets backend is
-non-conformant; the platform refuses to start Enterprise-mode
-components against a flat-file secrets configuration (fail-closed, not
-warn-and-run).
-
-## 4. Conversion transition
-
-1. **Direction and terminality.** The only transition is
-   `standalone → enterprise`. `enterprise → standalone` does not exist:
-   there is no command, no admin override, and no support path. An
-   attempt is refused with the precondition/state error class of the
-   command envelope (`tool-gateway-mapping.md` §4.2).
-2. **Preconditions (all verified before the record changes):**
-   - Secrets: OpenBao/Vault is configured and reachable, and every
-     required secret is served from the Vault backend — none from a
-     flat-file backend. Secret migration completes before conversion;
-     this contract does not define the migration tooling, only the
-     gate.
-   - Brains: the per-user brain split required by the Enterprise row of
-     §3 is established for **every** existing user (or the deployment
-     already kept the split, the D14 recommended default). Brain
-     partitioning mechanics are contract 7; this contract binds only
-     that the split is complete before the mode flips.
-   - Identity: at least one platform administrator account exists that
-     is active in identity-contract terms — authenticated capability,
-     not banned, not deactivated (identity §2, §5). And the conversion
-     request carries a **configuration acknowledgment**: the current
-     canonical values of registration mode and per-provider JIT
-     enablement (identity §2.2, §4.1), echoed back in the request. A
-     mismatch between the echoed values and the canonical values at
-     verification refuses the conversion. This acknowledgment record
-     is conversion-local, owned by this contract, and stored with the
-     §4.4 audit event as the precondition evidence; it adds no
-     identity-contract obligation and no mode-specific identity
-     default — identity's own defaults remain valid states.
-3. **Preparation state and the flip boundary.** Preparatory work is
-   tracked durably: each preparation unit (§1.4) records its
-   completion in a preparation table keyed by (bootstrap epoch, unit
-   identity — the secret's path, the user's id), written in the same
-   transaction as the unit's own effect where the unit's backend
-   allows it, and reconciled from the backend's actual state where it
-   does not (a secret already served by Vault, a brain already split,
-   is complete regardless of the table). Units are at-most-once per
-   key and re-runnable across attempts. **Standalone-safe
-   representation:** every preparation unit moves the deployment into
-   a state that is itself valid Standalone configuration (§3 note), so
-   an interrupted preparation leaves a fully operational Standalone
-   deployment reading its state through the ordinary contracts — no
-   rollback, fencing, or special Standalone read path is needed, and
-   no component behavior may key on "preparation in progress".
-   **The flip:** one transaction that (a) locks the mode record, (b)
-   re-verifies every §4.2 precondition after acquiring the lock, and
-   (c) writes the mode record and the §4.4 audit event. Any re-check
-   failure aborts with no write. External state that changes after the
-   re-check but before commit is bounded by the transaction window;
-   an external backend (Vault) failing after conversion is an
-   Enterprise runtime fault handled by §3's fail-closed steady-state
-   rule, not a conversion defect. An interrupted or failed conversion
-   leaves the record `standalone` and the platform fully operational;
-   there is no intermediate mode and no half-converted state
-   observable through the record.
-4. **Authority and audit.** Conversion is a platform-administrator
-   command carrying an explicit irreversibility acknowledgment in its
-   request (distinct from the §4.2 configuration acknowledgment). It
-   is an official Gateway/CLI command (D8): when built, it is added to
-   the tool↔Gateway mapping by amendment (`tool-gateway-mapping.md`
-   §3.3). The transition emits an audit event (actor, prior mode, new
-   mode, precondition evidence reference including the configuration
-   acknowledgment) in the same transaction as the record change; the
-   event survives indefinitely. A refused attempt emits a refusal
-   event naming the failed precondition class and actor, with no
-   mode-change event.
-
-## 5. v1 obligations (non-foreclosure)
-
-v1 ships Standalone only (D11); the conversion command is deferred
-work. v1 still MUST:
-
-1. Record the mode per §2 at bootstrap, with `enterprise` a reserved,
-   refused value for bootstrap — v1 bootstrap accepts `standalone`
-   only. The wizard reads the record (contract 3 §2.3); nothing in v1
-   writes it after bootstrap.
-2. Keep the §2.3 immutability rule: no v1 surface mutates the mode
-   record.
-3. Not foreclose conversion: the v1 platform database holds no
-   sensitive user content — sensitive categories live in the owning
-   user's brain, and postgres holds structure, consent records, and
-   pointers only (the D14 boundary, PRD §7). Custody mechanics are
-   contract 7's; this contract binds the boundary itself here so v1
-   cannot ship a layout that makes the §4.2 brain precondition
-   unsatisfiable, and §6.3 gives it a stable witness that does not
-   depend on contract 7's internals. Conversion implementation
-   additionally requires contract 7 ratified.
-4. Not foreclose federation: v1 components accept exactly the two §1.1
-   values wherever a mode value is parsed and refuse any other value
-   **before side effects** — a refused configuration, not undefined
-   behavior and not a crash mid-operation. Forward compatibility lives
-   in storage and architecture, not in parser speculation: the mode
-   record's storage is not structurally locked to two values (no
-   database-level two-value enum), and any future value (e.g. a
-   federation mode) is defined by a versioned amendment to this
-   contract before any component accepts it. The PRD defers
-   federation's shape entirely; this contract does not presume it
-   arrives as a third mode value.
-
-## 6. Verification requirements
-
-Binding on the implementing PRs:
-
-1. **Mode-record witness (v1):** after bootstrap the mode is readable
-   via the Gateway command and CLI and equals the bootstrap-recorded
-   choice; bootstrap with mode `enterprise` is refused; bootstrap with
-   any unknown mode value is refused before side effects (§5.4).
-2. **Writer-coverage witness (v1):** the mode record's writer set is
-   closed by the same three-prong static assertion contract 1 §6.3(b)
-   defines — symbol, class-table literal, and raw-execution prongs
-   with its allowlist composition rules — scoped to the
-   `platform_mode` table, with a writer allowlist containing exactly
-   the bootstrap writer in v1 (and exactly plus the conversion command
-   at the conversion milestone). Companions: a crafted direct write
-   attempted in a test fails and leaves the record unchanged; a
-   mode-resolution assertion that no shipped component derives mode
-   from feature state (mode reads occur only through the §2.2 read
-   surface — static assertion over Gateway, CLI, bootstrap, and
-   repository sources).
-3. **D14-boundary witness (v1):** a column-allowlist assertion in the
-   style of contract 1 §6.2 that the platform database schema contains
-   no sensitive-content column — the §5.3 boundary — stable regardless
-   of contract 7's internals (contract 7 §7 carries the full custody
-   witnesses).
-4. **No-downgrade witness (conversion milestone):** with mode
-   `enterprise`, a conversion request to `standalone` (and any crafted
-   mode-write) is refused with the precondition/state error class and
-   no record change.
-5. **Precondition witnesses (conversion milestone),** each refused
-   with no record change and no partial mode effect, parameterized
-   over both OpenBao and Vault where secrets are involved:
-   (a) secrets backend unreachable; (b) one required secret still
-   flat-file backed (migration incomplete); (c) one unpartitioned user
-   brain in a **multi-user** deployment where every other user is
-   partitioned; (d) no active platform administrator (the only admin
-   banned or deactivated); (e) configuration acknowledgment missing or
-   mismatching the canonical registration/JIT values; (f) actor not a
-   platform administrator (authorization refusal); (g) irreversibility
-   acknowledgment absent. And the steady-state rule: an
-   Enterprise-mode component started against a flat-file secrets
-   configuration refuses to start (§3).
-6. **Interruption and fence witnesses (conversion milestone):** fault
-   injection aborting conversion after each preparation unit and
-   between preparation and flip leaves the record `standalone` and the
-   platform operational in Standalone semantics (§4.3
-   Standalone-safety), and a re-attempt completes without duplicating
-   prepared state (at-most-once keys); a precondition invalidated
-   after preparation but before the flip (a secret reverted to
-   flat-file) is caught by the in-transaction re-check and refused.
-7. **Audit witnesses (conversion milestone):** a completed conversion
-   has exactly one mode-change audit event, same-transaction with the
-   record change (transaction linkage asserted), carrying actor, prior
-   mode, new mode, and the precondition evidence reference including
-   the configuration acknowledgment; a failed attempt has a refusal
-   event naming the failed precondition class and no mode-change
-   event; the mode-change event remains queryable after subsequent
-   unrelated audit activity (retention probe).
-8. **Mapping witness (conversion milestone):** the conversion command
-   and the mode read command each have their
-   `tool-gateway-mapping.md` row (added by amendment per §2.2/§4.4)
-   before the commands ship.
-
-## Ruling request
-
-Ratify sections 1–6 as written, with one decision embedded:
-
-- Decision (§5): v1 implements the **mode record and its immutability
-  only** — bootstrap records `standalone`, the `enterprise` value is
-  reserved and refused, and the conversion command itself is deferred
-  to the Enterprise milestone, consistent with D11's deferred list.
-  v1 carries three obligations beyond the record: the closed writer
-  assertion, the D14 column boundary, and the unknown-value refusal
-  (§6.1–§6.3) — these are the non-foreclosure floor, not hidden
-  conversion work. Alternative if rejected: build the conversion
-  command inside v1 — rejected because D11 scopes v1 to the Standalone
-  slice and conversion depends on contract 7 custody mechanics that
-  are themselves not in the v1 slice.

docs/requirements/native-kanban-sot.md

@@ -514,47 +514,3 @@ itself permits, so that contract does not stretch A1 by interpretation.
    default-open disclosure.
 5. Every other constraint of A1 — §8.1.2's remaining bullets, §8.2 in full,
    and §8.3's other acceptance criteria — is untouched.
-
-## 10. Amendment A3 — capability-holder existence disclosure
-
-**Status:** amendment to Amendment A2, added by reviewed PR together with
-contract 2 Amendment 1 (`rbac-grant-model.md` §8, this PR), under that
-amendment's ruling request (decision owner Jason). It binds if and only if
-contract 2 Amendment 1 ratifies; until then §9.1.2's sole-disclosure rule
-stands unmodified — which is consistent, because until ratification the
-company-CRUD capability class is empty and the carve-out below has no
-holders. Everything in §§1–9 remains binding verbatim, with exactly the one
-express modification below. The detailed contract text lives in
-`rbac-grant-model.md` §8.1; this amendment changes only what A2 itself
-permits, so that contract does not stretch A2 by interpretation.
-
-### 10.1 What A3 modifies in A2
-
-1. **Capability-holder disclosure (narrows §9.1.2's sole-disclosure rule
-   by one carve-out).** §9.1.2 makes the directory the sole permitted
-   existence disclosure and keeps private companies undisclosed to
-   non-granted subjects everywhere. A3 admits exactly one further
-   disclosure channel: a subject holding the company-CRUD capability
-   (contract 2 §8), when exercising the hierarchy schema §5.5 visibility
-   command, learns the target company's existence and its old/new
-   visibility values through the command's redacted actor receipt —
-   success for an existing target (private or directory alike) versus
-   `not_found` for a nonexistent id — bounded exactly as contract 2 §8.1
-   states: no name, slug, structure, content, grant, or membership
-   information, and no read command of any kind. To every other
-   non-granted subject, private companies remain undisclosed everywhere,
-   including the directory; the directory remains the sole
-   existence-disclosure _listing_.
-
-### 10.2 What A3 explicitly does not change
-
-1. The directory itself is unchanged: read-only, directory-class companies
-   only, existence/name/slug only (§9.1.2's enumeration is narrowed for
-   capability holders' receipts, widened for nothing).
-2. No join-request surface, no curation listing, no read command of any
-   family is authorized (§9.2.2 unchanged; a curation listing is a further
-   amendment per contract 2 §8.1).
-3. The canonical audit event for visibility mutations is untouched — it
-   keeps hierarchy schema §5.2's full immutable target snapshot; the
-   capability confers no audit read (contract 2 §8.5).
-4. Every other constraint of A1 and A2 is untouched.

docs/requirements/rbac-grant-model.md

@@ -24,26 +24,6 @@ fail-closed-fault, and existence-oracle observables added (§7);
 role-string namespacing rule added (§4.5); ruling request now names the
 interpretive resolution of PRD "admins".
 
-Amendment 1 (company-CRUD capability): defines the capability class that
-contract 1 Amendment 1 (Ruling 4b, 2026-08-28) and hierarchy schema §5.5
-anticipate. §8 defines the capability as a platform-scoped, admin-assigned,
-audited delegation of exactly the hierarchy schema §5.5 company visibility
-command — no read command, no other company operation; the mutation's
-inherent existence disclosure is ratified as a bounded carve-out to
-hierarchy schema §6.7/§2.8 and to kanban SOT Amendment A2's
-sole-disclosure rule — SOT Amendment A3 (native-kanban-sot.md §10, this
-PR) expressly extends A2 by exactly this carve-out (§8.1). The holder
-sees only a redacted actor receipt; the canonical audit event keeps
-hierarchy schema §5.2's full immutable snapshot. The hierarchy role
-vocabulary (§2), every evaluation rule (§3), and grant management (§4) are
-untouched: the capability is not a `hierarchy_grants.role` value and
-evaluates outside the chain; capability-row deletion joins §6.1's
-revocation enumeration (§8.4). Until this amendment ratifies, the capability
-class is empty and
-the visibility command remains admin-only (hierarchy schema §5.5 states
-this fallback; the shipped gate at
-`apps/gateway/src/hierarchy/hierarchy.repository.ts` implements it).
-
 Scope: the roles that can appear in `hierarchy_grants.role`, what a grant at
 each hierarchy level confers, how grants evaluate down the chain, how
 revocation propagates, and who may manage grants. Out of scope: the hierarchy
@@ -262,191 +242,6 @@ contract 1 §6):
 8. Transfer: both-sides `owner` accepted, each single-side case refused
    (completing contract 1 §6.5).
 
-## 8. Company-CRUD capability (Amendment 1)
-
-Hierarchy schema §5.5 authorizes the company visibility mutation for
-exactly two actor classes: platform admins and "subjects holding the
-company-CRUD capability that a follow-up amendment to contract 2 will
-define". This section is that definition. The name is historical — coined
-in contract 1 Amendment 1 before the capability's content was fixed — and
-confers nothing by connotation: the ratified content is exactly §8.1.
-Company _creation_ is already ruled open to active users and always
-private (contract 3 §5.2, Ruling 4); rename, delete, and transfer of
-companies remain hierarchy `owner` operations (§2.3, §5); none of those is
-part of this capability, and widening it to any other operation is a
-further amendment, not an implementation decision.
-
-1. **Content: exactly one command, no read command, disclosure stated.**
-   Holding the capability authorizes executing the hierarchy schema §5.5
-   visibility command (`companies.visibility`, both directions:
-   `private → directory` and `directory → private`) on any company in the
-   deployment, and no other command of any family. It confers **no read
-   command**: no company enumeration, no curation listing, no structure
-   read. The practical flow this implies is deliberate: to publish a
-   private company, the holder is given the target identifier by the
-   requesting company `owner` out of band; to unpublish, the target is
-   already directory-listed. A curation listing for capability holders,
-   if ever wanted, is a further amendment with its own disclosure
-   analysis under hierarchy schema §6.7.
-
-   **Existence disclosure carve-out, stated rather than pretended away:**
-   exercising a mutation inherently discloses its target's existence.
-   The command's result distinguishes an existing company (success, for
-   private and directory targets alike) from a nonexistent id
-   (`not_found`), so a holder presenting candidate ids learns existence —
-   exactly as a platform admin already does through the same command.
-   This amendment ratifies that disclosure as part of the §5.5 curation
-   authority, bounded as follows. The holder-visible surface is the
-   command's **actor receipt** — the mutation result payload, carrying
-   exactly the target id, old visibility, and new visibility, and
-   **nothing else**: no name, slug, structure, content, grant, or
-   membership information. The actor receipt is a redacted projection
-   distinct from the **canonical audit event**, which is unchanged by
-   this amendment: it keeps hierarchy schema §5.2's deletion-safe
-   immutable target snapshot (id, slug, and parent chain at event time)
-   in full. The two never converge on the holder: the capability confers
-   no audit read (§8.5), so the canonical event — and with it the slug
-   and parent chain — is reachable only by subjects independently
-   authorized to read audit data, never through this capability. A
-   successful publish additionally makes the target directory-listed to
-   every authenticated user; that is the command's ratified purpose
-   (hierarchy schema §5.5), not a leak. Hierarchy schema §6.7's
-   existence-oracle rule and §2.8's directory-only disclosure are amended
-   by exactly this carve-out for capability holders, kanban SOT Amendment
-   A3 (native-kanban-sot.md §10, this PR) expressly extends A2's
-   sole-disclosure enumeration by the same carve-out, and all three are
-   otherwise untouched. Witnessed in §8.6.3.
-
-2. **Holding: platform-scoped assignment, user subjects only.** The
-   capability is not a hierarchy grant: it attaches to no node, has no
-   role, and never enters §3 chain evaluation. It is held via a
-   `platform_capabilities` table whose column set is exactly (nothing
-   else, per the contract 1 §2.7 exhaustiveness discipline):
-   - `id` — uuid, primary key;
-   - `user_id` — text, NOT NULL, FK `users` **ON DELETE RESTRICT**;
-   - `capability` — text, NOT NULL, constraint-checked against exactly
-     `company_crud`;
-   - `granted_by` — text, NOT NULL, FK `users` **ON DELETE RESTRICT**;
-   - `created_at` — timestamptz, NOT NULL;
-   - UNIQUE (`user_id`, `capability`).
-
-   The user FKs are **text**, not uuid, because `users.id` is a BetterAuth
-   text key (`packages/db/src/schema.ts`; custody schema records the same)
-   — PostgreSQL cannot reference a text primary key with a uuid column.
-   This matches the shipped `hierarchy_grants` shape exactly: uuid
-   surrogate `id`, text FKs to `users`.
-
-   Both user FKs are RESTRICT for the same reason contract 1 §3.3 pins
-   RESTRICT on principal FKs: the identity contract (§7.3) gates user
-   deletion, and a cascade here could silently destroy a capability
-   without its §8.3 revocation audit event. Revocation is row deletion
-   through the §8.3 command — there is no other removal path, no expiry
-   column, and no tombstone. A deactivated holder confers nothing while
-   deactivated: identity contract §7.1 denies all authorization to
-   deactivated accounts, and the §8.4 predicate evaluates on the
-   authenticated live user. No team subjects (§1.4's suspension reasoning
-   applies with more force here — a workspace-bound team holding
-   deployment-wide curation authority has no ratified meaning).
-
-3. **Assignment is instance administration on the normal admin surface.**
-   Only platform admins (`users.role = 'admin'`) may assign or revoke the
-   capability, through an ordinary admin command (the same command class
-   `AdminGuard` governs, §1.1) — not through direct table writes.
-   Assignment delegates a slice of instance administration and is itself
-   an instance-administration act under §1.1. A capability holder as such
-   may NOT assign or revoke it (no self-propagation). Every assignment
-   and revocation is a semantic audit event carrying actor, verb, subject
-   user, and capability; serialized capability strings are namespaced per
-   §4.5 (`platform-capability:company-crud` — a bare `company_crud` in
-   any serialized artifact is non-conformant).
-4. **Evaluation and revocation follow this contract's existing rules.**
-   The hierarchy schema §5.5 command's authorization predicate is:
-   `users.role = 'admin'` OR a live `platform_capabilities` row
-   (`user_id`, `company_crud`). Both disjuncts are evaluated live and
-   fail closed per §3.5 — **independently**: with capability state
-   unreadable (fault), the capability disjunct denies, but a platform
-   admin whose `users.role` is readable remains authorized through the
-   admin disjunct; with role state unreadable, the admin disjunct denies
-   likewise. A decision that can read neither denies. Capability-row
-   deletion is hereby added to §6.1's enumerated revocation paths:
-   it propagates identically, under §6.2's bound, on every transport —
-   no new HTTP/MCP command authorized by the deleted row after the
-   revoking transaction commits, and any cached authorization is
-   invalidated in the revoking transaction (§3.5).
-5. **What it does not confer**, stated so implementing PRs cannot drift:
-   no hierarchy grant or effective role at any node; no workspace
-   authorization or membership; no content, structure, or roll-up read;
-   no grant management (§4.1 unchanged); no MCP scope; no other instance
-   administration (user management, system settings, provider
-   configuration remain platform-admin-only); no company create, rename,
-   delete, or transfer. Hierarchy schema §5.5's rule that a company
-   `owner` as such may NOT change visibility is unchanged — `owner` and
-   this capability are disjoint authorities that combine only by a
-   subject holding both.
-6. **Verification requirements** (extends §7, binding on implementing
-   PRs):
-   1. Schema witnesses (real PostgreSQL, `ci-postgres` service in the
-      `test` CI step): the `capability` CHECK constraint rejects any
-      value outside `company_crud`; NOT NULL enforced on every declared
-      NOT NULL column; UNIQUE (`user_id`, `capability`) rejects a
-      duplicate; both user FKs reject a dangling reference AND deleting a
-      referenced user is refused (RESTRICT witnessed in both directions);
-      the table's column set is exactly the §8.2 declared set (contract 1
-      §6.2 discipline).
-   2. Capability-only command matrix — the witness that proves "exactly
-      one command", not merely "at least one": a non-admin holder with no
-      other grants succeeds on the visibility command in **both**
-      directions with contract 1 §5.2's audit event (old and new values
-      as semantic content), and the **same** actor is refused, case by
-      enumerated case: every hierarchy mutation family (company/child
-      create under another's node, rename, delete, transfer); grant
-      create/change/revoke; the workspace read and write command
-      families; roll-up reads; structure reads — including the
-      not-found-indistinguishable refusal on a structure read of the very
-      company they just mutated (hierarchy schema §6.7); every
-      instance-administration surface other than the visibility command
-      (user management, system settings, provider configuration, and
-      capability assign/revoke itself); and MCP scope derivation yields
-      nothing — the §7.4 deny-by-default matrix gains this row. Company
-      creation compares against an eligible-user baseline: the holder's
-      create behaves exactly as any active user's — always `private`,
-      and a creation request carrying a visibility argument is refused
-      for holder and baseline alike (contract 3 §5.2).
-   3. Disclosure bound (§8.1 carve-out witnessed, receipt and canonical
-      event separately): the mutation result for a private-valid target,
-      a directory-valid target, and a nonexistent id is exactly {success,
-      success, `not_found`}; the actor receipt for a success carries
-      exactly {target id, old visibility, new visibility} and no result
-      or error payload carries name, slug, structure, content, grant, or
-      membership data; the canonical audit event for the same mutation —
-      asserted directly against the hierarchy outbox, not through any
-      holder-facing surface — carries hierarchy schema §5.2's full
-      immutable snapshot (id, slug, parent chain); and the holder's
-      attempt to read audit data is refused (no audit read conferred,
-      §8.5), proving the receipt/event separation reaches the holder as
-      a redaction, not a weakened event.
-   4. Assignment path, both polarities: a platform admin assigns and
-      revokes through the normal admin command (positive witnesses —
-      assign then observe the §8.6.2 allow, revoke then observe deny); a
-      non-admin — including a current capability holder — is refused
-      assign and revoke; every assign/revoke produces its audit event
-      with the namespaced string (§8.3); a direct-write path that skips
-      the command surface is non-conformant (the §8.3 command is the only
-      writer of `platform_capabilities`).
-   5. Revocation joins the §7.6 matrix: assignment is decision-time-live
-      (capability assigned → the holder's next visibility command allows,
-      no re-login); after row deletion, the ex-holder's next visibility
-      command is refused **on every exposed transport**, measured with
-      the revocation and the decision on distinct physical connections; a
-      cached-authorization implementation proves transactional
-      invalidation (§3.5). Fail-closed fault witnesses, both disjuncts
-      (§8.4): with `platform_capabilities` unreadable, a non-admin holder
-      is denied while a platform admin remains authorized; with role
-      state unreadable, the admin disjunct denies.
-   6. Owner-as-such refusal re-witnessed: hierarchy schema §6.9's
-      owner-cannot-publish witness re-asserted with the
-      `platform_capabilities` table present and empty for that owner.
-
 ## Ruling request
 
 Ratify sections 1–7 as written, with one decision embedded and one
@@ -462,17 +257,3 @@ interpretive resolution named:
   platform admins. A1 §8.1.3 does not attribute grant declaration to
   platform admins, and the §1.1 decision above is what makes this reading
   binding.
-
-## Ruling request (Amendment 1)
-
-Ratify §8, the Amendment 1 header note, and kanban SOT Amendment A3
-(native-kanban-sot.md §10 — the express A2 carve-out extension, which
-binds only with this ratification) as written, with one decision
-embedded:
-
-- Decision: the company-CRUD capability is a platform-scoped,
-  admin-assigned, audited delegation of exactly the hierarchy schema §5.5
-  visibility command — no read command, no other company operation, with
-  the mutation's inherent existence disclosure ratified as a bounded
-  carve-out (§8.1). Say "agreed" or name the additional operations (or
-  the curation listing) you want it to carry.

docs/requirements/tool-gateway-mapping.md

@@ -1,197 +0,0 @@
-# Tool↔Gateway Mapping Contract (D8)
-
-Status: DRAFT — awaiting ratification (webui-audit S2, contract 5 of 9).
-Authority: PRD D8/D12 (Part I §8) — the webUI sits OVER official tooling:
-every webUI operation goes through the Gateway API backed by the same
-official framework tooling the CLI uses, and a webUI operation with no
-backing tool is scored **blocked on tooling** and the tool is built
-first. Measured input: the webui-audit A5 tooling baseline
-(operation-by-operation inventory of the current Gateway surface and the
-P1 gaps, cross-reviewed; `fleet/lanes/webui-audit/findings/
-A5-tooling-baseline.md` in the estate brain). The T10 ruling adopted the
-targeted-update plan including building the D8 tools in A5's rank order.
-
-Revision 2 (GLM review F1–F5): the §2 table completed against an
-independent re-measurement of the live `apps/web` surface (mission
-reads, coordination status, capability-gated `turn:send` added); rank-6
-composition corrected to ranks 1 and 4; SOT citations corrected to §3
-invariant 11 / REQ-TASK-001 / §5+A1; the §3.2 retirement clause
-softened to match what the owning contracts actually schedule; §6.1
-scoped to outbound calls with an extractability lint, and §6.3 given
-static companions for §4.1 and §4.3.
-
-This contract binds three things: the operation→tool mapping itself
-(§2–§3), the command envelope every mapped operation satisfies
-(§4), and the process rule that keeps the mapping closed (§5). Domain
-semantics stay with their owning contracts — hierarchy (contract 1,
-`hierarchy-schema.md`), grants (contract 2, `rbac-grant-model.md`),
-wizard (contract 3, `onboarding-wizard.md`), identity
-(`identity-lifecycle.md`), kanban lifecycle (`native-kanban-sot.md`
-§5 and Amendment A1), roll-up (contract 8), API artifact format
-(contract 9).
-
-## 1. Definitions
-
-1. **Official tool**: a command implemented in the framework packages and
-   exposed through the Gateway API; the CLI remains the primary execution
-   method for the same command (D8). The webUI is a Gateway client only.
-2. **Mapped operation**: a webUI operation with a named official path in
-   §2 or §3. Anything else the webUI wants to do is unmapped and follows
-   §5.
-3. **Legacy non-substitute**: an existing endpoint that resembles a P1
-   need but is contractually barred from backing it (§3.2).
-
-## 2. P0 mapping (current operations, ratified as-is)
-
-This table is the complete measured P0 surface: every Gateway call the
-web app's production sources make at this revision's head appears as a
-row (independently re-measured at review; the three calls the first
-measurement missed — mission reads, coordination status, and the
-capability-gated `turn:send` emit — are rows below). The surface stays
-bound to these paths:
-
-| WebUI operation                                                   | Official path                                                                                                                                                                                                                               |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Register / log in / log out / OIDC callback                       | better-auth mount `/api/auth/*`; `GET /api/sso/providers`                                                                                                                                                                                   |
-| List/show projects (legacy read)                                  | `GET /api/projects`, `GET /api/projects/:id`                                                                                                                                                                                                |
-| List tasks / task detail (legacy read)                            | `GET /api/tasks`, `GET /api/tasks/:id` — with the filtered legacy project/mission reads the same surfaces use                                                                                                                               |
-| Mission list (legacy read)                                        | `GET /api/missions`                                                                                                                                                                                                                         |
-| Coordination status (legacy read)                                 | `GET /api/coord/status`                                                                                                                                                                                                                     |
-| Conversation CRUD/search/messages                                 | `/api/conversations*`                                                                                                                                                                                                                       |
-| Chat turn / stop / thinking / command execute+approve / streaming | `/chat` socket events `message`, `abort`, `set:thinking`, `command:execute`, `command:approve`; `turn:send` (capability-gated — emitted only when the server advertises the pi turn-runtime capability, which the current Gateway does not) |
-| Harness/model selection                                           | `GET /api/harnesses*`, `GET/PUT /api/chat/preferences/selection`                                                                                                                                                                            |
-| Preferences; provider inspect/test                                | `/api/memory/preferences`, `GET /api/providers`, `POST /api/providers/test`                                                                                                                                                                 |
-| Admin users / roles / ban / health                                | `/api/admin/users*`, `/api/admin/health`                                                                                                                                                                                                    |
-
-P0 rows inherit §4 obligations as their backing controllers are next
-touched; they are not required to be retrofitted in one sweep.
-
-## 3. P1 mapping (bound to the build-first tools)
-
-1. Every P1 operation maps to exactly one build-first command family, in
-   the T10-ruled rank order:
-
-| Rank | Command family (owning contract)                                       | P1 webUI operations it backs                                                                                                                      |
-| ---- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1    | Hierarchy command family (contract 1 §5; grants attach per contract 2) | Company/estate/platform-project/workspace CRUD, parentage and reparenting, hierarchy reads; the wizard's initial-hierarchy step (contract 3 §3.4) |
-| 2    | Hierarchy RBAC command/evaluator (contract 2)                          | Grant create/change/revoke at company/estate/platform-project; inherited evaluation down to workspace; authorization-safe hierarchy queries       |
-| 3    | Typed kanban command/query surface (SOT §5, Amendment A1)              | Workspace task lifecycle (create/edit/cancel/archive/move), board rank, typed queries                                                             |
-| 4    | Agent enrollment command                                               | Enroll one agent: harness, credential reference/API-key intake (values never echoed), name/persona, assignment scope (contract 3 §3.5)            |
-| 5    | Authorized roll-up query (contract 8)                                  | Read-only aggregated task counts/statuses at every hierarchy level over readable workspaces only                                                  |
-| 6    | Onboarding orchestration (contract 3)                                  | The re-runnable wizard flow, composing ranks 1 and 4 (its only grant write rides inside the rank-1 company-create command, contract 2 §4.3)       |
-
-2. **Legacy non-substitutes.** The following MUST NOT back any P1
-   operation, matching the audit findings: legacy `/api/projects` and
-   `/api/tasks` CRUD (planning-data records, not hierarchy nodes and not
-   the typed kanban boundary); `POST /api/workspaces` (filesystem
-   bootstrap, not audited hierarchy parentage); `/api/teams` reads (no
-   grants, no inheritance); `POST /api/bootstrap/setup` (one-shot
-   epoch transition, identity §3 — not the re-runnable wizard); the MCP
-   `brain_*` task mutations (legacy Brain writes, not the typed kanban
-   commands). These stay serving their existing P0/host consumers until
-   the owning contract (or a successor amendment) schedules each
-   retirement — no such migration is scheduled at this revision; the
-   freeze stands on its own.
-3. New P1 mapping rows (operations this table does not list) are added by
-   amending this contract, not ad hoc (§5).
-
-## 4. Command envelope (request / result / error / audit)
-
-Binding on every mapped operation the build-first families expose:
-
-1. **Typed request and result.** Each command and query has an explicit
-   request DTO and result DTO in the shared types package, validated at
-   the Gateway boundary; unvalidated pass-through and `any`-typed
-   payloads are non-conformant. Mutations on records with an
-   expected-version rule in their owning contract carry the expected
-   version in the request and fail on mismatch with the conflict error
-   class (SOT §3 invariant 11 and REQ-TASK-001's concurrent-update
-   conflict acceptance; hierarchy per contract 1).
-2. **Error taxonomy.** Every error result carries a stable
-   machine-readable code from a closed per-family enum plus an HTTP
-   status mapping, distinguishing at minimum: validation failure,
-   authentication failure, authorization refusal, not-found, conflict
-   (version/uniqueness), precondition/state refusal (e.g. bootstrap
-   epoch, suspended team subjects), and internal fault. Where contract
-   2's no-existence-oracle rule applies, authorization refusal and
-   not-found are indistinguishable on the wire for unauthorized readers
-   — same code, same status, same shape.
-3. **Audit linkage.** A mutating mapped operation emits exactly the
-   audit events its owning contract defines (contract 1 §5.2, contract 2
-   §4.4, identity §§2–4, SOT audit rules); the envelope contributes the
-   correlation: every request accepts/generates a correlation id,
-   carried into the audit events and returned in the result, so a UI
-   action is traceable end to end. The mapping layer itself adds no
-   second audit stream.
-4. **Fail-closed.** A mapped operation that cannot evaluate its
-   authorization or reach its owning tool refuses (contract 2 §3.5); the
-   envelope never degrades to an unauthorized fallback read or a direct
-   data access.
-5. **CLI parity.** Each build-first family is invocable through the
-   official CLI against the same Gateway commands with the same
-   request/result/error contracts. No webUI-only command exists; a
-   Gateway command without CLI exposure is a conformance gap tracked at
-   the family's implementing issue.
-
-## 5. Closure rule (blocked on tooling)
-
-1. A webUI change that needs an operation with no mapping row is
-   **blocked on tooling**: the backing tool is built and mapped first
-   (D8). Scoring a gap "blocked on tooling" is mandatory, not
-   discretionary; working around it in the UI (direct DB or filesystem
-   access, calling a legacy non-substitute, embedding domain logic in
-   the web app) is non-conformant.
-2. The mapping is enforced closed by §6.1's inventory witness: the web
-   app's network surface must be a subset of the mapped paths.
-
-## 6. Verification requirements
-
-Binding on the implementing PRs:
-
-1. **Network-surface inventory witness:** a CI assertion extracting the
-   web app's outbound Gateway calls — route literals at request call
-   sites and outbound socket emits in `apps/web` sources (inbound
-   handler registrations are not calls and are out of scope) — and
-   failing on any call outside the §2/§3 mapped paths. The inventory is
-   closed like contract 1 §6.3's allowlist: a new call fails until a
-   mapping row exists in the same PR. Dynamic route construction that
-   evades extraction is resolved toward the witness, enforced by an
-   extractability lint: every request call site takes a literal or
-   template-literal path, and a call site that does not fails the
-   assertion itself (the web-side analogue of contract 1's
-   raw-execution prong), never an exemption for the caller.
-2. **Non-substitute witness:** the P1 surfaces (hierarchy, RBAC, kanban,
-   enrollment, roll-up, wizard UI) make zero calls to the §3.2 legacy
-   endpoints — asserted by the same inventory, scoped per surface.
-3. **Envelope witnesses per family:** for each build-first family — a
-   request with an invalid DTO is refused with the validation code; a
-   version-mismatch mutation returns the conflict code; an unauthorized
-   read of an existing node and a read of a nonexistent node return
-   indistinguishable results where the no-existence-oracle rule applies;
-   a correlation id submitted on a mutation appears in its audit
-   event(s) and result. Two static companions: a type-level assertion
-   that the family's boundary accepts no `any`-typed or unvalidated
-   pass-through payload (§4.1), and a single-emitter assertion that the
-   mapped operation's audit events originate only from the owning
-   contract's audit emitter (§4.3's no-second-audit-stream, made
-   checkable).
-4. **CLI-parity witness:** for each family, a CLI smoke invocation of at
-   least one command and one query against the Gateway succeeds with the
-   same typed result the web client receives.
-5. **Fail-closed witness:** with the owning tool or grant state
-   unreachable (fault injection), the mapped operation returns the
-   internal-fault or authorization-refusal class and performs no
-   fallback read/write (extends contract 2 §7.6 to the mapping layer).
-
-## Ruling request
-
-Ratify sections 1–6 as written, with one decision embedded:
-
-- Decision (§3.2): the legacy endpoints named there are **frozen for new
-  consumers** as of ratification — existing P0/host consumers keep
-  working, new UI or tool code may not call them, and each is retired by
-  the migration its owning contract schedules. Alternative if rejected:
-  allow P1 surfaces to reuse legacy endpoints as interim backends —
-  rejected by the audit's finding that they cannot satisfy the
-  hierarchy/kanban/RBAC contracts, so the interim would ship
-  non-conformant semantics.

packages/db/drizzle/0020_special_betty_brant.sql

@@ -1,5 +0,0 @@
-ALTER TABLE "hierarchy_audit_events" DROP CONSTRAINT "hierarchy_audit_events_verb_check";--> statement-breakpoint
-ALTER TABLE "companies" ADD COLUMN "visibility" text DEFAULT 'private' NOT NULL;--> statement-breakpoint
-ALTER TABLE "companies" ADD CONSTRAINT "companies_visibility_check" CHECK (visibility IN ('private', 'directory'));--> statement-breakpoint
-ALTER TABLE "hierarchy_audit_events" ADD CONSTRAINT "hierarchy_audit_events_verb_check" CHECK (verb IN ('create', 'rename', 'transfer', 'visibility_change', 'delete', 'grant_create', 'grant_change', 'grant_revoke'));--> statement-breakpoint
-ALTER TABLE "hierarchy_grants" ADD CONSTRAINT "hierarchy_grants_role_check" CHECK (role IN ('viewer', 'member', 'owner'));

packages/db/drizzle/meta/_journal.json

@@ -141,13 +141,6 @@
       "when": 1787880918208,
       "tag": "0019_volatile_killraven",
       "breakpoints": true
-    },
-    {
-      "idx": 20,
-      "version": "7",
-      "when": 1787963521142,
-      "tag": "0020_special_betty_brant",
-      "breakpoints": true
     }
   ]
 }

packages/db/src/hierarchy-schema.witness.test.ts

@@ -44,7 +44,7 @@ type AnyDb = {
 
 /** Column allowlist — the exact declared sets of §2/§3. Nothing else. */
 const COLUMN_ALLOWLIST: Record<string, string[]> = {
-  companies: ['id', 'name', 'slug', 'visibility', 'created_at', 'updated_at'],
+  companies: ['id', 'name', 'slug', 'created_at', 'updated_at'],
   estates: ['id', 'name', 'slug', 'company_id'],
   platform_projects: ['id', 'name', 'slug', 'estate_id'],
   workspaces: ['id', 'name', 'slug', 'platform_project_id'],
@@ -377,61 +377,7 @@ function witnessSuite(getHandle: () => AnyDb): void {
     // Control: same subject and target with a different role is a new grant.
     await db()
       .insert(hierarchyGrants)
-      .values({ userId: userA, companyId, role: 'member', grantedBy: userA });
-  });
-
-  // ── §2.6 role vocabulary CHECK ─────────────────────────────────────────────
-
-  it('refuses a grant role outside the ratified vocabulary, accepts each ratified role', async () => {
-    await expectViolation(
-      db()
-        .insert(hierarchyGrants)
-        .values({ userId: userB, companyId, role: 'superuser', grantedBy: userA }),
-      /check constraint/i,
-    );
-    // Serialized namespaced forms are storage-invalid too: rows hold bare roles.
-    await expectViolation(
-      db()
-        .insert(hierarchyGrants)
-        .values({ userId: userB, companyId, role: 'hierarchy:owner', grantedBy: userA }),
-      /check constraint/i,
-    );
-    for (const role of ['viewer', 'member', 'owner'] as const) {
-      await db()
-        .insert(hierarchyGrants)
-        .values({ userId: userB, estateId, role, grantedBy: userA });
-    }
-    await db().execute(
-      sql`DELETE FROM hierarchy_grants WHERE user_id = ${userB} AND estate_id = ${estateId}`,
-    );
-  });
-
-  // ── §2.8 visibility column ─────────────────────────────────────────────────
-
-  it('defaults companies.visibility to private and refuses values outside the class', async () => {
-    const visId = randomUUID();
-    await db().execute(
-      sql`INSERT INTO companies (id, name, slug) VALUES (${visId}, 'Vis', ${T + '-vis'})`,
-    );
-    const res = rows(await db().execute(sql`SELECT visibility FROM companies WHERE id = ${visId}`));
-    expect(res[0]!['visibility']).toBe('private');
-    await db().execute(
-      sql`INSERT INTO companies (id, name, slug, visibility) VALUES (${randomUUID()}, 'Vis D', ${T + '-vis-d'}, 'directory')`,
-    );
-    await expectViolation(
-      db().execute(
-        sql`INSERT INTO companies (id, name, slug, visibility) VALUES (${randomUUID()}, 'Vis X', ${T + '-vis-x'}, 'public')`,
-      ),
-      /check constraint/i,
-    );
-    await expectViolation(
-      db().execute(sql`UPDATE companies SET visibility = 'hidden' WHERE id = ${visId}`),
-      /check constraint/i,
-    );
-    await expectViolation(
-      db().execute(sql`UPDATE companies SET visibility = NULL WHERE id = ${visId}`),
-      /null value|not-null/i,
-    );
+      .values({ userId: userA, companyId, role: `${T}-other-role`, grantedBy: userA });
   });
 
   // ── §6.1 NOT NULLs ─────────────────────────────────────────────────────────
@@ -445,7 +391,7 @@ function witnessSuite(getHandle: () => AnyDb): void {
     );
     await expectViolation(
       db().execute(
-        sql`INSERT INTO hierarchy_grants (user_id, company_id, role, granted_by) VALUES (${userA}, ${companyId}, 'viewer', NULL)`,
+        sql`INSERT INTO hierarchy_grants (user_id, company_id, role, granted_by) VALUES (${userA}, ${companyId}, 'x', NULL)`,
       ),
       /null value|not-null/i,
     );

packages/db/src/hierarchy-writer-coverage.test.ts

@@ -135,9 +135,9 @@
  *     production code is anomalous and review-visible; that blind spot is
  *     accepted as a residual, not closed.
  *
- * The writer allowlist names hierarchy command/repository modules ONLY. Its
- * single entry is the M4-1b-ii hierarchy command repository — the sole
- * production module permitted to write the class tables. The infrastructure register
+ * The writer allowlist names hierarchy command/repository modules ONLY. It is
+ * empty today: the hierarchy command family (M4-1b-ii) has not landed, so no
+ * production module may write the class tables. The infrastructure register
  * holds legitimate non-hierarchy raw execution; registered modules are exempt
  * from prong (iii) only — prongs (i) and (ii) apply to them with no
  * exemption, and no registered module may appear on the writer allowlist.
@@ -181,15 +181,13 @@ const CLASS_TABLES = [
 
 /**
  * Writer allowlist (§6.3b): hierarchy command/repository modules only.
- * Adding a module here is a contract-conformance decision reviewed under
- * §5.1 — the module must be part of the Gateway hierarchy command path, and
- * it must not export a function that executes caller-supplied SQL.
+ * EMPTY until the hierarchy command family lands (M4-1b-ii; M4-1b-i ships
+ * only the audit/outbox machinery, which writes no class table). Adding a module
+ * here is a contract-conformance decision reviewed under §5.1 — the module
+ * must be part of the Gateway hierarchy command path, and it must not export
+ * a function that executes caller-supplied SQL.
  */
-const WRITER_ALLOWLIST: string[] = [
-  // The hierarchy command repository (M4-1b-ii): the sole class-table
-  // writer; every mutation is audited on its own transaction (§5.2).
-  'apps/gateway/src/hierarchy/hierarchy.repository.ts',
-];
+const WRITER_ALLOWLIST: string[] = [];
 
 /**
  * Infrastructure register: closed enumeration of legitimate non-hierarchy raw

packages/db/src/schema.ts

@@ -1063,24 +1063,13 @@ export const federationEnrollmentTokens = pgTable('federation_enrollment_tokens'
 // command family only (§5.1), enforced by the writer-coverage assertion
 // (§6.3b) — do not add writers outside that allowlist.
 
-/** Company visibility classes (contract 1 §2.8, Ruling 4b): 'private' is the
- * only creatable class (§5.5 — creation carries no visibility argument);
- * 'directory' discloses existence/name/slug to all users and is entered only
- * through the admin-gated visibility-change command. */
-export const COMPANY_VISIBILITY = ['private', 'directory'] as const;
-
-export const companies = pgTable(
-  'companies',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    name: text('name').notNull(),
-    slug: text('slug').notNull().unique(),
-    visibility: text('visibility').notNull().default('private'),
-    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-  },
-  () => [check('companies_visibility_check', sql`visibility IN ('private', 'directory')`)],
-);
+export const companies = pgTable('companies', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  name: text('name').notNull(),
+  slug: text('slug').notNull().unique(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+});
 
 export const estates = pgTable(
   'estates',
@@ -1121,10 +1110,6 @@ export const workspaces = pgTable(
   (t) => [unique('workspaces_platform_project_slug_uniq').on(t.platformProjectId, t.slug)],
 );
 
-/** Grant role vocabulary (contract 2 §2): totally ordered, viewer ⊂ member ⊂
- * owner. Order in this tuple IS the ordering — index = strength. */
-export const HIERARCHY_GRANT_ROLES = ['viewer', 'member', 'owner'] as const;
-
 export const hierarchyGrants = pgTable(
   'hierarchy_grants',
   {
@@ -1141,8 +1126,7 @@ export const hierarchyGrants = pgTable(
     platformProjectId: uuid('platform_project_id').references(() => platformProjects.id, {
       onDelete: 'cascade',
     }),
-    // Role vocabulary per contract 2 §2: exactly viewer ⊂ member ⊂ owner,
-    // totally ordered; CHECK below closes the column to that vocabulary.
+    // Role vocabulary and its CHECK constraint are contract 2 §2 (M4-2).
     role: text('role').notNull(),
     grantedBy: text('granted_by')
       .notNull()
@@ -1150,7 +1134,6 @@ export const hierarchyGrants = pgTable(
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   },
   (t) => [
-    check('hierarchy_grants_role_check', sql`role IN ('viewer', 'member', 'owner')`),
     check('hierarchy_grants_subject_check', sql`num_nonnulls(user_id, team_id) = 1`),
     check(
       'hierarchy_grants_target_check',
@@ -1187,7 +1170,6 @@ export const HIERARCHY_AUDIT_VERBS = [
   'create',
   'rename',
   'transfer',
-  'visibility_change',
   'delete',
   'grant_create',
   'grant_change',
@@ -1238,7 +1220,7 @@ export const hierarchyAuditEvents = pgTable(
     index('hierarchy_audit_events_correlation_idx').on(t.correlationId),
     check(
       'hierarchy_audit_events_verb_check',
-      sql`verb IN ('create', 'rename', 'transfer', 'visibility_change', 'delete', 'grant_create', 'grant_change', 'grant_revoke')`,
+      sql`verb IN ('create', 'rename', 'transfer', 'delete', 'grant_create', 'grant_change', 'grant_revoke')`,
     ),
     check(
       'hierarchy_audit_events_target_kind_check',

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--no-ci-expected] [--base-line BRANCH] [--co-author-trailers --escalate-to PRINCIPAL]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--no-ci-expected] [--co-author-trailers --escalate-to PRINCIPAL]
 
 set -euo pipefail
 
@@ -30,12 +30,6 @@ Options:
     -d, --delete-branch     Delete the head branch after merge
         --dry-run           Run metadata/login preflight without merging
         --expect-head SHA   Refuse unless the PR head matches this full commit SHA
-        --base-line BRANCH  Documented intra-line exception (B5, ruled
-                            2026-08-29): authorize a merge whose base is
-                            neither main nor next (stacked PR lines). The
-                            value must MATCH the PR base; all other gates
-                            (queue guard, head pin, CI) still run and the
-                            exception is recorded in the merge audit.
         --no-ci-expected    Assert the target repository has no CI: forward --no-ci-expected to the queue guard (requires repository admin)
         --co-author-trailers Build verified trailers from linked PR commit authors
         --escalate-to NAME  Named principal for an unresolved-author BLOCK
@@ -52,7 +46,6 @@ EOF
 }
 
 # Parse arguments
-BASE_LINE_OVERRIDE=""
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
@@ -71,11 +64,6 @@ while [[ $# -gt 0 ]]; do
             DRY_RUN=true
             shift
             ;;
-        --base-line)
-            [[ $# -ge 2 ]] || { echo "Error: --base-line requires a branch name." >&2; exit 1; }
-            BASE_LINE_OVERRIDE="$2"
-            shift 2
-            ;;
         --expect-head)
             if [[ $# -lt 2 ]]; then
                 echo "Error: --expect-head requires one full commit SHA." >&2
@@ -184,17 +172,8 @@ if [[ "$DECL_STATE" == valid && "$DECL_SCHEMA" == 2 ]]; then
 else
     repo_decl_warn_absent_irreversible "pr-merge"
     if [[ "$BASE_BRANCH" != "main" && "$BASE_BRANCH" != "next" ]]; then
-        if [[ -n "$BASE_LINE_OVERRIDE" && "$BASE_LINE_OVERRIDE" != "$BASE_BRANCH" ]]; then
-            echo "Error: --base-line '$BASE_LINE_OVERRIDE' does not match the PR base '$BASE_BRANCH' (refusing; the exception must name the real base)." >&2
-            exit 1
-        fi
-        if [[ "$BASE_LINE_OVERRIDE" == "$BASE_BRANCH" ]]; then
-            echo "audit: base-line exception — merge into '$BASE_BRANCH' authorized by explicit --base-line (B5 ruling 2026-08-29); queue guard, head pin, and CI gates unchanged." >&2
-        else
-            echo "Error: Mosaic policy allows merges only for PRs targeting 'main' or 'next' (found '$BASE_BRANCH')." >&2
-            echo "  A ruled intra-line merge may pass --base-line '$BASE_BRANCH' (same gates; the exception is recorded)." >&2
-            exit 1
-        fi
+        echo "Error: Mosaic policy allows merges only for PRs targeting 'main' or 'next' (found '$BASE_BRANCH')." >&2
+        exit 1
     fi
 fi
 if [[ -z "$HEAD_BRANCH" || -z "$HEAD_REPO" || ! "$HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then

packages/mosaic/framework/tools/git/test-pr-merge-baseline.sh

@@ -1,68 +0,0 @@
-#!/usr/bin/env bash
-# B5 (ruled 2026-08-29, orch-01-adopted): pr-merge --base-line — the
-# documented intra-line exception. Arms:
-#   1. Base neither main nor next, no flag: policy refusal (rc 1), queue
-#      guard NOT invoked, hint names the exception.
-#   2. Base neither main nor next, matching --base-line: authorized; the
-#      queue guard IS invoked with the same args (rc from the stub proves
-#      gates still run) and the audit line is emitted.
-#   3. Mismatched --base-line (different branch than the PR base): refusal
-#      rc 1 with the mismatch named; queue guard NOT invoked.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-baseline}"
-FIXTURE_DIR="$WORK_DIR/tools/git"
-CALL_LOG="$WORK_DIR/queue-call.log"
-OUT_LOG="$WORK_DIR/out.log"
-
-rm -rf "$WORK_DIR"
-mkdir -p "$FIXTURE_DIR"
-cp "$SCRIPT_DIR/pr-merge.sh" "$FIXTURE_DIR/pr-merge.sh"
-cp "$SCRIPT_DIR/detect-platform.sh" "$FIXTURE_DIR/detect-platform.sh"
-
-cat > "$FIXTURE_DIR/pr-metadata.sh" <<'SH'
-#!/usr/bin/env bash
-printf '%s\n' '{"baseRefName":"mosaic-cli-p0","baseRepository":"mosaicstack/stack","headRefName":"mosaic-cli-p2-socket-res","headRefOid":"0123456789abcdef0123456789abcdef01234567","headRepository":"mosaicstack/stack"}'
-SH
-
-cat > "$FIXTURE_DIR/ci-queue-wait.sh" <<'SH'
-#!/usr/bin/env bash
-printf '%s\n' "$*" > "${MOSAIC_QUEUE_CALL_LOG:?}"
-exit 42
-SH
-chmod +x "$FIXTURE_DIR"/*.sh
-
-run_case() { # run_case <extra-args...>
-    : > "$CALL_LOG"
-    set +e
-    (
-        cd "$WORK_DIR"
-        export MOSAIC_QUEUE_CALL_LOG="$CALL_LOG"
-        "$FIXTURE_DIR/pr-merge.sh" -n 123 "$@"
-    ) >"$OUT_LOG" 2>&1
-    rc=$?
-    set -e
-}
-
-# 1. No flag: policy refusal, no gate invocation.
-run_case
-[[ "$rc" -eq 1 ]] || { echo "FAIL arm1: rc=$rc want 1" >&2; cat "$OUT_LOG" >&2; exit 1; }
-[[ ! -s "$CALL_LOG" ]] || { echo "FAIL arm1: queue guard ran without authorization" >&2; exit 1; }
-grep -q "only for PRs targeting" "$OUT_LOG" || { echo "FAIL arm1: policy message missing" >&2; exit 1; }
-grep -q -- "--base-line 'mosaic-cli-p0'" "$OUT_LOG" || { echo "FAIL arm1: hint missing" >&2; exit 1; }
-
-# 2. Matching flag: authorized, audit line emitted, gates RUN (stub rc 42).
-run_case --base-line mosaic-cli-p0
-[[ "$rc" -eq 42 ]] || { echo "FAIL arm2: rc=$rc want 42 (gate stub rc must propagate)" >&2; cat "$OUT_LOG" >&2; exit 1; }
-[[ -s "$CALL_LOG" ]] || { echo "FAIL arm2: queue guard NOT invoked despite authorization" >&2; exit 1; }
-grep -q -- '-B mosaic-cli-p2-socket-res' "$CALL_LOG" || { echo "FAIL arm2: guard args wrong" >&2; cat "$CALL_LOG" >&2; exit 1; }
-grep -q "base-line exception" "$OUT_LOG" || { echo "FAIL arm2: audit line missing" >&2; exit 1; }
-
-# 3. Mismatched flag: refusal, mismatch named, no gate invocation.
-run_case --base-line some-other-line
-[[ "$rc" -eq 1 ]] || { echo "FAIL arm3: rc=$rc want 1" >&2; cat "$OUT_LOG" >&2; exit 1; }
-[[ ! -s "$CALL_LOG" ]] || { echo "FAIL arm3: queue guard ran on a refused merge" >&2; exit 1; }
-grep -q "does not match the PR base" "$OUT_LOG" || { echo "FAIL arm3: mismatch message missing" >&2; exit 1; }
-
-echo "pr-merge --base-line exception regression passed (B5)"

packages/mosaic/src/cli.ts

@@ -11,9 +11,6 @@ import { registerQualityRails } from '@mosaicstack/quality-rails';
 import { registerQueueCommand } from '@mosaicstack/queue';
 import { registerStorageCommand } from '@mosaicstack/storage';
 import { registerTelemetryCommand } from './commands/telemetry.js';
-import { registerCommsCommand } from './commands/comms.js';
-import { registerQCommand } from './commands/q.js';
-import { registerWatchCommand } from './commands/watch.js';
 import { registerAgentCommand } from './commands/agent.js';
 import { registerInteractionCommand } from './commands/interaction.js';
 import { registerConfigCommand } from './commands/config.js';
@@ -431,9 +428,6 @@ registerSkillCommand(program);
 // ─── telemetry ───────────────────────────────────────────────────────────────
 
 registerTelemetryCommand(program);
-registerWatchCommand(program);
-registerQCommand(program);
-registerCommsCommand(program);
 
 // ─── update ─────────────────────────────────────────────────────────────
 

packages/mosaic/src/commands/brain-dispatch.ts

@@ -1,67 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import { accessSync, constants } from 'node:fs';
-import { join } from 'node:path';
-
-import { resolveBrainHome } from '../fleet/brain-home.js';
-
-/**
- * Shared brain-tool dispatch (fleet CLI integration, Jason ruling
- * 2026-08-28): the npm package embeds the COMMAND SURFACE; operator-owned
- * implementations stay in the brain (tools/). Commands resolve the brain
- * home (MOSAIC_BRAIN_HOME wins — see brain-home.ts) and exec the tool
- * there. Nothing operator-specific ships inside the package.
- *
- * Pass-through contract: arguments, stdout/stderr, and the exit code belong
- * to the tool. The CLI adds nothing on success; absent tools fail loudly
- * with the resolved path (127) instead of guessing.
- */
-
-/** Absolute path of a brain-relative tool. */
-export function resolveBrainTool(mosaicHome: string, relPath: string): string {
-  return join(resolveBrainHome(mosaicHome), ...relPath.split('/'));
-}
-
-/** Map a spawnSync result + tool existence to the CLI exit status. */
-export function exitStatusFor(
-  result: { status: number | null; error?: NodeJS.ErrnoException },
-  toolExists: boolean,
-): number {
-  if (!toolExists) return 127;
-  if (result.status !== null) return result.status;
-  return 125; // killed by signal / could not run
-}
-
-export function brainToolExists(tool: string): boolean {
-  try {
-    accessSync(tool, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Exec a brain tool with full pass-through. `interpreter` runs the tool
- * through e.g. python3 (renderers); omit it for executable scripts.
- * Returns the process exit status; callers assign it to process.exitCode.
- */
-export function execBrainTool(
-  mosaicHome: string,
-  relPath: string,
-  args: string[],
-  interpreter?: string,
-): number {
-  const tool = resolveBrainTool(mosaicHome, relPath);
-  if (!brainToolExists(tool)) {
-    console.error(
-      `mosaic: brain tool not found (expected ${tool}). ` +
-        'Tool suites live in the brain tree under tools/; ' +
-        'check MOSAIC_BRAIN_HOME or the brain checkout.',
-    );
-    return 127;
-  }
-  const result = interpreter
-    ? spawnSync(interpreter, [tool, ...args], { stdio: 'inherit', env: process.env })
-    : spawnSync(tool, args, { stdio: 'inherit', env: process.env });
-  return exitStatusFor(result, true);
-}

packages/mosaic/src/commands/comms.spec.ts

@@ -1,143 +0,0 @@
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  writeFileSync,
-  readFileSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { Command } from 'commander';
-import { afterEach, describe, expect, it } from 'vitest';
-
-import { fleetCommsSendArgs, registerCommsCommand, tmuxSendArgs } from './comms.js';
-
-describe('arg translation', () => {
-  it('tmux path: -s/-C/-L/-f/-m per agent-send.sh getopts', () => {
-    expect(tmuxSendArgs('orch-01', 'hello', {})).toEqual(['-s', 'orch-01', '-m', 'hello']);
-    expect(
-      tmuxSendArgs('orch-01', 'unused', {
-        class: 'actionable',
-        socket: 'mosaic-fleet',
-        file: '/tmp/body.txt',
-      }),
-    ).toEqual(['-s', 'orch-01', '-C', 'actionable', '-L', 'mosaic-fleet', '-f', '/tmp/body.txt']);
-  });
-
-  it('fleet-comms path: -t site/agent and -c class', () => {
-    expect(fleetCommsSendArgs('usc', 'fred', 'hi', {})).toEqual(['-t', 'usc/fred', '-m', 'hi']);
-    expect(fleetCommsSendArgs('usc', 'fred', 'hi', { class: 'human' })).toEqual([
-      '-t',
-      'usc/fred',
-      '-c',
-      'human',
-      '-m',
-      'hi',
-    ]);
-  });
-});
-
-describe('registerCommsCommand routing', () => {
-  const savedBrain = process.env['MOSAIC_BRAIN_HOME'];
-  const savedRepo = process.env['MOSAIC_FLEET_COMMS_REPO'];
-  const savedAgent = process.env['MOSAIC_AGENT_NAME'];
-  afterEach(() => {
-    for (const [k, v] of [
-      ['MOSAIC_BRAIN_HOME', savedBrain],
-      ['MOSAIC_FLEET_COMMS_REPO', savedRepo],
-      ['MOSAIC_AGENT_NAME', savedAgent],
-    ] as const) {
-      if (v === undefined) delete process.env[k];
-      else process.env[k] = v;
-    }
-    process.exitCode = undefined;
-  });
-
-  function fixture(): { brain: string; repo: string; tmuxLog: string; commsLog: string } {
-    const brain = mkdtempSync(join(tmpdir(), 'comms-brain-'));
-    const repo = mkdtempSync(join(tmpdir(), 'comms-repo-'));
-    mkdirSync(join(brain, 'tools', 'tmux'), { recursive: true });
-    mkdirSync(join(repo, 'tools'), { recursive: true });
-    const tmuxLog = join(brain, 'tmux.log');
-    const commsLog = join(repo, 'comms.log');
-    writeFileSync(
-      join(brain, 'tools', 'tmux', 'agent-send.sh'),
-      `#!/usr/bin/env bash\nprintf '%s\\n' "$*" >> ${JSON.stringify(tmuxLog)}\nexit 7\n`,
-    );
-    writeFileSync(
-      join(repo, 'tools', 'comms-send.sh'),
-      `#!/usr/bin/env bash\nprintf '%s\\n' "$*" >> ${JSON.stringify(commsLog)}\nprintf 'FLEET_COMMS_REPO=%s FLEET_COMMS_SITE=%s\\n' "$FLEET_COMMS_REPO" "$FLEET_COMMS_SITE" >> ${JSON.stringify(commsLog)}\nexit 5\n`,
-    );
-    chmodSync(join(brain, 'tools', 'tmux', 'agent-send.sh'), 0o755);
-    chmodSync(join(repo, 'tools', 'comms-send.sh'), 0o755);
-    process.env['MOSAIC_BRAIN_HOME'] = brain;
-    process.env['MOSAIC_FLEET_COMMS_REPO'] = repo;
-    process.env['MOSAIC_AGENT_NAME'] = 'tester';
-    return { brain, repo, tmuxLog, commsLog };
-  }
-
-  it('default routes same-host via agent-send with translated flags and passes rc through', async () => {
-    const f = fixture();
-    const program = new Command();
-    registerCommsCommand(program);
-    await program.parseAsync(
-      [
-        'comms',
-        'send',
-        'orch-01',
-        '--class',
-        'actionable',
-        '--socket',
-        'mosaic-fleet',
-        'verdict',
-        'landed',
-      ],
-      { from: 'user' },
-    );
-    expect(process.exitCode).toBe(7);
-    expect(readFileSync(f.tmuxLog, 'utf8').trim()).toBe(
-      '-s orch-01 -C actionable -L mosaic-fleet -m verdict landed',
-    );
-    expect(existsSync(f.commsLog)).toBe(false); // inter-site tool never invoked
-  });
-
-  it('--site routes inter-site via comms-send with site-prefixed target and passes rc through', async () => {
-    const f = fixture();
-    const program = new Command();
-    registerCommsCommand(program);
-    await program.parseAsync(
-      ['comms', 'send', 'fred', '--site', 'usc', '--class', 'human', 'hello', 'there'],
-      { from: 'user' },
-    );
-    expect(process.exitCode).toBe(5);
-    expect(readFileSync(f.commsLog, 'utf8').split('\n')[0]?.trim()).toBe(
-      '-t usc/fred -c human -m hello there',
-    );
-    // The sender must bind comms-send.sh to the SELECTED repo (codex 9c8b6ebf).
-    expect(readFileSync(f.commsLog, 'utf8')).toContain(
-      `FLEET_COMMS_REPO=${f.repo} FLEET_COMMS_SITE=usc`,
-    );
-    expect(existsSync(f.tmuxLog)).toBe(false); // same-host tool never invoked
-  });
-
-  it('inter-site without MOSAIC_AGENT_NAME is an invocation defect (exit 2)', async () => {
-    const f = fixture();
-    delete process.env['MOSAIC_AGENT_NAME'];
-    const program = new Command();
-    registerCommsCommand(program);
-    await program.parseAsync(['comms', 'send', 'fred', '--site', 'usc', 'hi'], { from: 'user' });
-    expect(process.exitCode).toBe(2);
-    expect(existsSync(f.commsLog)).toBe(false); // inter-site tool never invoked
-  });
-
-  it('missing fleet-comms repo fails 127 naming the expected path', async () => {
-    fixture();
-    process.env['MOSAIC_FLEET_COMMS_REPO'] = '/nonexistent-comms-repo';
-    const program = new Command();
-    registerCommsCommand(program);
-    await program.parseAsync(['comms', 'send', 'fred', '--site', 'usc', 'hi'], { from: 'user' });
-    expect(process.exitCode).toBe(127);
-  });
-});

packages/mosaic/src/commands/comms.ts

@@ -1,135 +0,0 @@
-import type { Command } from 'commander';
-import { spawnSync } from 'node:child_process';
-import { accessSync, constants } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-
-import { DEFAULT_MOSAIC_HOME } from '../constants.js';
-import { execBrainTool } from './brain-dispatch.js';
-
-/**
- * `mosaic comms send` — routed agent messaging (FLEET-COMMS.md doctrine).
- *
- * Same-host (default): brain tools/tmux/agent-send.sh. Inter-site
- * (--site <site>): the fleet-comms repo's comms-send.sh — never for
- * local traffic (a git round trip per message; Jason 2026-08-28).
- *
- * Exit codes pass through BOTH paths. rc=2 (text in pane, still draft) is
- * a CONTRACT, not a failure: never retry, confirm with capture-pane.
- */
-export interface CommsSendOptions {
-  readonly class?: string;
-  readonly file?: string;
-  readonly socket?: string;
-  readonly site?: string;
-  readonly commsRepo?: string;
-}
-
-export function defaultCommsRepo(): string {
-  return process.env['MOSAIC_FLEET_COMMS_REPO'] ?? join(homedir(), 'src', 'fleet-comms');
-}
-
-/** Build the agent-send.sh argv for the same-host path. */
-export function tmuxSendArgs(target: string, message: string, opts: CommsSendOptions): string[] {
-  const args = ['-s', target];
-  if (opts.class) args.push('-C', opts.class);
-  if (opts.socket) args.push('-L', opts.socket);
-  if (opts.file) args.push('-f', opts.file);
-  else args.push('-m', message);
-  return args;
-}
-
-/** Build the comms-send.sh argv for the inter-site path. */
-export function fleetCommsSendArgs(
-  site: string,
-  target: string,
-  message: string,
-  opts: CommsSendOptions,
-): string[] {
-  const args = ['-t', `${site}/${target}`];
-  if (opts.class) args.push('-c', opts.class);
-  args.push('-m', message);
-  return args;
-}
-
-export function registerCommsCommand(program: Command): void {
-  const cmd: Command = program
-    .command('comms')
-    .description(
-      'Routed agent messaging: tmux same-host (default), fleet-comms inter-site (--site)',
-    )
-    .command('send')
-    .description('send <target> [message...] — same-host tmux unless --site is given')
-    .option('--class <class>', 'terminal-log | actionable | human | reaction | digest')
-    .option('--file <path>', 'message body from file (same-host path only)')
-    .option('--socket <name>', 'tmux socket for the same-host send (e.g. mosaic-fleet)')
-    .option('--site <site>', 'route via fleet-comms to <site>/<target>')
-    .option('--comms-repo <path>', 'fleet-comms checkout', defaultCommsRepo())
-    .argument('<target>', 'destination seat (session name)')
-    .argument('[message...]', 'message text (joined; or use --file)')
-    .action(
-      async (
-        target: string,
-        messageWords: string[],
-        opts: CommsSendOptions & Record<string, unknown>,
-        command: Command,
-      ) => {
-        let mosaicHome: string | undefined;
-        for (let anc: Command | null = command; anc; anc = anc.parent) {
-          const v = (anc.opts() as Record<string, string | undefined>)['mosaicHome'];
-          if (v !== undefined) {
-            mosaicHome = v;
-            break;
-          }
-        }
-        const home = mosaicHome ?? DEFAULT_MOSAIC_HOME;
-        const message = messageWords.join(' ');
-
-        if (opts.site) {
-          const repo = opts.commsRepo ?? defaultCommsRepo();
-          const tool = join(repo, 'tools', 'comms-send.sh');
-          try {
-            accessSync(tool, constants.X_OK);
-          } catch {
-            console.error(
-              `mosaic comms: fleet-comms sender not found (expected ${tool}). ` +
-                'Clone the fleet-comms repo or point --comms-repo at it.',
-            );
-            process.exitCode = 127;
-            return;
-          }
-          if (!process.env['MOSAIC_AGENT_NAME']) {
-            console.error(
-              'mosaic comms: inter-site sends require MOSAIC_AGENT_NAME (sending identity).',
-            );
-            process.exitCode = 2; // invocation defect: fixable by the caller
-            return;
-          }
-          // comms-send.sh locates its working repo via FLEET_COMMS_REPO
-          // (default $HOME/src/fleet-comms); without this, --comms-repo
-          // would select the executable but not the repository it operates
-          // on (codex review of 9c8b6ebf).
-          const env = { ...process.env, FLEET_COMMS_SITE: opts.site, FLEET_COMMS_REPO: repo };
-          const result = spawnSync(tool, fleetCommsSendArgs(opts.site, target, message, opts), {
-            stdio: 'inherit',
-            env,
-          });
-          process.exitCode = result.status ?? 125;
-          return;
-        }
-
-        // Same-host: the brain tool owns validation (bad class -> its rc 3)
-        // and absence (execBrainTool -> 127 with the resolved path).
-        process.exitCode = execBrainTool(
-          home,
-          'tools/tmux/agent-send.sh',
-          tmuxSendArgs(target, message, opts),
-        );
-      },
-    );
-
-  cmd.addHelpText(
-    'after',
-    '\nExit codes pass through. rc=2 means the text reached the pane but is still a draft: NEVER retry (double-send); confirm with tmux capture-pane.',
-  );
-}

packages/mosaic/src/commands/launch.ts

@@ -1162,8 +1162,6 @@ const COORD_SUBCMDS: Record<string, string> = {
   test: 'smoke-test.sh',
   resume: 'session-resume.sh',
   recover: 'session-resume.sh',
-  board: 'board-roll.sh',
-  roll: 'board-roll.sh',
 };
 
 function runCoord(args: string[]): never {
@@ -1197,7 +1195,6 @@ Commands:
   run [--project <path>]      Launch runtime with mission context
   smoke                       Run orchestration smoke checks
   resume [--project <path>]   Crash recovery
-  board                      Roll the orchestration board (board-roll.sh)
 
 Runtime: --claude (default) | --codex | --pi | --yolo`);
     process.exit(subcmd === 'help' ? 0 : 1);

packages/mosaic/src/commands/q.spec.ts

@@ -1,91 +0,0 @@
-import { mkdirSync, mkdtempSync, writeFileSync, chmodSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { Command } from 'commander';
-import { afterEach, describe, expect, it } from 'vitest';
-
-import { registerQCommand, resolveQuestionTool } from './q.js';
-import { exitStatusFor, resolveBrainTool } from './brain-dispatch.js';
-
-describe('resolveBrainTool', () => {
-  const saved = process.env['MOSAIC_BRAIN_HOME'];
-  afterEach(() => {
-    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
-    else process.env['MOSAIC_BRAIN_HOME'] = saved;
-  });
-
-  it('joins brain home with the relative tool path', () => {
-    const tmp = mkdtempSync(join(tmpdir(), 'dispatch-resolve-'));
-    process.env['MOSAIC_BRAIN_HOME'] = tmp;
-    expect(resolveBrainTool('/nonexistent/mosaic-home', 'tools/questions/q-new.sh')).toBe(
-      join(tmp, 'tools', 'questions', 'q-new.sh'),
-    );
-  });
-});
-
-describe('resolveQuestionTool', () => {
-  const saved = process.env['MOSAIC_BRAIN_HOME'];
-  afterEach(() => {
-    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
-    else process.env['MOSAIC_BRAIN_HOME'] = saved;
-  });
-
-  it('maps new/render subcommands to their brain tools', () => {
-    const tmp = mkdtempSync(join(tmpdir(), 'q-resolve-'));
-    process.env['MOSAIC_BRAIN_HOME'] = tmp;
-    expect(resolveQuestionTool(tmp, 'new')).toBe(join(tmp, 'tools', 'questions', 'q-new.sh'));
-    expect(resolveQuestionTool(tmp, 'render')).toBe(join(tmp, 'tools', 'questions', 'render.py'));
-    expect(resolveQuestionTool(tmp, 'bogus')).toBeUndefined();
-  });
-});
-
-describe('registerQCommand usage + dispatch', () => {
-  const saved = process.env['MOSAIC_BRAIN_HOME'];
-  afterEach(() => {
-    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
-    else process.env['MOSAIC_BRAIN_HOME'] = saved;
-    process.exitCode = undefined;
-  });
-
-  it('exit 2 with the subcommand list when no/unknown subcommand', async () => {
-    process.env['MOSAIC_BRAIN_HOME'] = mkdtempSync(join(tmpdir(), 'q-usage-'));
-    const program = new Command();
-    registerQCommand(program);
-    await program.parseAsync(['q'], { from: 'user' });
-    expect(process.exitCode).toBe(2);
-    process.exitCode = undefined;
-    await program.parseAsync(['q', 'bogus'], { from: 'user' });
-    expect(process.exitCode).toBe(2);
-    process.exitCode = undefined;
-    // Reserved property names must not leak through the record lookup.
-    await program.parseAsync(['q', 'toString'], { from: 'user' });
-    expect(process.exitCode).toBe(2);
-  });
-
-  it('execs the brain tool with pass-through args and exit code', async () => {
-    const tmp = mkdtempSync(join(tmpdir(), 'q-live-'));
-    process.env['MOSAIC_BRAIN_HOME'] = tmp;
-    mkdirSync(join(tmp, 'tools', 'questions'), { recursive: true });
-    const stub = join(tmp, 'tools', 'questions', 'q-new.sh');
-    writeFileSync(stub, '#!/usr/bin/env bash\necho "called with: $*"\nexit 7\n');
-    chmodSync(stub, 0o755);
-
-    const program = new Command();
-    registerQCommand(program);
-    await program.parseAsync(['q', 'new', '--slug', 'x', '--question', 'why'], { from: 'user' });
-    expect(process.exitCode).toBe(7);
-  });
-});
-
-describe('exitStatusFor (shared dispatch contract)', () => {
-  it('maps absent tool to 127', () => {
-    expect(exitStatusFor({ status: 0 }, false)).toBe(127);
-  });
-  it('passes tool status through', () => {
-    expect(exitStatusFor({ status: 7 }, true)).toBe(7);
-  });
-  it('maps signal death to 125', () => {
-    expect(exitStatusFor({ status: null }, true)).toBe(125);
-  });
-});

packages/mosaic/src/commands/q.ts

@@ -1,63 +0,0 @@
-import type { Command } from 'commander';
-
-import { DEFAULT_MOSAIC_HOME } from '../constants.js';
-import { execBrainTool, resolveBrainTool } from './brain-dispatch.js';
-
-/**
- * `mosaic q` — tracked decision questions (brain tools/questions).
- * `new` files a question file (one FILE per question, merge-conflict
- * impossible by construction); `render` regenerates the
- * docs/OPEN-QUESTIONS.md index (id allocation happens in the renderer).
- */
-const SUBCOMMANDS: Record<string, { path: string; interpreter?: string; help: string }> = {
-  new: {
-    path: 'tools/questions/q-new.sh',
-    help: 'file a question (--question, --slug, --owed-by, ...)',
-  },
-  render: {
-    path: 'tools/questions/render.py',
-    interpreter: 'python3',
-    help: 'regenerate docs/OPEN-QUESTIONS.md (owns Q-id allocation)',
-  },
-};
-
-export function resolveQuestionTool(mosaicHome: string, sub: string): string | undefined {
-  const entry = SUBCOMMANDS[sub];
-  return entry ? resolveBrainTool(mosaicHome, entry.path) : undefined;
-}
-
-export function registerQCommand(program: Command): void {
-  const cmd: Command = program
-    .command('q')
-    .description('Tracked decision questions: file and render (brain tools/questions)')
-    .allowUnknownOption()
-    .argument('[args...]', 'subcommand + args passed through to the question tools')
-    .action(async (args: string[], _opts: unknown, command: Command) => {
-      let mosaicHome: string | undefined;
-      for (let anc: Command | null = command; anc; anc = anc.parent) {
-        const v = (anc.opts() as Record<string, string | undefined>)['mosaicHome'];
-        if (v !== undefined) {
-          mosaicHome = v;
-          break;
-        }
-      }
-      const home = mosaicHome ?? DEFAULT_MOSAIC_HOME;
-
-      const sub = args[0];
-      if (!sub || !Object.hasOwn(SUBCOMMANDS, sub)) {
-        console.error('mosaic q: expected a subcommand:');
-        for (const [name, entry] of Object.entries(SUBCOMMANDS)) {
-          console.error(`  mosaic q ${name}   ${entry.help}`);
-        }
-        process.exitCode = 2; // usage error contract: invocation defect
-        return;
-      }
-      const entry = SUBCOMMANDS[sub]!;
-      process.exitCode = execBrainTool(home, entry.path, args.slice(1), entry.interpreter);
-    });
-
-  cmd.addHelpText(
-    'after',
-    '\nEverything after the subcommand is passed through verbatim (args, output, exit code).',
-  );
-}

packages/mosaic/src/commands/watch.spec.ts

@@ -1,72 +0,0 @@
-import { mkdirSync, mkdtempSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { Command } from 'commander';
-import { afterEach, describe, expect, it } from 'vitest';
-
-import { exitStatusFor, registerWatchCommand, resolveAgentWatchTool } from './watch.js';
-
-// The dispatch command execs a real process with inherited stdio; the spec
-// covers the pure resolution and exit-mapping surfaces plus the absent-tool
-// path (which exits without spawning). Live pass-through is exercised by the
-// fleet smoke test against the real brain tool.
-
-describe('resolveAgentWatchTool', () => {
-  const saved = process.env['MOSAIC_BRAIN_HOME'];
-  afterEach(() => {
-    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
-    else process.env['MOSAIC_BRAIN_HOME'] = saved;
-  });
-
-  it('honors MOSAIC_BRAIN_HOME over the canonical brain', () => {
-    const tmp = mkdtempSync(join(tmpdir(), 'watch-resolve-'));
-    process.env['MOSAIC_BRAIN_HOME'] = tmp;
-    expect(resolveAgentWatchTool('/nonexistent/mosaic-home')).toBe(
-      join(tmp, 'tools', 'agent-watch', 'agent-watch.sh'),
-    );
-  });
-
-  it('resolves inside the brain tools tree', () => {
-    const tmp = mkdtempSync(join(tmpdir(), 'watch-resolve-'));
-    process.env['MOSAIC_BRAIN_HOME'] = tmp;
-    const tool = resolveAgentWatchTool(tmp);
-    expect(tool.endsWith(join('tools', 'agent-watch', 'agent-watch.sh'))).toBe(true);
-  });
-});
-
-describe('exitStatusFor', () => {
-  it('maps absent tool to 127', () => {
-    expect(exitStatusFor({ status: 0 }, false)).toBe(127);
-  });
-
-  it('passes the tool exit status through', () => {
-    expect(exitStatusFor({ status: 2 }, true)).toBe(2);
-    expect(exitStatusFor({ status: 78 }, true)).toBe(78);
-  });
-
-  it('maps signal death / null status to 125', () => {
-    expect(exitStatusFor({ status: null }, true)).toBe(125);
-  });
-});
-
-describe('registerWatchCommand absent-tool path', () => {
-  const saved = process.env['MOSAIC_BRAIN_HOME'];
-  afterEach(() => {
-    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
-    else process.env['MOSAIC_BRAIN_HOME'] = saved;
-    process.exitCode = undefined;
-  });
-
-  it('sets exitCode 127 with the resolved path when the tool is missing', async () => {
-    const tmp = mkdtempSync(join(tmpdir(), 'watch-missing-'));
-    // The suite directory exists but the tool file does not.
-    mkdirSync(join(tmp, 'tools', 'agent-watch'), { recursive: true });
-    process.env['MOSAIC_BRAIN_HOME'] = tmp;
-
-    const program = new Command();
-    registerWatchCommand(program);
-    await program.parseAsync(['watch', 'list'], { from: 'user' });
-    expect(process.exitCode).toBe(127);
-  });
-});

packages/mosaic/src/commands/watch.ts

@@ -1,68 +0,0 @@
-import type { Command } from 'commander';
-
-import { DEFAULT_MOSAIC_HOME } from '../constants.js';
-import {
-  brainToolExists,
-  execBrainTool,
-  exitStatusFor,
-  resolveBrainTool,
-} from './brain-dispatch.js';
-
-export { exitStatusFor };
-
-/**
- * `mosaic watch` — dispatch to the brain's agent-watch suite.
- * See brain-dispatch.ts for the architecture and pass-through contract.
- */
-export function resolveAgentWatchTool(mosaicHome: string): string {
-  return resolveBrainTool(mosaicHome, 'tools/agent-watch/agent-watch.sh');
-}
-
-export function registerWatchCommand(program: Command): void {
-  const cmd: Command = program
-    .command('watch')
-    .description('Wake-me-when watchers (agent-watch): start, list, stop')
-    // allowUnknownOption + variadic = full ordered pass-through: unknown
-    // options (--name, --when, ...) and their values land in args verbatim
-    // (commander 13 measured behavior), so the tool owns its own flag
-    // surface without the CLI needing passThroughOptions (which would
-    // force enablePositionalOptions fleet-wide on the root program).
-    .allowUnknownOption()
-    // The tool owns help too: without this, commander would intercept
-    // --help and answer with wrapper help instead of agent-watch's own
-    // (codex review of 18f3dd49).
-    .helpOption(false)
-    .argument('[args...]', 'args passed through to agent-watch.sh')
-    .action(async (args: string[], _opts: unknown, command: Command) => {
-      // --mosaic-home is not global in this CLI; walk parents for it and
-      // fall back to the default. MOSAIC_BRAIN_HOME (seat launchers export
-      // it) wins inside resolveBrainHome regardless.
-      let mosaicHome: string | undefined;
-      for (let anc: Command | null = command; anc; anc = anc.parent) {
-        const v = (anc.opts() as Record<string, string | undefined>)['mosaicHome'];
-        if (v !== undefined) {
-          mosaicHome = v;
-          break;
-        }
-      }
-      const home = mosaicHome ?? DEFAULT_MOSAIC_HOME;
-
-      const tool = resolveAgentWatchTool(home);
-      if (!brainToolExists(tool)) {
-        console.error(
-          `mosaic watch: agent-watch not found (expected ${tool}). ` +
-            'The watcher suite lives in the brain tree under tools/agent-watch/; ' +
-            'check MOSAIC_BRAIN_HOME or the brain checkout.',
-        );
-        process.exitCode = 127;
-        return;
-      }
-
-      process.exitCode = execBrainTool(home, 'tools/agent-watch/agent-watch.sh', args);
-    });
-
-  cmd.addHelpText(
-    'after',
-    '\nEverything after `mosaic watch` is passed through to agent-watch.sh verbatim (args, output, exit code).',
-  );
-}