mind

mind is a local, advisory CLI that helps a human retain operational ownership of a codebase being built with coding agents.

Agents can produce changes faster than a person can absorb them. Tests and reviewers check the code; mind checks whether its human owner can still explain, predict, diagnose, and judge the system as it evolves.

It is designed first for a Product Builder with development knowledge, not necessarily a professional developer. The target is system understanding—not syntax recall.

Install

go install github.com/ArnaudGuiovanna/mind-cli/cmd/mind@latest

From a source checkout:

go build -o mind ./cmd/mind

Go 1.25 or newer is required.

Quick start

cd your-repository
mind init
mind check --json

mind check emits a versioned brief. A coding agent, editor, or local orchestrator then:

1. asks for your probability of passing before revealing the question;
2. poses one causal system-reasoning scenario;
3. evaluates the answer against the frozen rubric and writes a Markdown narrative;
4. records the result locally:

mind record \
  --brief BRIEF_ID \
  --predicted 0.80 \
  --score 0.60 \
  --assistance none \
  --evidence .mind/sessions/BRIEF_ID.md

Narrative evidence is deliberately constrained: it must be a regular .md file addressed by a repository-relative path below .mind/sessions/. Absolute paths, symlinks, and symlinked parent directories are rejected; mind hashes the file before appending the immutable record.

Inspect the resulting model:

mind status
mind explain CONCEPT_ID

For a specific change:

mind review --staged --json
mind review --range BASE..HEAD --json

review --staged refuses an unstaged or non-ignored untracked source overlay, because the question must match the index exactly. review --range requires a clean worktree and its right endpoint to be the checked-out HEAD.

The bundled mind skill implements this interaction protocol without depending on a particular agent. The normative boundary is Agent contract v1.

Audited semantic curriculum

mind init always creates a deterministic structural fallback. An external coding agent can additionally propose a complete provider-neutral semantic curriculum covering invariants, flows, security boundaries, failure modes, and design decisions:

mind curriculum validate --file .mind/imports/curriculum.json
mind curriculum propose --file .mind/imports/curriculum.json
mind curriculum diff DIGEST
mind curriculum approve DIGEST \
  --reviewer HUMAN_NAME \
  --parent-digest none \
  --source-revision SOURCE_REVISION \
  --attest-reviewed
mind curriculum status

The proposal file must be below .mind/imports/ or another Git-ignored path. A tracked or non-ignored proposal would enter the source revision it describes and is rejected as self-referential. The tracked example is only a shape template: adapt its repository, revision, hashes, and claims, then write the result to the ignored import path.

Use the active digest instead of none for a later revision. Validation computes the digest and verifies the exact repository, source revision, audited path scope, whole-file hashes, anchors, relations, and lineage. A declared_complete audit is also rejected if any file in its selected scope lacks semantic support. A proposal is append-only but inert: it cannot affect check, review, status, or prior evidence until the separate approval command records review of its exact digest, parent, and source revision.

--attest-reviewed is an anti-accident and audit-trail guard, not authentication. A process that already controls the user's shell can assert the flag and reviewer name; human review must therefore happen at that existing trust boundary. The full contract is in Audited semantic curriculum; a complete payload is in examples/curriculum.v1.json.

The first real self-hosted map is intentionally narrower than the whole repository. Its eleven claims cover mind's trust kernel and declare the remaining gaps instead of hiding them. See Mind's self-hosted curriculum. The revision-bound JSON is generated below .mind/imports/, proposed as a pending ledger event, and remains inert for instruction and mastery until its exact claims, supports, relations, scope, and digest are reviewed by a human.

What the model tracks

Each claim/facet keeps an immutable evidence history and exposes separately:

• observed performance and evidence mass;
• heuristic memory retention over time;
• direct validity of old evidence against current code;
• whether a full unassisted demonstration exists;
• Brier score and signed over/under-confidence;
• why the cell is selected next.

It never collapses these into an unbounded “percentage of code known.” Without an active semantic curriculum, status explicitly limits its scope to the detected structural skeleton. With one, ratios cover only its audited claims and required facets. bounded_ownership becomes true only when the declared-complete audit matches the exact current source revision, has no known gap or missing support, and every required cell is currently verified. This remains a bounded claim about that audited scope, never proof of universal code knowledge. The status field retention_only_30d_delta is the change forecast 30 days forward using today's complete evidence ledger and fixed code context, not a repository trend.

Context dependencies are typed. part_of records containment, requires records a prerequisite or structural dependency, and only an explicitly audited affects edge may propagate semantic invalidity.

Local and agent-agnostic

• no network or LLM call inside the binary;
• no provider-specific hook;
• SQLite state and Markdown sessions under .mind/;
• .mind/ is gitignored by default; mind init --shared is explicit opt-in;
• source snapshots use Git's allowlist of tracked files plus non-ignored untracked files and always exclude .mind/**;
• snapshot and staged-diff capture retry when source or index state changes during the read, then fail conservatively after three unstable attempts;
• JSON stdout is stable enough for an external agent; diagnostics use stderr;
• no understanding score blocks CI.

Each issued brief and its full immutable semantic context are appended in one SQLite transaction. Model parameters, projection version, and structural mapper version are pinned in repository state; an incompatible binary refuses replay instead of silently reinterpreting old evidence.

Longitudinal dogfood

mind can run its preregistered six-week, private n = 1 protocol without changing the understanding model:

mind study start
mind study due --json
mind study status

study due is the read-only queue intended for the provider-neutral skill: it reports open or overdue delayed-transfer probes, the next probe window, the currently recordable weekly checkpoint, and checkpoint weeks that were missed. Study events remain local and are refused in mind init --shared repositories. Feedback, probe administration, and checkpoint scores never enter the understanding ledger; a delayed probe can affect the model only through its ordinary mind record. study stop appends a terminal event, preserves all prior measurements, reports terminated_early, and leaves no further study work actionable. SQLite schema v5 enforces both “nothing after stop” and non-overlapping studies across racing CLI processes by serializing appends on a per-repository lock row, then comparing exact Go timestamps inside the same transaction. A database trigger remains as defense in depth against measurements after a stop. The stop command uses a minimal administrative runtime, so withdrawal remains available even when source or curriculum capture currently fails.

Only for participant withdrawal or a safety stop:

mind study stop --reason "participant withdrawal"

The instrumentation is ready, but no longitudinal human result is claimed yet. See the dogfood protocol for the frozen denominators, windows, and limits on interpretation.

Scientific status

The deterministic Phase 0 harness includes naïve, classic BKT, activity, HLR, simplified DAS3H, HLR+validity, no-validity, and no-retention models in report v2:

go run ./cmd/mind-sim --split all

This run is descriptive, not inferential: no model is declared a winner. DAS3H and the naïve baseline currently have lower predictive losses, while the no-retention ablation exposes a different safety/prediction trade-off. Most importantly, the production DueCode predicate has only weak stale-evidence recall in the held-out test (about 1.7%); the much higher proxy-validity recall of HLR+validity is not a product result for mind. The two-decay design therefore remains a transparent hypothesis with deterministic invariants, not an empirically accepted superiority claim.

The separately preregistered confirmatory v1 suite has now been consumed exactly once on its paired predictive and policy held-outs. Its frozen verdict is reject_both: neither mind nor aligned HLR+validity passes every absolute safety guardrail. This rejects both a simplification claim for HLR+validity and any claim that the current mind model is validated. The result is synthetic evidence about this protocol—not a longitudinal human outcome. See Confirmatory results v1, Algorithm, and the Implementation report.

Confirmatory v2 is now preregistered with fresh, disjoint seeds, paired world bootstrap, practical margins, an explicit feasibility gate, two non-interchangeable stale labels, and a save-aware cognitive budget. Its held-outs have not been opened, generated, or run. That separation is deliberate: implementation tests use only disjoint development seeds, and no v2 verdict exists yet. See Confirmatory protocol v2.

Self-hosted end-to-end tests

The CLI dogfoods its own codebase in a disposable Git mirror:

go test ./cmd/mind -run SelfHosted -count=1

These journeys exercise structural discovery, a staged review, an inert then activated test-only semantic curriculum, code-churn invalidation, and the isolated study ledger on Mind's real packages. Synthetic scores and the synthetic curriculum approval never touch the developer's private .mind; real ownership still requires real human predictions and answers. See Self-hosted E2E.

Design

• Product vision and target UX
• Prior art and benchmark
• Mathematical derivation and simulations
• Confirmatory results v1
• Confirmatory protocol v2 — held-outs unopened
• Architecture
• Agent contract v1
• Audited semantic curriculum
• Mind's self-hosted curriculum
• Self-hosted E2E
• Longitudinal dogfood protocol

Non-goals

No server, team leaderboard, web dashboard, embedded LLM, multi-user mode, provider hook, or blocking CI gate belongs in the MVP.

License

MIT