telos-md

Custodian of the project's telos. Drift-guard for earned commitments.

A project has a telos — the unchanging thing it is for. Goals, guardrails, and execution all derive from it. When work runs autonomously across many iterations, the telos is the first thing to dissolve: not by a single decision to abandon it, but by accumulated drift that no participant in the loop is positioned to see.

telos-md is the per-project discipline that holds that line. It does two things and refuses to do anything else.

It takes custody. telos_set_north_star is not a setup call; it is a custody act. A telos is registered against a repo, a metric, and a set of stop conditions earned upstream via research.md and locked in governor. Closure (telos_close) is the discharge. Between those two acts, the contract is the tool's responsibility.

It signals drift. Every iteration is reported through telos_tick. The tool measures trajectory against the custodied commitment and names known failure modes — monolithic-loop, heuristic-ratchet, zero-delta-churn, caretaking-drift, execution-without-decision, same-signature-repeat. Each pattern has a specific counter-action. The tool is advisory at counter-action time — it does not execute for the pod — but it is directive at custody time: the contract it holds is the contract.

Custodial-directive, counter-action-advisory. This distinction is the load-bearing rule. See PHILOSOPHY.md.

See TELOS_CUSTODY.md for the mental model, USING_TELOS.md for the quickstart, .governor/adr/ADR-003 for the AGI-substrate thesis.

Five AGI-like sub-properties telos-md scores per project

Emitted by self_audit as a vector, 0–1 each:

1. Persistence of decision — does this project accumulate durable records of earned autonomy? (AUTONOMY.md growth)
2. Heterogeneity — are multiple model families authoring the work, or is it monocultural? (fleet_diversity distribution)
3. Contract-earning — do consequential decisions go through research.md → governor → docket.md before execution? (trilogy coverage)
4. Empirical validation — are improvements gated by evidence or by advocacy? (promoted patterns + signal-lift over null)
5. Self-observation — does the system notice its own drift, or does it require external correction? (drift-catches-that-changed-behavior)

Directional fidelity — the drift detection most consumers will interact with first — is the tactic that protects these five properties. Every drift pattern and counter-action maps to one of them.

Named drift patterns

Autonomous agents keep running. That's the whole point. But left unchecked, they drift into named, repeatable failure modes — each of which is a violation of one of the five AGI-like sub-properties:

• monolithic-loop — one model authoring every iteration; no basis change, no escape from its own geometry.
• heuristic-ratchet — tightening the same knob past usefulness; marginal value per iteration goes to zero.
• zero-delta-churn — N consecutive iterations producing no change on the declared metric.
• caretaking-drift — hedging or asking permission instead of executing.
• execution-without-decision — thrashing implementations that should've been earned upstream in research.md.
• same-signature-repeat — re-doing work another pod is already doing.

Each pattern has a specific counter-action. A pod inside a loop can't see them. A pod consulting telos-md can.

MCP surface (9 tools)

See USING_TELOS.md for the quickstart, file layout, full pattern table, trilogy composition, and the per-repo orchestrator pattern.

Per-repo, no cross-repo state

telos-md is strictly per-repo. Every artifact lands in <repo>/.telos/:

<repo>/.telos/
├── config.yaml                # project UUID + metadata
├── AUTONOMY.md                # settled decisions earned here (custody trail)
├── north_stars/<nsid>.yaml    # per-NS config + outcome
├── north_stars/<nsid>/ticks.jsonl         # append-only tick log
├── north_stars/<nsid>/applications.jsonl  # tick → candidate attributions
├── trials/<trial_id>/<cid>.md # candidate + metrics (frontmatter)
└── promoted/<date>-<id>.md    # durable promotion records

No user-global registry. No SQLite. Everything is plain-text, git-diffable, portable with the repo.

Relationship to existing tools

• Trilogy (research.md, governor, docket.md): telos-md does not replace them. It guards execution within their contracts. Counter-actions for several drift patterns explicitly route back to the trilogy — execution-without-decision sends you to research.md + governor + docket.md; heuristic-ratchet tells you to promote the current state as a governor ADR and stop ratcheting.
• hone (per-tick reflective ceremony, future praxis-md): the discipline every looping agent should run inside each iteration. telos-md measures trajectory across many ticks; hone enforces presence at each individual tick — observe before, propose at most one delta, retain the turn (even on no-op). They are paired primitives, not redundant: skip telos-md and you lose course; skip hone and you lose honesty about what each tick actually changed.
• rhea, brutal-forge, pal: domain consultants for adversarial challenge, audits, cross-model code review. telos-md is the consultant for temporal coordination: when to pivot, when to stop, when to escape your own geometry. monolithic-loop's counter-action names rhea_challenge and pal_codereview directly.
• resume-resume: session memory. telos-md's per-repo state is git-portable and composes cleanly with session archives.

Self-improvement

telos-md improves its own pattern library via propose→trial→empirically-validate→promote. Candidates compete on evidence, not advocacy. The promotion gates (applications, score, lift, regression test, cross-model review) exist because specific failure modes were observed or reasoned about. No force-promote path; the gates decide.

Install

uv tool install telos-md
# or: pip install telos-md

Add to your .mcp.json:

{
  "mcpServers": {
    "telos": {
      "type": "stdio",
      "command": "telos"
    }
  }
}

Status

0.3.0. Previously released as lighthouse (up to v0.2.1). Renamed to telos-md to align with the eidosagi.com architecture vocabulary (Telos pulls. Praxis steers.) and to correct the under-described "lighthouse observes, does not set" framing — the tool is in fact the custodian of the project's telos, not a passive observer of drift from a telos declared elsewhere. See .governor/adr/ADR-005 for the rename rationale; GENESIS.md for the original framing.

Documentation

• TELOS_CUSTODY.md — the mental model: two-axis (custody + drift), no extended metaphor
• USING_TELOS.md — consumer quickstart, file layout, pattern table, trilogy composition, per-repo orchestrator example
• SPEC.md — MCP tool contract, pattern library index (note: partially predates the current surface; USING_TELOS.md is authoritative)
• PHILOSOPHY.md — why telos-md exists at this level of the stack
• LEARNING.md — how telos-md improves with use
• GENESIS.md — origin story (historical record; tool was originally named lighthouse)
• .governor/adr/ — architectural decisions recorded as ADRs (ADR-001: file-only storage; ADR-002: empirical promotion gates; ADR-003: AGI-substrate thesis; ADR-004: session-internal scores; ADR-005: rename from lighthouse)