Consult the trust methodology before touching CLI/schema evidence surface
TM facts (weights, caps, dedup, inheritance, grade floors, star gates, persistence and
appraisal scope) come from one canonical map:
docs/agents/curation-authority-map.md.
tests/test_curation_authority_map.py checks that map against the live engine. Read it
before restating any number, and cite it instead of copying formulas into a fix or a skill.
The Gaia trust surface is a three-layer contract. Skipping any layer when
proposing a fix guarantees you either widen or narrow it incorrectly:
| Layer | Source of truth |
|---|
| Concept — what the numbers mean and why they exist | docs/codex/trust-methodology.html (also mirrored in docs/meta/2026-06-trust-methodology.md and the G7 supersession note at docs/meta/2026-06-17-g7-trust-magnitude-supersession.md) |
| Compute — how the numbers are actually produced | src/gaia_cli/trustMagnitude.py (backend); docs/js/tm-config.js (frontend SoT) |
| Persistence — what shape the CLI writes and the schema bounds | src/gaia_cli/commands/dev/evidence.py (writer) + registry/schema/skill.schema.json + registry/schema/namedSkill.schema.json (bounds) |
| Star level gates — what a skill must satisfy to hold 0★–6★ | META.md §2 (Star Bar, installability, blob-link requirement, 4★+ live evidence rule, Specialist Path rubric, Apex 6-predicate gate (Suite branch, §4.3) and the provisional Unique Impossible 5-predicate gate (Unique branch, §4.4)) |
When an issue lands as "CLI gap" or "schema gap" on this surface, ONE of those
layers is out of step with the other two. Your first job is to identify which.
Star Bar — read META.md before calibrating any 3★+
The TM methodology page covers how scores are computed. It does not cover
what a skill must have to hold a given star level. Those gates live in
META.md §2 and must be checked independently:
| Level | Gate |
|---|
| 0★–2★ | No link requirement; installable: false permitted |
| 3★+ | links.github must be a verified blob URL (.../blob/<branch>/...). Bare repo root → hard-demote to 1★. |
| 4★ | Overall Trust Grade A (TM ≥ 100), strictly. B caps a skill at 3★. |
| 4★+ | Live, verifiable usage evidence required. Seed/placeholder evidence is insufficient. |
| 5★ | Overall Trust Grade S (TM ≥ 250) and its independent-witness diversity gate. |
| 4★+ Specialist | Vendor-locked skills: Depth-of-Integration rubric (META.md §2.3) |
| 6★ Suite (Apex) | Grade S + 6-predicate Apex gate (META.md §4.3) |
| 6★ Unique (Unique Impossible) | Grade S + provisional 5-predicate gate (Apex set minus directNestedSuiteGte1, META.md §4.4; branch distinction ratified under Yggdrasil III, predicate set otherwise unchanged) |
When asked "should this skill be 4★?", run this check before computing TM:
- Does
links.github point to a concrete file via /blob/?
- Is every scoring evidence row live and non-seed?
- Is the computed Overall Trust Grade A (TM ≥ 100)? This gate is strict: META.md §1.1,
promotion._UNIQUE_GATE_BY_LEVEL, and the grade-ceiling clamp in
scripts/generateNamedIndex.py (B → max 3★). B does not hold 4★.
If any gate fails, the correct action is to fix the gate or demote — not to
add more evidence rows to compensate.
The read pass — do this before writing code
- Read the methodology page. Open
docs/codex/trust-methodology.html.
The "10 evidence types — base formula at a glance" table (search for
base formula) lists every evidence type and the raw input fields its
formula consumes. Confirm the field the issue names appears there.
- Confirm the CLI writes it. Grep
src/gaia_cli/commands/dev/evidence.py
for the field name. If the flag exists and the writer stores it, the CLI
already treats that field as persistable.
- Confirm the TM engine reads it. Grep
src/gaia_cli/trustMagnitude.py
for the field name via row.get("<field>", ...). If the engine reads it,
the field is a first-class input, not a derived value.
- Confirm the schema declares it. Open the relevant
evidenceEntry
definition and check the properties block. Because both schemas set
additionalProperties: false, any field the CLI writes but the schema
does not list will be rejected on the first gaia dev validate run —
which is exactly what surfaces most of these gaps.
- Validate the failure locally, don't infer it. Write a tiny probe file
with the field, run
jsonschema.validate(instance, schema), and observe
the exact rejection path. Do not trust an issue's diagnosis until the
local repro matches.
The design principle you must not violate
The founder ruling in META.md §2.1c and authority map §4 permits computed
Trust Magnitude and Overall Trust Grade on a named node as a hash-signed cache:
trustMagnitude, overallTrustGrade, and trustMagnitudeInputHash are written
only by gaia dev calibrate-trust-magnitude. scripts/generateNamedIndex.py trusts
the cache only while the input hash matches; otherwise it recomputes. Raw evidence
remains the source of truth. A named skill's effective TM includes eligible
generic-layer evidence at the engine's inheritance multipliers; an own-only
proposal total is not its final effective TM.
- Raw inputs are the persisted state. Fields like
citations, stars,
commits, contributors, views, reviewers, percentile, and
skillCountInRepo are the evidence inventory. They MUST be storable on an
evidence row so gaia dev calibrate-evidence-grades can re-derive grades
from them at any future time.
- Derived fields remain recomputable.
trustMagnitude and overallTrustGrade
are computed. They may appear in reports, generated catalogs, and the permitted
CLI-written cache, which never replaces the underlying evidence inventory.
- Do not "collapse" raw inputs into
trustNumber as a workaround. Writing
only a pre-computed trustNumber to sidestep a schema rejection erases the
audit chain ("why did this row score 73?") and breaks the recompute path.
It is a legitimate one-off remediation when a schema fix is blocked; it is
never a design.
Decision matrix — what kind of gap is it?
| Symptom | Most likely gap | Fix direction |
|---|
CLI writes field X; TM engine reads field X; schema rejects X | Schema gap — schemas lag documented reality | Add X to evidenceEntry.properties in both skill.schema.json and namedSkill.schema.json; keep the two schemas symmetric |
CLI writes field X; TM engine ignores X; schema silent | CLI over-writes — the field is dead weight | Remove the write in evidence.py; document why |
CLI has no flag for X; TM engine reads X; schema silent | CLI gap — TM depends on data no operator can add | Add the flag + writer, then verify schema accepts it (add if needed) |
| Methodology page mentions a metric not in the CLI or TM engine | Doc drift — treat as spec, not law | Open a discussion issue before touching any of the three layers |
The write pass — order matters
The methodology page's own "if you change a formula" checklist applies, in
this exact order. Do not skip a step or reorder them:
docs/js/tm-config.js — frontend SoT for the formulasrc/gaia_cli/trustMagnitude.py — backend implementationdocs/codex/trust-methodology.html — the doc itselfregistry/schema/meta.json — perRowGradeThresholds and gradeCeilingtests/test_row_grading.py + tests/test_calibrate_evidence_grades.pypython scripts/build_docs.py — regenerate everythinggaia dev calibrate-evidence-grades --yes — refresh stored grades
If the gap is schema-only (as in Issue #941 — the field is already read and
written, only the schema disagrees), most of that list does not apply —
only steps 4-ish (extend the schema), 6 (regen docs), and 7 (rerun the
calibration if any stored grade shifted) matter. Small schema changes still
belong on a schema/* branch per the branch-scope rules.
A stale stored TM is refreshed through the CLI, not a helper
When a consumer shows a stale cached TM, refresh it with the CLI write verb, not a
vendored script or a hand edit. The verb is Verifier-gated, so run it on a review/meta/
branch, dry-run first, then run gaia dev docs:
gaia dev calibrate-trust-magnitude --skill <owner/skill-id> --dry-run
gaia dev calibrate-trust-magnitude --skill <owner/skill-id>
gaia dev docs
Do not add or recommend a separate write-back helper. The earlier vendored
recompute_one_tm.py was retired because it bypassed this verb.
What NOT to do
- Do not "just remove the field" from the CLI when the TM engine still reads
it — you'll silently zero out every skill's citations-based magnitude.
- Do not add the field to only one of the two schemas. Named and generic
evidence entries share the same shape; asymmetric schemas guarantee the
next reviewer will re-file the same issue.
- Do not persist a pre-computed
trustNumber in place of the raw input as a
"design" — see "The design principle you must not violate" above.
- Do not hand-write
trustMagnitude / overallTrustGrade, or recommend any write-back
path other than gaia dev calibrate-trust-magnitude.
- Do not re-derive the answer from memory. The methodology has been superseded
once already (2026-06-17, G7). Always re-read the page before acting.