Metadata-Version: 2.4
Name: telos-md
Version: 0.4.0
Summary: Custodian of the project's telos. Drift-guard for earned commitments. CLI-first; MCP is a razor-thin help-only wrapper.
Project-URL: Homepage, https://github.com/eidos-agi/telos.md
Project-URL: Repository, https://github.com/eidos-agi/telos.md
Author: eidos-agi
License: MIT
Keywords: agent,autonomous,coordination,mcp,orchestration
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](https://github.com/eidos-agi/research.md) and locked in [`governor`](https://github.com/eidos-agi/governor.md). 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`](./PHILOSOPHY.md).

See [`TELOS_CUSTODY.md`](./TELOS_CUSTODY.md) for the mental model, [`USING_TELOS.md`](./USING_TELOS.md) for the quickstart, [`.governor/adr/ADR-003`](./.governor/adr/) 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)

| Tool | Purpose |
|---|---|
| `telos_set_north_star` | Custody act. Declare a goal + trajectory metric + stop conditions; scoped to a `repo_path`. |
| `telos_tick` | Report one iteration. Returns `heading`, `drift_category`, `signal`, counter-action reasoning, and any `settled_autonomy` hint from the repo's `AUTONOMY.md`. *(`tick` arguably belongs on the `praxis-md` side when `hone` is later renamed; flagged in ADR-005.)* |
| `telos_close` | Discharge custody with an outcome (`reached` / `abandoned` / `converged` / `pivoted`). Triggers empirical metrics for any trial candidates applied during the loop. |
| `telos_hypothesize` | Draft N competing candidate patterns / counter-actions / refinements. Accepts caller-provided heterogeneous candidates (preferred) or falls back to built-in drafting. |
| `telos_trial_status` | Read-only inspection of a trial's candidates + metrics. |
| `telos_patterns` | Inspect the pattern library. |
| `telos_traffic` | List open north stars for a repo. |
| `telos_promote` | Promote a trial winner. Gated on: applications≥5, score≥0.2, lift≥0.4 over null baseline, regression_test passes, `cross_model_review` approved for pattern/refinement/counter_action kinds, strictly-best sibling on the rank cascade. Writes `<repo>/.telos/promoted/<date>-<id>.md` and appends to `AUTONOMY.md`. |
| `telos_reload` | Re-import `patterns` / `store` / `llm` from disk. Auto-invoked on successful promote so code changes take effect in the running server. |

See [`USING_TELOS.md`](./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

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

Add to your `.mcp.json`:

```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`](./.governor/adr/) for the rename rationale; [`GENESIS.md`](./GENESIS.md) for the original framing.

---

## Documentation

- [`TELOS_CUSTODY.md`](./TELOS_CUSTODY.md) — the mental model: two-axis (custody + drift), no extended metaphor
- [`USING_TELOS.md`](./USING_TELOS.md) — consumer quickstart, file layout, pattern table, trilogy composition, per-repo orchestrator example
- [`SPEC.md`](./SPEC.md) — MCP tool contract, pattern library index (note: partially predates the current surface; `USING_TELOS.md` is authoritative)
- [`PHILOSOPHY.md`](./PHILOSOPHY.md) — why `telos-md` exists at this level of the stack
- [`LEARNING.md`](./LEARNING.md) — how `telos-md` improves with use
- [`GENESIS.md`](./GENESIS.md) — origin story (historical record; tool was originally named `lighthouse`)
- [`.governor/adr/`](./.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`)
