From df1e65abc2ef5f697176202e3c50cc0aa82074c7 Mon Sep 17 00:00:00 2001 From: fred Date: Fri, 28 Aug 2026 14:31:37 -0500 Subject: [PATCH] docs: address terra round-1 findings on 4b amendment (class-data classification, visibility audit witness, ruled request annotation) --- docs/requirements/hierarchy-schema.md | 19 +++++++++++++++---- docs/requirements/onboarding-wizard.md | 8 +++++++- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/requirements/hierarchy-schema.md b/docs/requirements/hierarchy-schema.md index f66240c4..389fda16 100644 --- a/docs/requirements/hierarchy-schema.md +++ b/docs/requirements/hierarchy-schema.md @@ -100,8 +100,14 @@ legacy flat data (future work; see §1.3). 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, and audit-linkage data only — never - task, plan, or any business/orchestration payload. + 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 ratified by Amendment 1 as + authorization/disclosure data: it controls what the class discloses + about its own nodes, which sits inside A1 §8.1.2's + tenancy/authorization purpose for the class — it is 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 @@ -407,7 +413,8 @@ Binding on the implementing PRs (extends A1 §8.3): 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, - grant create/change/revoke, delete) — the event exists after commit + visibility change, grant create/change/revoke, delete) — the event + exists after commit with actor/verb/target and same-transaction atomicity; a rolled-back mutation leaves no event (rollback witness); a node delete's cascaded grant deletions are each covered by events; events survive deletion of @@ -446,7 +453,11 @@ Binding on the implementing PRs (extends A1 §8.3): 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. + new values — the full audit pattern for the mutation class + (same-transaction atomicity, rollback leaving no event, + actor/verb/target, outbox delivery) is §6.4's, which enumerates + visibility change; this item adds only the old/new-value payload + assertion. ## Ruling request diff --git a/docs/requirements/onboarding-wizard.md b/docs/requirements/onboarding-wizard.md index 2ec0fd39..b50fb8e4 100644 --- a/docs/requirements/onboarding-wizard.md +++ b/docs/requirements/onboarding-wizard.md @@ -1943,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: