KB-60A8

94 — Phase 1 Stepwise Build Plan (no build, no COMMIT, 2026-06-01)

13 min read Revision 1
one-roof-governanceimplementation-indexphase1stepwise-build-planstop-conditionsno-commit2026-06-01

94 — Phase 1 Stepwise Build Plan

Mission §5 (Branch B). Tier: concrete step-by-step plan. Mutation footprint: ZERO (plan only). Order: the doc-93 §93.4 order (GCOS substrate → SB-2 → SB-1), consistent with doc 89 §89.2 dependency rules and the GPT "cleanest foundation, SB-1 last" recommendation. Iron rule (every step): no COMMIT unless a live os_proposal_approvals row for THIS step (M-1) + the step's council record exists. Absent that → run BEGIN..ROLLBACK rehearsal only. Stop and re-verify between every step. Never batch steps under one approval. Channel: ssh contabo → docker exec -i postgres psql -U workflow_admin -d directus (PG 16.13). Every transaction sets statement_timeout='5s', lock_timeout='3s', idle_in_transaction_session_timeout='15s'.


94.0 Step ledger (overview)

Step Component COMMIT needs Builds Gates downstream
0 Preflight + backup — (read-only + pg_dump) nothing all steps
1 SB-12 M-1 governance_ruleset (draft) + evo snapshot row SB-10 (FK)
2 SB-13 M-1 gov_worker_cursor + heartbeat rows GCOS workers (post-P1)
3 SB-10 M-1 (after STEP 1) governance_candidate_state + candidate_scan_run scanner (post-P1)
4 SB-11 M-1 5 event types active=false T7 (post-P1)
5 SB-2 M-1 + C-1 scope + ownership + 2 views SB-1 Phase-B owner writes (post-P1)
6 SB-1 M-1 + C-2 F-83-1 fix + 4 action-types Phase-B handler (NO-GO)
7 HOLD nothing

94.1 STEP 0 — Preflight & backup

  • Prerequisites: KB read; live PG read-only; write channel reachable. No authorization needed (no mutation).
  • Allowed objects: read-only query_pg; pg_dump of the reuse-tables that any step touches (apr_action_types, governance_relations, governance_registry, event_type_registry, evolution_snapshots, queue_heartbeat, dot_tools, dot_domains, dot_coverage_required). pg_dump is a read; it commits nothing.
  • Forbidden objects: any DDL/DML; any COMMIT.
  • COMMIT permission required: none (no transaction commits).
  • Stop condition: if the doc-96 preflight shows os_proposal_approvals=0 AND the next step is meant to COMMIT → STOP at that step (rehearsal-only). If any GCOS/SB-2 target table is unexpectedly PRESENT, or counts contradict doc 91/this package → STOP, reconcile, do not proceed.
  • Success evidence: doc-96 checklist captured; baseline counts recorded; pg_dump path on file.
  • Rollback evidence: n/a (read-only).
  • Handoff to next step: baseline + pg_dump path handed to STEP 1; the next step re-runs the relevant slice of doc 96.

94.2 STEP 1 — SB-12 (governance_ruleset + evolution_snapshots)

  • Prerequisites: STEP 0 done; M-1 row for "SB-12 build"; doc-86 fold-ins reviewed; rehearsal entry==exit re-proven this session (BEGIN..ROLLBACK).
  • Allowed objects: CREATE TABLE governance_ruleset (+ index/constraint); 1 reuse row in evolution_snapshots (metrics jsonb fingerprint). Ruleset row(s) status='draft'.
  • Forbidden objects: activating a ruleset; trigger on the new table; law/version write; any other table.
  • COMMIT permission required: M-1 (SB-12). Absent → rehearsal-only.
  • Stop condition: M-1 absent; rehearsal entry≠exit; idle_in_transaction>0; ruleset would be created non-draft.
  • Success evidence: to_regclass('public.governance_ruleset') non-null; ruleset row(s) status='draft'; post-counts delta = exactly the new table + 1 evo row; event_outbox governance still 0.
  • Rollback evidence: in-flight → ROLLBACK, table ABSENT again; committed → DROP TABLE governance_ruleset + DELETE the evo row, re-verify ABSENT.
  • Handoff: ruleset table exists ⇒ SB-10 FK parent ready. Re-verify before STEP 2.

94.3 STEP 2 — SB-13 (gov_worker_cursor + queue_heartbeat)

  • Prerequisites: STEP 1 verified; M-1 row for "SB-13 build"; F-57-1 + L-WATERMARK fold-ins in the script.
  • Allowed objects: CREATE TABLE gov_worker_cursor (last_watermark_id text); optional additive queue_heartbeat rows (executor_name LIKE 'gov_%', executor_kind='PG_worker', metadata='{}').
  • Forbidden objects: reusing a typed (uuid/int) id column for the watermark; Đ45-unsafe metadata keys; trigger; any other table.
  • COMMIT permission required: M-1 (SB-13).
  • Stop condition: M-1 absent; F-57-1 safe-check RAISE; watermark column not text; entry≠exit.
  • Success evidence: gov_worker_cursor present; heartbeat rows (if any) executor_kind='PG_worker', no safe-check RAISE; delta = the new table (+ heartbeat rows).
  • Rollback evidence: DROP TABLE gov_worker_cursor; DELETE FROM queue_heartbeat WHERE executor_name LIKE 'gov\_%'.
  • Handoff: cursor family present. Re-verify before STEP 3.

94.4 STEP 3 — SB-10 (governance_candidate_state + candidate_scan_run)

  • Prerequisites: STEP 1 committed (FK parent governance_ruleset exists); M-1 row for "SB-10 build"; L-CANON-NULL fold-in.
  • Allowed objects: CREATE TABLE governance_candidate_state (+ optional object table) + CREATE TABLE candidate_scan_run; FK → governance_ruleset; candidate_key = COALESCE(canonical_address, collection_name||':'||entity_code).
  • Forbidden objects: a checked_forever/boolean-verdict column; keying on canonical_address alone; seeding candidate rows (backfill = out of Phase 1); FK to a not-yet-built parent.
  • COMMIT permission required: M-1 (SB-10).
  • Stop condition: SB-12 not present (FK would fail) → STOP; M-1 absent; any verdict-boolean in the DDL; entry≠exit.
  • Success evidence: both tables present; FK to governance_ruleset enforced (negative test: bad ruleset_version rejected); 0 candidate rows committed; delta = the 2 (or 3) new tables only.
  • Rollback evidence: DROP TABLE candidate_scan_run; DROP TABLE governance_candidate_state; (+ object table first if present).
  • Handoff: keystone store present, empty. Re-verify before STEP 4.

94.5 STEP 4 — SB-11 (register 5 governance event types, active=false)

  • Prerequisites: M-1 row for "SB-11 register"; F-57-2/3/4 enum fold-ins.
  • Allowed objects: 5 INSERTs into event_type_registryevent_domain='governance', delivery_lane='delayed', event_stream∈{alert,health}, default_severity∈{info,warning}, active=false.
  • Forbidden objects: active=true; any event_outbox row; new table; trigger.
  • COMMIT permission required: M-1 (SB-11). (Activation/trust = C-7.1, NOT now.)
  • Stop condition: M-1 absent; CHECK enum failure (wrong delivery_lane/event_stream/default_severity); any active=true; event_outbox governance ≠ 0; entry≠exit.
  • Success evidence: event_type_registry governance = 5, all active=false; event_outbox governance = 0; delta = exactly 5 registry rows.
  • Rollback evidence: DELETE FROM event_type_registry WHERE event_domain='governance'.
  • Handoff: register-before-emit satisfied; nothing emitted. Re-verify before STEP 5.

94.6 STEP 5 — SB-2 (scope + ownership + 2 resolution views)

  • Prerequisites: M-1 row for "SB-2 build" + C-1 council build record; additive-table notes (doc 86 §86.3) in the script.
  • Allowed objects (one transaction): CREATE TABLE governance_responsibility_scope (+6 seed scopes) + CREATE TABLE governance_object_ownership (20-col, partial UNIQUE per (object_type,object_ref,scope), owner_kind∈{accountable,supporting,delegated,exception}, delegated requires effective_to) + CREATE VIEW v_object_effective_owner + CREATE VIEW v_object_owner_gap.
  • Forbidden objects: ALTER governance_relations (CHECK-widen); any trigger on the new tables; writing owner rows for real objects.
  • COMMIT permission required: M-1 (SB-2) + C-1. Absent C-1 → rehearsal-only even if M-1 present.
  • Stop condition: C-1 or M-1 absent; any governance_relations ALTER in the script; any trigger added; a negative test (dup-accountable / phantom FK / bad scope / bad kind / delegated-no-TTL) fails to reject; entry≠exit.
  • Success evidence: 2 tables + 2 views present; 6 seed scopes; 5 negative tests reject as designed (docs 77/78); governance_relations count unchanged (8); delta = the new objects + 6 seed rows.
  • Rollback evidence: DROP VIEW v_object_owner_gap, v_object_effective_owner; DROP TABLE governance_object_ownership; DROP TABLE governance_responsibility_scope;.
  • Handoff: ownership substrate present (the eventual SB-1 Phase-B write target). Re-verify before STEP 6.

94.7 STEP 6 — SB-1 (F-83-1 fix + 4 apr_action_types rows) — special risk

  • Prerequisites: M-1 row for "SB-1 build" + C-2 council build record; doc 98 (F-83-1) read; rehearsal entry==exit re-proven (docs 83 pattern); pg_dump of apr_action_types on file.
  • Allowed objects (one transaction):
    1. DROP TRIGGER trg_birth_apr_action_types ON apr_action_types;
    2. CREATE TRIGGER trg_birth_apr_action_types AFTER INSERT ON apr_action_types FOR EACH ROW EXECUTE FUNCTION fn_birth_registry_auto('action_code'); (F-83-1 fix)
    3. 4 INSERTs: assign_governance_owner, grant_governance_exception, delegate_authority, assign_axis_owner — all handler_ref='unimplemented', risk_level='high', status='active', _dot_origin set.
  • Forbidden objects: flipping any handler_ref to a real handler (Phase B = NO-GO); creating an approval_requests row (esp. action='add'); any emit; touching governance_relations.
  • COMMIT permission required: M-1 (SB-1) + C-2.
  • Stop condition: C-2 or M-1 absent; the TRIGGER-GUARD fires at ERROR (not WARNING) level → STOP, route per doc 98; the in-rehearsal INSERT still hits a birth_registry.entity_code NULL (fix not effective) → STOP; any approval_requests row would be created; entry≠exit.
  • Success evidence: apr_action_types = 10 (6→10, +4); 4 new rows handler_ref='unimplemented'/risk='high'; birth_registry WHERE collection_name='apr_action_types' = 4 (entity_code=action_code); approval_requests=211 unchanged; apr_approvals=42 unchanged; trigger def now fn_birth_registry_auto('action_code').
  • Rollback evidence: in-flight → ROLLBACK (rows gone, birth rows gone, trigger restored to no-arg def — proven doc 83 §83.3); committed → retire action-types (status='retired', retired_at=now(); NEVER delete — FK RESTRICT) and keep the F-83-1 trigger fix in place (doc 98 §98.5).
  • Handoff: SB-1 vocabulary present, fail-closed. Phase B (handler flip / apply DOT) = NO-GO (A-9). Proceed to STEP 7.

94.8 STEP 7 — HOLD

  • Prerequisites: STEPs 1–6 (those that were authorized) committed + verified.
  • Allowed objects: none. Run doc-101 post-build verification only.
  • Forbidden objects: T6/T7 DOT registration; GCOS backfill (even dry-run beyond doc-96 read); event activation (active=true)/emit; production gate enforcement; SB-1 Phase-B; UI/Directus/Nuxt/Qdrant.
  • COMMIT permission required: none (no build).
  • Stop condition: any pressure to proceed to T6/T7/backfill/DOT/activation without a NEW authorization macro → STOP.
  • Success evidence: doc-101 verification clean; scanner inactive; candidate store empty; no event emitted; no DOT rows; no owner rows for real objects.
  • Rollback evidence: n/a (no build).
  • Handoff: Phase 1 complete and quiet. Next work requires a new authorization/design macro (doc 102).

94.9 Cross-step invariants (hold at EVERY step)

  1. One step, one COMMIT, one auth row. Never batch.
  2. Rehearse BEGIN..ROLLBACK and prove entry==exit before the COMMIT version of any step.
  3. pg_dump the touched reuse-tables immediately before COMMIT.
  4. Re-verify (doc 96) after each COMMIT; record the delta; confirm only authorized rows changed.
  5. event_outbox governance = 0 and os_proposal_approvals writes only by the sovereign — never by the build agent.
  6. No-hardcode / no-island attestation per step (doc 89 §89.9).
  7. Stop on any contradiction between live state and this plan.

Branch B verdict: Phase 1 is a 6-build-step plan (STEP 1–6) bracketed by preflight (STEP 0) and hold (STEP 7), each step independently authorized, rehearsed, and reversible, with SB-12→SB-10 FK ordering and SB-1/F-83-1 isolated last. No step is authorized to COMMIT by this plan; M-1=0 ⇒ COMMIT_FORBIDDEN.

Back to Knowledge Hub knowledge/dev/reports/architecture/one-roof-governance-technical-addendum-and-implementation-index-2026-06-01/94-phase1-stepwise-build-plan.md