# Ethos How an agent drives ethos — not how to develop ethos itself. Ethos binds a name, voice, email, GitHub handle, writing style, personality, and talents into one identity that other tools read. New in this repo, or `ethos doctor` reports missing state? Setup guide is deposited alongside this file at `.punt-labs/ethos/ETHOS-SETUP.md` on `ethos enable`. Pre-enable, fetch from . Either way it's a one-time task and is deliberately not `@`-imported here. ## Who am I - `ethos whoami` — resolve your identity from the session, git config, or OS user. - `ethos iam ` — declare a persona for the current session. Session hooks inject your persona into context at start and after compaction. Ethos generates `.claude/agents/.md` from team data at SessionStart; restart Claude Code to regenerate them after a team change. ## Delegation (missions) - `ethos mission dispatch --worker --evaluator --write-set --criteria ` — write a mission contract. Dispatch writes the contract; a separate agent spawn does the work. - `ethos mission show|log|results ` — inspect a mission. - `ethos mission close ` — close a passing mission (requires a submitted result for the current round). - `ethos mission abandon --reason ` — retire a mission that was created but never had a worker spawned against it. Refuses if any *blocking* delegation or any result exists — use `close` for those. A delegation refused before its worker ran (`verdict: aborted`) never blocks, automatically. A delegation proven to be a dispatch-sidecar misattribution (DES-076) can be named via repeatable `--disclaim ` to unblock just that one. Neither is a bypass of `close`'s result gate, which has no override; see `docs/mission-abandon.md`. - `ethos mission pipeline list|show|instantiate ` — drive multi-stage work from a template. Commit one logical step at a time; the write-set is enforced at runtime, so an edit outside it fails the mission. ## Audit - `ethos audit show --delegation ` — reconstruct a delegation's trail. - `ethos audit seal` runs at pre-commit when ethos is enabled here. DES-079 requires local archives by default, not automatically committed chunks. - `ethos audit quarantine` — the recovery path for a corrupt chunk. ## Storage and sharing (DES-079; acceptance pending) DES-080 redaction shipped in v4.20.0. The DES-079 requirements below are pending final entry-point acceptance, not guarantees of an installed binary. The [storage contract](https://github.com/punt-labs/ethos/blob/main/docs/storage-layout.md) supersedes older tracked-by-default and checkout-local audit guidance. Four classes: source/configuration and blame records are intended for Git; trace is retained locally with explicit sharing; runtime state is never published. Regenerated agents are expected source changes when inputs or the binary change. Edit their sources, not generated output. Redaction is only a backstop: contracts and commands must not contain credentials. - Resolve canonical store root **S** through Git's common directory, separately from invoking checkout **C**. Shared source/blame records live in `S/.punt-labs/ethos/`; all new repository live logs, retained archives, overlays, locks, receipts, scratch and temporaries belong under `S/.punt-labs/local/ethos/`. No record-tree ignore workaround. - C owns generated agents, guide/marker/import deposits and publication into its actual index. Removing a linked C distinct from S must retain even unsealed tails without SessionEnd; deleting S or its local data is not covered. - `record: blame` is the default; sealing neither queries nor changes the index. `record: full` retains the same local trace and adds eligible copies, including sealed session audits. Consent is per immutable entry. Mode switches do not promote old private history or remove published history; pending eligible copies remain retryable. Invalid config fails visibly, validated once per request, including each MCP call. - Full Reflection submission remains mandatory. Bounded inline v1 `round_decisions` in the shared contract govern advancement; full prose stays local. Durable local intent and required event precede decision installation. A prepared event alone grants no permission. Reads must distinguish submitted/detail unavailable here from never submitted, legacy unknown or unreadable authority. Ordinary required-event rollback remains. Local detail uses per-round envelopes at `S/.punt-labs/local/ethos/trace/missions//reflection-.yaml`; pending receipts use `missions//reflection-intents/.yaml` under the same local root. Each has `version`, `kind`, `mission`, `decision`, `reflection`, `event`, `event_session` and `publish`. Join the complete decision against shared authority; a receipt alone does not mean accepted. Published/exported `reflections.yaml` is an aggregate, not this local format. - Repository overlays move to `S/.punt-labs/local/ethos/identities/.ext/.local.yaml`; ordinary writes remain base-only. Overlays are not a vault and may reach model context. Global overlay layout is unchanged. Legacy repository siblings are read-only: stop writers and explicitly reconcile each into the local destination, preserving all credentials and resolving an existing destination before removing the old copy. Unequal copies refuse reads; local writes refuse while a legacy sibling remains. Never serialize the merged identity into the base or print credentials. - Worker files, including `MISSION_ARTIFACTS_DIR`, target local scratch, not the tracked delegation directory. Ethos does not automatically move, export or redact agent-owned files; legacy cleanup is operator-directed. - Pending `mission publish ...` snapshots complete selected blame records into C and its actual index. `provenance message ` supplies the generated body for the head-pinned GitHub squash route; fetch and `provenance verify ` afterward. Local hooks do not run remotely. See the [merge procedure](https://github.com/punt-labs/ethos/blob/main/docs/example/07-pr-and-merge.md). - Plain `mission export` remains contract + final result, without staging. Pending `mission export --full` explicitly shares that mission's retained prompts, reflections and event chunks, including a locally sealed unsealed tail, regardless of original mode. Missing expected history is incomplete. It excludes session audits, scratch, overlays, artifacts and transcripts. Use ordinary `git add`, never force-add. - Readers union local, published and supported legacy evidence in either mode, collapse equal copies and report conflicting payloads before watermark filtering. Direct filesystem consumers need this contract too; legacy fallback inside Ethos does not update Quarry or Desk automatically. - All repository staging stays local; `EXDEV` refuses with the old target intact, never an adjacent-temp/copy-over fallback. ### Bounded legacy repair `ethos repair --dry-run` inventories known obsolete trace/runtime files. Destructive `ethos repair` lists them, warns of permanent loss of old prompts, reflections, events/audit history and runtime residue, and asks `Are you sure? [y/N]` in a terminal. Empty input, no and EOF delete nothing. `--yes` explicitly consents for automation and asserts that all old/new writers, hooks and MCP servers are stopped. Busy locks refuse. Windows supports inventory but currently refuses destructive repair; deletion requires a Unix host with all writers stopped. No backup, lossless migration, authority backfill, lifecycle change, Git staging/commit or configuration rewrite is performed. Cleanup excludes shared identities, contracts, results, corrections, provenance and ADRs, private credentials/overlays, configuration, global data, arbitrary/agent-owned files and canonical local history. Current publications and flat current exports (`missions/.contract.yaml` / `.result.yaml`, with associated trace) are retained, including incomplete/ambiguous exports. Other intentional publications and exports are not blanket deletion targets. Repair neither moves nor deletes private overlays; use the operator-directed handling above. Historical shipped `mission migrate` / `audit migrate` are not expanded; there is no storage-upgrade command. After interruption, inspect a fresh inventory and confirm again; incremental deletion has no rollback. Old missions may need manual retirement; repair never invents shared authority. Review tracked deletions and stage/commit normally. Then run `ethos enable` to refresh integration and reconnect long-lived MCP servers. Re-enable maintains the shared local-zone exclusion, not record-tree ignore exceptions; it does not prove final storage acceptance. ## Session - `ethos session` — the current roster. - `ethos session purge` — clear stale sessions. ## Review agents `ethos seed` deploys three review-checklist agents to `.claude/agents/`: `code-reviewer` (general code-quality and CLAUDE.md-compliance), `silent-failure-hunter` (error handling, swallowed exceptions, fallback logic), and `invariant-completeness-reviewer` (verifies a claimed invariant, exhaustiveness property, or regression-guarding test actually holds, rather than trusting the prose that asserts it). These are checklist agents, not mission-dispatchable specialists: invoke them directly as local review passes, never via `ethos mission dispatch --worker `. Local review sequence, after `make check` passes: 1. Run `code-reviewer` on the diff. 2. Run `silent-failure-hunter` on the diff. 3. Run `invariant-completeness-reviewer` on the diff. 4. Fix all valid findings; re-run until all three return zero findings. ## Gotchas - Reinstalling ethos does not restart a running MCP server. An `ethos serve` started before the install keeps answering from the old binary — reconnect the ethos server afterwards, or the new code stays inert. Installing mid-session is itself safe: every supported install path unlinks or renames over the old file rather than writing into it, so a running process keeps its own image and never hits `ETXTBSY`. - Agent types are discovered at SessionStart; restart after adding one. - `ethos doctor` checks seal and trailer hook presence only when ethos is enabled here, but its hook currency checks run unconditionally, on dormant repos too.