--- name: teleo-kb-bridge description: Use the VPS Postgres KB bridge before answering questions about claims, evidence, edges, schema-backed soul/context, KB approval, or KB edit workflow. version: 1.0.0 author: m3taversal license: MIT metadata: hermes: tags: [teleo, kb, postgres, claims, evidence, governance] related_skills: [leo-synthesis-methods] --- # Teleo KB Bridge The canonical Teleo knowledge base is Postgres, not runtime memory. This is the VPS production leoclean surface. Before answering a KB-specific question, run the local bridge: ```bash /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb context "" ``` Use narrower bridge commands when needed: ```bash /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb status /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search "" /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb evidence /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb edges /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb list-proposals /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search-proposals "" /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show-proposal /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb decision-matrix-status ``` ## Answer Discipline For KB questions, prefer the bridge over raw database access. A good default is: 1. `teleo-kb context ""`; 2. at most three `show` / `evidence` / `edges` / `show-proposal` follow-ups for the most relevant IDs; 3. final answer with what is grounded, what is weak, and what evidence or proposal would improve it. For no-context direct claims such as "Is X in Leo now?", "did the DB change?", "did the decision matrix approve this?", or "is it still just proposals?", do not stop at `search` or default `list-proposals`. Run the status-specific proposal and governance readbacks needed to avoid overclaiming: ```bash /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb list-proposals --status all --limit 50 /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search-proposals "" --status all --limit 20 /home/teleo/.hermes/profiles/leoclean/bin/teleo-kb decision-matrix-status ``` If `decision-matrix-status` says the matrix tables are absent or incomplete, do not infer matrix approval from proposal rationale, reviewer notes, or `kb_stage.kb_proposals.status`. Say the matrix approval path is not proven and fall back to proposal status plus canonical `public.*` readback. If `search-proposals` finds an `approved` proposal with `applied_at` empty, say it is approved/staged or packet-ready but not canonical. Do not answer "missing" merely because default `list-proposals` did not show approved rows. For these no-context direct claims, use this compact answer shape so the operator gets the expected follow-up without needing to ask twice: 1. Direct answer: yes/no/partly, with the truth ceiling. 2. Readback used: the exact bridge commands or row facts checked. 3. Canonical vs staged split: name `public.*`, `kb_stage.kb_proposals`, status, proposal id, and `applied_at` when relevant. 4. Next proof-changing follow-up: the one proof-changing or admin action that would change the answer. Always include the final line label `Next proof-changing follow-up:` for a no-context direct-claim answer. Do not omit it just because the answer seems complete. If the proof-changing action is applying a proposal to canonical `public.*`, say that apply requires explicit operator/admin authorization and should not be run from normal chat without that authorization. Use explicit no-overclaim wording when the canonical DB did not change: "I cannot claim canonical DB changed until `public.*` readback plus `applied_at`/postflight proof says it changed." ### Telegram Participant Naming Contract - Address `@m3taversal` only as `m3taversal`, exactly. Do not shorten it, infer a personal name, or substitute a name from memory, a session header, a soul document, another chat, or another participant's message. - Resolve the current speaker from the current Telegram update. Never carry a participant identity across sessions or assign one participant's identity to another user who replies or tags an account. - When the visible sender is ambiguous, avoid direct address or use only the exact visible Telegram handle. Ask for clarification only if identity is required to perform the requested action. - The legacy reviewer value `m3ta` may be quoted only as an exact database row value, with wording such as `stored reviewed_by_handle: m3ta`. It is not a form of address and does not authorize a nickname. - Keep answer labels neutral. Never put a participant's name in a standard follow-up label. ### Operator Direct-Claim Answer Contract For m3taversal-style no-context questions, keep the answer direct but include the proof language below. These are behavioral examples, not feature changes. Before describing current database objects, separate current v1 schema from proposed architecture. Current `public.claims` has `id`, `type`, `text`, `status`, `confidence`, `tags`, `created_by`, `superseded_by`, `created_at`, and `updated_at`; it has no `body`, generic metadata, or forecast-resolution column. Current `public.sources` has `id`, `source_type`, `url`, `storage_path`, `excerpt`, `hash`, `captured_at`, `created_by`, and `created_at`; it has no author/channel/date fields. Current accepted claim-edge types are `supports`, `challenges`, `requires`, `relates`, `contradicts`, `supersedes`, `derives_from`, `cites`, `causes`, `constrains`, and `accelerates`. Do not present a proposed v3 field, table, edge type, or policy as shipped. If the requested representation does not fit current v1, state the gap and stage a separate schema proposal before proposing data that depends on it. Current `public.claim_evidence` has only `claim_id`, `source_id`, `role`, `weight`, `created_by`, and `created_at`. Its accepted roles are `grounds`, `illustrates`, and `contradicts`. It has no excerpt, excerpt anchor, rationale, or generic metadata column; source text belongs in `public.sources.excerpt`. Current `public.claim_edges` has only `id`, `from_claim`, `to_claim`, `edge_type`, `weight`, `created_by`, and `created_at`. Both endpoints are claim IDs, so do not claim that a `reasoning_tools` row is directly connected through `public.claim_edges`. For heterogeneous research packets, map only to structures proven in the current schema: - factual observations and disputed interpretations may become separate `public.claims` rows with source/evidence links and valid claim-to-claim edges; - a reusable framework may become a `public.reasoning_tools` row, but the current schema has no generic reasoning-tool-to-claim edge and no shipped `concept_maps` or `claim_concept_map_links` table; - `public.governance_gates` can store an evaluative gate with `name`, `criteria`, `evidence_bar`, and `pass_condition`; it is not a generic behavioral-rule or policy table, so state a schema gap when a governance rule does not fit that contract; - a belief correction may create a new claim, a valid `supersedes` edge, and set the old claim's `superseded_by` column. `superseded_by` is a column, not an edge type. Extraction and review do not write candidate material into canonical `public.sources` or `public.claims`. Keep source candidates, extracted claims, deduplication findings, contradictions, and proposed rows in the reviewed proposal payload. A guarded apply may then create or reuse canonical source rows before inserting the packet's dependent claims, evidence links, edges, and supported context rows in one validated transaction. Count receipts are packet-specific. The five values in the standard count readback must all be observed, but they do not all need to change. Before offering apply, validate the proposal's strict `apply_payload`; after apply, prove the declared row IDs, the expected table-specific deltas, a committed transaction, and a non-null `applied_at`. For an existing-claim/existing-source evidence attachment, only `claim_evidence` may increase. For an edge-only packet, only `claim_edges` may increase. Updating a proposal status need not increase the proposal count. Never use `all five counts increased` as a universal success condition. - "Did we actually update the KB?": answer `partly` only when current readback shows `applied_at` rows and canonical `public.*` rows. Otherwise say `mostly still proposals`; list applied, approved-but-not-applied, pending, and canceled counts. Always include the state sentence `Approved is not the same as applied`; for rows with empty apply timestamps, say `applied_at: NULL` or `no applied_at`, and call them `not applied`. Before offering apply as the next action, validate that the target has a matching strict `apply_payload`; otherwise offer to rebuild and review that payload first. - "Is Helmer's 7 Powers in Leo now?": answer `no, not canonical` unless `public.sources`, `public.claims`, evidence, edges, and any reasoning-tool rows exist. If proposal `a64df080` is approved with empty `applied_at`, call it `approved/staged or packet-ready but not canonical`. Do not jump directly from reviewer approval to authorization: first validate or rebuild the matching strict payload, then review, authorize, apply, and postflight it. - "Did the decision matrix approve this?": start with current/fresh schema readback. For this question, run both `decision-matrix-status` and `status`, then use the complete numeric count receipt. If `matrix_voters`, `proposal_votes`, or `proposal_decisions` are absent, say the decision-matrix path is not shipped; reviewer approval in `kb_stage.kb_proposals` is not a matrix vote. Include this compact sentence: `Fresh readback: the decision-matrix schema is absent; reviewer status is not a decision-matrix vote.` If the operator wants the reviewer-only path, validate the proposal's strict payload before offering authorization. - "Are proposals stuck because documents point at the wrong source rows?": do not answer as a single-cause `yes`. Say `not just pointer mismatch`: raw files, Telegram refs, document evaluations, proposal `source_ref`/logical source keys, and canonical `public.sources` rows are different layers. The missing proof is a row-link audit plus guarded apply contract. - "Can I demo Leo changes the KB?": lead with `staging yes, canonical KB change not safe to demo from chat`. Include `demo tier` language. A safe demo can show a real staging write to `kb_stage.kb_proposals` and read it back. Say exactly: `Approved is not the same as applied.` Canonical mutation is not provable from chat alone and is not a normal chat command. State the exact current tier: the strict existing-ID `add_edge` path is live-proven; guarded `approve_claim` bundles and the rich packet set are clone-proven behind separate reviewer and apply roles; the production permission migration and apply worker remain disabled. Current approved legacy packets without strict `apply_payload` are not worker-applyable. A canonical demo therefore still requires explicit operator/admin authorization, the matching reviewed apply path, and retained before/after postflight readback. Never suggest applying the strict canary `add_edge` path to an approved legacy proposal unless that proposal itself has a matching strict `add_edge` payload with two existing canonical claim IDs. The safe default follow-up is a new staging canary or a separately reviewed strict `add_edge` canary. Never collapse that into the false global statement that no apply tooling exists. - "Did editing SOUL.md change canonical identity?": answer `no`. `SOUL.md` is a runtime/rendered artifact, not canonical Postgres, not the source of truth, not a canonical commit, and not collective truth; canonical identity requires DB rows plus render/sync proof. Direct edits can affect the next runtime session but do not change canonical Postgres rows. Always include a row-level proof sentence for this case: `Row-level proof would require current readback of new or updated row IDs in public.claims, public.sources, public.claim_evidence, public.claim_edges or identity tables, plus postflight/render-sync proof; without those rows, canonical identity is unchanged.` Before every direct-claim answer, run a fresh bridge read. Use `status` for the complete numeric count template, `search-proposals` followed by `show-proposal` for a named proposal, and `decision-matrix-status` for matrix questions. If those bridge commands do not return the exact canonical counts needed for the question, use the documented read-only Postgres fallback. Never invent or reuse a stale count. Every direct-claim answer must contain one compact line beginning `DB readback:` and copy either (a) a full UUID plus observed `status` and `applied_at`, or (b) exact observed counts for the relevant `claims`, `sources`, `claim_edges`, `claim_evidence`, and `kb_proposals` tables. Short eight-character IDs and phrases such as `current readback` are not structured proof by themselves. Copy exactly one of these formats, replacing every all-caps token with a value from the current tool call: ```text DB readback: proposal: `PROPOSAL_UUID_36_CHARS`; status: `OBSERVED_STATUS`; applied_at: `OBSERVED_TIMESTAMP_OR_NONE`. DB readback: claims: `N`; sources: `N`; claim_edges: `N`; claim_evidence: `N`; kb_proposals: `N`. ``` Never shorten a UUID: it must contain all 36 characters and four hyphens. Use `none` for `OBSERVED_TIMESTAMP_OR_NONE` when the database value is `NULL`, and optionally add `(database NULL)` after the template. Do not paraphrase a count as `total proposals`, omit a label, or substitute prose for either template. If using the count template, all five values must be observed integers; `N/A` and `see public.*` are invalid and the line is not evidence. If the first read does not expose every required value, run another bounded read-only bridge command before answering. Prefer the proposal template when one unambiguous proposal answers the question; otherwise use the complete count template. Before returning the answer, verify that the literal `DB readback:` line is present and complete. If it is missing, do not finalize the response; run the bounded read-only bridge command needed to fill it. Also use row-level proof vocabulary such as `row-link audit`, `row IDs`, `new or updated rows`, `public.*`, and `postflight proof` where relevant. End with exactly one final line beginning `Next proof-changing follow-up:` that asks for or offers the next proof-changing action. ## Telegram Rendering Make KB answers easy to scan in Telegram: - wrap claim IDs, proposal IDs, edge types, table names, statuses, counts, and command names in backticks; - when citing a specific claim, include both the claim headline and the claim ID, for example: `claim text` (``); - when the bridge output includes `claim page: https://leo.livingip.xyz/kb/claims/`, copy that URL into the answer so Telegram users can open the claim, body, evidence, and edges directly; - when a dashboard URL is available, include the canonical claim page as `https:///kb/claims/`; otherwise name the dashboard path `/kb/claims/` so the operator can open the claim, body, evidence, and edges; - prefer short sections such as `Claim`, `Body readback`, `Edges`, `Evidence`, and `Proposal` instead of dense paragraphs. Use raw `docker exec ... psql` only as a narrow read-only fallback when the bridge cannot answer a schema or implementation-status question. If you use that fallback, say it was a read-only inspection. Do not present raw SQL as the normal user workflow. ## Claim / Body / Concept Map Loop When a user challenges a claim as too broad, too light, unfalsifiable, or poorly linked, do this loop: 1. fetch the headline claim with `teleo-kb show ` or `search`; 2. fetch evidence and edges with `teleo-kb evidence ` and `teleo-kb edges `; 3. separate what the KB actually says from your synthesis; 4. decide whether the right change is: attach evidence, add edges, revise the claim, supersede the claim, split the claim into multiple claims, or create a concept-map/reasoning-tool proposal; 5. stage a reviewable proposal when the requested correction is clear enough. For "was this implemented?" or "did you apply that?" questions, answer in this shape: ```text Status: applied | pending | missing | partially applied Canonical rows: Staged proposals: Rows/edges/evidence needed: Next admin action: approve/apply the proposal, request edits, or create the missing proposal. ``` Do not call an approved proposal "implemented" until canonical `public.*` rows and edges show the applied state. ## External Doctrine Contributions When asked to help with another project's declaration, constitution, doctrine, manifesto, GitHub issue, or PR, do not export Teleo doctrine as if it is the target project's own position. Use the target project's native language first. If the external text says phrases like `no single voice can own understanding`, `purpose precedes capability`, or another local principle, treat those as the wedge. Frame Leo's contribution as: ```text This extends your own principle into . ``` Prefer issue-before-PR unless the operator explicitly authorizes a PR. The issue should ask a concrete question, identify the gap, and invite the target community to decide whether they want draft language. Link Teleo analysis only as one reference, not as controlling doctrine. Consent is action-specific. Leo may draft, critique, and propose language in chat. Leo should not sign, post, submit, open an issue/PR, or speak for Teleo publicly without explicit operator authorization for that exact public action. ## Memory vs KB Rule Do not treat runtime memory as canonical truth. ```text agent memory = local/runtime continuity Postgres KB = canonical collective knowledge ``` If a correction changes collective truth, it belongs in the KB graph, not only runtime memory. ## VPS DB Objects Relevant DB objects live in the VPS Postgres container and should normally be reached through `teleo-kb`: - `kb_stage.kb_proposals` - durable proposal ledger; - `kb_stage.pending_kb_proposals` - proposals with `status = 'pending_review'`; - `kb_stage.document_evaluations` - lightweight document evaluation decisions; - `public.claims`, `public.sources`, `public.claim_evidence`, `public.claim_edges` - canonical tables. ## Write Policy Canonical KB writes are locked. The bridge can create reviewable proposals, but it does not directly mutate canonical `public.*` rows from normal chat. If a reviewer explicitly asks for proposal status reconciliation or canonical application, inspect the proposal first, use the narrowest available bridge or admin apply path, and retain before/after readback. The normal chat bridge does not expose `teleo-kb apply-*`, but the repository contains a live-proven strict existing-ID `add_edge` path and clone-proven guarded `approve_claim` tooling. Name which exact operation/tier is available, and say when the production permission migration, worker, strict payload, or explicit authorization is still missing. Do not invite ad hoc SQL from chat or treat a chat statement, runtime memory, or staged proposal as canonical truth. Never end a normal Telegram answer by offering to run direct `INSERT`, `UPDATE`, or transaction SQL from chat. Even if the user is authorized, the product flow is review-first: ```text Next admin-panel action: show the staged proposal, dependency groups, and before/after rows; let a reviewer approve, reject, edit, or run a dedicated apply tool with retained readback. ``` Because the current chat bridge has no apply command, stop at the exact reviewed operator path and its authorization boundary. The next thing Leo may offer from chat is to draft or refresh the admin review packet, not to mutate canonical tables directly.