# ADR 0001 — Markdown owns behaviour, Node owns determinism

- **Status**: Accepted
- **Date**: 2026-09-09

## Context

The harness must be *simple*, *lean on context*, *distributable as a plugin*, and run on two
hosts (GitHub Copilot CLI, VS Code Copilot) that both already contain a capable agent runtime.

There is a strong temptation to build an orchestrator process that drives the model directly.
That path produces a second agent runtime we would have to maintain, and it cannot be shipped
as a plugin because plugins run *inside* the host.

## Decision

Split the system in three, with a hard boundary:

| Layer | Owns | Artifact |
| --- | --- | --- |
| Markdown | Behaviour — agents, skills, instructions | `.github/` |
| Node CLI (`lh`) | Determinism — index, gates, lanes, telemetry, memory | `src/` |
| Host | Execution — subagents, fleet, tools, models | Copilot CLI / VS Code |

`lh` never calls a model. Agents never do arithmetic, parsing, git plumbing, or bookkeeping
by hand. **We do not reimplement an agent runtime.**

## Consequences

- The same `.github/` tree works in both hosts; only the scheduler differs (see ADR 0003).
- `lh` is trivially testable — it is pure I/O with no model in the loop.
- Anything the host cannot do, we cannot do. Accepted: host capability detection (`lh host`)
  makes the limitation explicit and degrades rather than failing.
- Behaviour changes are markdown diffs, reviewable in a PR without running anything.

## Alternatives considered

- **Standalone orchestrator binary** — rejected: not plugin-distributable, duplicates the host.
- **Everything in markdown, no CLI** — rejected: indexing, worktrees, structural analysis and
  token accounting are not things an LLM should do by hand; they are slow, expensive and unreliable.
- **Everything in Node, markdown as prompts only** — rejected: opaque, unreviewable, and it
  breaks the self-documenting requirement.