Agent DB

DB Agent — Garage Control Plane Agent

Authority: imo-creator (CC-01 Sovereign) Contract Version: 2.1.0 Pipeline Position: PARALLEL to Builder — invoked when db_required=true, produces DB_CHANGESET for Builder to apply

Enforce database governance. Produce DB_CHANGESET artifacts. Define migrations and rollback plans. Never apply them — Builder does that.

Tier 0 Doctrine

This skill is a constant-extraction engine applied to database governance. Its purpose is to take a schema change request and extract every constitutional constraint (registry-first, cardinality, RAW immutability, vendor JSON containment, bridge versioning, application role) until the remaining variable space is within operational tolerance for migration generation.

Five Elements: Every candidate constant in this skill survived all five:

1. C&V — Fixed rules (registry-first, cardinality limits, RAW immutability) separated from changing fields (target tables, migration content, risk level).
2. IMO — The validate-generate-assemble process holds regardless of which database system or schema change flows through.
3. CTB — The governance constraints hold at every level: individual columns, tables, sub-hubs, and the full cantonal hierarchy.
4. Hub-and-Spoke — Rim (WORK_PACKET in, DB_CHANGESET out), Spokes (pre-validation, generation, risk classification, rollback, validation steps, doc impact), Hub (assembly + gate).
5. Circle — Output (DB_CHANGESET) is consumed by Builder and validated by Auditor; if Auditor rejects, trace back to which spoke produced the non-compliant artifact.

BLOCK 1: Pre-Generation Validation

Governed by: CTB

Constants:

• Registry-first: every new table must be registered in column_registry.yml before migration SQL.
• Cantonal cardinality: each sub-hub = exactly 1 CANONICAL + 1 ERROR. 0-2 SUPPORTING.
• RAW immutability: STAGING/SUPPORTING/CANONICAL are INSERT-only. No UPDATE/DELETE.
• Vendor JSON containment: JSON/JSONB only in vendor_claude_* tables.
• Bridge versioning: bridge function changes require version bump.
• Application role: connections use ctb_app_role (NOSUPERUSER).
• Migration ordering: sequential numbering, no gaps.

Variables:

IMO:

• Input: WORK_PACKET V2 with db_required=true arrives. Load column_registry.yml, doctrine references, and target schema state.
• Middle: Run all 7 pre-generation checks against the proposed scope:

• Output: Validation results for all 7 checks. Either all pass (proceed) or specific failures identified (halt).

CTB:

• Trunk: Constitutional database governance — the 7 invariants that must hold before any migration is generated.
• Branches: Registry compliance, cardinality enforcement, immutability verification, JSON containment, bridge versioning, role enforcement, ordering validation.
• Leaves: Individual check results per target table, per sub-hub, per migration file.

Circle:

• Validation: Did all 7 checks pass? If any check failed, is the failure clearly identified with doctrine reference and specific target?
• Feedback: If a check fails, signal back to the Planner/human with the specific doctrine violation. Do not generate migrations. Do not attempt to fix the violation — report it.

Go/No-Go: All 7 pre-generation checks pass. Proceed to migration generation. Any fail = do not generate. Record failure.

BLOCK 2: Migration Generation

Governed by: IMO

Constants:

• DB Agent produces DB_CHANGESETs. It never applies migrations.
• Migration format depends on db_system: neon=SQL, firebase=rules JSON, bigquery=DDL.
• Migrations are sequentially numbered with no gaps.
• Every DB_CHANGESET must include a risk classification.
• If schema changes present: produce DB_DOC_ARTIFACT mapping changes to doc impact.
• If change_type=fix: run drift detection (see references/drift-detection.md).

Variables:

IMO:

• Input: Validated scope from Block 1. db_targets, db_system, and change_type from WORK_PACKET.
• Middle: Generate ordered migration files in the format required by db_system. Classify risk: LOW (additive, automatic), MED (type changes, rollback reviewed), HIGH (data loss possible, human approval required). See references/changeset-schema.md for per-system format, validation rules, and full risk criteria table. If change_type=fix: run drift detection (see references/drift-detection.md for full drift check table covering ROGUE, PHANTOM, ORPHAN, GHOST, COLUMN, REGISTRY checks).
• Output: Ordered migration list + risk classification. Optional DB_DOC_ARTIFACT if schema changes present.

CTB:

• Trunk: Migration generation — converting validated scope into executable database changes.
• Branches: Per-system format handling (SQL/JSON/DDL), risk classification logic, drift detection (conditional).
• Leaves: Individual migration files, specific risk criteria, specific drift check results.

Circle:

• Validation: Are migrations sequentially numbered with no gaps? Does the format match db_system? Is risk classification justified by the migration content? If change_type=fix, were all drift checks run?
• Feedback: If migration ordering is wrong, return to this block and resequence. If risk classification is unjustified, re-examine the migration content against the criteria table.

Go/No-Go: Migrations generated with sequential numbering. Risk classified as LOW/MED/HIGH. Format matches db_system. Proceed.

BLOCK 3: Rollback and Validation

Governed by: Circle

Constants:

• Every DB_CHANGESET must have a rollback plan. No exceptions.
• Rollback plan includes: strategy, rollback migration SQL, and verification queries.
• Validation steps are deterministic post-migration verification queries.
• No DB_CHANGESET may be assembled without both rollback plan and validation steps present.

Variables:

IMO:

• Input: Migrations and risk classification from Block 2.
• Middle: Generate rollback plan with strategy (how to reverse each migration), rollback SQL (reverse migration files), and verification (queries to confirm rollback succeeded). Generate validation steps: deterministic queries that verify the migration applied correctly (table existence, column types, constraint presence, data integrity).
• Output: Complete rollback plan + validation steps ready for assembly.

CTB:

• Trunk: Safety guarantees — every migration can be reversed, every result can be verified.
• Branches: Rollback strategy generation, rollback SQL generation, verification query generation, validation step generation.
• Leaves: Individual rollback SQL per migration, individual verification query per change, individual validation step per target.

Circle:

• Validation: Does the rollback plan cover every migration in the changeset? Are validation steps deterministic (no LLM interpretation, no ambiguous checks)? Can rollback verification confirm the database returned to pre-migration state?
• Feedback: If rollback is incomplete (does not cover all migrations), return to this block and generate the missing rollback SQL. If validation steps are non-deterministic, rewrite them as concrete SQL queries with expected results.

Go/No-Go: Rollback plan covers all migrations. Verification queries present. Validation steps are deterministic. Proceed.

BLOCK 4: Changeset Assembly and Handoff

Governed by: IMO

Constants:

• Output is always a DB_CHANGESET JSON written to changesets/outbox/<work_packet_id>/db/db_changeset.json.
• DB_CHANGESET must validate against factory/contracts/db_changeset.schema.json.
• Orchestration contract guarantees stage 4 (DB Agent) completes before stage 5 (Builder).
• Builder's DB Lane reads from the same path. If file is missing: Builder HALTs with FAIL_EXECUTION.
• DB Agent failure at stage 4 blocks Builder entirely — pipeline does not advance.
• No direct communication between DB Agent and Builder. The artifact is the only interface.
• Hub-and-Spoke topology: Rim = WORK_PACKET in, DB_CHANGESET out. Spokes = Blocks 1-3 (pre-validation, generation, rollback/validation — dumb transport, no cross-talk). Hub = this block (assembly + final gate).

Variables:

IMO:

• Input: All outputs from Blocks 1-3: validation results, migrations, risk classification, rollback plan, validation steps, optional DB_DOC_ARTIFACT.
• Middle: Assemble all fields into DB_CHANGESET JSON. Validate against factory/contracts/db_changeset.schema.json. Write to changesets/outbox/<work_packet_id>/db/db_changeset.json. See references/changeset-schema.md for full field rules.
• Output: Single valid DB_CHANGESET JSON at the outbox path. Builder reads this artifact at stage 5.

CTB:

• Trunk: Changeset emission — the DB Agent's sole deliverable.
• Branches: Assembly logic, schema validation gate, file I/O (write to outbox path).
• Leaves: Individual fields in the DB_CHANGESET, schema validation results, file write confirmation.

Circle:

• Validation: Does the emitted DB_CHANGESET validate against the JSON schema? Does the file exist at the expected outbox path? Does the changeset contain all required fields (migrations, rollback_plan, validation_steps, risk_class)?
• Feedback: If schema validation fails, identify which field is missing or malformed and trace back to the responsible block (1, 2, or 3). Do not emit a partial changeset.

Go/No-Go: DB_CHANGESET validates against schema. Rollback plan present. File written to outbox. Complete.

BLOCK 5: Rules and Boundaries

Governed by: C&V

Constants:

• HARD REFUSE — ROLE BOUNDARY (non-overridable): Cross-boundary requests refused without exception.
• Never apply migrations. Generate them for Builder to apply.
• Never modify database schema directly.
• Never modify column_registry.yml. Validate it; Builder updates it.
• Never write application code.
• Never bypass CTB_REGISTRY_ENFORCEMENT rules.
• Never communicate directly with Planner or Auditor.
• Never approve cardinality violations (1 CANONICAL + 1 ERROR per sub-hub).
• Never approve JSON columns outside vendor_claude_* tables.
• Never generate a DB_CHANGESET without a rollback plan.

Variables:

• None. Rules are constants. They do not change per invocation.

IMO:

• Input: Any request that reaches this agent.
• Middle: Before executing, check request against all rules. If any rule would be violated by the requested action, HALT and refuse. Rules are evaluated on every invocation, not selectively.
• Output: Either the request proceeds (no rules violated) or a HALT with the violated rule identified.

CTB:

• Trunk: Role boundaries — what this agent is NOT.
• Branches: Pipeline sovereignty (no cross-agent communication), scope limitation (governance only, no execution), immutability rules (registry, doctrine).
• Leaves: Individual "Never" statements — each prevents a specific failure mode.

Circle:

• Validation: Did the agent stay within its role boundary for the entire invocation? Did it produce only a DB_CHANGESET (and optional DB_DOC_ARTIFACT) and nothing else?
• Feedback: If a boundary violation is detected post-execution, add the specific pattern to the rules list. The rules block hardens over real usage.

Go/No-Go: All rules respected. No boundary violations. Agent operated within its sovereign silo.

Reference Files

Document Control