Close yolo, contract, and helper gaps from #78 #79

Goal

Close the 13 gaps that #78 lists in the plan-lifecycle plugin: the yolo skill, the plan contract, the plan-reviewer surfaces, and plan.mjs. Make the yolo skill apply code-clarity to every change of code, tests, comments, or error messages. After the fixes, run trial yolo runs in a disposable private repository, and fix in this plan each further gap that the trial proves with evidence.

Mode: plan-and-implement

Research

Repository facts (paths relative to the repository root):

• plugins/plan-lifecycle/skills/productivity/yolo/SKILL.md: Run order Decide says "The path is a plan... Ask nothing", and Draft always runs new (gap 1). Review loops has no rule for edits after plan=pass (gap 2). Research has no required-check rule (gap 3). The Run summary template has only <command>: <result> (gap 4). The constraints have no baseline-failure rule (gap 5). Engineering standards maps tdd-workflow but names no baseline owner or record (gap 6). Self-review has no record (gap 7). Landing step 1 says "Commit the reviewed bytes" with no commit timing (gap 8). Landing step 9 covers only a worktree (gap 9). No rule orders a merge answer and a new request (gap 10). code-clarity applies only to the row "Names, comments, errors, and function size".
• plugins/plan-lifecycle/skills/productivity/plan-manager/scripts/plan.mjs: setPlanStatus writes planned with placeholder Research; printAdvice only advises Research is not filled after drafting. after the write (gap 11). runGh throws gh <a> <b> failed: <stderr>; the top-level catch prints it on stderr with exit 1 and nothing on stdout. editPlan refreshes the .origin sidecar before the remote write, so a retry of the same file after a failed gh issue edit refuses as stale export (gap 12). No code reads the Files cell (gap 13).
• plugins/plan-lifecycle/skills/productivity/plan-manager/references/plan-contract.md: the refusal list has no gh failure and no retry rule (gap 12); Steps has no Files grammar and no overlap rule (gap 13); the review loop has no re-review rule after a pass (gap 2).
• plugins/plan-lifecycle/agents/plan-reviewer.md and plugins/plan-lifecycle/skills/productivity/plan-reviewer/SKILL.md: the goal_fit triggers do not cover a missing repository-required check (gap 3). The review block must stay identical in both files (plugins/plan-lifecycle/skills/AGENTS.md, Plan-skill contract sync).
• scripts/tests/plan-cli.mjs tests the helper with the stub scripts/tests/fixtures/gh-stub/gh; the stub fails every issue edit while state.issueEditError is set.
• Versioning (scripts/AGENTS.md): a pull request does not bump plugin versions; scripts/release.mjs bumps them after the merge.
• code-clarity lives at plugins/docks/skills/engineering/code-clarity/SKILL.md.

Decisions:

• Gap 11: status refuses planned and ongoing while the trimmed Research section is empty or equals _Not researched yet._. blocked stays allowed. The drafting advice uses the same test. Evidence for equality, not substring: this plan's Research quotes the placeholder in prose, and the 0.13.1 helper then printed Research is not filled after drafting. for this plan. Rejected: a done-when text change only, because it is not a gate.
• Gap 12: no automatic retry in the helper, because the server result of a failed write is unknown. The agent runs show first. edit refreshes provenance only after the remote write succeeds, so one retry with the same file works. Rejected: a helper retry loop.
• Gap 13: advice, not a refusal, with exact path equality after trimming and backtick removal. Rejected: a refusal, because Files cells can hold folders or globs.
• Gap 2: a contract rule, plus edit advice when a trusted plan pass exists and Goal, Research, Steps, Acceptance, or Do not touch changed. Rejected: a derived stale verdict, because issue updatedAt also changes on comments.
• Gap 9: switch a clean user checkout back to the default branch; keep the merged local branch and name it in the report. Rejected: a branch-deletion question, because yolo asks only the merge question.
• Gap 8: commit each step when its proof passes; review fixes are new commits.
• The trial uses a disposable private repository and the branch files, not the installed plugin.

Trial decisions (gaps 14-18; evidence in Verification Results):

• Gap 14: a red baseline can fail on a missing export or symbol that the step adds. Any other import, setup, or syntax failure is not a red baseline. Do not add an empty stub. Reason: tdd-workflow says "the compile error IS the failing baseline" and lists "Add an empty function foo() {} stub" as the wrong fix; yolo Red baseline item 2 required an assertion failure. Rejected: keep the yolo text, because two docks rules then conflict.
• Gap 15: the run summary gets its pull request URL and check state after the checks finish, through gh pr edit --body-file. An open pull request for the branch gets its body updated instead of a second gh pr create. Rejected: write the summary after gh pr create, because gh pr create needs a body.
• Gap 16: the run summary is the pull request description; commit-discipline owns the commits only. Rejected: merge both formats, because the run summary already holds what changed, verification, and decisions.
• Gap 17: temporary check worktrees use ${XDG_DATA_HOME:-$HOME/.local/share}/agent-worktrees/<repository-name>/check-<short-sha>, the same root as the contract's yolo worktree. Rejected: the review scratch directory, because it is inside .git.
• Gap 18: Research is done for an adopted plan that is already ongoing; the Done when names that case. Rejected: move the plan back to planned, because the contract refuses that transition after work starts.

Steps

Acceptance

Do not touch

Plugin manifest and marketplace version fields (scripts/release.mjs bumps them after the merge). Skills of the docks plugin. Frozen docs/plans/finished/ history.

Open questions

Verification Results

Gates and helper probes

• Each of steps 1-7: node scripts/tests/plan-cli.mjs printed the PASSED line, and node scripts/ci.mjs --plugin plan-lifecycle passed on the committed step in a clean worktree.
• Red runs before each helper change: step 1 AssertionError: status planned requires a filled Research section (actual 0, expected 1); step 2 stale export: ... was exported from a superseded body; step 3 only steps without a Depends chain get shared-path advice; step 4 the re-review advice regex did not match.
• Step 6: the ### Plan review round <N> blocks of both plan-reviewer files are byte-identical (110 bytes each).
• Step 7: yolo SKILL.md has 316 lines; the run summary moved to references/run-summary.md. Score 16 against the productivity floor 8.
• Full node scripts/ci.mjs on the step 7 head failed bun run check:js on the format of one scripts/tests/plan-cli.mjs call. The plugin gate does not check that file. The format commit fixed it, and the full gate then passed.
• A3 on the disposable trial repository: status 1 planned with placeholder Research printed status planned requires a filled Research section, exit 1.
• A4 on the disposable trial repository: edit printed advice: steps add_truncate and fix_slugify share src/text.mjs with no Depends link. After a posted plan-review pass, a Research edit printed advice: plan review passed before this edit; changed sections: Research; run a new plan-review round before code that depends on them. The probe plan was retired.

Trial runs

Three yolo runs used the branch files in the disposable trial repository. Run A took the truncate and slugify request. Run B received the cut-off request check the open pull request and. Run C started in the message that answered run B's merge question. The user answered Merge now for runs B and C. Trial issue and pull request numbers below refer to that repository.

Accepted gaps (trial event quote plus rule text):

• Gap 14. Event (run A): "I added an empty truncate declaration first. Without it, the missing named export fails the whole test file at import." Text: yolo Red baseline item 2 "Each new test must fail on an assertion, not on an import, setup, or syntax error" against tdd-workflow "Add an empty function foo() {} stub ... the compile error IS the failing baseline."
• Gap 15. Event (runs A and C): "I wrote "this pull request" and "pending when opened" first. After the checks passed, I filled in the real values with gh pr edit --body-file." Run B replaced the body of an existing pull request without a rule. Text: Landing step 4 writes the summary before step 5 opens the pull request, and the template starts "Pull request: . Checks: ."; Landing step 5 only names gh pr create.
• Gap 16. Event (run A): "I used only the yolo run-summary template and dropped the commit-discipline sections". Text: Engineering standards row "Commits and the pull request description | commit-discipline" against Landing step 4 "Write the run summary from references/run-summary.md".
• Gap 17. Event (run A): "For the lint check on origin/main, I put the worktree under the review scratch directory". Text: grep -rn "temporary worktree" plugins/plan-lifecycle finds only yolo "Run the same check on origin/<default> in a temporary worktree." with no path.
• Gap 18. Event (run B): "The Research "Done when" cannot be tested on an adopted plan that is ongoing." Text: Run order Research "status <n> planned succeeds" against the contract "After it starts, only ongoing and blocked are legal targets."

Rejected candidates: reviewer wrappers from the installed plugin (a trial setup effect: the trial forbade the installed plugin); a review fix that changes a spec assertion (Red baseline item 4 covers it); acceptance for a check that fails on the default branch and a missing type checker (Checks that fail outside the goal covers it, and the run recorded it); the meaning of "check" and of "the open pull request" (the incomplete-request rule covers both, and the run followed it); summary content for an adopted plan, and where adoption facts go (the template and the contract sections cover them); acceptance rerun when the default branch did not move (no rule forbids it); merge method (the contract permits any method that the repository allows); remote and earlier-run branches (no deletion happened, which is the safe default); the user's checkout in an adopted run, code-clarity on a README code block, proof for a non-tdd-workflow step, and review results in Verification Results (each run followed the existing text).

Proofs for steps 12-16

Each step was committed alone, and node scripts/ci.mjs --plugin plan-lifecycle passed on each commit. A fresh read-only agent then got the trial situation and the new yolo text, without the expected answer.

• Step 12 (gap 14): "Yes, this is a valid red baseline ... The docks tdd-workflow skill agrees". The agent found that "for it" did not say whether the record replaces the counts. A new commit now says "instead of the counts for that file".
• Step 13 (gap 15): "You write pending for both the URL and the checks ... The real values go in only after the head check in step 7"; for an open pull request: "You use gh pr edit for the body, not gh pr create."
• Step 14 (gap 16): "For the pull request description, use the yolo run summary as written, with nothing added. For commit messages, follow commit-discipline. The two texts do not conflict".
• Step 15 (gap 17): the agent gave git worktree add --detach "${XDG_DATA_HOME:-$HOME/.local/share}/agent-worktrees/yolo-trial/check-ea9eab9" ea9eab9 and "the path must not be under /tmp or inside .git". It noted that no fetch came before the check. A new commit adds git fetch origin <default> first.
• Step 16 (gap 18): "Research counts as done ... This plan reads ongoing". It found that the Draft Done when could not be met by an adopted plan. A new commit adds "The run adopted a plan" to that Done when.

Acceptance on the candidate head

• A1 node scripts/tests/plan-cli.mjs: exit 0; PASSED line ends with machine path advice, research gate, edit retry, shared files advice, re-review advice.
• A2 full node scripts/ci.mjs on 9105202b: All ci.mjs checks passed - 2 plugin(s) + repo-wide.
• A3 and A4: see Gates and helper probes. A5: see Trial runs.