docs: contract 2 Amendment 1 — company-CRUD capability definition

Defines the capability class hierarchy schema §5.5 / contract 1
Amendment 1 anticipates: a platform-scoped, admin-assigned, audited
delegation of exactly the company visibility command. No read surface,
no other company operation; §2 vocabulary and §3 evaluation untouched.
Ends in a one-sentence ruling request (S2 process).

docs/requirements/rbac-grant-model.md

@@ -24,6 +24,19 @@ 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 surface, no other company operation. 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. 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
@@ -242,6 +255,91 @@ contract 1 §6):
 8. Transfer: both-sides `owner` accepted, each single-side case refused
    (completing contract 1 §6.5).
 
+## 8. Company-CRUD capability (Amendment 1)
+
+Hierarchy schema §5.5 authorizes the company visibility mutation for
+exactly two actor classes: platform admins and "subjects holding the
+company-CRUD capability that a follow-up amendment to contract 2 will
+define". This section is that definition. The name is historical — coined
+in contract 1 Amendment 1 before the capability's content was fixed — and
+confers nothing by connotation: the ratified content is exactly §8.1.
+Company _creation_ is already ruled open to active users and always
+private (contract 3 §5.2, Ruling 4); rename, delete, and transfer of
+companies remain hierarchy `owner` operations (§2.3, §5); none of those is
+part of this capability, and widening it to any other operation is a
+further amendment, not an implementation decision.
+
+1. **Content: exactly one command, no read surface.** 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. It authorizes nothing else — and in particular it carries
+   **no read surface**: no company enumeration, no structure read, no
+   existence probe beyond what every authenticated user already has (the
+   §2.8 directory listing). 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.
+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: `id`, `user_id` (FK `users`, NOT NULL),
+   `capability` (text, NOT NULL, constraint-checked against exactly
+   `company_crud`), `granted_by` (FK `users`, NOT NULL), `created_at`;
+   UNIQUE (`user_id`, `capability`). 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), no expiry
+   column: revocation is row deletion, as everywhere in this contract.
+3. **Assignment is instance administration.** Only platform admins
+   (`users.role = 'admin'`) may assign or revoke the capability —
+   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`) —
+   evaluated live and fail-closed per §3.5 (unreadable capability state
+   denies). Revocation propagates per §6: the next authorization decision
+   on any transport decides against the deleted row, within §6.2's bound.
+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. Vocabulary: the `capability` CHECK constraint rejects any value
+      outside `company_crud` (real-PostgreSQL witness, `ci-postgres`
+      service in the `test` CI step).
+   2. Conferral exactness: a non-admin holder succeeds on the visibility
+      command in both directions with contract 1 §5.2's audit event
+      (old and new values as semantic content); the same holder, with no
+      other grants, is refused a workspace command, receives the
+      not-found-indistinguishable refusal on a structure read of the very
+      company they just mutated (hierarchy schema §6.7), cannot create a
+      grant, and derives no MCP scope — the §7.4 deny-by-default matrix
+      gains this cell.
+   3. Assignment authority: 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).
+   4. Revocation and fail-closed: after row deletion, the ex-holder's
+      next visibility command is refused; with capability state
+      unreadable (fault injection), the decision denies (§3.5).
+   5. 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
@@ -257,3 +355,15 @@ interpretive resolution named:
   platform admins. A1 §8.1.3 does not attribute grant declaration to
   platform admins, and the §1.1 decision above is what makes this reading
   binding.
+
+## Ruling request (Amendment 1)
+
+Ratify §8 and the Amendment 1 header note 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 surface, no other company operation. Say
+  "agreed" or
+  name the additional operations (or the curation listing) you want it to
+  carry.