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

name	description
teleo-kb-db-change-workflow	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:

.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:

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.