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

---
name: teleo-kb-bridge
description: Use the GCP Cloud SQL 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, cloudsql, claims, evidence, governance]
    related_skills: [leo-synthesis-methods]
---

# Teleo KB Bridge

The canonical Teleo knowledge base is Postgres, not runtime memory.

This is the GCP parallel leoclean surface. The local bridge command is still the
only path Leo should use directly:

```bash
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb context "<question>"
```

On GCP, `teleo-kb` routes to the Cloud SQL wrapper. Do not use raw
container-Postgres commands from the VPS playbook; those are not valid on the
GCP VM.

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 "<terms>"
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb context "<question>"
/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
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb propose-core-change --proposal-type revise_claim --target-kind claim --target-ref "<claim id or description>" --proposed "<replacement>" --source-ref "<telegram/chat/source ref>" --rationale "<why this should be reviewed>"
```

## Answer Discipline

For non-live questions, answer from the Cloud SQL KB after a bounded read. A
good default is:

1. `teleo-kb context "<question>"`;
2. at most three `show` / `evidence` / `edges` follow-ups for the most relevant
   IDs;
3. final answer with what is grounded, what is weak, and what evidence 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 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`.
- "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. 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.`
- "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 on VPS; guarded
  `approve_claim` bundles and the rich packet set are clone-proven behind
  separate reviewer and apply roles; equivalent GCP execution is not yet
  proven. 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 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. 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.
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` (`<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.

Do not browse the public web just because the KB has evidence gaps. If the user
asks for current Twitter/X, current market activity, today's news, or another
fresh external read, use the configured current-source path if it exists. If it
does not exist, say the fresh external source is unavailable from this runtime
and answer from cached/canonical context with an explicit freshness caveat.

## When To Use This

Use this bridge before answering when the user asks:

- what the KB says;
- whether a claim is approved, grounded, contradicted, or superseded;
- what evidence supports a claim;
- which claims support/challenge/relate to another claim;
- how to approve/edit/retire/supersede a claim;
- what the schema-backed soul/context says about roles, peers, blindspots, strategy, rules, or reasoning tools.

## 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
Cloud SQL / Postgres KB = canonical collective knowledge
```

If a correction changes collective truth, it belongs in the KB graph, not only
runtime memory.

## GCP DB Objects

Relevant DB objects are reached through `teleo-kb` on GCP:

- `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.

When a user says they want to change a core Teleo claim, strategy, identity,
role, telos, framework, belief, or reasoning tool, stage it in Cloud SQL:

```bash
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb propose-core-change \
  --proposal-type revise_claim \
  --target-kind claim \
  --target-ref "<claim id if known, otherwise a precise target description>" \
  --current "<current claim if known>" \
  --proposed "<proposed replacement/correction>" \
  --evidence "<source, message, document, or reason>" \
  --originator "<human handle>" \
  --channel telegram \
  --source-ref "<chat/message/source reference>" \
  --rationale "<why this should be reviewed>"
```

Use `--proposal-type revise_strategy` for strategy-level changes. The command
writes a `kb_stage.kb_proposals` row with `pending_review` status. It does not
mutate canonical `public.*` rows and does not write runtime memory.

After staging, read it back:

```bash
/home/teleo/.hermes/profiles/leoclean/bin/teleo-kb show-proposal <proposal_id>
```

A good Telegram reply after staging should say:

```text
I staged this as a KB proposal, not runtime memory.
Proposal: <id>
Status: pending_review
Next: reviewer approves/applies or requests changes.
```

## Applying Approved Changes

The default Telegram path does not apply approved proposals into canonical
truth. Application requires a reviewer/operator workflow. On GCP, do not suggest
raw container shell commands. Prefer one of:

1. use a dedicated `teleo-kb apply-*` command if the bridge exposes one;
2. use a reviewed migration/PR workflow;
3. use an explicit operator-approved Cloud SQL apply script with retained
   before/after readback.

When applying is requested, inspect `teleo-kb --help` and the proposal first,
then state the exact available apply path and proof tier. The normal chat bridge
does not expose an apply command, but repository apply tooling exists; VPS
existing-ID apply is live-proven, richer bundles are clone-proven, and GCP
execution remains unproven. Name the missing production migration, worker,
strict payload, authorization, or GCP proof instead of saying globally that
apply tooling does not exist.