239 lines
12 KiB
Markdown
239 lines
12 KiB
Markdown
---
|
|
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` searches claims and identity
|
|
context, not canonical source rows. Use `evidence <claim_id>` or a bounded
|
|
read-only `public.claim_evidence` to `public.sources` join. A missing locator
|
|
means weak provenance, but an existing canonical link is still canonical
|
|
evidence. 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.
|
|
|
|
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.
|
|
- 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.
|