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/missions/missions.controller.ts

@@ -108,13 +108,11 @@ export class MissionsController {
   ) {
     const mission = await this.brain.missions.findByIdAndUser(missionId, user.id);
     if (!mission) throw new NotFoundException('Mission not found');
-    // dto.status is deliberately not forwarded: mission_tasks.status is
-    // write-prohibited through the N-1 window (SHARED-CONTRACT §5.1 phase 1);
-    // the repo strips it as well.
     return this.brain.missionTasks.create({
       missionId,
       taskId: dto.taskId,
       userId: user.id,
+      status: dto.status,
       description: dto.description,
       notes: dto.notes,
       pr: dto.pr,

apps/gateway/src/missions/missions.dto.ts

@@ -77,12 +77,6 @@ export class CreateMissionTaskDto {
   @IsUUID()
   taskId?: string;
 
-  /**
-   * @deprecated Accepted for N-1 wire compatibility but ignored: mission_tasks.status
-   * is write-prohibited through the migration window (SHARED-CONTRACT §5.1 phase 1).
-   * The field stays declared because the global ValidationPipe runs with
-   * forbidNonWhitelisted, and removing it would 400 frozen legacy consumers.
-   */
   @IsOptional()
   @IsIn(taskStatuses)
   status?: 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
@@ -108,12 +102,6 @@ export class UpdateMissionTaskDto {
   @IsUUID()
   taskId?: string;
 
-  /**
-   * @deprecated Accepted for N-1 wire compatibility but ignored: mission_tasks.status
-   * is write-prohibited through the migration window (SHARED-CONTRACT §5.1 phase 1).
-   * The field stays declared because the global ValidationPipe runs with
-   * forbidNonWhitelisted, and removing it would 400 frozen legacy consumers.
-   */
   @IsOptional()
   @IsIn(taskStatuses)
   status?: 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';

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/PRD.md

@@ -197,41 +197,24 @@ conflict must amend one of them explicitly, never fork a third document
 - A second writable task store beside PostgreSQL (native-kanban-sot invariants).
 - Fully-designed federation in v1 (D3 — roadmap placeholder only).
 
-### D15 — Tiered containerized deployment (2026-08-30, containerization lane)
+### 12. Decision registry
 
-The stack ships a tiered deployment target, additive to the architecture
-gate (D8): (1) Standalone tier — docker compose is the canonical
-single-host deployment: postgres, valkey, openbao, gateway, appservice
-and the served webUI in one composition, with migrations, health checks,
-and a documented install/upgrade path; the registry (CI-published
-images) is the only deployment source. (2) Enterprise tier — Kubernetes
-manifests for the same service set, phase-gated on the standalone tier
-holding its acceptance bar. The v1 acceptance bar for the standalone
-tier: compose-up healthy; webUI hosts agent chat; an in-stack agent can
-open a PR to this repo; CI validates it; the running deployment adopts
-the merged change (pull + restart). Federation (D3 clause) remains
-deferred and unforeclosed. Implementation plan:
-docs/plans/2026-08-30_containerization.md.
-
-## 12. Decision registry
-
-| ID  | Decision (short form)                                                                                                                      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
-| D1  | Open-source, AI-first, self-hosted platform for agentic management + life OS                                                               |
-| D2  | Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC                                                                |
-| D3  | Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred                          |
-| D4  | Re-runnable, extensible, per-mode onboarding wizards                                                                                       |
-| D5  | North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT                                                                       |
-| D6  | Only product-relevant material migrates from brains; operational records stay and link                                                     |
-| D7  | Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 2026-08-25)                             |
-| D8  | webUI sits over official framework tooling; CLI primary                                                                                    |
-| D9  | Not a hosted business; company = organizational separation for one operator                                                                |
-| D10 | better-auth is the account system of record; external IdPs via OIDC                                                                        |
-| D11 | Small v1 slice; ALL phases on the documented roadmap from day one                                                                          |
-| D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first                                                               |
-| D13 | workspace_id stays the hard isolation unit; hierarchy is parent structure above; kanban SOT amended, not rewritten                         |
-| D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers                                             |
-| D15 | Tiered containerized deployment: compose standalone tier (five-point v1 bar) + phase-gated k8s enterprise tier; registry-only image source | 2026-08-30 containerization lane; plan docs/plans/2026-08-30_containerization.md |
+| ID  | Decision (short form)                                                                                              |
+| --- | ------------------------------------------------------------------------------------------------------------------ |
+| D1  | Open-source, AI-first, self-hosted platform for agentic management + life OS                                       |
+| D2  | Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC                                        |
+| D3  | Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred  |
+| D4  | Re-runnable, extensible, per-mode onboarding wizards                                                               |
+| D5  | North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT                                               |
+| D6  | Only product-relevant material migrates from brains; operational records stay and link                             |
+| D7  | Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 2026-08-25)     |
+| D8  | webUI sits over official framework tooling; CLI primary                                                            |
+| D9  | Not a hosted business; company = organizational separation for one operator                                        |
+| D10 | better-auth is the account system of record; external IdPs via OIDC                                                |
+| D11 | Small v1 slice; ALL phases on the documented roadmap from day one                                                  |
+| D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first                                       |
+| D13 | workspace_id stays the hard isolation unit; hierarchy is parent structure above; kanban SOT amended, not rewritten |
+| D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers                     |
 
 The full decision texts are recorded in the operator decision log (USC estate
 brain, webui-audit lane, `GRILL.md`).

docs/native-kanban-sot/INDEX.md

@@ -14,7 +14,6 @@
 | [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md)                                                       | rc.16 direct-Drizzle current storage-wrapper hold: legacy N-1/uncertified/non-operative pending -02/-03/-06/-08; exact README commented/user-guide executable forms fail before masking and source-consistency rejects runner-delegation copy; held future bootstrap → TLS/roles → run → verify → readiness; plus prior production boundary, pgvector owner, attestation, inventory, manifests, DDL classifier, TLS/bootstrap, activation, and certification contract; foundation prerequisite of KBN-100 and real-role gate before KBN-105 |
 | [`KBN-101-ENVELOPE-A.md`](./KBN-101-ENVELOPE-A.md)                                                             | KBN-101 Envelope A (v6) — RATIFIED, part of the frozen SSOT: rc.20 declarative sink-RBAC + per-role connection-selection + RLS `WITH CHECK`/`USING` write-source + `FORCE ROW LEVEL SECURITY` + sink-resident `task_status_write_override`; adds owner card KBN-101-10 + responsibility-widenings; authority Jason B1 + Mos OPTION A/Q1/Q2                                                                                                                                                                                                  |
 | [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)                                                                   | Remediated v1 integration contract: proof authority, exact failures/routes/DTOs/MCP ownership, concrete current-main field migration map, relational invariants, Coordinator split, recovery delivery                                                                                                                                                                                                                                                                                                                                       |
-| [`P0-MAP-CURRENCY-2026-08-29.md`](./P0-MAP-CURRENCY-2026-08-29.md)                                             | REQ-MIG-001 lane-opening verification: SHARED-CONTRACT §5 field map re-verified byte-identical at `next` @ `abb0c936`; workspaces/audit-pattern refinements; measured `mission_tasks.status` writer inventory and the pre-expand stop-write work item                                                                                                                                                                                                                                                                                       |
 | [`contracts/kanban-schema.v1.ts`](./contracts/kanban-schema.v1.ts)                                             | Drizzle target declarations including exact owner/principal membership, project congruence, tags/archive, proposals, persisted assignments, monotonic fences, durable retry, immutable evidence/audit                                                                                                                                                                                                                                                                                                                                       |
 | [`contracts/mechanical-coordinator.v1.ts`](./contracts/mechanical-coordinator.v1.ts)                           | Pure snapshot decision engine separated from persistence/service adapter; ID-bound approvals, bigint-safe fences, durable retry/quarantine, artifact-backed checkpoints, exact failures                                                                                                                                                                                                                                                                                                                                                     |
 | [`contracts/health-state.v1.ts`](./contracts/health-state.v1.ts)                                               | Discriminated public health, separate branded transaction-local write proof, and non-overlapping denial/transport/version-conflict mappings                                                                                                                                                                                                                                                                                                                                                                                                 |

docs/native-kanban-sot/P0-MAP-CURRENCY-2026-08-29.md

@@ -1,117 +0,0 @@
----
-kind: verification
-status: active
----
-
-# P0 Field-Map Currency Verification — 2026-08-29
-
-**Purpose:** REQ-MIG-001 (native-kanban-sot.md §5) accepts only when "P0 publishes
-the current `origin/main` field-by-field expand/backfill/compatibility/switch/contract
-map before any schema lane starts." That map exists: [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)
-§5, inspected at `packages/db/src/schema.ts` @ `e72388b2cbfe400842fe940fa6cabf984ed43711`
-(2026-07-13). The M4-3 schema lane (expand migration 0021+) now opens against the
-integration trunk `next`. This document re-verifies the map's currency at the
-lane-opening head and records the measured pre-expand writer inventory. It amends
-nothing normative in SHARED-CONTRACT.md; where the two disagree, SHARED-CONTRACT.md
-wins.
-
-## 1. Currency verification (measured)
-
-- Map pin: `e72388b2cbfe400842fe940fa6cabf984ed43711` (2026-07-13, `main`).
-- Lane-opening head: `abb0c936011c7f6b8c0bcc90a20a865d5e8a40e9` (`origin/next`,
-  2026-08-29).
-- Measurement: `git diff e72388b2 abb0c936 -- packages/db/src/schema.ts` reports
-  **300 insertions, 0 deletions** — no existing declaration changed.
-- The additions: the new declarations `logicalAgentConnectorLeases`,
-  `connectorLeaseAuditLog`, and the hierarchy layer (`companies`, `estates`,
-  `platformProjects`, `workspaces`, `hierarchyGrants`, `hierarchyAuditEvents`,
-  `hierarchyOutbox`, plus their enums and constant arrays); a nullable `issuer`
-  column on the unmapped BetterAuth `accounts` table (shipped as
-  `drizzle/0017_accounts_issuer.sql`); and expanded `drizzle-orm` imports
-  (`sql`, `AnyPgColumn`, `unique`, `check`, `bigint`). None touch a mapped
-  source.
-- Stronger literal fact: REQ-MIG-001's acceptance names `origin/main`. Measured
-  pin → `origin/main` (`7102ccb9`, 2026-08-13): **63 insertions, 0 deletions**
-  for `schema.ts`, and `origin/main` is an ancestor of `abb0c936`. The map is
-  therefore current at `origin/main` itself, and at the trunk head beyond it.
-
-**Consequence:** every source column mapped in SHARED-CONTRACT.md §5.4 —
-`teams`/`team_members`, `projects`, `missions`, `tasks`, `mission_tasks`,
-`agents`, fleet `backlog` — is byte-identical to the declaration the map
-inspected. The field map is current as written. No row changes.
-
-## 2. Refinements available since the pin (context, not map changes)
-
-1. **The `workspaces` table exists.** The map predates contract 1's hierarchy
-   layer; its "bootstrap workspace" backfill step now has a shipped target:
-   `workspaces` (uuid PK, chained under platform projects per
-   `docs/requirements/hierarchy-schema.md`; hierarchy core in
-   `drizzle/0018_clean_cobalt_man.sql`, audit/outbox in
-   `0019_volatile_killraven.sql`, visibility in
-   `0020_special_betty_brant.sql`). New `workspace_id` columns FK there.
-2. **The audit/outbox envelope pattern is shipped.** `hierarchyAuditEvents` +
-   `hierarchyOutbox` implement same-transaction semantic event + outbox. The
-   task lane's `task_events`/`task_outbox` mirror the pattern but are
-   workspace-scoped with the composite `(workspace_id, id)` key required by
-   §5.3 and REQ-SOT-004. The hierarchy tables are a pattern reference, never a
-   shared store for task events.
-3. **Trunk designation.** The integration trunk is `next` (`.mosaic/repo.json`).
-   §1 measures currency at both the literal `origin/main` REQ-MIG-001 names and
-   the trunk head pinned above, so no reinterpretation of the acceptance text
-   is needed.
-4. **Migration ownership.** SHARED-CONTRACT.md §6 assigns schema/migration
-   ownership to the mission seat `coder2`. Seat identity is operational fleet
-   state, not resolvable from this repository, and is outside this document's
-   scope. The invariant §6 protects binds regardless of seat and is restated
-   here as binding on the M4-3 schema lane: exactly one lane generates
-   migrations at a time; expand is additive; no drop/rename/narrow; constraints
-   validate before NOT NULL.
-
-## 3. Pre-expand writer inventory (measured 2026-08-29 at `abb0c936`)
-
-SHARED-CONTRACT.md §5.1 phase 1 requires an N-1 patch that stops
-`mission_tasks.status` as a write source, plus a writer inventory, before any
-expand DDL.
-
-- **Sole authoring write path:** `packages/brain/src/mission-tasks.ts`
-  `create`/`update` (Drizzle insert/update on `mission_tasks`), invoked by
-  `apps/gateway/src/missions/missions.controller.ts`. `update` accepts
-  `Partial<NewMissionTask>`, so `status` is writable through both DTOs today.
-  The same module also exposes `remove`/`removeByMission` DELETE paths —
-  immaterial to `status` writes, listed for inventory completeness.
-- **Storage-layer surfaces that touch the column without authoring it**
-  (added 2026-08-29 after independent review of the phase-1 patch):
-  `packages/storage/src/migrate-tier.ts` copies whole `mission_tasks` rows
-  between storage tiers and must preserve the stored `status` verbatim — row
-  transport, exempt from the write prohibition (stripping there would corrupt
-  data inside the N-1 window). The generic table-keyed storage adapters
-  (`adapters/postgres.ts`, `adapters/pglite.ts`) register `mission_tasks` in
-  their table maps but have no caller that targets it: measured at this head,
-  every runtime adapter caller passes a fixed collection constant
-  (preferences/insights). Neither surface authors a new `status` value.
-- **Read-only consumers of `mission_tasks`:** federation verb services
-  (`get-query.service.ts`, `list-query.service.ts`) select only. The MCP
-  `brain_*` tools do not touch `mission_tasks` at all; `brain_create_task` /
-  `brain_update_task` write the separately mapped `tasks` table, a legitimate
-  N-1 writer through the compatibility window.
-- The ratified contract 5 decision
-  (`docs/requirements/tool-gateway-mapping.md` §3.2, ruled 2026-08-27) freezes
-  the legacy endpoints — including MCP `brain_*` task mutations — for new
-  consumers, while existing consumers keep working until each surface's owning
-  contract retires it. It does not stop existing writes.
-
-**Standing work item:** the phase-1 stop-write patch (reject or ignore `status`
-on `mission_tasks` create/update) MUST land before the expand DDL of migration
-lane M4-3a. It is N-1-safe per the §5.4 row for `mission_tasks.status` (linked
-status is ignored; the column stays declared and readable through the whole
-N-1 window; retirement only after no readers).
-
-## 4. Lane opening
-
-With this verification merged, REQ-MIG-001's P0-map precondition is satisfied
-for the M4-3 schema lane at pinned head `abb0c936`. The ordered phases (§5.1),
-mission candidate-key DDL order (§5.2), audit/proposal DDL order (§5.3), field
-map (§5.4), and required migration tests (§5.5) bind as written. External
-import machinery (jarvis-brain/Vikunja shadow import, REQ-MIG-001) and client
-cutover (REQ-MIG-002) remain out of scope for M4-3; the legacy surface stays
-frozen for new consumers meanwhile (`tool-gateway-mapping.md` §3.2 decision).

docs/plans/2026-08-29-agent-enrollment-command-design.md

@@ -1,315 +0,0 @@
----
-kind: spec
-status: active
-audience: developer
----
-
-# Agent Enrollment Command Family — v1 Design (M4-4-0)
-
-Status: design note (implementation-facing; amends no contract).
-Authority chain: tool-gateway-mapping.md §3.1 rank-4 row + §4 envelope
-(ruled 2026-08-27), onboarding-wizard.md §3.5 (D11 minimal enrollment),
-custody-schema.md §5.2 at revision 13 (agent-grantee FK bound to the
-live `agents` table — a binding introduced at rev 4 and standing
-verbatim), PRD §9 D11. Where this note and a ratified contract disagree,
-the contract wins.
-
-## 1. What the contracts bind (and what they leave open)
-
-There is no standalone enrollment contract. The rank-4 family is defined
-by composition:
-
-1. **Contract 5 §3.1 rank 4:** "Enroll one agent: harness, credential
-   reference/API-key intake (values never echoed), name/persona,
-   assignment scope (contract 3 §3.5)."
-2. **Contract 5 §4 — all five sub-clauses:** §4.1 typed request/result
-   DTOs validated at the Gateway boundary (expected-version only where
-   an owning contract defines one); §4.2 closed per-family error enum
-   (validation, authentication, authorization, not-found, conflict,
-   precondition, internal) with HTTP mappings; §4.3 audit linkage — the
-   envelope contributes correlation: every request accepts/generates a
-   correlation id, carried into the audit events **and returned in the
-   result**, with no second audit stream; §4.4 fail-closed — an
-   operation that cannot evaluate its authorization or reach its owning
-   tool refuses, never degrading to a fallback read or direct data
-   access; §4.5 CLI parity — the family MUST be invocable through the
-   official CLI against the same Gateway commands with the same
-   request/result/error contracts (a Gateway command without CLI
-   exposure is a tracked conformance gap).
-   **Idempotency keys are NOT contract 5 §4.3:** the idempotency-key
-   envelope is contract 3 §4.3, ratified as a drafting addition to
-   contract 5 §4's command envelope via contract 3 §7 item 4. Its fence
-   and replay rules bind as written there; §3.1 rule 5 below designs to
-   them.
-3. **Contract 3 §3.5:** the wizard's enrollment step is minimal (one
-   harness, API-key login, agent name and persona — D11), uses ONLY this
-   family, and is skippable. Wizard witness §6.10: a run that skips the
-   step produces zero enrollment-family mutations.
-4. **Custody-schema §5.2 (rev 13; binding introduced at rev 4):**
-   contract 7's agent-grantee FK references the live `agents` table
-   (`agents.id`, uuid); an enrollment surface with its own table would
-   force a contract-7 amendment.
-
-**Assignment scope (open point, pinned here):** the rank-4 row cites
-contract 3 §3.5, which defines no assignment semantics; the PRD's full
-enrollment vision (Part I, Standalone flow) includes "account
-assignment", but the D11 v1 slice is exactly "one harness, API key,
-name/persona". v1 therefore scopes assignment to the two bindings the
-minimal slice already implies — the enrolling user becomes the agent's
-owner (`agents.owner_id`), and the credential reference names which of
-that user's stored provider credentials the agent uses. Richer
-assignment (multi-account, comms auto-enroll, workspace placement) is
-deferred with the rest of the PRD's full flow (D11); when a contract
-defines it, this family extends by ordinary amendment of the design.
-The deferral rests on contract 3 §3.5's explicit delegation of
-enrollment specifics to this family — not on reading the D11 list as
-exhaustive (it is not: the §3.1 `model`/`provider` fields are required
-by the live table's NOT NULL columns, though D11 does not name them).
-
-## 2. Current state (measured 2026-08-29 at `origin/next` = `94d626df`)
-
-- `agents` table (packages/db `schema.ts`): id uuid PK, name, provider,
-  model, status enum, project_id (legacy `projects`, ON DELETE SET
-  NULL), owner_id → users, system_prompt, allowed_tools, skills,
-  is_system, config jsonb, timestamps. No harness column (provider and
-  model describe the LLM backend, not the harness), no audit coupling.
-- Sole write path: `packages/brain/src/agents.ts` repository (the only
-  module issuing `insert(agents)`), with three write consumers: the
-  legacy `/api/agents` CRUD controller
-  (`apps/gateway/src/agent/agent-configs.controller.ts`), the `/agent
-new` chat command (`apps/gateway/src/commands/command-executor.service.ts`
-  → `brain.agents.create`), and workspace bootstrap
-  (`apps/gateway/src/workspace/project-bootstrap.service.ts`). All
-  three keep serving existing consumers; none is touched by M4-4.
-- Sealed credential store exists: `ProviderCredentialsService`
-  (apps/gateway/src/agent/) — one row per (userId, provider), values
-  sealed at rest, decrypt server-side only, summaries never carry
-  values.
-- Harness registry exists (`apps/gateway/src/harness/`), the validation
-  source for the harness field.
-- Implementation pattern: the merged hierarchy module (M4-1) —
-  transaction-scoped command context, in-tx authorization, discriminated
-  result unions, same-transaction semantic audit event + transactional
-  outbox, no-oracle not_found folding.
-
-**F1 — contract-5 mapping note (disposition, not an amendment):**
-`/api/agents` appears nowhere in contract 5 — neither as a P0 row nor in
-the §3.2 legacy non-substitutes list (the ruled §3.2 freeze names
-specific endpoints, and `/api/agents` is not among them). The operative
-constraints are §3.3's amendment-only rule for new mapping rows and §5's
-closure rule: this design adds no new consumer to `/api/agents` and
-builds the rank-4 family as the P1 path for enrollment. Adding the
-missing P0 row is a contract amendment for a future S2 pass; nothing in
-M4-4 depends on it.
-
-## 3. Command family surface (v1)
-
-One command, one query. Module: `apps/gateway/src/enrollment/`
-(`enrollment.module.ts`), mirroring the hierarchy module's shape.
-
-### 3.1 `agent.enroll` (mutation)
-
-Request DTO (shared types package, class-validator at the boundary):
-
-| Field            | Type                | Rule                                                                                                                                                                                                                                                                                                      |
-| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `harness`        | string              | syntactically invalid (empty/malformed) → `validation_failed`; well-formed but not in the harness registry → `precondition_failed`                                                                                                                                                                        |
-| `correlationId`  | string (uuid)       | optional; generated when absent (contract 5 §4.3); carried into audit events and returned in the result                                                                                                                                                                                                   |
-| `replayMode`     | 'actor-bound'       | optional, default `actor-bound`. `shared` is seed-only (contract 3 §4.3 binds it to the §3.4 canonical seed key set and "no other operation can carry a shared declaration"; §7 item 4 closes it); a `shared` declaration here is refused `validation_failed`, executes nothing, and records no fence row |
-| `name`           | string              | non-empty, trimmed, ≤ 200 chars                                                                                                                                                                                                                                                                           |
-| `persona`        | string \| null      | optional; stored as the agent's system prompt                                                                                                                                                                                                                                                             |
-| `model`          | string              | non-empty (provider-qualified model id)                                                                                                                                                                                                                                                                   |
-| `provider`       | string              | non-empty; names the credential's provider                                                                                                                                                                                                                                                                |
-| `credential`     | discriminated union | `{ mode: 'reference' }` — a credential for (actor, provider) MUST already exist; `{ mode: 'intake', type: 'api_key', value: string }` — value is sealed into the credential store in the same flow                                                                                                        |
-| `idempotencyKey` | string (uuid)       | required (contract 3 §4.3, ratified into contract 5 §4 via contract 3 §7 item 4)                                                                                                                                                                                                                          |
-
-Rules:
-
-1. **Never echoed.** The credential value appears in no result DTO, no
-   audit event, no outbox payload, and no log line. The result carries
-   only `{ provider, credentialMode }`.
-2. **Intake = the existing sealed store, inside the transaction.**
-   `intake` writes through the sealed-store path
-   (`ProviderCredentialsService.store` semantics: seal-at-rest, upsert
-   per (userId, provider)) **in the same transaction** as the agent
-   insert — a failure after the credential write rolls everything back,
-   leaving no orphan credential. Enrollment persists no second copy and
-   no plaintext.
-3. **Reference must resolve.** `reference` with no stored credential for
-   (actor, provider) refuses with `precondition_failed` (nothing is
-   created).
-4. **Ownership.** `owner_id` = the authenticated actor. v1 authorization
-   is AuthGuard-authenticated user; no hierarchy grant is required
-   because v1 enrollment binds no hierarchy node (§1 assignment-scope
-   pin). `is_system` is never settable through this command.
-5. **Idempotency fence (contract 3 §4.3, in full).** The command layer
-   records, in a uniqueness-constrained fence table in the same
-   transaction as the mutation and its audit event: the key, the
-   operation identifier (`agent.enroll`), the acting principal, the
-   authorization scope, a digest of the canonicalized request payload
-   (the digest input EXCLUDES the credential value — it covers
-   provider + credentialMode, never plaintext), the declared replay
-   mode (always `actor-bound` for this family — the `shared` refusal
-   in the table above means no shared fence row can exist here; the
-   column is kept for envelope-shape fidelity and mode-mismatch
-   collision checks), and a reference to the committed outcome (the
-   agent id). The recorded **authorization scope** for this family is
-   pinned to the acting principal's platform-user scope (v1
-   authorization is grant-free per rule 4, so the scope is the
-   authenticated-user identity domain — recorded so the §4.3
-   scope-equality check has a defined value). Fence uniqueness is the
-   pair (operation identifier, key). **Replay:** a submission whose
-   (operation, key) is recorded is first authorized exactly as a fresh
-   submission; then replay-mode, scope, and digest equality are
-   checked (a mismatch on any — including scope — is a collision);
-   then **target-result authorization** — the submitter must hold, at
-   replay time, read authority on the referenced agent row under
-   §3.2's rule (owner or admin) — plus recorded-actor equality
-   (`actor-bound`). A passing replay executes nothing, returns the
-   recorded outcome, and appends a replay access event (non-mutation
-   audit class: accessing principal, current correlation id,
-   fence-row reference). Any equality or authorization failure refuses
-   with the single bounded `conflict` shape — constant, identifying no
-   record — preserving the no-existence-oracle rule. **Concurrency
-   (contract 3 §4.3's rule, ratified via §7 item 4):** two submissions
-   with the same (operation, key) serialize on the fence's unique
-   constraint — exactly one executes; the loser waits for the winner's
-   transaction, and is then handled as a replay if it committed
-   (through the full replay path above) or executes afresh if it
-   aborted. A unique-violation race never surfaces as an unhandled
-   internal fault.
-6. **Audit + outbox, same transaction.** Insert into `agents` +
-   sealed credential write (intake mode) + fence row + semantic audit
-   event (`agent.enrolled`: actor, agent id, harness, provider, name,
-   credentialMode — no credential material) + outbox row commit
-   atomically, hierarchy-pattern style. Audit rows reference the agent
-   by **snapshot id, not FK** — mirroring the hierarchy audit tables'
-   deliberate FK-free linkage so audit history survives agent deletion
-   through the legacy CRUD DELETE path.
-
-Result union: `enrolled { agent, correlationId }` | refusal from the
-§3.3 enum (refusals also carry the correlation id, per contract 5
-§4.3's end-to-end traceability). `agent` in the result is the persisted
-row minus nothing sensitive (the table stores no credential material).
-
-### 3.2 `agent.enrollment.get` (query)
-
-By agent id; actor must be the owner (or admin). Unauthorized and
-missing fold to the same `not_found` wire shape (contract 2
-no-existence-oracle rule, applied family-wide for uniformity).
-
-The query carries the same non-state envelope as the mutation
-(contract 5 §4.3; contract 3's envelope reconciliation confirms closed
-query responses carry it): typed request DTO with an optional
-`correlationId` (generated when absent) and a typed result —
-`found { agent, correlationId }` | `not_found` (the folded shape,
-also carrying the correlation id). Queries take no idempotency key
-(the fence binds mutations).
-
-### 3.3 Error enum (closed, §4.2)
-
-`validation_failed` 400 · `authentication_failed` 401 ·
-`authorization_refused` 403 (owner-only paths; folded to `not_found`
-where §3.2 applies) · `not_found` 404 · `conflict` 409 (the single
-bounded idempotency refusal shape of §3.1 rule 5) · `precondition_failed`
-422 (unresolvable credential reference; well-formed harness not in the
-registry — syntactic invalidity is `validation_failed` per the §3.1
-table) · `internal_fault` 500 (also the §4.4 fail-closed class when the
-owning tool is unreachable; unauthorized-fallback behavior is
-prohibited).
-
-## 4. Schema delta (migration 0021, additive-only)
-
-Extend `agents` — no new agent table, preserving custody-schema §5.2's
-FK binding without amendment:
-
-- `harness` text NULL — registered harness name; NULL for pre-existing
-  rows (legacy rows predate the concept).
-- `enrolled_at` timestamptz NULL — set by `agent.enroll`; NULL marks a
-  legacy (non-enrolled) row. No backfill: enrollment is a fact this
-  command creates, not one to invent for existing rows.
-
-New tables, mirroring the hierarchy audit/outbox pair (pattern reuse,
-separate store): `agent_audit_events` (append-only: id, event_type,
-actor id, agent id — snapshot value, no FK, per §3.1 rule 6 —
-correlation id, causation id, payload jsonb, created_at; per-agent
-ordering index), `agent_outbox` (hierarchy-outbox shape), and
-`agent_idempotency_fence` (contract 3 §4.3 shape: operation identifier,
-key, acting principal, authorization scope, canonicalized-payload
-digest, replay mode, committed-outcome reference (agent id), created_at;
-UNIQUE (operation identifier, key)). Persona reuses the existing
-`system_prompt` column; no version column (no ratified expected-version
-rule names `agents` — §4.1 binds only where the owning contract defines
-one).
-
-Witnesses (real PostgreSQL, lane standard): append-only enforcement,
-same-tx atomicity (agent row + credential write + fence row + audit +
-outbox all-or-nothing under injected failure at multiple points,
-including after the credential write), fence uniqueness on
-(operation, key).
-
-Sequencing: additive DDL via the same migration path as 0018–0020
-(hierarchy). The docs/native-kanban-sot/SHARED-CONTRACT.md §5.3 DDL
-gate binds the kanban lane's audit/proposal DDL, not this lane; if a
-pending operator ruling on migration sequencing changes mechanics
-lane-wide, re-check before generating 0021.
-
-## 5. Witnesses the implementation slice must ship
-
-1. Never-echo: enroll via `intake`, assert the value string is absent
-   from the HTTP result, the audit row, the outbox payload, and captured
-   logs.
-2. Sealed-store single-copy: after intake, the credential exists only in
-   `provider_credentials` (sealed), and `agents` has no credential
-   column at all.
-3. Reference-resolution refusal (`precondition_failed`, no row created).
-4. Harness refusals, both codes: syntactically invalid →
-   `validation_failed`; well-formed registry miss →
-   `precondition_failed` (against the live registry).
-5. Idempotency (contract 3 §4.3 set): actor-bound replay returns the
-   recorded outcome and executes nothing (no new agent/audit/outbox
-   mutation rows; a replay access event is appended); payload-digest
-   mismatch, replay-mode mismatch, scope mismatch, and different-actor
-   actor-bound replay each refuse with the single bounded `conflict`
-   shape; a replay is re-authorized fresh (a submitter whose
-   authorization was revoked since the original is refused, not
-   replayed); a `shared` declaration on `agent.enroll` is refused
-   `validation_failed` with nothing executed and no fence row
-   recorded (seed-only rule); two concurrent same-(operation, key)
-   submissions produce exactly one mutation, the loser resolving
-   through the replay path (no unhandled unique-violation fault).
-6. Same-tx atomicity fault injection (agent / credential write / fence
-   / audit / outbox), including a failure injected after the intake
-   credential write commits its statement — everything rolls back, no
-   orphan credential.
-7. Wizard-facing zero-mutation witness (contract 3 §6.10 shape): no
-   call → zero rows in `agents`/`agent_audit_events`/`agent_outbox`/
-   `agent_idempotency_fence` attributable to the family.
-8. `is_system` injection attempt is rejected by DTO validation.
-9. Correlation-id witness (contract 5 §6.3): a correlation id submitted
-   on `agent.enroll` appears in its audit event(s) and in the result;
-   the same holds for `agent.enrollment.get`'s result; the §6.3 static
-   companions (no `any`-typed boundary pass-through; single audit
-   emitter) apply. §6.3's no-existence-oracle probe: an unauthorized
-   `agent.enrollment.get` of an existing agent and a get of a
-   nonexistent id return indistinguishable results.
-10. CLI-parity witness (contract 5 §6.4): a CLI smoke invocation of
-    `agent.enroll` and `agent.enrollment.get` against the Gateway
-    succeeds with the same typed results the web client receives. The
-    implementation slice therefore SHIPS CLI exposure for both
-    operations (contract 5 §4.5 — a Gateway command without CLI
-    exposure is a tracked conformance gap; this design refuses to open
-    one).
-11. Fail-closed witness (contract 5 §6.5): with the owning tool or
-    grant state unreachable (fault injection), the operation returns
-    the internal-fault or authorization-refusal class and performs no
-    fallback read/write.
-
-## 6. Out of scope
-
-Wizard orchestration (M4-6); any UI (D8/D12); un-enroll/update lifecycle
-(no contract requires it in v1 — the legacy write surfaces named in §2
-keep serving existing consumers); OAuth login, multi-account, comms
-auto-enroll, model recommendation (PRD full flow, deferred by D11);
-contract amendments (F1 recorded above for a future S2 pass). CLI
-exposure is explicitly IN scope (witness 10 — contract 5 §4.5 binds it).

docs/plans/2026-08-30_containerization.md

@@ -1,99 +0,0 @@
-# Plan — Stack Containerization (tiered deployment)
-
-Status: DRAFT for review. Charter: fleet/lanes/stack-containerization
-(brain) NORTH-STAR.md; PRD amendment in the same PR adds D15.
-Supersedes nothing; sequences the absorbed M4 remainder per its lane.
-
-## Measured baseline (origin/next @ 143ba0f5, 2026-08-30)
-
-- `docker-compose.yml`: dev infrastructure only — postgres (pgvector),
-  valkey, otel-collector, jaeger. No application services.
-- `docker-compose.federated.yml`: standalone overlay for the FEDERATED
-  storage tier (own postgres/valkey; port-conflicts the base stack by
-  design). Not an app deployment.
-- `docker/gateway.Dockerfile`, `docker/appservice.Dockerfile`:
-  multi-stage production builds (node:22-alpine) EXIST; the gateway image
-  includes the web SPA bundle (#1444).
-- CI (`publish.yml`) builds and publishes these images (next-channel
-  prereleases + main stable), and runs `verify:release` fail-closed.
-- Gap: no stack-level composition wires gateway+appservice+data plane
-  into one deployable unit; no blessed install/upgrade path; no
-  in-container agent-runtime story for the dogfood loop.
-
-## Target (PRD D15 amendment)
-
-Tiered deployment, additive to the existing architecture:
-
-1. **Standalone tier (v1 bar)**: `docker compose up` on one host brings
-   postgres, valkey, openbao, gateway, appservice (and the webUI the
-   gateway serves) to healthy; migrations apply; the webUI hosts agent
-   chat; an in-stack agent can read this repo and open a PR; CI
-   validates; the deployment adopts merged images (pull + restart).
-2. **Enterprise tier (post-v1)**: Kubernetes manifests (or Helm) for the
-   same service set, phase-gated on the standalone bar holding.
-
-## Phases
-
-### Phase A — blessed standalone compose
-
-- A1 Compose service definitions for gateway + appservice joining the
-  existing infra compose (profiles: `dev` keeps today's behavior;
-  `stack` adds the app tier), with health checks and dependency order.
-- A2 Migrations on boot (or an explicit migrate step) with idempotency
-  and version pinning; init-db.sql folded into pg-init.
-- A3 Openbao in the compose set (secret plumbing for the app tier).
-- A4 `.env.example` + `mosaic.config.json` defaults documented for the
-  standalone mode; mode recorded per the mode-conversion contract.
-- A5 Smoke: `docker compose --profile stack up` green on a scratch host;
-  webUI served; agent chat reachable; failures catalogued and fixed.
-- Acceptance: the five-point NORTH-STAR bar measured live.
-
-### Phase B — component completion
-
-- Interface assumption (velma verdict A1, P5-RM-005/006): in-stack
-  dogfood agents inherit SEAT-GRADE identity — credential-slot
-  isolation, wrapper-first enforcement, no privileged coordination
-  identity, evidence by references that resolve outside the container
-  lifetime.
-- Decompose JIT from A5's catalogue. Known candidates: agent runtime
-  bits (brain/tool access paths in-container), repo credentials for the
-  dogfood agent, watch/comms surfaces inside the deployment.
-
-### Phase C — CI/CD parity
-
-- Publish pipeline is the only image source (already true); add the
-  deployment-side pull/upgrade path (compose pull + migrate + restart =
-  next iteration); document the promotion flow next -> registry ->
-  deployment.
-
-### Phase D — coordinator integration (GATED)
-
-- Gate (velma verdict C2): blocked until the checkpoint-and-lease child
-  of the guides-proposed control-plane refactor — core + WU-P1-CHECKPOINT
-  (schema, freshness, incarnation, clean-replacement resume; D57-D60
-  lineage) — carries an independent target-bound PASS. Wiring restarts
-  against the core alone re-creates the stale-incarnation failure class
-  D57-D60 closed. Transitive: inherits the T108 gates (P0 exit + Jason
-  P1 authorization).
-- Scope (velma verdict C1): lifecycle actions (start/stop/restart/
-  health/recovery) executed by the SHIPPED coord client over the one
-  typed coordination contract (request id, actor identity, epoch,
-  revision, lease, correlation; typed stale rejection; worker role
-  boundary). No second coordination interface gets designed here —
-  containerization consumes the coordination contract, never defines it.
-
-### Phase E — enterprise tier
-
-- k8s manifests/Helm for the same set; phase-gated on Phase A holding.
-
-### Absorbed M4 remainder
-
-- M4-3 pivot: KBN-101 foundation first (per ruling R6), then expand DDL.
-- M4-5: lands inside Phase B/C where natural.
-- M4-6 (composes M4-1+M4-4): last, as designed.
-
-## Non-goals (v1)
-
-- No Kubernetes in v1; no multi-host federation; no replacement of the
-  fleet's brain-based seats (the stack is an additional operator
-  surface); no on-host image builds for deployment (registry only).

docs/plans/README.md

@@ -13,10 +13,6 @@ status: active
 - [Documentation structure README implementation](2026-08-10-docs-structure-readme.md) — completed implementation plan for the documentation contract and atlas.
 - [Documentation catalog and truth audit](2026-08-10-docs-catalog-audit.md) — audit method, evidence statuses, deliverables, and acceptance criteria.
 
-## Feature design plans
-
-- [Agent enrollment command design](2026-08-29-agent-enrollment-command-design.md) — v1 rank-4 enrollment command family: contract composition, command surface, schema delta, witnesses (M4-4-0).
-
 After a plan is delivered, update the canonical guide, contract, decision, or index. Do not cite a plan as proof that intended behavior shipped.
 
 ## Related

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/brain/src/mission-tasks.spec.ts

@@ -1,79 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { createMissionTasksRepo } from './mission-tasks.js';
-
-/**
- * SHARED-CONTRACT §5.5 "mission_tasks.status write prohibition": this repo is
- * the sole path that authors mission_tasks.status from caller input (storage
- * tier migration is row transport and preserves stored values; the generic
- * storage adapters have no mission_tasks caller), and it must never forward a
- * caller-supplied status to the database on create or update. Callers keep
- * working (the field is accepted and ignored), so these tests assert on what
- * reaches the Drizzle chain, not on rejection.
- */
-
-function makeInsertDb(returned: unknown[]) {
-  const values = vi.fn((_v: unknown) => ({ returning: vi.fn().mockResolvedValue(returned) }));
-  return { db: { insert: vi.fn(() => ({ values })) }, values };
-}
-
-function makeUpdateDb(returned: unknown[]) {
-  const set = vi.fn((_v: unknown) => ({
-    where: vi.fn(() => ({ returning: vi.fn().mockResolvedValue(returned) })),
-  }));
-  return { db: { update: vi.fn(() => ({ set })) }, set };
-}
-
-describe('createMissionTasksRepo — status write prohibition', () => {
-  it('create strips a caller-supplied status before insert', async () => {
-    const { db, values } = makeInsertDb([{ id: 'mt1', status: 'not-started' }]);
-    const repo = createMissionTasksRepo(db as never);
-
-    const result = await repo.create({
-      missionId: 'm1',
-      userId: 'u1',
-      status: 'done',
-      description: 'd',
-    } as never);
-
-    expect(values).toHaveBeenCalledTimes(1);
-    const inserted = values.mock.calls[0]![0] as Record<string, unknown>;
-    expect('status' in inserted).toBe(false);
-    expect(inserted.missionId).toBe('m1');
-    expect(inserted.description).toBe('d');
-    expect(result.id).toBe('mt1');
-  });
-
-  it('create without status still inserts (DB default applies)', async () => {
-    const { db, values } = makeInsertDb([{ id: 'mt2' }]);
-    const repo = createMissionTasksRepo(db as never);
-
-    await repo.create({ missionId: 'm1', userId: 'u1' } as never);
-
-    const inserted = values.mock.calls[0]![0] as Record<string, unknown>;
-    expect('status' in inserted).toBe(false);
-  });
-
-  it('update strips a caller-supplied status but keeps the other fields', async () => {
-    const { db, set } = makeUpdateDb([{ id: 'mt1', notes: 'n' }]);
-    const repo = createMissionTasksRepo(db as never);
-
-    const result = await repo.update('mt1', { status: 'done', notes: 'n' } as never);
-
-    expect(set).toHaveBeenCalledTimes(1);
-    const updated = set.mock.calls[0]![0] as Record<string, unknown>;
-    expect('status' in updated).toBe(false);
-    expect(updated.notes).toBe('n');
-    expect(updated.updatedAt).toBeInstanceOf(Date);
-    expect(result?.id).toBe('mt1');
-  });
-
-  it('update with only status degenerates to a timestamp-only update', async () => {
-    const { db, set } = makeUpdateDb([{ id: 'mt1' }]);
-    const repo = createMissionTasksRepo(db as never);
-
-    await repo.update('mt1', { status: 'blocked' } as never);
-
-    const updated = set.mock.calls[0]![0] as Record<string, unknown>;
-    expect(Object.keys(updated)).toEqual(['updatedAt']);
-  });
-});

packages/brain/src/mission-tasks.ts

@@ -3,24 +3,6 @@ import { eq, and, type Db, missionTasks } from '@mosaicstack/db';
 export type MissionTask = typeof missionTasks.$inferSelect;
 export type NewMissionTask = typeof missionTasks.$inferInsert;
 
-// SHARED-CONTRACT §5.1 phase 1 / §5.4: mission_tasks.status is prohibited as a
-// write source through the N-1 window. This repo is the sole path that authors
-// status from caller input, so the field is stripped here — accepted and
-// ignored rather than rejected, because the legacy surface is frozen with
-// existing consumers kept working (tool-gateway-mapping.md §3.2). Two other
-// surfaces touch the column and are deliberately NOT stripped:
-// packages/storage/migrate-tier.ts copies whole rows between storage tiers and
-// must preserve the stored value verbatim, and the generic table-keyed storage
-// adapters register mission_tasks but have no caller that targets it (runtime
-// callers use fixed collection constants). Neither authors a new status. The
-// column keeps its DB default, stays declared and readable, and is retired
-// only after no readers remain.
-function stripStatus<T extends { status?: unknown }>(data: T): Omit<T, 'status'> {
-  const rest = { ...data };
-  delete rest.status;
-  return rest;
-}
-
 export function createMissionTasksRepo(db: Db) {
   return {
     async findByMission(missionId: string): Promise<MissionTask[]> {
@@ -48,14 +30,14 @@ export function createMissionTasksRepo(db: Db) {
     },
 
     async create(data: NewMissionTask): Promise<MissionTask> {
-      const rows = await db.insert(missionTasks).values(stripStatus(data)).returning();
+      const rows = await db.insert(missionTasks).values(data).returning();
       return rows[0]!;
     },
 
     async update(id: string, data: Partial<NewMissionTask>): Promise<MissionTask | undefined> {
       const rows = await db
         .update(missionTasks)
-        .set({ ...stripStatus(data), updatedAt: new Date() })
+        .set({ ...data, updatedAt: new Date() })
         .where(eq(missionTasks.id, id))
         .returning();
       return rows[0];

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/0021_agent_enrollment.sql

@@ -1,47 +0,0 @@
-CREATE TYPE "public"."agent_outbox_status" AS ENUM('pending', 'processing', 'delivered');--> statement-breakpoint
-CREATE TABLE "agent_audit_events" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"seq" bigint GENERATED ALWAYS AS IDENTITY (sequence name "agent_audit_events_seq_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 9223372036854775807 START WITH 1 CACHE 1),
-	"event_type" text NOT NULL,
-	"actor_id" text NOT NULL,
-	"agent_id" uuid NOT NULL,
-	"correlation_id" text NOT NULL,
-	"causation_id" uuid,
-	"payload" jsonb NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	CONSTRAINT "agent_audit_events_type_check" CHECK (event_type IN ('agent.enrolled', 'agent.enrollment.replayed'))
-);
---> statement-breakpoint
-CREATE TABLE "agent_idempotency_fence" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"operation" text NOT NULL,
-	"idempotency_key" text NOT NULL,
-	"actor_id" text NOT NULL,
-	"authorization_scope" text NOT NULL,
-	"payload_digest" text NOT NULL,
-	"replay_mode" text DEFAULT 'actor-bound' NOT NULL,
-	"outcome_agent_id" uuid NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	CONSTRAINT "agent_idempotency_fence_replay_mode_check" CHECK (replay_mode IN ('actor-bound', 'shared'))
-);
---> statement-breakpoint
-CREATE TABLE "agent_outbox" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"event_id" uuid NOT NULL,
-	"correlation_id" text NOT NULL,
-	"status" "agent_outbox_status" DEFAULT 'pending' NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"delivered_at" timestamp with time zone
-);
---> statement-breakpoint
-ALTER TABLE "agents" ADD COLUMN "harness" text;--> statement-breakpoint
-ALTER TABLE "agents" ADD COLUMN "enrolled_at" timestamp with time zone;--> statement-breakpoint
-ALTER TABLE "agent_audit_events" ADD CONSTRAINT "agent_audit_events_causation_id_agent_audit_events_id_fk" FOREIGN KEY ("causation_id") REFERENCES "public"."agent_audit_events"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "agent_outbox" ADD CONSTRAINT "agent_outbox_event_id_agent_audit_events_id_fk" FOREIGN KEY ("event_id") REFERENCES "public"."agent_audit_events"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
-CREATE UNIQUE INDEX "agent_audit_events_seq_idx" ON "agent_audit_events" USING btree ("seq");--> statement-breakpoint
-CREATE INDEX "agent_audit_events_agent_seq_idx" ON "agent_audit_events" USING btree ("agent_id","seq");--> statement-breakpoint
-CREATE INDEX "agent_audit_events_correlation_idx" ON "agent_audit_events" USING btree ("correlation_id");--> statement-breakpoint
-CREATE UNIQUE INDEX "agent_idempotency_fence_operation_key_idx" ON "agent_idempotency_fence" USING btree ("operation","idempotency_key");--> statement-breakpoint
-CREATE UNIQUE INDEX "agent_outbox_event_idx" ON "agent_outbox" USING btree ("event_id");--> statement-breakpoint
-CREATE INDEX "agent_outbox_status_created_idx" ON "agent_outbox" USING btree ("status","created_at");

packages/db/drizzle/meta/_journal.json

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

packages/db/src/agent-enrollment.witness.test.ts

@@ -1,412 +0,0 @@
-/**
- * Agent enrollment schema witnesses — M4-4a, the schema-level half of the
- * witness list in docs/plans/2026-08-29-agent-enrollment-command-design.md §5.
- *
- * Witnesses the guarantees migration 0021's tables themselves carry: the
- * event-type CHECK, monotonic per-agent append order (`seq`), deletion-safe
- * linkage (no foreign key from the events or fence tables into `agents` —
- * rows survive a legacy CRUD DELETE of the agent), the causation self-FK,
- * the outbox's FK/uniqueness/status shape, the fence's UNIQUE
- * (operation, key) and replay-mode CHECK, and the nullable enrollment
- * columns on `agents` (legacy rows insert without them). The command-level
- * witnesses (never-echo, same-tx atomicity, replay semantics, correlation,
- * CLI parity, fail-closed) belong to the M4-4b implementation slice.
- *
- * Two legs run the same witness body:
- *  - PGlite (WASM Postgres): always runs.
- *  - Real PostgreSQL: runs when DATABASE_URL is set — the binding witness;
- *    CI migrates ci-postgres before `pnpm test`.
- */
-import { randomUUID } from 'node:crypto';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { sql } from 'drizzle-orm';
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
-import { createDb } from './client.js';
-import { createPgliteDb } from './client-pglite.js';
-import { runPgliteMigrations } from './migrate.js';
-import { agentAuditEvents, agentIdempotencyFence, agentOutbox, agents } from './schema.js';
-
-type AnyDb = {
-  db: {
-    insert: (t: unknown) => { values: (v: unknown) => Promise<unknown> };
-    execute: (q: unknown) => Promise<{ rows?: unknown[] } | unknown[]>;
-  };
-  close: () => Promise<void>;
-};
-
-/** Match a constraint failure anywhere along drizzle's cause chain. */
-async function expectViolation(p: Promise<unknown>, re: RegExp, label = ''): Promise<void> {
-  let err: unknown;
-  try {
-    await p;
-  } catch (e) {
-    err = e;
-  }
-  expect(err, label || 'expected the statement to be refused').toBeDefined();
-  const messages: string[] = [];
-  let cur: unknown = err;
-  while (cur instanceof Error) {
-    messages.push(cur.message);
-    cur = (cur as { cause?: unknown }).cause;
-  }
-  expect(messages.join(' | '), label).toMatch(re);
-}
-
-function rows(res: { rows?: unknown[] } | unknown[]): Record<string, unknown>[] {
-  return (Array.isArray(res) ? res : (res.rows ?? [])) as Record<string, unknown>[];
-}
-
-/** Unique per-run prefix so real-PG runs never collide and clean up safely. */
-const T = `agent-e-${randomUUID().slice(0, 8)}`;
-
-type EventInsert = typeof agentAuditEvents.$inferInsert;
-
-function eventRow(overrides: Partial<EventInsert> = {}): EventInsert {
-  return {
-    eventType: 'agent.enrolled',
-    actorId: `${T}-actor`,
-    agentId: randomUUID(),
-    correlationId: `${T}-corr-${randomUUID()}`,
-    payload: {
-      harness: 'claude-code',
-      provider: 'anthropic',
-      name: 'x',
-      credentialMode: 'reference',
-    },
-    ...overrides,
-  };
-}
-
-type FenceInsert = typeof agentIdempotencyFence.$inferInsert;
-
-function fenceRow(overrides: Partial<FenceInsert> = {}): FenceInsert {
-  return {
-    operation: 'agent.enroll',
-    idempotencyKey: `${T}-${randomUUID()}`,
-    actorId: `${T}-actor`,
-    authorizationScope: 'platform-user',
-    payloadDigest: `${T}-digest`,
-    outcomeAgentId: randomUUID(),
-    ...overrides,
-  };
-}
-
-function witnessSuite(getHandle: () => AnyDb): void {
-  const db = () => getHandle().db as unknown as ReturnType<typeof createDb>['db'];
-
-  afterAll(async () => {
-    const d = db();
-    await d.execute(sql`DELETE FROM agent_outbox WHERE correlation_id LIKE ${T + '%'}`);
-    // Caused events first: the causation self-FK is RESTRICT.
-    await d.execute(
-      sql`DELETE FROM agent_audit_events WHERE correlation_id LIKE ${T + '%'} AND causation_id IS NOT NULL`,
-    );
-    await d.execute(sql`DELETE FROM agent_audit_events WHERE correlation_id LIKE ${T + '%'}`);
-    await d.execute(sql`DELETE FROM agent_idempotency_fence WHERE actor_id LIKE ${T + '%'}`);
-    await d.execute(sql`DELETE FROM agents WHERE name LIKE ${T + '%'}`);
-  });
-
-  // ── agents: nullable enrollment columns (no backfill semantics) ────────────
-
-  it('legacy agent rows insert without enrollment columns; enrolled rows carry both', async () => {
-    const legacyId = randomUUID();
-    await db()
-      .insert(agents)
-      .values({
-        id: legacyId,
-        name: `${T}-legacy`,
-        provider: 'anthropic',
-        model: 'claude-fable-5',
-      });
-    const legacy = rows(
-      await db().execute(sql`SELECT harness, enrolled_at FROM agents WHERE id = ${legacyId}`),
-    )[0]!;
-    expect(legacy['harness']).toBeNull();
-    expect(legacy['enrolled_at']).toBeNull();
-
-    const enrolledId = randomUUID();
-    await db()
-      .insert(agents)
-      .values({
-        id: enrolledId,
-        name: `${T}-enrolled`,
-        provider: 'anthropic',
-        model: 'claude-fable-5',
-        harness: 'claude-code',
-        enrolledAt: new Date(),
-      });
-    const enrolled = rows(
-      await db().execute(sql`SELECT harness, enrolled_at FROM agents WHERE id = ${enrolledId}`),
-    )[0]!;
-    expect(enrolled['harness']).toBe('claude-code');
-    expect(enrolled['enrolled_at']).not.toBeNull();
-  });
-
-  // ── agent_audit_events: CHECK, ordering, deletion-safe linkage ─────────────
-
-  it('accepts both declared event types and refuses an undeclared one', async () => {
-    await db()
-      .insert(agentAuditEvents)
-      .values(eventRow({ eventType: 'agent.enrolled' }));
-    await db()
-      .insert(agentAuditEvents)
-      .values(eventRow({ eventType: 'agent.enrollment.replayed' }));
-    await expectViolation(
-      db()
-        .insert(agentAuditEvents)
-        .values(eventRow({ eventType: 'agent.deleted' })),
-      /type_check|violates check/i,
-      'undeclared event type must be refused',
-    );
-  });
-
-  it('assigns strictly increasing seq in insert order for one agent', async () => {
-    const agentId = randomUUID();
-    const c1 = `${T}-seq-1-${randomUUID()}`;
-    const c2 = `${T}-seq-2-${randomUUID()}`;
-    await db()
-      .insert(agentAuditEvents)
-      .values(eventRow({ agentId, correlationId: c1 }));
-    await db()
-      .insert(agentAuditEvents)
-      .values(eventRow({ agentId, eventType: 'agent.enrollment.replayed', correlationId: c2 }));
-    const res = rows(
-      await db().execute(
-        sql`SELECT correlation_id, seq FROM agent_audit_events WHERE agent_id = ${agentId} ORDER BY seq ASC`,
-      ),
-    );
-    expect(res.map((r) => r['correlation_id'])).toEqual([c1, c2]);
-    expect(Number(res[1]!['seq'])).toBeGreaterThan(Number(res[0]!['seq']));
-  });
-
-  it('has no foreign key into agents, and events survive agent deletion', async () => {
-    const fks = rows(
-      await db().execute(sql`
-        SELECT ccu.table_name AS referenced_table
-        FROM information_schema.table_constraints tc
-        JOIN information_schema.constraint_column_usage ccu
-          ON ccu.constraint_name = tc.constraint_name AND ccu.constraint_schema = tc.constraint_schema
-        WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = 'agent_audit_events'
-      `),
-    );
-    // The causation self-FK is the ONLY foreign key on the events table.
-    expect([...new Set(fks.map((r) => r['referenced_table']))]).toEqual(['agent_audit_events']);
-
-    const agentId = randomUUID();
-    await db()
-      .insert(agents)
-      .values({ id: agentId, name: `${T}-doomed`, provider: 'anthropic', model: 'claude-fable-5' });
-    const corr = `${T}-survive-${randomUUID()}`;
-    await db()
-      .insert(agentAuditEvents)
-      .values(eventRow({ agentId, correlationId: corr }));
-    await db().execute(sql`DELETE FROM agents WHERE id = ${agentId}`);
-    const after = rows(
-      await db().execute(
-        sql`SELECT agent_id FROM agent_audit_events WHERE correlation_id = ${corr}`,
-      ),
-    );
-    expect(after).toHaveLength(1);
-    expect(after[0]!['agent_id']).toBe(agentId);
-  });
-
-  it('enforces the causation self-FK and RESTRICTs deleting a cause', async () => {
-    await expectViolation(
-      db()
-        .insert(agentAuditEvents)
-        .values(eventRow({ causationId: randomUUID() })),
-      /foreign key/i,
-      'causation must reference an existing event',
-    );
-    const causeCorr = `${T}-cause-${randomUUID()}`;
-    await db()
-      .insert(agentAuditEvents)
-      .values(eventRow({ correlationId: causeCorr }));
-    const cause = rows(
-      await db().execute(
-        sql`SELECT id FROM agent_audit_events WHERE correlation_id = ${causeCorr}`,
-      ),
-    )[0]!;
-    await db()
-      .insert(agentAuditEvents)
-      .values(
-        eventRow({
-          eventType: 'agent.enrollment.replayed',
-          causationId: cause['id'] as string,
-        }),
-      );
-    await expectViolation(
-      db().execute(sql`DELETE FROM agent_audit_events WHERE id = ${cause['id'] as string}`),
-      /foreign key/i,
-      'a cause with dependent events must not be deletable',
-    );
-  });
-
-  // ── agent_outbox shape ─────────────────────────────────────────────────────
-
-  it('outbox rows require an existing event, one outbox row per event, closed status enum', async () => {
-    await expectViolation(
-      db()
-        .insert(agentOutbox)
-        .values({ eventId: randomUUID(), correlationId: `${T}-corr` }),
-      /foreign key/i,
-      'outbox must reference an existing event',
-    );
-    const corr = `${T}-ob-${randomUUID()}`;
-    await db()
-      .insert(agentAuditEvents)
-      .values(eventRow({ correlationId: corr }));
-    const event = rows(
-      await db().execute(sql`SELECT id FROM agent_audit_events WHERE correlation_id = ${corr}`),
-    )[0]!;
-    const eventId = event['id'] as string;
-    await db().insert(agentOutbox).values({ eventId, correlationId: corr });
-    await expectViolation(
-      db()
-        .insert(agentOutbox)
-        .values({ eventId, correlationId: `${T}-ob2` }),
-      /duplicate key|unique/i,
-      'one outbox record per event',
-    );
-    await expectViolation(
-      db().execute(
-        sql`INSERT INTO agent_outbox (event_id, correlation_id, status)
-            VALUES (${eventId}, ${`${T}-ob3`}, 'failed')`,
-      ),
-      /invalid input value for enum|22P02/i,
-      'status outside pending/processing/delivered must be refused',
-    );
-  });
-
-  it('outbox FK RESTRICTs event deletion while the outbox row exists', async () => {
-    const corr = `${T}-obr-${randomUUID()}`;
-    await db()
-      .insert(agentAuditEvents)
-      .values(eventRow({ correlationId: corr }));
-    const event = rows(
-      await db().execute(sql`SELECT id FROM agent_audit_events WHERE correlation_id = ${corr}`),
-    )[0]!;
-    await db()
-      .insert(agentOutbox)
-      .values({ eventId: event['id'] as string, correlationId: corr });
-    await expectViolation(
-      db().execute(sql`DELETE FROM agent_audit_events WHERE id = ${event['id'] as string}`),
-      /foreign key/i,
-    );
-  });
-
-  // ── agent_idempotency_fence: (operation, key) uniqueness, mode CHECK ───────
-
-  it('refuses a duplicate (operation, key) pair but allows the same key under another operation', async () => {
-    const key = `${T}-fence-${randomUUID()}`;
-    await db()
-      .insert(agentIdempotencyFence)
-      .values(fenceRow({ idempotencyKey: key }));
-    await expectViolation(
-      db()
-        .insert(agentIdempotencyFence)
-        .values(fenceRow({ idempotencyKey: key })),
-      /duplicate key|unique/i,
-      'fence uniqueness is (operation, key)',
-    );
-    // Same key, different operation identifier: a distinct fence.
-    await db()
-      .insert(agentIdempotencyFence)
-      .values(fenceRow({ idempotencyKey: key, operation: 'agent.other' }));
-  });
-
-  it('defaults replay mode to actor-bound and refuses an undeclared mode', async () => {
-    const key = `${T}-mode-${randomUUID()}`;
-    await db()
-      .insert(agentIdempotencyFence)
-      .values(fenceRow({ idempotencyKey: key }));
-    const row = rows(
-      await db().execute(
-        sql`SELECT replay_mode FROM agent_idempotency_fence WHERE idempotency_key = ${key}`,
-      ),
-    )[0]!;
-    expect(row['replay_mode']).toBe('actor-bound');
-    await expectViolation(
-      db()
-        .insert(agentIdempotencyFence)
-        .values(fenceRow({ replayMode: 'unbound' as 'actor-bound' })),
-      /replay_mode_check|violates check/i,
-      'a mode outside actor-bound/shared must be refused',
-    );
-  });
-
-  it('fence has no foreign key at all, and rows survive agent deletion', async () => {
-    const fks = rows(
-      await db().execute(sql`
-        SELECT ccu.table_name AS referenced_table
-        FROM information_schema.table_constraints tc
-        JOIN information_schema.constraint_column_usage ccu
-          ON ccu.constraint_name = tc.constraint_name AND ccu.constraint_schema = tc.constraint_schema
-        WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = 'agent_idempotency_fence'
-      `),
-    );
-    expect(fks).toHaveLength(0);
-
-    const agentId = randomUUID();
-    await db()
-      .insert(agents)
-      .values({
-        id: agentId,
-        name: `${T}-fdoomed`,
-        provider: 'anthropic',
-        model: 'claude-fable-5',
-      });
-    const key = `${T}-fsurvive-${randomUUID()}`;
-    await db()
-      .insert(agentIdempotencyFence)
-      .values(fenceRow({ idempotencyKey: key, outcomeAgentId: agentId }));
-    await db().execute(sql`DELETE FROM agents WHERE id = ${agentId}`);
-    const after = rows(
-      await db().execute(
-        sql`SELECT outcome_agent_id FROM agent_idempotency_fence WHERE idempotency_key = ${key}`,
-      ),
-    );
-    expect(after).toHaveLength(1);
-    expect(after[0]!['outcome_agent_id']).toBe(agentId);
-  });
-}
-
-// ── Leg 1: PGlite (always runs — local witness signal) ───────────────────────
-
-describe('agent enrollment schema witnesses — PGlite', () => {
-  let dir: string;
-  let handle: ReturnType<typeof createPgliteDb>;
-
-  beforeAll(async () => {
-    dir = mkdtempSync(join(tmpdir(), 'agent-enroll-witness-'));
-    handle = createPgliteDb(dir);
-    await runPgliteMigrations(handle);
-  });
-
-  afterAll(async () => {
-    await handle.close();
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  witnessSuite(() => handle as unknown as AnyDb);
-});
-
-// ── Leg 2: real PostgreSQL (binding witness, ci-postgres in CI) ──────────────
-
-const hasPostgres = Boolean(process.env['DATABASE_URL']);
-
-describe.skipIf(!hasPostgres)('agent enrollment schema witnesses — real PostgreSQL', () => {
-  let handle: ReturnType<typeof createDb>;
-
-  beforeAll(() => {
-    handle = createDb(process.env['DATABASE_URL']!);
-  });
-
-  afterAll(async () => {
-    await handle.close();
-  });
-
-  witnessSuite(() => handle as unknown as AnyDb);
-});

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

@@ -302,11 +302,6 @@ export const agents = pgTable(
     skills: jsonb('skills').$type<string[]>(),
     isSystem: boolean('is_system').notNull().default(false),
     config: jsonb('config'),
-    // Enrollment (M4-4, docs/plans/2026-08-29-agent-enrollment-command-design.md §4).
-    // NULL on both marks a legacy (non-enrolled) row; no backfill — enrollment
-    // is a fact the rank-4 command creates, not one to invent for existing rows.
-    harness: text('harness'),
-    enrolledAt: timestamp('enrolled_at', { withTimezone: true }),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
   },
@@ -1068,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',
@@ -1126,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',
   {
@@ -1146,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()
@@ -1155,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',
@@ -1192,7 +1170,6 @@ export const HIERARCHY_AUDIT_VERBS = [
   'create',
   'rename',
   'transfer',
-  'visibility_change',
   'delete',
   'grant_create',
   'grant_change',
@@ -1243,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',
@@ -1284,109 +1261,3 @@ export const hierarchyOutbox = pgTable(
     index('hierarchy_outbox_status_created_idx').on(t.status, t.createdAt),
   ],
 );
-
-// ---------------------------------------------------------------------------
-// Agent enrollment (M4-4) — rank-4 command family audit/outbox/fence stores.
-// Design: docs/plans/2026-08-29-agent-enrollment-command-design.md §4.
-// Pattern reuse from the hierarchy audit/outbox pair, separate store. Audit
-// rows reference the agent by snapshot id, deliberately with NO FK, so audit
-// history survives agent deletion through the legacy CRUD DELETE path.
-// Idempotency for this family lives in agent_idempotency_fence (contract 3
-// §4.3 envelope, ratified into contract 5 §4 via contract 3 §7 item 4) — the
-// audit and outbox tables carry no idempotency key of their own.
-
-export const AGENT_AUDIT_EVENT_TYPES = [
-  // Semantic mutation event of agent.enroll.
-  'agent.enrolled',
-  // Non-mutation access class: a passing idempotent replay appends this and
-  // nothing else (accessing principal, current correlation id, fence-row
-  // reference in the payload).
-  'agent.enrollment.replayed',
-] as const;
-
-export const agentAuditEvents = pgTable(
-  'agent_audit_events',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    // Global append order; per-agent ordering is a filter on agent_id ordered
-    // by seq.
-    seq: bigint('seq', { mode: 'number' }).notNull().generatedAlwaysAsIdentity(),
-    eventType: text('event_type').notNull(),
-    // No FK: audit events outlive every principal and every target.
-    actorId: text('actor_id').notNull(),
-    agentId: uuid('agent_id').notNull(),
-    correlationId: text('correlation_id').notNull(),
-    causationId: uuid('causation_id').references((): AnyPgColumn => agentAuditEvents.id, {
-      onDelete: 'restrict',
-    }),
-    // Immutable snapshot at event time; never carries credential material
-    // (§3.1 rule 1: actor, agent id, harness, provider, name, credentialMode).
-    payload: jsonb('payload').notNull(),
-    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-  },
-  (t) => [
-    uniqueIndex('agent_audit_events_seq_idx').on(t.seq),
-    index('agent_audit_events_agent_seq_idx').on(t.agentId, t.seq),
-    index('agent_audit_events_correlation_idx').on(t.correlationId),
-    check(
-      'agent_audit_events_type_check',
-      sql`event_type IN ('agent.enrolled', 'agent.enrollment.replayed')`,
-    ),
-  ],
-);
-
-export const agentOutboxStatusEnum = pgEnum('agent_outbox_status', [
-  'pending',
-  'processing',
-  'delivered',
-]);
-
-export const agentOutbox = pgTable(
-  'agent_outbox',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    // FK into the append-only events table: never dangles, RESTRICT is safe.
-    eventId: uuid('event_id')
-      .notNull()
-      .references(() => agentAuditEvents.id, { onDelete: 'restrict' }),
-    correlationId: text('correlation_id').notNull(),
-    status: agentOutboxStatusEnum('status').notNull().default('pending'),
-    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-    deliveredAt: timestamp('delivered_at', { withTimezone: true }),
-  },
-  (t) => [
-    uniqueIndex('agent_outbox_event_idx').on(t.eventId),
-    index('agent_outbox_status_created_idx').on(t.status, t.createdAt),
-  ],
-);
-
-// Contract 3 §4.3 fence shape. Uniqueness is (operation, key); the recorded
-// replay mode is always 'actor-bound' for this family (`shared` is seed-only
-// and refused at validation — design §3.1), but the column keeps the ratified
-// envelope shape and serves the mode-mismatch collision check. The payload
-// digest input EXCLUDES the credential value (design §3.1 rule 5).
-export const agentIdempotencyFence = pgTable(
-  'agent_idempotency_fence',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    operation: text('operation').notNull(),
-    idempotencyKey: text('idempotency_key').notNull(),
-    // No FK: fence rows outlive principals, mirroring the audit tables.
-    actorId: text('actor_id').notNull(),
-    authorizationScope: text('authorization_scope').notNull(),
-    payloadDigest: text('payload_digest').notNull(),
-    replayMode: text('replay_mode').notNull().default('actor-bound'),
-    // Committed-outcome reference (the enrolled agent's id). Snapshot value,
-    // no FK: the fence must keep answering replays after a legacy DELETE.
-    outcomeAgentId: uuid('outcome_agent_id').notNull(),
-    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-  },
-  (t) => [
-    uniqueIndex('agent_idempotency_fence_operation_key_idx').on(t.operation, t.idempotencyKey),
-    check(
-      'agent_idempotency_fence_replay_mode_check',
-      sql`replay_mode IN ('actor-bound', 'shared')`,
-    ),
-  ],
-);

packages/mosaic/framework/tools/git/issue-assign.sh

@@ -47,7 +47,7 @@ usage_error() {
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue|--number)
+        -i|--issue)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE="$2"
             shift 2

packages/mosaic/framework/tools/git/issue-close.sh

@@ -12,7 +12,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 ISSUE_NUMBER=""
 COMMENT=""
-BODY_FILE=""
 
 # Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
 # distinct from provider, credential, and verification failures (exit 1), so a
@@ -25,7 +24,7 @@ usage_error() {
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue|--number)
+        -i|--issue)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
@@ -37,18 +36,11 @@ while [[ $# -gt 0 ]]; do
             COMMENT="$2"
             shift 2
             ;;
-        --body-file)
-            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
-            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
-            BODY_FILE="$2"
-            shift 2
-            ;;
         -h|--help)
             echo "Usage: issue-close.sh -i <issue_number> [-b <comment>]"
             echo ""
             echo "Options:"
-            echo "  -n, --number   Issue number (required; canonical)"
-            echo "  -i, --issue    Alias for --number"
+            echo "  -i, --issue    Issue number (required)"
             echo "  -b, --body     Comment to add before closing (optional; canonical)"
             echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
@@ -62,19 +54,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
-# exclusive with an explicit --body/--comment value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        COMMENT=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 if [[ -z "$ISSUE_NUMBER" ]]; then
     usage_error "issue number is required (-i/--issue)"
 fi

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -31,7 +31,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 ISSUE_NUMBER=""
 COMMENT=""
-BODY_FILE=""
 LOGIN_OVERRIDE=""
 
 # Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
@@ -46,7 +45,7 @@ usage_error() {
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue|--number)
+        -i|--issue)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
@@ -59,12 +58,6 @@ while [[ $# -gt 0 ]]; do
             COMMENT="$2"
             shift 2
             ;;
-        --body-file)
-            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
-            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
-            BODY_FILE="$2"
-            shift 2
-            ;;
         -l|--login)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LOGIN_OVERRIDE="$2"
@@ -74,8 +67,7 @@ while [[ $# -gt 0 ]]; do
             echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]"
             echo ""
             echo "Options:"
-            echo "  -n, --number   Issue number (required; canonical)"
-            echo "  -i, --issue    Alias for --number"
+            echo "  -i, --issue    Issue number (required)"
             echo "  -b, --body     Comment text (required; canonical)"
             echo "  -c, --comment  Alias for --body"
             echo "  -l, --login    Override the detected Gitea tea login for this call"
@@ -90,19 +82,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
-# exclusive with an explicit --body/--comment value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        COMMENT=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 if [[ -z "$ISSUE_NUMBER" ]]; then
     usage_error "issue number is required (-i/--issue)"
 fi

packages/mosaic/framework/tools/git/issue-create.sh

@@ -10,7 +10,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Default values
 TITLE=""
 BODY=""
-BODY_FILE=""
 LABELS=""
 MILESTONE=""
 INTERACTIVE=false
@@ -101,12 +100,6 @@ while [[ $# -gt 0 ]]; do
             BODY="$2"
             shift 2
             ;;
-        --body-file)
-            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
-            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
-            BODY_FILE="$2"
-            shift 2
-            ;;
         -l|--labels)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
@@ -131,19 +124,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into BODY (file or stdin '-');
-# exclusive with an explicit --body/--comment value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$BODY" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        BODY=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        BODY=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 if [[ "$INTERACTIVE" == true ]]; then
     [[ -n "$TITLE" ]] || read -r -p "Issue title: " TITLE
     [[ -n "$BODY" ]] || read -r -p "Issue body (optional): " BODY || true

packages/mosaic/framework/tools/git/issue-edit.sh

@@ -11,7 +11,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 ISSUE_NUMBER=""
 TITLE=""
 BODY=""
-BODY_FILE=""
 LABELS=""
 MILESTONE=""
 
@@ -26,7 +25,7 @@ usage_error() {
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue|--number)
+        -i|--issue)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
@@ -41,12 +40,6 @@ while [[ $# -gt 0 ]]; do
             BODY="$2"
             shift 2
             ;;
-        --body-file)
-            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
-            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
-            BODY_FILE="$2"
-            shift 2
-            ;;
         -l|--labels)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
@@ -61,8 +54,7 @@ while [[ $# -gt 0 ]]; do
             echo "Usage: issue-edit.sh -i <issue_number> [-t <title>] [-b <body>] [-l <labels>] [-m <milestone>]"
             echo ""
             echo "Options:"
-            echo "  -n, --number     Issue number (required; canonical)"
-            echo "  -i, --issue      Alias for --number"
+            echo "  -i, --issue      Issue number (required)"
             echo "  -t, --title      New title"
             echo "  -b, --body       New body/description"
             echo "  -l, --labels     Labels (comma-separated, replaces existing)"
@@ -78,19 +70,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into BODY (file or stdin '-');
-# exclusive with an explicit --body/--comment value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$BODY" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        BODY=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        BODY=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 if [[ -z "$ISSUE_NUMBER" ]]; then
     usage_error "issue number is required (-i/--issue)"
 fi

packages/mosaic/framework/tools/git/issue-list.sh

@@ -54,7 +54,7 @@ while [[ $# -gt 0 ]]; do
             STATE="$2"
             shift 2
             ;;
-        -l|--label|--labels)
+        -l|--label)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABEL="$2"
             shift 2

packages/mosaic/framework/tools/git/issue-reopen.sh

@@ -11,7 +11,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 ISSUE_NUMBER=""
 COMMENT=""
-BODY_FILE=""
 
 # Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
 # distinct from provider, credential, and verification failures (exit 1), so a
@@ -24,7 +23,7 @@ usage_error() {
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue|--number)
+        -i|--issue)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
@@ -36,18 +35,11 @@ while [[ $# -gt 0 ]]; do
             COMMENT="$2"
             shift 2
             ;;
-        --body-file)
-            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
-            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
-            BODY_FILE="$2"
-            shift 2
-            ;;
         -h|--help)
             echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>]"
             echo ""
             echo "Options:"
-            echo "  -n, --number   Issue number (required; canonical)"
-            echo "  -i, --issue    Alias for --number"
+            echo "  -i, --issue    Issue number (required)"
             echo "  -b, --body     Comment to add when reopening (optional; canonical)"
             echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
@@ -61,19 +53,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
-# exclusive with an explicit --body/--comment value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        COMMENT=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 if [[ -z "$ISSUE_NUMBER" ]]; then
     usage_error "issue number is required (-i/--issue)"
 fi

packages/mosaic/framework/tools/git/issue-view.sh

@@ -81,7 +81,7 @@ if comments:
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue|--number)
+        -i|--issue)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
@@ -90,8 +90,7 @@ while [[ $# -gt 0 ]]; do
             echo "Usage: issue-view.sh -i <issue_number>"
             echo ""
             echo "Options:"
-            echo "  -n, --number   Issue number (required; canonical)"
-            echo "  -i, --issue    Alias for --number"
+            echo "  -i, --issue    Issue number (required)"
             echo ""
             echo "Comments are always included (tea --comments / Gitea API /comments)."
             echo "  -h, --help     Show this help"

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

@@ -11,7 +11,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 PR_NUMBER=""
 COMMENT=""
-BODY_FILE=""
 
 # Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
 # distinct from provider, credential, and verification failures (exit 1), so a
@@ -36,12 +35,6 @@ while [[ $# -gt 0 ]]; do
             COMMENT="$2"
             shift 2
             ;;
-        --body-file)
-            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
-            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
-            BODY_FILE="$2"
-            shift 2
-            ;;
         -h|--help)
             echo "Usage: pr-close.sh -n <pr_number> [-b <comment>]"
             echo ""
@@ -60,19 +53,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
-# exclusive with an explicit --body/--comment value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        COMMENT=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 if [[ -z "$PR_NUMBER" ]]; then
     usage_error "PR number is required (-n/--number)"
 fi

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

@@ -10,7 +10,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Default values
 TITLE=""
 BODY=""
-BODY_FILE=""
 BASE_BRANCH=""
 HEAD_BRANCH=""
 LABELS=""
@@ -159,12 +158,6 @@ while [[ $# -gt 0 ]]; do
             BODY="$2"
             shift 2
             ;;
-        --body-file)
-            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
-            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
-            BODY_FILE="$2"
-            shift 2
-            ;;
         -B|--base)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BASE_BRANCH="$2"
@@ -204,19 +197,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into BODY (file or stdin '-');
-# exclusive with an explicit --body/--comment value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$BODY" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        BODY=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        BODY=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 # If no title but issue provided, generate title
 if [[ -z "$TITLE" ]] && [[ -n "$ISSUE" ]]; then
     TITLE="Fixes #$ISSUE"

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

@@ -13,33 +13,21 @@ OUTPUT_FILE=""
 REPO_OVERRIDE=""
 HOST_OVERRIDE=""
 
-# Usage-error contract (R4): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: pr-diff.sh -n <pr_number> [-r owner/repo] [--host host] [-o <output_file>] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -o|--output)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             OUTPUT_FILE="$2"
             shift 2
             ;;
         -r|--repo)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
         --host)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             HOST_OVERRIDE="$2"
             shift 2
             ;;
@@ -52,18 +40,18 @@ while [[ $# -gt 0 ]]; do
             echo "      --host     Gitea host for --repo API calls (or set GITEA_HOST/GITEA_URL)"
             echo "  -o, --output   Output file (optional, prints to stdout if omitted)"
             echo "  -h, --help     Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    usage_error "PR number is required (-n/--number)"
+    echo "Error: PR number is required (-n)" >&2
+    exit 1
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then

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

@@ -11,7 +11,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 TITLE=""
 BODY=""
-BODY_FILE=""
 BASE_BRANCH=""
 DRAFT_MODE=""
 LOGIN_OVERRIDE=""
@@ -66,7 +65,6 @@ while [[ $# -gt 0 ]]; do
         -n|--number) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; PR_NUMBER="${2:-}"; shift 2 ;;
         -t|--title) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; TITLE="${2:-}"; shift 2 ;;
         -b|--body) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; BODY="${2:-}"; shift 2 ;;
-        --body-file) [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"; BODY_FILE="$2"; shift 2 ;;
         -B|--base) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; BASE_BRANCH="${2:-}"; shift 2 ;;
         --draft)
             [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
@@ -82,19 +80,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into BODY (file or stdin '-');
-# exclusive with an explicit --body value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$BODY" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        BODY=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        BODY=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 [[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 2; }
 [[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 2; }
 if [[ -z "$TITLE" && -z "$BODY" && -z "$BASE_BRANCH" && -z "$DRAFT_MODE" ]]; then

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

@@ -34,41 +34,29 @@ Examples:
     $(basename "$0") -s merged -a username    # Merged PRs by user
     $(basename "$0") --repo ddk/ai-bma         # List PRs from anywhere
 EOF
-    exit "${1:-2}"
+    exit "${1:-1}"
 }
 
 # Parse arguments
-# Usage-error contract (R4): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    usage >&2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -s|--state)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             STATE="$2"
             shift 2
             ;;
-        -l|--label|--labels)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
+        -l|--label)
             LABEL="$2"
             shift 2
             ;;
         -a|--author)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             AUTHOR="$2"
             shift 2
             ;;
         -n|--limit)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LIMIT="$2"
             shift 2
             ;;
         -r|--repo)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
@@ -76,7 +64,8 @@ while [[ $# -gt 0 ]]; do
             usage 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1" >&2
+            usage
             ;;
     esac
 done

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/pr-metadata.sh

@@ -12,23 +12,13 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 OUTPUT_FILE=""
 
-# Usage-error contract (R4): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: pr-metadata.sh -n <pr_number> [-o <output_file>] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -o|--output)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             OUTPUT_FILE="$2"
             shift 2
             ;;
@@ -39,18 +29,18 @@ while [[ $# -gt 0 ]]; do
             echo "  -n, --number   PR number (required)"
             echo "  -o, --output   Output file (optional, prints to stdout if omitted)"
             echo "  -h, --help     Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1" >&2
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    usage_error "PR number is required (-n/--number)"
+    echo "Error: PR number is required (-n)" >&2
+    exit 1
 fi
 
 write_metadata() {

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

@@ -39,7 +39,6 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 ACTION=""
 COMMENT=""
-BODY_FILE=""
 LOGIN_OVERRIDE=""
 REPO_OVERRIDE=""
 HOST_OVERRIDE=""
@@ -72,12 +71,6 @@ while [[ $# -gt 0 ]]; do
             COMMENT="$2"
             shift 2
             ;;
-        --body-file)
-            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
-            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
-            BODY_FILE="$2"
-            shift 2
-            ;;
         -l|--login)
             [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LOGIN_OVERRIDE="$2"
@@ -115,19 +108,6 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
-# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
-# exclusive with an explicit --body/--comment value.
-if [[ -n "$BODY_FILE" ]]; then
-    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
-    if [[ "$BODY_FILE" == "-" ]]; then
-        COMMENT=$(cat) || usage_error "could not read body from stdin"
-    else
-        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
-        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
-    fi
-fi
-
-
 if [[ -z "$PR_NUMBER" ]]; then
     usage_error "PR number is required (-n/--number)"
 fi

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

@@ -11,23 +11,13 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 REPO_OVERRIDE=""
 
-# Usage-error contract (R4): usage errors print to STDERR and exit 2,
-# distinct from provider, credential, and verification failures (exit 1).
-usage_error() {
-    echo "Error: $*" >&2
-    echo "Usage: pr-view.sh -n <pr_number> [-r owner/repo] (see --help)" >&2
-    exit 2
-}
-
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -r|--repo)
-            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
@@ -38,18 +28,18 @@ while [[ $# -gt 0 ]]; do
             echo "  -n, --number   PR number (required)"
             echo "  -r, --repo     Repository slug (default: infer from git origin)"
             echo "  -h, --help     Show this help"
-            echo ""
-            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure."
             exit 0
             ;;
         *)
-            usage_error "unknown option: $1"
+            echo "Unknown option: $1"
+            exit 1
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    usage_error "PR number is required (-n/--number)"
+    echo "Error: PR number is required (-n)"
+    exit 1
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then

packages/mosaic/framework/tools/git/test-issue-comment-usage-contract.sh

@@ -161,30 +161,6 @@ rc=0
 grep -q "GitHub comment write failed" "$ERR_FILE" || fail "GitHub path: normalized error missing from stderr"
 grep -q "^gh issue comment" "$PROBE_LOG" || fail "GitHub path: gh write was not invoked"
 
-# R3 body-file arms (2026-08-29): --body-file <path> and '-' (stdin).
-BF_FILE="$WORK_DIR/body.md"
-printf 'line one\nline two\n' > "$BF_FILE"
-
-# File loads the body: parse acceptance then credential-class failure
-# (sandboxed runner: rc nonzero and NOT 2).
-rc=0
-run_wrapper_sandboxed -i 5 --body-file "$BF_FILE" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-[[ "$rc" -ne 0 ]] || fail "body-file arm unexpectedly succeeded in the sandbox"
-[[ "$rc" -ne 2 ]] || fail "body-file arm misclassified credential failure as a usage error"
-
-# Stdin form loads the body the same way.
-rc=0
-printf 'from stdin' | run_wrapper_sandboxed -i 5 --body-file - >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-[[ "$rc" -ne 0 && "$rc" -ne 2 ]] || fail "body-file stdin arm rc=$rc (want nonzero, not 2)"
-
-# Mutually exclusive with --body: rc 2.
-expect_rc 2 "body-file + body exclusive" -i 5 --body-file "$BF_FILE" -b explicit
-expect_stderr "mutually exclusive" "exclusivity message on stderr"
-
-# Missing file: rc 2 naming the path.
-expect_rc 2 "missing body file" -i 5 --body-file "$WORK_DIR/nope.md"
-expect_stderr "not readable" "missing-file message on stderr"
-
 # 7. No provider contact from any usage-error arm (arm 6b's deliberate gh
 # invocation is the only permitted entry in the probe log).
 if grep -v '^gh issue comment' "$PROBE_LOG" | grep -q .; then

packages/mosaic/framework/tools/git/test-pr-diff-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for pr-diff.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-diff-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-diff.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/pr-diff.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: pr-diff.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -n exits 2"
-expect_stderr "PR number is required" "missing -n message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -n -o -r --number --output --repo --host; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -n --help
-expect_rc 2 "short flag value rejected" -n -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -n; do
-    rc=0
-    run_wrapper_sandboxed -n 5 >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "pr-diff.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-list-usage-contract.sh

@@ -1,131 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for pr-list.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-list-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-list.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/pr-list.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: pr-list.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -s -l -a -n -r --state --label --author --limit --repo; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -s --help
-expect_rc 2 "short flag value rejected" -s -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -s; do
-    rc=0
-    run_wrapper_sandboxed -s open >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "pr-list.sh usage-contract regression passed (R1/R4)"

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/framework/tools/git/test-pr-metadata-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for pr-metadata.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-metadata-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-metadata.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/pr-metadata.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: pr-metadata.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -n exits 2"
-expect_stderr "PR number is required" "missing -n message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -n -o --number --output; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -n --help
-expect_rc 2 "short flag value rejected" -n -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -n; do
-    rc=0
-    run_wrapper_sandboxed -n 5 >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "pr-metadata.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-view-usage-contract.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# Usage-error contract for pr-view.sh (R4, 2026-08-28).
-#
-# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
-# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
-# contract, value checks, and the no-provider-contact proof. Required: -i.
-#
-# Arms:
-#   1. --help and -h exit 0 and print usage.
-#   2. Unknown option exits 2 with the message on stderr.
-#   3. Missing required -i exits 2 (stderr).
-#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
-#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
-#      at credential resolution, nonzero and NOT 2) — no real token is
-#      ever read and no provider is contacted.
-#   6. No arm performs any provider request (PATH shims record every
-#      invocation; the probe log must stay empty).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-view-usage}"
-BIN_DIR="$WORK_DIR/bin"
-PROBE_LOG="$WORK_DIR/provider-probes.log"
-OUT_FILE="$WORK_DIR/out.log"
-ERR_FILE="$WORK_DIR/err.log"
-
-cleanup() {
-    rm -rf "$WORK_DIR"
-}
-trap cleanup EXIT
-
-mkdir -p "$BIN_DIR"
-: > "$PROBE_LOG"
-
-# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
-# API fallback that treats a successful curl as a closed PR, so exit-0
-# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
-for tool in gh tea curl; do
-    cat > "$BIN_DIR/$tool" <<STUB
-#!/usr/bin/env bash
-echo "$tool \$*" >> "$PROBE_LOG"
-exit 99
-STUB
-    chmod +x "$BIN_DIR/$tool"
-done
-
-run_wrapper() {
-    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-view.sh" "$@" )
-}
-
-# Hermetic variant: neutralizes every identity/credential source the wrapper
-# consults so parse-acceptance arms fail at credential resolution in ANY cwd
-# repo (see test-issue-comment-usage-contract.sh for the measured incident).
-run_wrapper_sandboxed() {
-    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
-    (
-        cd "$WORK_DIR"
-        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
-            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
-            "$SCRIPT_DIR/pr-view.sh" "$@"
-    )
-}
-
-fail() {
-    echo "FAIL: $*" >&2
-    echo "--- stderr ---" >&2
-    cat "$ERR_FILE" >&2
-    exit 1
-}
-
-expect_rc() { # expect_rc <want> <desc> <args...>
-    local want="$1" desc="$2" rc=0
-    shift 2
-    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
-}
-
-expect_stderr() { # expect_stderr <pattern> <desc>
-    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
-}
-
-# 1. Help exits 0 and prints usage.
-expect_rc 0 "--help exits 0" --help
-grep -q "Usage: pr-view.sh" "$OUT_FILE" || fail "--help did not print usage"
-expect_rc 0 "-h exits 0" -h
-
-# 2. Unknown option: rc 2, stderr.
-expect_rc 2 "unknown option exits 2" --bogus
-expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
-
-# 3. Missing required PR number: rc 2, stderr.
-expect_rc 2 "missing -n exits 2"
-expect_stderr "PR number is required" "missing -n message on stderr"
-
-
-# 4. Value-less flags: rc 2 with "requires a value" on stderr.
-for flag in -n -r --number --repo; do
-    expect_rc 2 "value-less $flag exits 2" "$flag"
-    expect_stderr "requires a value" "value-less $flag message on stderr"
-done
-
-# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
-# -b --help previously consumed --help as the body and performed the write).
-expect_rc 2 "option-like value rejected" -n --help
-expect_rc 2 "short flag value rejected" -n -h
-expect_stderr "requires a value" "short flag value message on stderr"
-expect_stderr "requires a value" "option-like value message on stderr"
-
-# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
-if [[ -s "$PROBE_LOG" ]]; then
-    echo "FAIL: a parser-failure arm contacted a provider:" >&2
-    cat "$PROBE_LOG" >&2
-    exit 1
-fi
-
-# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
-#    parsing; the run fails at credential resolution nonzero and NOT 2.
-for flag in -n; do
-    rc=0
-    run_wrapper_sandboxed -n 5 >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
-    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
-    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
-done
-
-# 6. Post-sandbox provider assertions are intentionally NOT applied here:
-# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
-# comment parses, then falls back to the API. Hermeticity for this
-# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
-# the arm above proves only parse acceptance and non-usage classification.
-# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
-
-echo "pr-view.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/tmux/agent-send.sh

@@ -35,9 +35,6 @@
 #
 # OPTIONS
 #   -L NAME         tmux socket name passed to `tmux -L NAME` on the target host
-#
-# Exit 4: local target session exists on multiple socket servers and no
-#         -L / MOSAIC_TMUX_SOCKET disambiguated it (B1 stale-twin guard).
 #   -s DST_SESSION  target tmux session (or session:window.pane)   [required]
 #   -H SSH_TARGET   ssh target (user@host) for a remote pane; omit for local
 #   -n DST_HOST     hostname to show in the preamble for the target.
@@ -66,10 +63,8 @@
 #     group 1 = src label   group 2 = dst host:session
 #     group 3 = class (absent => actionable)   group 4 = message body
 #
-# EXIT CODES  (passed through from send-message.sh, except 4)
+# EXIT CODES  (passed through from send-message.sh)
 #   0 delivered/queued · 1 target not found · 2 still draft · 3 usage error
-#   4 agent-send refusal: local target session exists on multiple socket
-#     servers and no -L / MOSAIC_TMUX_SOCKET disambiguated it (B1)
 set -uo pipefail
 
 SELF_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
@@ -159,61 +154,6 @@ FULL="${PREAMBLE} ${MSG}"
 B64=$(printf '%s' "$FULL" | base64 -w0)
 
 vflag=""; [ "$VERBOSE" = 1 ] && vflag="-v"
-
-# Exact session matching for the sender target (codex PR #1466): without
-# '=', tmux target syntax accepts an unambiguous PREFIX, so a delivery
-# aimed at session X can land in X-old. Compound targets (session:win.pane)
-# and already-exact ('=...') forms pass through untouched. Computed BEFORE
-# socket discovery so the discovery probes use the same target semantics
-# (probing '==name' for an already-exact input was a false-negative hit).
-DST_TARGET="$DST_SESSION"
-case "$DST_SESSION" in
-  =*) ;;
-  *:*)
-    # Compound target (session:win.pane): pin the SESSION component exact
-    # (=session:win.pane); unpinned, the session part still prefix-matches
-    # (codex PR #1466: 'agent:0.0' can resolve into 'agent-old').
-    DST_TARGET="=${DST_SESSION%%:*}:${DST_SESSION#*:}"
-    ;;
-  *) DST_TARGET="=$DST_SESSION" ;;
-esac
-
-# Socket default resolution (B1, 2026-08-29). Precedence: explicit -L >
-# launcher-exported MOSAIC_TMUX_SOCKET > unique socket hit > refusal on
-# ambiguity > tmux default socket. The ambiguity refusal fires ONLY when
-# no explicit or env choice exists and the session name lives on multiple
-# servers (measured 2026-08-28/29: tasking sends landed in a stale
-# default-socket twin; rc 0 reported honest delivery to the wrong pane).
-# Socket discovery scans tmux's own socket dir, ${TMUX_TMPDIR:-/tmp}/tmux-UID
-# (codex PR #1466: TMPDIR is not where tmux keeps -L sockets).
-# MOSAIC_TMUX_SOCKET is LOCAL-host state (launcher-exported): it must not
-# leak into remote sends, where -L would target a socket on the remote
-# host (codex PR #1466).
-if [ -z "$SOCKET_NAME" ] && [ -z "$SSH_TARGET" ] && [ -n "${MOSAIC_TMUX_SOCKET:-}" ]; then
-  SOCKET_NAME="$MOSAIC_TMUX_SOCKET"
-fi
-if [ -z "$SOCKET_NAME" ] && [ -z "$SSH_TARGET" ]; then
-  socket_dir="${TMUX_TMPDIR:-/tmp}/tmux-$(id -u)"
-  hits=""
-  for sf in "$socket_dir"/*; do
-    [ -S "$sf" ] || continue
-    sname="${sf##*/}"
-    # '=' forces exact session-name matching: tmux target syntax otherwise
-    # accepts an unambiguous PREFIX, so a session named X-old on a socket
-    # would count as a false hit for target X (codex PR #1466).
-    tmux -L "$sname" has-session -t "$DST_TARGET" 2>/dev/null && hits="$hits$sname"$'\n'
-  done
-  hit_count=$(printf '%s' "$hits" | grep -c . || true)
-  if [ "$hit_count" -gt 1 ]; then
-    echo "agent-send.sh: REFUSING - session '$DST_SESSION' exists on multiple sockets:" >&2
-    printf '  %s\n' $hits >&2
-    echo "  Pass -L <socket> explicitly (or export MOSAIC_TMUX_SOCKET to disambiguate)." >&2
-    exit 4
-  elif [ "$hit_count" -eq 1 ]; then
-    SOCKET_NAME="$(printf '%s' "$hits")"
-  fi
-fi
-
 socket_args=()
 if [ -n "$SOCKET_NAME" ]; then
   socket_args=(-L "$SOCKET_NAME")
@@ -221,9 +161,9 @@ fi
 
 if [ -z "$SSH_TARGET" ]; then
   # Local pane: call the canonical sender directly.
-  exec "$SENDER" "${socket_args[@]}" -t "$DST_TARGET" -b "$B64" -r "$RETRIES" $vflag
+  exec "$SENDER" "${socket_args[@]}" -t "$DST_SESSION" -b "$B64" -r "$RETRIES" $vflag
 else
   # Remote pane: ship the sender over ssh and run it local to the target.
   ssh -o ConnectTimeout=10 "$SSH_TARGET" \
-      "bash -s -- ${socket_args[*]@Q} -t '$DST_TARGET' -b '$B64' -r '$RETRIES' $vflag" < "$SENDER"
+      "bash -s -- ${socket_args[*]@Q} -t '$DST_SESSION' -b '$B64' -r '$RETRIES' $vflag" < "$SENDER"
 fi

packages/mosaic/framework/tools/tmux/test-send-message-socket.sh

@@ -8,15 +8,7 @@ SOCKET="mosaic-test-$RANDOM-$$"
 TARGET="target-$RANDOM"
 DEFAULT_TARGET="default-target-$RANDOM"
 TMPDIR=$(mktemp -d)
-ART_OUT=$(mktemp)
-AMB_OUT=$(mktemp)
-AMB_ERR=$(mktemp)
-A2_OUT=$(mktemp)
-A2_ERR=$(mktemp)
-UNIQ_OUT=$(mktemp)
-UNIQ_ERR=$(mktemp)
-TWIN="twin-$RANDOM-$$"
-trap 'tmux -L "$SOCKET" kill-server >/dev/null 2>&1 || true; tmux kill-session -t "$DEFAULT_TARGET" >/dev/null 2>&1 || true; tmux kill-session -t "$TWIN" >/dev/null 2>&1 || true; rm -rf "$TMPDIR" $ART_OUT $AMB_OUT $AMB_ERR $A2_OUT $A2_ERR $UNIQ_OUT $UNIQ_ERR' EXIT
+trap 'tmux -L "$SOCKET" kill-server >/dev/null 2>&1 || true; tmux kill-session -t "$DEFAULT_TARGET" >/dev/null 2>&1 || true; rm -rf "$TMPDIR"' EXIT
 
 fail() {
   echo "FAIL: $*" >&2
@@ -87,83 +79,4 @@ for i in $(seq 1 "$CONC_N"); do
   done
 done
 
-# B1 (2026-08-29): socket default resolution in agent-send.sh. Measured
-# defect: tasking sends without -L landed in a stale default-socket twin of
-# the target seat; rc 0 reported honest delivery to the wrong pane.
-
-# Arm A: session on MULTIPLE sockets, no -L -> refuse with rc 4 naming both.
-tmux -L "$SOCKET" new-session -d -s "$TWIN" -c "$TMPDIR" 'PS1="❯ " exec bash --noprofile --norc -i'
-tmux new-session -d -s "$TWIN" -c "$TMPDIR" 'PS1="❯ " exec bash --noprofile --norc -i'
-amb_rc=0
-env -u MOSAIC_TMUX_SOCKET "$AGENT_SEND" -s "$TWIN" -m "must refuse" >$AMB_OUT 2>$AMB_ERR || amb_rc=$?
-[ "$amb_rc" -eq 4 ] || fail "ambiguity refusal: rc=$amb_rc want 4 (stderr: $(cat $AMB_ERR))"
-grep -q "multiple sockets" $AMB_ERR || fail "ambiguity refusal message missing socket list"
-grep -qF "$SOCKET" $AMB_ERR || fail "ambiguity refusal message does not name the test socket"
-tmux kill-session -t "$TWIN" >/dev/null 2>&1 || true
-tmux -L "$SOCKET" kill-session -t "$TWIN" >/dev/null 2>&1 || true
-
-# Arm A2: with MOSAIC_TMUX_SOCKET exported, a twin session is NOT ambiguous:
-# the env var disambiguates by precedence (codex PR #1466 blocker).
-tmux -L "$SOCKET" new-session -d -s "$TWIN" -c "$TMPDIR" 'PS1="❯ " exec bash --noprofile --norc -i'
-tmux new-session -d -s "$TWIN" -c "$TMPDIR" 'PS1="❯ " exec bash --noprofile --norc -i'
-a2_rc=0
-MOSAIC_TMUX_SOCKET="$SOCKET" "$AGENT_SEND" -s "$TWIN" -m "env disambiguated" >$A2_OUT 2>$A2_ERR || a2_rc=$?
-[ "$a2_rc" -eq 0 ] || fail "env disambiguation: rc=$a2_rc (stderr: $(cat $A2_ERR))"
-sleep 0.2
-a2_pane="$(tmux -L "$SOCKET" capture-pane -t "=$TWIN:0.0" -p)" || fail "cannot capture twin (arm A2)"
-grep -qF "env disambiguated" <<<"$a2_pane" || fail "env disambiguation did not deliver on the named socket"
-a2_default="$(tmux capture-pane -t "=$TWIN:0.0" -p)" || true
-if grep -qF "env disambiguated" <<<"$a2_default"; then
-  fail "env disambiguation cross-delivered to the default-socket twin"
-fi
-tmux kill-session -t "$TWIN" >/dev/null 2>&1 || true
-tmux -L "$SOCKET" kill-session -t "$TWIN" >/dev/null 2>&1 || true
-
-# Arm B: session unique to ONE socket, no -L -> auto-resolve to that socket
-# and deliver there.
-# Arm A3: prefix matching must not produce false socket hits (codex PR
-# #1466): a session named TWIN-old must not count as a hit for target
-# TWIN (tmux target syntax prefix-matches without '=').
-PSEUDO="${TWIN}-old"
-tmux new-session -d -s "$PSEUDO" -c "$TMPDIR" 'PS1="❯ " exec bash --noprofile --norc -i'
-A3_ERR=$(mktemp)
-a3_rc=0
-env -u MOSAIC_TMUX_SOCKET "$AGENT_SEND" -s "$TWIN" -m "prefix trap" >/dev/null 2>"$A3_ERR" || a3_rc=$?
-# TWIN exists nowhere (both twins killed after arm A2); with '=' the
-# PSEUDO session is not a hit, so the sender must fail target-not-found
-# (rc 1) instead of delivering into the prefix-named session.
-[ "$a3_rc" -eq 1 ] || fail "prefix false-hit: rc=$a3_rc want 1 (stderr: $(cat "$A3_ERR"))"
-a3_pane="$(tmux capture-pane -t "=$PSEUDO:0.0" -p 2>/dev/null)" || a3_pane=""
-if printf '%s' "$a3_pane" | grep -F "prefix trap" >/dev/null; then
-  fail "delivery landed in the prefix-named session (false socket hit)"
-fi
-tmux kill-session -t "$PSEUDO" >/dev/null 2>&1 || true
-rm -f "$A3_ERR"
-
-# Arm A4: compound targets pin the SESSION component exact (codex PR
-# #1466): 'TWIN:0.0' must not resolve into the prefix-named session.
-PSEUDO2="${TWIN}-old"
-tmux new-session -d -s "$PSEUDO2" -c "$TMPDIR" 'PS1="❯ " exec bash --noprofile --norc -i'
-A4_ERR=$(mktemp)
-a4_rc=0
-env -u MOSAIC_TMUX_SOCKET "$AGENT_SEND" -s "$TWIN:0.0" -m "compound trap" >/dev/null 2>"$A4_ERR" || a4_rc=$?
-[ "$a4_rc" -eq 1 ] || fail "compound prefix false-hit: rc=$a4_rc want 1 (stderr: $(cat "$A4_ERR"))"
-a4_pane="$(tmux capture-pane -t "=$PSEUDO2:0.0" -p 2>/dev/null)" || a4_pane=""
-if printf '%s' "$a4_pane" | grep -F "compound trap" >/dev/null; then
-  fail "compound delivery landed in the prefix-named session"
-fi
-tmux kill-session -t "$PSEUDO2" >/dev/null 2>&1 || true
-rm -f "$A4_ERR"
-
-uniq_rc=0
-env -u MOSAIC_TMUX_SOCKET "$AGENT_SEND" -s "$TARGET" -m "autoresolved hello" >$UNIQ_OUT 2>$UNIQ_ERR || uniq_rc=$?
-[ "$uniq_rc" -eq 0 ] || fail "unique auto-resolution: rc=$uniq_rc (stderr: $(cat $UNIQ_ERR))"
-sleep 0.2
-auto_pane="$(capture_named)" || fail "could not capture named socket pane (arm B)"
-grep -qF "autoresolved hello" <<<"$auto_pane" || fail "auto-resolution did not deliver to the named-socket pane"
-default_pane2="$(capture_default)" || fail "could not capture default socket pane (arm B)"
-if grep -qF "autoresolved hello" <<<"$default_pane2"; then
-  fail "auto-resolution cross-delivered to the default socket pane"
-fi
-
 echo "ok - named tmux socket send tools"

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,154 +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', () => {
-  // B2 (2026-08-29): when --socket is omitted, the CLI forwards NO -L and
-  // agent-send.sh's own resolution governs (explicit -L > MOSAIC_TMUX_SOCKET
-  // > unique hit > ambiguity refusal). Forwarding a guessed default here
-  // would defeat that resolution and reintroduce the stale-twin defect.
-  it('omits -L entirely when --socket is not given (tool-owned resolution)', () => {
-    const args = tmuxSendArgs('orch-01', 'hello', {});
-    expect(args).toEqual(['-s', 'orch-01', '-m', 'hello']);
-    expect(args).not.toContain('-L');
-    expect(args.join(' ')).not.toContain('-L');
-  });
-
-  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,138 +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). OMIT it to let agent-send.sh resolve the socket (explicit -L > MOSAIC_TMUX_SOCKET > unique hit; ambiguity refuses with its exit 4).',
-    )
-    .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/fleet.spec.ts

@@ -106,7 +106,6 @@ describe('registerFleetCommand', () => {
       'init',
       'install',
       'install-systemd',
-      'logins',
       'migrate-v1',
       'persona',
       'plan',

packages/mosaic/src/commands/fleet.ts

@@ -17,7 +17,7 @@ import { homedir, hostname, userInfo } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fleetAgentEnvDir } from '../fleet/brain-home.js';
 import { fileURLToPath } from 'node:url';
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
@@ -1606,24 +1606,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
     .option('--mosaic-home <path>', 'Mosaic home directory', paths.mosaicHome)
     .option('--roster <path>', 'Fleet roster path');
 
-  // fleet logins (P4 gap closure, 2026-08-29): project per-seat git tokens
-  // from the brain into usable credentials. The implementation is the
-  // framework fleet tool; args pass through verbatim (--apply --seat X).
-  cmd
-    .command('logins')
-    .description('Per-seat git credentials: seat-logins.sh pass-through (--apply --seat <name>)')
-    .allowUnknownOption(true)
-    .allowExcessArguments(true)
-    .action((...rest: unknown[]) => {
-      const cmdObj = rest[rest.length - 1] as { args: string[] };
-      const script = `${frameworkRoot}/tools/fleet/seat-logins.sh`;
-      const result = spawnSync('bash', [script, ...cmdObj.args], {
-        stdio: 'inherit',
-        env: process.env,
-      });
-      process.exit(result.status ?? 125);
-    });
-
   cmd
     .command('init')
     .description('Initialize a local fleet roster')

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).',
-  );
-}