db: agent enrollment schema (M4-4a, migration 0021) (#1482)

Co-authored-by: marcie <[email protected]>

.gitignore

@@ -23,3 +23,7 @@ infra/step-ca/dev-password
 # traversal error: ... .timestamp-*.mjs: No such file or directory" when the
 # file vanished mid-scan. Ignoring them removes the race.
 *.timestamp-*.mjs
+
+# Playwright run artifacts (#1445, P6 E2E gate)
+apps/web/test-results/
+apps/web/playwright-report/

.woodpecker/ci.yml

@@ -254,6 +254,23 @@ steps:
     depends_on:
       - typecheck
 
+  # Canonical verify:release stage `build` (#1445, P6): every PR proves the
+  # full workspace build — including the SPA `vite build` — before merge,
+  # instead of leaving build breakage to surface post-merge in publish.yml's
+  # verify step. Same canonical command the publish pipeline's build step runs.
+  build:
+    image: *node_image
+    commands:
+      - *enable_pnpm
+      - pnpm build
+    depends_on:
+      # after test, not typecheck: turbo gives `test` a ^build dependency, so
+      # running this step concurrently with test would put two independent
+      # turbo builds on the same shared-workspace dist/ and turbo cache with
+      # no cross-process locking — the same serialization invariant
+      # publish.yml documents for #1411.
+      - test
+
 services:
   ci-postgres:
     image: pgvector/pgvector:pg17

.woodpecker/publish.yml

@@ -407,6 +407,96 @@ steps:
       - build
       - verify
 
+  # #1445 (P6): headless Playwright E2E gate on every trunk merge. Boots the
+  # real gateway on the embedded PGlite path (no DATABASE_URL, no services)
+  # serving the built SPA bundle via WEB_DIST_DIR — the exact serving path the
+  # gateway image ships (docker/gateway.Dockerfile sets WEB_DIST_DIR to the
+  # baked bundle), which keeps #1407's parity guarantee: the image build steps
+  # below depend on this gate, so a bundle that fails E2E never publishes.
+  #
+  # Image pinned to the @playwright/test version in pnpm-lock.yaml so the
+  # image's bundled browsers match the workspace driver exactly (bump the two
+  # together). The step installs no workspace packages (corepack does fetch
+  # the pinned pnpm itself): it reuses the workspace node_modules
+  # from `install` and the dist outputs from `build` — the gateway's runtime
+  # dependency path is pure JS/WASM (PGlite is WASM, postgres-js is pure JS),
+  # so the alpine-installed modules run unchanged under this glibc image.
+  # depends_on publish-next-npm per the #1411 serialization invariant: this
+  # step reads the workspace and must never run inside the manifest-transform
+  # window.
+  e2e:
+    image: mcr.microsoft.com/playwright:v1.58.2-noble
+    environment:
+      GATEWAY_PORT: '14242'
+      PLAYWRIGHT_BASE_URL: http://localhost:14242
+      # The database is seeded by Playwright's globalSetup in this step, so
+      # login failures are real failures: without this flag the suite's
+      # skip-when-login-fails guards (a live-environment affordance) could
+      # skip every authenticated spec and go green while proving nothing.
+      E2E_REQUIRE_SEEDED_AUTH: '1'
+    commands:
+      - corepack enable
+      - |
+        # Throwaway signing secret for this step's ephemeral embedded database
+        # (the gateway refuses to boot without one). Generated per run so no
+        # usable literal lives in the tree.
+        export BETTER_AUTH_SECRET="$(head -c 32 /dev/urandom | base64)"
+        export WEB_DIST_DIR="$(pwd)/apps/web/dist"
+        if [ ! -f "$WEB_DIST_DIR/index.html" ]; then
+          echo "[e2e] FATAL: $WEB_DIST_DIR/index.html missing — did the build step run?" >&2
+          exit 1
+        fi
+        # Boot the gateway from the built dist, cwd- AND HOME-isolated: the
+        # local-tier PGlite database lives under $HOME/.config/mosaic/gateway/
+        # (database.module.ts), not under cwd, so HOME must point at the
+        # throwaway dir too or the run would share a database with anything
+        # else in the container's home.
+        GATEWAY_RUN_DIR="$(mktemp -d /tmp/e2e-gateway.XXXXXX)"
+        (cd "$GATEWAY_RUN_DIR" && export HOME="$GATEWAY_RUN_DIR" && exec node "$OLDPWD/apps/gateway/dist/main.js") > /tmp/gateway.log 2>&1 &
+        GATEWAY_PID=$!
+        ready=0
+        for i in $(seq 1 90); do
+          if node -e "fetch('http://localhost:' + process.env.GATEWAY_PORT + '/health', { signal: AbortSignal.timeout(2000) }).then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"; then
+            ready=1
+            break
+          fi
+          if ! kill -0 "$GATEWAY_PID" 2>/dev/null; then
+            echo "[e2e] FATAL: gateway process exited during startup" >&2
+            cat /tmp/gateway.log >&2
+            exit 1
+          fi
+          echo "[e2e] waiting for gateway ($i/90)..."
+          sleep 1
+        done
+        if [ "$ready" -ne 1 ]; then
+          echo "[e2e] FATAL: gateway did not become ready in 90s" >&2
+          cat /tmp/gateway.log >&2
+          exit 1
+        fi
+        echo "[e2e] gateway ready; running Playwright suite"
+        set +e
+        pnpm --filter @mosaicstack/web exec playwright test
+        E2E_EXIT=$?
+        set -e
+        kill "$GATEWAY_PID" 2>/dev/null || true
+        if [ "$E2E_EXIT" -ne 0 ]; then
+          echo "[e2e] FATAL: Playwright suite failed (exit $E2E_EXIT); gateway log follows" >&2
+          tail -100 /tmp/gateway.log >&2
+          echo "[e2e] browser-side traces/screenshots are under apps/web/test-results/ in the step workspace (not persisted past the pod)" >&2
+        fi
+        exit "$E2E_EXIT"
+    # Same filter as the image builds it gates: a merge that publishes no
+    # image (docs-only on main) pays no browser suite, and a skipped e2e does
+    # not block anything (skipped-dependency semantics, same as
+    # publish-next-npm on tag events).
+    when: *image_build_when
+    depends_on:
+      - build
+      - verify
+      # #1411: never read the workspace inside publish-next-npm's
+      # manifest-transform window.
+      - publish-next-npm
+
   # TODO: Uncomment when ready to publish to npmjs.org
   # publish-npmjs:
   #   image: *node_image
@@ -466,6 +556,8 @@ steps:
       # ERR_PNPM_OUTDATED_LOCKFILE despite a clean restore. This edge is the
       # serialization invariant; add it to every new workspace consumer.
       - publish-next-npm
+      # #1445 (P6): a bundle that fails the E2E gate never publishes an image.
+      - e2e
 
   build-appservice:
     image: gcr.io/kaniko-project/executor:debug
@@ -510,3 +602,5 @@ steps:
       # ERR_PNPM_OUTDATED_LOCKFILE despite a clean restore. This edge is the
       # serialization invariant; add it to every new workspace consumer.
       - publish-next-npm
+      # #1445 (P6): a bundle that fails the E2E gate never publishes an image.
+      - e2e

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

@@ -0,0 +1,133 @@
+import { RequestMethod, type Type } from '@nestjs/common';
+import { describe, expect, it } from 'vitest';
+import { AppModule } from '../app.module.js';
+import { HierarchyModule } from '../hierarchy/hierarchy.module.js';
+
+/**
+ * Hierarchy route inventory (contract 1 §6.3).
+ *
+ * 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.
+ */
+
+interface RouteEntry {
+  method: string;
+  path: string;
+  controller: string;
+}
+
+/** Module-metadata entry: a module class or a DynamicModule-shaped object. */
+type ModuleEntry =
+  | Type<unknown>
+  | { module: Type<unknown>; imports?: unknown[]; controllers?: Type<unknown>[] };
+
+function collectControllers(root: ModuleEntry): Type<unknown>[] {
+  const visited = new Set<unknown>();
+  const controllers: Type<unknown>[] = [];
+  const walk = (entry: ModuleEntry | undefined | null): void => {
+    if (!entry || visited.has(entry)) return;
+    visited.add(entry);
+    const moduleClass = typeof entry === 'function' ? entry : entry.module;
+    // Entries with no resolvable class (forwardRef wrappers, async dynamic
+    // modules) carry no decorator metadata to read here.
+    if (typeof moduleClass !== 'function') return;
+    if (visited.has(moduleClass) && typeof entry !== 'function') return;
+    visited.add(moduleClass);
+    // 'controllers' / 'imports' are the metadata keys the @Module decorator writes.
+    const declared = (Reflect.getMetadata('controllers', moduleClass) ?? []) as Type<unknown>[];
+    controllers.push(...declared);
+    if (typeof entry !== 'function' && entry.controllers) controllers.push(...entry.controllers);
+    const imports = [
+      ...((Reflect.getMetadata('imports', moduleClass) ?? []) as ModuleEntry[]),
+      ...(typeof entry !== 'function' ? ((entry.imports ?? []) as ModuleEntry[]) : []),
+    ];
+    for (const imported of imports) walk(imported);
+  };
+  walk(root);
+  return controllers;
+}
+
+function routesOf(controller: Type<unknown>): RouteEntry[] {
+  // 'path' on the class is the @Controller prefix; 'path'/'method' on a
+  // handler are written by the @Get/@Post/... route decorators.
+  const base = (Reflect.getMetadata('path', controller) ?? '') as string | string[];
+  const bases = Array.isArray(base) ? base : [base];
+  const routes: RouteEntry[] = [];
+  const prototype = controller.prototype as Record<string, unknown>;
+  for (const name of Object.getOwnPropertyNames(prototype)) {
+    if (name === 'constructor') continue;
+    const handler = Object.getOwnPropertyDescriptor(prototype, name)?.value;
+    if (typeof handler !== 'function') continue;
+    const method = Reflect.getMetadata('method', handler) as number | undefined;
+    if (method === undefined) continue;
+    const sub = (Reflect.getMetadata('path', handler) ?? '/') as string;
+    for (const prefix of bases) {
+      const path = `/${prefix}/${sub}`.replace(/\/+/g, '/').replace(/(.)\/$/, '$1');
+      routes.push({
+        method: RequestMethod[method] ?? String(method),
+        path,
+        controller: controller.name,
+      });
+    }
+  }
+  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)', () => {
+  const inventory = collectControllers(AppModule).flatMap(routesOf);
+
+  it('control: the enumeration sees the known route surface', () => {
+    const paths = inventory.map((r) => `${r.method} ${r.path}`);
+    expect(paths).toContain('GET /health');
+    expect(paths).toContain('POST /api/workspaces');
+    expect(paths).toContain('GET /api/teams');
+    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('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());
+  });
+});

apps/gateway/src/app.module.ts

@@ -24,6 +24,7 @@ import { GCModule } from './gc/gc.module.js';
 import { HarnessModule } from './harness/harness.module.js';
 import { ReloadModule } from './reload/reload.module.js';
 import { WorkspaceModule } from './workspace/workspace.module.js';
+import { HierarchyModule } from './hierarchy/hierarchy.module.js';
 import { QueueModule } from './queue/queue.module.js';
 import { FederationModule } from './federation/federation.module.js';
 import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
@@ -65,6 +66,7 @@ const federationEnabled = loadConfig(resolveGatewayConfigPath()).tier === 'feder
     QueueModule,
     ReloadModule,
     WorkspaceModule,
+    HierarchyModule,
     ...(federationEnabled ? [FederationModule] : []),
   ],
   controllers: [HealthController],

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

@@ -61,6 +61,33 @@ 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,8 +154,15 @@ 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 (role === 'admin') return true;
+    if (scope === 'admin') return role === 'admin';
     return role === 'member' && (scope === 'core' || scope === 'agent');
   }
 

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

@@ -0,0 +1,247 @@
+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,
+  hierarchyOutbox,
+  platformProjects,
+  runPgliteMigrations,
+  type DbHandle,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+import {
+  HierarchyAuditIdempotencyConflictError,
+  HierarchyAuditRepository,
+  HierarchyNodeNotFoundError,
+  type AppendHierarchyEventInput,
+} from './hierarchy-audit.repository.js';
+
+/**
+ * Repository-level §6.4 witnesses for the hierarchy audit machinery
+ * (contract 1 §5.2, REQ-AUD-001): same-transaction atomicity of state +
+ * event + outbox, rollback leaving no residue, idempotent replay, snapshot
+ * parent chains, events surviving target deletion, per-target ordering, and
+ * the outbox claim/complete/release CAS. The schema-level constraints are
+ * witnessed in packages/db/src/hierarchy-audit.witness.test.ts.
+ */
+describe('hierarchy audit repository integration', (): void => {
+  let dataDir: string;
+  let handle: DbHandle;
+  let moduleRef: TestingModule;
+  let repo: HierarchyAuditRepository;
+
+  const input = (
+    overrides: Partial<AppendHierarchyEventInput> = {},
+  ): AppendHierarchyEventInput => ({
+    actorId: 'user-actor',
+    verb: 'create',
+    targetKind: 'company',
+    targetId: randomUUID(),
+    targetSnapshot: { id: 'x', slug: 'x', name: 'x', parentChain: [] },
+    correlationId: 'corr-1',
+    idempotencyKey: `key-${randomUUID()}`,
+    ...overrides,
+  });
+
+  beforeAll(async (): Promise<void> => {
+    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-gateway-hierarchy-audit-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    moduleRef = await Test.createTestingModule({
+      providers: [HierarchyAuditRepository, { provide: DB, useValue: handle.db }],
+    }).compile();
+    repo = moduleRef.get(HierarchyAuditRepository);
+  });
+
+  afterAll(async (): Promise<void> => {
+    await moduleRef.close();
+    await handle.close();
+    await rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('commits state, event, and outbox record atomically in one transaction', async () => {
+    const companyId = randomUUID();
+    const key = `key-${randomUUID()}`;
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Atomic Co', slug: 'atomic-co' });
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      const result = await repo.append(tx, {
+        ...input({ targetId: companyId, idempotencyKey: key }),
+        targetSnapshot: { ...snapshot },
+      });
+      expect(result.replayed).toBe(false);
+      expect(result.event.idempotencyKey).toBe(key);
+    });
+    const events = await handle.db
+      .select()
+      .from(hierarchyAuditEvents)
+      .where(eq(hierarchyAuditEvents.idempotencyKey, key));
+    expect(events).toHaveLength(1);
+    const outbox = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.eventId, events[0]!.id));
+    expect(outbox).toHaveLength(1);
+    expect(outbox[0]).toMatchObject({
+      status: 'pending',
+      idempotencyKey: key,
+      correlationId: 'corr-1',
+    });
+  });
+
+  it('a rolled-back transaction leaves no state, no event, and no outbox record', async () => {
+    const companyId = randomUUID();
+    const key = `key-${randomUUID()}`;
+    await expect(
+      handle.db.transaction(async (tx) => {
+        await tx.insert(companies).values({ id: companyId, name: 'Doomed Co', slug: 'doomed-co' });
+        await repo.append(tx, input({ targetId: companyId, idempotencyKey: key }));
+        throw new Error('deliberate rollback');
+      }),
+    ).rejects.toThrow('deliberate rollback');
+    const [companyRows, eventRows, outboxRows] = await Promise.all([
+      handle.db.select().from(companies).where(eq(companies.id, companyId)),
+      handle.db
+        .select()
+        .from(hierarchyAuditEvents)
+        .where(eq(hierarchyAuditEvents.idempotencyKey, key)),
+      handle.db.select().from(hierarchyOutbox).where(eq(hierarchyOutbox.idempotencyKey, key)),
+    ]);
+    expect(companyRows).toHaveLength(0);
+    expect(eventRows).toHaveLength(0);
+    expect(outboxRows).toHaveLength(0);
+  });
+
+  it('replays a duplicate idempotency key without inserting a second event or outbox record', async () => {
+    const first = input();
+    const original = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    const replay = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(original.replayed).toBe(false);
+    expect(replay.replayed).toBe(true);
+    expect(replay.event.id).toBe(original.event.id);
+    const outbox = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.eventId, original.event.id));
+    expect(outbox).toHaveLength(1);
+  });
+
+  it('throws on a duplicate idempotency key carrying different event content', async () => {
+    const first = input();
+    await handle.db.transaction(async (tx) => repo.append(tx, first));
+    await expect(
+      handle.db.transaction(async (tx) =>
+        repo.append(tx, { ...first, verb: 'rename', targetId: randomUUID() }),
+      ),
+    ).rejects.toThrow(HierarchyAuditIdempotencyConflictError);
+  });
+
+  it('throws on a duplicate idempotency key whose transfer destination differs', async () => {
+    const from = { kind: 'company' as const, id: randomUUID(), slug: 'src-co' };
+    const to = { kind: 'company' as const, id: randomUUID(), slug: 'dst-co' };
+    const first = input({
+      verb: 'transfer',
+      targetKind: 'estate',
+      transferFrom: from,
+      transferTo: to,
+    });
+    const original = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(original.replayed).toBe(false);
+    // Identical retry replays; a retry re-routed to a different destination must conflict.
+    const replay = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(replay.replayed).toBe(true);
+    await expect(
+      handle.db.transaction(async (tx) =>
+        repo.append(tx, { ...first, transferTo: { ...to, id: randomUUID() } }),
+      ),
+    ).rejects.toThrow(HierarchyAuditIdempotencyConflictError);
+  });
+
+  it('builds root-first parent chains and rejects unknown nodes', async () => {
+    const companyId = randomUUID();
+    const estateId = randomUUID();
+    const projectId = randomUUID();
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Chain Co', slug: 'chain-co' });
+      await tx
+        .insert(estates)
+        .values({ id: estateId, name: 'Chain Estate', slug: 'chain-estate', companyId });
+      await tx
+        .insert(platformProjects)
+        .values({ id: projectId, name: 'Chain Project', slug: 'chain-project', estateId });
+    });
+    const snapshot = await repo.snapshot(handle.db, 'platform_project', projectId);
+    expect(snapshot).toMatchObject({ id: projectId, slug: 'chain-project', name: 'Chain Project' });
+    expect(snapshot.parentChain).toEqual([
+      { kind: 'company', id: companyId, slug: 'chain-co' },
+      { kind: 'estate', id: estateId, slug: 'chain-estate' },
+    ]);
+    await expect(repo.snapshot(handle.db, 'estate', randomUUID())).rejects.toThrow(
+      HierarchyNodeNotFoundError,
+    );
+  });
+
+  it('keeps events readable, in per-target seq order, after the target row is deleted', async () => {
+    const companyId = randomUUID();
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Mortal Co', slug: 'mortal-co' });
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      await repo.append(tx, input({ targetId: companyId, targetSnapshot: { ...snapshot } }));
+    });
+    await handle.db.transaction(async (tx) => {
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      await repo.append(tx, {
+        ...input({ verb: 'delete', targetId: companyId }),
+        targetSnapshot: { ...snapshot },
+      });
+      await tx.delete(companies).where(eq(companies.id, companyId));
+    });
+    const events = await repo.eventsForTarget(companyId);
+    expect(events.map((e) => e.verb)).toEqual(['create', 'delete']);
+    expect(events[1]!.seq).toBeGreaterThan(events[0]!.seq);
+    expect((events[1]!.targetSnapshot as { id: string }).id).toBe(companyId);
+  });
+
+  it('claims the oldest pending outbox record exactly once, completes and releases by CAS', async () => {
+    // Drain records left pending by earlier cases so ordering is deterministic.
+    for (;;) {
+      const drained = await repo.claimPendingOutbox();
+      if (!drained) break;
+      await repo.completeOutbox(drained.id);
+    }
+    const older = await handle.db.transaction(async (tx) => repo.append(tx, input()));
+    const newer = await handle.db.transaction(async (tx) => repo.append(tx, input()));
+
+    const claimed = await repo.claimPendingOutbox();
+    expect(claimed).not.toBeNull();
+    expect(claimed!.eventId).toBe(older.event.id);
+    expect(claimed!.status).toBe('processing');
+
+    // Delivery fails: release returns it to pending and it is claimable again.
+    await repo.releaseOutbox(claimed!.id);
+    const reclaimed = await repo.claimPendingOutbox();
+    expect(reclaimed!.id).toBe(claimed!.id);
+
+    await repo.completeOutbox(reclaimed!.id);
+    const done = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.id, reclaimed!.id));
+    expect(done[0]!.status).toBe('delivered');
+    expect(done[0]!.deliveredAt).not.toBeNull();
+    // completeOutbox is CAS-guarded on 'processing': completing again is a no-op.
+    await repo.completeOutbox(reclaimed!.id);
+
+    const second = await repo.claimPendingOutbox();
+    expect(second!.eventId).toBe(newer.event.id);
+    await repo.completeOutbox(second!.id);
+    expect(await repo.claimPendingOutbox()).toBeNull();
+  });
+});

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

@@ -0,0 +1,274 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  asc,
+  companies,
+  eq,
+  estates,
+  hierarchyAuditEvents,
+  hierarchyOutbox,
+  platformProjects,
+  type Db,
+  type HIERARCHY_AUDIT_TARGET_KINDS,
+  type HIERARCHY_AUDIT_VERBS,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+
+/**
+ * Hierarchy audit event + outbox machinery (contract 1 §5.2).
+ *
+ * Every hierarchy mutation writes its semantic audit event AND the event's
+ * outbox record on the caller's transaction, so state, event, and outbox
+ * commit or roll back together. Events reference their target by an
+ * immutable snapshot (id, slug, parent chain at event time), never by a
+ * foreign key into the class tables — append-only events survive the
+ * deletion of their target. This module exposes no update or delete path
+ * for events: append-only is a property of the code surface, witnessed by
+ * the integration tests.
+ *
+ * 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.
+ */
+
+export type HierarchyAuditVerb = (typeof HIERARCHY_AUDIT_VERBS)[number];
+export type HierarchyTargetKind = (typeof HIERARCHY_AUDIT_TARGET_KINDS)[number];
+export type HierarchyNodeKind = Exclude<HierarchyTargetKind, 'grant'>;
+
+export interface ParentChainEntry {
+  readonly kind: HierarchyNodeKind;
+  readonly id: string;
+  readonly slug: string;
+}
+
+/** Immutable node snapshot at event time; parentChain is root-first. */
+export interface HierarchyNodeSnapshot {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  readonly parentChain: readonly ParentChainEntry[];
+}
+
+export interface AppendHierarchyEventInput {
+  readonly actorId: string;
+  readonly verb: HierarchyAuditVerb;
+  readonly targetKind: HierarchyTargetKind;
+  readonly targetId: string;
+  /** Node events: HierarchyNodeSnapshot. Grant events: subject/target/role snapshot (contract 2 §4.4). */
+  readonly targetSnapshot: Record<string, unknown>;
+  /** Present exactly on transfers (CHECK-enforced): source/destination parent { kind, id, slug }. */
+  readonly transferFrom?: ParentChainEntry;
+  readonly transferTo?: ParentChainEntry;
+  readonly correlationId: string;
+  /** Prior event in the causal chain (e.g. the delete event causing cascaded grant_revoke events). */
+  readonly causationId?: string;
+  readonly idempotencyKey: string;
+}
+
+export type HierarchyAuditEventRow = typeof hierarchyAuditEvents.$inferSelect;
+export type HierarchyOutboxRow = typeof hierarchyOutbox.$inferSelect;
+
+export interface AppendHierarchyEventResult {
+  readonly event: HierarchyAuditEventRow;
+  /** True when the idempotency key had already committed an identical event (REQ-AUD-001 duplicate suppression). */
+  readonly replayed: boolean;
+}
+
+type Tx = Pick<Db, 'insert' | 'select'>;
+
+export class HierarchyAuditIdempotencyConflictError extends Error {
+  constructor(idempotencyKey: string) {
+    super(
+      `hierarchy audit idempotency key ${idempotencyKey} already exists with different event content`,
+    );
+    this.name = 'HierarchyAuditIdempotencyConflictError';
+  }
+}
+
+export class HierarchyNodeNotFoundError extends Error {
+  constructor(kind: HierarchyNodeKind, id: string) {
+    super(`hierarchy node not found: ${kind} ${id}`);
+    this.name = 'HierarchyNodeNotFoundError';
+  }
+}
+
+/**
+ * Append one audit event and its outbox record on the caller's transaction.
+ * A duplicate idempotency key with identical semantic content returns the
+ * prior event (replayed: true) without inserting anything; a duplicate key
+ * with different content throws.
+ */
+export async function appendHierarchyEvent(
+  tx: Tx,
+  input: AppendHierarchyEventInput,
+): Promise<AppendHierarchyEventResult> {
+  const inserted = await tx
+    .insert(hierarchyAuditEvents)
+    .values({
+      actorId: input.actorId,
+      verb: input.verb,
+      targetKind: input.targetKind,
+      targetId: input.targetId,
+      targetSnapshot: input.targetSnapshot,
+      transferFrom: input.transferFrom ?? null,
+      transferTo: input.transferTo ?? null,
+      correlationId: input.correlationId,
+      causationId: input.causationId ?? null,
+      idempotencyKey: input.idempotencyKey,
+    })
+    .onConflictDoNothing()
+    .returning();
+  const event = inserted[0];
+  if (event) {
+    await tx.insert(hierarchyOutbox).values({
+      eventId: event.id,
+      idempotencyKey: input.idempotencyKey,
+      correlationId: input.correlationId,
+    });
+    return { event, replayed: false };
+  }
+
+  const prior = await tx
+    .select()
+    .from(hierarchyAuditEvents)
+    .where(eq(hierarchyAuditEvents.idempotencyKey, input.idempotencyKey))
+    .limit(1);
+  const existing = prior[0];
+  if (!existing || !sameEvent(existing, input)) {
+    throw new HierarchyAuditIdempotencyConflictError(input.idempotencyKey);
+  }
+  // Event and outbox committed atomically the first time, so the outbox
+  // record already exists; a replay inserts nothing.
+  return { event: existing, replayed: true };
+}
+
+/** Key-order-independent serialization: jsonb does not preserve key order. */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const body = Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+      .join(',');
+    return `{${body}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sameEvent(row: HierarchyAuditEventRow, input: AppendHierarchyEventInput): boolean {
+  return (
+    row.actorId === input.actorId &&
+    row.verb === input.verb &&
+    row.targetKind === input.targetKind &&
+    row.targetId === input.targetId &&
+    row.correlationId === input.correlationId &&
+    (row.causationId ?? null) === (input.causationId ?? null) &&
+    canonicalJson(row.targetSnapshot) === canonicalJson(input.targetSnapshot) &&
+    // Transfer source/destination are semantic content (§5.2): a retry with a
+    // different destination must conflict, never silently replay.
+    canonicalJson(row.transferFrom ?? null) === canonicalJson(input.transferFrom ?? null) &&
+    canonicalJson(row.transferTo ?? null) === canonicalJson(input.transferTo ?? null)
+  );
+}
+
+/**
+ * Build the immutable snapshot for a node: its row plus the parent chain up
+ * to the company root, root-first, read on the caller's transaction so the
+ * snapshot is consistent with the mutation it audits.
+ */
+export async function buildNodeSnapshot(
+  tx: Tx,
+  kind: HierarchyNodeKind,
+  id: string,
+): Promise<HierarchyNodeSnapshot> {
+  if (kind === 'company') {
+    const rows = await tx.select().from(companies).where(eq(companies.id, id)).limit(1);
+    const row = rows[0];
+    if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+    return { id: row.id, slug: row.slug, name: row.name, parentChain: [] };
+  }
+  if (kind === 'estate') {
+    const rows = await tx.select().from(estates).where(eq(estates.id, id)).limit(1);
+    const row = rows[0];
+    if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+    const parent = await buildNodeSnapshot(tx, 'company', row.companyId);
+    return {
+      id: row.id,
+      slug: row.slug,
+      name: row.name,
+      parentChain: [...parent.parentChain, { kind: 'company', id: parent.id, slug: parent.slug }],
+    };
+  }
+  const rows = await tx.select().from(platformProjects).where(eq(platformProjects.id, id)).limit(1);
+  const row = rows[0];
+  if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+  const parent = await buildNodeSnapshot(tx, 'estate', row.estateId);
+  return {
+    id: row.id,
+    slug: row.slug,
+    name: row.name,
+    parentChain: [...parent.parentChain, { kind: 'estate', id: parent.id, slug: parent.slug }],
+  };
+}
+
+@Injectable()
+export class HierarchyAuditRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  /** Compose an event+outbox append into a caller-owned transaction. */
+  append(tx: Tx, input: AppendHierarchyEventInput): Promise<AppendHierarchyEventResult> {
+    return appendHierarchyEvent(tx, input);
+  }
+
+  snapshot(tx: Tx, kind: HierarchyNodeKind, id: string): Promise<HierarchyNodeSnapshot> {
+    return buildNodeSnapshot(tx, kind, id);
+  }
+
+  /** Per-target ordered event history (REQ-AUD-001 per-target ordering; read-only). */
+  async eventsForTarget(targetId: string): Promise<HierarchyAuditEventRow[]> {
+    return this.db
+      .select()
+      .from(hierarchyAuditEvents)
+      .where(eq(hierarchyAuditEvents.targetId, targetId))
+      .orderBy(asc(hierarchyAuditEvents.seq));
+  }
+
+  /**
+   * Claim the oldest pending outbox record (claim-by-CAS: the UPDATE is
+   * guarded on status so a lost race returns null and the caller retries).
+   */
+  async claimPendingOutbox(): Promise<HierarchyOutboxRow | null> {
+    const candidates = await this.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.status, 'pending'))
+      .orderBy(asc(hierarchyOutbox.createdAt))
+      .limit(1);
+    const candidate = candidates[0];
+    if (!candidate) return null;
+    const claimed = await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'processing', updatedAt: new Date() })
+      .where(and(eq(hierarchyOutbox.id, candidate.id), eq(hierarchyOutbox.status, 'pending')))
+      .returning();
+    return claimed[0] ?? null;
+  }
+
+  async completeOutbox(id: string): Promise<void> {
+    const now = new Date();
+    await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'delivered', deliveredAt: now, updatedAt: now })
+      .where(and(eq(hierarchyOutbox.id, id), eq(hierarchyOutbox.status, 'processing')));
+  }
+
+  /** Return a claimed record to pending (delivery failed; it stays replayable). */
+  async releaseOutbox(id: string): Promise<void> {
+    await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(and(eq(hierarchyOutbox.id, id), eq(hierarchyOutbox.status, 'processing')));
+  }
+}

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

@@ -0,0 +1,965 @@
+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

@@ -0,0 +1,242 @@
+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

@@ -0,0 +1,297 @@
+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

@@ -0,0 +1,169 @@
+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

@@ -0,0 +1,28 @@
+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.
+ */
+@Module({
+  controllers: [HierarchyController],
+  providers: [
+    HierarchyAuditRepository,
+    HierarchyGrantEvaluationService,
+    HierarchyRepository,
+    HierarchyService,
+  ],
+  exports: [HierarchyAuditRepository, HierarchyGrantEvaluationService],
+})
+export class HierarchyModule {}

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

@@ -0,0 +1,935 @@
+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

@@ -0,0 +1,31 @@
+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,7 +176,18 @@ describe('MCP actor identity and tool scope enforcement', () => {
     ).toBe(false);
     expect(
       deriveMcpToolScopesForUser({ role: 'platform-admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
-    ).toBe(true);
+    ).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);
+    }
   });
 
   it('fails closed when scopes are not supplied by the authenticated context policy', () => {
@@ -311,14 +322,20 @@ describe('MCP actor identity and tool scope enforcement', () => {
     ]);
   });
 
-  it('enforces tenant boundaries for tenant-admin brain project, mission, and task reads', async () => {
-    const { service } = makeService({
+  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 = {
       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',
+          name: 'same tenant, unowned',
         },
         {
           id: 'project-tenant-b',
@@ -328,39 +345,50 @@ 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');
+    };
 
-    service.registerTools(server, actor);
+    const actors = [
+      makeAdminActor('role-bearing-user', 'tenant-a'),
+      makePlatformAdminActor('role-bearing-user'),
+    ];
 
-    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']);
+    for (const actor of actors) {
+      const { service } = makeService(fixtures);
+      const { server, tools } = makeCapturingServer();
+      service.registerTools(server, actor);
 
-    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 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 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']);
+      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']);
+    }
   });
 
   it('denies tenant-admin task writes outside the authenticated tenant', async () => {
     const { service, brain } = makeService({
       projects: [
-        { id: 'project-tenant-a', ownerId: 'other-user-a', teamId: 'tenant-a' },
+        // §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-b', ownerId: 'other-user-b', teamId: 'tenant-b' },
       ],
       missions: [
@@ -373,7 +401,29 @@ describe('MCP actor identity and tool scope enforcement', () => {
       ],
     });
     const { server, tools } = makeCapturingServer();
-    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
+    // 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,
+      ],
+    });
 
     service.registerTools(server, actor);
 
@@ -416,7 +466,7 @@ describe('MCP actor identity and tool scope enforcement', () => {
     );
   });
 
-  it('keeps admin-only coordination tools on server-derived paths', async () => {
+  it('denies coordination tools to every role-derived actor and keeps the granted path server-derived', async () => {
     const { service, coord } = makeService();
     const { server, tools } = makeCapturingServer();
     const member = makeMemberActor('authenticated-user');
@@ -433,10 +483,25 @@ 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 platformAdminTool.handler({ projectPath: '/tmp/victim' });
+    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' });
     expect(coord.listTasks).toHaveBeenCalledWith(process.cwd());
   });
 

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

@@ -63,20 +63,6 @@ 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,
@@ -89,15 +75,17 @@ const MEMBER_MCP_SCOPES = new Set<McpToolScope>([
   MCP_TOOL_SCOPES.memory_save_insight,
 ]);
 
-export function deriveMcpToolScopesForUser(input: {
+/**
+ * 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: {
   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);
 }
 
@@ -168,41 +156,22 @@ type TaskLike = TenantScopedLike & {
   userId?: string | null;
 };
 
-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
-  );
-}
-
+/**
+ * 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 filterProjectsForActor<T extends ProjectLike>(actor: McpActorContext, projects: T[]): T[] {
-  if (isGlobalAdminActor(actor)) return projects;
-  return projects.filter(
-    (project) =>
-      project.ownerId === actor.userId ||
-      (isTenantAdminActor(actor) && matchesTenant(actor, project)),
-  );
+  return projects.filter((project) => project.ownerId === actor.userId);
 }
 
 function filterMissionsByDirectActorScope<T extends MissionLike>(
   actor: McpActorContext,
   missions: T[],
 ): T[] {
-  if (isGlobalAdminActor(actor)) return missions;
-  return missions.filter(
-    (mission) =>
-      mission.userId === actor.userId ||
-      (isTenantAdminActor(actor) && matchesTenant(actor, mission)),
-  );
+  return missions.filter((mission) => mission.userId === actor.userId);
 }
 
 function scopesEqual(left: ReadonlySet<McpToolScope>, right: ReadonlySet<McpToolScope>): boolean {
@@ -293,7 +262,6 @@ 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;
   }
@@ -302,8 +270,6 @@ 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),
@@ -317,7 +283,6 @@ 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;
@@ -339,7 +304,7 @@ export class McpService implements OnModuleDestroy {
     actor: McpActorContext,
     refs: { projectId?: string | null; missionId?: string | null },
   ): Promise<void> {
-    if (!isGlobalAdminActor(actor) && !refs.projectId && !refs.missionId) {
+    if (!refs.projectId && !refs.missionId) {
       throw new Error('MCP task scope denied');
     }
     await this.assertTaskReferencesAuthorized(actor, refs);
@@ -349,8 +314,6 @@ 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(),
@@ -367,7 +330,6 @@ 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,11 +108,13 @@ 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,6 +77,12 @@ 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';
@@ -102,6 +108,12 @@ 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/spa/serve-spa.e2e.spec.ts

@@ -0,0 +1,192 @@
+/**
+ * E2E integration test — SPA static serving (Phase P5 cutover, #1444; tests
+ * added in P6, #1445, review follow-up SF1 on PR #1453).
+ *
+ * Boots a real Nest+Fastify app the way main.ts does (mountSpaStatic after the
+ * controllers) against a fixture dist directory, and pins the serving
+ * contract:
+ *
+ *   1. `/` and client-side deep links fall back to index.html.
+ *   2. Declared API routes win over the catch-all.
+ *   3. Unknown backend paths (/api, /mcp, /socket.io) are JSON 404s, never the
+ *      SPA page — including with a query string (`/api?x=1`).
+ *   4. Static files are served exactly; hashed /assets/ files get immutable
+ *      cache headers, everything else revalidates (max-age=0), and a missing
+ *      /assets/ file is a 404 — never the SPA fallback.
+ *   5. WEB_DIST_DIR unset disables SPA serving entirely.
+ *   6. WEB_DIST_DIR pointing at a directory without index.html fails at boot.
+ */
+
+import 'reflect-metadata';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it, expect, afterAll, beforeAll } from 'vitest';
+import { Test } from '@nestjs/testing';
+import { Controller, Get, type INestApplication } from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import request from 'supertest';
+import { mountSpaStatic } from './serve-spa.js';
+
+const INDEX_HTML = '<!doctype html><html><body>mosaic spa fixture</body></html>\n';
+const ASSET_JS = 'console.log("hashed asset");\n';
+
+@Controller('api/spa-test')
+class SpaTestController {
+  @Get('ping')
+  ping(): { ok: boolean } {
+    return { ok: true };
+  }
+}
+
+async function createApp(): Promise<INestApplication> {
+  const moduleRef = await Test.createTestingModule({
+    controllers: [SpaTestController],
+  }).compile();
+
+  const app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+  await app.init();
+  // Mirror main.ts ordering: SPA mounting happens after the app (and its
+  // controllers) exist, before listen.
+  await mountSpaStatic(app as NestFastifyApplication);
+  await (app as NestFastifyApplication).getHttpAdapter().getInstance().ready();
+  return app;
+}
+
+describe('SPA static serving — fixture dist dir', () => {
+  let app: INestApplication;
+  let distDir: string;
+  let previousWebDistDir: string | undefined;
+
+  beforeAll(async () => {
+    distDir = await mkdtemp(path.join(tmpdir(), 'serve-spa-fixture-'));
+    await writeFile(path.join(distDir, 'index.html'), INDEX_HTML);
+    await writeFile(path.join(distDir, 'favicon.svg'), '<svg></svg>\n');
+    await mkdir(path.join(distDir, 'assets'), { recursive: true });
+    await writeFile(path.join(distDir, 'assets', 'app-abc123.js'), ASSET_JS);
+
+    previousWebDistDir = process.env['WEB_DIST_DIR'];
+    process.env['WEB_DIST_DIR'] = distDir;
+    app = await createApp();
+  });
+
+  afterAll(async () => {
+    if (previousWebDistDir === undefined) {
+      delete process.env['WEB_DIST_DIR'];
+    } else {
+      process.env['WEB_DIST_DIR'] = previousWebDistDir;
+    }
+    await app.close();
+    await rm(distDir, { recursive: true, force: true });
+  });
+
+  it('serves index.html at /', async () => {
+    const res = await request(app.getHttpServer()).get('/');
+    expect(res.status).toBe(200);
+    expect(res.text).toBe(INDEX_HTML);
+    expect(res.headers['content-type']).toContain('text/html');
+  });
+
+  it('falls back to index.html for client-side deep links', async () => {
+    for (const deepLink of ['/chat', '/projects/42', '/settings']) {
+      const res = await request(app.getHttpServer()).get(deepLink);
+      expect(res.status, deepLink).toBe(200);
+      expect(res.text, deepLink).toBe(INDEX_HTML);
+    }
+  });
+
+  it('declared API routes win over the SPA catch-all', async () => {
+    const res = await request(app.getHttpServer()).get('/api/spa-test/ping');
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ ok: true });
+  });
+
+  it('unknown backend paths are JSON 404s, never the SPA page', async () => {
+    for (const backendPath of ['/api/nope', '/api', '/mcp/nope', '/socket.io/nope']) {
+      const res = await request(app.getHttpServer()).get(backendPath);
+      expect(res.status, backendPath).toBe(404);
+      expect(res.headers['content-type'], backendPath).toContain('application/json');
+      expect(res.body, backendPath).toMatchObject({ error: 'Not Found', statusCode: 404 });
+    }
+  });
+
+  it('a backend path with a query string is still a backend 404 (/api?x=1)', async () => {
+    const res = await request(app.getHttpServer()).get('/api?x=1');
+    expect(res.status).toBe(404);
+    expect(res.headers['content-type']).toContain('application/json');
+  });
+
+  it('serves static files exactly', async () => {
+    const res = await request(app.getHttpServer()).get('/favicon.svg');
+    expect(res.status).toBe(200);
+    // supertest buffers image/svg+xml as a Buffer body, not res.text.
+    const body = res.text || (res.body as Buffer).toString('utf8');
+    expect(body).toBe('<svg></svg>\n');
+  });
+
+  it('hashed /assets/ files get immutable cache headers', async () => {
+    const res = await request(app.getHttpServer()).get('/assets/app-abc123.js');
+    expect(res.status).toBe(200);
+    expect(res.text).toBe(ASSET_JS);
+    expect(res.headers['cache-control']).toBe('public, max-age=31536000, immutable');
+  });
+
+  it('missing /assets/ files are 404s, never the SPA page with an immutable header', async () => {
+    // The exact request a browser with a stale index.html makes after a
+    // deploy: the old hashed filename. Serving index.html here would poison
+    // caches with a year-long immutable entry whose body is HTML.
+    for (const missingAsset of ['/assets/app-old999.js', '/assets/app-old999.js?v=1']) {
+      const res = await request(app.getHttpServer()).get(missingAsset);
+      expect(res.status, missingAsset).toBe(404);
+      expect(res.text, missingAsset).not.toContain('mosaic spa fixture');
+      // The 404 carries no cache-control at all; ?? '' keeps the assertion valid.
+      expect(res.headers['cache-control'] ?? '', missingAsset).not.toContain('immutable');
+    }
+  });
+
+  it('index.html and non-asset files revalidate (no immutable caching)', async () => {
+    for (const revalidating of ['/', '/chat', '/favicon.svg']) {
+      const res = await request(app.getHttpServer()).get(revalidating);
+      expect(res.headers['cache-control'], revalidating).not.toContain('immutable');
+    }
+  });
+
+  it('non-GET unmatched requests keep the stock 404 (catch-all is GET/HEAD only)', async () => {
+    const res = await request(app.getHttpServer()).post('/chat');
+    expect(res.status).toBe(404);
+    expect(res.text).not.toContain('mosaic spa fixture');
+  });
+});
+
+describe('SPA static serving — configuration edges', () => {
+  it('WEB_DIST_DIR unset disables SPA serving', async () => {
+    const previous = process.env['WEB_DIST_DIR'];
+    delete process.env['WEB_DIST_DIR'];
+    try {
+      const app = await createApp();
+      const res = await request(app.getHttpServer()).get('/chat');
+      expect(res.status).toBe(404);
+      await app.close();
+    } finally {
+      if (previous !== undefined) {
+        process.env['WEB_DIST_DIR'] = previous;
+      }
+    }
+  });
+
+  it('WEB_DIST_DIR without index.html fails at boot', async () => {
+    const emptyDir = await mkdtemp(path.join(tmpdir(), 'serve-spa-empty-'));
+    const previous = process.env['WEB_DIST_DIR'];
+    process.env['WEB_DIST_DIR'] = emptyDir;
+    try {
+      await expect(createApp()).rejects.toThrow(/index\.html.*does not exist/);
+    } finally {
+      if (previous === undefined) {
+        delete process.env['WEB_DIST_DIR'];
+      } else {
+        process.env['WEB_DIST_DIR'] = previous;
+      }
+      await rm(emptyDir, { recursive: true, force: true });
+    }
+  });
+});

apps/gateway/src/spa/serve-spa.ts

@@ -8,7 +8,12 @@ import type { NestFastifyApplication } from '@nestjs/platform-fastify';
 const BACKEND_PREFIXES = ['/api', '/mcp', '/socket.io'] as const;
 
 function isBackendPath(url: string): boolean {
-  return BACKEND_PREFIXES.some((prefix) => url === prefix || url.startsWith(`${prefix}/`));
+  // Match on the path only: `/api?x=1` is a backend request, and the query
+  // string must never turn it into an SPA fallback.
+  const pathOnly = url.split('?', 1)[0] ?? url;
+  return BACKEND_PREFIXES.some(
+    (prefix) => pathOnly === prefix || pathOnly.startsWith(`${prefix}/`),
+  );
 }
 
 /**
@@ -39,8 +44,7 @@ export async function mountSpaStatic(app: NestFastifyApplication): Promise<void>
 
   // Default cache semantics: public, max-age=0 with ETag/Last-Modified, so
   // every response revalidates (304 when unchanged). Always correct, including
-  // for index.html after a deploy; immutable caching for hashed /assets/ files
-  // is a P6 optimization.
+  // for index.html after a deploy.
   await app.register(
     fastifyStatic as never,
     {
@@ -50,13 +54,28 @@ export async function mountSpaStatic(app: NestFastifyApplication): Promise<void>
     } as never,
   );
 
+  const fastify = app.getHttpAdapter().getInstance();
+
+  // Files under /assets/ carry a content hash in their name (Vite emits them
+  // that way), so they get long-lived immutable caching: a changed file is a
+  // new URL, never a stale cache hit. An onSend hook rather than the plugin's
+  // `setHeaders` option, because @fastify/static applies its own computed
+  // cache-control (reply.headers) after calling setHeaders, overriding it.
+  fastify.addHook('onSend', (req, reply, payload, done) => {
+    const pathOnly = (req.raw.url ?? '').split('?', 1)[0] ?? '';
+    if (reply.statusCode === 200 && pathOnly.startsWith('/assets/')) {
+      void reply.header('cache-control', 'public, max-age=31536000, immutable');
+    }
+    done(null, payload);
+  });
+
   // A wildcard route, not setNotFoundHandler: Nest installs its own not-found
   // handler during init and Fastify allows only one. find-my-way matches
   // most-specific-first, so every declared route (API, static files) wins over
   // this catch-all; non-GET unmatched requests keep Fastify's stock 404.
-  const fastify = app.getHttpAdapter().getInstance();
   fastify.get('/*', (req, reply) => {
     const url = req.raw.url ?? '';
+    const pathOnly = url.split('?', 1)[0] ?? url;
     if (isBackendPath(url)) {
       // An unknown backend path is an API 404, never the SPA page.
       void reply.code(404).send({
@@ -66,6 +85,18 @@ export async function mountSpaStatic(app: NestFastifyApplication): Promise<void>
       });
       return;
     }
+    if (pathOnly === '/assets' || pathOnly.startsWith('/assets/')) {
+      // A missing hashed asset — typically a browser holding a stale
+      // index.html after a deploy — must 404. Falling through to the SPA
+      // fallback would return index.html as the asset body, and the onSend
+      // hook above would stamp it with a year-long immutable cache-control.
+      void reply.code(404).send({
+        message: `Asset ${pathOnly} not found`,
+        error: 'Not Found',
+        statusCode: 404,
+      });
+      return;
+    }
     // sendFile is decorated by @fastify/static; its type augmentation targets
     // a different fastify copy in the pnpm tree than the Nest adapter's.
     (reply as unknown as { sendFile: (file: string) => unknown }).sendFile('index.html');

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

@@ -1,6 +1,18 @@
 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
@@ -43,6 +55,56 @@ 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 {

apps/web/e2e/admin.spec.ts

@@ -1,11 +1,14 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, ADMIN_USER, TEST_USER } from './helpers/auth.js';
+import { loginAs, ADMIN_USER, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Admin page — admin user', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, ADMIN_USER.email, ADMIN_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded admin user — skipping admin tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded admin user — skipping admin tests',
+    );
   });
 
   test('admin page loads with the Admin Panel heading', async ({ page }) => {
@@ -31,15 +34,11 @@ test.describe('Admin page — admin user', () => {
     await page.goto('/admin');
     await page.getByRole('button', { name: /system health/i }).click();
     // Health cards or loading indicator should appear
-    const hasLoading = await page
+    const loadingOrCard = page
       .getByText(/loading health/i)
-      .isVisible()
-      .catch(() => false);
-    const hasCard = await page
-      .getByText(/database/i)
-      .isVisible()
-      .catch(() => false);
-    expect(hasLoading || hasCard).toBe(true);
+      .or(page.getByText(/database/i))
+      .first();
+    await expect(loadingOrCard).toBeVisible({ timeout: 10_000 });
   });
 });
 
@@ -47,26 +46,19 @@ test.describe('Admin page — non-admin user', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping non-admin tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping non-admin tests',
+    );
   });
 
-  test('non-admin visiting /admin sees access denied or is redirected', async ({ page }) => {
+  test('non-admin visiting /admin never sees the admin panel', async ({ page }) => {
     await page.goto('/admin');
-    // Either redirected away or shown an access-denied message
-    const onAdmin = page.url().includes('/admin');
-    if (onAdmin) {
-      // Should show some access-denied content rather than the full admin panel
-      const hasPanel = await page
-        .getByRole('heading', { name: /admin panel/i })
-        .isVisible()
-        .catch(() => false);
-      // If heading is visible, the guard allowed access (user may have admin role in this env)
-      // — not a failure, just informational
-      if (!hasPanel) {
-        // access denied message, redirect, or guard placeholder
-        const url = page.url();
-        expect(url).toBeTruthy(); // environment-dependent — no hard assertion
-      }
-    }
+    // Wait for the app shell to render (redirect and access-denied views both
+    // keep the sidebar), then assert the panel itself is absent. globalSetup
+    // seeds TEST_USER with role 'member', so this is a real authorization
+    // assertion, not environment-dependent.
+    await expect(page.getByRole('img', { name: /mosaic logo/i })).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByRole('heading', { name: /admin panel/i })).not.toBeVisible();
   });
 });

apps/web/e2e/auth.spec.ts

@@ -1,5 +1,5 @@
 import { test, expect } from '@playwright/test';
-import { TEST_USER } from './helpers/auth.js';
+import { REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 // ── Login page ────────────────────────────────────────────────────────────────
 
@@ -49,18 +49,14 @@ test.describe('Login page', () => {
   });
 
   test('redirects to /chat after successful login', async ({ page }) => {
+    // Only meaningful with known-good credentials; against a live environment
+    // this would just probe someone else's user table.
+    test.skip(!REQUIRE_SEEDED_AUTH, 'needs seeded credentials (E2E_REQUIRE_SEEDED_AUTH=1)');
     await page.goto('/login');
     await page.getByLabel('Email').fill(TEST_USER.email);
     await page.getByLabel('Password').fill(TEST_USER.password);
     await page.getByRole('button', { name: /sign in/i }).click();
-    // Either reaches /chat or shows an error (if credentials are wrong in this env).
-    // We assert a navigation away from /login, or the alert is shown.
-    await Promise.race([
-      expect(page).toHaveURL(/\/chat/, { timeout: 10_000 }),
-      expect(page.getByRole('alert')).toBeVisible({ timeout: 10_000 }),
-    ]).catch(() => {
-      // Acceptable — environment may not have seeded credentials
-    });
+    await expect(page).toHaveURL(/\/chat/, { timeout: 10_000 });
   });
 });
 

apps/web/e2e/chat.spec.ts

@@ -1,45 +1,38 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
+import { loginAs, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Chat page', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     // If login failed (no seeded user in env) we may be on /login — skip
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
-  test('chat page loads and shows the welcome message or conversation list', async ({ page }) => {
+  test('chat page loads and shows the conversation area', async ({ page }) => {
     await page.goto('/chat');
-    // Either there are conversations listed or the welcome empty-state is shown
-    const hasWelcome = await page
-      .getByRole('heading', { name: /welcome to mosaic chat/i })
-      .isVisible()
-      .catch(() => false);
-    const hasConversationPanel = await page
-      .locator('[data-testid="conversation-list"], nav, aside')
-      .first()
-      .isVisible()
-      .catch(() => false);
-
-    expect(hasWelcome || hasConversationPanel).toBe(true);
+    await expect(page.getByRole('heading', { level: 1, name: /chat/i })).toBeVisible({
+      timeout: 10_000,
+    });
+    await expect(page.getByRole('log', { name: /conversation/i })).toBeVisible();
   });
 
-  test('new conversation button is visible', async ({ page }) => {
+  test('message composer input is visible', async ({ page }) => {
     await page.goto('/chat');
-    // "Start new conversation" button or a "+" button in the sidebar
-    const newConvButton = page.getByRole('button', { name: /new conversation|start new/i }).first();
-    await expect(newConvButton).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByLabel('Message')).toBeVisible({ timeout: 10_000 });
   });
 
-  test('clicking new conversation shows a chat input area', async ({ page }) => {
+  test('command panel lists /new and exposes the run controls', async ({ page }) => {
     await page.goto('/chat');
-    // Find any button that creates a new conversation
-    const newBtn = page.getByRole('button', { name: /new conversation|start new/i }).first();
-    await newBtn.click();
-    // After creating, a text input for sending messages should appear
-    const chatInput = page.getByRole('textbox').or(page.locator('textarea')).first();
-    await expect(chatInput).toBeVisible({ timeout: 10_000 });
+    // Conversations are command-driven: /new starts one via the commands panel.
+    const commandList = page.getByRole('list', { name: /available commands/i });
+    await expect(commandList).toBeVisible({ timeout: 10_000 });
+    await expect(commandList.getByText('/new', { exact: true })).toBeVisible();
+    await expect(page.getByLabel('Command name')).toBeVisible();
+    await expect(page.getByRole('button', { name: /run command/i })).toBeVisible();
   });
 
   test('sidebar navigation is present on chat page', async ({ page }) => {

apps/web/e2e/global-setup.ts

@@ -0,0 +1,95 @@
+import type { FullConfig } from '@playwright/test';
+import { ADMIN_USER, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
+
+/**
+ * Seed the E2E users through the gateway's real APIs (#1445, P6).
+ *
+ * On a fresh database (CI boots the gateway on the embedded PGlite path):
+ *   1. POST /api/bootstrap/setup creates ADMIN_USER as the first admin.
+ *   2. The admin signs in and creates TEST_USER via the better-auth admin API.
+ *
+ * Against an environment that already has users (needsSetup=false), seeding is
+ * skipped entirely: the specs keep their own skip-when-login-fails guards, so
+ * a live environment stays usable as a test target without mutation. Under
+ * E2E_REQUIRE_SEEDED_AUTH=1 (CI) that state is instead a hard failure and the
+ * guards are disabled — see helpers/auth.ts.
+ *
+ * On a fresh database, any seeding failure throws and fails the whole run: an
+ * E2E gate whose authenticated suites silently skip would pass while proving
+ * nothing.
+ */
+export default async function globalSetup(config: FullConfig): Promise<void> {
+  const baseURL = config.projects[0]?.use?.baseURL ?? 'http://localhost:14242';
+
+  const statusRes = await fetch(`${baseURL}/api/bootstrap/status`);
+  if (!statusRes.ok) {
+    throw new Error(`GET /api/bootstrap/status returned ${statusRes.status} — is the gateway up?`);
+  }
+  const status = (await statusRes.json()) as { needsSetup: boolean };
+  if (!status.needsSetup) {
+    if (REQUIRE_SEEDED_AUTH) {
+      // CI boots the gateway on a fresh HOME-isolated database, so an
+      // already-populated one means the isolation regressed — refuse to run
+      // against unknown data rather than skip-and-pass.
+      throw new Error(
+        'E2E_REQUIRE_SEEDED_AUTH=1 but the database already has users — gateway HOME isolation regressed?',
+      );
+    }
+    console.info('[e2e setup] users already exist; skipping seed');
+    return;
+  }
+
+  const setupRes = await fetch(`${baseURL}/api/bootstrap/setup`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      name: ADMIN_USER.name,
+      email: ADMIN_USER.email,
+      password: ADMIN_USER.password,
+    }),
+  });
+  if (!setupRes.ok) {
+    throw new Error(
+      `POST /api/bootstrap/setup failed (${setupRes.status}): ${await setupRes.text()}`,
+    );
+  }
+  console.info(`[e2e setup] bootstrap admin created: ${ADMIN_USER.email}`);
+
+  // better-auth's CSRF protection rejects requests without an Origin header
+  // (403 MISSING_OR_NULL_ORIGIN), so the server-side fetches here send the
+  // gateway's own origin — the same value a browser tab on the SPA would send.
+  const authHeaders = { 'content-type': 'application/json', origin: baseURL };
+
+  const signInRes = await fetch(`${baseURL}/api/auth/sign-in/email`, {
+    method: 'POST',
+    headers: authHeaders,
+    body: JSON.stringify({ email: ADMIN_USER.email, password: ADMIN_USER.password }),
+  });
+  if (!signInRes.ok) {
+    throw new Error(`admin sign-in failed (${signInRes.status}): ${await signInRes.text()}`);
+  }
+  const cookies = signInRes.headers
+    .getSetCookie()
+    .map((cookie) => cookie.split(';', 1)[0])
+    .join('; ');
+  if (!cookies) {
+    throw new Error('admin sign-in returned no session cookie');
+  }
+
+  const createRes = await fetch(`${baseURL}/api/auth/admin/create-user`, {
+    method: 'POST',
+    headers: { ...authHeaders, cookie: cookies },
+    body: JSON.stringify({
+      name: TEST_USER.name,
+      email: TEST_USER.email,
+      password: TEST_USER.password,
+      role: 'member',
+    }),
+  });
+  if (!createRes.ok) {
+    throw new Error(
+      `POST /api/auth/admin/create-user failed (${createRes.status}): ${await createRes.text()}`,
+    );
+  }
+  console.info(`[e2e setup] test user created: ${TEST_USER.email}`);
+}

apps/web/e2e/helpers/auth.ts

@@ -13,11 +13,28 @@ export const ADMIN_USER = {
 };
 
 /**
- * Fill the login form and submit. Waits for navigation after success.
+ * Set when the database was seeded by global-setup (CI sets it in the
+ * publish.yml e2e step). Seeded credentials MUST work, so login failures are
+ * hard failures and the skip-when-login-fails guards are disabled — otherwise
+ * a login regression would skip every authenticated suite and the gate would
+ * pass while proving nothing. Unset (a live environment used as a test
+ * target), the guards stay on and unseeded credentials skip their suites.
+ */
+export const REQUIRE_SEEDED_AUTH = process.env['E2E_REQUIRE_SEEDED_AUTH'] === '1';
+
+/**
+ * Fill the login form and submit, then wait for the post-login redirect to
+ * /chat. Under REQUIRE_SEEDED_AUTH a missed redirect throws (failing the
+ * test). Otherwise the timeout is swallowed: the page stays on /login and the
+ * callers' `test.skip(...)` guards see that. Without this wait, every guard
+ * read page.url() before the redirect happened and skipped its suite even
+ * when login succeeded (#1445).
  */
 export async function loginAs(page: Page, email: string, password: string): Promise<void> {
   await page.goto('/login');
   await page.getByLabel('Email').fill(email);
   await page.getByLabel('Password').fill(password);
   await page.getByRole('button', { name: /sign in/i }).click();
+  const redirect = page.waitForURL(/\/chat/, { timeout: 10_000 });
+  await (REQUIRE_SEEDED_AUTH ? redirect : redirect.catch(() => {}));
 }

apps/web/e2e/navigation.spec.ts

@@ -1,16 +1,22 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
+import { loginAs, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Sidebar navigation', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
-  test('sidebar shows Mosaic brand link', async ({ page }) => {
+  test('sidebar shows the Mosaic brand', async ({ page }) => {
     await page.goto('/chat');
-    await expect(page.getByRole('link', { name: /mosaic/i }).first()).toBeVisible();
+    // The brand block is a logo image plus "Mosaic / Mission Control" text,
+    // not a link.
+    await expect(page.getByRole('img', { name: /mosaic logo/i })).toBeVisible();
+    await expect(page.getByText('Mission Control')).toBeVisible();
   });
 
   test('Chat nav link navigates to /chat', async ({ page }) => {
@@ -48,11 +54,12 @@ test.describe('Sidebar navigation', () => {
 
   test('active link is visually highlighted', async ({ page }) => {
     await page.goto('/chat');
-    // The active link should have a distinct class — check that the Chat link
-    // has the active style class (bg-blue-600/20 text-blue-400)
+    // The sidebar marks the active item with `font-medium` (plus an inline
+    // primary-color style); inactive items get the hover class instead.
     const chatLink = page.getByRole('link', { name: /^chat$/i }).first();
-    const cls = await chatLink.getAttribute('class');
-    expect(cls).toContain('blue');
+    const projectsLink = page.getByRole('link', { name: /^projects$/i }).first();
+    await expect(chatLink).toHaveClass(/font-medium/);
+    await expect(projectsLink).not.toHaveClass(/font-medium/);
   });
 });
 
@@ -60,18 +67,23 @@ test.describe('Route transitions', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
   test('navigating chat → projects → settings → chat works without errors', async ({ page }) => {
     await page.goto('/chat');
     await expect(page).toHaveURL(/\/chat/);
 
+    // level: 1 — empty-state h2s ("No projects yet") also match the loose
+    // patterns, and a two-element match is a strict-mode violation.
     await page.goto('/projects');
-    await expect(page.getByRole('heading', { name: /projects/i })).toBeVisible();
+    await expect(page.getByRole('heading', { level: 1, name: /projects/i })).toBeVisible();
 
     await page.goto('/settings');
-    await expect(page.getByRole('heading', { name: /settings/i })).toBeVisible();
+    await expect(page.getByRole('heading', { level: 1, name: /settings/i })).toBeVisible();
 
     await page.goto('/chat');
     await expect(page).toHaveURL(/\/chat/);

apps/web/e2e/projects.spec.ts

@@ -1,16 +1,23 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
+import { loginAs, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Projects page', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
   test('projects page loads with heading', async ({ page }) => {
     await page.goto('/projects');
-    await expect(page.getByRole('heading', { name: /projects/i })).toBeVisible({ timeout: 10_000 });
+    // level: 1 — the "No projects yet" empty-state h2 also matches /projects/i
+    // and a two-element match is a strict-mode violation.
+    await expect(page.getByRole('heading', { level: 1, name: /projects/i })).toBeVisible({
+      timeout: 10_000,
+    });
   });
 
   test('shows empty state or project cards when loaded', async ({ page }) => {
@@ -18,23 +25,11 @@ test.describe('Projects page', () => {
     // Wait for loading state to clear
     await expect(page.getByText(/loading projects/i)).not.toBeVisible({ timeout: 10_000 });
 
-    const hasProjects = await page
+    const cardsOrEmpty = page
       .locator('[class*="grid"]')
-      .isVisible()
-      .catch(() => false);
-    const hasEmpty = await page
-      .getByText(/no projects yet/i)
-      .isVisible()
-      .catch(() => false);
-
-    expect(hasProjects || hasEmpty).toBe(true);
-  });
-
-  test('shows Active Mission section', async ({ page }) => {
-    await page.goto('/projects');
-    await expect(page.getByRole('heading', { name: /active mission/i })).toBeVisible({
-      timeout: 10_000,
-    });
+      .or(page.getByText(/no projects yet/i))
+      .first();
+    await expect(cardsOrEmpty).toBeVisible({ timeout: 10_000 });
   });
 
   test('sidebar navigation is present', async ({ page }) => {

apps/web/e2e/settings.spec.ts

@@ -1,11 +1,14 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
+import { loginAs, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Settings page', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
   test('settings page loads with heading', async ({ page }) => {

apps/web/playwright.config.ts

@@ -1,23 +1,30 @@
 import { defineConfig, devices } from '@playwright/test';
 
 /**
- * Playwright E2E configuration for Mosaic web app.
+ * Playwright E2E configuration for the Mosaic web SPA.
  *
- * Assumes:
- *   - Next.js web app running on http://localhost:3000
- *   - NestJS gateway running on http://localhost:14242
+ * Assumes the NestJS gateway is already running on http://localhost:14242 and
+ * serving the built SPA bundle (WEB_DIST_DIR pointing at apps/web/dist) — the
+ * same serving path production uses (Phase P5, #1444). Override the target
+ * with PLAYWRIGHT_BASE_URL.
+ *
+ * global-setup seeds the E2E users through the real bootstrap and admin APIs
+ * when the database is empty; against an already-populated environment it
+ * seeds nothing.
  *
  * Run with:   pnpm --filter @mosaicstack/web test:e2e
  */
 export default defineConfig({
   testDir: './e2e',
+  globalSetup: './e2e/global-setup.ts',
   fullyParallel: true,
   forbidOnly: !!process.env['CI'],
   retries: process.env['CI'] ? 2 : 0,
   workers: process.env['CI'] ? 1 : undefined,
-  reporter: 'html',
+  // CI needs the verdict in the step log; the html report is a local tool.
+  reporter: process.env['CI'] ? 'list' : 'html',
   use: {
-    baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:3000',
+    baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:14242',
     trace: 'on-first-retry',
     screenshot: 'only-on-failure',
   },
@@ -27,6 +34,6 @@ export default defineConfig({
       use: { ...devices['Desktop Chrome'] },
     },
   ],
-  // Do NOT auto-start the dev server — tests assume it is already running.
+  // Do NOT auto-start a server — tests assume the gateway is already running.
   // webServer is intentionally omitted so tests can run against a live env.
 });

apps/web/src/spa/pages/settings.tsx

@@ -57,6 +57,16 @@ function prefValue<T>(prefs: Preference[], key: string, fallback: T): T {
   return p.value as T;
 }
 
+// The reset must not outlive the tab: an uncleared setTimeout fires into a
+// torn-down environment (unmount, or jsdom teardown under vitest).
+function useSavedBadgeReset(saveState: SaveState, setSaveState: (s: SaveState) => void): void {
+  useEffect(() => {
+    if (saveState !== 'saved') return undefined;
+    const timer = setTimeout(() => setSaveState('idle'), 2000);
+    return () => clearTimeout(timer);
+  }, [saveState, setSaveState]);
+}
+
 // ─── Main Page ────────────────────────────────────────────────────────────────
 
 export function SettingsPage(): React.ReactElement {
@@ -111,6 +121,7 @@ function ProfileTab({
   const [image, setImage] = useState(session?.user.image ?? '');
   const [saveState, setSaveState] = useState<SaveState>('idle');
   const [errorMsg, setErrorMsg] = useState('');
+  useSavedBadgeReset(saveState, setSaveState);
 
   // Sync from session when it loads
   useEffect(() => {
@@ -131,7 +142,6 @@ function ProfileTab({
         return;
       }
       setSaveState('saved');
-      setTimeout(() => setSaveState('idle'), 2000);
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : 'Failed to update profile';
       setErrorMsg(message);
@@ -194,6 +204,7 @@ function AppearanceTab(): React.ReactElement {
   const [defaultModel, setDefaultModel] = useState('');
   const [saveState, setSaveState] = useState<SaveState>('idle');
   const [errorMsg, setErrorMsg] = useState('');
+  useSavedBadgeReset(saveState, setSaveState);
 
   useEffect(() => {
     api<Preference[]>('/api/memory/preferences?category=appearance')
@@ -239,7 +250,6 @@ function AppearanceTab(): React.ReactElement {
           : []),
       ]);
       setSaveState('saved');
-      setTimeout(() => setSaveState('idle'), 2000);
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : 'Failed to save preferences';
       setErrorMsg(message);
@@ -323,6 +333,7 @@ function NotificationsTab(): React.ReactElement {
   const [emailDigest, setEmailDigest] = useState(false);
   const [saveState, setSaveState] = useState<SaveState>('idle');
   const [errorMsg, setErrorMsg] = useState('');
+  useSavedBadgeReset(saveState, setSaveState);
 
   useEffect(() => {
     api<Preference[]>('/api/memory/preferences?category=communication')
@@ -369,7 +380,6 @@ function NotificationsTab(): React.ReactElement {
         }),
       ]);
       setSaveState('saved');
-      setTimeout(() => setSaveState('idle'), 2000);
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : 'Failed to save preferences';
       setErrorMsg(message);

docs/PRD.md

@@ -882,3 +882,12 @@ Objective: for alpha 0.0.50, the release cannot publish, report, or display work
 ### Out of scope
 
 The canonical dispatcher/control-plane vertical slice (work graph, execution attempts, fenced leases, typed check-in, independent verifier dispatch) is decided post-alpha (SDLC-D-033, option B). Multi-pipeline verification certificates (SDLC-D-034 option B) are post-alpha. Full AF-1..AF-4 objective matrices and Mission Control portfolio surfaces are post-alpha.
+
+## Official CLI Capability and Tool Migration Workstream (T78)
+
+Normative contract on integration trunk `next`:
+[docs/requirements/cli-capability-migration.md](./requirements/cli-capability-migration.md):
+migrates agent-facing operations from directly invoked scripts into documented, first-class
+`mosaic` CLI command groups, together with the central-registry resolver, capability catalog,
+adapter boundary, and phased legacy-tool-tree decommission the migration requires. The contract
+carries its own implementation hold and delivery stages.

docs/ROADMAP.md

@@ -12,7 +12,9 @@ design; scoping one requires its own PRD section or requirements doc plus
 review.
 
 Phases are product phases. The in-flight platform workstreams (KBN-100/101
-kanban SOT implementation, FCM #758, FCOM #766, TESS, RI #1275, and the other
+kanban SOT implementation, FCM #758, FCOM #766, TESS, RI #1275, T78 CLI
+capability migration
+([requirements](./requirements/cli-capability-migration.md)), and the other
 Part II contracts in the PRD) run as parallel tracks under their own issues
 and are prerequisites where noted.
 

docs/SITEMAP.md

@@ -18,6 +18,7 @@
 - [Active task rollup](TASKS.md) — orchestrator-owned work state; workers do not modify it.
 - [MVP mission manifest](MISSION-MANIFEST.md) — control-plane mission rollup; activity and status remain under its authorized owner.
 - [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — complete baseline inventory, evidence labels, broken-link clusters, and migration recommendations.
+- [CLI capability migration requirements](requirements/cli-capability-migration.md): T78 official CLI capability and tool migration contract, normative contract with implementation hold (M0).
 
 ## Protected current authority and executable books
 

docs/guides/dev-guide.md

@@ -212,6 +212,20 @@ Woodpecker `.woodpecker/publish.yml` keeps stable and integration-line artifacts
 
 `next` never publishes npm `latest` or Docker `latest`. The next npm publish step verifies that `@mosaicstack/mosaic@next` resolves to the computed prerelease before the pipeline can pass.
 
+### E2E Gate (#1445, P6)
+
+Trunk publish pipelines run a headless Playwright suite (`e2e` step) before any image publishes: the built gateway `dist` boots on a throwaway embedded PGlite database (isolated via a fresh `HOME`), serves the built SPA bundle through `WEB_DIST_DIR` — the same serving path the gateway image ships — and the suite runs against it inside the pinned `mcr.microsoft.com/playwright` image. `E2E_REQUIRE_SEEDED_AUTH=1` makes login failures hard failures (the skip-when-login-fails guards are a live-environment affordance only). Both image build steps depend on this gate.
+
+Reproduce locally (Ubuntu-based environments; Fedora's headless-shell rendering is broken):
+
+```bash
+pnpm build
+BETTER_AUTH_SECRET="$(head -c 32 /dev/urandom | base64)" GATEWAY_PORT=14242 \
+  WEB_DIST_DIR="$PWD/apps/web/dist" HOME="$(mktemp -d)" node apps/gateway/dist/main.js &
+E2E_REQUIRE_SEEDED_AUTH=1 PLAYWRIGHT_BASE_URL=http://localhost:14242 \
+  pnpm --filter @mosaicstack/web exec playwright test
+```
+
 ---
 
 ## Adding New Agent Tools

docs/native-kanban-sot/INDEX.md

@@ -14,6 +14,7 @@
 | [`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

@@ -0,0 +1,117 @@
+---
+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

@@ -0,0 +1,315 @@
+---
+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/README.md

@@ -13,6 +13,10 @@ 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/cli-capability-migration.md

@@ -0,0 +1,748 @@
+---
+kind: spec
+status: active
+source_of_truth: true
+---
+
+# Official Mosaic CLI Capability and Tool Migration
+
+- **Workstream:** T78
+- **Status:** active requirements contract, implementation held by the M0 gates
+- **Decision authority:** Jason Woltje
+- **Design owner:** Vision
+- **Integration trunk:** `next`
+
+This contract is authoritative only on the integration trunk `next`. Branch copies are proposals.
+Publication does not authorize implementation until the M0 milestone, task-graph, interface, and
+partition gates pass.
+
+## 1. Purpose
+
+Migrate agent-facing operations from directly invoked scripts into documented, first-class command
+groups in the existing TypeScript and Node.js `mosaic` CLI. The CLI becomes the stable interface
+for operators, agents, the webUI, future seat containers, and future `mosaicd` execution.
+
+The mission also phases out the installed `~/.config/mosaic/tools` script surface. Existing scripts
+may remain private compatibility adapters only while measured consumers still require them.
+
+## 2. Product alignment
+
+Items 1 through 3 implement PRD D8 and D12:
+
+1. The CLI is the primary execution surface.
+2. The webUI uses Gateway APIs backed by the same official capability contracts.
+3. A missing official capability is built before a webUI bypass is accepted.
+
+This contract adds one explicit extension beyond D8 and D12: no harness, skill, or agent receives a
+separate business-logic path around the CLI and Gateway capability contract.
+
+This contract does not replace the fleet north star, issue `#1382`, the fleet configuration
+contract `#758`, the exact fleet communications contract `#766`, or future container and `mosaicd`
+specifications. It defines the interfaces those tracks consume.
+
+## 3. Fixed decisions
+
+| ID     | Decision                                                                                                                                                                       |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| T78-D1 | Extend the existing official TypeScript and Node.js `mosaic` CLI. A second Python or shell entrypoint is forbidden.                                                            |
+| T78-D2 | Expose documented groups such as `mosaic git`, `mosaic comms`, and `mosaic ci`. A generic public `mosaic tools` passthrough is forbidden.                                      |
+| T78-D3 | Resolve homes, endpoints, sockets, tool locations, and runtime paths through the central registry and one typed resolver. Commands do not hard-code them.                      |
+| T78-D4 | One rootless container per seat is the target sandbox. It has a read-only root filesystem, no container-runtime socket, and lifecycle through future `mosaicd`.                |
+| T78-D5 | Dispatch is per-site. Localhost `orch-01` alone dispatches USC-seat implementation. Homelab `orch-01` alone dispatches homelab-seat implementation and homelab-owned surfaces. |
+| T78-D6 | Tmux and fleet-comms remain temporary communications adapters behind a transport-neutral CLI contract.                                                                         |
+| T78-D7 | Decommissioning is phased and mechanically enforced. Removal requires zero measured consumers and a discriminating planted-reference control.                                  |
+
+Derived security boundary:
+
+- `~/.mosaic/tools` is canonical working source during migration. It is not automatically trusted
+  runtime installation state.
+- Reviewed source is promoted into installed or packaged runtime artifacts.
+- A multi-writer brain-repository push must not silently replace credential-bearing executable code
+  used by every seat.
+
+## 4. Explicitly rejected alternatives
+
+| Alternative                                          | Rejection reason                                                                                       |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Separate Python CLI                                  | Creates a second contract, release path, and policy surface.                                           |
+| Public `mosaic tools <script>` passthrough           | Preserves script names and paths as the API instead of defining capabilities.                          |
+| CLI allowlists as the sandbox                        | Parser allowlists do not isolate files, credentials, processes, networks, or container control.        |
+| Execute the synced working tree as the final runtime | A brain push would become host-wide code execution authority.                                          |
+| Big-bang script rewrite and deletion                 | Mature queue, identity, credential, and uncertainty behavior would be changed without parity evidence. |
+| Tmux-shaped communications API                       | It would force future Matrix or native transports to preserve tmux concepts.                           |
+
+## 5. Terminology
+
+- **Central registry:** the schema-v1 `config.json` authority filed in issue `#1382`.
+- **Registry resolver:** the typed reader that validates and resolves central-registry values.
+- **Capability catalog:** the typed inventory of public capability identifiers and behavior. It is
+  not the central registry.
+- **Capability policy:** data that maps verified actor and lane identity to allowed capabilities and
+  scopes.
+- **Local adapter:** a temporary in-process or private-script implementation used before `mosaicd`
+  is available.
+- **Broker adapter:** the future client transport to `mosaicd` outside the seat container.
+- **Installed legacy tree:** `~/.config/mosaic/tools`.
+- **Canonical working source:** `~/.mosaic/tools` during the migration period.
+- **Runtime artifact:** reviewed package or installed bytes actually executed by a seat.
+
+## 6. Public CLI grammar
+
+### CLI-REQ-001: First-class command groups
+
+The official help surface MUST register domain groups directly:
+
+```text
+mosaic git ...
+mosaic comms ...
+mosaic ci ...
+```
+
+Future domains MAY include `infra`, `identity`, and other reviewed capability families. They MUST
+NOT appear through a generic script dispatcher.
+
+### CLI-REQ-002: Stable command shape
+
+New capability commands use this grammar:
+
+```text
+mosaic <domain> <resource> <verb> [target] [options]
+```
+
+The first pilot freezes these paths:
+
+```text
+mosaic git issue list
+mosaic git issue view <number>
+mosaic git issue comment <number> --input <path|->
+```
+
+Capability identifiers are independent from display text:
+
+| Command                    | Capability ID       | Class            |
+| -------------------------- | ------------------- | ---------------- |
+| `mosaic git issue list`    | `git.issue.list`    | read             |
+| `mosaic git issue view`    | `git.issue.view`    | read             |
+| `mosaic git issue comment` | `git.issue.comment` | bounded mutation |
+
+Renaming a command path does not silently rename its capability identifier. Either change requires a
+versioned compatibility decision.
+
+### CLI-REQ-003: Common targeting options
+
+The pilot supports:
+
+- `--instance <name>` for the configured provider instance.
+- `--repo <owner/name>` for the provider repository.
+- `--format <table|json>` for output selection.
+- `--correlation-id <id>` for a caller-supplied valid identifier. Omission generates one.
+- `--idempotency-key <key>` for mutations. Omission generates one and returns it.
+
+An instance may be inferred only when the registry has exactly one valid instance for that domain.
+A repository may be inferred only from a validated current repository declaration and an
+unambiguous canonical remote. Ambiguity fails closed and names the missing field.
+
+No public option forces local compatibility mode when policy selected broker mode. A caller cannot
+downgrade the execution boundary.
+
+### CLI-REQ-004: Mutation input
+
+`git.issue.comment` reads its body from `--input <path>` or stdin with `--input -`. The CLI MUST:
+
+1. reject a missing or empty body.
+2. apply a documented byte limit before provider access.
+3. never place the body in process arguments, diagnostics, or audit metadata.
+4. compute a body digest for read-back verification without exposing the body.
+5. avoid automatic retry after an uncertain provider mutation.
+
+### CLI-REQ-005: Structured result envelope
+
+JSON output uses one versioned envelope:
+
+```ts
+interface CapabilityResultV1<T> {
+  schemaVersion: 1;
+  capabilityId: string;
+  status: 'succeeded' | 'invalid' | 'denied' | 'failed' | 'uncertain' | 'unavailable';
+  executionMode: 'local-adapter' | 'mosaicd';
+  identityTrust: 'local-asserted' | 'runtime-verified';
+  correlationId: string;
+  idempotencyKey?: string;
+  target: Record<string, string | number | boolean | null>;
+  data?: T;
+  diagnostics: Array<{
+    code: string;
+    message: string;
+    field?: string;
+    retryable: boolean;
+  }>;
+  audit:
+    | { authority: 'mosaicd'; recorded: true; eventId: string }
+    | { authority: 'none'; recorded: false; localEventId?: string };
+}
+```
+
+`target` and `diagnostics` contain no credentials or unbounded provider body. Table output is a
+human view of the same result and cannot carry a different verdict.
+
+### CLI-REQ-006: Exit behavior
+
+| Exit | Meaning                                                                     |
+| ---: | --------------------------------------------------------------------------- |
+|    0 | `succeeded`                                                                 |
+|    2 | `invalid`: invalid input, invalid configuration, or unsupported schema      |
+|    3 | `denied` by capability or scope policy                                      |
+|    4 | `failed` with a confirmed non-success outcome                               |
+|    5 | `uncertain`, including a mutation whose provider result cannot be confirmed |
+|    6 | `unavailable`, including missing broker, credentials, or required adapter   |
+
+A provider HTTP success alone is insufficient. The adapter validates the expected response shape.
+A mutation that may have landed but lacks confirmation returns exit 5 and is never described as
+failed or safe to retry. For a provider-native idempotent mutation, manual reconciliation MAY retry
+the same key. For `uncertain-no-retry`, help directs the caller to a read-back check and forbids
+mutation retry.
+
+### CLI-REQ-007: Help and discovery
+
+The capability catalog generates or validates:
+
+- `mosaic --help` command-group listing.
+- group and command help.
+- stable capability identifiers.
+- machine-readable capability discovery.
+- documentation tables.
+- policy-generation inputs.
+- tests that reject undocumented public commands and orphaned capabilities.
+
+## 7. Central registry resolver
+
+### CFG-REQ-001: One distinct resolver
+
+Implement one exported resolver named `MosaicRegistryResolver` or another name explicitly approved
+in the contract review. It MUST NOT be named `ConfigService`. The existing
+`packages/mosaic/src/config/config-service.ts` exports `ConfigService` for SOUL, USER, and TOOLS
+content and remains a separate concern.
+
+### CFG-REQ-002: Frozen schema consumption
+
+The resolver consumes schema v1 from issue `#1382` without creating parallel keys. Every key is
+optional. The exact v1 surface is:
+
+- `$schema`, with the known marker `mosaic-config-v1`.
+- `mosaicHome`, reserved, null, and without a v1 consumer.
+- `brainHome`, default `~/.mosaic`.
+- `instances.gitea.<name>.url`.
+- `fleet.socket`.
+- `harnessConfig.pi.agentDir`.
+- `harnessConfig.claude.configDir`.
+- `harnessConfig.claude.secureStorageDir`.
+
+Credential values, model and effort defaults, and `fleet.rosterPath` are forbidden. A non-null
+`mosaicHome` value fails validation because v1 reserves the field without implementing relocation.
+An absent or null `$schema` is interpreted as v1, the exact `mosaic-config-v1` marker is accepted,
+and every other non-null marker fails before value resolution.
+
+Absent or null values select the framework default. A `~` path prefix expands at read time and is
+never rewritten into the user file. Unknown top-level and nested keys warn loudly and are ignored
+for rolling-version compatibility. Every warning and machine-readable diagnostic names the full
+ignored key path, so a typo is visible at every read.
+
+Fail-closed read behavior applies to invalid JSON, a failed C1 version check, a known key with an
+invalid type or value, and a present but empty or invalid override. An optional
+`mosaic registry validate` lint mode MAY reject unknown keys for operator validation, but the normal
+resolver read path does not. This top-level group is separate from the existing `mosaic config`
+commands backed by `ConfigService`.
+
+### CFG-REQ-003: Resolution precedence
+
+For each supported value, resolution follows exactly:
+
+1. the schema-defined `MOSAIC_<KEY>_OVERRIDE` environment override.
+2. validated `config.json` value.
+3. one centralized framework default, when the key defines a default.
+
+A present override always wins. An empty or invalid override fails and does not fall through to the
+file or default. `$schema` and reserved `mosaicHome` have no environment override. Consumed values
+use this collision-free mapping:
+
+| Registry key                            | Environment override                                       |
+| --------------------------------------- | ---------------------------------------------------------- |
+| `brainHome`                             | `MOSAIC_BRAIN_HOME_OVERRIDE`                               |
+| `fleet.socket`                          | `MOSAIC_FLEET_SOCKET_OVERRIDE`                             |
+| `harnessConfig.pi.agentDir`             | `MOSAIC_HARNESS_CONFIG_PI_AGENT_DIR_OVERRIDE`              |
+| `harnessConfig.claude.configDir`        | `MOSAIC_HARNESS_CONFIG_CLAUDE_CONFIG_DIR_OVERRIDE`         |
+| `harnessConfig.claude.secureStorageDir` | `MOSAIC_HARNESS_CONFIG_CLAUDE_SECURE_STORAGE_DIR_OVERRIDE` |
+| `instances.gitea.<name>.url`            | `MOSAIC_INSTANCES_GITEA_<NAME>_URL_OVERRIDE`               |
+
+Gitea instance names match `[a-z][a-z0-9-]*`. The override name uppercases the instance name and
+maps hyphen to underscore. Underscores are not valid in source instance names, so two valid names
+cannot flatten to the same override.
+
+A value without a valid result fails before adapter or provider access. Invalid known URLs, socket
+names, paths, and value types fail closed. Unknown keys follow CFG-REQ-002.
+
+### CFG-REQ-004: Typed provenance
+
+Every resolved value carries non-secret provenance:
+
+```ts
+type RegistryValueSource = 'override' | 'registry' | 'framework-default';
+
+interface ResolvedRegistryValue<T> {
+  key: string;
+  value: T;
+  source: RegistryValueSource;
+  schemaVersion: 1;
+}
+```
+
+Machine-readable diagnostics include the full path of every ignored unknown key. Diagnostics may
+name a known key and source class. They do not emit credential values or unrelated configuration.
+
+### CFG-REQ-005: Bootstrap and path safety
+
+Registry discovery is the fixed path `~/.config/mosaic/config.json`. It has no v1 search path and no
+alternate location. The file is the one user-updatable path inside `~/.config/mosaic` and is
+protected by a deny-wins upgrade carve-out. Upgrades never overwrite user edits.
+
+This fixed bootstrap avoids circular dependence on reserved `mosaicHome`. A seat container reads its
+own internal `~/.config/mosaic/config.json`, supplied by the container topology, rather than a host
+path or a relocation flag. Path values are expanded, normalized, validated, and tested under at
+least two distinct home roots.
+
+No command embeds home directories, script locations, provider endpoints, seat paths, or tmux socket
+names outside the resolver and its reviewed defaults.
+
+### CFG-REQ-006: Schema evolution
+
+A new key requires:
+
+1. a named consumer.
+2. a `#1382` schema amendment.
+3. joint ACK from the frozen-schema and resolver-contract custodians until handoff, recorded by
+   custodian-authored commits rather than relayed tokens alone.
+4. parser, invalid-input, default, and two-root tests.
+5. documentation in the same reviewed change.
+
+Speculative keys are forbidden.
+
+### CFG-REQ-007: Joint freeze evidence
+
+The v1 resolver contract is jointly frozen:
+
+- Fred, frozen-schema custodian, accepted C1 and C3 through token
+  `CLI-T78-REGISTRY-FREEZE ACCEPT`, then accepted amended C2 through token
+  `CLI-T78-REGISTRY-C2 ACCEPT`.
+- Homelab `orch-01`, issue and resolver-contract custodian, accepted C1 and C3 and supplied the
+  adopted C2 rolling-version amendment in the fleet-comms repository, message
+  `sites/usc/20260827T004509Z__to-vision__from-homelab.orch-01__683e4c.md`, blob
+  `35a7c4c1e54eb9196abeef3135d211ee1dfc46db`.
+
+Durable lane provenance is recorded in the Mosaic brain repository at
+`fleet/lanes/cli-migration/registry-freeze-evidence.md` and the independent custodian-authored
+`fleet/lanes/cli-migration/registry-freeze-fred-ack.md`. Schema evolution after this freeze still
+follows CFG-REQ-006.
+
+## 8. Capability catalog and policy
+
+### CAP-REQ-001: One typed catalog
+
+Each capability definition records:
+
+```ts
+type CapabilityEffect = 'read' | 'bounded-mutation' | 'privileged-mutation';
+
+interface CapabilityDefinitionV1 {
+  id: string;
+  commandPath: readonly string[];
+  effect: CapabilityEffect;
+  targetSchema: string;
+  inputSchema: string;
+  outputSchema: string;
+  credentialClass: string | null;
+  requiredScopes: readonly string[];
+  auditRequired: boolean;
+  timeoutMs: number;
+  idempotency: 'read' | 'required-key' | 'provider-native' | 'uncertain-no-retry';
+  adapterId: string;
+  deprecation: 'active' | 'deprecated' | 'removed';
+}
+```
+
+The catalog is data consumed by the parser, help, policy, documentation, and tests. Command handlers
+must not maintain independent copies of these facts.
+
+### CAP-REQ-002: Policy is not parser logic
+
+Capability grants map verified actor identity and lane to capability IDs and resource scopes. They
+are data. A named seat receives no authority from its name alone.
+
+The user-editable central registry is placement and endpoint configuration, not authorization
+policy. It MUST NOT contain lane grants or let a seat self-grant capability scope. Target authority
+lives in the `mosaicd` control-plane store outside seat containers and returns a policy revision and
+digest with every decision.
+
+Before `mosaicd`, local compatibility mode may evaluate a package-owned policy for behavior and test
+parity, but it reports locally asserted identity and makes no broker-grade authorization claim. Mode
+selection is declared by topology and policy, never inferred from broker availability. A missing or
+unhealthy required broker returns `unavailable`. It never falls back to local mode.
+
+A capability using a shared, service, operator, or admin credential is broker-only. Local mode may
+use only the acting seat's own credential against a registry endpoint. Privileged infrastructure,
+merge, deployment, identity, authorization, and secret-management cutover requires `mosaicd`. A
+future policy-store key or broker endpoint still requires CFG-REQ-006 and the `mosaicd` topology
+contract.
+
+### CAP-REQ-003: Identity trust
+
+CLI arguments and ordinary environment variables are actor hints, not authorization identity. The
+local adapter reports that identity is locally asserted and MUST NOT claim broker-grade
+authorization. `mosaicd` derives or verifies actor identity from the authenticated seat runtime.
+
+### CAP-REQ-004: Positive and denied controls
+
+Every capability test includes:
+
+1. an allowed request with expected result.
+2. a denied request differing only in the relevant lane or scope.
+3. a malformed target or configuration denial.
+4. a credential-redaction assertion.
+5. a verdict-discrimination control that proves the test can fail.
+
+## 9. Adapter and broker contract
+
+### EXE-REQ-001: One capability request
+
+```ts
+interface CapabilityRequestV1 {
+  schemaVersion: 1;
+  capabilityId: string;
+  actorHint?: { seat?: string; lane?: string };
+  target: Record<string, string | number | boolean | null>;
+  arguments: Record<string, string | number | boolean | null>;
+  correlationId: string;
+  idempotencyKey?: string;
+}
+```
+
+Credential values and unbounded comment bodies are not serialized into audit-safe request metadata.
+Body content travels through a bounded private input channel appropriate to the adapter.
+
+### EXE-REQ-002: Local compatibility adapter
+
+The local adapter MAY call a reviewed in-process implementation or a private script adapter. It
+MUST preserve existing queue guards, wrapper-first behavior, credential resolution, response
+validation, and mutation uncertainty. It reports `executionMode: local-adapter` and
+`identityTrust: local-asserted`.
+
+Private child adapters receive bodies and credentials only through stdin, owner-only temporary
+files, or inherited file descriptors, never child-process arguments. Captured child stderr, shell
+trace, and diagnostics are inside the redaction boundary. Local results always use
+`audit: { authority: 'none', recorded: false }`. A local event identifier is not authoritative
+audit evidence.
+
+The local adapter is compatibility, not a sandbox or authorization claim.
+
+### EXE-REQ-003: `mosaicd` broker adapter
+
+The broker adapter sends the same logical request to `mosaicd` outside the seat container.
+`mosaicd` owns:
+
+- authoritative seat identity, recorded in audit from the derived runtime identity rather than
+  `actorHint`.
+- capability and scope authorization.
+- credential resolution.
+- operation execution.
+- output sanitization.
+- audit persistence.
+- bounded timeout and cancellation behavior.
+
+A contradictory `actorHint` produces a diagnostic and never replaces the derived actor. Broker
+results report `identityTrust: runtime-verified`. `audit.recorded: true` is valid only after
+`mosaicd` confirms persistence and returns its event ID. Consumers verify authoritative evidence
+against the broker trail, not the seat-produced envelope alone.
+
+The transport and endpoint are supplied by immutable container topology and the reviewed central
+registry contract. No command hard-codes a daemon socket.
+
+### EXE-REQ-004: Packaged implementation boundary
+
+The initial TypeScript layout is:
+
+- `packages/mosaic/src/central-registry/` for `MosaicRegistryResolver`, schema, and provenance.
+- `packages/mosaic/src/capabilities/` for catalog, request, result, policy interfaces, and tests.
+- `packages/mosaic/src/capabilities/adapters/local/` for temporary local adapter modules.
+- `packages/mosaic/src/capabilities/adapters/mosaicd/` for the broker client seam.
+- `packages/mosaic/src/commands/git.ts`, with later first-class domain files following the same
+  command pattern.
+
+Remaining script implementations may be promoted under `packages/mosaic/framework/tools/` as
+private packaged adapters during transition. Their installed paths are resolver-owned and are not
+public command contracts. No production adapter imports or executes source from the brain working
+tree as the final path.
+
+### EXE-REQ-005: Container boundary
+
+The representative seat container has:
+
+- one seat identity.
+- rootless execution.
+- read-only root filesystem, with explicit bounded writable mounts.
+- a read-only internal `~/.config/mosaic/config.json` supplied by topology.
+- no host credential tree.
+- no shared host or fleet tmux socket.
+- a dedicated per-seat tmux socket only for one named, reviewed temporary adapter with a stated
+  removal stage.
+- no Docker, Podman, or other container-runtime socket.
+- no installed legacy tool tree mount.
+- network access limited to declared capability paths.
+
+Container implementation is outside this mission. Contract and compatibility tests are inside it.
+
+## 10. Communications portability
+
+### COM-REQ-001: Transport-neutral public contract
+
+Public communications capabilities use logical addresses, messages, correlation IDs, delivery
+status, and adapter diagnostics. Tmux pane, socket, retry, and draft details stay below the public
+contract.
+
+### COM-REQ-002: Transitional semantics
+
+The tmux adapter preserves the measured `rc=2` behavior: content reached a pane as a draft, so the
+operation is not retried automatically. Fleet-comms preserves durable cross-site message identity
+and acknowledgment behavior.
+
+### COM-REQ-003: Future transport replacement
+
+A Matrix or native transport implementation passes the same contract tests. Callers do not change
+command paths, capability IDs, or result interpretation when the adapter changes.
+
+## 11. Canonical source and runtime integrity
+
+### SRC-REQ-001: Reviewed baseline
+
+The F11 baseline is commit `5be5825`. Inventory report `585f214`, code review `3fe8de7`, and
+security review `e270098` are the M0 evidence. Both reviews found no blocker.
+
+### SRC-REQ-002: Required M1 corrections
+
+Before expanding direct execution from the working tree:
+
+1. fix the `check-helper-drift.sh` environment assignment that suppresses version diagnostics.
+2. strip 20 dangling Excalidraw `node_modules` symlinks.
+3. add `tools/**/node_modules/` to the brain `.gitignore`.
+4. keep the reviewed `package-lock.json` as the reproducible dependency contract.
+5. correct the baseline report's misleading path-count headline.
+6. move `ci-publish-watch.sh` credential headers from process arguments to curl stdin
+   configuration when that suite is changed.
+
+### SRC-REQ-003: Source is not installation
+
+Runtime code is loaded from reviewed package or installed artifacts, not directly from a mutable
+multi-writer checkout as the final design. Any transitional direct execution requires:
+
+- a protected-path review rule.
+- an accepted digest anchored outside the synced tree in reviewed package metadata or Stack source.
+- verification before execution, including every credential-helper invocation.
+- a periodic verifier whose mismatch alert reaches a human.
+- a stated removal point.
+
+### SRC-REQ-004: Credential helper integrity
+
+The host-wide git credential helper and its accepted pin cannot be replaceable by the same synced
+commit. Transition requires an independently anchored verifier and alert. Final state moves the
+helper into the reviewed runtime installation or another explicitly protected location.
+
+## 12. Migration and decommission
+
+### MIG-REQ-001: Consumer census
+
+Inventory every direct caller of `~/.config/mosaic/tools`, grouped as:
+
+- skills and guides.
+- hooks and generated harness configuration.
+- systemd units and timers.
+- launchers and provisioning.
+- tests and CI.
+- direct agent commands.
+- private tool-to-tool calls.
+- production consumers.
+
+Each census run creates a fresh randomized planted legacy reference at a unique path and is valid
+only when the detector reports that run's exact plant. Every host at every site still running the
+installed legacy tree is censused independently. An empty result without the fresh control, or a
+zero from only one host, is not evidence.
+
+### MIG-REQ-002: Risk-ordered waves
+
+Migrate in this order:
+
+1. read-only status, health, list, and view.
+2. bounded CI and communications.
+3. issue, pull-request, and milestone mutation.
+4. credentialed infrastructure.
+5. merge, deployment, identity, authorization, and secret management.
+
+Each wave proves contract parity before consumer cutover. Waves 1 through 3 may use local mode with
+acting-seat credentials. Wave 4 cutover is broker-only when it uses a shared or service credential.
+Wave 5 cutover is always broker-only and begins only after the M6 `mosaicd` boundary gate passes.
+
+### MIG-REQ-003: Protected consumers
+
+- M365 credentials, AD status, and six production consumers remain Peggy-owned until exact signoff
+  and timer-aware tests.
+- Fleet-doctor, seat-service, Woodpecker extras, and their units remain Veronica-owned until exact
+  replacement proof and named handoff.
+- Brain guards are excluded from wholesale removal.
+- The active A2 hold applies to `tools/seat-service/` and
+  `fleet/bin/launch-seat-claude.sh` only.
+- Fleet configuration issue `#758` retains its own normative contract and delivery DAG. T78 does
+  not re-scope or absorb its missing `inspect` and `validate` verbs. T78 measures and consumes the
+  stable fleet surface only after `#758` completion or an explicit owner handoff.
+
+### MIG-REQ-004: Compatibility and deprecation
+
+Compatibility shims are private and time-bounded. Each shim:
+
+- names its public replacement.
+- preserves existing safety behavior.
+- emits a machine-detectable deprecation diagnostic without corrupting JSON output.
+- has a measured consumer and removal issue.
+- cannot be used to add new direct callers.
+
+### MIG-REQ-005: Final removal
+
+The installed `~/.config/mosaic/tools` script surface is removed only after:
+
+1. all active consumers use official capabilities.
+2. the census reports zero with a firing planted control.
+3. Constitution and wrapper-first gates are mechanically enforced by the CLI path.
+4. systemd units are regenerated, daemon-reloaded, re-enabled, and behavior-tested.
+5. fleet-doctor state is preserved.
+6. clean install, upgrade, rollback, and stale-install tests pass.
+7. user, admin, developer, API, and migration documentation is current.
+
+## 13. Testing requirements
+
+### TST-REQ-001: Resolver
+
+- exact schema-v1 valid fixture.
+- absent, null, exact-v1, and unknown-non-null `$schema` cases.
+- unknown top-level and nested key warnings with full-path diagnostics.
+- `mosaic registry validate` lint rejection of the same unknown-key fixture.
+- invalid URL, path, socket, and type failures.
+- every precedence branch, including present-empty and present-invalid override denial without
+  fallback.
+- two valid roots.
+- container topology with a read-only internal registry and no host registry path.
+- no credential value accepted or emitted.
+- control proving the invalid fixture fails.
+
+### TST-REQ-002: Capability catalog
+
+- command and capability ID uniqueness.
+- every public command documented.
+- no orphan catalog record.
+- parser, policy, help, and docs consume the same definition.
+- unauthorized lane and scope denial.
+- unknown capability denial.
+- topology-selected mode never falls back when the required broker is unavailable.
+- shared, service, operator, and admin credential classes reject local mode.
+
+### TST-REQ-003: Pilot
+
+- issue list and view against a valid configured instance.
+- invalid instance and repository denial.
+- comment success with provider response-shape and body-digest confirmation.
+- comment denial before provider access.
+- post-request uncertainty without retry, plus provider-native same-key and
+  `uncertain-no-retry` read-back reconciliation cases.
+- credential, cookie, token, comment-body, child-argv, captured-stderr, and shell-trace redaction.
+- local results prove `identityTrust: local-asserted` and `audit.recorded: false`.
+- broker-stub results prove derived-identity precedence and reject unconfirmed
+  `audit.recorded: true`.
+- user-editable endpoint changes cannot redirect a shared or service credential.
+- local-adapter and broker-stub request/result seam parity at M3.
+- live local-adapter and `mosaicd` contract parity at M6.
+
+### TST-REQ-004: Migration
+
+- fresh randomized consumer-census plant detected independently on every affected host and site.
+- compatibility diagnostics in table and JSON modes.
+- systemd timer and restart behavior.
+- production M365/AD consumer probes.
+- fleet-doctor digest-state preservation.
+- clean install, upgrade, rollback, stale install, and greenfield operation.
+- representative container without legacy tools mounted.
+- representative container mounts no shared or fleet tmux socket, and any temporary tmux exception
+  uses only the named adapter's dedicated per-seat socket.
+
+### TST-REQ-005: Delivery gates
+
+Every source card requires focused tests, repository quality gates, independent code review,
+security review for authorization, credentials, transport, or integrity surfaces, reviewed squash
+PR to `next`, terminal-green CI, and linked-issue closure.
+
+## 14. Documentation requirements
+
+The workstream updates in the same delivery sequence:
+
+- official CLI help.
+- `docs/PRD.md` workstream pointer.
+- `docs/ROADMAP.md` parallel-track entry.
+- `docs/SITEMAP.md` requirements link.
+- user guide commands and deprecation behavior.
+- administrator configuration, migration, and recovery.
+- developer architecture, capability authoring, schemas, and adapter contracts.
+- API and machine-readable result schemas.
+- release notes.
+- T78 program-map and unified-roadmap records.
+
+No command is public until its help, structured output, authorization behavior, and documentation
+are present.
+
+## 15. Delivery stages
+
+| Stage | Scope                                                                                                                          | Exit gate                                                                      |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| M0    | Register mission, reconcile ownership, establish and review source baseline, publish requirements and tracking                 | Reviewed contract merged, dedicated milestone and task graph present           |
+| M1    | Inventory consumers, normalize baseline, freeze registry resolver, capability catalog, policy, and runtime-integrity contracts | Typed interfaces and migration census reviewed                                 |
+| M2    | Implement resolver, catalog, common result envelope, and adapter interface                                                     | Contract and two-root tests green                                              |
+| M3    | Deliver pilot issue list, view, and comment                                                                                    | Allowed and denied controls, uncertainty behavior, docs, review, CI            |
+| M4    | Migrate waves 1 through 3, prepare wave 4 private adapters without shared-credential cutover                                   | Per-suite owner handoff and parity evidence                                    |
+| M5    | Cut eligible consumers and generate harness policy                                                                             | No new direct references, compatibility callers measured                       |
+| M6    | Prove representative container and `mosaicd` seam, then cut over shared-credential wave 4 and all wave 5 capabilities          | Boundary, authorization, audit, and parity tests green                         |
+| M7    | Remove installed legacy script tree                                                                                            | Zero callers, migration and rollback evidence, docs and release gates complete |
+
+## 16. Workstream acceptance
+
+T78 completes only when:
+
+1. the official TypeScript CLI exposes documented first-class capability groups.
+2. the central registry resolver and capability catalog are single typed authorities.
+3. two-root and container-topology tests prove no command-path hard-coding.
+4. authorization has allowed and denied situational evidence.
+5. agent-visible output, logs, and process arguments contain no credential values.
+6. local and `mosaicd` modes share one request and result contract and report their mode honestly.
+7. a representative rootless seat container performs granted operations without legacy tools,
+   host credentials, or a container-runtime socket.
+8. tmux and fleet-comms can be replaced without changing public communications callers.
+9. the legacy consumer census reaches zero with a discriminating control.
+10. the installed `~/.config/mosaic/tools` script surface is removed.
+11. independent review passes for every source partition.
+12. all PRs are squash-merged to `next`, terminal CI is green, and linked issues are closed.
+
+## 17. Contract-freeze status
+
+The architecture inputs are frozen for independent review:
+
+1. The central-registry resolver has joint C1, amended C2, and C3 approval.
+2. User-editable `config.json` is not authorization policy. Target grant authority belongs to
+   `mosaicd`. Local mode is explicitly non-authoritative.
+3. Registry, capability, and adapter source boundaries are packaged TypeScript modules. Brain tools
+   remain working source and temporary private adapters, not the final runtime contract.
+4. Issue `#758` remains an independent dependency and is not re-scoped into T78.
+
+Provider tracking remains operationally blocked until the `orch-01` Mosaic Stack credential slot is
+minted. This does not weaken the contract or authorize implementation before reviewed publication.

docs/requirements/hierarchy-schema.md

@@ -0,0 +1,484 @@
+# Hierarchy Schema Contract (D2)
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 1 of 9).
+Authority: PRD D2/D9/D13 (Part I §4) and the native-kanban SOT Amendment A1
+(`docs/requirements/native-kanban-sot.md` §8, ratified 2026-08-25). This
+document turns the ratified hierarchy into a concrete schema contract:
+tables, cardinalities, constraints, and ownership/transfer semantics. It is
+the prerequisite for the hierarchy command family and for the RBAC grant
+model (contract 2, `docs/requirements/rbac-grant-model.md`).
+
+Revision 2 (independent review, GPT-5.6 terra): tenancy-FK exemption made
+explicit (§1.1); record class extended to include `hierarchy_grants`
+(§1.1); provenance corrections on legacy tables and the planning `projects`
+table (§1.3, §2 naming note); NOT NULL and `NULLS NOT DISTINCT` grant
+uniqueness (§2.6, §3.2); grant FK delete actions split cascade/restrict
+(§3.3); transfer transaction includes its audit write (§4.3); ownership
+invariant completed via contract 2 with the both-sides rule marked as new
+policy (§4.2, §4.4); hierarchy audit brought under REQ-AUD-001-equivalent
+guarantees with deletion-safe linkage (§5.2); roll-up never-a-write restored
+to full A1 strength (§5.4); §6 rebuilt with bounded observables for every
+MUST (allowlist, command surface, audit, corrected cardinality witness).
+
+Revision 3 (terra re-review residuals): §4.3 transfer write inventory
+reconciled with §5.2 — the transaction's writes are the single class-row
+mutation plus that mutation's §5.2 audit writes (event + outbox record),
+not "exactly two writes"; §6.3 extended with a closed writer-coverage
+witness so an unregistered internal writer cannot pass a registered-route
+inventory. (Terra's finding-8 residual — a stale contract 2 §7.8 backlink
+to contract 1 §6.2 — was already fixed in contract 2 revision 2, which
+cites §6.5; measured against `origin/contract/rbac-grants` head
+`501112d2`.)
+
+Revision 4 (terra r3 residual F7): the §6.3(b) writer-coverage assertion
+extended to raw SQL — it now also fails on class-table name literals
+inside SQL strings or tagged SQL templates outside the allowlist, so a
+raw-SQL writer that touches no schema symbol is still caught.
+
+Revision 5 (terra r4 residual F7): §6.3(b) gains a third prong — any
+raw-SQL execution primitive outside the allowlist fails the assertion
+regardless of its SQL content, closing the evasion where a
+dynamically constructed table name carries neither a schema symbol nor
+a class-table literal. The detection claim is now coextensive with
+what the three prongs statically see.
+
+Revision 6 (terra r5 residual F7 + new F8): the "two prongs" wording
+corrected to three (F8); §6.3(b) gains the allowlist composition rules
+(no generic raw-SQL helper is allowlisted; an allowlisted module may
+not export caller-supplied-SQL execution) and fails outright on
+runtime code-construction primitives; the detection claim is scoped
+honestly to the stated syntactic forms, with evasions beyond static
+reach assigned to §5.1 review/audit rather than claimed for CI.
+
+Revision 7 (terra r6 new F9): the false-positive remedy no longer
+contradicts the composition rules — legitimate non-hierarchy raw
+execution (e.g. the db package's migration runner) is dispositioned
+onto a second closed enumerated list, the infrastructure register,
+exempt from prong (iii) only, still bound by prongs (i)/(ii), barred
+from the writer allowlist, and importable only by registered modules
+or the operational entry points.
+
+Revision 8 (terra r7 residual F9): the register's import rule made
+satisfiable by the live tree — imports are checked re-export-aware
+(package barrels followed), and each registered module carries its own
+closed importer enumeration, which may name operational entry points
+such as the Gateway's startup migration hook; named importers stay
+subject to prongs (i)/(ii) and gain no writer standing.
+
+Revision 9 (terra r8 F10): revision 8 called the Gateway database
+module the runner's "one live importer today". That was false — the
+measured production importer set has four members. The enumeration
+example now lists the complete measured set, and the import analysis
+is extended to resolve literal dynamic `import()` routes, which two of
+the four members use.
+
+Amendment 1 (Ruling 4b, 2026-08-28): company visibility classes. The
+directory exists so one shared company can serve many users instead of
+each user creating a duplicate private company (Ruling 4b, webui-audit
+lane, ruled 2026-08-27). §2.1 gains a `visibility` column; §2.8 defines
+the two classes (`private`/`directory`), the directory's existence-only
+disclosure, and the pre-binding invariants for the deferred
+see-and-ask-to-join flow (no join-request surface is authorized here —
+its flow is a follow-up contract); §5.2's mutation
+enumeration gains the visibility change; §5.5 defines who may change
+visibility (platform admins, plus a company-CRUD capability whose
+definition is a follow-up amendment to contract 2 — until it ratifies,
+admin-only); §6.1 and §6.9 add the witnesses; §6.7's existence-oracle
+rule is scoped around the ratified directory carve-out. Top-level
+creation (contract 3 §5.2) is unchanged and always yields a private
+company. Upstream, SOT Amendment A2 (native-kanban-sot.md §9, this PR)
+expressly extends A1 §8.1.2 to admit the visibility column and A1
+§8.1.3 to admit the directory function — this contract relies on that
+amendment, not on a reinterpretation of A1.
+
+Scope: the tenancy/authorization structure record class — companies,
+estates, platform-projects, workspaces, hierarchy grants, their parentage,
+and constraints. Out of scope: the RBAC grant vocabulary and evaluation
+semantics (contract 2), roll-up projection semantics (contract 8), kanban
+planning entities inside workspaces (SOT §5), migration or retirement of
+legacy flat data (future work; see §1.3).
+
+## 1. Record class and placement
+
+1. The **tenancy/authorization structure record class** defined by
+   Amendment A1 §8.1.2 comprises five tables: the four node tables of §2
+   AND `hierarchy_grants` (§3) — A1 includes hierarchy-level access grants
+   in the class. Every rule addressed to "the class" in this contract
+   (payload prohibition, mutation path, audit) binds all five tables. Class
+   rows carry parentage, naming, grant, audit-linkage, and visibility-class
+   data only — never task, plan, or any business/orchestration payload.
+   Visibility (`companies.visibility`, §2.8) is admitted into that
+   enumeration by SOT Amendment A2 §9.1.1, which expressly extends A1
+   §8.1.2 for exactly this one column: it is disclosure data about the
+   class's own nodes — not a payload field, carries no business content,
+   and widens the payload prohibition for nothing else.
+   References from business/orchestration rows into the class are limited
+   to exactly one form: the canonical `workspace_id` tenancy column that
+   REQ-TEN-001 requires on every canonical row, referencing
+   `workspaces.id`. No business/orchestration row may reference a company,
+   estate, platform-project, or grant id in any position, and no
+   business/orchestration row may reference a workspace id in any
+   non-tenancy position (dependency, claim target, work subject).
+2. Hierarchy records are NOT workspace-scoped rows: REQ-TEN-001's
+   `workspace_id` obligation binds business/orchestration rows and does not
+   apply to this class (A1 §8.1.2). The `workspaces` table itself is the
+   anchor the obligation points at.
+3. The legacy flat tables (`teams`, and the Brain planning `projects` table
+   in `packages/db/src/schema.ts`) are not part of this class. What A1
+   §8.1.4 pins is narrower: the planning `projects` table and
+   `platform_projects` stay distinct tables. This contract adds, as new
+   policy ratified here: neither `teams` nor `projects` is repurposed as a
+   hierarchy table. Their eventual migration or retirement is future work
+   that no existing REQ assigns; it is out of scope here.
+
+## 2. Tables and cardinalities
+
+Naming: the level above workspaces is `platform_projects`, per A1 §8.1.4.
+The existing `projects` table is Brain planning data (so labeled in
+`packages/db/src/schema.ts`; it carries no `workspace_id`), and the schema
+MUST NOT merge the two. (A rename of either remains an implementation-PR
+decision under A1; this contract pins only that they stay distinct tables.)
+
+1. `companies` — id (uuid pk), name, slug (unique per deployment),
+   `visibility` (text NOT NULL, DEFAULT `private`, CHECK constrained to
+   exactly `private` | `directory`; semantics §2.8), created_at,
+   updated_at. N per deployment (D2).
+2. `estates` — id, name, slug, `company_id` NOT NULL →
+   `companies.id` ON DELETE RESTRICT. Exactly one company per estate; a
+   company holds any number of estates.
+3. `platform_projects` — id, name, slug, `estate_id` NOT NULL →
+   `estates.id` ON DELETE RESTRICT. Exactly one estate per
+   platform-project; an estate holds any number of platform-projects.
+4. `workspaces` — id, name, slug, `platform_project_id` NOT NULL →
+   `platform_projects.id` ON DELETE RESTRICT. Exactly one platform-project
+   per workspace. This table is the referent of every `workspace_id` column
+   the SOT requires on canonical rows.
+5. **Chain resolution is by construction.** Because every parent FK is NOT
+   NULL and single-valued (one FK column, no parentage edge tables, no
+   multi-parent forms, no nullable "detached" states), each workspace
+   resolves to exactly one platform-project → estate → company chain (A1
+   §8.3 acceptance 1). One-parent-per-child is the constrained direction;
+   many children per parent is valid data.
+6. **Slug scoping.** All `name` and `slug` columns are NOT NULL.
+   `estates.slug` is unique within its company, `platform_projects.slug`
+   within its estate, `workspaces.slug` within its platform-project
+   (composite unique constraints). Display names are unconstrained beyond
+   NOT NULL.
+7. No hierarchy table carries a `metadata` jsonb column or any
+   free-form payload field. The columns declared in this section and §3
+   are exhaustive: a class table's column set is exactly its declared set
+   (verified per §6.2) — nothing else (A1 §8.1.2).
+8. **Company visibility classes (Ruling 4b).** Every company is exactly
+   one of two classes, carried by `visibility`:
+   - `private` (the default): the company is disclosed only to subjects
+     holding a grant on it or on a descendant — the resting state every
+     company is created in. Open creation under contract 3 §5.2
+     (Ruling 4) survives unchanged: it creates private companies.
+   - `directory`: the company is listed in the deployment-wide company
+     directory. Directory listing discloses **existence, name, and slug
+     to every authenticated user — nothing else**: no subtree structure,
+     no roll-up aggregates, no workspace content, no grant or membership
+     information.
+     Visibility is disclosure, not authority. Content and structure access
+     to a directory-listed company still require explicit grants —
+     contract 2 §3.1 deny-by-default is unchanged, and the ownership model
+     (§4.4, contract 2 §4.3) is unchanged. Ruling 4b decision 5 wants a
+     see-and-ask-to-join flow for directory-listed companies. **This
+     contract authorizes no join-request runtime surface**: the flow in
+     its entirety — the ability to submit a request, its transport,
+     storage, and request lifecycle — is a follow-up contract, and until
+     that contract ratifies, the directory's only function is the
+     read-only listing above (A2 §9.1.2 admits nothing more). Two
+     invariants pre-bind that future contract now:
+     a join request confers no authority of any kind, and approval is
+     ordinary grant creation by an effective `owner` under contract 2 §4.1
+     — there is no other acceptance path.
+
+## 3. Grant attachment points
+
+The grant vocabulary (which roles exist, what each permits, how evaluation
+and revocation work) is contract 2. This contract pins only the schema
+shape contract 2 attaches to:
+
+1. `hierarchy_grants` — id, subject (exactly one of `user_id` → `users.id`,
+   `team_id` → `teams.id`; CHECK-enforced exactly-one-of), target (exactly
+   one of `company_id`, `estate_id`, `platform_project_id`;
+   CHECK-enforced exactly-one-of), `role` (text NOT NULL; vocabulary and
+   its CHECK constraint owned by contract 2 §2), `granted_by` NOT NULL →
+   `users.id`, created_at.
+2. Uniqueness: at most one grant row per (subject, target, role). Because
+   the subject and target columns are nullable by design, ordinary
+   PostgreSQL composite uniqueness treats NULLs as distinct and would not
+   enforce this. The implementation MUST use a single
+   `UNIQUE NULLS NOT DISTINCT` constraint across (`user_id`, `team_id`,
+   `company_id`, `estate_id`, `platform_project_id`, `role`) or six
+   equivalent partial unique indexes (one per subject×target form). The
+   pinned Drizzle ORM supports `nullsNotDistinct()`.
+3. Delete actions are split by column class:
+   - Target FKs (`company_id`, `estate_id`, `platform_project_id`):
+     ON DELETE CASCADE — the one permitted cascade in this class. A grant
+     on a deleted node is meaningless and fail-open if retained. Cascaded
+     grant deletions are audited per §5.2.
+   - Principal FKs (`user_id`, `team_id`, `granted_by`): ON DELETE
+     RESTRICT. The identity contract (§7.3) gates user deletion today and
+     defines no team-deletion rule; this contract does not invent one.
+     These FKs stay RESTRICT until an explicit deletion-and-retention
+     contract ratifies otherwise.
+4. Workspace-level access is evaluated, not stored here: a grant at any of
+   the three levels evaluates down the chain to workspace-scoped
+   authorization (A1 §8.1.3). No `workspace_id` column exists on
+   `hierarchy_grants` — workspace membership (REQ-ID-001) remains its own
+   mechanism inside the SOT schema, and the chain adds where grants can be
+   declared, never a bypass.
+
+## 4. Ownership and transfer
+
+"Assets are transferable subject to the structure" (PRD Part I §4):
+
+1. A transfer changes exactly one parent FK on exactly one hierarchy row:
+   workspace → new platform-project, platform-project → new estate, estate
+   → new company. Nothing else in the class or the SOT changes: business
+   and orchestration rows inside affected workspaces are untouched, keep
+   their `workspace_id`, and never cross a workspace boundary (A1 §8.1.3
+   "chain maintenance").
+2. Transfer authorization requires authority over BOTH the source and the
+   destination parent. This both-sides predicate is **new policy
+   introduced by this contract pair** (D2/A1 do not state it); its
+   evaluation semantics are contract 2 §5. The structural half — that the
+   transfer command evaluates it before mutating — binds here.
+3. A transfer transaction mutates exactly one class-table row — the
+   single-row parent-FK update — and contains, beyond that, only the
+   §5.2 audit writes for that mutation (the audit event and its
+   hierarchy-outbox record, committing in the same transaction). No other
+   class, business, or orchestration row changes. There are no multi-row
+   transfer batches at the schema level; bulk moves are N audited
+   transfers.
+4. Hierarchy records have no `owner_id`. Ownership in the hierarchy IS the
+   grant structure: a "company owner" is a subject with an `owner` grant
+   on that company or an ancestor (contract 2 §2), not a column. The
+   ownership invariant across the contract pair: a node may hold zero
+   direct owner grants (authority can derive from an ancestor grant); node
+   creation names the initial `owner` grant in the same audited operation
+   and the wizard seeds the first company's owner the same way (contract 2
+   §4.3); transfer and revocation semantics are contract 2 §§5–6. This
+   avoids column-encoded authority of the kind the legacy schema carries
+   (`teams.owner_id` and `teams.manager_id` are required user FKs, and
+   `team_members.role` is a further authority field — none of them
+   evaluable under a grant model).
+
+## 5. Mutation path, audit, and deletion
+
+1. All hierarchy mutations flow through the same sole-writable-SOT,
+   fail-closed, audited Gateway command path as everything else (A1 §8.2.3,
+   REQ-API-001). No direct-DB writers, no raw CRUD endpoints.
+2. **Audit parity.** A1 §8.2 leaves every pre-existing REQ binding, so
+   hierarchy mutations get REQ-AUD-001's guarantees, not a weakened
+   substitute. Concretely:
+   - Every create, rename, transfer, visibility change (§5.5), grant
+     create/change/revoke, and
+     delete — including every grant deletion cascaded by a node delete —
+     emits a semantic audit event carrying actor, verb, target, and (for
+     transfers) source and destination parents, with the correlation,
+     causation, idempotency, and per-target ordering guarantees REQ-AUD-001
+     defines.
+   - The state change and its audit event(s) commit in the same
+     transaction, delivered through a transactional outbox. Hierarchy
+     events are not workspace-scoped rows and do not ride the workspace
+     outbox; they get an equivalent hierarchy outbox under the same
+     append-only, same-transaction rules.
+   - **Deletion-safe linkage:** audit events reference their target by an
+     immutable snapshot (id, slug, and parent chain at event time), never
+     by a foreign key into the class tables, so append-only events survive
+     the deletion of their target.
+3. Deletion is fail-closed bottom-up: a hierarchy record with children
+   cannot be deleted (RESTRICT FKs, §2). Deleting a workspace is a SOT-side
+   operation subject to the kanban SOT's own rules and is not granted any
+   new semantics by this contract.
+4. **Roll-up is never a write** (A1 §8.2.2, preserved at full strength). A
+   roll-up read mutates nothing — not hierarchy state, and not business or
+   orchestration state: it must not mutate, claim, order, or gate
+   workspace work. Contract 8 owns projection details but cannot narrow
+   this rule. This contract additionally guarantees the chain roll-ups
+   aggregate over is unique and non-null (§2.5).
+5. **Visibility administration (Ruling 4b decisions 2–3).** Changing
+   `companies.visibility` is a hierarchy mutation through the §5.1
+   command path, audited per §5.2 (the event carries the old and new
+   visibility values as its semantic content). It is authorized for
+   exactly two actor classes: platform admins (`users.role = 'admin'`)
+   and subjects holding the company-CRUD capability that a follow-up
+   amendment to contract 2 will define — until that amendment ratifies,
+   the capability class is empty and the command is admin-only.
+   A company `owner` as such may NOT change visibility: standard users
+   cannot publish a company into the directory. This is the one
+   hierarchy mutation a platform admin performs without holding a
+   hierarchy grant, and it is ratified here as instance administration
+   (directory curation) in contract 2 §1.1's sense, not tenant access:
+   the command mutates the single `visibility` column, reads no tenant
+   content, and confers no grant — contract 2 §1.1's
+   no-implicit-tenant-access rule is otherwise untouched. Top-level
+   company creation (contract 3 §5.2) always creates
+   `visibility = 'private'`; the creation command cannot set or change
+   visibility.
+
+## 6. Verification requirements
+
+Binding on the implementing PRs (extends A1 §8.3):
+
+1. Schema witnesses (real PostgreSQL, §6.8): chain construction — insert
+   with a null parent FK refused; insert with one valid parent accepted;
+   two siblings under one parent accepted (the control proving the
+   constraint rejects only what §2.5 forbids); catalog assertion that each
+   child table has exactly one parent-FK column and no parentage edge
+   table exists. Composite slug uniqueness per parent (duplicate slug
+   under same parent refused; same slug under different parents accepted).
+   Grant CHECKs: exactly-one-of subject and exactly-one-of target each
+   witnessed (zero and two set → refused). Grant uniqueness: a duplicate
+   (subject, target, role) row refused for each of the six subject×target
+   forms, proving NULLS-NOT-DISTINCT semantics; NOT NULL on `role`,
+   `granted_by`, and all `name`/`slug` columns witnessed. Company
+   visibility (§2.8): a value outside `private`/`directory` refused with
+   both valid values accepted as the control; an insert omitting the
+   column defaults to `private`.
+2. Column allowlist: an information_schema assertion that each class
+   table's column set is exactly the set declared in §2/§3 — the bounded
+   observable for no-payload (§2.7) and no-`owner_id` (§4.4).
+3. Command surface: two witnesses, both required (§5.1). (a) Route
+   inventory: an assertion over the Gateway's registered hierarchy
+   routes/commands proving the registered mutation surface is exactly the
+   declared hierarchy command family — no generic CRUD endpoint. (b)
+   Writer coverage — the closed allowlist a route inventory cannot
+   provide: a static CI assertion over the Gateway and package sources
+   with three prongs, each bound to one explicitly enumerated allowlist
+   of hierarchy command/repository modules. (i) Symbol prong: write
+   references to the class-table schema symbols (insert, update, delete)
+   occur only in allowlisted modules. (ii) Literal prong: a class-table
+   name appearing inside a SQL string or tagged SQL template outside the
+   allowlist fails the assertion — this is what catches a raw-SQL writer
+   that references no schema symbol. (iii) Raw-execution prong: any call
+   to a raw-SQL execution primitive (the ORM's raw/unsafe constructors,
+   driver-level query/execute) outside the allowlist fails the
+   assertion, regardless of what the SQL string contains or how it is
+   constructed — the call site is statically detectable even when a
+   dynamically assembled table name is not, so a raw writer with a
+   runtime-built identifier is caught by its primitive, not its
+   payload. Two composition rules keep prong (iii) meaningful: the
+   allowlist names hierarchy command/repository modules only — a
+   generic raw-SQL helper or database-utility module is never
+   allowlisted; and an allowlisted module MUST NOT export a function
+   that executes caller-supplied SQL (such an export is itself a
+   raw-execution primitive, and the exporting module is treated as
+   unallowlisted for prong (iii) if it does). Legitimate raw execution
+   that is not a hierarchy writer — e.g. the migration runner in the
+   db package — lives on a second, separately enumerated
+   **infrastructure register**, distinct from the writer allowlist and
+   equally closed. A registered module is exempt from prong (iii) only:
+   prongs (i) and (ii) apply to it with no exemption, so it can hold no
+   class-table schema symbol or class-table SQL literal, and it can
+   never appear on the writer allowlist. To close the laundering path,
+   the same assertion checks imports, and the import analysis is
+   **re-export-aware**: it follows package barrels and re-exports, so a
+   route hidden behind an index module is still a route — and it
+   resolves literal dynamic imports the same way: an
+   `await import('<literal specifier>')` is an import edge like any
+   static import, not an evasion of the analysis (a dynamic import of
+   the db package whose specifier is not a literal fails the assertion
+   outright, because it makes the import graph unanalyzable). A
+   registered module may be imported only by other registered modules
+   or by importers named on that module's own closed importer
+   enumeration in the register — operational entry points such as the
+   migration/bootstrap CLI or the Gateway's startup migration hook.
+   The enumeration names the complete permitted production consumer
+   set, and completeness is measured, not asserted: the migration
+   runner's measured production importer set today has four members —
+   the Gateway database module (reached through the db package
+   barrel), the storage package's Postgres adapter, and two mosaic CLI
+   commands, the fleet-backlog command and the gateway verify command,
+   both routed through literal dynamic imports of the db package — so
+   its enumeration names those four. A module that only receives the
+   runner's functions by parameter injection (the gateway schema-check
+   module takes them as arguments from the verify command) has no
+   import edge of its own and is not enumerated. Any import route
+   outside the enumeration fails the assertion. Being a
+   named importer confers nothing else: the importer stays fully
+   subject to prongs (i) and (ii), gains no writer-allowlist standing,
+   and whether it uses the registered module beyond its operational
+   purpose is a §5.1 review question, not a static claim. Runtime code-construction
+   primitives (`eval`, `new Function`) anywhere in the scanned sources
+   fail the assertion outright, allowlist or not. Schema definitions
+   and generated migrations are excluded from the literal prong; a
+   false positive is resolved in the same PR by adding the module to
+   the one enumerated list its role permits — the writer allowlist for
+   a hierarchy command/repository module, the infrastructure register
+   for non-hierarchy raw execution — never by weakening the assertion,
+   and neither list may take a module the composition rules bar from
+   it. Both lists are closed, and the assertion's detection
+   claim is exactly its prongs: it statically surfaces every writer
+   expressed as a schema-symbol reference, a class-table SQL literal, a
+   raw-execution call site, or runtime code construction. An evasion
+   engineered outside those syntactic forms is a §5.1 violation that
+   review and audit own — the witness does not claim to catch what
+   static analysis cannot see, and any such evasion found later is
+   corrected as a conformance defect, not grandfathered.
+4. Audit witnesses: for each mutation class (create, rename, transfer,
+   visibility change, grant create/change/revoke, delete) — the event
+   exists after commit
+   with actor/verb/target and same-transaction atomicity, and the
+   event's outbox record exists after the same commit — state row,
+   audit event, and outbox record are witnessed as one transaction
+   (REQ-AUD-001); a rolled-back
+   mutation leaves no event, no outbox record, AND no state effect —
+   a rolled-back create leaves no row, a rolled-back rename, transfer,
+   or visibility change leaves the prior values in place, and a
+   rolled-back delete or grant revoke leaves the row present
+   (rollback witness on all three legs, per REQ-AUD-001's
+   commit-or-roll-back-together acceptance); a
+   node delete's cascaded
+   grant deletions are each covered by events; events survive deletion of
+   their target (query the events of a deleted node).
+5. Transfer tests: parent-FK update moves the subtree resolution and
+   modifies zero business/orchestration rows (row-count and content
+   assertions on workspace contents before/after); transfer without
+   authority on the source or on the destination side is refused (with
+   contract 2 §7.8).
+6. Deletion tests: delete with children refused at the database level;
+   delete of a leaf cascades its grants and nothing else; deleting a user
+   or team that is a grant subject (or `granted_by` referent) is refused
+   (RESTRICT witnesses for §3.3).
+7. Negative tests: no business/orchestration table accepts a company,
+   estate, platform-project, or grant id in any reference position, and
+   none accepts a workspace id in any non-tenancy position; the canonical
+   tenancy FK control — a business row inserted with a valid
+   `workspace_id` succeeds, with an invalid one is refused; roll-up
+   endpoints mutate no canonical state anywhere (assert zero writes across
+   hierarchy AND workspace tables, not hierarchy only); readers see
+   aggregates only over workspaces they are authorized on, with no
+   cross-tenant existence oracles (A1 §8.3 acceptance 3, as narrowed by
+   A2 §9.1.2) beyond the one
+   ratified carve-out — the §2.8 company directory, witnessed in §6.9.
+8. Real-PostgreSQL coverage for every constraint witness (unique/CHECK/
+   RESTRICT/NULLS NOT DISTINCT behavior), using the `ci-postgres` service
+   in the `test` CI step; mocked specs cannot witness database constraints.
+9. Visibility witnesses (§2.8, §5.5): the directory read returns exactly
+   the `visibility = 'directory'` companies to any authenticated user,
+   disclosing existence, name, and slug only (closed-field assertion on
+   the response shape); a private company never appears in the directory
+   for a reader without a grant on it (with the control: it appears in
+   that reader's granted-structure reads); a directory-listed company's
+   subtree, aggregates, and content remain refused for a non-granted
+   reader (disclosure ≠ authority); the visibility command is refused
+   for a non-admin actor — including an effective `owner` of the target
+   company — with the platform-admin accept control; top-level creation
+   yields `visibility = 'private'` and accepts no visibility argument;
+   each visibility change emits its §5.2 audit event carrying old and
+   new values — the full audit pattern for the mutation class
+   (same-transaction atomicity of state row, audit event, and outbox
+   record; rollback leaving no state effect, no event, and no outbox
+   record; actor/verb/target) is §6.4's, which enumerates
+   visibility change; this item adds only the old/new-value payload
+   assertion.
+
+## Ruling request
+
+Ratify sections 1–6 as written, with one decision embedded: hierarchy
+records carry no owner column — ownership is expressed solely through
+grants (§4.4) — say "agreed" or name the ownership model you want.

docs/requirements/mode-conversion.md

@@ -0,0 +1,279 @@
+# 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

@@ -456,3 +456,105 @@ this line is weakened.
 - Negative tests prove roll-up endpoints cannot mutate state and that a
   reader sees aggregates only over workspaces they are authorized on
   (no cross-tenant existence oracles).
+
+## 9. Amendment A2 — company visibility classes and the company directory
+
+**Status:** amendment to Amendment A1, added by reviewed PR under Ruling 4b
+(operator ruling, 2026-08-27; decision owner Jason; recorded in the webui-audit
+lane RULINGS.md). Everything in §§1–8 remains binding verbatim, with exactly
+the two express modifications below. Nothing else is weakened. The detailed
+contract text lives in the hierarchy schema contract
+(`hierarchy-schema.md` §2.8, §5.5, §6.9); this amendment changes only what A1
+itself permits, so that contract does not stretch A1 by interpretation.
+
+### 9.1 What A2 modifies in A1
+
+1. **Class data (extends §8.1.2's first constraint).** The tenancy/authorization
+   structure record class additionally carries **visibility-class data**: the
+   single column `companies.visibility`, values `private` | `directory`
+   (hierarchy schema §2.8). Visibility is disclosure data about the class's own
+   nodes — what a company row reveals about its own existence — and is part of
+   the class's tenancy/authorization purpose. It is not business or
+   orchestration payload. §8.1.2's payload prohibition is widened for nothing
+   else: hierarchy tables still MUST NOT carry task, plan, or any other
+   business/orchestration payload, and this amendment admits exactly this one
+   column.
+2. **The company directory (extends §8.1.3's function enumeration).** The
+   hierarchy serves one additional, express, narrow runtime function: the
+   **company directory** — a read-only disclosure listing of exactly the
+   companies whose `visibility = 'directory'`, revealing existence, name, and
+   slug to every authenticated user of the deployment and nothing else. It
+   mutates nothing, confers no authority, evaluates no grant down the chain,
+   and aggregates nothing (it is not a roll-up). §8.3's
+   no-cross-tenant-existence-oracle acceptance is narrowed by exactly this one
+   ratified carve-out: the directory is the sole permitted existence
+   disclosure, and it discloses only directory-class companies (witnessed in
+   hierarchy schema §6.7 and §6.9). Private companies remain undisclosed to
+   non-granted subjects everywhere, including the directory.
+
+### 9.2 What A2 explicitly does not change
+
+1. Content access stays grant-only under the RBAC grant model contract:
+   directory listing discloses existence, never content, membership, or any
+   authority (Ruling 3 unchanged; hierarchy schema §2.8).
+2. **No join-request surface is authorized.** Ruling 4b decision 5's
+   see-and-ask-to-join flow is a follow-up contract in its entirety —
+   including the ability to submit a request. A2 admits exactly the
+   read-only listing of §9.1.2 and nothing more; hierarchy schema §2.8
+   states the invariants that pre-bind the future flow contract, and that
+   contract must itself amend this enumeration before any join-request
+   runtime surface exists.
+3. Visibility changes are hierarchy mutations on the existing §8.2.3 audited
+   mutation path — audited maintenance of the class's own structure in
+   §8.1.3's sense, not a further runtime function. Authorization for them is
+   defined in hierarchy schema §5.5 (platform admins plus the future
+   company-CRUD capability; owner-as-such cannot publish).
+4. Company creation is unchanged and always yields `visibility = 'private'`
+   (onboarding wizard §5.2); this amendment adds no creation path and no
+   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/onboarding-wizard.md

@@ -397,6 +397,14 @@ seed-workspace-scoped mutant, correctly refusing outside the seed
 set, passes branch (c), so the two branches detect distinct
 mutants. No other change.
 
+Amendment 1 (Ruling 4b, 2026-08-28): §5.2's embedded decision was RULED
+AGREED (Jason, 2026-08-27), and Ruling 4b adds company visibility
+classes (hierarchy schema §2.8): open top-level creation always yields
+a **private** company; publishing a company into the deployment-wide
+directory is a separate, gated visibility mutation (hierarchy schema
+§5.5) that is never part of the creation command. §5.2 is amended to
+state both.
+
 Scope: the Gateway-backed product onboarding wizard. Out of scope: the
 host-local install wizard (`mosaic wizard`, which drives host install and
 gateway bootstrap and is not this artifact — audit REPORT.md layer 3);
@@ -1169,15 +1177,18 @@ collects no sensitive category, so v1 ships no custody surface.
    party, service actor, or wizard-privileged writer exists in this
    flow.
 2. **Post-bootstrap top-level company creation** — the "N companies" flow
-   — is decided by the ruling below: any **eligible platform user** MAY
+   — RULED AGREED (Jason, 2026-08-27): any **eligible platform user** MAY
    create a top-level company and MUST name an initial `owner` grant in
    the same audited operation (contract 2 §4.3); the creator naming
    themselves is the default. Eligible means, in identity-contract
    terms: an authenticated account (identity §2) that is not banned
    (identity §7.1 — deactivation on this platform IS the better-auth
    ban; no separate deactivated state exists). No further role or grant
-   is required. Until that ruling, deny-by-default holds (contract 2
-   §3.1): no implicit creation authority exists.
+   is required. Creation always yields a **private** company
+   (`visibility = 'private'`, hierarchy schema §2.8, Ruling 4b): the
+   creation command accepts no visibility argument, and publishing into
+   the deployment-wide directory is a separate, gated mutation
+   (hierarchy schema §5.5) that standard users cannot perform.
 3. Child-node creation inside the wizard (estate, project, workspace
    under the seeded company) follows contract 2 §4.3: parent
    `owner` authority, no automatic grant needed — for canonical seed
@@ -1932,7 +1943,13 @@ contracts and are not additions:
     suffix at all — each contradicting PRD D4's no-lock-in
     requirement (§4.4).
 
-## Ruling request
+## Ruling request — RULED AGREED (Jason, 2026-08-27; Amendment 1)
+
+The §5.2 decision below was ruled agreed: open eligible-user creation
+stands (yielding private companies per Amendment 1), and the
+"alternative if rejected" did not take effect. The request is retained
+below as historical record of what was put to ruling; it is no longer
+live.
 
 Ratify sections 1–7 as written, with one decision embedded:
 

docs/requirements/rbac-grant-model.md

@@ -0,0 +1,478 @@
+# RBAC Grant Model Contract
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 2 of 9).
+Authority: PRD Part I §4 ("Granular RBAC: admins restrict access per company,
+estate, and project; grants are evaluated down the chain") and the
+native-kanban SOT Amendment A1 (§8.1.3 RBAC evaluation, §8.3 acceptance 2).
+This document defines the grant vocabulary, evaluation semantics, and
+revocation propagation that the hierarchy schema contract
+(`docs/requirements/hierarchy-schema.md`, contract 1) attaches to. Contract 1
+pins the `hierarchy_grants` table shape and defers the `role` vocabulary and
+the meaning of "authority" here; the identity contract
+(`docs/requirements/identity-lifecycle.md` §1.4) pins that account creation
+grants nothing.
+
+Revision 2 (independent review, GLM 5.3): §1.1 consequence analysis
+completed — the two existing platform-admin bypass code paths are named as
+non-conformant and §7.4 retires them; team grant subjects suspended pending
+a team contract (§1.4, §3.3–3.4, §7.5); no-self-escalation restated with
+its true rationale and a constructible observable (§4.2, §7.7);
+node-creation seeding scoped to the bootstrap path, resolving the §7.7/§4.3
+contradiction; A1 quotation corrected; audit-field provenance corrected;
+principal-position consequence named (§1.3); membership-row,
+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
+tables themselves (contract 1), workspace-internal membership and its
+role/capability vocabulary (native-kanban SOT REQ-ID-001 and its implementing
+schema), roll-up projection semantics (contract 8), wizard seeding
+(contract 3), the team model (suspended here; see §1.4).
+
+## 1. Three authority layers, none substitutable
+
+1. **Platform role** (`users.role`, better-auth: `member` | `admin`) governs
+   instance administration — user management, system settings, provider
+   configuration. It is not tenancy authority: holding platform `admin`
+   confers **no implicit hierarchy grant and no workspace authorization**.
+   An operator who should see tenant content holds an explicit, audited
+   grant like anyone else. This is the deny-by-default consequence of A1
+   §8.1.3 ("not a bypass of workspace authorization"). `AdminGuard`'s
+   `role === 'admin'` check on admin endpoints stays the platform role's
+   only meaning. **Two shipped code paths violate this rule today and are
+   implementation defects this contract makes non-conformant:** (a) the
+   command authorization service short-circuits every command scope to
+   allowed for platform admins
+   (`apps/gateway/src/commands/command-authorization.service.ts`,
+   `hasScope` returning true when `role === 'admin'`), and (b) the MCP
+   scope derivation maps platform `admin` to tenant-admin MCP scopes
+   including task create/update
+   (`apps/gateway/src/mcp/mcp.service.ts`,
+   `deriveMcpToolScopesForUser`). Ratifying this contract revokes both;
+   §7.4 names them as the surfaces the deny-by-default test retires.
+2. **Hierarchy grants** (`hierarchy_grants`, contract 1 §3) declare tenancy
+   authority at company, estate, or platform-project scope and evaluate down
+   the chain to workspace-scoped authorization (§3 below).
+3. **Workspace membership** (SOT REQ-ID-001) remains its own mechanism.
+   A chain grant confers command authorization over descendant workspaces;
+   it does not create membership rows, and row-level principal positions
+   (task owner, proposer, decision actor) still require ACTIVE workspace
+   membership exactly as REQ-TEN-001/REQ-ID-001 acceptance states.
+   Consequence, stated so implementing PRs do not weaken REQ-TEN-001 to
+   remove the friction: a chain-granted actor who is not a workspace member
+   may issue the write commands their role implies but cannot occupy a
+   principal position — any command taking a principal argument must name
+   an ACTIVE member of the target workspace (§7.2 enumerates this cell).
+4. **Team grant subjects are suspended.** Contract 1 §3.1 reserves a
+   `team_id` attachment point, but no ratified contract yet defines the
+   team it would bind: the only existing `teams` table is the legacy global
+   Brain table (own authority columns, no workspace binding, not
+   repurposed per contract 1 §1.3), while the SOT's teams are
+   workspace-bound (REQ-ID-001) — and a workspace-bound team holding a
+   company-level grant would be a cross-workspace authority group nothing
+   has ratified. Until a team contract defines the subject (which table,
+   which membership rows, and its relation to D2/REQ-ID-001), creating a
+   grant with a team subject MUST be refused at the command surface (the
+   schema column remains, per contract 1). §3's evaluation semantics for
+   team-conferred grants are specified now so the team contract activates
+   them without amending this one.
+
+## 2. Role vocabulary
+
+One vocabulary at every hierarchy level, totally ordered — a higher role
+includes everything below it:
+
+1. `viewer` — read: sees the node, its subtree structure, and the roll-up
+   aggregates over descendant workspaces (within contract 8's carve-out
+   bounds); read access to descendant workspace content per the SOT's read
+   command families. No mutation of anything.
+2. `member` — work: everything `viewer` has, plus write authorization for
+   business/orchestration command families in descendant workspaces (the
+   concrete command-family mapping is implementation work under SOT
+   REQ-ID-001; this contract pins that `member` maps to the workspace write
+   families and nothing structural).
+3. `owner` — structure: everything `member` has, plus hierarchy mutations on
+   the subtree (create/rename/delete child nodes, transfers per §5), and
+   grant management on the node and its subtree (§4).
+
+No other value is valid in `hierarchy_grants.role`; the column is
+constraint-checked against exactly these three. Extending the vocabulary is a
+contract amendment, not an implementation decision.
+
+## 3. Evaluation semantics
+
+1. **Deny by default.** No grant on any ancestor → no authority. There are
+   no implicit grants: not from platform role (§1.1), not from creating a
+   node (§4.3), not from workspace membership (membership without a chain
+   grant confers exactly what the SOT's own membership rules confer inside
+   that workspace, nothing up the chain).
+2. **Down-the-chain only.** A grant on a node applies to that node and its
+   entire descendant subtree. Nothing evaluates upward or sideways: a grant
+   on an estate says nothing about the parent company or sibling estates.
+3. **Effective role = maximum.** A subject's effective role at any node is
+   the highest role among grants held directly by the subject's user on
+   that node or any ancestor — and, once the team contract activates team
+   subjects (§1.4), grants held by any team the user is a member of on that
+   node or any ancestor. Roles never subtract — there is no negative/deny
+   grant in this model; revocation is deletion (§6).
+4. **Team grants follow live membership** (specified now, active only per
+   §1.4). A team grant confers its role on the team's current members,
+   evaluated at decision time. Leaving the team is loss of the grant with
+   §6's propagation bound.
+5. **Live evaluation, fail closed.** Authorization decisions derive from the
+   live grant and team-membership rows (or from a cache that is invalidated
+   in the same transaction as any grant/membership/hierarchy mutation). A
+   decision path that cannot read grant state denies. No materialized ACL is
+   ever authoritative.
+6. **Tenant context stays derived from authenticated authority**
+   (REQ-TEN-001). The chain adds where grants can be declared; a workspace
+   request is still authorized against that workspace, with the chain
+   contributing the effective role — never letting the chain become what A1
+   §8.1.3 forbids: "a bypass of workspace authorization".
+
+## 4. Grant management
+
+1. Creating, changing, or revoking a grant on a node requires effective
+   `owner` on that node (directly or via any ancestor).
+2. **No self-escalation.** A grant manager cannot create a grant with a role
+   higher than their own effective role on the target node. Under the §2
+   vocabulary this rule is currently implied by §4.1 (managers are `owner`,
+   the top role — no constructible grant exceeds it); it is stated
+   explicitly so it survives any future amendment that decouples
+   grant-management authority from role height. Its observable is the §7.7
+   audit invariant, not a refusal test.
+3. **Bootstrap of authority is explicit; inheritance covers the rest.**
+   Creating the first company (the wizard path, contract 3) and any
+   top-level company creation MUST name the initial `owner` grant in the
+   same audited operation — a top-level node has no ancestor to inherit
+   from, so without this the node would be unownable. Creating a child node
+   (estate, platform-project, workspace) requires effective `owner` on the
+   parent (§2.3) and confers no automatic grant; the creator's authority
+   over the new node already follows from §3.2 down-the-chain evaluation.
+   The creating command MAY additionally name an explicit initial grant for
+   a child node; it is not required to.
+4. Every grant mutation is a semantic audit event under contract 1 §5.2's
+   guarantees, extended by this contract with two further fields: the event
+   carries actor, verb, target, **subject, and role** (subject and role are
+   this contract's addition; contract 1 §5.2 does not enumerate them).
+5. **Role strings are namespaced.** `viewer`/`member` exist at hierarchy
+   level, `member`/`admin` on `users.role`, and the current command layer
+   uses a third `viewer|member|admin` vocabulary — same strings, different
+   meanings. Any serialized role string (audit events per §4.4, API
+   responses, logs) MUST identify its layer (e.g. `hierarchy:owner`,
+   `platform:admin`); a bare role string in a serialized artifact is
+   non-conformant.
+
+## 5. Transfer authority (completes contract 1 §4.2)
+
+"Authority over BOTH the source and the destination parent" means: effective
+`owner` on the current parent node (or an ancestor) AND effective `owner` on
+the destination parent node (or an ancestor), evaluated at transfer time in
+the transfer's own transaction. One subject must hold both; two cooperating
+half-authorized subjects are not a transfer protocol this contract defines.
+
+## 6. Revocation propagation
+
+1. Revoking a grant (deleting the row), removing a user from a team that
+   carries a grant (once team subjects activate, §1.4), or the cascade
+   deletion of a node's grants during node deletion (contract 1 §3.3) all
+   propagate identically: the authority derived from that grant is gone for
+   every descendant workspace.
+2. **Bound:** the next authorization decision on any affected transport
+   decides against the revoked grant. Concretely: no new HTTP/MCP command
+   authorized by the revoked grant after the revoking transaction commits;
+   an open Socket.IO connection whose subscriptions depend on the revoked
+   grant is re-evaluated within 30 seconds or at its next inbound message,
+   whichever comes first (same bound as the identity contract's §7.1
+   deactivation rule; same mechanism may serve both).
+3. Revocation is subtractive only in effect, not in representation: the
+   evaluator never needs tombstones; deletion of the row is the revocation.
+
+## 7. Verification requirements
+
+Binding on the implementing PRs (extends A1 §8.3 acceptance 2–3 and
+contract 1 §6):
+
+1. Vocabulary: the role CHECK constraint rejects any value outside
+   `viewer|member|owner` (real-PostgreSQL witness, `ci-postgres` service in
+   the `test` CI step).
+2. Per-level conferral: for each of the three levels × three roles, a grant
+   yields exactly the implied workspace authorization in a descendant
+   workspace and nothing in a non-descendant workspace (the A1 §8.3
+   "exactly the permissions the chain implies" matrix, enumerated). The
+   matrix includes: a chain grant creates zero workspace-membership rows
+   (assert row counts); a chain-granted non-member is refused as the
+   principal argument of any principal-taking command while their
+   non-principal writes succeed (§1.3); structure reads leak no existence
+   of nodes the reader holds no grant on (no cross-tenant existence
+   oracle, A1 §8.3 acceptance 3).
+3. Ordering: `owner` ⊇ `member` ⊇ `viewer` behaviorally — each higher role
+   passes every lower role's positive cases.
+4. Deny-by-default: platform `admin` with no grant reaches no tenant
+   content — asserted against the two §1.1 non-conformant surfaces after
+   their retirement: the command-authorization admin short-circuit and the
+   MCP tenant-admin scope derivation both gone (a platform admin with no
+   grant is refused workspace commands and receives no tenant MCP scopes);
+   workspace member with no chain grant gains nothing outside SOT
+   membership semantics; fresh account reaches nothing (identity contract
+   §1.4 cross-check).
+5. Team subjects: while suspended (§1.4), creating a team-subject grant is
+   refused at the command surface. On activation by the team contract:
+   user-direct and team-conferred grants combine to the maximum; team-leave
+   drops authority within the §6.2 bound; decision-time evaluation
+   witnessed (grant added → next decision allows; no restart or re-login
+   required).
+6. Revocation: each revocation path in §6.1 denies the next command on
+   every transport; the socket bound is measured; a cached-authorization
+   implementation proves transactional invalidation (grant revoked and
+   decision made on two distinct physical connections). Fail-closed fault
+   witness for §3.5: with grant state unreadable (fault injection), the
+   decision denies.
+7. Grant management: non-`owner` cannot mutate grants; top-level company
+   creation without the named initial `owner` grant is refused, while child
+   node creation under ancestor authority succeeds without one (§4.3 both
+   directions); every mutation produces its audit event with the §4.4
+   fields. Self-escalation observable: over the audit event stream, every
+   grant-create/change event's role is ≤ the acting user's effective role
+   on the target at event time (reconstructable invariant, not a refusal
+   test — see §4.2).
+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
+interpretive resolution named:
+
+- Decision: platform `admin` confers no implicit tenant access — operators
+  see tenant content only through explicit, audited grants (§1.1), which
+  retires the two existing admin bypass paths named there. Say "agreed" or
+  name the implicit access you want platform admins to keep.
+- Interpretive resolution (for visibility, not a separate question): PRD
+  Part I §4 says "admins restrict access per company, estate, and project";
+  this contract resolves "admins" as hierarchy `owner`s (§4.1), not
+  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

@@ -0,0 +1,197 @@
+# 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.

eslint.config.mjs

@@ -7,7 +7,6 @@ export default tseslint.config(
     ignores: [
       '**/dist/**',
       '**/node_modules/**',
-      '**/.next/**',
       '**/coverage/**',
       '**/drizzle.config.ts',
       '**/framework/**',

packages/brain/src/mission-tasks.spec.ts

@@ -0,0 +1,79 @@
+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,6 +3,24 @@ 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[]> {
@@ -30,14 +48,14 @@ export function createMissionTasksRepo(db: Db) {
     },
 
     async create(data: NewMissionTask): Promise<MissionTask> {
-      const rows = await db.insert(missionTasks).values(data).returning();
+      const rows = await db.insert(missionTasks).values(stripStatus(data)).returning();
       return rows[0]!;
     },
 
     async update(id: string, data: Partial<NewMissionTask>): Promise<MissionTask | undefined> {
       const rows = await db
         .update(missionTasks)
-        .set({ ...data, updatedAt: new Date() })
+        .set({ ...stripStatus(data), updatedAt: new Date() })
         .where(eq(missionTasks.id, id))
         .returning();
       return rows[0];

packages/db/drizzle/0018_clean_cobalt_man.sql

@@ -0,0 +1,63 @@
+CREATE TABLE "companies" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"slug" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "companies_slug_unique" UNIQUE("slug")
+);
+--> statement-breakpoint
+CREATE TABLE "estates" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"slug" text NOT NULL,
+	"company_id" uuid NOT NULL,
+	CONSTRAINT "estates_company_slug_uniq" UNIQUE("company_id","slug")
+);
+--> statement-breakpoint
+CREATE TABLE "hierarchy_grants" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"user_id" text,
+	"team_id" uuid,
+	"company_id" uuid,
+	"estate_id" uuid,
+	"platform_project_id" uuid,
+	"role" text NOT NULL,
+	"granted_by" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "hierarchy_grants_subject_target_role_uniq" UNIQUE NULLS NOT DISTINCT("user_id","team_id","company_id","estate_id","platform_project_id","role"),
+	CONSTRAINT "hierarchy_grants_subject_check" CHECK (num_nonnulls(user_id, team_id) = 1),
+	CONSTRAINT "hierarchy_grants_target_check" CHECK (num_nonnulls(company_id, estate_id, platform_project_id) = 1)
+);
+--> statement-breakpoint
+CREATE TABLE "platform_projects" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"slug" text NOT NULL,
+	"estate_id" uuid NOT NULL,
+	CONSTRAINT "platform_projects_estate_slug_uniq" UNIQUE("estate_id","slug")
+);
+--> statement-breakpoint
+CREATE TABLE "workspaces" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"slug" text NOT NULL,
+	"platform_project_id" uuid NOT NULL,
+	CONSTRAINT "workspaces_platform_project_slug_uniq" UNIQUE("platform_project_id","slug")
+);
+--> statement-breakpoint
+ALTER TABLE "estates" ADD CONSTRAINT "estates_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "hierarchy_grants" ADD CONSTRAINT "hierarchy_grants_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "hierarchy_grants" ADD CONSTRAINT "hierarchy_grants_team_id_teams_id_fk" FOREIGN KEY ("team_id") REFERENCES "public"."teams"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "hierarchy_grants" ADD CONSTRAINT "hierarchy_grants_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "hierarchy_grants" ADD CONSTRAINT "hierarchy_grants_estate_id_estates_id_fk" FOREIGN KEY ("estate_id") REFERENCES "public"."estates"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "hierarchy_grants" ADD CONSTRAINT "hierarchy_grants_platform_project_id_platform_projects_id_fk" FOREIGN KEY ("platform_project_id") REFERENCES "public"."platform_projects"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "hierarchy_grants" ADD CONSTRAINT "hierarchy_grants_granted_by_users_id_fk" FOREIGN KEY ("granted_by") REFERENCES "public"."users"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "platform_projects" ADD CONSTRAINT "platform_projects_estate_id_estates_id_fk" FOREIGN KEY ("estate_id") REFERENCES "public"."estates"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspaces" ADD CONSTRAINT "workspaces_platform_project_id_platform_projects_id_fk" FOREIGN KEY ("platform_project_id") REFERENCES "public"."platform_projects"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "hierarchy_grants_company_id_idx" ON "hierarchy_grants" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX "hierarchy_grants_estate_id_idx" ON "hierarchy_grants" USING btree ("estate_id");--> statement-breakpoint
+CREATE INDEX "hierarchy_grants_platform_project_id_idx" ON "hierarchy_grants" USING btree ("platform_project_id");--> statement-breakpoint
+CREATE INDEX "hierarchy_grants_user_id_idx" ON "hierarchy_grants" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "hierarchy_grants_team_id_idx" ON "hierarchy_grants" USING btree ("team_id");--> statement-breakpoint
+CREATE INDEX "hierarchy_grants_granted_by_idx" ON "hierarchy_grants" USING btree ("granted_by");

packages/db/drizzle/0019_volatile_killraven.sql

@@ -0,0 +1,40 @@
+CREATE TYPE "public"."hierarchy_outbox_status" AS ENUM('pending', 'processing', 'delivered');--> statement-breakpoint
+CREATE TABLE "hierarchy_audit_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"seq" bigint GENERATED ALWAYS AS IDENTITY (sequence name "hierarchy_audit_events_seq_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 9223372036854775807 START WITH 1 CACHE 1),
+	"actor_id" text NOT NULL,
+	"verb" text NOT NULL,
+	"target_kind" text NOT NULL,
+	"target_id" uuid NOT NULL,
+	"target_snapshot" jsonb NOT NULL,
+	"transfer_from" jsonb,
+	"transfer_to" jsonb,
+	"correlation_id" text NOT NULL,
+	"causation_id" uuid,
+	"idempotency_key" text NOT NULL,
+	"occurred_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "hierarchy_audit_events_verb_check" CHECK (verb IN ('create', 'rename', 'transfer', 'delete', 'grant_create', 'grant_change', 'grant_revoke')),
+	CONSTRAINT "hierarchy_audit_events_target_kind_check" CHECK (target_kind IN ('company', 'estate', 'platform_project', 'grant')),
+	CONSTRAINT "hierarchy_audit_events_transfer_check" CHECK ((verb = 'transfer') = (transfer_from IS NOT NULL AND transfer_to IS NOT NULL))
+);
+--> statement-breakpoint
+CREATE TABLE "hierarchy_outbox" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"event_id" uuid NOT NULL,
+	"idempotency_key" text NOT NULL,
+	"correlation_id" text NOT NULL,
+	"status" "hierarchy_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 "hierarchy_audit_events" ADD CONSTRAINT "hierarchy_audit_events_causation_id_hierarchy_audit_events_id_fk" FOREIGN KEY ("causation_id") REFERENCES "public"."hierarchy_audit_events"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "hierarchy_outbox" ADD CONSTRAINT "hierarchy_outbox_event_id_hierarchy_audit_events_id_fk" FOREIGN KEY ("event_id") REFERENCES "public"."hierarchy_audit_events"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "hierarchy_audit_events_idempotency_idx" ON "hierarchy_audit_events" USING btree ("idempotency_key");--> statement-breakpoint
+CREATE UNIQUE INDEX "hierarchy_audit_events_seq_idx" ON "hierarchy_audit_events" USING btree ("seq");--> statement-breakpoint
+CREATE INDEX "hierarchy_audit_events_target_seq_idx" ON "hierarchy_audit_events" USING btree ("target_id","seq");--> statement-breakpoint
+CREATE INDEX "hierarchy_audit_events_correlation_idx" ON "hierarchy_audit_events" USING btree ("correlation_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "hierarchy_outbox_event_idx" ON "hierarchy_outbox" USING btree ("event_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "hierarchy_outbox_idempotency_idx" ON "hierarchy_outbox" USING btree ("idempotency_key");--> statement-breakpoint
+CREATE INDEX "hierarchy_outbox_status_created_idx" ON "hierarchy_outbox" USING btree ("status","created_at");

packages/db/drizzle/0020_special_betty_brant.sql

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,47 @@
+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

@@ -127,6 +127,34 @@
       "when": 1787609223282,
       "tag": "0017_accounts_issuer",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1787862158838,
+      "tag": "0018_clean_cobalt_man",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "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

@@ -0,0 +1,412 @@
+/**
+ * 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-audit.witness.test.ts

@@ -0,0 +1,363 @@
+/**
+ * Hierarchy audit event + outbox schema witnesses — contract 1 §5.2 and the
+ * schema-level half of §6.4.
+ *
+ * Witnesses the guarantees the tables themselves carry: verb/target-kind/
+ * transfer CHECK constraints, idempotency uniqueness (REQ-AUD-001 duplicate
+ * suppression at the database level), monotonic append order (`seq`),
+ * deletion-safe linkage (no foreign key from the events table into any class
+ * table — events survive the deletion of their target), the causation
+ * self-FK, and the outbox's FK/uniqueness/status shape. The repository-level
+ * half of §6.4 (same-transaction atomicity, rollback, replay) is witnessed in
+ * apps/gateway/src/hierarchy/hierarchy-audit.integration.test.ts.
+ *
+ * Two legs run the same witness body:
+ *  - PGlite (WASM Postgres): always runs.
+ *  - Real PostgreSQL (§6.8): 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 { companies, hierarchyAuditEvents, hierarchyOutbox } 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 = `hier-a-${randomUUID().slice(0, 8)}`;
+
+/** Minimal valid event row; overrides compose the negative cases. */
+type EventInsert = typeof hierarchyAuditEvents.$inferInsert;
+
+function eventRow(overrides: Partial<EventInsert> = {}): EventInsert {
+  return {
+    actorId: `${T}-actor`,
+    verb: 'create',
+    targetKind: 'company',
+    targetId: randomUUID(),
+    targetSnapshot: { id: 'x', slug: 'x', name: 'x', parentChain: [] },
+    correlationId: `${T}-corr`,
+    idempotencyKey: `${T}-${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 hierarchy_outbox WHERE idempotency_key LIKE ${T + '%'}`);
+    // Caused events first: the causation self-FK is RESTRICT.
+    await d.execute(
+      sql`DELETE FROM hierarchy_audit_events WHERE idempotency_key LIKE ${T + '%'} AND causation_id IS NOT NULL`,
+    );
+    await d.execute(sql`DELETE FROM hierarchy_audit_events WHERE idempotency_key LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM companies WHERE slug LIKE ${T + '%'}`);
+  });
+
+  // ── CHECK constraints ──────────────────────────────────────────────────────
+
+  it('accepts every declared verb and refuses an undeclared one', async () => {
+    for (const verb of [
+      'create',
+      'rename',
+      'delete',
+      'grant_create',
+      'grant_change',
+      'grant_revoke',
+    ]) {
+      await db().insert(hierarchyAuditEvents).values(eventRow({ verb }));
+    }
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ verb: 'update' })),
+      /verb_check|violates check/i,
+      'undeclared verb must be refused',
+    );
+  });
+
+  it('refuses an undeclared target kind', async () => {
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ targetKind: 'workspace' })),
+      /target_kind_check|violates check/i,
+      'workspace is not an audited target kind (workspace mutation is SOT-side)',
+    );
+  });
+
+  it('requires transfer snapshots exactly on transfers', async () => {
+    const parent = { kind: 'company', id: randomUUID(), slug: 'p' };
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(
+        eventRow({
+          verb: 'transfer',
+          targetKind: 'estate',
+          transferFrom: parent,
+          transferTo: { ...parent, id: randomUUID() },
+        }),
+      );
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ verb: 'transfer' })),
+      /transfer_check|violates check/i,
+      'transfer without source/destination snapshots must be refused',
+    );
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ verb: 'transfer', transferFrom: parent })),
+      /transfer_check|violates check/i,
+      'transfer with only the source snapshot must be refused',
+    );
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ verb: 'create', transferFrom: parent, transferTo: parent })),
+      /transfer_check|violates check/i,
+      'non-transfer with transfer snapshots must be refused',
+    );
+  });
+
+  // ── Idempotency and ordering ───────────────────────────────────────────────
+
+  it('refuses a duplicate idempotency key', async () => {
+    const key = `${T}-dup-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ idempotencyKey: key }));
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ idempotencyKey: key })),
+      /duplicate key|unique/i,
+    );
+  });
+
+  it('assigns strictly increasing seq in insert order for one target', async () => {
+    const targetId = randomUUID();
+    const k1 = `${T}-seq-1-${randomUUID()}`;
+    const k2 = `${T}-seq-2-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ targetId, idempotencyKey: k1 }));
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ targetId, verb: 'rename', idempotencyKey: k2 }));
+    const res = rows(
+      await db().execute(
+        sql`SELECT idempotency_key, seq FROM hierarchy_audit_events WHERE target_id = ${targetId} ORDER BY seq ASC`,
+      ),
+    );
+    expect(res.map((r) => r['idempotency_key'])).toEqual([k1, k2]);
+    expect(Number(res[1]!['seq'])).toBeGreaterThan(Number(res[0]!['seq']));
+  });
+
+  // ── Deletion-safe linkage (§5.2) ───────────────────────────────────────────
+
+  it('has no foreign key into any class table, and events survive target 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 = 'hierarchy_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(['hierarchy_audit_events']);
+
+    const companyId = randomUUID();
+    await db()
+      .insert(companies)
+      .values({ id: companyId, name: 'Doomed', slug: `${T}-doomed` });
+    const key = `${T}-survive-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(
+        eventRow({
+          verb: 'delete',
+          targetId: companyId,
+          targetSnapshot: { id: companyId, slug: `${T}-doomed`, name: 'Doomed', parentChain: [] },
+          idempotencyKey: key,
+        }),
+      );
+    await db().execute(sql`DELETE FROM companies WHERE id = ${companyId}`);
+    const after = rows(
+      await db().execute(
+        sql`SELECT target_snapshot FROM hierarchy_audit_events WHERE idempotency_key = ${key}`,
+      ),
+    );
+    expect(after).toHaveLength(1);
+    expect((after[0]!['target_snapshot'] as { id: string }).id).toBe(companyId);
+  });
+
+  it('enforces the causation self-FK and RESTRICTs deleting a cause', async () => {
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ causationId: randomUUID() })),
+      /foreign key/i,
+      'causation must reference an existing event',
+    );
+    const causeKey = `${T}-cause-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ verb: 'delete', idempotencyKey: causeKey }));
+    const cause = rows(
+      await db().execute(
+        sql`SELECT id FROM hierarchy_audit_events WHERE idempotency_key = ${causeKey}`,
+      ),
+    )[0]!;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(
+        eventRow({ verb: 'grant_revoke', targetKind: 'grant', causationId: cause['id'] as string }),
+      );
+    await expectViolation(
+      db().execute(sql`DELETE FROM hierarchy_audit_events WHERE id = ${cause['id'] as string}`),
+      /foreign key/i,
+      'a cause with dependent events must not be deletable',
+    );
+  });
+
+  // ── Outbox shape ───────────────────────────────────────────────────────────
+
+  it('outbox rows require an existing event, one outbox row per event, unique idempotency', async () => {
+    await expectViolation(
+      db()
+        .insert(hierarchyOutbox)
+        .values({
+          eventId: randomUUID(),
+          idempotencyKey: `${T}-ob-${randomUUID()}`,
+          correlationId: `${T}-corr`,
+        }),
+      /foreign key/i,
+      'outbox must reference an existing event',
+    );
+    const key = `${T}-ob-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ idempotencyKey: key }));
+    const event = rows(
+      await db().execute(sql`SELECT id FROM hierarchy_audit_events WHERE idempotency_key = ${key}`),
+    )[0]!;
+    const eventId = event['id'] as string;
+    await db()
+      .insert(hierarchyOutbox)
+      .values({ eventId, idempotencyKey: key, correlationId: `${T}-corr` });
+    await expectViolation(
+      db()
+        .insert(hierarchyOutbox)
+        .values({ eventId, idempotencyKey: `${T}-ob2-${randomUUID()}`, correlationId: `${T}-c` }),
+      /duplicate key|unique/i,
+      'one outbox record per event',
+    );
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO hierarchy_outbox (event_id, idempotency_key, correlation_id, status)
+            VALUES (${eventId}, ${`${T}-ob3-${randomUUID()}`}, 'c', '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 key = `${T}-obr-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ idempotencyKey: key }));
+    const event = rows(
+      await db().execute(sql`SELECT id FROM hierarchy_audit_events WHERE idempotency_key = ${key}`),
+    )[0]!;
+    await db()
+      .insert(hierarchyOutbox)
+      .values({
+        eventId: event['id'] as string,
+        idempotencyKey: key,
+        correlationId: `${T}-corr`,
+      });
+    await expectViolation(
+      db().execute(sql`DELETE FROM hierarchy_audit_events WHERE id = ${event['id'] as string}`),
+      /foreign key/i,
+    );
+  });
+}
+
+// ── Leg 1: PGlite (always runs — local witness signal) ───────────────────────
+
+describe('hierarchy audit witnesses — PGlite', () => {
+  let dir: string;
+  let handle: ReturnType<typeof createPgliteDb>;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'hier-audit-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 (§6.8 — binding witness, ci-postgres in CI) ───────
+
+const hasPostgres = Boolean(process.env['DATABASE_URL']);
+
+describe.skipIf(!hasPostgres)('hierarchy audit 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

@@ -0,0 +1,555 @@
+/**
+ * Hierarchy schema witnesses — contract 1 (docs/requirements/hierarchy-schema.md) §6.
+ *
+ * Witnesses §6.1 (chain construction, slug scoping, grant CHECKs, grant
+ * uniqueness, NOT NULLs), §6.2 (column allowlist), the database-level parts of
+ * §6.6 (RESTRICT/cascade deletion behavior), and §6.7's catalog half (no
+ * foreign keys from outside the class into class tables).
+ *
+ * Two legs run the same witness body:
+ *  - PGlite (WASM Postgres): always runs, so the witnesses execute locally
+ *    with no database configured.
+ *  - Real PostgreSQL (§6.8): runs when DATABASE_URL is set — in CI that is
+ *    the ci-postgres service, migrated by the pipeline before `pnpm test`.
+ *    This leg is the contract's binding witness; the PGlite leg is the local
+ *    development signal.
+ */
+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 {
+  companies,
+  estates,
+  hierarchyGrants,
+  platformProjects,
+  workspaces,
+  teams,
+  users,
+} from './schema.js';
+
+type AnyDb = {
+  db: {
+    insert: (t: unknown) => { values: (v: unknown) => Promise<unknown> };
+    delete: (t: unknown) => { where?: unknown } & PromiseLike<unknown>;
+    execute: (q: unknown) => Promise<{ rows?: unknown[] } | unknown[]>;
+  };
+  close: () => Promise<void>;
+};
+
+/** 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'],
+  estates: ['id', 'name', 'slug', 'company_id'],
+  platform_projects: ['id', 'name', 'slug', 'estate_id'],
+  workspaces: ['id', 'name', 'slug', 'platform_project_id'],
+  hierarchy_grants: [
+    'id',
+    'user_id',
+    'team_id',
+    'company_id',
+    'estate_id',
+    'platform_project_id',
+    'role',
+    'granted_by',
+    'created_at',
+  ],
+};
+
+const NODE_TABLES = ['companies', 'estates', 'platform_projects', 'workspaces'];
+const CLASS_TABLES = [...NODE_TABLES, 'hierarchy_grants'];
+
+/**
+ * Drizzle wraps constraint failures ("Failed query: ...") with the driver
+ * error attached as `cause`. Match the pattern anywhere along the 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 = `hier-w-${randomUUID().slice(0, 8)}`;
+
+function witnessSuite(getHandle: () => AnyDb): void {
+  const db = () => getHandle().db as unknown as ReturnType<typeof createDb>['db'];
+
+  const userA = `${T}-user-a`;
+  const userB = `${T}-user-b`;
+  let teamId: string;
+  let companyId: string;
+  let company2Id: string;
+  let estateId: string;
+  let estate2Id: string;
+  let ppId: string;
+  let workspaceId: string;
+
+  beforeAll(async () => {
+    await db()
+      .insert(users)
+      .values([
+        { id: userA, name: 'Witness A', email: `${userA}@example.com` },
+        { id: userB, name: 'Witness B', email: `${userB}@example.com` },
+      ]);
+    teamId = randomUUID();
+    await db()
+      .insert(teams)
+      .values({
+        id: teamId,
+        name: `${T}-team`,
+        slug: `${T}-team`,
+        ownerId: userA,
+        managerId: userA,
+      });
+  });
+
+  afterAll(async () => {
+    // Bottom-up, fail-closed order; grants cascade with their targets.
+    const d = db();
+    await d.execute(sql`DELETE FROM hierarchy_grants WHERE granted_by LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM workspaces WHERE slug LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM platform_projects WHERE slug LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM estates WHERE slug LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM companies WHERE slug LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM teams WHERE slug LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM users WHERE id LIKE ${T + '%'}`);
+  });
+
+  // ── §6.1 chain construction ────────────────────────────────────────────────
+
+  it('accepts a full valid chain: company → estate → platform-project → workspace', async () => {
+    companyId = randomUUID();
+    estateId = randomUUID();
+    ppId = randomUUID();
+    workspaceId = randomUUID();
+    await db()
+      .insert(companies)
+      .values({ id: companyId, name: 'Acme', slug: `${T}-acme` });
+    await db()
+      .insert(estates)
+      .values({ id: estateId, name: 'Estate 1', slug: `${T}-e1`, companyId });
+    await db()
+      .insert(platformProjects)
+      .values({ id: ppId, name: 'PP 1', slug: `${T}-pp1`, estateId });
+    await db()
+      .insert(workspaces)
+      .values({ id: workspaceId, name: 'WS 1', slug: `${T}-ws1`, platformProjectId: ppId });
+  });
+
+  it('accepts two siblings under one parent (the §2.5 control)', async () => {
+    estate2Id = randomUUID();
+    await db()
+      .insert(estates)
+      .values({ id: estate2Id, name: 'Estate 2', slug: `${T}-e2`, companyId });
+  });
+
+  it('refuses inserts with a null parent FK', async () => {
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO estates (id, name, slug, company_id) VALUES (${randomUUID()}, 'x', ${T + '-null-e'}, NULL)`,
+      ),
+      /null value|not-null/i,
+    );
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO platform_projects (id, name, slug, estate_id) VALUES (${randomUUID()}, 'x', ${T + '-null-p'}, NULL)`,
+      ),
+      /null value|not-null/i,
+    );
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO workspaces (id, name, slug, platform_project_id) VALUES (${randomUUID()}, 'x', ${T + '-null-w'}, NULL)`,
+      ),
+      /null value|not-null/i,
+    );
+  });
+
+  it('refuses inserts with a dangling parent FK', async () => {
+    await expectViolation(
+      db()
+        .insert(estates)
+        .values({ id: randomUUID(), name: 'x', slug: `${T}-dangle`, companyId: randomUUID() }),
+      /foreign key/i,
+    );
+  });
+
+  it('catalog: each child table has exactly one parent-FK column and no parentage edge table exists', async () => {
+    const res = rows(
+      await db().execute(sql`
+        SELECT tc.table_name, kcu.column_name, ccu.table_name AS ref_table
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+        JOIN information_schema.constraint_column_usage ccu
+          ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+        WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_schema = 'public'
+      `),
+    );
+    const nodeSet = new Set(NODE_TABLES);
+    // Exactly one parent FK per child node table.
+    for (const [child, parent] of [
+      ['estates', 'companies'],
+      ['platform_projects', 'estates'],
+      ['workspaces', 'platform_projects'],
+    ] as const) {
+      const parentFks = res.filter(
+        (r) => r['table_name'] === child && nodeSet.has(String(r['ref_table'])),
+      );
+      expect(parentFks.map((r) => `${r['column_name']}->${r['ref_table']}`)).toEqual([
+        `${{ estates: 'company_id', platform_projects: 'estate_id', workspaces: 'platform_project_id' }[child]}->${parent}`,
+      ]);
+    }
+    // No table outside the class references a node table (also §6.7's catalog
+    // half for companies/estates/platform_projects/workspaces), and the only
+    // multi-FK referencer is hierarchy_grants (grant attachment, not
+    // parentage).
+    const referencers = new Map<string, number>();
+    for (const r of res) {
+      if (nodeSet.has(String(r['ref_table']))) {
+        const t = String(r['table_name']);
+        referencers.set(t, (referencers.get(t) ?? 0) + 1);
+      }
+    }
+    for (const [table, count] of referencers) {
+      expect(CLASS_TABLES, `unexpected referencer of a node table: ${table}`).toContain(table);
+      if (count > 1) expect(table).toBe('hierarchy_grants');
+    }
+    // No FK anywhere references hierarchy_grants.
+    expect(res.filter((r) => r['ref_table'] === 'hierarchy_grants')).toEqual([]);
+  });
+
+  // ── §6.1 slug scoping ──────────────────────────────────────────────────────
+
+  it('refuses a duplicate slug under the same parent, accepts it under another parent', async () => {
+    company2Id = randomUUID();
+    await db()
+      .insert(companies)
+      .values({ id: company2Id, name: 'Beta', slug: `${T}-beta` });
+    await expectViolation(
+      db()
+        .insert(estates)
+        .values({ id: randomUUID(), name: 'dup', slug: `${T}-e1`, companyId }),
+      /duplicate key|unique/i,
+    );
+    // Same slug, different company — accepted.
+    await db()
+      .insert(estates)
+      .values({ id: randomUUID(), name: 'ok', slug: `${T}-e1`, companyId: company2Id });
+    // companies.slug is unique per deployment.
+    await expectViolation(
+      db()
+        .insert(companies)
+        .values({ id: randomUUID(), name: 'dup', slug: `${T}-acme` }),
+      /duplicate key|unique/i,
+    );
+  });
+
+  it('scopes platform_projects and workspaces slugs per parent (refuse same-parent duplicate, accept cross-parent)', async () => {
+    // Dedicated parent estate so this test leaves estate2 a leaf (the §3.4
+    // cascade witness depends on that).
+    const estate3Id = randomUUID();
+    await db()
+      .insert(estates)
+      .values({ id: estate3Id, name: 'Estate 3', slug: `${T}-e3`, companyId });
+    // platform_projects: (estate_id, slug) unique.
+    await expectViolation(
+      db()
+        .insert(platformProjects)
+        .values({ id: randomUUID(), name: 'dup', slug: `${T}-pp1`, estateId }),
+      /duplicate key|unique/i,
+    );
+    const pp2Id = randomUUID();
+    await db()
+      .insert(platformProjects)
+      .values({ id: pp2Id, name: 'ok', slug: `${T}-pp1`, estateId: estate3Id });
+    // workspaces: (platform_project_id, slug) unique.
+    await expectViolation(
+      db()
+        .insert(workspaces)
+        .values({ id: randomUUID(), name: 'dup', slug: `${T}-ws1`, platformProjectId: ppId }),
+      /duplicate key|unique/i,
+    );
+    await db()
+      .insert(workspaces)
+      .values({ id: randomUUID(), name: 'ok', slug: `${T}-ws1`, platformProjectId: pp2Id });
+  });
+
+  // ── §6.2 column allowlist ──────────────────────────────────────────────────
+
+  it('column allowlist: each class table has exactly its declared columns (no payload, no owner_id)', async () => {
+    for (const [table, allow] of Object.entries(COLUMN_ALLOWLIST)) {
+      const res = rows(
+        await db().execute(
+          sql`SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ${table}`,
+        ),
+      );
+      const actual = res.map((r) => String(r['column_name'])).sort();
+      expect(actual, `column set of ${table}`).toEqual([...allow].sort());
+    }
+  });
+
+  // ── §6.1 grant CHECKs ──────────────────────────────────────────────────────
+
+  it('accepts one valid grant per subject×target form', async () => {
+    // All six forms; also the base rows for the §6.1 uniqueness witness below.
+    const forms = [
+      { userId: userA, companyId },
+      { userId: userA, estateId },
+      { userId: userA, platformProjectId: ppId },
+      { teamId, companyId },
+      { teamId, estateId },
+      { teamId, platformProjectId: ppId },
+    ];
+    for (const form of forms) {
+      await db()
+        .insert(hierarchyGrants)
+        .values({ ...form, role: 'owner', grantedBy: userA });
+    }
+  });
+
+  it('refuses a grant with zero or two subjects (exactly-one-of CHECK)', async () => {
+    await expectViolation(
+      db().insert(hierarchyGrants).values({ companyId, role: 'viewer', grantedBy: userA }),
+      /check constraint/i,
+    );
+    await expectViolation(
+      db()
+        .insert(hierarchyGrants)
+        .values({ userId: userA, teamId, companyId, role: 'viewer', grantedBy: userA }),
+      /check constraint/i,
+    );
+  });
+
+  it('refuses a grant with zero or two targets (exactly-one-of CHECK)', async () => {
+    await expectViolation(
+      db().insert(hierarchyGrants).values({ userId: userA, role: 'viewer', grantedBy: userA }),
+      /check constraint/i,
+    );
+    await expectViolation(
+      db()
+        .insert(hierarchyGrants)
+        .values({ userId: userA, companyId, estateId, role: 'viewer', grantedBy: userA }),
+      /check constraint/i,
+    );
+  });
+
+  // ── §6.1 grant uniqueness (NULLS NOT DISTINCT) ─────────────────────────────
+
+  it('refuses a duplicate (subject, target, role) for each of the six forms', async () => {
+    const forms = [
+      { userId: userA, companyId },
+      { userId: userA, estateId },
+      { userId: userA, platformProjectId: ppId },
+      { teamId, companyId },
+      { teamId, estateId },
+      { teamId, platformProjectId: ppId },
+    ];
+    for (const form of forms) {
+      await expectViolation(
+        db()
+          .insert(hierarchyGrants)
+          .values({ ...form, role: 'owner', grantedBy: userB }),
+        /duplicate key|unique/i,
+        `duplicate form ${JSON.stringify(form)} must be refused`,
+      );
+    }
+    // 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,
+    );
+  });
+
+  // ── §6.1 NOT NULLs ─────────────────────────────────────────────────────────
+
+  it('refuses null role, granted_by, and null name/slug columns', async () => {
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO hierarchy_grants (user_id, company_id, role, granted_by) VALUES (${userA}, ${companyId}, NULL, ${userA})`,
+      ),
+      /null value|not-null/i,
+    );
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO hierarchy_grants (user_id, company_id, role, granted_by) VALUES (${userA}, ${companyId}, 'viewer', NULL)`,
+      ),
+      /null value|not-null/i,
+    );
+    await expectViolation(
+      db().execute(sql`INSERT INTO companies (name, slug) VALUES (NULL, ${T + '-nn'})`),
+      /null value|not-null/i,
+    );
+    await expectViolation(
+      db().execute(sql`INSERT INTO companies (name, slug) VALUES ('x', NULL)`),
+      /null value|not-null/i,
+    );
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO estates (name, slug, company_id) VALUES ('x', NULL, ${companyId})`,
+      ),
+      /null value|not-null/i,
+    );
+  });
+
+  // ── §6.6 deletion (database-level witnesses) ───────────────────────────────
+
+  it('refuses deleting a node with children (fail-closed bottom-up)', async () => {
+    await expectViolation(
+      db().execute(sql`DELETE FROM companies WHERE id = ${companyId}`),
+      /foreign key/i,
+    );
+    await expectViolation(
+      db().execute(sql`DELETE FROM estates WHERE id = ${estateId}`),
+      /foreign key/i,
+    );
+    await expectViolation(
+      db().execute(sql`DELETE FROM platform_projects WHERE id = ${ppId}`),
+      /foreign key/i,
+    );
+  });
+
+  it('cascades a deleted leaf node’s grants and nothing else', async () => {
+    // estate2 is a leaf (no platform-projects). Attach one grant to it.
+    await db()
+      .insert(hierarchyGrants)
+      .values({ userId: userB, estateId: estate2Id, role: 'viewer', grantedBy: userA });
+    const grantCount = async () =>
+      Number(
+        rows(
+          await db().execute(
+            sql`SELECT count(*)::int AS n FROM hierarchy_grants WHERE granted_by LIKE ${T + '%'}`,
+          ),
+        )[0]!['n'],
+      );
+    const before = await grantCount();
+    await db().execute(sql`DELETE FROM estates WHERE id = ${estate2Id}`);
+    // Exactly the one grant on the deleted estate is gone.
+    expect(await grantCount()).toBe(before - 1);
+  });
+
+  it('refuses deleting a user or team that is a grant subject or granted_by referent (RESTRICT)', async () => {
+    await expectViolation(db().execute(sql`DELETE FROM users WHERE id = ${userA}`), /foreign key/i);
+    // userB is only a subject (its estate2 grant cascaded away above, but it
+    // still holds no grants — re-create one to witness subject RESTRICT).
+    await db()
+      .insert(hierarchyGrants)
+      .values({ userId: userB, companyId: company2Id, role: 'viewer', grantedBy: userA });
+    await expectViolation(db().execute(sql`DELETE FROM users WHERE id = ${userB}`), /foreign key/i);
+    await expectViolation(
+      db().execute(sql`DELETE FROM teams WHERE id = ${teamId}`),
+      /foreign key/i,
+    );
+  });
+}
+
+// ── Leg 1: PGlite (always runs — local witness signal) ───────────────────────
+
+describe('hierarchy schema witnesses — PGlite', () => {
+  let dir: string;
+  let handle: ReturnType<typeof createPgliteDb>;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'hier-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 (§6.8 — binding witness, ci-postgres in CI) ───────
+
+const hasPostgres = Boolean(process.env['DATABASE_URL']);
+
+describe.skipIf(!hasPostgres)('hierarchy 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/schema.ts

@@ -3,6 +3,8 @@
  * drizzle-kit reads this file directly (avoids CJS/ESM extension issues).
  */
 
+import { sql } from 'drizzle-orm';
+import type { AnyPgColumn } from 'drizzle-orm/pg-core';
 import {
   pgTable,
   pgEnum,
@@ -13,6 +15,8 @@ import {
   jsonb,
   index,
   uniqueIndex,
+  unique,
+  check,
   real,
   integer,
   bigint,
@@ -298,6 +302,11 @@ 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(),
   },
@@ -1048,3 +1057,336 @@ export const federationEnrollmentTokens = pgTable('federation_enrollment_tokens'
 
   createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
 });
+
+// ─── Hierarchy (tenancy/authorization structure record class) ────────────────
+// Contract: docs/requirements/hierarchy-schema.md (D2, ratified 2026-08-27).
+// Five tables: companies → estates → platform_projects → workspaces, plus
+// hierarchy_grants. Class rows carry parentage, naming, grant, and
+// audit-linkage data only — the column sets below are exhaustive (§2.7) and
+// witnessed against information_schema (§6.2). No owner_id: ownership is the
+// grant structure (§4.4). All writes flow through the Gateway hierarchy
+// 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 estates = pgTable(
+  'estates',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    name: text('name').notNull(),
+    slug: text('slug').notNull(),
+    companyId: uuid('company_id')
+      .notNull()
+      .references(() => companies.id, { onDelete: 'restrict' }),
+  },
+  (t) => [unique('estates_company_slug_uniq').on(t.companyId, t.slug)],
+);
+
+export const platformProjects = pgTable(
+  'platform_projects',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    name: text('name').notNull(),
+    slug: text('slug').notNull(),
+    estateId: uuid('estate_id')
+      .notNull()
+      .references(() => estates.id, { onDelete: 'restrict' }),
+  },
+  (t) => [unique('platform_projects_estate_slug_uniq').on(t.estateId, t.slug)],
+);
+
+export const workspaces = pgTable(
+  'workspaces',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    name: text('name').notNull(),
+    slug: text('slug').notNull(),
+    platformProjectId: uuid('platform_project_id')
+      .notNull()
+      .references(() => platformProjects.id, { onDelete: 'restrict' }),
+  },
+  (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',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // Subject: exactly one of user/team (CHECK below). Principal FKs are
+    // RESTRICT until a deletion-and-retention contract rules otherwise (§3.3).
+    userId: text('user_id').references(() => users.id, { onDelete: 'restrict' }),
+    teamId: uuid('team_id').references(() => teams.id, { onDelete: 'restrict' }),
+    // Target: exactly one of the three grantable levels (CHECK below).
+    // Target FKs CASCADE — the one permitted cascade in the class (§3.3);
+    // cascaded grant deletions are audited by the command family (§5.2).
+    companyId: uuid('company_id').references(() => companies.id, { onDelete: 'cascade' }),
+    estateId: uuid('estate_id').references(() => estates.id, { onDelete: 'cascade' }),
+    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: text('role').notNull(),
+    grantedBy: text('granted_by')
+      .notNull()
+      .references(() => users.id, { onDelete: 'restrict' }),
+    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',
+      sql`num_nonnulls(company_id, estate_id, platform_project_id) = 1`,
+    ),
+    // At most one grant per (subject, target, role) across all six
+    // subject×target forms — NULLS NOT DISTINCT so nullable columns
+    // participate (§3.2).
+    unique('hierarchy_grants_subject_target_role_uniq')
+      .on(t.userId, t.teamId, t.companyId, t.estateId, t.platformProjectId, t.role)
+      .nullsNotDistinct(),
+    index('hierarchy_grants_company_id_idx').on(t.companyId),
+    index('hierarchy_grants_estate_id_idx').on(t.estateId),
+    index('hierarchy_grants_platform_project_id_idx').on(t.platformProjectId),
+    index('hierarchy_grants_user_id_idx').on(t.userId),
+    index('hierarchy_grants_team_id_idx').on(t.teamId),
+    index('hierarchy_grants_granted_by_idx').on(t.grantedBy),
+  ],
+);
+
+// ─── Hierarchy audit events + outbox (contract 1 §5.2) ──────────────────────
+// NOT part of the record class (the class is exactly the five tables above).
+// Append-only semantic audit log for hierarchy mutations, with a dedicated
+// transactional outbox — hierarchy events are not workspace-scoped rows and
+// do not ride the workspace outbox. Deletion-safe linkage: events reference
+// their target by an immutable snapshot (id, slug, parent chain at event
+// time), never by a foreign key into the class tables, so append-only events
+// survive the deletion of their target. Append-only is enforced at the
+// application layer (the hierarchy audit repository exposes no update/delete
+// path for events); REQ-AUD-001's INSERT/SELECT-only database role is a
+// deployment concern outside this schema.
+
+export const HIERARCHY_AUDIT_VERBS = [
+  'create',
+  'rename',
+  'transfer',
+  'visibility_change',
+  'delete',
+  'grant_create',
+  'grant_change',
+  'grant_revoke',
+] as const;
+
+export const HIERARCHY_AUDIT_TARGET_KINDS = [
+  'company',
+  'estate',
+  'platform_project',
+  'grant',
+] as const;
+
+export const hierarchyAuditEvents = pgTable(
+  'hierarchy_audit_events',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // Global append order; per-target ordering (REQ-AUD-001) is a filter on
+    // target_id ordered by seq.
+    seq: bigint('seq', { mode: 'number' }).notNull().generatedAlwaysAsIdentity(),
+    // No FK: audit events outlive every principal and every target (§5.2).
+    actorId: text('actor_id').notNull(),
+    verb: text('verb').notNull(),
+    targetKind: text('target_kind').notNull(),
+    targetId: uuid('target_id').notNull(),
+    // Immutable snapshot at event time. Node events: { id, slug, name,
+    // parentChain: [{ kind, id, slug }, …] root-first }. Grant events:
+    // { id, subject: { userId | teamId }, target: { kind, id }, role }
+    // (subject and role per contract 2 §4.4).
+    targetSnapshot: jsonb('target_snapshot').notNull(),
+    // Present exactly on transfers: snapshot of the source/destination
+    // parent ({ kind, id, slug }), CHECK-enforced below.
+    transferFrom: jsonb('transfer_from'),
+    transferTo: jsonb('transfer_to'),
+    correlationId: text('correlation_id').notNull(),
+    // Prior event in the causal chain (e.g. cascaded grant_revoke events
+    // caused by a node delete). Self-FK RESTRICT keeps the chain intact.
+    causationId: uuid('causation_id').references((): AnyPgColumn => hierarchyAuditEvents.id, {
+      onDelete: 'restrict',
+    }),
+    idempotencyKey: text('idempotency_key').notNull(),
+    occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('hierarchy_audit_events_idempotency_idx').on(t.idempotencyKey),
+    uniqueIndex('hierarchy_audit_events_seq_idx').on(t.seq),
+    index('hierarchy_audit_events_target_seq_idx').on(t.targetId, t.seq),
+    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')`,
+    ),
+    check(
+      'hierarchy_audit_events_target_kind_check',
+      sql`target_kind IN ('company', 'estate', 'platform_project', 'grant')`,
+    ),
+    check(
+      'hierarchy_audit_events_transfer_check',
+      sql`(verb = 'transfer') = (transfer_from IS NOT NULL AND transfer_to IS NOT NULL)`,
+    ),
+  ],
+);
+
+export const hierarchyOutboxStatusEnum = pgEnum('hierarchy_outbox_status', [
+  'pending',
+  'processing',
+  'delivered',
+]);
+
+export const hierarchyOutbox = pgTable(
+  'hierarchy_outbox',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // FK into the append-only events table (not a class table): never
+    // dangles, so RESTRICT is safe and keeps event/outbox integrity.
+    eventId: uuid('event_id')
+      .notNull()
+      .references(() => hierarchyAuditEvents.id, { onDelete: 'restrict' }),
+    idempotencyKey: text('idempotency_key').notNull(),
+    correlationId: text('correlation_id').notNull(),
+    status: hierarchyOutboxStatusEnum('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('hierarchy_outbox_event_idx').on(t.eventId),
+    uniqueIndex('hierarchy_outbox_idempotency_idx').on(t.idempotencyKey),
+    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

@@ -3,6 +3,7 @@
 # Usage: issue-assign.sh -i ISSUE_NUMBER [-a assignee] [-l labels] [-m milestone]
 
 set -e
+set -o pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
@@ -33,25 +34,36 @@ Examples:
     $(basename "$0") -i 42 -l "in-progress" -m "0.2.0"
     $(basename "$0") -i 42 -a @me
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
+}
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
 }
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -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
             ;;
         -a|--assignee)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ASSIGNEE="$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"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -79,20 +91,35 @@ PLATFORM=$(detect_platform)
 case "$PLATFORM" in
     github)
         if [[ -n "$ASSIGNEE" ]]; then
-            gh issue edit "$ISSUE" --add-assignee "$ASSIGNEE"
+            prov_rc=0
+            gh issue edit "$ISSUE" --add-assignee "$ASSIGNEE" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         if [[ "$REMOVE_ASSIGNEE" == true ]]; then
             # Get current assignees and remove them
-            CURRENT=$(gh issue view "$ISSUE" --json assignees -q '.assignees[].login' 2>/dev/null | tr '\n' ',')
+            # pipefail preserves the provider status through the pipeline;
+            # a FAILED lookup exits here instead of reading as a silent
+            # no-assignees skip (codex PR #1464). A successful lookup with
+            # zero assignees still skips the edit below.
+            CURRENT=$(gh issue view "$ISSUE" --json assignees -q '.assignees[].login' 2>/dev/null | tr '\n' ',') || {
+                echo "Error: could not read current assignees (provider lookup failed)" >&2
+                exit 1
+            }
             if [[ -n "$CURRENT" ]]; then
-                gh issue edit "$ISSUE" --remove-assignee "${CURRENT%,}"
+                prov_rc=0
+                gh issue edit "$ISSUE" --remove-assignee "${CURRENT%,}" || prov_rc=$?
+                [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
             fi
         fi
         if [[ -n "$LABELS" ]]; then
-            gh issue edit "$ISSUE" --add-label "$LABELS"
+            prov_rc=0
+            gh issue edit "$ISSUE" --add-label "$LABELS" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         if [[ -n "$MILESTONE" ]]; then
-            gh issue edit "$ISSUE" --milestone "$MILESTONE"
+            prov_rc=0
+            gh issue edit "$ISSUE" --milestone "$MILESTONE" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         echo "Issue #$ISSUE updated successfully"
         ;;
@@ -131,7 +158,9 @@ case "$PLATFORM" in
         fi
 
         if [[ "$NEEDS_EDIT" == true ]]; then
-            "${CMD[@]}"
+            prov_rc=0
+            "${CMD[@]}" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
             echo "Issue #$ISSUE updated successfully"
         else
             echo "No changes specified"

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

@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-close.sh - Close an issue on GitHub or Gitea
-# Usage: issue-close.sh -i <issue_number> [-c <comment>]
+# Usage: issue-close.sh -i <issue_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
 
 set -e
 
@@ -11,36 +12,71 @@ 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
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-close.sh -i <issue_number> [-b <comment>] (see --help)" >&2
+    exit 2
+}
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -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
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             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> [-c <comment>]"
+            echo "Usage: issue-close.sh -i <issue_number> [-b <comment>]"
             echo ""
             echo "Options:"
-            echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment to add before closing (optional)"
+            echo "  -n, --number   Issue number (required; canonical)"
+            echo "  -i, --issue    Alias for --number"
+            echo "  -b, --body     Comment to add before closing (optional; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     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
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 # Detect platform and close issue
@@ -82,10 +118,22 @@ gitea_issue_close_api() {
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
+    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
+    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+        gh_rc=0
+        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+        if [[ "$gh_rc" -ne 0 ]]; then
+            echo "Error: GitHub comment before close failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh issue close "$ISSUE_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub issue close failed (gh exit $gh_rc)" >&2
+        exit 1
     fi
-    gh issue close "$ISSUE_NUMBER"
     echo "Closed GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     GITEA_LOGIN_NAME=$(get_gitea_login || true)
@@ -107,7 +155,9 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 exit 1
             }
         fi
-        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME"
+        prov_rc=0
+        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     else
         echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
         if [[ -n "$COMMENT" ]]; then

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

@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-comment.sh - Add a comment to an issue on GitHub or Gitea
-# Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]
+# Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1, 2026-08-28)
 #
 # tea v0.11.1 defines no `comment` subcommand under `tea issue` (or `tea pr`);
 # the non-existent `tea issue comment ...` form does not error — tea silently
@@ -30,47 +31,84 @@ 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,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker
+# (CONSTITUTION gate 8 as amended; E2E-DELIVERY).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -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
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag, matching
+            # issue-create/issue-edit/pr-create/pr-edit; -c/--comment stays a
+            # backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             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"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]"
+            echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]"
             echo ""
             echo "Options:"
-            echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment text (required)"
+            echo "  -n, --number   Issue number (required; canonical)"
+            echo "  -i, --issue    Alias for --number"
+            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"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     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
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 if [[ -z "$COMMENT" ]]; then
-    echo "Error: Comment is required (-c)"
-    exit 1
+    usage_error "comment is required (-b/--body, or the -c/--comment alias)"
 fi
 
 detect_platform >/dev/null
@@ -340,7 +378,15 @@ PY
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+    # R4 exit-code contract: normalize provider failures to exit 1. gh's own
+    # usage errors exit 2, which would collide with this wrapper's reserved
+    # usage-error status if propagated raw (codex review of 08a00149).
+    gh_rc=0
+    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub comment write failed (gh exit $gh_rc; provider/credential failure — usage errors are exit 2)" >&2
+        exit 1
+    fi
     echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     # A --login override selects a NAMED tea credential and is the only way to

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

@@ -10,6 +10,7 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Default values
 TITLE=""
 BODY=""
+BODY_FILE=""
 LABELS=""
 MILESTONE=""
 INTERACTIVE=false
@@ -74,26 +75,45 @@ Examples:
     $(basename "$0") -t "Fix login bug" -l "bug,priority-high"
     $(basename "$0") -t "Add dark mode" -b "Implement theme switching" -m "0.2.0"
     $(basename "$0") -i
+
+Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure.
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): 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
         -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)
+            # 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"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -111,6 +131,19 @@ 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
@@ -131,7 +164,9 @@ case "$PLATFORM" in
         [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
         [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         ;;
     gitea)
         if command -v tea >/dev/null 2>&1; then

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

@@ -11,28 +11,49 @@ source "$SCRIPT_DIR/detect-platform.sh"
 ISSUE_NUMBER=""
 TITLE=""
 BODY=""
+BODY_FILE=""
 LABELS=""
 MILESTONE=""
 
+# 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
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-edit.sh -i <issue_number> [-t <title>] [-b <body>] [-l <labels>] [-m <milestone>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -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
             ;;
         -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)
+            # 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"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -40,24 +61,38 @@ while [[ $# -gt 0 ]]; do
             echo "Usage: issue-edit.sh -i <issue_number> [-t <title>] [-b <body>] [-l <labels>] [-m <milestone>]"
             echo ""
             echo "Options:"
-            echo "  -i, --issue      Issue number (required)"
+            echo "  -n, --number     Issue number (required; canonical)"
+            echo "  -i, --issue      Alias for --number"
             echo "  -t, --title      New title"
             echo "  -b, --body       New body/description"
             echo "  -l, --labels     Labels (comma-separated, replaces existing)"
             echo "  -m, --milestone  Milestone name"
             echo "  -h, --help       Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     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
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 detect_platform >/dev/null
@@ -68,7 +103,9 @@ if [[ "$PLATFORM" == "github" ]]; then
     [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
     [[ -n "$LABELS" ]] && CMD+=(--add-label "$LABELS")
     [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-    "${CMD[@]}"
+    prov_rc=0
+    "${CMD[@]}" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Updated GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_SLUG=$(get_repo_slug) || {
@@ -84,7 +121,9 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
     [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
     [[ -n "$LABELS" ]] && CMD+=(--add-labels "$LABELS")
     [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-    "${CMD[@]}"
+    prov_rc=0
+    "${CMD[@]}" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Updated Gitea issue #$ISSUE_NUMBER"
 else
     echo "Error: Unknown platform"

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

@@ -36,33 +36,46 @@ Examples:
     $(basename "$0") -m "0.2.0"               # Issues in milestone 0.2.0
     $(basename "$0") --repo ddk/ai-bma         # List issues from anywhere
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): 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)
+        -l|--label|--labels)
+            [[ $# -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
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
         -a|--assignee)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ASSIGNEE="$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
             ;;
@@ -95,7 +108,9 @@ case "$PLATFORM" in
         [[ -n "$LABEL" ]] && CMD+=(--label "$LABEL")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
         [[ -n "$ASSIGNEE" ]] && CMD+=(--assignee "$ASSIGNEE")
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         ;;
     gitea)
         if [[ -n "$REPO_OVERRIDE" ]]; then
@@ -114,7 +129,9 @@ case "$PLATFORM" in
         [[ -n "$MILESTONE" ]] && CMD+=(--milestones "$MILESTONE")
         # Note: tea may not support assignee filter directly in all versions.
         [[ -n "$ASSIGNEE" ]] && echo "Note: Assignee filtering may require manual review for Gitea" >&2
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         ;;
     *)
         echo "Error: Could not detect git platform" >&2

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

@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-reopen.sh - Reopen a closed issue on GitHub or Gitea
-# Usage: issue-reopen.sh -i <issue_number> [-c <comment>]
+# Usage: issue-reopen.sh -i <issue_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
 
 set -e
 
@@ -10,36 +11,71 @@ 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
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>] (see --help)" >&2
+    exit 2
+}
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -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
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             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> [-c <comment>]"
+            echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>]"
             echo ""
             echo "Options:"
-            echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment to add when reopening (optional)"
+            echo "  -n, --number   Issue number (required; canonical)"
+            echo "  -i, --issue    Alias for --number"
+            echo "  -b, --body     Comment to add when reopening (optional; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     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
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 detect_platform >/dev/null
@@ -80,18 +116,34 @@ gitea_issue_reopen_api() {
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
+    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
+    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+        gh_rc=0
+        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+        if [[ "$gh_rc" -ne 0 ]]; then
+            echo "Error: GitHub comment before reopen failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh issue reopen "$ISSUE_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub issue reopen failed (gh exit $gh_rc)" >&2
+        exit 1
     fi
-    gh issue reopen "$ISSUE_NUMBER"
     echo "Reopened GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args || true)
     if [[ -n "$REPO_ARGS" ]]; then
         if [[ -n "$COMMENT" ]]; then
-            tea issue comment "$ISSUE_NUMBER" "$COMMENT" $REPO_ARGS
+            prov_rc=0
+            tea issue comment "$ISSUE_NUMBER" "$COMMENT" $REPO_ARGS || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
-        tea issue reopen "$ISSUE_NUMBER" $REPO_ARGS
+        prov_rc=0
+        tea issue reopen "$ISSUE_NUMBER" $REPO_ARGS || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     else
         echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
         if [[ -n "$COMMENT" ]]; then

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

@@ -8,6 +8,14 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-view.sh -i <issue_number> (see --help)" >&2
+    exit 2
+}
+
 ISSUE_NUMBER=""
 
 # get_remote_host and get_gitea_token are provided by detect-platform.sh
@@ -73,7 +81,8 @@ if comments:
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -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
             ;;
@@ -81,28 +90,29 @@ while [[ $# -gt 0 ]]; do
             echo "Usage: issue-view.sh -i <issue_number>"
             echo ""
             echo "Options:"
-            echo "  -i, --issue    Issue number (required)"
+            echo "  -n, --number   Issue number (required; canonical)"
+            echo "  -i, --issue    Alias for --number"
             echo ""
             echo "Comments are always included (tea --comments / Gitea API /comments)."
             echo "  -h, --help     Show this help"
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "Issue number is required"
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh issue view "$ISSUE_NUMBER"
+    prov_rc=0
+    gh issue view "$ISSUE_NUMBER" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if command -v tea >/dev/null 2>&1; then
         # --comments is what makes tea print the comment bodies (#1357 F3).

packages/mosaic/framework/tools/git/lane-brief.sh

@@ -28,18 +28,25 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 REPO="" MILESTONE="" LABEL="" LOGIN="" LIMIT=100
-while getopts "r:m:l:L:n:h" opt; do
-  case "$opt" in
-    r) REPO="$OPTARG" ;;
-    m) MILESTONE="$OPTARG" ;;
-    l) LABEL="$OPTARG" ;;
-    L) LOGIN="$OPTARG" ;;
-    n) LIMIT="$OPTARG" ;;
-    h) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
-    *) echo "see -h" >&2; exit 2 ;;
+# R2 (2026-08-28): long-flag aliases with the same usage-error contract the
+# wrapper family shares (rc 2, stderr). getopts could not take long flags.
+usage_error() {
+  echo "Error: $*" >&2
+  echo "Usage: lane-brief.sh -r <owner/repo> [-m milestone] [-l label] [-L login] [-n limit]" >&2
+  exit 2
+}
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -r|--repo) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; REPO="$2"; shift 2 ;;
+    -m|--milestone) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; MILESTONE="$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)"; LABEL="$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="$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 ;;
+    -h|--help) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) usage_error "unknown option: $1" ;;
   esac
 done
-[[ -n "$REPO" ]] || { echo "FATAL: -r <owner/repo> required" >&2; exit 2; }
+[[ -n "$REPO" ]] || usage_error "-r/--repo <owner/repo> required"
 
 # Resolve login: explicit -L, then $GITEA_LOGIN, then owner inference, then the
 # shared default-login resolver. Owner inference comes before the shared fallback
@@ -72,7 +79,7 @@ if [[ -z "$LOGIN" ]]; then
     fi
   fi
 fi
-[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 2; }
+[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 1; }
 
 command -v tea >/dev/null || { echo "FATAL: tea not found" >&2; exit 1; }
 command -v jq  >/dev/null || { echo "FATAL: jq not found" >&2; exit 1; }

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

@@ -8,11 +8,20 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: milestone-close.sh -t <title> (see --help)" >&2
+    exit 2
+}
+
 TITLE=""
 
 while [[ $# -gt 0 ]]; do
     case $1 in
         -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
             ;;
@@ -25,28 +34,30 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$TITLE" ]]; then
-    echo "Error: Milestone title is required (-t)"
-    exit 1
+    usage_error "Milestone title is required"
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh api -X PATCH "/repos/{owner}/{repo}/milestones/$(gh api "/repos/{owner}/{repo}/milestones" --jq ".[] | select(.title==\"$TITLE\") | .number")" -f state=closed
+    prov_rc=0
+    gh api -X PATCH "/repos/{owner}/{repo}/milestones/$(gh api "/repos/{owner}/{repo}/milestones" --jq ".[] | select(.title==\"$TITLE\") | .number")" -f state=closed || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Closed GitHub milestone: $TITLE"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args) || {
         echo "Error: Could not resolve Gitea repo/login for remote host" >&2
         exit 1
     }
-    tea milestone close "$TITLE" $REPO_ARGS
+    prov_rc=0
+    tea milestone close "$TITLE" $REPO_ARGS || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Closed Gitea milestone: $TITLE"
 else
     echo "Error: Unknown platform"

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

@@ -3,6 +3,7 @@
 # Usage: milestone-create.sh -t "Title" [-d "Description"] [--due "YYYY-MM-DD"]
 
 set -e
+set -o pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
@@ -37,21 +38,31 @@ Examples:
     $(basename "$0") -t "0.0.1" -d "Pre-MVP Foundation Sprint"
     $(basename "$0") -t "0.1.0" -d "MVP Release" --due "2025-03-01"
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): 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
         -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
             ;;
         -d|--desc)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             DESCRIPTION="$2"
             shift 2
             ;;
         --due)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             DUE_DATE="$2"
             shift 2
             ;;
@@ -74,14 +85,18 @@ PLATFORM=$(detect_platform)
 if [[ "$LIST_ONLY" == true ]]; then
     case "$PLATFORM" in
         github)
-            gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)\t\(.open_issues)/\(.closed_issues) issues"'
+            prov_rc=0
+            gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)\t\(.open_issues)/\(.closed_issues) issues"' || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
             ;;
         gitea)
             REPO_ARGS=$(get_gitea_repo_args) || {
                 echo "Error: Could not resolve Gitea repo/login for remote host" >&2
                 exit 1
             }
-            tea milestones list $REPO_ARGS
+            prov_rc=0
+            tea milestones list $REPO_ARGS || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
             ;;
         *)
             echo "Error: Could not detect git platform" >&2
@@ -92,8 +107,7 @@ if [[ "$LIST_ONLY" == true ]]; then
 fi
 
 if [[ -z "$TITLE" ]]; then
-    echo "Error: Title is required (-t) for creating milestones" >&2
-    usage
+    usage_error "Title is required (-t) for creating milestones"
 fi
 
 case "$PLATFORM" in
@@ -109,7 +123,9 @@ case "$PLATFORM" in
              + (if $d != "" then {"description": $d} else {} end)
              + (if $due != "" then {"due_on": ($due + "T00:00:00Z")} else {} end)')
 
-        gh api repos/:owner/:repo/milestones --method POST --input - <<< "$JSON_PAYLOAD"
+        prov_rc=0
+        gh api repos/:owner/:repo/milestones --method POST --input - <<< "$JSON_PAYLOAD" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         echo "Milestone '$TITLE' created successfully"
         ;;
     gitea)
@@ -120,7 +136,9 @@ case "$PLATFORM" in
         CMD=(tea milestones create --title "$TITLE")
         [[ -n "$DESCRIPTION" ]] && CMD+=(--description "$DESCRIPTION")
         [[ -n "$DUE_DATE" ]] && CMD+=(--deadline "$DUE_DATE")
-        "${CMD[@]}" $REPO_ARGS
+        prov_rc=0
+        "${CMD[@]}" $REPO_ARGS || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         echo "Milestone '$TITLE' created successfully"
         ;;
     *)

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

@@ -8,11 +8,20 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: milestone-list.sh [-s <state>] (see --help)" >&2
+    exit 2
+}
+
 STATE="open"
 
 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
             ;;
@@ -25,8 +34,7 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
@@ -34,13 +42,17 @@ done
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh api "/repos/{owner}/{repo}/milestones?state=$STATE" --jq '.[] | "\(.title) (\(.state)) - \(.open_issues) open, \(.closed_issues) closed"'
+    prov_rc=0
+    gh api "/repos/{owner}/{repo}/milestones?state=$STATE" --jq '.[] | "\(.title) (\(.state)) - \(.open_issues) open, \(.closed_issues) closed"' || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args) || {
         echo "Error: Could not resolve Gitea repo/login for remote host" >&2
         exit 1
     }
-    tea milestone list $REPO_ARGS
+    prov_rc=0
+    tea milestone list $REPO_ARGS || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 else
     echo "Error: Unknown platform"
     exit 1

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

@@ -1,6 +1,7 @@
 #!/bin/bash
 # pr-close.sh - Close a pull request without merging on GitHub or Gitea
-# Usage: pr-close.sh -n <pr_number> [-c <comment>]
+# Usage: pr-close.sh -n <pr_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
 
 set -e
 
@@ -10,51 +11,101 @@ 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
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: pr-close.sh -n <pr_number> [-b <comment>] (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
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             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> [-c <comment>]"
+            echo "Usage: pr-close.sh -n <pr_number> [-b <comment>]"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
-            echo "  -c, --comment  Comment before closing (optional)"
+            echo "  -b, --body     Comment before closing (optional; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     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
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
+    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
+    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh pr comment "$PR_NUMBER" --body "$COMMENT"
+        gh_rc=0
+        gh pr comment "$PR_NUMBER" --body "$COMMENT" || gh_rc=$?
+        if [[ "$gh_rc" -ne 0 ]]; then
+            echo "Error: GitHub PR comment before close failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh pr close "$PR_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub PR close failed (gh exit $gh_rc)" >&2
+        exit 1
     fi
-    gh pr close "$PR_NUMBER"
     echo "Closed GitHub PR #$PR_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if [[ -n "$COMMENT" ]]; then
-        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args)
+        prov_rc=0
+        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args) || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     fi
-    tea pr close "$PR_NUMBER" $(get_gitea_repo_args)
+    prov_rc=0
+    tea pr close "$PR_NUMBER" $(get_gitea_repo_args) || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Closed Gitea PR #$PR_NUMBER"
 else
     echo "Error: Unknown platform"

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

@@ -10,6 +10,7 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Default values
 TITLE=""
 BODY=""
+BODY_FILE=""
 BASE_BRANCH=""
 HEAD_BRANCH=""
 LABELS=""
@@ -135,37 +136,57 @@ Examples:
     $(basename "$0") -i 42 -b "Implements the feature described in #42"
     $(basename "$0") -t "WIP: New feature" --draft
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
+}
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
 }
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
         -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)
+            # 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"
             shift 2
             ;;
         -H|--head)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             HEAD_BRANCH="$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"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
         -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
             ;;
@@ -183,6 +204,19 @@ 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"
@@ -266,7 +300,9 @@ case "$PLATFORM" in
         [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
         [[ "$DRAFT" == true ]] && CMD+=(--draft)
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         ;;
     gitea)
         # tea pull create syntax. Always pass --repo because tea repo inference

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

@@ -13,21 +13,33 @@ 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
             ;;
@@ -40,18 +52,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
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)" >&2
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then

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

@@ -11,6 +11,7 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 TITLE=""
 BODY=""
+BODY_FILE=""
 BASE_BRANCH=""
 DRAFT_MODE=""
 LOGIN_OVERRIDE=""
@@ -50,38 +51,59 @@ Options:
     -H, --host HOST        Explicit Gitea host (required with --repo off-host)
     -h, --help             Show this help message
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
+}
+
+# Usage-error contract (R4, 2026-08-28): 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
-        -n|--number) PR_NUMBER="${2:-}"; shift 2 ;;
-        -t|--title) TITLE="${2:-}"; shift 2 ;;
-        -b|--body) BODY="${2:-}"; shift 2 ;;
-        -B|--base) BASE_BRANCH="${2:-}"; shift 2 ;;
+        -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 1; }
+            [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
             DRAFT_MODE="draft"; shift ;;
         --ready)
-            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
+            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
             DRAFT_MODE="ready"; shift ;;
-        -l|--login) LOGIN_OVERRIDE="${2:-}"; shift 2 ;;
-        -r|--repo) REPO_OVERRIDE="${2:-}"; shift 2 ;;
-        -H|--host) HOST_OVERRIDE="${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:-}"; 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 ;;
+        -H|--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 ;;
         -h|--help) usage 0 ;;
         *) echo "Unknown option: $1" >&2; usage ;;
     esac
 done
 
-[[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 1; }
-[[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 1; }
+# 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
     echo "Error: At least one edit option is required" >&2
-    exit 1
+    exit 2
 fi
 [[ -z "$REPO_OVERRIDE" || "$REPO_OVERRIDE" =~ ^[^/[:space:]]+/[^/[:space:]]+$ ]] || {
     echo "Error: --repo must be OWNER/REPO" >&2
-    exit 1
+    exit 2
 }
 
 if [[ -n "$HOST_OVERRIDE" || -n "$REPO_OVERRIDE" ]]; then
@@ -92,18 +114,24 @@ fi
 
 case "$PLATFORM" in
     github)
-        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 1; }
+        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 2; }
         if [[ -n "$TITLE" || -n "$BODY" || -n "$BASE_BRANCH" ]]; then
             CMD=(gh pr edit "$PR_NUMBER")
             [[ -n "$TITLE" ]] && CMD+=(--title "$TITLE")
             [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
             [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
-            "${CMD[@]}"
+            prov_rc=0
+            "${CMD[@]}" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         if [[ "$DRAFT_MODE" == "draft" ]]; then
-            gh pr ready "$PR_NUMBER" --undo
+            prov_rc=0
+            gh pr ready "$PR_NUMBER" --undo || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         elif [[ "$DRAFT_MODE" == "ready" ]]; then
-            gh pr ready "$PR_NUMBER"
+            prov_rc=0
+            gh pr ready "$PR_NUMBER" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         ;;
     gitea)

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

@@ -34,29 +34,41 @@ Examples:
     $(basename "$0") -s merged -a username    # Merged PRs by user
     $(basename "$0") --repo ddk/ai-bma         # List PRs from anywhere
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # 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)
+        -l|--label|--labels)
+            [[ $# -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
             ;;
         -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
             ;;
@@ -64,8 +76,7 @@ while [[ $# -gt 0 ]]; do
             usage 0
             ;;
         *)
-            echo "Unknown option: $1" >&2
-            usage
+            usage_error "unknown option: $1"
             ;;
     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] [--co-author-trailers --escalate-to PRINCIPAL]
+# 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]
 
 set -euo pipefail
 
@@ -30,6 +30,12 @@ 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
@@ -46,6 +52,7 @@ EOF
 }
 
 # Parse arguments
+BASE_LINE_OVERRIDE=""
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
@@ -64,6 +71,11 @@ 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
@@ -172,8 +184,17 @@ if [[ "$DECL_STATE" == valid && "$DECL_SCHEMA" == 2 ]]; then
 else
     repo_decl_warn_absent_irreversible "pr-merge"
     if [[ "$BASE_BRANCH" != "main" && "$BASE_BRANCH" != "next" ]]; then
-        echo "Error: Mosaic policy allows merges only for PRs targeting 'main' or 'next' (found '$BASE_BRANCH')." >&2
-        exit 1
+        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
     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,13 +12,23 @@ 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
             ;;
@@ -29,18 +39,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
             ;;
         *)
-            echo "Unknown option: $1" >&2
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)" >&2
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 write_metadata() {

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

@@ -39,64 +39,116 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 ACTION=""
 COMMENT=""
+BODY_FILE=""
 LOGIN_OVERRIDE=""
 REPO_OVERRIDE=""
 HOST_OVERRIDE=""
 
+# 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
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: pr-review.sh -n <pr_number> -a <action> [-b <comment>] (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
             ;;
         -a|--action)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ACTION="$2"
             shift 2
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             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"
             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
             ;;
         -H|--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
             ;;
         -h|--help)
-            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>] [-r owner/repo] [-H host]"
+            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-b <comment>] [--login <name>] [-r owner/repo] [-H host]"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
             echo "  -a, --action   Review action: approve, request-changes, comment (required)"
-            echo "  -c, --comment  Review comment (required for request-changes)"
+            echo "  -b, --body     Review comment (required for request-changes; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
             echo "  -r, --repo     Explicit owner/repo slug (skips git-remote slug inference)"
             echo "  -H, --host     Explicit Gitea host (skips remote-host inference)"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     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
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 if [[ -z "$ACTION" ]]; then
-    echo "Error: Action is required (-a): approve, request-changes, comment"
-    exit 1
+    usage_error "Action is required (-a/--action): approve, request-changes, comment"
+fi
+
+# Validate the action BEFORE any provider contact (codex review of PR #1464:
+# an unsupported --action previously reached platform detection and could
+# touch the provider before failing with a provider-class status).
+case "$ACTION" in
+    approve|request-changes|comment) ;;
+    *) usage_error "unknown action '$ACTION': approve, request-changes, comment" ;;
+esac
+
+# Body-required actions fail fast too (codex follow-up on PR #1464):
+# request-changes and comment both require a body; validate before any
+# provider contact.
+if [[ ( "$ACTION" == "request-changes" || "$ACTION" == "comment" ) && -z "$COMMENT" ]]; then
+    usage_error "comment required for $ACTION (-b/--body)"
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then
@@ -679,15 +731,18 @@ PY
 if [[ "$PLATFORM" == "github" ]]; then
     case $ACTION in
         approve)
-            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"}
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"} || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub approve failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
             echo "Approved GitHub PR #$PR_NUMBER"
             ;;
         request-changes)
             if [[ -z "$COMMENT" ]]; then
-                echo "Error: Comment required for request-changes"
-                exit 1
+                usage_error "comment required for request-changes (-b/--body)"
             fi
-            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT"
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT" || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub request-changes failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
             echo "Requested changes on GitHub PR #$PR_NUMBER"
             ;;
         comment)
@@ -695,12 +750,13 @@ if [[ "$PLATFORM" == "github" ]]; then
                 echo "Error: Comment required"
                 exit 1
             fi
-            gh pr review "$PR_NUMBER" --comment --body "$COMMENT"
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --comment --body "$COMMENT" || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub review comment failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
             echo "Added review comment to GitHub PR #$PR_NUMBER"
             ;;
         *)
-            echo "Error: Unknown action: $ACTION"
-            exit 1
+            usage_error "unknown action: $ACTION"
             ;;
     esac
 elif [[ "$PLATFORM" == "gitea" ]]; then
@@ -738,8 +794,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             ;;
         request-changes)
             if [[ -z "$COMMENT" ]]; then
-                echo "Error: Comment required for request-changes"
-                exit 1
+                usage_error "comment required for request-changes (-b/--body)"
             fi
             # Best-effort host for credential resolution only (gitea_resolve_api_for_login
             # below re-derives the real host from HOST_OVERRIDE/remote independently and
@@ -794,8 +849,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             echo "Added and verified comment on Gitea PR #$PR_NUMBER (comment ID $comment_id)"
             ;;
         *)
-            echo "Error: Unknown action: $ACTION"
-            exit 1
+            usage_error "unknown action: $ACTION"
             ;;
     esac
 else

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

@@ -11,13 +11,23 @@ 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
             ;;
@@ -28,18 +38,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
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then

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

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-assign.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/issue-assign-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/issue-assign.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/issue-assign.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: issue-assign.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 -i exits 2"
+expect_stderr "Issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -a -l -m --issue --assignee --labels --milestone; 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" -i 5 -a --help
+expect_rc 2 "short flag value rejected" -i 5 -a -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 -a; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "value" >"$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).
+
+# 6b. Provider-exit normalization (codex PR #1464): a provider stub exiting
+# 2 (its own usage-error status) must surface as wrapper exit 1, never 2.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+cat > "$BIN_DIR/gh" <<GHSTUB
+#!/usr/bin/env bash
+echo "gh \$*" >> "$PROBE_LOG"
+if [[ "\$1 \$2" == "issue edit" ]]; then exit 2; fi
+exit 0
+GHSTUB
+chmod +x "$BIN_DIR/gh"
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/issue-assign.sh" -i 5 -a someone >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+grep -q "provider" "$ERR_FILE" || fail "GitHub path: normalized provider error missing from stderr"
+
+echo "issue-assign.sh usage-contract regression passed (R1/R4)"

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

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-close.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# The comment is OPTIONAL here (an issue may close without one), so unlike
+# issue-comment there is no missing-comment arm.
+#
+# 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/issue-close-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"
+
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-close.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/issue-close.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: issue-close.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 "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -b -c --issue --body --comment; 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" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -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 -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "closing note" >"$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. Sandbox arms may issue DETECTION reads only (tea login list via the
+# stub); no gh/curl write or read may occur.
+if grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a sandbox arm performed a non-detection provider request:" >&2
+    grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" >&2
+    exit 1
+fi
+if grep -qE '^(gh|curl)' "$PROBE_LOG"; then
+    echo "FAIL: gh or curl was invoked during a sandbox arm:" >&2
+    grep -E '^(gh|curl)' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-close.sh usage-contract regression passed (R1/R4)"

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

@@ -42,6 +42,8 @@
 #  10. leaves NO temp files behind (POST/GET bodies + metadata) on either the
 #      success or the failure path — nested function-scoped RETURN traps do not
 #      clobber each other and every scratch file is removed on all exit paths.
+#  11. accepts the canonical -b/--body flag exactly like the -c/--comment alias
+#      (R1, 2026-08-28): a full verified write via -b alone.
 
 set -euo pipefail
 
@@ -409,11 +411,28 @@ run_comment() {
     seed_state "$mode"
     (
         cd "$REPO_DIR"
+        # Provisioned seats export MOSAIC_GIT_IDENTITY and MOSAIC_BRAIN_HOME
+        # seat-wide (launcher), and both escape this harness's sandboxed HOME:
+        # detect-platform.sh consults MOSAIC_GIT_IDENTITY BEFORE the repo-local
+        # mosaic.gitIdentity pin, and resolves the brain home (whose
+        # fleet/agents presence arms the no-identity fail-loud branch) from
+        # MOSAIC_BRAIN_HOME before $HOME. Without these explicit empties the
+        # wrapper either resolves the REAL seat-slot token (stub curl rejects
+        # it: the documented HTTP 401) or fails loud before any request.
+        # Set-but-empty reads as unset to detect-platform's "${VAR:-}" forms.
+        # NOTE: keep this comment block ABOVE the assignment chain — a comment
+        # inside a backslash-continued prefix chain terminates the command and
+        # silently demotes every earlier assignment to an unexported subshell
+        # assignment (measured 2026-08-28: the wrapper then ran without
+        # MOSAIC_CREDENTIALS_FILE and the suite died at credential resolution
+        # with zero diagnostic output).
         PATH="$BIN_DIR:$PATH" \
         TMPDIR="$TMP_SCRATCH" \
         HOME="$HOME_DIR" \
         XDG_CONFIG_HOME="$XDG_DIR" \
         MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
+        MOSAIC_GIT_IDENTITY="" \
+        MOSAIC_BRAIN_HOME="" \
         ISSUE_COMMENT_TEA_LOG="$TEA_LOG" \
         ISSUE_COMMENT_CURL_LOG="$CURL_LOG" \
         ISSUE_COMMENT_CURL_ARGV_LOG="$CURL_ARGV_LOG" \
@@ -430,7 +449,7 @@ run_comment() {
         ISSUE_COMMENT_REPO_SLUG="$REPO_SLUG" \
         ISSUE_COMMENT_API_BASE="$API_BASE" \
         ISSUE_COMMENT_API_ROOT="$API_ROOT" \
-        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" -c "$BODY" "$@"
+        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" "${BODY_FLAG:--c}" "$BODY" "$@"
     ) > "$OUTPUT_FILE" 2>&1
 }
 
@@ -614,4 +633,21 @@ done
 # issue_url (already exercised by Case 1's fresh-success), so the tightened check
 # is not rejecting genuine writes.
 
+# Case 11 (R1, 2026-08-28): -b/--body is the canonical comment flag and must
+# drive a full verified write exactly like the -c/--comment alias. BODY_FLAG
+# swaps only the flag spelling; every assertion below is case 1's contract.
+BODY_FLAG="-b"
+run_comment fresh-success
+grep -q 'Added and verified comment on Gitea issue #7 (comment ID 51)' "$OUTPUT_FILE"
+grep -q "^POST $API_BASE/issues/7/comments$" "$CURL_LOG"
+if grep -Eq '^comment |^issue comment ' "$TEA_LOG"; then
+    echo "FAIL: --body write went through tea instead of REST" >&2
+    exit 1
+fi
+grep -q "^GET $API_BASE/issues/comments/51$" "$CURL_LOG"
+grep -q "^POST $API_BASE/issues/7/comments $ACTING_LOGIN$" "$AUTH_LOG"
+assert_no_temp_leak "fresh-success-body-flag"
+assert_token_not_in_argv "fresh-success-body-flag"
+unset BODY_FLAG
+
 echo "issue-comment.sh REST create + exact-id read-back regression passed"

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

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-comment.sh (R1/R4 remediation, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1), so a caller (or a stop gate)
+# can tell an invocation defect from a delivery blocker. Before this contract
+# the wrapper exited 1 for usage errors with messages on STDOUT, and a
+# value-less flag (-c with no value) died SILENTLY at rc=1 because set -e
+# killed the failed `shift 2`. That silent shape is what full-stopped a fleet
+# seat: a caller could not distinguish "I invoked it wrong" from "delivery is
+# blocked".
+#
+# R1: -b/--body is the canonical comment flag (matching issue-create,
+# issue-edit, pr-create, pr-edit); -c/--comment remains a backward-compatible
+# alias.
+#
+# 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. Missing required comment exits 2 (stderr).
+#   5. A value-less flag (-i -b -c -l and long forms) exits 2 with a
+#      "requires a value" message on stderr (the former silent-death class).
+#   6. -b and -c both pass parsing (the run then fails at platform detection
+#      in this non-repo fixture, nonzero and NOT 2), proving alias acceptance
+#      without any provider fixture.
+#   7. No arm performs any provider request: PATH shims for gh/tea/curl
+#      record every invocation and 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/issue-comment-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"
+
+# Provider shims: any invocation is recorded and fails the run at the end.
+# Usage-error arms must exit during argument parsing, before detect_platform,
+# so these prove "no provider request on parser failure".
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+# gh doubles as platform probe AND write path in arm 6b: probes exit 0; the
+# comment write exits 2 (gh's own usage-error status) to prove the wrapper
+# normalizes provider failures to exit 1 instead of propagating 2.
+if [[ "\$1 \$2" == "issue comment" ]]; then exit 2; fi
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-comment.sh" "$@" )
+}
+
+# Hermetic variant for parse-acceptance arms: neutralizes every identity/
+# credential source the wrapper consults (seat env vars, HOME, XDG tea config)
+# so the arm fails at credential resolution in ANY cwd repo, never reading a
+# real token or contacting a provider. Measured 2026-08-28: without this, the
+# arm's outcome depended on incidental URL-resolution state (brain cwd died at
+# URL-not-found; a stack worktree cwd resolved a configured URL, read the real
+# seat token, and invoked the curl stub — the suite then failed its own
+# no-provider-contact check, correctly).
+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/issue-comment.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 on stdout.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-comment.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, message on stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Missing required comment: rc 2, stderr.
+expect_rc 2 "missing comment exits 2" -i 5
+expect_stderr "comment is required" "missing comment message on stderr"
+
+# 5. Value-less flags: rc 2 with "requires a value" on stderr. The old parser
+# died here silently (set -e on the failed shift 2).
+for flag in -i -b -c -l --issue --body --comment --login; 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" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 6. Alias acceptance at parse level: both -b and -c carry a value past
+# parsing; the wrapper then fails at platform detection (not a git repo)
+# nonzero but NOT as a usage error (rc must not be 2).
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "some text" >"$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
+
+# 6b. GitHub-path exit normalization (codex blocker on 08a00149): gh's own
+# usage errors exit 2; the wrapper must NOT propagate that status (reserved
+# for the wrapper's usage-error contract). With a github remote and a gh stub
+# whose comment write exits 2, the wrapper must exit 1 with the normalized
+# error on stderr.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+git -C "$GH_REPO" config mosaic.gitIdentity ""
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/issue-comment.sh" -i 5 -b "text" >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+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
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    grep -v '^gh issue comment' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-comment.sh usage-contract regression passed (R1/R4)"

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-create.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/issue-create-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/issue-create.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/issue-create.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: issue-create.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 -t exits 2"
+expect_stderr "Title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t -b -l -m --title --body --labels --milestone; 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" -t smoke -b --help
+expect_rc 2 "short flag value rejected" -t smoke -b -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 -b; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" "$flag" "value" >"$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 "issue-create.sh usage-contract regression passed (R1/R4)"

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-edit.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/issue-edit-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/issue-edit.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/issue-edit.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: issue-edit.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 "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -t -b -l -m --issue --title --body --labels --milestone; 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" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -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 -b; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "value" >"$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 "issue-edit.sh usage-contract regression passed (R1/R4)"

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

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-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/issue-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/issue-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/issue-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: issue-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 -m -a -n -r --state --label --milestone --assignee --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 "issue-list.sh usage-contract regression passed (R1/R4)"

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

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-reopen.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# The comment is OPTIONAL here (an issue may close without one), so unlike
+# issue-comment there is no missing-comment arm.
+#
+# 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/issue-reopen-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"
+
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-reopen.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/issue-reopen.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: issue-reopen.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 "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -b -c --issue --body --comment; 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" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -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 -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "closing note" >"$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. Sandbox arms may issue DETECTION reads only (tea login list via the
+# stub); no gh/curl write or read may occur.
+if grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a sandbox arm performed a non-detection provider request:" >&2
+    grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" >&2
+    exit 1
+fi
+if grep -qE '^(gh|curl)' "$PROBE_LOG"; then
+    echo "FAIL: gh or curl was invoked during a sandbox arm:" >&2
+    grep -E '^(gh|curl)' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-reopen.sh usage-contract regression passed (R1/R4)"

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-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/issue-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/issue-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/issue-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: issue-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 -i exits 2"
+expect_stderr "Issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i --issue; 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" -i --help
+expect_rc 2 "short flag value rejected" -i -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 -i; do
+    rc=0
+    run_wrapper_sandboxed -i 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 "issue-view.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-lane-brief-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for lane-brief.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/lane-brief-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/lane-brief.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/lane-brief.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 "owner/repo" "$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 -r exits 2"
+expect_stderr "required" "missing -r message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -r -m -l -L -n --repo --milestone --label --login --limit; 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" -r owner/repo -m --help
+expect_rc 2 "short flag value rejected" -r owner/repo -m -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 -r; do
+    rc=0
+    run_wrapper_sandboxed -r owner/repo >"$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 "lane-brief.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-milestone-close-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for milestone-close.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/milestone-close-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/milestone-close.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/milestone-close.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: milestone-close.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 -t exits 2"
+expect_stderr "Milestone title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t --title; 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" -t --help --help
+expect_rc 2 "short flag value rejected" -t --help -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 -t; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" >"$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 "milestone-close.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-milestone-create-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for milestone-create.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/milestone-create-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/milestone-create.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/milestone-create.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: milestone-create.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 -t exits 2"
+expect_stderr "Title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t -d --due --title --desc; 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" -t smoke -d --help
+expect_rc 2 "short flag value rejected" -t smoke -d -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 -t; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" >"$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 "milestone-create.sh usage-contract regression passed (R1/R4)"