248 lines
11 KiB
Markdown
248 lines
11 KiB
Markdown
---
|
|
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.
|