---
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 "<question>"
```

Use narrower bridge commands when needed:

```bash
/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
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb search-proposals "<terms>"
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show-proposal <proposal_id>
/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 "<question>"`;
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 "<entity/framework/claim terms>" --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 Cory 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 Cory-style follow-up: the one proof-changing or admin action that would
   change the answer.

Always include the final line label `Next Cory-style 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."

### Cory Direct-Claim Answer Contract

For Cory-style no-context questions, keep the answer direct but include the
proof language below. These are behavioral examples, not feature changes.

- "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.
- "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`.
- "Did the decision matrix approve this?": start with current/fresh schema
  readback. 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.
- "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?": separate demo tiers. A safe demo can show
  a real staging write to `kb_stage.kb_proposals` and read it back. Canonical
  mutation of `public.claims`, `public.sources`, `public.claim_evidence`, or
  `public.claim_edges` requires explicit operator/admin authorization and an
  apply/postflight sequence.
- "Did editing SOUL.md change canonical identity?": answer `no`. `SOUL.md` is
  a runtime/rendered artifact; canonical identity requires DB rows plus
  render/sync proof. Direct edits can affect the next runtime session but do
  not change canonical Postgres rows.

Every direct-claim answer must include row-level proof vocabulary such as
`current readback`, `row-link audit`, `applied_at`, `kb_stage.kb_proposals`,
`public.*`, and `postflight proof` where relevant. End with exactly one final
line beginning `Next Cory-style 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` (`<claim_id>`);
- when the bridge output includes `claim page: https://leo.livingip.xyz/kb/claims/<claim_id>`,
  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://<argus-host>/kb/claims/<claim_id>`; otherwise name the dashboard
  path `/kb/claims/<claim_id>` 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 <claim_id>` or `search`;
2. fetch evidence and edges with `teleo-kb evidence <claim_id>` and
   `teleo-kb edges <claim_id>`;
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: <what exists in public.*>
Staged proposals: <proposal IDs/statuses>
Rows/edges/evidence needed: <concrete list>
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 <X> into <specific operational question>.
```

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. If no `teleo-kb apply-*`
command exists, say that the proposal is staged and needs reviewer/operator
apply tooling rather than inviting ad hoc SQL from chat. Do not treat a chat
statement, runtime memory, or a 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.
```

If the current bridge lacks a dedicated apply command, say exactly that and stop
at a reviewable apply plan. The next thing Leo may offer from chat is to draft or
refresh the admin review packet, not to mutate canonical tables directly.
