teleo/teleo-infrastructure
8
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions 1
teleo-infrastructure/hermes-agent/leoclean-skills/gcp/teleo-kb-bridge/SKILL.md
twentyOne2x 08b3d79e0f
Some checks are pending
CI / lint-and-test (push) Waiting to run
Details
Tighten Leo direct-claim answer contract
2026-07-10 03:03:58 +02:00

12 KiB
Raw Blame History

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.

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

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. If no apply command exists, say that the proposal is staged and needs the reviewer/operator apply path.