---
name: teleo-kb-db-change-workflow
description: Use for Teleo KB proposal normalization, approved-to-canonical DB change workflows, clone rehearsals, apply packets, rollback plans, and row-level proof without silently mutating production.
---

# Teleo KB DB Change Workflow

## Job

Turn approved KB proposal intent into a strict, reviewable, rehearsed, row-level DB change contract.

## Trigger Phrases

- "manipulate the knowledge base"
- "approved proposal apply"
- "canonical DB rows"
- "kb_stage to public"
- "claim/source contract"
- "rollback rehearsal"
- "production apply packet"

## State Model

Use these states exactly:

- `proposed`: draft or staged proposal text exists.
- `pending_review`: proposal exists but is not approved.
- `approved`: reviewer approved intent; canonical DB may still be unchanged.
- `applied`: canonical row mutation happened and was read back.
- `not_applied`: no canonical mutation exists.
- `packet_ready_not_executed`: SQL packet and rehearsal proof exist, but production was not changed.

## Current Table Contract

Core canonical tables used in July 9 work:

- `public.claims`
- `public.sources`
- `public.claim_edges`
- `public.claim_evidence`
- `public.reasoning_tools`

Staging table:

- `kb_stage.kb_proposals`

## Required Workflow

1. Fetch proposal and status from live DB.
2. Normalize proposal payload into planned rows.
3. Preserve reviewer/caveat text as source/evidence/proposal body context.
4. Reject or block unsupported edge types, unknown targets, and schema gaps unless a reviewed mapping overlay exists.
5. Generate rollback-only SQL first.
6. Run live rollback rehearsal in a transaction.
7. Run disposable clone commit rehearsal.
8. Generate production packet only after clone proof passes.
9. Do not execute production commit unless explicitly authorized.
10. If production commit is authorized later, run preflight, commit, postflight, and service stability readback.

## Current Important Proposals

- `00957f6c-9883-4015-95a4-6b09367efb0e`: strict `add_edge` canary, applied.
- `8dfedb3f-3aa4-4200-970f-4c0016f6869f`: live Telegram staged proposal, pending review at the retained snapshot.
- `14fa5ecc-ac7a-41c1-807d-a2e85b936617`: approved rich proposal, mapped subset packet-ready, not production-applied.
- `ac036c9d-20a0-4ffe-881f-57d6b7bacf22`: approved rich proposal, mapped subset packet-ready, not production-applied.
- `a64df080-8502-42e2-98f4-9bbdecb8da73`: approved Helmer 7 Powers proposal, plan generated for reasoning tool plus claims/sources/edges; continue with rehearsal/packet proof.

## Claim Ceiling

Clone proof is not production apply. A packet file is not a DB change. Production apply requires explicit authority and postflight row readback.

## Validation

Run focused tests after planner/packet changes:

```bash
uv run --extra dev ruff check scripts/kb_rich_proposal_creation_plan.py scripts/kb_rich_proposal_apply_packet.py tests/test_kb_rich_proposal_creation_plan.py tests/test_kb_rich_proposal_apply_packet.py
uv run --extra dev pytest tests/test_kb_rich_proposal_creation_plan.py tests/test_kb_rich_proposal_apply_packet.py
```
