Newer
Older
openstack-caracal-dc-dc / docs / audit / ga-rulings.md

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: RATIFIED 2026-07-18 (operator, with amendments E1 + E2 + E3). Question as presented (2026-07-18): "Adopt GA-R6 as written -- including rule 3's supersession of the charter's hard-coded 5/0/6 by the CURRENT-STATE section-5 mechanism -- or with what amendment?" Operator answer (2026-07-18), exact utterance: "Ratify with E1, E2, and E3: Amendment E1 (scope): 'Rules 1-2 govern stage closes and verification-type gates. Gates whose closer is an operator ruling close per GA-R5: the recorded, pushed ruling (Status block with paired question and utterance, commit hash) is that gate's closure evidence. A gate row states which type it is.' ; Amendment E2 (extends rule 1): 'A check named as a closer must itself have a green test harness per the standing delivery discipline before its verdict counts. Where a closer is later found to pass vacuously (the DOCFIX-194 class -- passing without exercising what it claims to verify), the closure is VOID, the gate reopens, and the check defect gets its own finding.' ; Amendment E3 (new rule): 'There is no conditional close. A gate with any named remainder either stays open, or the remainder is split into its own gate row (with its own closer) and the original closes on its check alone. Closed with carry-forwards is not a state.'"

Ratified ruling text (as amended; rule 1 extended by E2, rules 6-7 added by E1/E3):

  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. A check named as a closer must itself have a green test harness per the standing delivery discipline before its verdict counts. Where a closer is later found to pass vacuously (the DOCFIX-194 class -- passing without exercising what it claims to verify), the closure is VOID, the gate reopens, and the check defect gets its own finding.
  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.
  6. Scope (E1): rules 1-2 govern stage closes and verification-type gates. Gates whose closer is an operator ruling close per GA-R5: the recorded, pushed ruling (Status block with paired question and utterance, commit hash) is that gate's closure evidence. A gate row states which type it is.
  7. No conditional close (E3): a gate with any named remainder either stays open, or the remainder is split into its own gate row (with its own closer) and the original closes on its check alone. "Closed with carry-forwards" is not a state.

GA-R4 -- Ledger rotation

Status: RATIFIED 2026-07-18 (operator, with amendments F1 + F2 + F3). Question as presented (2026-07-18): "Adopt GA-R4 as written -- with the 15-line per-session cap and 300-line live-ledger cap as proposed -- or with what amendment (including different cap numbers)?" Operator answer (2026-07-18), exact utterance: "Ratify with F1, F2, and F3: Amendment F1 (cap semantics): 'The 300-line cap binds at session close: after writing the close summary, rotate oldest closed-session summaries until under cap. An OPEN session's in-flight section is never rotated (nothing moves out from under a live session) but counts toward the cap -- a long-running session forces older summaries out rather than being truncated itself.' ; Amendment F2 (new rule): 'A session finding an orphaned in-flight section (no close bookend, session verifiably ended) closes it post-hoc: a summary marked "closed post-hoc by ; original did not bookend", body archived per rule 2. Post-hoc summaries carry no status weight -- they record that the session happened, not that its work is durable.' ; Amendment F3 (extends rule 5): 'The SEC register of record is docs/security-ledger.md; the session ledger's machine-derived block may carry a pointer and a scan-derived count, never row-level dispositions. Phase 5 repoints ledger-scan's SEC reporting (and G14's evidence cell) at security-ledger.md accordingly.'"

Ratified ruling text (as amended; rule 3 extended by F1, rule 5 extended by F3, rule 7 added by F2):

  1. Session close writes a BOUNDED summary to docs/session-ledger.md: hard cap 15 lines per closed session.
  2. The closed session's full body moves to docs/archive/ (dated file) in the same close commit; the ledger keeps the summary plus a one-line pointer to the archived body.
  3. The ledger's live working set stays under 300 lines total. The cap binds at session close: after writing the close summary, rotate oldest closed-session summaries until under cap. An OPEN session's in-flight section is never rotated (nothing moves out from under a live session) but counts toward the cap -- a long-running session forces older summaries out rather than being truncated itself.
  4. Fence discipline is unchanged: the --fences validation and section ownership rules stay exactly as they are; the machine-derived section remains machine-owned.
  5. The ledger records SESSION narrative only (what happened, in what order, what was handed off). Status remains CURRENT-STATE.md's alone (GA-R1): a ledger line touching status is a pointer, never a claim. The SEC register of record is docs/security-ledger.md; the session ledger's machine-derived block may carry a pointer and a scan-derived count, never row-level dispositions. Phase 5 repoints ledger-scan's SEC reporting (and G14's evidence cell) at security-ledger.md accordingly.
  6. One-time Phase-5 rotation: the current ~1142-line ledger is rotated per rules 1-3 (bodies to archive, bounded summaries retained), history preserved in git.
  7. Orphaned sessions (F2): a session finding an orphaned in-flight section (no close bookend, session verifiably ended) closes it post-hoc: a summary marked "closed post-hoc by ; original did not bookend", body archived per rule 2. Post-hoc summaries carry no status weight -- they record that the session happened, not that its work is durable.

GA-R7 -- Memory governance

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

Proposed ruling text:

  1. Auto-memory (the project MEMORY.md index and its topic files) may record OBSERVATIONS and CONVENTIONS: measured facts, environment traps, repeatable techniques, naming/layout conventions. It may NEVER record operator policy, standing instructions, priorities, or postures.
  2. Policy and standing instructions live in the REPO with quoted provenance per GA-R5. If a memory-worthy insight is actually policy, it is PROPOSED to the operator for a repo ruling -- not memorized.
  3. Any memory entry claiming operator intent ("operator wants...", "operator ruling...", "prioritize X over Y") is PROPOSED-only until the operator confirms the claim verbatim. Unconfirmed intent claims are removed on discovery and registered as findings.
  4. Every memory entry carries its origin scope: session, date, and the task the observation came from. An instruction observed in one task is recorded as scoped to THAT task unless the operator states otherwise (this is the GA-F06 mechanism killer: a one-time instruction can no longer generalize itself into a standing rule).
  5. Memory is subordinate to the repo: on any divergence the repo wins and the memory entry is corrected or deleted (the skill's divergence rule, extended to memory).
  6. Chartered Phase-5 hygiene under this ruling: correct or remove review-after-each-step.md and project-posture-closed-test.md per the operator's recorded provenance rulings (GA-F06/GA-F07), update the MEMORY.md index (GA-F08), fix the stale hostname in multi-workstation-remote-control.md (GA-F05), and add the skill line: "Claude Code sessions launch from the repo root, always."

Drafts not yet delivered: stage-status vocabulary A/B (last item).