@agentskit/harness 0.4.0 → 0.6.0

package/docs/ADR-0027-keep-pushing-loop.md

@@ -0,0 +1,41 @@
+# ADR-0027: Keep-pushing loop as composition over Orca
+
+- Status: Accepted
+- Date: 2026-09-11
+
+## Context
+
+Teams want a coding-agent loop that drains one person's Linear queue around the clock: pick a ticket, freeze a
+verifiable contract, run a worker in an isolated worktree, review, merge, repeat — while never exceeding the
+machine, never guessing when acceptance criteria are missing, and surviving provider usage limits. The harness already
+owns the deterministic pieces (dispatch ledger, machine pressure, delivery gates, evidence). Orca already owns
+scheduling, worktrees, terminals, Linear access and the visibility surface. Nothing owned the composition.
+
+## Decision
+
+1. The loop lives in this package as **Adapter + Composition** (`src/adapters/{command,orca-cli,providers,linear-orca,
+   github-cli,code-review}.ts`, `src/loop/*`). The kernel is unchanged and never imports it (`pnpm test:boundaries`).
+2. Every project-specific value lives in `loop.config.yaml` (zod-validated). The code carries no repository, person,
+   path or model id. Env variable **names** may appear in config; values never do.
+3. External systems are reached only through argv-based, timeout-bounded process execution injected as a
+   `CommandRunner`. Adapters never spawn a shell; composition supplies the real runner; tests supply fakes.
+4. Orca is the single scheduler and visibility surface: two automations (`<prefix>-tick`, `<prefix>-deliver`), each
+   gated by a read-only `--precheck` that exits 0 only when work exists, run an agent prompt whose sole job is to
+   invoke `ak-harness loop <stage>`. No cron, launchd or daemon of our own.
+5. Model routing is tiered per role (`orchestrator`, `reviewer`, `builder`, `watcher`); within a tier the first
+   provider with usage available wins. Usage comes from `orca account list`; an auth/quota failure marks the provider
+   cooling down (exponential, never before the reset Orca reports) and the next candidate is tried.
+6. Autonomy envelope: the loop may claim tickets, freeze contracts, dispatch workers, nudge them, review, squash-merge on
+   a clean review plus green checks, move Linear states and clean worktrees. It must not merge PRs touching
+   `selfEditPaths`, must not force-push or bypass approvals, must not recover leases (human only, ADR-0021), and must
+   escalate with one deduplicated comment when a contract has no executable acceptance criterion or when fix rounds
+   are exhausted.
+
+## Consequences
+
+- `yaml` and `zod` become runtime dependencies of the package.
+- The loop is verifiable offline: every stage has fixture-driven tests and `--dry-run` prints the exact argv.
+- Provider CLIs (`claude`, `codex`, `grok`, `opencode`) are configuration, not code; adding one is a YAML entry with a
+  TUI template, an optional headless template and an `agentskit-review` provider id.
+- Windows is supported through Node's process model; WSL is detected and capped to one worker because host
+  antivirus load is invisible from the distro.

package/docs/ADR-0028-mcp-adapter-boundary.md

@@ -0,0 +1,45 @@
+# ADR-0028: MCP is an adapter-only boundary
+
+## Status
+
+Accepted — 2026-09-11.
+
+## Context
+
+MCP (Model Context Protocol) is a useful integration surface for read-only
+inspection and, later, gated tool calls. The keep-pushing loop and kernel must
+remain usable without any MCP host, SDK, or network dependency. MODULE-BOUNDARIES
+and ADR-0026 already classify MCP as an adapter concern; 0.6.0 needs an
+explicit decision before any public bridge ships.
+
+## Decision
+
+1. **Adapter-only.** MCP lives under `src/adapters/mcp.ts` (and future adapter
+   modules). Kernel modules do not import MCP clients, hosts, or transports.
+2. **Default-deny policy.** Every tool call goes through an allowlist
+   (`allowTools`) and a `PolicyGate` (or compatible `evaluate`). Missing
+   allowlist entry or non-`allow` decision returns `{ status: 'blocked' }`
+   without invoking the underlying call.
+3. **Read-only profile first.** The initial public surface is a policy-gated
+   call bridge intended for read-only / inspection tools. Mutating MCP tools
+   require a later ADR covering authorization, idempotency, and audit evidence.
+4. **Harness works without MCP.** Default loop config keeps `mcp.enabled: false`.
+   No MCP process is started by install, tick, or deliver.
+5. **Not wired into loop tick/deliver in 0.6.0.** The bridge is exported for
+   composition and future CLI/doctor use. Tick and deliver must not call it in
+   this release.
+
+## Consequences
+
+- Consumers can plug MCP behind the same policy gate used by session tool
+  recording without coupling the kernel to a vendor host.
+- Loop automation remains deterministic and offline-testable when MCP is off.
+- A later release may wire a read-only MCP profile into doctor or a dedicated
+  CLI after eval coverage; mutating tools stay out until gated separately.
+
+## Alternatives considered
+
+- **Kernel MCP host:** rejected; violates ADR-0026 and forces an optional
+  network dependency into deterministic gates.
+- **Wire MCP into tick/deliver now:** rejected for 0.6.0; needs allowlist
+  provenance, audit events, and eval coverage first.

package/docs/LOOP.md

@@ -0,0 +1,276 @@
+# Keep-pushing loop (`ak-harness loop`)
+
+The loop drains one person's Linear queue through Orca worktrees, 24/7, with role-based model routing and
+usage-aware fallback. The harness supplies the deterministic parts (claims, machine pressure, gates, evidence);
+Orca supplies scheduling, worktrees, terminals, Linear access and visibility. Everything project-specific lives in
+`loop.config.yaml` — switching project or person is a config change, never a code change.
+
+Status: **complete (phases 1–5).** Config, doctor, adapters, the dispatch tick, the deliver stage and the Orca
+automation installer are in place. See [ADR-0027](ADR-0027-keep-pushing-loop.md).
+
+## Commands
+
+```bash
+ak-harness loop validate -f loop.config.yaml          # schema check + effective config + hash
+ak-harness loop doctor   -f loop.config.yaml --json   # readiness report (exit 1 when a blocking check fails)
+ak-harness loop doctor --no-probe                     # skip provider probe commands
+ak-harness loop precheck tick                         # exit 0 when a slot, a builder and a candidate exist (Orca --precheck)
+ak-harness loop tick --dry-run --max 1                # plan the next dispatch, print the exact orca argv, write nothing
+ak-harness loop tick                                  # dispatch up to <free slots> workers
+ak-harness loop contract ENG-123 [--refresh|--dry-run] # freeze or show the orchestrator contract for one issue
+ak-harness loop precheck deliver                      # exit 0 when a dispatched issue is in flight
+ak-harness loop deliver [--dry-run] [--issue ENG-123] # drive dispatched workers to merge
+ak-harness loop install [--yes|--force|--skip-rehearsal|--skip-local-config|--dry-run|--plain]  # guided: overlay → checks → rehearsal → confirm
+ak-harness loop uninstall [--dry-run]                 # remove them
+ak-harness loop status                                # what Orca knows: enabled, trigger, provider, latest run
+ak-harness loop hook                                  # one status line for a SessionStart hook; never mutates
+ak-harness loop debrief [--issue ENG-123] [--since 24h]  # human-facing: what is in flight, held, escalated
+ak-harness loop watch [--issue ENG-123] [--once] [--interval 30]  # poll delivery/PR; DONE|FAILED|ACTION_REQUIRED
+ak-harness loop retro [--since 7d] [--json|--learnings]  # weekly digest + calibration suggestions
+```
+
+### Debrief and watch
+
+`loop debrief` is the human companion to the automations: a read-only Markdown (or `--json`) snapshot of
+in-flight dispatches, delivery phase (waiting for PR / review / fix round / ready to merge), holds that need a
+person, recent escalations and provider cooldowns. It does not call Orca or `gh` — only the loop state directory —
+so it is safe to run from a SessionStart hook or a chat agent that needs context before acting.
+
+`loop watch` polls `delivery.json` (and optionally the live PR via `gh`) and prints line-oriented events:
+
+| Event | Meaning |
+|---|---|
+| `DONE` | Delivery finished as merged (or the PR is MERGED) |
+| `FAILED` | stuck / abandoned / failed / PR closed without merge |
+| `ACTION_REQUIRED` | held for a human, incomplete review twice, or fix-round findings |
+| `PROGRESS` | still moving (waiting for PR, review pending, …) |
+
+Use `--once` for a single snapshot; omit it to block until a terminal outcome (or `--timeout <seconds>`).
+
+## Running 24/7 with Orca
+
+`loop install` is guided and rendered with Ink when stdin/stdout are terminals (plain lines otherwise). When no
+`loop.config.local.yaml` exists next to the config it first offers to create one: it lists the Linear team members from
+Orca, asks whose queue this machine drains and, optionally, how much RAM to keep free and the worker ceiling, then
+writes the gitignored overlay and reloads. It then runs the doctor and the automation-environment checks (harness and review CLIs on
+PATH, `gh auth status`, checkout registered in Orca, queue owner), stops on any failed check unless `--force`,
+offers a dry-run tick rehearsal (one orchestrator call, nothing written), lists the exact automations it will
+create, and asks for confirmation before touching Orca. `--yes` accepts every prompt for scripted setups; without
+a TTY the command refuses unless `--yes` or `--dry-run` is given; `--plain` keeps the old check-free behaviour.
+
+It creates two automations in the Orca runtime, each bound to the main checkout as an existing workspace
+with session reuse:
+
+| Automation | Trigger | Precheck (plain command, exit 0 = run) | Prompt |
+|---|---|---|---|
+| `<prefix>-tick` | `schedule.tick` | `<harnessCommand> loop stage tick -f <config>` (runs the tick, exits 1) | never reached under `runner: precheck` |
+| `<prefix>-deliver` | `schedule.deliver` | `<harnessCommand> loop stage deliver -f <config>` (runs deliver, exits 1) | never reached under `runner: precheck` |
+
+With the default `schedule.runner: precheck` the **precheck command is the stage itself** (`ak-harness loop stage
+tick|deliver`): it runs the harness, prints the JSON report and always exits 1, so Orca records every run as
+`skipped_precheck` with the report in `precheckResult.stdout` and never opens an agent session. This is deliberate:
+Orca caps a precheck at 600 s, so `contract.timeoutMs` (default 300 s) plus dispatch must fit one run; an Orca-launched agent starts in bypass-permissions mode and waits for a human to accept the warning, which leaks one
+stuck session per run. `schedule.runner: agent` keeps the legacy behaviour for providers that run unattended.
+Runs and their output are visible in Orca's Automations view and via `loop status`.
+
+`schedule.harnessCommand` must resolve inside Orca's environment: install the harness globally
+(`npm i -g @agentskit/harness`) or set an absolute command. `loop install` warns when it cannot find it on this shell's PATH.
+
+Optional SessionStart hook for Claude Code (`.claude/settings.json` of the target project):
+
+```json
+{ "hooks": { "SessionStart": [{ "hooks": [{ "type": "command", "command": "ak-harness loop hook -f loop.config.yaml", "timeout": 10 }] }] } }
+```
+
+It prints `loop: installed (2/2, last run …)` or the install command; it never installs or changes anything.
+
+## Deliver
+
+For every issue the loop dispatched (`<stateDir>/issues/<id>/dispatch.json`) and has not finished:
+
+| Situation | Action |
+|---|---|
+| No PR, worker terminal alive and active | wait |
+| No PR, idle ≥ `workerIdleTimeoutMin` | one check-in via `terminal send`; idle again after that → **stuck**: lease released, issue → `returnState` + `blocked`, worktree kept |
+| No PR, terminal gone (> 5 min after dispatch) | **stuck** as above |
+| PR touches `selfEditPaths` | **held**: one PR comment, no review, no merge |
+| PR conflicting | rebase instruction to the worker, once per head (does not count as a fix round) |
+| CI red | failing check names to the worker; counts as a fix round |
+| CI pending / required check missing | wait |
+| CI green, head not reviewed | `agentskit-review --pr … --block <minSeverity> --result … [--post]` with the first available reviewer candidate |
+| Review findings ≥ floor | findings to the worker; counts as a fix round; same head is never re-reviewed |
+| Fix rounds exhausted (`maxFixRounds`) | **blocked**: Linear comment + label + `returnState`, PR comment, lease released, worktree and PR kept |
+| Review clean, `merge.auto` | `gh api PUT …/merge` with `sha=<reviewed head>` (GitHub refuses if the head moved) → Linear attach + comment + `doneState`, worktree removed when `cleanupWorktree` |
+| PR merged outside the loop | same completion path |
+| PR closed without merge | **abandoned**: lease released, issue → `returnState`, worktree kept |
+
+State lives in `<stateDir>/issues/<id>/delivery.json` (reviews per head, fix rounds, nudges) and every decision is
+appended to `<stateDir>/events.ndjson`. `--dry-run` reports the decision for each issue without touching anything.
+
+## One tick
+
+1. **Intake** — `orca linear list-issues` once per configured state, filtered and ordered locally; issues already
+   leased, linked to a live worktree or sitting on their branch are *busy* and skipped.
+2. **Admit** — `assessSlots` (machine) and the harness dispatch ledger (`<stateDir>/coordination`) decide how many
+   workers may start; a claim is atomic per issue/worktree/branch.
+3. **Contract** — the orchestrator (first available candidate across `models.orchestrator` tiers) reads the issue and
+   the repository read-only and returns a JSON contract between `<<<LOOP_CONTRACT … LOOP_CONTRACT>>>`. Issue text is
+   wrapped as untrusted data. An auth/quota failure on one candidate marks it cooling down and the next is tried.
+   Contracts are cached under `<stateDir>/issues/<id>/contract.json` while the issue is unchanged.
+4. **Dispatch or escalate** — a contract with at least one executable outcome and no blocking ambiguity becomes a
+   worker: `orca worktree create --linear-issue <url> --base-branch <base> --no-parent` (no `--agent`: Orca's agent
+   launcher runs Claude in bypass-permissions mode and waits for a human), then `orca terminal create --command
+   "<providers.<id>.tui>"`, `terminal wait --for tui-idle`, and the brief goes in through `terminal send`. The issue
+   moves to `In Progress` and one dedicated comment is posted. Otherwise the loop posts one
+   `needs-info` comment (deduped by contract digest), adds the label, and moves on without consuming a slot.
+
+Every side effect is recorded in `<stateDir>/events.ndjson`; `dispatch.json` per issue links the worktree,
+terminal handle, provider/model and lease for the deliver stage.
+
+Start from [`loop.config.example.yaml`](../loop.config.example.yaml) at the package root.
+
+## What the doctor checks
+
+| Check | Source | Blocking |
+|---|---|---|
+| `orca.version` / `orca.runtime` | `orca --version`, `orca status --json` | yes — the loop cannot run without a reachable Orca runtime at or above `orca.minVersion` |
+| `provider.<id>` | PATH lookup, `orca account list` usage windows, `orca agent hooks status`, env key names, optional probe, cooldown store | no — reported per provider |
+| `routing.<role>` | tiers from `models.<role>` filtered by provider availability | yes — a role with no available provider blocks |
+| `machine.slots` | `sampleMachine` + `adaptiveConcurrency`, free RAM reserve, WSL cap, running worktrees | no — 0 free slots is a warning, not a failure |
+| `linear.queue` | `orca linear list-issues` per configured state, filtered and ordered locally | yes — an unreachable Linear blocks |
+
+## Model routing
+
+`models.<role>` is a list of tiers; each tier is a list of `provider/model`. Tiers are tried in order and, inside a
+tier, providers in declaration order. The first provider that is **available** wins. A provider is available when
+its binary is on PATH, its auth is not known to be missing, no Orca usage window is at or above
+`cooldown.exhaustedPercent`, it is not cooling down, and its optional probe passed.
+
+Providers authenticate through their own CLI login (`claude login`, `codex login`, `grok login`); only providers
+declared `auth: api-key` need an environment variable, and the loop never reads its value. Orca has no per-run model flag; the chosen model is rendered into `providers.<id>.tui` (for example
+`codex -m {model} --full-auto`) and launched in the worker terminal.
+
+When a provider runs out of usage the loop records a cooldown in `<stateDir>/provider-cooldowns.json`:
+`initialMin` doubling up to `maxMin`, never earlier than the reset instant Orca reported.
+
+## Machine slots
+
+`maxAgents = max(floor, min(adaptiveConcurrency(ceiling), ramBound, wslCap?))` where `ceiling` defaults to
+`cpus / 2`, `ramBound` fits `agentRssMb` agents into free RAM minus `minFreeRamGb`, and the WSL cap applies only
+inside a WSL distro (host Defender load is invisible there). The loop never lowers a running worker; it only
+decides whether to start another.
+
+## Integrations used by the loop
+
+The loop talks to the rest of AgentsKit through **adapters and CLI seams**, not by importing those packages into
+the published dependency tree. `@agentskit/harness` stays dependency-light (`commander`, `ink`, `react`, `yaml`,
+`zod`); Doc Bridge and Code Review are optional at runtime.
+
+### Doc Bridge (context for the orchestrator)
+
+| Item | Detail |
+|---|---|
+| Adapter | `src/adapters/doc-bridge.ts` → `createDocBridgeContextProvider` |
+| Loop wiring | `resolveDocContext` in `src/loop/contract.ts` |
+| Trigger | `.doc-bridge/index.json` exists under `project.root` |
+| Knob | `contract.maxContextReferences` (default `6`; `0` disables) |
+| Behaviour | Query is `"<issue id> <title>"`. Up to N deterministic references are appended to the orchestrator prompt. Missing or malformed index → **no refs** (loop continues). |
+| Boundary | No `@agentskit/doc-bridge` import; the adapter only reads the local index contract ([ADR-0003](ADR-0003-doc-bridge-context-binding.md)). Index build/refresh stays with Doc Bridge (`pnpm docs:bridge:index` in repos that use it). |
+
+### Code Review (`agentskit-review`)
+
+| Item | Detail |
+|---|---|
+| Adapter | `src/adapters/code-review.ts` → `runCodeReview` / `buildReviewArgv` |
+| Loop wiring | Deliver stage, after CI is green and the head has not been reviewed |
+| CLI | `delivery.review.cli` (default `agentskit-review` from `@agentskit/code-review`) |
+| Knobs | `mode` (`trusted-local` recommended so CLI logins work), `transport` (`headless` for current Grok CLI), `profile` (`fast` fits a 600 s Orca stage; `full` needs batching), `votes`, `concurrency`, `minSeverity`, `deadlineMs`, `maxCalls`, `post` |
+| Provider/model | First available candidate from `models.reviewer` tiers |
+| Verdicts | exit `0` → clean (merge path); `1` → findings ≥ floor (fix round); `2` / timeout / incomplete → wait and retry |
+| Boundary | Argv + `--result` file only; the harness never embeds the review SDK. |
+
+### Eval battery (package quality, not the live loop)
+
+`evals/manifest.json` plus `runEvalBattery` / `pnpm test:eval-battery` score harness components (`doc-bridge`,
+`code-review`, `orca-worktree`, `memory`, …) under a frozen fixture provider. That is the **library** eval gate.
+The live SDLC loop does **not** call the eval battery on every PR; it calls `agentskit-review` on each head.
+
+Loop-focused Vitest coverage lives under `test/loop-*.test.ts`, `test/review.test.ts`, and `test/doc-bridge.test.ts`.
+
+## AgentsKit ecosystem map (what the harness has vs what the loop uses)
+
+Legend: **Loop** = wired into `ak-harness loop …` today · **Kernel** = public API / contracts available to callers ·
+**Compat** = pinned in `compatibility/manifest.json` · **Absent** = no seam yet.
+
+| Capability | Status | Where | Notes for SDLC |
+|---|---|---|---|
+| **Doc Bridge** | Loop + Kernel + Compat | `adapters/doc-bridge.ts`, contract stage | Optional context on contract freeze. Playbook/docs surfaces appear as Doc Bridge scopes when the index includes them. |
+| **Code Review** | Loop + Compat | `adapters/code-review.ts`, deliver | Live adversarial review before auto-merge. |
+| **Orca / Linear / GitHub** | Loop | `adapters/orca-cli.ts`, `linear-orca.ts`, `github-cli.ts` | Scheduler, worktrees, queue, PR merge. |
+| **Coding-agent CLIs** | Loop | `adapters/providers.ts`, `models.*` tiers | Claude / Codex / Grok / OpenCode via TUI + headless templates — not an AgentsKit agent registry. |
+| **Memory** | Loop + Kernel + Compat | `kernel/memory.ts`, `loop/memory.ts` | Approved learnings (`loop learning promote`) shrink Doc Bridge/issue text in contract + brief. |
+| **Eval** | Kernel + Compat | `kernel/eval.ts`, `evals/manifest.json` | Battery + `assessAgentEval`. **Not run inside tick/deliver**. |
+| **Runtime (process / Docker)** | Kernel | `execution/runtime.ts` | Tool runtimes with attestation for kernel/agent sessions. Loop workers run as Orca terminals + provider TUIs instead. |
+| **Plugin / context registry** | Kernel | `kernel/plugins.ts`, `CONTEXT_PROVIDER_SLOT` | Typed slots so Doc Bridge / Playbook / custom providers plug in without kernel changes. Loop uses Doc Bridge directly today. |
+| **Playbook practices** | Loop (via Doc Bridge scopes) | `contract.briefScopes` → worker brief | Titles/paths for `playbook` / `for-agents` scopes listed in the brief when indexed. |
+| **RAG (`@agentskit/rag` / os-rag)** | Kernel adapter (opt-in) | `adapters/rag-context.ts` | Argv/`ContextProvider` seam; enable via `rag.enabled` + `contract.contextProviders`. No hard dep. |
+| **AgentsKit agent registry** | Composition (opt-in file) | `loop/agent-registry.ts` | Optional `agents.registry.yaml` role→TUI/argv overlay. Not OS marketplace. |
+| **MCP / event bridge** | Kernel adapter + ADR-0028 | `adapters/mcp.ts` | Policy-gated tool bridge; **not** wired into tick/deliver in 0.6.0. |
+| **`@agentskit/core` / `@agentskit/eval` / `@agentskit/memory`** | Compat pins only | `compatibility/manifest.json` | Upstream packages are compatibility-tested; harness does **not** depend on them at runtime. Callers adapt them through the seams above. |
+
+Compatibility report for 0.4.0 was **fail-closed** on code-review quality baselines and the no-Harness pilot cohort; see `compatibility/report.md`. Refresh after each release (qualification + pinned revisions).
+
+## What can be added to help the SDLC
+
+**0.6.0 ships the backlog below** (memory, doctor freshness/review probe, brief scopes, deliver smoke, agent registry, RAG provider, MCP seam+ADR, Docker verify config, weekly retro automation). Remaining work is dogfooding and deeper MCP/OS registry integrations.
+
+Ordered by leverage for a keep-pushing loop (config/adapters first; no kernel redesign required for the early items).
+
+| Priority | Addition | Why it helps | Suggested shape |
+|---|---|---|---|
+| P0 | **Memory in contract + brief** | Stop re-deriving the same repo facts; carry approved decisions across tickets | On contract freeze / worker brief, `recall` from an `AgentMemoryAdapter` (backed by `@agentskit/memory` or a file store under `<stateDir>`). Persist only human-`promoteLearnings` / retro-approved records. |
+| P0 | **Doc Bridge freshness gate** | Orchestrator context goes stale when the index is old | Doctor check: index exists, `contentHash` age, optional `docs:bridge:index` hint when missing. |
+| P1 | **Playbook / for-agents snippets in the brief** | Workers skip repo conventions that already exist as docs | Resolve Doc Bridge (or a Playbook `ContextProvider`) with scopes `playbook` + `for-agents` and render a bounded “must follow” block into `renderWorkerBrief`. |
+| P1 | **Eval smoke on deliver (optional)** | Catch harness/component regressions before merge on harness itself | Config flag to run a **bounded** subset of `evals/manifest.json` (or project `ak-verify`) as an extra deliver gate — not a full battery on every product PR. |
+| P1 | **Review transport/doctor** | Incomplete reviews burned the pilot (login / model id / stage budget) | Doctor probes `agentskit-review --help`, configured transport, and a one-lens trusted-local dry call; surface `review-tool-errors` in retro. |
+| P2 | **RAG context provider** | Large codebases exceed Doc Bridge’s deterministic top-N | New adapter implementing `ContextProvider` over `@agentskit/rag` / os-rag; same freeze-into-contract rules as Doc Bridge (hash + cap). |
+| P2 | **AgentsKit agent/skill registry** | Reuse named agents (reviewer, security, docs) instead of free-form CLI templates | Optional `agents.registry` file or OS dispatcher lookup → map role → argv/TUI. Keep fail-closed when the registry entry is missing. |
+| P2 | **MCP tools behind policy** | Controlled access to issue trackers, browsers, internal APIs | MCP adapter + `createPolicyGate` allowlist; record hashed tool events. Requires ADR (MODULE-BOUNDARIES already flags this). |
+| P3 | **Kernel runtime for untrusted tools** | Sandbox one-off scripts the worker must not run on the host | Offer Docker tool runtime as an opt-in for verify commands; loop default stays Orca worktree. |
+| P3 | **Weekly Linear retro automation** | Close the continuous-improvement loop without a human remembering `loop retro` | Orca schedule → `loop retro --learnings` → comment on a fixed Linear issue (project vs harness sections already split). |
+
+Non-goals for the loop: embedding LLM SDKs, reading API key values from config, or making `@agentskit/*` hard dependencies of the published package. New ecosystem pieces enter as adapters/plugins with argv/timeouts and eval coverage ([ADR-0026](ADR-0026-kernel-adapters-boundary.md), [ADR-0027](ADR-0027-keep-pushing-loop.md)).
+
+## Boundaries
+
+Adapters (`src/adapters/command.ts`, `orca-cli.ts`, `providers.ts`, `linear-orca.ts`) depend on kernel contracts
+only and receive a `CommandRunner`; they never spawn a shell. Composition (`src/loop/*`) supplies the real
+runner and wires adapters together. See `docs/MODULE-BOUNDARIES.md`.
+
+## Security notes
+
+- `loop.config.yaml` holds env variable **names**, never values.
+- Every external call is argv-based with a timeout; `ok: false` envelopes fail closed.
+- Linear text is data. Later phases render it into worker briefs inside delimiters and never execute it.
+
+## Continuous improvement: `loop retro`
+
+`ak-harness loop retro --since 7d` reads `<stateDir>/events.ndjson`, every `issues/<id>/{contract,dispatch,delivery}.json`,
+`provider-cooldowns.json` and (unless `--no-orca`) the Orca run records of the two automations, and prints a Markdown
+digest:
+
+- **Numbers** — contracts frozen, escalation rate, dispatches by provider, merged/blocked/stuck/abandoned/in flight,
+  review outcomes, fix rounds, median dispatch→merge, cooldowns, Orca runs (idle/work/timed out, durations).
+- **Problems** — escalation reasons grouped by shape, blocked/stuck/abandoned issues.
+- **What worked** — merged issues with worker, lead time and fix rounds.
+- **Adjustments — project** — rule-based suggestions about the target project, each with its evidence and the
+  `loop.config.yaml` knob to turn (`escalation-rate`, `review-floor`, `fix-rounds`, `stuck-workers`, `review-incomplete`,
+  `provider-cooldowns`, `idle-loop`, `lead-time`, or `steady`).
+- **Adjustments — harness** — defects or limitations of the library itself, derived from events the loop only emits
+  when its own machinery misbehaved (`worker-relaunch`, `dispatch-failures`, `contract-failures`, `merge-refusals`,
+  `review-tool-errors`, `stage-timeout`), with a pointer to the harness issue tracker. `--target project|harness`
+  filters one side.
+
+The headings follow the harness retro grammar, so `--learnings` prints `LearningRecord`s in `proposed` state; a human
+promotes them with `promoteLearnings` (ADR-0019 keeps that decision human). The calibration loop is: read the digest →
+change one knob in `loop.config.yaml` → next digest measures the effect.

package/docs/MODULE-BOUNDARIES.md

@@ -9,7 +9,7 @@ does not claim that the proposed 0.4.0 boundary has already been accepted.
 
 | Class | Meaning | Dependency rule |
 | --- | --- | --- |
-| Kernel | Deterministic contracts, state transitions, policy and metric projections | May use Node standard library and other kernel modules; must not import adapters, provider SDKs, CLI composition, or credentials. |
+| Kernel | Deterministic contracts, state transitions, policy and metric projections | May use Node standard library and other kernel modules; must not import adapters, provider SDKs, CLI composition, credentials, or UI libraries (`ink`/`react` are composition-only). |
 | Execution support | Local process, filesystem, event, evidence, and run lifecycle plumbing | May depend on the kernel; must expose provenance and fail closed at trust boundaries. |
 | Adapter | Provider-specific or external-system integration | May depend on kernel contracts; must not be imported by kernel modules. |
 | Composition | Package and CLI entry points | May compose kernel, execution support, and adapters; consumers use `src/index.ts`. |
@@ -73,6 +73,30 @@ modules, not a provider dependency.
 | `src/adapters/agent.ts` | Adapter | Structured coding-agent execution with bounded timeout and failure classification | `errors`, `resilience`, `adapter-contract` | Agent/provider callback supplied by caller |
 | `src/adapters/orca.ts` | Adapter | Safe, idempotent Orca dispatch plan | `errors`, `hash`, `preflight` | Orca CLI arguments; no execution |
 | `src/adapters/tracking.ts` | Adapter | Idempotent provider-neutral tracking transition | `errors`, `hash` | User-supplied Linear/GitHub/etc. handler |
+| `src/adapters/command.ts` | Adapter | Shell-free command runner seam, PATH executable lookup, Orca JSON envelope parsing | stdlib | Command runner supplied by composition or tests |
+| `src/adapters/orca-cli.ts` | Adapter | Typed `orca … --json` calls: version/status/account/agent hooks, worktree ps/create/set/rm, terminal list/send/wait/read, automations list/create/edit/remove/run | `errors`, `command` | Orca CLI via the injected runner |
+| `src/adapters/providers.ts` | Adapter | Coding-agent CLI availability: binary, auth, Orca usage windows, exhaustion, cooldown, optional probe | `command` | PATH, env var names, `orca account list` payload |
+| `src/adapters/linear-orca.ts` | Adapter | Linear queue via `orca linear list-issues`, issue detail, status/comment/label/attach writes with deterministic `--write-id`, `TrackingAdapter` over Orca | `errors`, `hash`, `orca-cli`, `tracking`, `command` | Linear through the Orca CLI |
+| `src/adapters/github-cli.ts` | Adapter | Pull request snapshots, check classification, self-edit path guard, optimistic squash-merge and comments via `gh` | `errors`, `command` | GitHub through the `gh` CLI |
+| `src/adapters/code-review.ts` | Adapter | `agentskit-review` argv, `--result` parsing, severity floor, worker-facing findings | `command` (type-only) | AgentsKit code review CLI via runner |
+| `src/loop/config.ts` | Composition | `loop.config.yaml` schema (zod), loading, model reference parsing | `errors`, `hash`, `model-policy`, `yaml`, `zod` | Project config file |
+| `src/loop/process.ts` | Composition | Real shell-free `CommandRunner` with timeout and output caps | stdlib, `command` (type-only) | Child processes |
+| `src/loop/slots.ts` | Composition | Machine slot assessment: adaptive concurrency, RAM reserve, WSL cap, floor | stdlib, `machine`, `config` | Host CPU/memory |
+| `src/loop/routing.ts` | Composition | Tiered role → provider/model selection over provider availability | `model-policy`, `providers` (type-only), `config` | None |
+| `src/loop/cooldown.ts` | Composition | Provider cooldown store with exponential backoff | stdlib, `providers` | `<stateDir>/provider-cooldowns.json` |
+| `src/loop/doctor.ts` | Composition | Loop readiness report: Orca, providers, routing, slots, workers, queue | adapters, `config`, `cooldown`, `routing`, `slots` | Orca CLI via runner |
+| `src/loop/contract.ts` | Composition | Task contract schema, orchestrator prompt (issue text as untrusted data), marked-JSON parsing, dispatchability assessment, candidate fallback with auth/quota classification, contract cache | `errors`, `hash`, `resilience`, `doc-bridge`, `config`, `routing` (type-only), `zod` | Headless coding-agent CLI via runner |
+| `src/loop/brief.ts` | Composition | Worker prompt: frozen contract + repository rules + protected paths + done signal | `contract`, `config`, `linear-orca` (type-only) | None |
+| `src/loop/tick.ts` | Composition | One keep-pushing tick: intake, admit (slots + dispatch ledger claim), contract, dispatch into an Orca worktree, Linear transition, escalation, precheck | adapters, `coordination`, `errors`, `hash`, `brief`, `config`, `contract`, `cooldown`, `doctor`, `routing`, `slots` | Orca CLI + Linear via runner; `<stateDir>` files |
+| `src/loop/deliver.ts` | Composition | Deliver stage per dispatched issue: PR detection, self-edit hold, conflict/CI/review fix rounds via terminal, review at head, optimistic squash-merge, Linear Done, cleanup, stuck/abandoned escalation | adapters, `coordination`, `errors`, `config`, `cooldown`, `doctor`, `routing`, `tick` | Orca, Linear, GitHub, agentskit-review via runner; `<stateDir>` files |
+| `src/loop/install.ts` | Composition | Orca automation specs (`<prefix>-tick`, `<prefix>-deliver`) with read-only prechecks, idempotent create/edit by name, uninstall, status and the SessionStart hook line | `command`, `orca-cli`, `providers`, `errors`, `config`, `cooldown`, `doctor`, `routing` | Orca automations via runner |
+| `src/loop/guided-install.ts` | Composition | Interactive install: doctor + environment preflight, dry-run rehearsal, confirmation, install, status; readline IO injected | `command`, `orca-cli`, `config`, `doctor`, `install`, `tick`, stdlib readline | Terminal prompts; Orca via runner |
+| `src/loop/local-config.ts` | Composition | Per-machine overlay wizard: Linear team members via Orca, queue owner and machine tuning answers, YAML rendering and reload | `orca-cli`, `config`, `yaml` | Orca via runner; writes `loop.config.local.yaml` |
+| `src/loop/retro.ts` | Composition | Retro digest over `events.ndjson`, per-issue state, cooldowns and Orca runs; rule-based calibration suggestions; Markdown that `parseRetro` can lift into learnings | `orca-cli`, `hash`, `learning`, `config`, `contract`, `cooldown`, `deliver`, `install`, `tick` | Orca via runner (optional); `<stateDir>` files |
+| `src/loop/debrief.ts` | Composition | Human-facing read-only snapshot of what the loop is working on (in-flight, holds, escalations, cooldowns) | `config`, `contract`, `cooldown`, `deliver`, `retro`, `tick` | `<stateDir>` files only |
+| `src/loop/watch.ts` | Composition | Poll delivery (+ optional live PR) and emit DONE/FAILED/ACTION_REQUIRED/PROGRESS for agents or humans | `command`, `github-cli`, `config`, `deliver`, `tick` | optional `gh` via runner; `<stateDir>` files |
+| `src/loop/ui/components.tsx` | Composition | Ink components: check rows, sections, banner, spinner, select/confirm/text prompts | `ink`, `react`, `doctor` (type-only) | Terminal |
+| `src/loop/ui/terminal.tsx` | Composition | `createRichIO`: Ink-backed IO for TTYs with a plain-text fallback | `ink`, `react`, `components`, `guided-install` (type-only) | Terminal |
 
 ## Allowed dependency directions and exceptions
 
@@ -125,16 +149,25 @@ Orca, and tracking. No adapter implementation is re-exported wholesale.
 
 ## External integration inventory
 
-| Integration | Current location | Side effects | 0.4.0 boundary |
+How these seams are wired into the keep-pushing loop (and what is still only a kernel contract) is summarized in
+[`LOOP.md`](LOOP.md#integrations-used-by-the-loop) and the [AgentsKit ecosystem map](LOOP.md#agentskit-ecosystem-map-what-the-harness-has-vs-what-the-loop-uses).
+
+| Integration | Current location | Side effects | Boundary |
 | --- | --- | --- | --- |
 | Doc Bridge | `src/adapters/doc-bridge.ts` | Reads a local index | Keep behind `ContextProvider`; measure context hit/quality separately. |
 | Orca | `src/adapters/orca.ts` | None; produces argv and lifecycle projections only | Keep lease/worktree/issue-lock/SHA planning provider-neutral; execution belongs to the orchestrator. |
 | Linear/GitHub/other tracker | `src/adapters/tracking.ts` callback | Caller-owned network mutation | Require idempotency key and explicit tracking authorization. |
+| Orca CLI (loop) | `src/adapters/orca-cli.ts`, `src/adapters/linear-orca.ts` via `CommandRunner` | Read-only `--json` calls in the doctor; dispatch/mutation arrive in later loop phases | Argv only, never a shell string; every call bounded by a timeout; envelope `ok:false` fails closed. |
+| Coding-agent CLIs | `src/adapters/providers.ts` | PATH lookup and optional probe command | Env keys are names only; usage comes from Orca, never from provider SDKs. |
+| GitHub | `src/adapters/github-cli.ts` via `CommandRunner` | `gh pr view/list`, `gh api PUT …/merge` with `sha=<reviewed head>`, `gh pr comment` | Merge is refused by GitHub when the head moved; every call argv-based and bounded. |
+| AgentsKit code review | `src/adapters/code-review.ts` via `CommandRunner` | `agentskit-review --pr … --result <file> [--post]` | Exit codes 0/1/2 plus the private result file decide clean/findings/incomplete; the floor is `--block`. |
 | Process runtime | `src/execution/runtime.ts` | Starts child processes | Execution support; policy and evidence gates remain kernel decisions. |
 | Docker runtime | `src/execution/runtime.ts` | Starts Docker containers | Optional sandbox selected by config, never a mandatory kernel dependency. |
 | LLM provider/model | Caller/plugin | Provider call and token spend | Bind provider/model in experiment metadata; do not embed SDKs in kernel. |
-| Memory backend | Caller/plugin; `memory.ts` contract | Backend reads/writes | Keep record validation in kernel; backend adapter owns persistence. |
-| MCP/event bridge | Not implemented | Future network/event effects | Add as adapters only after a separate ADR and eval coverage. |
+| Memory backend | Caller/plugin; `memory.ts` + `loop/memory.ts` | Backend reads/writes; loop file store under `stateDir` | Only human-promoted approved records enter loop prompts; prefer-over-DocBridge shrinks tokens. |
+| RAG context | `src/adapters/rag-context.ts` | Optional argv / injected query | No hard `@agentskit/rag` dep; same ContextProvider freeze rules as Doc Bridge. |
+| Agent registry (file) | `src/loop/agent-registry.ts` | Reads YAML | Role→TUI/argv overlay; fail closed only when `agents.requireRegistry`. |
+| MCP/event bridge | `src/adapters/mcp.ts` + [ADR-0028](ADR-0028-mcp-adapter-boundary.md) | Policy-gated tool calls | Adapter-only in 0.6.0; **not** wired into tick/deliver. |
 
 ## Review status