ETHOS

Evidence-grounded Trust for Human-Agent Operational Stewardship

ETHOS is Evidence-grounded Trust for Human-Agent Operational Stewardship.

See the Brand Kit for repository-owned public identity and presentation assets.

Design status: projection. The canonical semantic owner is the Product Design Contract.

ETHOS aims to provide the complete human-Agent path from problem and research through aligned intent, specification, capability composition and execution to verified delivery, actual-use feedback, learning and exit. Its small trust kernel compiles accepted meaning and fresh facts into controlled repository effects. The terminal plan separates implemented capabilities from remaining full-path conformance; the kernel alone does not prove that the complete product promise has been delivered.

ETHOS does not take over your domain model, CI provider, assistant host, or issue tracker. Those systems stay native carriers, adapters, or projections. Current truth resolves from the declared owner and fresh facts for the exact context; views and history never become authority by position.

Isomorphic Governance

ETHOS governs the ETHOS product repository and adopted repositories through the same kernel: (Commitment, Facts, prior Attestations) -> TransitionPlan -> new Attestations. Product and adopter work differ by profiles and adapters, not by separate command planes or private truth stores. This is not product cloning: each governed repository keeps its domain model, provider surfaces, and local shape while ETHOS applies one evidence-bound transition loop.

The same commands answer the same transition questions in every governed repository: where am I, what may mutate, which proof is required, can this land, and what publication boundary remains. Official OpenSpec owns tracked intent; Commitment compiles its acceptance transiently. Attestation preserves semantic results, while Facts and TransitionPlan are fresh, context-bound inputs. Profiles tune checks and proof depth; adapters project providers without becoming truth stores.

First Hour

The first hour is deliberately small. Start with the single bounded reader, then follow the one continuation selected from current facts:

ethos status

ethos status is the single bounded reader for current repository facts, authority, gaps, coordination, and the next action. It does not mint repository truth.

For an unadopted repository, start read-only with ethos adopt --json. Review the proposed .ethos/profile.toml and official openspec/config.yaml bindings. Apply only when conflicts are empty and the recovery boundary is understood, then re-observe and follow the resulting continuation. This bootstrap is not a complete domain scaffold or a crash-atomic multi-file migration.

For an absent target, use the distinct ethos adopt --create preview and reviewed apply path in the quickstart. It forms a governed foundation from an installed product; domain intent still belongs to an official Change.

A completed reader may return continuation=done with no next action. This ends the requested observation, not the repository project or unrelated work. Foreign lanes remain visible; seeing them neither grants ownership nor requires a new task.

Tracked .ethos/ files declare repository bindings only. Mutable coordination, runtime state, and content-addressed local evidence live exclusively under the repository's Git common directory.

Human And Agent Discovery

Use one discovery path, then branch by audience.

• Humans start from this README, then the documentation root and quickstart.
• Agents start from AGENTS.md, load the matching rule and skill, then run ethos status --json before planning mutation.
• Both treat ethos status as a reader view: it makes role, capability, foreign Work Lanes, unbound Work Lane refs, gaps, and the current continuation visible without minting truth.
• Foreign Work Lanes and unbound Work Lane refs are coordination signals. Visibility is collaboration, not authority; write, land, retire, or cleanup requires owner handoff or maintainer break-glass evidence.

Kernel

This section is a reader projection of the canonical semantic model:

(Commitment, Facts, prior Attestations) -> TransitionPlan -> new Attestations

Only Attestation persists. Commitment is transient acceptance intent compiled from official OpenSpec; Facts and TransitionPlan are also transient. Model Promotion is the canonical conflict adjudication; its full definition remains in the Product Design Contract rather than this projection.

Product Shape

src/ethos/          one cohesive Python product package
distributions/npm/  thin npm launcher adapter

The package contains the semantic kernel, contracts, command plane, repository orchestration, adapters, and projections. Internal module boundaries protect meaning; a second distribution package is not needed to express them.

The npm package is a thin launcher over the Python command plane:

npm run ethos -- --version

Command Plane

ETHOS exposes one governed lifecycle rather than a parallel maintainer surface:

ethos status --json
ethos plan --changed --json
ethos prove --execute --expect-head "$(git rev-parse HEAD)" --json
ethos land --json
ethos publish --json

The same evidence, docs, schema, and proof-gate rules used for adopter repositories apply to ETHOS product changes.

Release Readiness

GitLab-visible project governance is tracked in LICENSE, CONTRIBUTING.md, CHANGELOG.md, .gitlab-ci.yml, and GitLab templates. Use ethos prove --full --execute --json and ethos publish --json before publishing.

Development

uv run --frozen --offline python -m nox -s tests
uv run --frozen --offline python -m nox -s lint
uv run ethos status --json
uv run ethos plan --changed --json
uv run ethos prove --json