Governance Convergence — Phase 4: Gas City Pack Structure Design¶

Prerequisite: Phase 1 Inventory — approved Principle: AUTHOR ONCE → COMPOSE THROUGH GAS CITY → ENFORCE THROUGH EXISTING POLICY SYSTEMS → GENERATE VENDOR-SPECIFIC PROJECTIONS ONLY WHEN REQUIRED

1. Current State (From Inventory)¶

.claude/rules/              13 files     5,575 LOC    Claude-only, prose, ~90% unenforced
GEMINI.md                    1 file        300 LOC    ~80% duplication of .claude/rules/
.codex/agents/               9 files    25,628 LOC    Codex-only, pre-Gas City inline prompts
.codex/hooks/               10 scripts   1,100 LOC    Two independent hook systems
CLAUDE.md + AGENTS.md       26 files       590 LOC    Stubs and scaffolds
                            ─────────  ────────
                             59 files   33,193 LOC

2. Target Architecture¶

graph TD
    A["foundation/governance<br/>pack.toml"] --> B["prompts/shared/<br/>6 canonical fragments"]
    A --> C["doctor/<br/>governance checks"]
    A --> D["overlay/per-provider/<br/>vendor projections"]
    A --> E["formulas/<br/>audit + verification"]

    B --> F["global_fragments in city pack.toml"]
    F --> G["Every agent session loads shared policy"]

    D --> H["claude/.claude/rules/<br/>GENERATED from fragments"]
    D --> I["codex/.codex/instructions.md<br/>GENERATED from fragments"]
    D --> J["gemini/GEMINI.md<br/>GENERATED from fragments"]

    C --> K["gc doctor governance-policy-sync"]
    K --> L["Validates projections match canonical"]

Pack Layout¶

BluCity-Packs/foundation/governance/
├── pack.toml                              # Pack manifest
├── prompts/
│   └── shared/                            # CANONICAL policy — authored here ONLY
│       ├── work-authority.md              # Beads ownership + pull model + claim protocol
│       ├── verify-the-effect.md           # Success acceptance + verification discipline
│       ├── reuse-and-delete-first.md      # Ownership audit + deletion + use-what-we-have
│       ├── agent-identity.md              # Identity + provenance + action classes
│       ├── delegation-and-policy.md       # Delegation grant + Cedar enforcement
│       └── git-completion.md              # Commit → push → MR → merge chain
├── prompts/
│   └── domain/                            # Domain-specific fragments (loaded per-agent)
│       └── drupal-standard.md             # Drupal principles (loaded for drupal role only)
├── doctor/
│   ├── governance-adr-index.toml          # [EXISTS] ADR check
│   ├── governance-policy-sync.toml        # [NEW] Validates vendor projections match canonical
│   └── governance-enforcement-audit.toml  # [NEW] Reports unenforced rules
├── overlay/
│   └── per-provider/
│       ├── claude/
│       │   └── .claude/rules/             # GENERATED — gc import install materializes these
│       ├── codex/
│       │   └── .codex/instructions.md     # GENERATED
│       └── gemini/
│           └── GEMINI.md                  # GENERATED
├── skills/
│   └── governance-work-authority/         # [EXISTS] Beads work authority skill
├── formulas/
│   └── governance-audit.toml             # [EXISTS] Periodic audit formula
└── orders/
    └── governance-weekly-audit.toml      # [EXISTS] Weekly audit order

3. Fragment Consolidation Map¶

From 13 rules (5,575 LOC) → 6 shared fragments (~600 LOC) + 1 domain fragment + docs¶

Source Rule	Lines	→ Target Fragment	Core Content (kept)	Worked Examples (→ docs)
`beads-work-ownership.md`	871	`work-authority.md`	Pull model, claim protocol, session start, bead types, handoff	→ BluCity-Docs
`beads-scope.md`	44	`work-authority.md`	Topology reference	inline (small)
`success-is-the-effect.md`	791	`verify-the-effect.md`	Verification table, corollaries, positive controls	→ BluCity-Docs
`ownership-audit-law.md`	629	`reuse-and-delete-first.md`	Audit prompt template, burden of proof, sweep contract	→ BluCity-Docs
`deletion-is-the-deliverable.md`	370	`reuse-and-delete-first.md`	Pre-write gate, decision hierarchy, NET_CUSTOM_LOC_DELTA	→ BluCity-Docs
`use-what-we-have.md`	75	`reuse-and-delete-first.md`	Search order, gc import check/install	inline (small)
`agent-identity-and-provenance.md`	300	`agent-identity.md`	Role→account model, commit trailers, separation of duties	→ BluCity-Docs
`action-classes.md`	321	`agent-identity.md`	Action classes A-D, credential discovery rule	→ BluCity-Docs
`delegation-grant.md`	219	`delegation-and-policy.md`	Cedar Lease schema, grant record, NOT YET IN FORCE status	inline
`git-completion-law.md`	78	`git-completion.md`	Session exit gate, commit chain, worktree path	inline
`pack-overlays.md`	21	(stays project-local)	Gas City pack/overlay rules — not shared policy	stays as-is
`drupal-standard.md`	842	`domain/drupal-standard.md`	Principles, Starforge, read-the-docs	→ BluCity-Docs
`HANDOFF-2026-09-14.md`	1,021	ARCHIVE	Session state — not policy	→ ledger/agent-memory/

Fragment Size Targets¶

Fragment	Source LOC	Target LOC	Reduction	Content
`work-authority.md`	915	~120	87%	Rules only; examples → docs
`verify-the-effect.md`	791	~100	87%	Verification table + 3 corollaries; 8 worked examples → docs
`reuse-and-delete-first.md`	1,074	~150	86%	Pre-write gate + audit prompt + hierarchy; examples → docs
`agent-identity.md`	621	~100	84%	Classes + role model + trailers; incident history → docs
`delegation-and-policy.md`	219	~80	63%	Lease schema + status + deny list (already compact)
`git-completion.md`	78	~50	36%	Session gate + chain (already compact)
`domain/drupal-standard.md`	842	~120	86%	Decision hierarchy + Starforge + docs links; examples → docs
TOTAL	4,540	~720	84%	—

[!IMPORTANT] 84% reduction in loaded policy LOC — from 5,575 lines loaded per session to ~720 lines of distilled rules. The worked examples (which are the bulk) become BluCity-Docs reference material, not agent context.

4. Gas City Composition Wiring¶

In `pack.toml` (foundation/governance)¶

[pack]
name = "governance"
schema = 2
version = "0.2.0"
description = "Governance pack — shared policy fragments, enforcement checks, Cedar integration"

# Shared prompt fragments — loaded into every agent session
[prompts.shared]
global_fragments = [
  "prompts/shared/work-authority.md",
  "prompts/shared/verify-the-effect.md",
  "prompts/shared/reuse-and-delete-first.md",
  "prompts/shared/agent-identity.md",
  "prompts/shared/delegation-and-policy.md",
  "prompts/shared/git-completion.md",
]

In BluCity `pack.toml` (city root — already imports foundation-governance)¶

# Already exists:
[imports.foundation-governance]
source = "git@gitlab-bluefly:blueflyio/blu/blucity-packs.git//foundation/governance"
version = "sha:..."  # update to version with prompts/shared/

No new import needed — the existing foundation-governance import already wires this pack into the city. When the pack gains prompts/shared/, those fragments flow to all agents automatically via Gas City's pack composition.

Domain Fragment Loading (Drupal agents only)¶

# In organization/agents/drupal/agent.toml:
[agent]
name = "drupal"
append_fragments = ["foundation-governance.prompts/domain/drupal-standard.md"]

5. Vendor Overlay Generation¶

How It Works¶

Gas City's overlay/per-provider/ mechanism materializes vendor-specific files when gc import install runs. The governance pack generates compatibility surfaces:

gc import install
  → reads foundation/governance/overlay/per-provider/claude/.claude/rules/
  → symlinks into BluCity/.claude/rules/
  → GENERATED files, not authored files

What Gets Generated¶

Provider	Output	Source
Claude	`.claude/rules/governance-policy.md`	Concatenation of 6 shared fragments
Codex	`.codex/instructions.md`	Same content, Codex format
Gemini	`GEMINI.md`	Same content, Gemini format
Kiro	`AGENTS.md` (if needed)	Same content

.gitignore¶

# Generated vendor projections — regenerated by gc import install
.claude/rules/governance-policy.md
.codex/instructions.md
# GEMINI.md stays at estate root (loaded via user rules)

[!NOTE] The existing .claude/skills/ is already gitignored for this reason. Vendor projection files are regenerated, not committed.

6. Hook Unification¶

Current State: Two Independent Systems¶

System	Location	Fires For
Estate root `.codex/hooks.json`	Beads + policy enforcement	All Codex sessions
BluCity `.codex/hooks.json`	Gas City prime + drain + mail	BluCity Codex sessions

Target: Gas City Owns Hooks¶

Gas City already has its own hook mechanism (gc prime --hook, gc nudge drain, gc mail check). The Codex hooks in BluCity's .codex/hooks.json are Gas City hooks wearing a Codex costume.

CURRENT:  Codex hooks.json → shell script → gc prime
TARGET:   Gas City hook contract → generates hooks.json per provider

The estate root .codex/hooks.json (Beads + policy) should be evaluated: - bd codex-hook calls → already Gas City (bd is a gc subcommand) - pre-tool-policy-block.sh → candidate for Gas City pre_start hook or Cedar check - session-start-loader.sh (11KB) → candidate for Gas City gc prime equivalent - user-prompt-anti-churn.sh → candidate for Gas City drain/formula guard

7. Codex Agent Replacement¶

Current: 25,628 LOC of Inline TOML Prompts¶

These 9 .codex/agents/*.toml files (from May 5) are pre-Gas City inline prompt definitions. Gas City's pack composition replaces them:

Codex Agent	Gas City Replacement
`oracle-infra.toml` (9,369 LOC)	`gascity.mayor` + `organization.sentinel` + shared fragments
`done-gate.toml` (5,938 LOC)	`gascity.witness` + governance formula
`quality-gate.toml` (3,376 LOC)	`gascity.refinery` + CI enforcement
`drupal-specialist.toml` (1,391 LOC)	`organization.drupal` + domain fragment
`frontend-specialist.toml` (1,393 LOC)	`organization.foundry`
`researcher.toml` (857 LOC)	`kingstown-core.blu` (research mode)
`reviewer.toml` (786 LOC)	`gascity.witness` (review mode)
`test-runner.toml` (752 LOC)	CI / formula — not an agent
`test-writer.toml` (1,766 LOC)	`organization.drupal` + test formula

[!WARNING] Do NOT delete these until Gas City pack composition is proven to cover the same capabilities. Verify each agent's behavior is reproduced by the pack-composed equivalent first.

8. Disposition Summary¶

Artifact	Current LOC	Action	Target LOC
`.claude/rules/` (13 files)	5,575	REPLACE with 6 shared fragments + 1 domain	~720
`GEMINI.md`	300	GENERATE from shared fragments	~720
`.codex/agents/` (9 files)	25,628	REPLACE with Gas City pack agents	0 (pack-composed)
`.codex/hooks.json` (2 files)	148	UNIFY under Gas City hook contract	~50
`HANDOFF-2026-09-14.md`	1,021	ARCHIVE to BluCity-Docs/ledger/	0
`pack-overlays.md` + `overlays/AGENTS.md`	34	MERGE into single project doc	~20
Worked examples (from rules)	~4,000	MOVE to BluCity-Docs Engineering-Standard	—
TOTAL	~33,000	—	~1,500

[!TIP] 95% reduction in governance artifact LOC (33,000 → 1,500). The knowledge isn't lost — worked examples become documentation. What agents load per session drops from 5,575+ to ~720 lines.

9. Migration Sequence¶

[!CAUTION] This is a DESIGN. Do not execute until approved. Do not delete existing files until replacements are proven.

PHASE 4a: Author canonical fragments
  → Write 6 shared fragments + 1 domain fragment in foundation/governance/prompts/
  → Each fragment is the distilled rules from its source cluster
  → Commit to BluCity-Packs, push, create MR

PHASE 4b: Wire Gas City composition
  → Update foundation/governance/pack.toml with global_fragments
  → Update organization/agents/drupal/agent.toml with domain fragment
  → gc import install → verify fragments load

PHASE 4c: Add doctor checks
  → governance-policy-sync doctor check: canonical fragments match vendor projections
  → governance-enforcement-audit: reports rules without mechanical enforcement

PHASE 4d: Generate vendor overlays
  → Create overlay/per-provider/ structure
  → gc import install generates .claude/rules/, GEMINI.md from fragments
  → Verify generated output matches distilled content

PHASE 4e: Archive session handoff
  → Move HANDOFF-2026-09-14.md to BluCity-Docs/ledger/agent-memory/
  → Remove from .claude/rules/

PHASE 4f: Extract worked examples
  → Move ~4,000 lines of worked examples to BluCity-Docs Engineering-Standard
  → Each example becomes a reference page, not loaded agent context

PHASE 4g: Verify and cut over
  → Run gc doctor to validate
  → Verify agent sessions load shared fragments
  → Verify vendor projections are correct
  → Only THEN remove old .claude/rules/ files
  → Only THEN evaluate .codex/agents/ replacement

PHASE 4h: Hook unification (deferred — requires Gas City hook contract verification)

10. Open Questions¶

Does Gas City global_fragments exist in the current version? The docs describe append_fragments per agent. Need to verify the exact mechanism for city-wide shared prompt injection.
Does Gas City overlay/per-provider/ exist today? The docs describe it conceptually. Need to verify gc import install actually materializes these files.
Should the Codex agents (25,628 LOC) be migrated in this phase or a separate one? They're pre-Gas City and enormous, but they're also in a different vendor directory and may still be in active use.
GEMINI.md is loaded via Gemini user rules, not via Gas City. The overlay mechanism generates a file, but it won't be loaded unless the user rules reference it. Should the user rules reference the generated file, or should the Gas City fragments be the authority and GEMINI.md become a thin pointer?