teleo-infrastructure/hermes-agent/leoclean-skills/vps/teleo-kb-bridge/SKILL.md

name	description	version	author	license	metadata
teleo-kb-bridge	Use the VPS Postgres KB bridge before answering questions about claims, evidence, agent beliefs, schema-backed identity, proposal readiness, or KB changes.	1.2.0	m3taversal	MIT	hermes tags related_skills teleo kb postgres claims evidence governance 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:

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

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

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

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

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:

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

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