Close mechanical-checks 6.3, and document how a chain moves and the git stage is driven

[VeryComplexAndLongName]

Two commits: the last open task of harness-mechanical-checks, and three additions to the agentic-harness-documentation proposal.

harness-mechanical-checks 6.3 — 31/31

The parser change was the one thing in that change whose blast radius is every tasks.md in the repository, and the five tests for the new syntax all ran over fixtures. This one reads openspec/changes/*/tasks.md from disk, compares readTaskChecklist's item count against an independent count of checkbox lines for each, and asserts none of them already carries the new declaration — which a raw-text search could not do, since that change's own tasks.md describes the syntax in prose.

Written by the session that implemented the change; committed here so the working tree could return to main.

Three files it also touched are left out. gh-pr-gateway.test.ts, git.push.test.ts and harness-chain-runner.ts differed only in indentation — an editor reformatting on save — and git diff -w shows all three as empty. Committing 358 lines of whitespace would bury the next real change to those files. There is no .editorconfig in the repository, which is why the editor had nothing to follow; worth adding separately.

Documentation proposal — three additions

Where a chain starts, and what a user can steer

A chain does not always begin at propose. determineStartStage reads the change's own artifacts and task counts and enters at the first stage with work left, so running a chain twice resumes. When progress cannot be determined it enters at apply, deliberately — a redundant apply costs one run, a wrong archive costs an unimplemented change.

Going back is a different mechanism, and the document has to say so rather than imply it:

A chain runs forward only. There is no control that steps a running chain back to an earlier stage.

Re-running an earlier stage means running that stage on its own — the panel's per-stage commands go through RunController, not through the chain. A checkpoint offers confirm or cancel, not redo.

Switching to another change while one runs

The question with the least obvious answer, so it gets its own task. WorkbenchProcessScheduler holds a single mutationLocked flag for the whole workspace, so a second mutating run enqueues rather than starting, and ADR 0010's lease extends that to a second editor or host on the same workspace. Non-mutating runs (status, list, show, validate) are not blocked — which is the difference between a stuck UI and a working queue.

The git stage

Its own section: what it does, that it runs only under a per-change reviewGate.mode: "agent-sufficient" and that the default ends the chain cleanly after archive, the per-change allowlist, the prerequisite that gh is on PATH and already authenticated, and that every action is audited including blocked ones.

The check gate stated as what it is: the merge waits, refuses a pull request whose checks have not passed, treats an absent or all-skipped result as refusal, and cannot be configured off.

That section describes a stage nothing here has run end to end. agentic-harness-git-stage task 4.4 is still open, and three of the four defects found in review sat precisely behind it. So the section says so to the reader (2B.7), and a verification task (6.8) requires every sentence in it to be traceable to runGitStage, gh-pr-gateway.ts or ADR 0014 — not to how such a stage would reasonably behave.

Test plan

• task-checklist.test.ts — 17/17, including the new real-tree block
• openspec change validate --strict agentic-harness-documentation — valid
• npm run lint:english — passed
• Excluded files confirmed whitespace-only via git diff -w
• CI green

🤖 Generated with Claude Code