Propose two harness guides, and one defect found while writing them

[VeryComplexAndLongName]

Two proposals. No implementation yet.

agentic-harness-documentation

README.md does not contain the word "harness". The largest capability this repository has built has no document saying what it is or how to configure it — what exists is spread across nineteen ADRs and forty change proposals, which record why each decision was made and are the wrong shape for someone who wants to use the thing.

HARNESS.md — how to set it up. The stage sequence, both configuration files and their merge rule, every key with its accepted values, where each is edited in both interfaces, mechanical checks, and one table with a row per agent id: model, effort and which values, spending cap and in which unit, and whether any binary for it has ever run here.

LIMITS.md — what stops a run, and when. Two independent levels: a chain-wide budget evaluated between stages (so it cannot stop a stage already running), and a per-stage budget passed to one CLI invocation as its own flag. Plus what does not exist:

There is no wall-clock or duration limit on a harness run, and no per-stage timeout.

The durations in the code are not user settings — external-waiter.ts's maxDurationMs, gh-pr-gateway.ts's five-minute check poll, agent detection's timeout, the CI job ceilings. The request that prompted this asked about time limits as though they existed, which is exactly why the document has to say so outright.

Screenshots get generated

docs/images/standalone/harness-settings.png is from 2026-08-31 and shows a settings screen that stopped existing three commits ago — before the effort and budget controls, the chat target, and the mechanical archive row. grep -rn "docs/images" over the repository's code, CI and tooling returns nothing: all seventeen images are manual captures, and nothing announced that one had rotted.

packages/server already runs Playwright with four specs and a CI job, so the standalone images become a product of the code the tests exercise. VS Code's cannot be automated — that host has not been startable in this environment even for its own integration tests (see audit-log-persistence task 4.2) — so those stay manual and carry the date and version they show. That is the honest version of the same guarantee, rather than claiming an automation that a person will keep performing by hand.

One thing is not written as asked

The request asks to document that agents communicate over ACP. The accurate statement is narrower: ACP is the protocol between the harness and one agent process — structured session/update progress instead of scraped text, and a session/request_permission gate where the agent offers one. It is not a channel between two agents, and no agent here sends a message to another. ADR 0018's event-driven orchestration is between stages, which is a different mechanism and also not agent-to-agent messaging.

Writing it the other way would put a capability in the documentation that does not exist in the product — the class of defect this repository has spent the week removing from its own configuration surface. The document says what ACP gives and says plainly what it does not.

acp-agent-capabilities — found while writing the table

HARNESS_AGENT_CAPABILITIES has rows for the five CLI adapters and vscode-chat. It has no rows for the four ACP ids, and by the table's own documented contract an absent row means "no mechanism at all" — so effort and budget are refused for all four.

For two of them that is wrong, and the evidence is three files apart:

	renders	allowlist permits	validator says
copilot-cli-acp	--effort, --max-ai-credits	both	no mechanism
claude-cli-acp	--effort, --max-budget-usd	both	no mechanism

The adapter builds the flag, the allowlist admits the flag, and the validator refuses the configuration that would produce it.

This is the mirror image of what harness-config-strictness removed. There the validator accepted a setting nothing could honour; here it refuses one the runtime honours. Same failure — validator and runtime disagreeing — and the refusal is the more confusing direction, because it presents as a deliberate decision.

The practical cost is specific: copilot-cli is the cheap agent, --max-ai-credits is its only spending cap, and copilot-cli-acp is the adapter this project recommends for structured output. Today those three cannot be combined — ACP or the cap, not both.

The fix is the table and nothing else. Adapters and allowlist are already correct. It also requires explicit empty entries for codex-cli-acp and gemini-cli-acp, which genuinely render nothing, so an omission stops being spelled the same way as a decision — and a test that every registered id has a row, since that is what failed silently here.

Test plan

• openspec change validate --strict — both valid
• npm run lint:english — passed
• Agent ids, capabilities, allowlist entries and adapter flags read out of the source, not recalled
• docs/images/standalone/harness-settings.png staleness confirmed against git log
• CI green

🤖 Generated with Claude Code