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

name	description	version	author	license	metadata
teleo-kb-bridge	Use the GCP Cloud SQL KB bridge before answering questions about claims, evidence, edges, schema-backed soul/context, KB approval, or KB edit workflow.	1.0.0	m3taversal	MIT	hermes tags related_skills teleo kb postgres cloudsql claims evidence governance 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:

/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:

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

Lead with the answer. Unless the operator asks for a detailed audit, keep the whole reply under 220 words and end with one proof-changing follow-up. Do not turn a direct operational question into an architecture lecture.

Postgres is canonical knowledge, but it is not the only input to current reply behavior. Deployed skills, runtime configuration, rendered SOUL.md, Hermes session state, and current conversation context can also change an answer. Unchanged canonical counts therefore do not prove that no runtime behavior changed. Hermes state.db and session JSONL provide durable continuity; do not say a restart necessarily erases every prior-session fact. Separate these proof tiers explicitly:

• handler or temporary-profile success with no Telegram post is handler proof, not Telegram-visible delivery proof;
• a Telegram-visible reply proves delivery and reply behavior, not canonical DB mutation;
• canonical mutation requires row-level public.* readback and the matching applied proposal receipt.

Leo may capture a source and stage a reviewable proposal when the operator asks for knowledge intake. Staging is not canonical apply and does not require the canonical-apply authorization. Approval is required before the guarded apply step. Never manufacture a source row from a temporary memory label, chat label, or proposal pointer; resolve a real URL, storage path, file hash, or retained artifact first.

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:

/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. A public.claim_evidence link from a claim to a public.sources row is canonical evidence even when that source row has no url or storage_path. Describe a missing locator as weak or citation-only provenance, or say the evidence is not traceable to the raw artifact. Do not call the canonical link non-canonical or ungrounded solely because the locator is missing.

A Telegram attachment, extracted file, or proposal source_ref does not by itself prove canonical evidence from that attachment. That proof requires a public.sources row representing the attachment and a public.claim_evidence link from the claim to that source row. Audit those rows before attributing the claim's canonical evidence to the attachment.

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:

• claims, sources, and evidence links are shared knowledge objects; an agent's confidence, stance, or position belongs in agent-specific belief/position structures rather than duplicate agent-authored copies of the same claim;

• 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;

• a behavioral or operating rule belongs in the existing public.behavioral_rules table, whose rule contract includes agent_id, category, rank, rule, and rationale;

• an evaluative gate belongs in public.governance_gates, with name, criteria, evidence_bar, and pass_condition; do not flatten a behavioral rule into this gate table;

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

The current strict approve_claim contract accepts only claims, sources, evidence, edges, and reasoning_tools collections. It does not insert behavioral_rules or governance_gates, update an existing claim's status or superseded_by, or write arbitrary soul/context rows. Both policy tables already exist; the missing piece is a separate reviewed apply capability for them, not a generic schema-table gap. A correction packet may insert the new claim and a valid supersedes edge, but retiring/updating the existing old claim needs a separately reviewed apply capability. Do not describe any of those unsupported writes as part of one atomic approve_claim transaction.

Use the current claim taxonomy unless a reviewed taxonomy change explicitly authorizes a new value. The live values are structural, normative, empirical, concept, and meta; do not invent observation, hypothesis, or belief as current public.claims.type values. Current public.reasoning_tools has id, agent_id, name, description, category, and created_at; criteria or steps may be described inside description, but they are not separate structured columns. When describing evidence, say that public.claim_evidence links a claim to a source row whose text may live in public.sources.excerpt; never say the evidence row stores or carries the excerpt.

Current v1 has no shipped forecast-resolution fields or forecast-resolution edge type. Preserve the original probability and its timestamp. Do not overwrite historical confidence, invent resolution criteria after the fact, or claim a resolves edge exists. If a forecast lacks precommitted criteria, call the resolution ambiguous and stage any new forecast mechanism as a separate schema proposal.

• "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:

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:

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.

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:

/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:

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

A good Telegram reply after staging should say:

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.