---
name: teleo-kb-bridge
description: Use the VPS Postgres KB bridge before answering questions about claims, evidence, agent beliefs, schema-backed identity, proposal readiness, or KB changes.
version: 1.2.0
author: m3taversal
license: MIT
metadata:
  hermes:
    tags: [teleo, kb, postgres, claims, evidence, governance]
    related_skills: [leo-synthesis-methods]
---

# Teleo KB Bridge

Postgres is canonical knowledge. Runtime memory, chat, and `SOUL.md` are not
canonical database writes.

## Mandatory Reply Contract

Unless the operator explicitly requests a detailed audit or long-form document,
draft to at most 170 words; the final reply must never exceed 220 words. A
smaller word or line limit is mandatory.

Use this shape:

1. direct answer in the first sentence;
2. at most three short bullets with only the relevant readback, state boundary,
   and current-schema constraint;
3. at most one proof-changing next action.

Do not mirror this skill, enumerate unrelated fields, repeat the answer as a
summary, or turn a direct question into an architecture lecture. Silently
count and shorten the draft before sending it; never send more than 220 words.

## Mandatory Current-Truth Gates

Apply these before drafting the answer or proposing a next action:

1. **Proposal readiness:** `approved` is intent approval, not applyability.
   Read the proposal's `readiness` object. If `review_state` is
   `approved_needs_apply_payload`, normalize into a strict payload and review
   that new packet; never tell the operator to apply the legacy row.
   `approved_contract_present` proves only contract presence, not strict
   validation, production-worker enablement, authorization, or apply.
2. **Source/evidence audit:** `teleo-kb search` and `teleo-kb context` emit the
   selected claims, evidence, edges, and a deterministic retrieval receipt. Read
   each evidence row's `artifact_verification` before describing provenance.
   Never infer that an artifact is missing from a raw `storage_path`; use the
   reported status. `no_source_pointer` means the canonical source row has no
   resolvable locator, while `missing`, `hash_mismatch`, and `verified` describe
   distinct artifact states. An existing claim-evidence link remains canonical
   evidence even when raw-artifact verification is unavailable. Null
   `applied_at` proves only that proposal did not apply; matching canonical rows
   could have another origin.
3. **Shared facts versus agent positions:** store the factual claim once with
   shared evidence. Current agent-owned positions live in `public.beliefs` with
   `id`, `agent_id`, `level`, `statement`, `confidence`, `falsifier`, `rank`,
   `status`, `created_at`, and `updated_at`. The table has no claim-ID foreign
   key and there is no belief-edge table. `public.claim_edges` connects claims,
   never belief rows. `reasoning_tools` are methods and `behavioral_rules` are
   operating rules; neither is generic stance storage.
4. **Write boundary:** extraction creates candidates inside a reviewed proposal,
   not canonical `public.sources` or `public.claims`. Capture a retained artifact,
   URL/storage path, and content hash; reject a chat label or `source_ref` as
   source identity. `teleo-kb prepare-source` is shipped on the VPS for a
   text-like artifact under the private `state/kb-source-inbox` root or a
   supplied strict UTF-8 extraction in that root. It reads
   nearby canonical claims before model extraction. The model selects dense,
   numbered non-empty source fragments; the compiler resolves those IDs back to byte-exact text and
   rejects unknown IDs rather than fuzzy-matching invented prose. It emits a
   private manifest without a DB write. `teleo-kb propose-source` can
   then stage one deterministic `pending_review` packet. Automatic Telegram
   attachment capture and arbitrary tweet fetching are not shipped. Approval
   begins before guarded canonical apply.
5. **Capability boundary:** current `approve_claim` accepts only `claims`,
   `sources`, `evidence`, `edges`, and `reasoning_tools`. It cannot insert
   `behavioral_rules` or `governance_gates`, update beliefs or an existing claim,
   or run a general identity render. Separate unsupported changes for a reviewed
   future capability; never include them in a runnable apply sequence.
   `applied_at` belongs to the proposal receipt, not each inserted row.
6. **Identity and proof:** canonical identity can include `personas`,
   `strategies`, `beliefs`, strategy nodes/anchors, and related governed rows;
   do not reduce it to claims. No active general DB-to-`SOUL.md` renderer
   automation is currently proven. Unchanged table totals also do not prove
   unchanged rows; use row IDs, timestamps, hashes, or fingerprints. Hermes
   `state.db` and session JSONL can preserve continuity across restart. Separate
   handler proof, Telegram-visible delivery, and canonical DB-mutation proof.
7. **Explanation versus relationship:** current `public.claim_edges` has no rationale
   field. A `supersedes` edge records a relationship, not the human explanation.
   Ground the explanation in source/evidence or a separately reviewable claim.
   Do not invent a `retired` status value.
8. **Mixed-packet composition:** facts and disputed interpretations map to
   claims plus sources/evidence; a reusable framework maps to `reasoning_tools`,
   not a claim graph; operating rules map to `behavioral_rules`; evaluative gates
   map to `governance_gates`; agent positions map to `beliefs`. Current
   `approve_claim` can apply only its five supported collections. Keep policy,
   gate, belief-update, and existing-row updates staged until a separate reviewed
   capability is live; never list them in the supported apply order.

## Read Commands

This is the VPS production leoclean surface. Start with:

```bash
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb context "<question>"
```

Treat the emitted `Current Runtime Contracts` / `operational_contracts` block as
binding deployed-code readback. Follow its `required_lead`, schema guards,
capability tier, and reply budget. It overrides recalled or generic architecture.

For `search` and `context`, cite the receipt's `semantic_context_sha256` when an
exact repeatable read matters. `read_consistency.status=stable_wal_marker` means
the read had a stable WAL marker: the database position did not move during the
read. If it did move, the bridge
retries and accepts only an identical semantic context; otherwise it fails rather
than combining rows from ambiguous database states.

The live leoclean profile injects that exact read-only contract automatically
before the model turn. Before delivery, the same snapshot validates the draft.
For contract-covered composition and source-intake questions, an invalid draft
is replaced by a response compiled from that snapshot's mappings, supported
collections, staged collections, and receipt requirements. The replacement is
written into session memory before Telegram delivery, so remembered and visible
answers stay identical. This is database/runtime composition, not repeated
prompt training; do not work around a failed validator by adding examples to
the skill.

Use only the bounded follow-ups relevant to the question:

```bash
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb status
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search "<terms>"
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show <claim_id>
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb evidence <claim_id>
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb edges <claim_id>
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb list-proposals --status all --limit 50
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search-proposals "<terms>" --status all --limit 20
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show-proposal <proposal_id>
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb decision-matrix-status
```

## Source To Proposal

First prepare a retained text-like filesystem document. For a binary artifact,
provide a separate strict UTF-8 extraction with `--text`:

```bash
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb prepare-source \
  --artifact /home/teleo/.hermes/profiles/leoclean/state/kb-source-inbox/source.md \
  --identity document:stable-source-id \
  --source-key stable_source_key \
  --source-type article \
  --title "Stable source title" \
  --locator artifact://stable/source-id \
  --output-dir /home/teleo/.hermes/profiles/leoclean/state/kb-source-preparation/source-id
```

This performs a canonical claim retrieval before model extraction, allows at
most three single-source candidates, caps confidence at `0.75`, binds every
claim/evidence/duplicate judgment to a dense numbered source fragment that is resolved
deterministically to an exact substring, and writes private mode-`0600`
outputs. The concise extracted proposition becomes the candidate claim text;
the exact source wording remains its hash-bound quote and evidence. It performs
no database write. If status is
`no_novel_claims`, inspect the duplicate judgments and do not stage an empty
packet.

For each newly supported document format, run one representative live
preparation before calling it working. Verify the receipt reports both database
and canonical apply as false, every emitted quote is an exact substring of the
retained extraction, and canonical counts remain unchanged. After staging,
verify only one `pending_review` proposal was added and an identical rerun is
idempotent.

After reviewing a `prepared` receipt, stage exactly one reviewable proposal:

```bash
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb propose-source \
  --artifact /home/teleo/.hermes/profiles/leoclean/state/kb-source-inbox/source.md \
  --text /home/teleo/.hermes/profiles/leoclean/state/kb-source-preparation/source-id/extracted-text.txt \
  --manifest /home/teleo/.hermes/profiles/leoclean/state/kb-source-preparation/source-id/source-manifest.json \
  --receipt /home/teleo/.hermes/profiles/leoclean/state/kb-source-receipts/source.json
```

The command is VPS-local, idempotent by deterministic proposal ID, and may write
only `kb_stage.kb_proposals`. Verify the receipt says `canonical counts
unchanged: true`, then use `show-proposal <id>` for readback. Never call this
proof of extraction from Telegram, reviewer approval, or canonical apply.

For direct state questions, run `status` plus the relevant proposal read. Copy a
full proposal UUID when one row answers the question; otherwise copy all five
observed counts:

```text
DB readback: proposal: `PROPOSAL_UUID`; status: `STATUS`; applied_at: `TIMESTAMP_OR_NONE`; readiness: `REVIEW_STATE`.
DB readback: claims: `N`; sources: `N`; claim_edges: `N`; claim_evidence: `N`; kb_proposals: `N`.
```

If decision-matrix tables are absent, say reviewer status is not a
decision-matrix vote. If a bridge command cannot answer a schema question, use
one bounded read-only Postgres inspection and label it as such.

## Current V1 Facts

- Claim types: `structural`, `normative`, `empirical`, `concept`, `meta`.
- Evidence roles: `grounds`, `illustrates`, `contradicts`; evidence links point
  to source rows whose text may live in `public.sources.excerpt`.
- Current `public.sources` stores `id`, `source_type`, `url`, `storage_path`,
  `excerpt`, `hash`, `captured_at`, `created_by`, and `created_at`. It has no
  `author`, `title`, `publisher`, or publication-date column. Retain that richer
  metadata in the review packet until a reviewed schema can store it canonically.
- Edge types: `supports`, `challenges`, `requires`, `relates`, `contradicts`,
  `supersedes`, `derives_from`, `cites`, `causes`, `constrains`, `accelerates`.
- Current v1 has no forecast-resolution fields or `resolves` edge. Preserve the
  original probability and call resolution ambiguous when criteria were absent.
- A Telegram attachment, cache file, or proposal `source_ref` alone does not
  prove canonical evidence from that artifact.
- `artifact_verification.status` distinguishes `verified`,
  `verified_hash_unavailable`, `hash_mismatch`, `missing`, `locator_only`,
  `no_source_pointer`, `remote_locator_only`,
  `rejected_outside_allowlisted_roots`, `ambiguous_multiple_files`,
  `too_large_to_verify`, `unreadable`, and `changed_during_verification`. Never infer `missing` from a raw
  `storage_path` without this verification result.
- Handler success without a Telegram post is handler proof, not
  Telegram-visible delivery. A visible reply proves delivery, not DB mutation.

## Write Policy

Normal chat may capture a real source and stage a reviewable proposal. It may
not mutate canonical `public.*`. Apply requires the matching strict payload,
human review, explicit operator/admin authorization, a supported apply path, a
committed transaction, row-level postflight proof, and non-null `applied_at`.

The strict existing-ID `add_edge` path is live-proven. Rich `approve_claim`
bundles are clone-proven. The production apply worker remains disabled/inactive
unless a fresh service readback proves otherwise. Never offer direct SQL from
chat.

## Telegram Participant Naming

Address `@m3taversal` only as `m3taversal`, exactly. Never infer or reuse a
personal name or nickname. The stored legacy reviewer value `m3ta` may be quoted
only as a database value; it is not a form of address. Resolve every speaker
from the current Telegram update and never carry identity across participants.

## Detailed Reference

Only when the operator explicitly asks for a detailed audit, schema inventory,
external-doctrine workflow, or long-form runbook, read the relevant section of:

```text
/home/teleo/.hermes/profiles/leoclean/skills/teleo-kb-bridge/REFERENCE.md
```

Do not load or repeat the entire reference for normal Telegram questions.
