teleo-infrastructure/.agents/skills/teleo-kb-db-change-workflow/SKILL.md

---
name: teleo-kb-db-change-workflow
description: Use for Teleo canonical Postgres changes, proposal normalization, separate review and apply authority, isolated approve_claim canaries, row-level proof, rollback, and production-apply gating.
---

# Teleo KB DB Change Workflow

## Working Target

Move one reviewed knowledge change from `kb_stage.kb_proposals` to exact
canonical rows without confusing approval with application or silently changing
production.

## State Model

- `pending_review`: staged, not approved, canonical rows unchanged.
- `approved`: reviewed intent exists, but `applied_at` may still be null.
- `applied`: the guarded transaction finished and canonical postflight matches.
- `packet_ready_not_executed`: rehearsed artifacts exist; production is unchanged.

Never infer `applied` from chat text, a packet, a clone, or `status=approved`.

## Canonical Contract

The strict `approve_claim` v2 payload may create:

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

The lifecycle is split across:

- `scripts/kb_proposal_normalize.py`: fail-closed rich intent to strict payload.
- `scripts/approve_proposal.py`: `kb_review` login approves the exact type/payload.
- `scripts/apply_proposal.py`: operator-only `kb_apply` login writes and verifies.
- `scripts/kb_apply_prereqs.sql`: roles, immutable approval row, gate functions,
  ownership, indexes, and exact ACL matrix.
- `scripts/run_approve_claim_isolated_container_canary.sh`: disposable runtime
  proof plus read-only live count/service endpoints.

## Authority Invariants

1. `kb_review` and `kb_apply` are separate `NOINHERIT` login roles with no role
   memberships.
2. `kb_gate_owner` is `NOLOGIN` and owns the immutable approval table and three
   `SECURITY DEFINER` gate functions.
3. The legacy three-argument approval overload must be absent.
4. Review binds DB role, reviewer principal, type, full payload, timestamp, and
   note in one immutable row.
5. Apply locks and compares that snapshot before writes, verifies every
   payload-controlled field and exact table deltas, then finishes the ledger.
6. Existing semantic evidence/edge rows must match approved weights and owners;
   a mismatch rolls back.
7. `kb_apply` remains a trusted operator-only canonical writer. This design does
   not claim resistance to a compromised apply credential.

## Operator Path

1. Read the proposal and canonical target rows.
2. Normalize rich intent; reject malformed, duplicate, lossy, or unsupported
   candidates instead of guessing.
3. Run focused tests:

```bash
.venv/bin/python -m pytest -q \
  tests/test_kb_proposal_normalize.py \
  tests/test_approve_proposal.py \
  tests/test_apply_proposal.py \
  tests/test_kb_apply_prereqs.py
```

4. Run both disposable canaries from the repo root:

```bash
scripts/run_approve_claim_isolated_container_canary.sh \
  --output docs/reports/leo-working-state-20260709/approve-claim-clone-canary-current.json

scripts/run_approve_claim_isolated_container_canary.sh \
  --normalization-json docs/reports/leo-working-state-20260709/helmer-approve-claim-normalization-current.json \
  --output docs/reports/leo-working-state-20260709/helmer-approve-claim-clone-canary-current.json
```

5. Require `status=pass`, every check true, expected deltas equal measured
   deltas, source hashes matching current files, zero live count deltas, stable
   service endpoints, and independent clone/container/workdir cleanup.
6. Treat production deployment, permission migration, worker enablement, and a
   production proposal apply as separate authorization windows.

## Current Proof And Claim Ceiling

The retained generic and Helmer v3 receipts each pass `37/37`. Generic proves
`2/2/2/1/1`; Helmer proves `5/13/17/7/1`. Live read-only endpoint counts stayed
`1837/4145/4670/4916/17/26`, and the gateway stayed on PID `2999690` with zero
restarts during those runs.

This proves current-source behavior in disposable PostgreSQL and unchanged live
count/service endpoints. PR #72 source later auto-synchronized to the VPS
checkout without a gateway restart or profile-source delta; the production
permission migration was not applied, the apply worker remained disabled and
inactive, and Helmer remained unapplied. Checkout synchronization alone is not
proof of any of those later state changes. It does not prove byte-for-byte live
content.

Read `docs/reports/leo-working-state-20260709/approve-claim-clone-canary-current.md`
and both JSON receipts before making a current claim.
Read `docs/reports/leo-working-state-20260709/pr72-vps-auto-deploy-runtime-nonchange-current.md`
before describing the VPS deployment state.