canon/technical.md

technical.md — how Savante runs

The complete mechanics: file formats, harness behavior, the verdict contract as a parseable API, and the wiring for each service mode.

1. Repository layout

.claude/agents/savante.md      the charter — canonical, installable
.claude/skills/sagi/SKILL.md   the /sagi skill — canonical, installable
savante.md                     top-level mirror of the charter (readable copy)
sAGI.md                        the sAGI definition + full skill text
README.md · explanation.md · technical.md · usage.md · SAVANTE_AS_A_SERVICE.md

The two .claude/ files are the only functional artifacts. Everything else is documentation. If the top-level mirrors and the .claude/ files ever disagree, the .claude/ files win — they are what the harness executes.

2. The agent file format

.claude/agents/savante.md is a Claude Code subagent definition: YAML frontmatter + markdown body.

---
name: savante          # the agent type name used by the Agent tool
description: >         # WHEN to delegate — the orchestrator reads this
  SAVANTE (SAGI) — chairman-tier strategic oversight ...
tools: Read, Grep, Glob, Bash   # tool allowlist — the authority boundary
---
# body = the agent's entire system prompt

Harness behavior that matters:

• Registration: Claude Code scans .claude/agents/*.md (project) and ~/.claude/agents/*.md (user) at session start. A file created mid-session registers for the next session — hence the skill's fallback path.
• Tool allowlist: Read, Grep, Glob, Bash gives Savante full read access plus the ability to run verification (tests, builds, git log, greps). No Edit, no Write, no Agent — read-only oversight is enforced by the harness, not by the prompt. Bash can still mutate in principle; the charter forbids it and the allowlist removes every purpose-built write tool.
• Context isolation: the subagent gets its own context window. It can read an entire repository and return only the verdict; the caller's context receives nothing else.
• Model inheritance: no model: key — Savante runs on whatever model the session runs on (frontier or local). This is deliberate: the doctrine forbids model pinning; the charter must be model-portable.

3. The skill file format

.claude/skills/sagi/SKILL.md: YAML frontmatter (name, description — the description doubles as the trigger index) + markdown body of instructions the orchestrator follows when the skill is invoked via /sagi or a trigger phrase. The body encodes the launch procedure, the fallback (charter-adoption by a general-purpose agent when savante is unregistered), the verification mandate ("run the tests... actual results only"), and the relay obligation (subagent reports are invisible to the user; the orchestrator must restate the verdict).

4. The verdict contract (parseable API)

Every review returns, in order:

FINDINGS        evidence per load-bearing claim (file:line), plus
                "not yet known" entries each naming the deciding experiment
VERDICT:        APPROVE | APPROVE_WITH_CONDITIONS | REJECT | DEFER
RATIONALE:      2–5 sentences, board-minute style
CONDITIONS:     numbered; each independently verifiable
RISKS WATCHED:  one or two named risks

Machine consumption: the verdict line is grep-stable —

result=$(claude -p "..." )
echo "$result" | grep -qE '^\*{0,2}VERDICT\*{0,2}: *APPROVE' || exit 1

DEFER is reserved for decisions requiring the operator (Professor / OVERLORD) signature — treat it as "block and page a human," not as failure.

5. Service-mode wiring

Interactive — /sagi <target> or "have savante review " inside a Claude Code session. Nothing to wire.

Headless / CI gate — GitHub Actions sketch:

- name: Savante review gate
  run: |
    out=$(claude -p "Invoke the sagi skill: review the diff of this branch
      against main. Print ONLY the verdict block." \
      --allowedTools "Read,Grep,Glob,Bash")
    echo "$out"
    echo "$out" | grep -qE 'VERDICT.*: *APPROVE' # WITH_CONDITIONS also matches APPROVE_
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Tighten the grep to APPROVE$ if conditions must block. Post CONDITIONS as PR comments in a follow-up step if desired.

Agent SDK / API endpoint — load the charter body (strip frontmatter) as the system prompt; run an agentic tool loop restricted to read-only filesystem tools over the target checkout; require the verdict contract as output. Load the charter from disk at request time so service and repo never drift. A natural mindX home: POST /savante/review {target, question} on the backend, emitting a savante.verdict catalogue event.

Scheduled — cron a headless run over the week's diff; one verdict per subsystem. The standing-audit mode: rarely intervenes, always watching.

6. Duplication procedure

git clone https://github.com/cryptoAGI/savante
cp    savante/.claude/agents/savante.md  <target>/.claude/agents/
cp -r savante/.claude/skills/sagi        <target>/.claude/skills/

Adapt only the charter's "Canon you measure against" section to the target repo's doctrine documents (the skill's fallback line reads the repo-relative .claude/agents/savante.md; change it only if you install the charter elsewhere — never to an absolute path, see §7 step 1). The epistemology, verdict contract, and standing constraints are the invariant core. With no canon listed, Savante still functions — it measures claims against the code itself.

7. The persona, the ledger, and the binder

These binding files sit beside the two .claude/ artifacts (eight of them on 2026-09-03; the list below is as of 2026-09-14). None of them changes §1: the two .claude/ files remain the only functional artifacts of the service, and if a top-level mirror ever disagrees with them the .claude/ copy wins (§1, lines 16–18 above).

savante.persona             SOURCE OF TRUTH — the mindX persona; carries the
                            `token` block (:186) and the `task` block (:565);
                            shape expanded from the draiml.persona founder template (:7)
savante.agentcard.json      DERIVED — the EIP-721 / ERC-8004 card
savante.commitments.json    DERIVED — the digest ledger (sha256, CIDv1, doctrine root)
savante.thot.json           DERIVED — the THOT manifest (sagi.thot_manifest/1)
bind/savante_bind.py        the OPERATOR's binder: writes the three derived files
                            (card, ledger, manifest)
bind/savante_verify.py      the holder's checker: recomputes and compares
bind/savante_publish.py     offline: prints mint parameters from the verified
                            bundle; signs, uploads and writes nothing
bind/verdict_record.schema.json
                            JSON Schema for a ledger entry; `verdict` is a
                            four-value enum
sAGI.agent · sAGI.model     the two authored mindX blockchain-agent facets
                            (savante === sAGI.agent; the persona is the third)
sAGI.prompt · sAGI.tool     DERIVED facets, checked by the binder (step 6 below)
sAGI.voaice · sAGI.faice    embodiment facets, validated by the binder (step 7)

Deviations from the implementing spec, recorded. Two persona sub-keys are not in the spec's file plan: token.standards_note (savante.persona:190) and task.battery_note (savante.persona:610). Both are loader-inert — corpus.persona_task copies only name, one_thing, battery and confirmed_when (mindX/mindx/godel/mindxtrain/corpus.py:376-386). And task.confirmed_when.imprint_delta_gt is the integer 0 where the spec wrote 0.0: preflight P2 is whole-document and would fail closed on a float, and hf_client.py:2127 coerces the value with float() before comparing.

Precedence. savante.persona is authored; savante.agentcard.json and savante.commitments.json are derived from it by bind/savante_bind.py, regenerable at any time, and never hand-edited — each opens with a $comment saying so. A hand edit to a derived file is a defect, not a customization: the next binder run overwrites it. Derived values never flow back: the persona's token.bindings slots are permanently null by rule, because writing an agentId into the persona would change its bytes and invalidate the digest a registry would hold (savante.commitments.json, bindings_rule).

Boundary. The binder is the operator's tool. Savante audits bind/ — reads it, runs the verifier, grades the ledger — and never runs the binder, because oversight that acts is oversight no longer, and that includes minting (savante.persona:562). A mint is a visibility-or-publication decision and a treasury action, two of the defer triggers at savante.persona:136; the office's own verdict on it is DEFER (savante.persona:560). The binder does no network I/O and writes nothing on chain (savante.commitments.json, mint_reason).

Not part of the product. bind/ is not part of the duplication in §6. cp of the charter and the skill still conveys the whole office; a copier receives the office and not the ledger, and should know which is which. The ledger answers a different question — is this the persona the author committed to? — and needs savante.persona plus, for keccak256 only, pycryptodome or eth_utils (bind/savante_bind.py:16); sha256 and the CID use the standard library. The verifier needs no network for steps 1–5 and never trusts the author: it recomputes every digest from raw bytes.

Order of operations. The sequence that produced the current files is load-bearing, and it is the order any regeneration must keep:

1. Fix .claude/skills/sagi/SKILL.md first. Its fallback path (line 33) carried a machine-specific absolute path, /home/hacker/mindX/... (visible in git diff against HEAD); it now reads the repo-relative .claude/agents/savante.md. A digest computed before that fix would have frozen one machine's home directory into the authenticity commitment of a duplication-first product, permanently.
2. Edit savante.persona.
3. Mirror it byte-for-byte to /home/hacker/mindX/mindx/godel/mindxtrain/personas/savante.persona. They are separate inodes and only the mindX copy is on the corpus loader's path; an edit landing in one place splits the identity and splits the document the ledger commits to.
4. Validate: python3 personas/persona_project.py --all --check in mindx/godel/mindxtrain/ must exit 0.
5. Mirror any charter edit to savante.md (§1 precedence).
6. Derive the derived facets. sAGI.prompt is the charter body verbatim and sAGI.tool is the allowlist plus the grant mask; the binder regenerates both and fails closed on drift, printing the offending byte offset and the regeneration command. A charter edit that skips this step is caught here rather than shipping two disagreeing copies of the system prompt.
7. Validate the embodiment facets. sAGI.voaice and sAGI.faice must satisfy the honest-null rule: measured and the print are null together or present together, and an unmeasured facet carries both a reason and its deciding experiment. A plausible-looking value here would fill a doctrine-protected embodiment null (pointer 14) with something nobody earned.
8. Then, and only then, run python3 bind/savante_bind.py. It fails closed on a mirror md5 mismatch (bind/savante_bind.py, the mirror check) and on the preflight — every property name ASCII, every number an integer — that makes its canonical bytes equal RFC 8785 output (:19-22). It writes the card, the ledger, and savante.thot.json. A facet change is a new generation (sagi engine/THOT_MANIFEST.md §7): bind it with --parent-commit <commit of the most recent published manifest> --parent-reason '<what changed>'. Without them the binder carries the manifest committed at HEAD forward and refuses a facet change (G5).
9. Nothing else. A mint is deferred.

Regeneration is idempotent: two consecutive binder runs over an unchanged tree produce byte-identical card, ledger and manifest (checked with cmp; first on 2026-09-03 for the card and ledger, and again on 2026-09-11 once the manifest joined them).