EKOSdocs
Docs / Concepts Learn

Human Review

Uncertain conclusions are stored as unconfirmed claims that a person (or reviewing agent) confirms or rejects.

EKOS prefers a reviewable question to a confident mistake.

What needs review Produced by Review with
Same-source fuzzy name matches ekos resolve ekos review identity or ekos_identity_review
Cross-system identity candidates ekos identity scan ekos review identity or ekos_identity_review
LLM-classified crate roles ekos architecture investigate ekos_architecture_review
Payment ↔ governance-approval candidates ekos treasury scan ekos treasury confirm|reject — CLI only, never MCP
Sources that disagree about one fact (a table defined twice, a column type a merge would drop, two labels for one code, the code and the live database) ekos compile / ekos commit (RFC 0172) ekos conflicts resolve --pick N | --both-valid — CLI only, never MCP
The source model: scope, PII, conflicts, identity, write behaviour, glossary ekos review list (RFC 0213) ekos review scope|pii|identity|write-behaviour, then ekos signoff approve, or the console's Review tab — never MCP
Business-semantics hypotheses (concepts, code meanings, constraints) ekos commit with [semantics] ekos semantics confirm|reject|edit, ekos import linkml or the console — CLI only, never MCP (guide)
Uncertain matches and roles become unconfirmed claims; a reviewer confirms or rejects, which appends an event
Uncertain matches and roles become unconfirmed claims; a reviewer confirms or rejects, which appends an event

When two sources disagree, EKOS no longer lets the last one win silently: it keeps every claim, with its file and line, as a ConflictingEvidence item. A person then decides which claim is right, or that both are valid. A decision holds while the claims stay the same; if one changes, the conflict reopens. Agents see open conflicts through ekos_conflicts and on ekos_state, and are told to report them as disagreements.

Sign-off

For a database estate, review ends in a sign-off. ekos review computes six subjects from the ledger — scope, PII, conflicts, identity, write behaviour and glossary. A person decides the items, then ekos signoff approve signs a subject on the digest of the facts they were shown. Validity is recomputed from that digest on every read, never stored: when a fact under a signed subject changes (a column added in the database, say), the sign-off becomes stale and names what changed, while other subjects stay valid. Steps 4–7 of the operator workflow stay blocked until every subject has a valid sign-off. Agents can read the state through ekos_signoff_status; none can sign.

Every decision is an appended fact

Confirming or rejecting writes a new event or decision object to the append-only ledger; nothing is overwritten, so a decision can itself be audited or superseded. ekos_identity_review and ekos_architecture_review are the only MCP tools that record a decision; every human-only entry point (review decisions, sign-offs, conflict resolution, semantics review, promoting agent session notes, migration approval, treasury authorizations) is listed in one guard that fails the build if MCP code can reach it. In the console these commands run as the signed-in person and are refused to API tokens.