mint: Instructions file for Codex

mint: atomic completion ledger contract

Drivers organize and execute work. mint records why an atomic unit is allowed to be called done.

mint is driver-, agent-, and user-agnostic. A human shell, CI job, SlayZone card, or any other driver uses the same commands and clears the same floor. mint never launches agents, manages tickets, owns terminals, or creates and removes Git worktrees.

One unit, one claim

A unit contains one goal, an explicit can-modify scope, observable EARS acceptance criteria, and its declared gates and review lenses. Create it through the CLI:

mint spec new "harden token validation" --slug harden-token \
  --goal "Reject empty tokens" --scope "src/auth/**,tests/auth/**" \
  --acceptance "WHEN an empty token is supplied, THE system SHALL reject it" \
  --gate "tests: go test ./..." --reviews "security,adversarial"

The JSON response contains the unit ID and absolute spec path. Specs are operational state, not repository files.

State and worktrees

mint writes no .mint directory and never edits .gitignore. State lives at:

$MINT_STATE_HOME/repos/<repo-id>/worktrees/<worktree-id>/{units,attempts,receipts,notes}

Without MINT_STATE_HOME, the base is $XDG_STATE_HOME/mint, or ~/.local/state/mint. Repository identity comes from the canonical common Git directory. Worktree identity comes from the canonical worktree root and worktree Git directory. Linked worktrees therefore aggregate under one repository while keeping all mutable evidence isolated. There is no repo-local compatibility reader or migration path.

Attempts and provenance

An attempt is one bounded effort against a unit. Initialize it with generic provenance:

mint exec init harden-token 001 --attempt maker-1 \
  --executor codex --vendor openai --model gpt-5 \
  --locality remote --execution-ref driver-run-42

executor, vendor, model, locality, and executionRef are opaque attributable claims. A driver may add --observed-by and --attestation; mint stores them but owns no executor registry, binary adapter, default executor, or process lifecycle. Typed provenance is declared evidence, not authenticated identity. observedBy and attestation improve attribution only to the strength of the supplying driver's trust boundary.