Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
Trust and operator surfaces - implementation plan
Atomic units in dependency order (atoms first, helpers second, consumers third). Each task is one conventional commit on feat/trust-operator-surfaces. TDD: failing tests first, then implementation, then refactor green.
Atoms layer
A1: BrainRole enum + BrainOperation type
- Files:
src/core/brain/trust/role.ts(new)tests/core/brain/trust/role.test.ts(new)
- Acceptance: enum exports
writer,dreamer,applier,unknown.BrainOperationis a union offeedback_write,preference_create_unconfirmed,preference_promote_confirmed,preference_retire,evidence_record,log_append. Test covers exhaustiveness viasatisfies. - Depends on: none.
- Commit:
feat(trust): add BrainRole enum and BrainOperation type
A2: BrainGuardrailConfig in policy.ts
- Files:
src/core/brain/policy.ts(modify - extendBrainConfigwith optionalguardrails?block)tests/core/brain/policy/guardrails.test.ts(new)
- Acceptance:
loadBrainConfigaccepts an optionalguardrails:YAML block with three fields:promotion_min_signals(default 2),promotion_min_distinct_agents(default 1),instruction_file_max_lines(default 200). When the block is absent, all three return their defaults. Existing fixtures stay byte-identical. - Depends on: none.
- Commit:
feat(policy): add BrainGuardrailConfig block with backward-compatible defaults
A3: Extend DreamRunSummary with uncertain + quarantined arrays
- Files:
src/core/brain/dream.ts(modify - adduncertain: ReadonlyArray<UncertainEntry>andquarantined: ReadonlyArray<QuarantinedSignal>toDreamRunSummary; emit empty arrays in this commit)tests/core/brain/dream.test.ts(modify - assert new fields are present and empty by default)
- Acceptance: existing dream snapshot tests still pass after adding the empty arrays. Type-checking confirms readers see both arrays.
- Depends on: none.
- Commit:
feat(dream): surface uncertain and quarantined arrays on DreamRunSummary
A4: Extend RunDoctorResult with trust + verification + instruction-file fields
- Files:
src/core/brain/doctor.ts(modify - addtrust_verdict?,verification_delta_summary?,instruction_file_warnings?,uncertain?optional fields. Optional so unrelated doctor callers stay green.)tests/core/brain/doctor.test.ts(modify - assert new fields default to absent / empty arrays)
- Acceptance: doctor snapshot tests pass; new fields are present only when populated by helpers.
- Depends on: none.
- Commit:
feat(doctor): add trust_verdict and verification_delta to RunDoctorResult
A5: Extend DigestJson with derived trust fields
- Files:
src/core/brain/digest.ts(modify - addtrust_verdict?,uncertain_count,quarantined_counttoDigestJson)tests/core/brain/digest.test.ts(modify - assert digest renders new fields)
- Acceptance: existing digest snapshot tests pass; new fields default to
unknown/ 0 when no trust input is provided. - Depends on: A3, A4 (digest reads from dream and doctor summaries).
- Commit:
feat(digest): surface derived trust_verdict and uncertain counts
Helpers layer
H1: assess-rule-quality (language-agnostic)
Files:
src/core/brain/trust/assess-rule-quality.ts(new)tests/core/brain/trust/assess-rule-quality.test.ts(new)
Acceptance:
assessRuleQuality(principle: string): RuleQualityResult { score: number, severity: 'ok' | 'warn' | 'reject', reasons: string[] }. Score uses shape-based heuristics only, no vocabulary lookups in any language:- empty / single token ->
reject. - too long (>500 chars or >80 tokens) ->
warn. - measurable signal absent: no token contains a digit anywhere, AND no token contains an operator-shape character (
>,<,=,%,/between digits) ->warn. - filler signal high: ratio of single-character alphanumeric tokens to total tokens above 0.4 (after stripping punctuation) ->
warn.
No enumerated unit list, no per-language vague-word list, no stopword list. The detector reads bytes and counts tokens by whitespace; "token contains digit" is a
/\d/test on the codepoint, language-independent.Test fixtures cover: empty input, single token, very long input, an imperative with a numeric outcome (
limit retries to 10 per hour), a numeric outcome in a non-Latin script (<NON-LATIN>10<NON-LATIN>/<NON-LATIN>placeholder), a vague rule with no structural signal (<TOKEN_A> <TOKEN_B> <TOKEN_C>placeholder).- empty / single token ->
Depends on: none.
Commit:
feat(trust): add language-agnostic assess-rule-quality helper
H2: check-role-permission
- Files:
src/core/brain/trust/check-role-permission.ts(new)tests/core/brain/trust/check-role-permission.test.ts(new)
- Acceptance:
checkRolePermission(role: BrainRole, op: BrainOperation, currentStatus?: BrainStatus): { allowed: boolean; reason?: string }. Static allow-list per role:writermay onlyfeedback_writeandpreference_create_unconfirmed;dreamermay onlypreference_promote_confirmed(fromunconfirmed) andpreference_retire;appliermay onlyevidence_recordandlog_append. Crossing a boundary (e.g. applier trying to mutateconfirmedstatus) returns{ allowed: false, reason: ... }with structured reason. - Depends on: A1.
- Commit:
feat(trust): add check-role-permission helper
H3: self-approval-guardrail
- Files:
src/core/brain/trust/self-approval-guardrail.ts(new)tests/core/brain/trust/self-approval-guardrail.test.ts(new)
- Acceptance:
applySelfApprovalGuardrail({signal_count, distinct_agents, age_days}, config): { decision: 'promote' | 'quarantine'; reason?: string }. Promotes only when all three thresholds met. Defaults fromBrainGuardrailConfigmake current behaviour bit-identical (min_signals=2, min_distinct_agents=1, min_age_days=0). - Depends on: A2.
- Commit:
feat(trust): add self-approval-guardrail helper
H4: compute-verification-delta
- Files:
src/core/brain/trust/compute-verification-delta.ts(new)tests/core/brain/trust/compute-verification-delta.test.ts(new)
- Acceptance:
computeVerificationDelta(vault: string, dream: DreamRunSummary): VerificationDeltaResult. For each preference id mentioned indream.confirmed | dream.retired | dream.new_unconfirmed, classifies into one ofconfirmed | drift | regression | missing_evidence. Pure file-system reads through existing path helpers; no network, no LLM. - Depends on: A3.
- Commit:
feat(trust): add compute-verification-delta helper
H5: instruction-file-ceiling
- Files:
src/core/brain/trust/instruction-file-ceiling.ts(new)tests/core/brain/trust/instruction-file-ceiling.test.ts(new)
- Acceptance:
checkInstructionFileCeiling(vault, { maxLines }): returns warnings for each vault-root file in the tracked setCLAUDE.md,AGENTS.md,GEMINI.mdthat exceedsmaxLines. Returns the actual line count in the warning payload so the operator can see by how much. - Depends on: A2.
- Commit:
feat(trust): add instruction-file-ceiling helper
H6: compute-trust-verdict
- Files:
src/core/brain/trust/compute-trust-verdict.ts(new)tests/core/brain/trust/compute-trust-verdict.test.ts(new)
- Acceptance:
computeTrustVerdict({doctor, dream, verification}): 'clean' | 'watch' | 'investigate'. Thresholds per design-doc. Pure aggregation, no side effects. - Depends on: A3, A4, H4.
- Commit:
feat(trust): add compute-trust-verdict helper
H7: operator-summary composer
- Files:
src/core/brain/trust/operator-summary.ts(new)tests/core/brain/trust/operator-summary.test.ts(new)
- Acceptance:
buildOperatorSummary(vault, opts): OperatorSummaryreturns{ trust_verdict, digest_summary, doctor_summary, dream_summary, verification_delta, top_actions, instruction_file_warnings }. Pulls digest, doctor (read-only), most-recent dream, and runs verification + trust helpers. Markdown renderer included in same file. - Depends on: H1-H6, A5.
- Commit:
feat(trust): add operator-summary composer
Consumers layer
C1: brain_dream uses self-approval-guardrail + uncertain
- Files:
src/core/brain/dream.ts(modify - callapplySelfApprovalGuardrailbefore promoting; route below-threshold candidates toquarantined; populateuncertainfor cases where verification cannot run)tests/core/brain/dream-guardrail.test.ts(new)
- Acceptance: a dream run with one signal below threshold lands in
quarantined, notconfirmed. Default config keeps existing tests green. - Depends on: H3.
- Commit:
feat(dream): wire self-approval guardrail and quarantine path
C2: brain_feedback uses assess-rule-quality
- Files:
src/core/brain/sessions/validate-feedback.ts(modify - callassessRuleQuality; onseverity: 'reject'return structured error)tests/core/brain/sessions/validate-feedback-quality.test.ts(new)
- Acceptance: empty principle or single token -> rejected with structured reason. Valid principles pass.
- Depends on: H1.
- Commit:
feat(feedback): reject structurally-vague principles via quality gate
C3: brain_apply_evidence uses check-role-permission
- Files:
src/core/brain/apply-evidence.ts(modify - callcheckRolePermission(BrainRole.applier, 'evidence_record', currentStatus))tests/core/brain/apply-evidence-role.test.ts(new)
- Acceptance: applier role cannot mutate confirmed preference status; helper returns rejection that surfaces as a structured error.
- Depends on: H2.
- Commit:
feat(evidence): enforce role-permission boundary on apply-evidence
C4: brain_doctor uses instruction-file-ceiling + verification-delta + trust-verdict
- Files:
src/core/brain/doctor.ts(modify - populatetrust_verdict,verification_delta_summary(counts only, not full entries),instruction_file_warnings)tests/core/brain/doctor-trust.test.ts(new)
- Acceptance: doctor on a clean vault returns
trust_verdict: 'clean'; doctor on a vault with one long CLAUDE.md emits a warning entry referencing the line count. - Depends on: H4, H5, H6.
- Commit:
feat(doctor): integrate trust verdict, ceiling, and verification delta
C5: brain_digest reads trust fields
- Files:
src/core/brain/digest.ts(modify - readtrust_verdictfrom doctor input anduncertain_count/quarantined_countfrom dream input; surface in JSON + markdown)tests/core/brain/digest-trust.test.ts(new)
- Acceptance:
brain_digestoutput includes the new fields; markdown section## Trustshows the verdict and counts. - Depends on: A5, C1, C4.
- Commit:
feat(digest): surface trust verdict and uncertainty counts in digest
C6: brain_operator_summary MCP tool
- Files:
src/mcp/brain-tools.ts(modify - registerbrain_operator_summarytool in the full scope; handler delegates tobuildOperatorSummary)tests/mcp/operator-summary-tool.test.ts(new)tests/mcp/mcp.test.ts(modify - registry includes the new tool name)
- Acceptance: MCP tool listed in full scope (not writer scope); JSON-RPC call returns the structured envelope.
- Depends on: H7.
- Commit:
feat(mcp): add brain_operator_summary tool in full scope
C7: o2b brain summary CLI verb
- Files:
src/cli/brain/verbs/summary.ts(new)src/cli/brain.ts(modify - dispatch case)src/cli/brain/help-text.ts(modify - BRAIN_HELP entry + VERB_HELP[summary])tests/cli/brain/summary.test.ts(new)tests/cli/help-text.test.ts(modify - assert new verb is listed)
- Acceptance:
o2b brain summaryprints markdown by default,--jsonprints JSON, both match thebuildOperatorSummaryenvelope. - Depends on: H7.
- Commit:
feat(cli): add o2b brain summary verb
Phase 5 (docs)
D1: CHANGELOG + README + how-it-works
- Files:
CHANGELOG.md(one[0.10.16]entry per playbook rule "one PR = one CHANGELOG version")README.md(add trust + operator dashboard line under features list)docs/how-it-works.md(one paragraph describing the trust layer)
- Acceptance: docs reference the new tool and verb; no
[Unreleased]section anywhere. - Depends on: all of C1-C7 merged conceptually (this is the last code commit in the implementation phase).
- Commit:
docs: v0.10.16 trust and operator surfaces
Phase 5b (version bump)
V1: bump 0.10.15 to 0.10.16 across all 8 manifests
- Files:
package.json.claude-plugin/plugin.json.codex-plugin/plugin.jsonopenclaw.plugin.jsonplugin.yamlplugins/codex/.codex-plugin/plugin.jsonplugins/hermes/plugin.yamlpyproject.toml
- Acceptance:
bun run sync-version:checkreturns ok. - Depends on: D1.
- Commit:
chore: bump version to 0.10.16
Notes on TDD discipline
- Every helper module ships its test in the same commit. Tests fail first, then pass after implementation lands.
- The dream and doctor changes (C1, C4) update existing tests with extended assertions plus add new tests for the new behaviour. Existing snapshot tests get regenerated to include the new fields.
- The assess-rule-quality test fixture must NOT include any specific-language vague-word string as a target case to reject. All reject cases must hinge on structure (empty, single token, no operator-shape).
- No new dependencies added. All helpers use Node.js built-ins and existing OSB path helpers.