Fork: 0
OpenStack / openstack-caracal-dc-dc
Transfer to URL with SHA Find file
Newer
Older
openstack-caracal-dc-dc / docs / audit / ga-rulings.md
@JANeumatrix JANeumatrix 16 hours ago 15 KB GA-R2 RATIFIED (operator, amendments D1+D2, question+answer quoted); GA-R6 draft staged
Raw Blame History

GA-R structural rulings (grounding audit Phase 4)

Delivery per the operator's recorded directive (register, Phase-4 directives item 5): one draft per exchange, held until ruled; every RATIFIED ruling's Status quotes the operator's exact utterance (GA-R5 discipline, applied to its own drafting). Implementation of ratified rulings happens in Phase 5. Order: GA-R3, GA-R5, GA-R1, GA-R2, GA-R6, GA-R4, GA-R7, stage-status vocabulary A/B.

GA-R3 -- D-number admission criteria

Status: RATIFIED 2026-07-18 (operator, with amendments A1 + A2). Exact utterance: "Ratify with A1 and A2: Amendment A1 (sharpens 1(b)): '(b) a Roosevelt-delta implication, tested as: a future Roosevelt build session would need to grep this decision before touching a built surface. Mentioning Roosevelt, or recording a Roosevelt-era preference, does not qualify; changing what gets built or how it transfers does. Where a single entry mixes both (D-129: an OPS plugin install plus an ARCH transfer profile), the class follows the dominant purpose and the ARCH fragment is split into its own entry or an amendment to the governing ARCH decision.' ; Amendment A2 (completes rule 2): 'Operational choices whose configuration must outlive the stage are recorded in the relevant as-built document (the configuration-of-record authority per the GA-R1/GA-R2 division); the runbook carries the how, the as-built carries the what-is.'"

Ratified ruling text (as amended):

  1. A new D-number is admitted ONLY if the decision has at least one of: (a) architectural consequence beyond the current stage; (b) a Roosevelt-delta implication, tested as: a future Roosevelt build session would need to grep this decision before touching a built surface. Mentioning Roosevelt, or recording a Roosevelt-era preference, does not qualify; changing what gets built or how it transfers does. Where a single entry mixes both (D-129: an OPS plugin install plus an ARCH transfer profile), the class follows the dominant purpose and the ARCH fragment is split into its own entry or an amendment to the governing ARCH decision; (c) supersession or material amendment of an existing D-number.
  2. Everything else -- tool options, service settings, plugin lists, host conveniences, process notes -- is an OPERATIONAL choice: it gets a runbook edit or (until GA-R2 lands) a changelog line, and NEVER a new D-number. Operational choices whose configuration must outlive the stage are recorded in the relevant as-built document (the configuration-of-record authority per the GA-R1/GA-R2 division); the runbook carries the how, the as-built carries the what-is.
  3. Every register entry gains a mandatory one-word class tag: ARCH or OPS. New entries are ARCH by construction (rule 1); the tag exists so the back-catalog stays findable.
  4. One-time review (Phase 5): D-121..D-129 are class-tagged in place. OPS candidates per the charter: D-126, D-127, D-128, D-129. Numbers are append-only and are KEPT regardless of tag. Per amendment A1, the D-129 ARCH fragment (the Roosevelt metal-edge transfer profile) is split into its own entry or an amendment to the governing ARCH decision during this review.
  5. Doubt resolves DOWN: if admission is arguable, it is OPS -- a runbook line can be promoted to a D-number later; a diluted register cannot be un-diluted.

Implementation (Phase 5): class-tag sweep of the register template + D-121..D-129 one-time review (incl. the A1 D-129 split); skill sweep carries the admission test.

GA-R5 -- Ruling gate discipline

Status: RATIFIED 2026-07-18 (operator, with amendments B1 + B2). Question as presented (2026-07-18): "Adopt GA-R5 as written (rules 1-5), or with what amendment?" Operator answer (2026-07-18), exact utterance: "Ratify with B1 and B2: Amendment B1 (extends rules 2 and 5): 'The Status block quotes both the single question as presented and the operator's answer, each with date. An answer that does not resolve the question as presented rules nothing -- responsiveness failure is treated identically to template-form ambiguity: the recorder stops and asks (D-123 precedent). For operator-initiated rulings, where no question was presented, the recorder restates the decision as understood in one line, the operator confirms, and both the original utterance and the confirmed restatement are quoted.' ; Amendment B2 (extends rule 4): 'The draft text presented for ruling is itself committed (marked DRAFT) before or with its presentation. The as-ratified text must be diffable in git history against the presented draft, so that any consolidation of amendments is mechanically auditable rather than trusted.'"

Ratified ruling text (as amended):

  1. Rulings are gated like mutations: ONE decision presented and ruled per operator exchange. Batch adoptions ("adopt all of the above") are invalid; each decision gets its own exchange.
  2. Every ruling's Status line quotes the operator's exact utterance and its date. A Status line without the quoted utterance is not a ruling. The Status block quotes both the single question as presented and the operator's answer, each with date.
  3. Scope: D-number rulings and amendments, GA-R ratifications, SEC-row dispositions, and any standing policy or preference recorded on any surface (including memory surfaces, per GA-R7 when ratified).
  4. A ruling exists only when committed: an in-session operator answer is written to its Status line and pushed in the same session, before any dependent work proceeds. An unrecorded ruling is not a ruling. The draft text presented for ruling is itself committed (marked DRAFT) before or with its presentation. The as-ratified text must be diffable in git history against the presented draft, so that any consolidation of amendments is mechanically auditable rather than trusted.
  5. An ambiguous or template-form utterance (unfilled brackets, placeholders) rules NOTHING: the recorder stops and asks; nothing is inferred from it. An answer that does not resolve the question as presented rules nothing -- responsiveness failure is treated identically to template-form ambiguity: the recorder stops and asks (D-123 precedent). For operator-initiated rulings, where no question was presented, the recorder restates the decision as understood in one line, the operator confirms, and both the original utterance and the confirmed restatement are quoted.

GA-R1 -- Single source of truth (status), size budget, rotation, as-built division

Status: RATIFIED 2026-07-18 (operator, with amendments C1 + C2). Question as presented (2026-07-18): "Adopt GA-R1 as written -- including the 360-line cap accounting (body + signature section), same-commit rotation, the Phase-5 demotions list, and signature-replacement rule 7 -- or with what amendment?" Operator answer (2026-07-18), exact utterance: "Ratify with C1 and C2: Amendment C1 (new rule): 'Any commit that changes a status CURRENT-STATE.md carries -- a gate's state, a capture's currency, a pin, the decision queue -- updates CURRENT-STATE.md in that same commit. A status-changing commit that does not touch it is defective by construction. Phase-5 implementation: repo-lint gains a check flagging commits that modify state-bearing surfaces (captures, ga-rulings, design-decisions Status lines, ledger gate rows) without touching CURRENT-STATE.md.' ; Amendment C2 (extends rule 1): 'CURRENT-STATE.md is authoritative over other documents, never over measurement. Where a fresh capture or live measurement contradicts it, the measurement wins: the document is corrected in the same commit as the new capture, and the divergence is noted rather than silently harmonized.'"

Ratified ruling text (as amended; rule 1 extended by C2, rule 8 added by C1):

  1. docs/CURRENT-STATE.md is the ONLY status authority. A status claim (stage state, gate state, plan count, version pin, deploy readiness, decision-queue state) is hand-written NOWHERE else; every other surface either points at CURRENT-STATE.md or is history. CURRENT-STATE.md is authoritative over other documents, never over measurement. Where a fresh capture or live measurement contradicts it, the measurement wins: the document is corrected in the same commit as the new capture, and the divergence is noted rather than silently harmonized.
  2. CURRENT-STATE.md itself asserts nothing unevidenced: every claim cites captured command output (dated capture files under docs/audit/, or a quoted command + output), a path:line, or a commit hash.
  3. Demotions (implemented in Phase 5): the workflow doc's stage table keeps stage IDENTITY and links only; dc0-deploy-readiness.md demotes to a checklist citing the plan capture, its fresh-session banner replaced by a one-line pointer to the G9 canonical entry path (GA-F02 scope addition); README, opentofu/README, and the skill drop every pin and status CURRENT-STATE.md owns (pointers allowed).
  4. Size budget: hard cap 360 lines total -- ~350 for the body (sections 1-10) plus the standing signature section. If a proposed edit would exceed the cap, the edit is wrong, not the cap. (At drafting: 356.)
  5. Rotation: anything that stops being CURRENT -- a closed gate, a resolved decision, a superseded capture, a historical measurement -- moves OUT in the SAME commit that closes it: configuration-of-record detail to the relevant as-built; narrative history to the archive. At most a one-line pointer remains.
  6. Division of authority: CURRENT-STATE.md = STATUS (what IS, what is OPEN). As-built documents (one per site/surface, the vr1-office1-as-built pattern) = CONFIGURATION-of-record for completed surfaces (what WAS BUILT and HOW, with evidence). Neither duplicates the other; they point.
  7. The operator must be able to read the document in full before any signature. Each new signature REPLACES the signature section (git history keeps the old ones); signature blocks do not accumulate.
  8. Any commit that changes a status CURRENT-STATE.md carries -- a gate's state, a capture's currency, a pin, the decision queue -- updates CURRENT-STATE.md in that same commit. A status-changing commit that does not touch it is defective by construction. Phase-5 implementation: repo-lint gains a check flagging commits that modify state-bearing surfaces (captures, ga-rulings, design-decisions Status lines, ledger gate rows) without touching CURRENT-STATE.md.

GA-R2 -- Changelog consolidation

Status: RATIFIED 2026-07-18 (operator, with amendments D1 + D2). Question as presented (2026-07-18): "Adopt GA-R2 as written -- including the under-25-file target and the one-time Phase-5 consolidation of the existing 95 changelogs -- or with what amendment?" Operator answer (2026-07-18), exact utterance: "Ratify with D1 and D2: Amendment D1 (sharpens rule 5): 'One changelog per session: a session appends to its own single changelog rather than minting per-topic files. Multiple same-day changelogs are legitimate only when they belong to distinct sessions.' That caps creation at session count by construction. ; Amendment D2 (extends rule 4): 'The Phase-5 sweep dispositions every docs/ file, not only the changelog class: each non-changelog file is routed per rule 3 (durable home / archive / retained with one-line justification), and each consolidation commit's message manifests the source files it consolidated. The under-25 target counts the top-level docs/ working set; docs/archive/ and dated capture directories under docs/audit/ are excluded from the count but not from routing discipline.'"

Ratified ruling text (as amended; rule 4 extended by D2, rule 5 extended by D1):

  1. Changelogs are session-scoped scratch: they record what a session did. They are NEVER citable as status authority (Phase 1 proved they lie -- GA-F14; standing wording per the charter).
  2. On stage close, per-stage consolidation (the proven v1 do-doc pattern): the stage's changelogs collapse into ONE consolidated per-stage record; the individual files are preserved in git history via the consolidation commit and removed from the working set.
  3. Consolidation ROUTES content to its durable home per the as-built division (GA-R1 rule 6): configuration-of-record detail to the relevant as-built; traps and invariants to platform-traps/the skill; ruling material to design-decisions; narrative history to the consolidated stage record (or docs/archive/). Status content is CURRENT-STATE.md's alone and is not copied anywhere.
  4. Working-set target: docs/ under 25 files. The one-time Phase-5 sweep consolidates the existing 95 changelogs per stage to reach it, history preserved. The Phase-5 sweep dispositions EVERY docs/ file, not only the changelog class: each non-changelog file is routed per rule 3 (durable home / archive / retained with one-line justification), and each consolidation commit's message manifests the source files it consolidated. The under-25 target counts the top-level docs/ working set; docs/archive/ and dated capture directories under docs/audit/ are excluded from the count but not from routing discipline.
  5. A changelog is named and scoped to its session and stage; nothing in a changelog outlives consolidation except by moving to a durable home (rule 3). No new doc class is created to work around this. One changelog per session: a session appends to its own single changelog rather than minting per-topic files. Multiple same-day changelogs are legitimate only when they belong to distinct sessions (creation is thereby capped at session count by construction).

GA-R6 -- Executable definition of done

Status: DRAFT (delivered 2026-07-18; awaiting operator ruling).

Proposed ruling text:

  1. A stage or gate is CLOSED only when a NAMED executable check passes -- a script, harness, or gauntlet target -- and the closing commit records the check's captured output or cites its dated capture file. Prose cannot close a stage.
  2. The check is named IN ADVANCE in the gate's CURRENT-STATE.md row (the "what closes it" cell names the executable), so closure is mechanical, not judged after the fact.
  3. For the current gate specifically (G9 / DC0 readiness): the captured outer plan must read EXACTLY the expected triple recorded in CURRENT-STATE.md section 5 -- which, per the operator's GA-F01 direction, does not exist until D-130 is ruled -- AND the fresh-agent grounding-test question 7 passes against the post-fix repo. (The charter's original hard-coded 5/0/6 wording is superseded by the section-5 mechanism, per the charter's own escape clause in Phase 6 item 4.)
  4. Stage close includes the standing close-out set as executable items: gauntlet ALL GREEN, repo-lint 0-fail, the stage branch merged per the workflow's cross-cutting discipline, the skill sweep done, and (per GA-R2) the stage's consolidation commit landed.
  5. A closed stage's definition-of-done record (the named check + its output citation) rotates to the stage's consolidated record or as-built per GA-R1 rule 5.

Drafts not yet delivered: GA-R4, GA-R7, stage-status vocabulary A/B (in that order).