docs: contract 2 Amendment 1 — company-CRUD capability (S2 follow-up) #1477

2026-08-29T18:37:06Z

fred commented

2026-08-29 18:37:06 +00:00

Contract 2 Amendment 1: defines the company-CRUD capability that hierarchy schema §5.5 / contract 1 Amendment 1 (Ruling 4b) anticipate. S2 process: reviewed document, ends in a one-sentence ruling request to Jason.

Definition (new §8): a platform-scoped, admin-assigned, audited delegation of exactly the hierarchy schema §5.5 company visibility command.

Content: the visibility mutation only, both directions, any company — no read surface (publish targets arrive out of band from the requesting owner; unpublish targets are already directory-listed). A curation listing, if ever wanted, is a further amendment with its own §6.7 disclosure analysis.
Holding: platform_capabilities table (user subjects only, CHECK-constrained to company_crud, UNIQUE per user); not a hierarchy grant, never enters §3 chain evaluation.
Assignment: platform admins only (instance administration per §1.1); no self-propagation by holders; every assign/revoke audited with §4.5-namespaced strings (platform-capability:company-crud).
Evaluation/revocation: live, fail-closed (§3.5); revocation is row deletion with the §6.2 bound.
§8.5 states the full deny list (no grants, no reads, no MCP scope, no other company operation, owner-as-such still cannot publish).
§8.6 adds five verification requirements binding on implementing PRs.

Untouched: §2 role vocabulary, §3 evaluation, §4 grant management. Company creation stays open-to-active-users and always private (contract 3 §5.2). Until this ratifies, the capability class is empty and the command stays admin-only (shipped gate in hierarchy.repository.ts unchanged by this PR — implementation follows ratification as a separate increment).

Ruling request (end of file, for Jason): the capability is exactly the visibility command, no read surface — "agreed", or name the additional operations / curation listing it should carry.

Contract 2 Amendment 1: defines the company-CRUD capability that hierarchy schema §5.5 / contract 1 Amendment 1 (Ruling 4b) anticipate. S2 process: reviewed document, ends in a one-sentence ruling request to Jason. **Definition (new §8):** a platform-scoped, admin-assigned, audited delegation of exactly the hierarchy schema §5.5 company visibility command. - Content: the visibility mutation only, both directions, any company — **no read surface** (publish targets arrive out of band from the requesting owner; unpublish targets are already directory-listed). A curation listing, if ever wanted, is a further amendment with its own §6.7 disclosure analysis. - Holding: `platform_capabilities` table (user subjects only, CHECK-constrained to `company_crud`, UNIQUE per user); not a hierarchy grant, never enters §3 chain evaluation. - Assignment: platform admins only (instance administration per §1.1); no self-propagation by holders; every assign/revoke audited with §4.5-namespaced strings (`platform-capability:company-crud`). - Evaluation/revocation: live, fail-closed (§3.5); revocation is row deletion with the §6.2 bound. - §8.5 states the full deny list (no grants, no reads, no MCP scope, no other company operation, owner-as-such still cannot publish). - §8.6 adds five verification requirements binding on implementing PRs. Untouched: §2 role vocabulary, §3 evaluation, §4 grant management. Company creation stays open-to-active-users and always private (contract 3 §5.2). Until this ratifies, the capability class is empty and the command stays admin-only (shipped gate in `hierarchy.repository.ts` unchanged by this PR — implementation follows ratification as a separate increment). **Ruling request (end of file, for Jason):** the capability is exactly the visibility command, no read surface — "agreed", or name the additional operations / curation listing it should carry.

fred added 1 commit 2026-08-29 18:37:06 +00:00

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

ci/woodpecker/pr/ci Pipeline was canceled

Details

009a0ef18e

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).

fred added 1 commit 2026-08-29 18:50:21 +00:00

docs: Amendment 1 rev 2 — terra round-1 fixes

ci/woodpecker/pr/ci Pipeline was canceled

Details

99a0c89c5a

Existence disclosure stated as a bounded carve-out to hierarchy schema
§6.7/§2.8 instead of denied (§8.1); platform_capabilities fully pinned
(uuid PK, timestamptz, both user FKs ON DELETE RESTRICT mirroring
contract 1 §3.3, column-set exhaustiveness) (§8.2); assignment rides the
normal admin command surface, sole writer (§8.3); disjunct-independent
fail-closed evaluation and capability deletion added to §6.1's
revocation enumeration (§8.4); §8.6 rewritten as a capability-only
command matrix with disclosure-bound, both-polarity assignment, and
per-transport revocation witnesses.

fred added 1 commit 2026-08-29 19:04:43 +00:00

docs: Amendment 1 rev 3 — terra round-2 fixes

ci/woodpecker/pr/ci Pipeline was successful

Details

6550bda5e1

- user FKs text not uuid (users.id is BetterAuth text; matches
  hierarchy_grants shape)
- actor receipt split from canonical audit event: receipt carries
  {target id, old, new}; canonical event keeps hierarchy schema §5.2's
  full immutable snapshot; no audit read conferred; §8.6.3 witnesses
  both sides
- kanban SOT Amendment A3 (§10) expressly extends A2's sole-disclosure
  rule by exactly the capability-holder carve-out; ruling request names
  it

rev-code-02 approved these changes 2026-08-29 19:13:19 +00:00

rev-code-02 left a comment

Independent review by rev-code-02 (gate 16; author fred). Head reviewed: 6550bda5e1 (verified current PR head == fetched ref == reviewed tree; base 09d24b92; three additive commits — original, rev 2, rev 3 — no rewrite). Detached terra verdicts were context only; every check below is mine.

Surface: exactly two files, both under docs/requirements/ (rbac-grant-model.md +219, native-kanban-sot.md +44). Docs-only as commissioned; no code, no scope creep.

Document review against the contract corpus I hold from reviewing #1465 (which shipped the hierarchy command family and the §5.5 admin-only fallback this amendment extends):

Amendment 1 §8 resolves hierarchy schema §5.5's forward reference ("a follow-up amendment to contract 2 will define"): the capability is exactly the §5.5 visibility command in both directions, no read command, no other company operation, and widening requires a further amendment. The fallback statement (capability class empty until ratification, command admin-only) matches the shipped gate I verified in #1465.
The three round-2 fixes are present and hold up: (1) SOT A2 is amended expressly, not by interpretation — A3 §10.1 narrows §9.1.2's sole-disclosure rule by exactly one carve-out, binding conditionally on this amendment's ratification, with §10.2 enumerating the non-changes; (2) the actor receipt is a redacted projection ({target id, old, new} only) explicitly split from the canonical §5.2 audit event, and the holder's audit-read refusal is itself a §8.6.3 witness; (3) the platform_capabilities user FKs are text with the BetterAuth-key rationale, matching the shipped hierarchy_grants shape (uuid surrogate id, text user FKs, RESTRICT on principals) I verified against packages/db/src/schema.ts in #1465.
§8.4's independently fail-closed disjuncts and the §6.1/§6.2 revocation join are precisely worded; §8.5's non-conferment list is enumerable; §8.6's six witness families (schema, capability-only command matrix including the structure-read oracle refusal on the just-mutated company, disclosure bound, assignment polarities, revocation + dual fault legs, owner re-witness) are all concretely testable against the shipped machinery.

Mechanical: Prettier 3.8.1 (the repo's lockfile pin, run from the repo's own install) passes both files at this head; control file fails as expected, so the green is a real result. CI pipeline 2994 is the PR pipeline at exactly 6550bda5 and was still running at review time — terminal green remains the merge gate's, per the commission.

One non-blocking observation (Suggestion): the existence-disclosure carve-out amends hierarchy-schema.md §6.7/§2.8 from within contract 2's text; contract 1's own file carries no backlink. This is defensible — §5.5 expressly delegates the capability definition to this amendment, and the SOT (the document claiming sole-disclosure exhaustiveness) got its own express amendment — but a one-line backlink in hierarchy-schema.md §6.7/§2.8 would help a future reader of contract 1 alone. Fine for a later docs pass; nothing here blocks.

Verdict: APPROVED at 6550bda5e1. An amend or rebase voids this approval.

Independent review by rev-code-02 (gate 16; author fred). Head reviewed: 6550bda5e1d95d823e3cf3d3e2265ca2d865c09c (verified current PR head == fetched ref == reviewed tree; base 09d24b92; three additive commits — original, rev 2, rev 3 — no rewrite). Detached terra verdicts were context only; every check below is mine. Surface: exactly two files, both under docs/requirements/ (rbac-grant-model.md +219, native-kanban-sot.md +44). Docs-only as commissioned; no code, no scope creep. Document review against the contract corpus I hold from reviewing #1465 (which shipped the hierarchy command family and the §5.5 admin-only fallback this amendment extends): - Amendment 1 §8 resolves hierarchy schema §5.5's forward reference ("a follow-up amendment to contract 2 will define"): the capability is exactly the §5.5 visibility command in both directions, no read command, no other company operation, and widening requires a further amendment. The fallback statement (capability class empty until ratification, command admin-only) matches the shipped gate I verified in #1465. - The three round-2 fixes are present and hold up: (1) SOT A2 is amended expressly, not by interpretation — A3 §10.1 narrows §9.1.2's sole-disclosure rule by exactly one carve-out, binding conditionally on this amendment's ratification, with §10.2 enumerating the non-changes; (2) the actor receipt is a redacted projection ({target id, old, new} only) explicitly split from the canonical §5.2 audit event, and the holder's audit-read refusal is itself a §8.6.3 witness; (3) the platform_capabilities user FKs are text with the BetterAuth-key rationale, matching the shipped hierarchy_grants shape (uuid surrogate id, text user FKs, RESTRICT on principals) I verified against packages/db/src/schema.ts in #1465. - §8.4's independently fail-closed disjuncts and the §6.1/§6.2 revocation join are precisely worded; §8.5's non-conferment list is enumerable; §8.6's six witness families (schema, capability-only command matrix including the structure-read oracle refusal on the just-mutated company, disclosure bound, assignment polarities, revocation + dual fault legs, owner re-witness) are all concretely testable against the shipped machinery. Mechanical: Prettier 3.8.1 (the repo's lockfile pin, run from the repo's own install) passes both files at this head; control file fails as expected, so the green is a real result. CI pipeline 2994 is the PR pipeline at exactly 6550bda5 and was still running at review time — terminal green remains the merge gate's, per the commission. One non-blocking observation (Suggestion): the existence-disclosure carve-out amends hierarchy-schema.md §6.7/§2.8 from within contract 2's text; contract 1's own file carries no backlink. This is defensible — §5.5 expressly delegates the capability definition to this amendment, and the SOT (the document claiming sole-disclosure exhaustiveness) got its own express amendment — but a one-line backlink in hierarchy-schema.md §6.7/§2.8 would help a future reader of contract 1 alone. Fine for a later docs pass; nothing here blocks. Verdict: APPROVED at 6550bda5e1d95d823e3cf3d3e2265ca2d865c09c. An amend or rebase voids this approval.

fred merged commit 635cb1f666 into next

2026-08-29 19:34:49 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#1477