@agentskit/harness 0.3.0 → 0.5.0

package/docs/ADR-0026-kernel-adapters-boundary.md

@@ -0,0 +1,82 @@
+# ADR-0026: Kernel and adapter boundary for 0.4.0
+
+## Status
+
+Accepted — approved by the owner on 2026-09-10.
+
+## Context
+
+The Harness now contains deterministic SDLC controls, local execution
+plumbing, and three provider-facing adapters. The 0.4.0 goal is a modular
+engine that can plug in orchestrators, documentation, trackers, memory,
+models, MCP, and event bridges without making the kernel provider-specific.
+H-040 requires a baseline before changing behavior and must not infer
+architecture decisions that belong to the owner.
+
+## Decision
+
+Adopt the following boundary for review:
+
+1. **Kernel:** deterministic contracts and decisions: state machine, discovery,
+   WIP admission, delivery gates, eval scoring, cache/memory record contracts,
+   workflow scheduling, policy, preflight, coordination, resilience, status,
+   learning, model bindings, and metric projections. Kernel modules may use
+   Node standard library and other kernel contracts only.
+2. **Execution support:** local filesystem, Git/source snapshots, process or
+   Docker execution, event logs, evidence, run persistence, reconciliation,
+   and the CLI. It may depend on the kernel but does not define provider
+   semantics.
+3. **Adapters/plugins:** Doc Bridge, Orca, Linear/GitHub (or another tracker),
+   LLM providers, memory stores, MCP, and event bridges. They implement
+   generic contracts and own credentials/network side effects.
+4. **Composition:** `src/index.ts` and `src/cli.ts` compose the surfaces. A
+   consumer must not import private module paths as a supported API.
+5. **Fail-closed rule:** provider failure, missing evidence, stale source, or
+   ambiguous product decisions cannot be converted into a passing kernel
+   decision by an adapter.
+
+## Dependency constraints
+
+```text
+consumer -> composition -> execution support -> kernel
+consumer -> composition -> adapters -> kernel contracts
+kernel -> kernel / Node stdlib only
+```
+
+Type-only references between `context`, `plugins`, `events`, `runtime`, and
+`types` are allowed. `bundle` may call run reconciliation because signed
+evidence must be exported only from a reconciled terminal run. These are the
+only baseline exceptions; a new runtime import direction requires an ADR.
+
+## Human decisions required
+
+The following decisions are intentionally not inferred by this ADR:
+
+- approve the module classifications in `docs/MODULE-BOUNDARIES.md`;
+- approve `codex / gpt-5.6-luna / high` as the pilot's fixed provider/model
+  binding, or provide a replacement;
+- approve the proposed eval thresholds and three repetitions, or provide
+  different values;
+- provide or authorize a controlled no-Harness cohort and its task IDs;
+- decide whether future MCP/event-bridge adapters belong in this package or a
+  separate integration package once their contracts are specified.
+
+The architecture decision is accepted. H-040 still requires empirical baseline
+collection and verification evidence before it can be reported complete.
+
+## Consequences
+
+- Swapping Orca, a tracker, Doc Bridge, a model, or a memory backend does not
+  require changing kernel decisions.
+- External side effects stay auditable and testable through adapter contracts.
+- The kernel remains usable in a local process or Docker execution mode.
+- Provider-specific integration tests and evals are required before an adapter
+  can be described as production-ready.
+
+## Alternatives considered
+
+- **Provider logic in the kernel:** rejected; it couples decisions to vendors
+  and makes deterministic comparison impossible.
+- **A new abstraction layer for every capability:** rejected for now; one-file
+  capabilities stay in the existing capability-first layout until a second
+  implementation or boundary test requires a directory.

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/GETTING-STARTED.md

@@ -0,0 +1,18 @@
+# Getting started
+
+Install the package, then run the included consumer example:
+
+```bash
+pnpm add -D @agentskit/harness
+pnpm build
+node examples/minimum-profile.mjs
+```
+
+The example uses a fake profile in YOLO mode, a coding-agent adapter, a local
+Doc Bridge index, adversarial code review, and a dry-run tracking adapter. It
+prints a structured result and never performs a network mutation.
+
+For a real project, keep phase decisions in the kernel, select a named profile,
+and provide integrations through adapters. Start with `mode: "dry-run"`, inspect
+the evidence, then move to `safe` or `yolo` only after the preflight contract is
+current.

package/docs/LOOP.md

@@ -0,0 +1,195 @@
+# 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.
+
+## 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

@@ -0,0 +1,171 @@
+# Module and boundary inventory (H-040)
+
+This document is the reviewed starting point for the 0.4.0 work. It describes
+the repository at revision `f4b2b092af97d528bd5fe5955ed38f101521b98d` (the
+`main` baseline captured on 2026-09-10) and is intentionally descriptive: it
+does not claim that the proposed 0.4.0 boundary has already been accepted.
+
+## Classification
+
+| 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, 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`. |
+
+## Complete source inventory
+
+Every current TypeScript module is listed below. Relative imports are the
+observed imports at the baseline revision; `stdlib` means Node's built-in
+modules, not a provider dependency.
+
+| Module | Class | Responsibility | Relative dependencies | External boundary |
+| --- | --- | --- | --- | --- |
+| `src/kernel/constants.ts` | Kernel | State, decision, and surface constants | `types` (type-only) | None |
+| `src/kernel/errors.ts` | Kernel | Typed fail-closed errors | None | None |
+| `src/kernel/hash.ts` | Kernel | SHA-256 and JSON digests | stdlib | None |
+| `src/kernel/types.ts` | Kernel | Shared contract, run, evidence, and metric types | `context` (type-only) | None |
+| `src/kernel/state-machine.ts` | Kernel | Legal lifecycle transitions and human decisions | `constants`, `types` | None |
+| `src/kernel/discovery.ts` | Kernel | Discovery freshness, ambiguity, and decision packets | `errors`, `hash` | None |
+| `src/kernel/wip.ts` | Kernel | WIP admission and capacity decisions | `errors` | None |
+| `src/kernel/experiment.ts` | Kernel | Comparable runtime/provider selection | `errors` | None |
+| `src/delivery/index.ts` | Delivery | G2–G5 delivery gates and deterministic PR projection | `errors`, `hash` | None |
+| `src/delivery/review.ts` | Delivery | Bounded parallel adversarial review lenses and evidence verdicts | `errors`, `hash`, `workflow`, `delivery/index` (type-only) | Reviewer callback supplied by caller |
+| `src/kernel/cycle.ts` | Kernel | Bounded improvement-cycle assessment | stdlib, `errors` | None |
+| `src/kernel/eval.ts` | Kernel | Versioned eval manifest validation, deterministic battery runner, min/median/max aggregation, and fail-closed assessment | `errors`, `hash` | Grader callback supplied by caller |
+| `src/kernel/compatibility.ts` | Kernel | Pinned AgentsKit component manifest and evidence-bound compatibility assessment | `errors`, `hash` | Upstream commands and reports supplied by caller |
+| `src/kernel/cache.ts` | Kernel | Safe cache keys and in-memory LLM cache contract | `hash`, `errors` | Cache backend supplied by caller |
+| `src/kernel/optimization.ts` | Kernel | Token, memory, cache, parallelism comparisons | `hash`, `errors` | None |
+| `src/kernel/memory.ts` | Kernel | Memory record validation and memory adapter contract | `errors` | KV store supplied by caller |
+| `src/kernel/policy.ts` | Kernel | Tool/action policy gate | `errors` | None |
+| `src/kernel/preflight.ts` | Kernel | File-scoped checks and safe-command validation | stdlib, `errors` | Shell command is data, never executed here |
+| `src/kernel/block.ts` | Kernel | Portable execution block manifest and dependency admission | `errors`, `hash` | None |
+| `src/kernel/learning.ts` | Kernel | Retrospective parsing and human learning promotion | stdlib, `errors` | None |
+| `src/kernel/status.ts` | Kernel | Deterministic status snapshot and digest | `errors`, `hash`, `block`, `types` (type-only) | None |
+| `src/kernel/model-policy.ts` | Kernel | Role-to-model binding and validation | `errors`, `hash` | Provider is data, not an SDK |
+| `src/execution/machine.ts` | Execution support | Machine sampling and adaptive concurrency | stdlib, `types`, `errors` | Host CPU/memory metrics |
+| `src/execution/coordination.ts` | Execution support | Atomic issue/worktree claims and dispatch ledger | stdlib, `errors`, `hash` | Local state directory only |
+| `src/kernel/resilience.ts` | Kernel | Failure classification and bounded retry/recovery policy | `errors` | Operation callback supplied by caller |
+| `src/kernel/workflow.ts` | Kernel | Bounded workflow scheduling | `errors` | Node callbacks supplied by caller |
+| `src/kernel/phase-executor.ts` | Kernel | Declarative phase routing, preflight, effect policy, and bounded decisions | `errors`, `workflow` | Phase handlers, gates, and Grill-me callback supplied by caller |
+| `src/kernel/artifacts.ts` | Kernel support | Versioned provenance-bound artifacts, Markdown rendering, and idempotent phase resume projection | stdlib, `errors`, `hash`, `events`, `phase-executor` (type-only) | Local state directory only |
+| `src/kernel/adapter-contract.ts` | Kernel | Shared assurance levels and bounded telemetry contract | `errors` | Provider measurements supplied by adapters |
+| `src/kernel/quality.ts` | Kernel | Phase telemetry validation, 0–100 quality matrix, baseline deltas, and watchdog blockers | `errors`, `hash` | Metrics supplied by phases/adapters |
+| `src/kernel/pilot.ts` | Kernel | Cohort freeze and pilot assessment | `errors`, `hash` | None |
+| `src/kernel/plugins.ts` | Kernel | Generic slots, dependency checks, and lifecycle listeners | `errors`, `events` (type-only) | Plugin implementation supplied by caller |
+| `src/context/index.ts` | Context | Context snapshot contract, hashing, and provider slot | stdlib, `plugins`, `hash`, `errors` | Provider implementation supplied by caller |
+| `src/execution/metrics.ts` | Execution support | Benchmark manifest validation, run projection, and comparison | stdlib, `errors`, `files`, `types` | Reads local state only |
+| `src/execution/config.ts` | Execution support | Contract loading, profile resolution, and config hashing | stdlib, `constants`, `profiles`, `errors`, `hash`, `files`, `types` | Local `.codex/verification.json` |
+| `src/profiles/index.ts` | Profiles | Profile defaults and overrides | `errors` | None |
+| `src/execution/files.ts` | Execution support | Run/config JSON and task-artifact filesystem helpers | stdlib, `errors`, `types` | Local filesystem |
+| `src/execution/source.ts` | Execution support | Git/source snapshot and dirty-tree detection | stdlib, `hash`, `errors`, `types` | Git CLI |
+| `src/execution/runs.ts` | Execution support | Run persistence and lifecycle event creation | `hash`, `files`, `events`, `context`, `types` | Local state directory |
+| `src/execution/verification.ts` | Execution support | Plan/start/verify/reconcile/approval orchestration | stdlib, `runs`, `config`, `errors`, `evidence`, `state-machine`, `source`, `files`, `context`, `hash`, `types`, `events`, `machine` | Configured check commands and local processes |
+| `src/kernel/events.ts` | Kernel support | Event contracts, append-only log, hash chain, and lock recovery | stdlib, `errors`, `hash`, `context` (type-only), `types` (type-only), `runtime` (type-only) | Local filesystem |
+| `src/execution/evidence.ts` | Execution support | Structured evidence parsing and artifact validation | stdlib, `hash`, `files`, `types` | Check output and local artifacts |
+| `src/execution/bundle.ts` | Execution support | Signed evidence bundle export and verification | stdlib, `errors`, `files`, `hash`, `verification`, `events`, `config`, `types` | Local keys and files |
+| `src/execution/agent.ts` | Execution support | Agent session recorder, resume, and tool lifecycle | stdlib, `events`, `errors`, `policy`, `runtime`, `types` | Agent/runtime callbacks |
+| `src/execution/runtime.ts` | Execution support | Process, Docker, and generic tool runtimes | stdlib, `hash`, `errors`, `types` | Child process and Docker CLI |
+| `src/cli.ts` | Composition | `ak-harness` / `ak-verify` command surface | `index`, `metrics`, `errors`, `events`, stdlib, `commander` | Shell/CLI invocation |
+| `src/index.ts` | Composition | Supported package entry point | All supported public modules | Consumer import boundary |
+| `src/adapters/doc-bridge.ts` | Adapter | Deterministic Doc Bridge context provider | stdlib, `hash`, `context` | `.doc-bridge/index.json` |
+| `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
+
+```text
+consumer -> src/index.ts -> composition
+                         -> execution support -> kernel
+                         -> adapters -> kernel
+kernel -----------------> kernel (or Node stdlib)
+```
+
+The following are intentional exceptions and are type-only or composition
+edges, not provider leakage:
+
+1. `context.ts` uses the generic plugin slot from `plugins.ts`; the provider
+   implementation remains outside the kernel.
+2. `plugins.ts` references event types and `events.ts` references context and
+   runtime types only. These are compile-time contracts, not runtime cycles.
+3. `cli.ts` imports from `index.ts` so the CLI exercises the supported public
+   surface rather than private implementation paths.
+4. `bundle.ts` calls reconciliation because a bundle is only exportable from a
+   reconciled terminal run; this is a local execution-support dependency.
+5. `runtime.ts` contains process/Docker mechanics because those are execution
+   providers. Kernel decisions receive runtime evidence as data and do not
+   import the runtime implementation.
+
+Any new external provider (Linear, GitHub, Orca, Doc Bridge, MCP, event bridge,
+LLM, or memory backend) must enter through an adapter or plugin slot. A new
+provider import in a kernel module is a boundary violation and requires an ADR.
+
+## Public entry point inventory
+
+`src/index.ts` is the only supported consumer entry point. Its named exports
+are grouped below; the source file remains authoritative for exact signatures.
+
+| Area | Named exports |
+| --- | --- |
+| Lifecycle/config | `STATES`, `LEGAL_TRANSITIONS`, `HarnessError`, `loadConfig`, `validateConfig`, `transition`, `assertHuman`, `approvedDecision`, `loadLatestRun`, `planRun`, `startRun`, `verifyRun`, `reconcileRun`, `approveRun`, `authorizeRun`, `retryRun`, `cancelRun`, `cleanTaskArtifacts` |
+| Events/plugins/context | `EVENT_LOG_GENESIS`, `FileEventStore`, `HARNESS_EVENT_SCHEMA_VERSION`, `HARNESS_EVENT_TYPES`, `inspectEventLogLock`, `recoverEventLogLock`, `createPluginRegistry`, `createPluginSlot`, `HARNESS_PLUGIN_API_VERSION`, `CONTEXT_PROVIDER_SLOT`, `hashContextSnapshot`, `hashContextSnapshots`, `readContextSnapshots`, `validateContextSnapshot`, `validateContextSnapshots` |
+| Discovery and delivery | `assessDiscovery`, `isDiscoveryCurrent`, `assessWip`, `WIP_STATES`, `selectRuntime`, `assessAcceptance`, `assessIntegration`, `assessPreflight`, `assessProduction`, `assessWorktreeCleanup`, `composePullRequest`, `assessPilot`, `IMPROVEMENT_CYCLE_STEPS`, `assessImprovementCycle` |
+| Eval and optimization | `assessAgentEval`, `runAgentEval`, `createLlmCache`, `createLlmCacheKey`, `validateCacheableOperation`, `compareOptimization`, `validateOptimizationObservation`, `MEMORY_SCOPES`, `createInMemoryMemoryAdapter`, `createKvMemoryAdapter`, `validateMemoryRecord`, `runWorkflow`, `BENCHMARK_SCHEMA_VERSION`, `benchmarkRuns`, `loadBenchmarkManifest`, `recordBenchmarkObservation`, `validateBenchmarkManifest` |
+| Agent/runtime controls | `createSessionRecorder`, `createCodingAgentAdapter`, `createPolicyGate`, `createConfiguredToolRuntime`, `createDockerToolRuntime`, `createProcessToolRuntime`, `createToolRuntime`, `adaptiveConcurrency`, `createMachineMonitor`, `sampleMachine`, `summarizeMachine`, `createDispatchLedger`, `classifyFailure`, `recoveryDelayMs`, `runWithRecovery`, `planFilePreflight`, `validateSafeCommand`, `BLOCK_STATUSES`, `assessBlock`, `validateBlockManifest`, `LEARNING_STATUSES`, `parseRetro`, `promoteLearnings`, `createStatusSnapshot`, `validateStatusSnapshot`, `MODEL_ROLES`, `createModelPolicy`, `modelFor`, `PHASE_MODES`, `createPhaseProfile`, `planPhaseProfile`, `executePhaseProfile`, `ARTIFACT_SCHEMA_VERSION`, `createArtifactEnvelope`, `FileArtifactStore`, `artifactIsFresh`, `resumeStateFromArtifacts`, `ASSURANCE_LEVELS`, `validateAdapterMetadata` |
+| Integrations and evidence | `createDocBridgeContextProvider`, `createOrcaDispatchPlan`, `createTrackingAdapter`, `createTrackingTransition`, `EVIDENCE_BUNDLE_SCHEMA_VERSION`, `exportEvidenceBundle`, `readEvidenceTrustStore`, `verifyEvidenceBundle` |
+
+The entry point also re-exports the public type surfaces from `types`,
+`events`, `plugins`, `context`, `discovery`, `wip`, `experiment`, `delivery`,
+`pilot`, `cycle`, `metrics`, `agent`, `policy`, `runtime`, `bundle`, and
+`machine`, `phase-executor`, `artifacts`, plus explicit type exports for cache, optimization, memory,
+coordination, resilience, preflight, block, learning, status, model policy,
+Orca, and tracking. No adapter implementation is re-exported wholesale.
+
+## External integration inventory
+
+| Integration | Current location | Side effects | 0.4.0 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. |
+
+## Review status
+
+This inventory is evidence for H-040. ADR-0026 records the accepted boundary;
+the remaining H-040 work is empirical baseline collection and verification
+evidence, not an unresolved architecture choice.

package/docs/ORGANIZATION.md

@@ -9,10 +9,17 @@ the repository stays navigable without speculative layers.
 ├── src/
 │   ├── index.ts          # supported package API
 │   ├── cli.ts            # ak-harness / ak-verify commands
-│   ├── adapters/         # optional integrations
-│   └── <capability>.ts   # contract, evidence, delivery, runtime, metrics...
+│   ├── kernel/           # deterministic contracts and decisions
+│   ├── execution/        # filesystem, runtime, evidence, and run plumbing
+│   ├── context/          # context contracts and provider slot
+│   ├── delivery/         # delivery gates and PR projection
+│   ├── profiles/         # configuration profiles
+│   └── adapters/         # optional integrations
 ├── test/                 # deterministic tests and fixtures
 ├── scripts/              # real CLI, packaging, and repository checks
+├── capabilities/         # generated public-surface capability manifest
+├── examples/              # runnable consumer examples
+├── compatibility/         # pinned ecosystem manifest and migration/rollback procedures
 ├── docs/                 # ADRs and this organization contract
 ├── .codex/               # verification contract and local run state
 └── .github/              # CI and release workflows
@@ -22,8 +29,10 @@ the repository stays navigable without speculative layers.
 
 - Import internal modules with explicit relative paths; only `src/index.ts`
   is supported for consumers.
-- Add a directory when a capability has multiple cohesive modules. Do not add
-  a layer for one file.
+- Keep deterministic decisions in `kernel/`; execution mechanics and external
+  effects live behind the other capability boundaries.
+- A single-file capability may use an `index.ts` boundary when it has a
+  distinct public contract; do not add speculative layers.
 - Adapters may depend on the kernel; the kernel must not depend on adapters or
   external providers.
 - Tests may use internal modules when exercising a boundary, but consumer