Lane Contract

---
name: lane-contract
description: File-based task contracts under .agents/runs/ with owns_paths, verification tiers L0/L1/L2, and solo merge rules. Use when authoring or reviewing task YAML / the task-v2 contract (Lane Pilot `plan`), owns_paths, acceptance, or verification commands; `$ARGUMENTS` exactly info prints the card.
argument-hint: "[info]"
---

# Lane contract (files only)

> **Inside a Lane Pilot chat** (`LANE_PILOT_AGENT_TYPE` set / tools `lane_pilot_*` present) the contract is the task-v2 JSON in the `plan` of `lane_pilot_dispatch_writer`, and its schema is strict: exactly `schema_version`, `id`, `title`, `risk`, `lane`, `project_cwd`, `read_first`, `interfaces`, `invariants`, `out_of_scope`, `expected_outputs`, `owns_paths`, `never_touch`, `depends_on`, `objective`, `acceptance`, `verify`, `verification[{command, cwd, timeout_sec?}]` (`timeout_sec` up to 7200). Any other field (`context_selectors`, `impact_*`, `skills`) makes Lane Pilot reject the whole contract: put line windows in `objective` or `interfaces` as `path:start-end`. The writer RUNS `verification` and Lane Pilot re-runs it at acceptance, so every task needs real verification commands. Lane Pilot owns run state; `run-init`, `run-validate --phase`, `lane-ctl`, `run-supervisor`, the L0 rule «writer does not run tests» and `lane = adoc main_write` below are the terminal Lane Stack harness.

## Info

If `$ARGUMENTS` is exactly `info`, print `references/info.md` verbatim (Russian), then stop. Do not write task YAML.

Canonical: `FILE-CONTRACT.md`, `SOLO-ORCHESTRATION.md`,
`docs/decisions/ADR-codex-effort.md`, skill **orchestrator-lanes** (`references/decomposition.md`).

---

## Orchestrator must

1. `run-init` → fill PLAN/SPEC/tasks → `run-validate --phase pre-dispatch` before dispatch.  
2. Set **`owns_paths`**, **`never_touch`**, behavioral **`acceptance`**.  
3. **`read_first`**: existing project-relative files only. Line windows go in **`context_selectors`**. **`interfaces`**: signatures/types, or `[]`. Product **`invariants`** / **`out_of_scope`**; never writer recovery. **`expected_outputs`**: artifact path, not “tests green”.  
4. One `run-supervisor` per run; `lane-supervisor` only for typed one-shots.  
5. Parallel only with **disjoint** owns_paths.  
6. Controller: owns → L1 verify → accept **progressively**.  
7. Task YAML immutable after first start.  
8. Pre-merge validate → merge main (PM only).  
9. Writers via durable controller (kimi/…); Codex write = recovery only.  
10. Separate provider vs verification pools.  
11. **Decompose** per orchestrator-lanes `references/decomposition.md` (one outcome per task; unlock ≠ feature).  
12. **SPEC.md** is real content when score ≥ 7 or ≥ 2 tasks (not the template stub).  

---

## Authoring checklist (before pre-dispatch)

### Decomposition

- [ ] Each task id has **one** product outcome  
- [ ] `depends_on` is a real compile/data edge, not narrative order  
- [ ] Large delete vs new algorithm are **separate** tasks  
- [ ] Parallel tasks have disjoint owns  

### Owns completeness

- [ ] Every path the objective **requires** editing is listed (including companion modules the prompt forces — e.g. quality gates that still reference a removed field)  
- [ ] Package caches, `node_modules`, `.npm-cache`, build caches are **never** in owns  
- [ ] `never_touch` covers secrets, prisma (if frozen), unrelated products  

### Verification (L1)

- [ ] Commands are path-scoped unit/typecheck for **this** task  
- [ ] No bare monorepo `npm run build` / root `npm test` on multi-task runs (that is L2)  
- [ ] **`timeout_sec` — omit.** Runtime defaults to 900s. Do not invent or bike-shed timeouts in plans  
- [ ] **Every script path in `verification[].command` exists on disk under `verification[].cwd` before pre-dispatch**  
- [ ] If `project_cwd` is a **worktree**: do **not** assume main-repo `.agents/runs/...` is visible — write/copy `check.py` into the worktree path **or** put tests under product `tests/` in owns; absolute paths to main are rejected  
- [ ] Prefer product tests (`tests/test_*.py`) over `.agents/**/check.py` when possible  
- [ ] PM **may** Write only basename `check.py` under `.agents/runs/<slug>/[artifacts/<id>/]` (guard allowlist); not other `.py`, not `state.json`/reports  


### Acceptance

- [ ] Observable behavior, not “all packages green”  
- [ ] Matches objective; greps/sweeps named when deletion tasks  

---

## Lane must (writer)

1. Read the complete raw task YAML supplied in the prompt; open TASK_FILE if absent or uncertain.
2. Work only in `PROJECT_CWD`.  
3. Edit **only** `owns_paths`. Honor `never_touch`.  
4. Do not write `.agents`.  
5. Do **not** run tests/typecheck/`verification[]`; L1 is `lane-ctl verify`. Report in English.  
6. No git merge/push main.  
7. Outside-owns build break → report Gaps, do not “fix the world”.  
8. Do not run monorepo suites or Worker checks.  

---

## Required schema-v2 task fields

Identity (must match adoc / run): `schema_version`, `id`, `title`, `risk`, `lane`, `project_cwd`.

| Field | What the machine uses | Fill | Leave empty / omit |
|-------|----------------------|------|-------------------|
| `objective` | Writer TZ (prompt) | One product outcome, behavior | never |
| `acceptance` | Report + PM | Observable behavior | never |
| `owns_paths` | Owns gate | Every path the outcome must edit | never |
| `never_touch` | Owns gate | Secrets / unrelated | `.env*` minimum |
| `read_first` | Packet files | Existing files, no notes | `[]` if none |
| `context_selectors` (terminal only) | Packet line windows | `{path, start_line, end_line}` | omit (do not put windows in `read_first`) |
| `verification` | L1 `lane-ctl verify` | Focused commands | `[]` only with `verify: none` |
| `verify` | Schema only | `tests` / `smoke` / `none` matching L1 | do not invent a second suite |
| `depends_on` | DAG | Real compile/data ids | `[]` |
| `interfaces` | Prompt + path scrape | Signatures / type names | `[]` |
| `invariants` | Prompt | Product constraints | `[]` |
| `out_of_scope` | Prompt | Non-goals not already in `never_touch` | `[]` |
| `expected_outputs` | Schema + prompt | Artifact path this task creates | one path, not “typecheck green” |
| `impact_receipt` / `impact_targets` (terminal only) | Packet | Only if you captured a receipt | omit |
| `skills` (terminal only) | Claude prompt inject | `impeccable-ui` on UI tasks | omit (OpenCode ignores) |

`run-validate --phase pre-dispatch` rejects: `git checkout`/`restore` in the YAML; `read_first` prose (`section C4`, `lines 10-20`); missing `read_first` files; CONTINUATION / Gaps / HARD RULE / `wc -l` / edit-tool recovery in `interfaces` or `invariants`.

No mutable `status` / free-form verify strings on new runs.

### Prepared execution context

`lane-ctl` supplies hashes and path pointers from `read_first` and `context_selectors`.
Paths named in `interfaces`/`objective` (`file.ts:12-40`) become `interface_refs`.
Keep related tests in `read_first` as **paths**.
The original task remains immutable. OpenCode already loads `lane-writer`; the
user prompt is YAML + packet, not a second copy of the writer contract.

Writers reuse unchanged supplied code. Omit `impact_receipt` unless the file exists
on disk.

---

## Verification tiers

| Tier | Who | What |
|------|-----|------|
| **L0** | Writer | Code + test files; do not execute runners |
| **L1** | `lane-ctl verify` | Task `verification[]` only |
| **L2** | PM / CI | One full or affected suite per run |

### Worktree + pre-authored checkers

`verification.cwd` must equal the task worktree/`project_cwd`. Relative scripts
resolve **inside that tree**. Main checkout `.agents/runs/<slug>/artifacts/001/check.py`
is **not** the same file as  
`worktree/.agents/runs/<slug>/artifacts/001/check.py`.

Before `run-validate --phase pre-dispatch` / controller start:

1. Pre-author the checker (recovery/PM — not the writer).  
2. Place it **under the worktree** at the path the command uses.  
3. Or use **in_place** workspace so one `.agents` tree is enough.

`run-validate` fails closed if the script file is missing.

### `verify` levels

| Level | Meaning |
|-------|---------|
| none | Trivial / visual |
| smoke | Single cheap command |
| tests | Focused automated tests (not monorepo green) |

---

## Owns / dirt / caches

| Class | Policy |
|-------|--------|
| Pre-existing dirt outside owns | Foreign ignored (baseline / no-baseline policy) |
| New product files outside owns | **Fail** (writer leak or missing owns entry) |
| `.npm-cache`, `node_modules`, pnpm/yarn/turbo caches | **Ignored** by gate — never put in owns |
| `never_touch` hits (new) | **Fail** |

If owns fails with only cache paths: treat as control-plane noise, not “expand owns”.

---

## SPEC.md contract (run level)

When required (score ≥ 7 or ≥ 2 tasks), SPEC must state goal, interfaces,
invariants, out of scope, definition of done — in English, not the run-init stub.
`run-validate --phase pre-dispatch` rejects stubs.