fix(code-review-gate,review-pipeline): run /code-review directly ahead of headless

[ultimatile]

Summary

code-review-gate rested on the premise that the Skill tool cannot invoke the built-in /code-review, and that premise no longer holds. The gate now tries a direct Skill-tool invocation first when the session already sits in the working tree under review, and keeps the headless claude -p lane behind it, because a driver without a Skill tool, a session started elsewhere, and a Claude Code session in which direct invocation is disabled all still need a way to get a Claude review.

Closes #236 Closes #238

Changes

• code-review-gate takes a third input, the review tree: the absolute path of the working tree that holds the change. The gate reads what it reviews there — the branch's committed diff against the root, the uncommitted changes, and the untracked files — and every lane that runs the review command runs it there.
• The review command, /code-review <effort> <root-rev>...HEAD, is defined once and referenced by each lane that runs it. <effort> is the caller's effort and <root-rev> is the caller's root (the branch the change merges into), refreshed from origin when it is a branch.
• Lanes are named rather than numbered. The chain is built at each gate run. When the review tree has untracked files, the chain is the subagent lane alone, as it was before this change. Otherwise it is direct, headless, user, subagent, with the direct lane included only when the session's primary working directory, as the harness states it in the session's environment, is the review tree. A lane left out of the chain is neither entered nor abandoned, and a lane abandoned earlier in the PR stays abandoned.
• The direct lane invokes the review command through the Skill tool and never switches the session to another directory. When the Skill tool runs the review in the background, the lane's output is that run's final result, not the launch acknowledgment. The lane is abandoned without retry when the Skill tool is absent or refuses the call.
• The user lane gives the user the review tree's path to run the command in.
• The lane the gate notes for each iteration (each gate run within one PR), which feeds the run's review-telemetry record, is recorded by name, for example lanes: [direct, direct, headless].
• The code-review-gate skill's description frontmatter and its README.md row no longer state the cannot-invoke premise or enumerate the lanes.
• review-pipeline Phase 0.5 passes, as the review tree, the working tree in which it ran its /stage-commit-push step, and re-runs the gate with every input its first run passed.
• metadata.version in .claude-plugin/marketplace.json is 2026.9.10.

Impact

review-pipeline is the only skill that invokes code-review-gate directly, and it now supplies the new input. land-via-integration-branch reaches the gate through review-pipeline Phase 0.5, so it needs no change. review-telemetry records written before this change carry numeric lane labels, and records written after it carry names.

Verification

• With the session's primary working directory set to this branch's worktree, the gate's direct lane ran /code-review medium over the branch range through the Skill tool, and the run returned an explicit clean verdict with no findings.
• Before implementation, two direct invocations against a probe branch showed that the invocation reviews the session's working directory rather than the shell's current directory. With the session in a different checkout it reported an empty range; after the session was moved into the probe worktree it reported a committed, an uncommitted, and an untracked-file bug.
• pre-commit run --files over each changed file: mdformat passed.

Plan-vs-actual delta

Compared against the Scope, Out of scope, and Acceptance of #236.

Scope additions

• The review tree became a third gate input, and review-pipeline changed with it, although Phase 2: Direct Skill-tool lane ahead of headless in code-review-gate #236 stated that review-pipeline would not change. The first version located the tree only through a definition inside the gate, "the working tree the caller commits the change in". The pre-merge audit then reported three times that the direct, headless, and user lanes all need the tree's path while the gate's written inputs named only effort and root. The fix makes the caller supply the path, and review-pipeline Phase 0.5 passes the tree in which it ran its commit step.
• The review command is defined once and referenced by the headless and user lanes. Phase 2: Direct Skill-tool lane ahead of headless in code-review-gate #236 had those two lanes keep their text apart from renaming. Without the shared definition, the direct lane would have added a third copy of the same command string.
• The headless lane's "From the repo root" became the general rule that every lane running the review command runs it in the review tree.
• The direct lane's output rule states its condition: it applies when the Skill tool runs the review in the background.
• review-pipeline Phase 0.5 re-runs the gate with every input its first run passed, and it points at the gate for choosing the effort instead of restating the gate's effort rule (medium by default, high for a large or risky diff). Both changes answer the Copilot finding in this thread, which read the earlier re-run wording as dropping the root.

Scope changes

• Phase 2: Direct Skill-tool lane ahead of headless in code-review-gate #236 had the direct lane switch the session into the review tree with EnterWorktree when the session was elsewhere. After that switch the session stayed worktree-isolated for the rest of the run, and Claude Code then refused later commands that contained the substring git or chained several commands. The direct lane therefore no longer switches the session: it joins the chain only when the session already sits in the review tree, and the chain starts at the headless lane otherwise. This resolves code-review-gate direct lane leaves the session worktree-isolated for later phases #238, which had asked whether the lane should leave the worktree again after its run.

Scope subtractions: none.

Out-of-scope churn

• The three deferred items of Phase 2: Direct Skill-tool lane ahead of headless in code-review-gate #236 are unchanged: whether the headless lane runs from a Codex-driven session, the review-pipeline-codex skill, and relaxing the untracked-part rule for the direct lane.

Acceptance

• No sentence in code-review-gate or the README.md row states that the Skill tool cannot invoke /code-review: met.
• Every direct-lane outcome maps to exactly one of a valid review, a lane failure with retry, or abandonment without retry: met. The case where the session sits outside the review tree no longer reaches the direct lane at all.
• This change's own review-pipeline run passed its code-review gate through the direct lane: met, as the first Verification item records.

[Copilot]

Copilot review overview

🟡 Changes recommended

The fix-loop re-run omits the gate’s required root input.

Review effort: Balanced
Findings: 1

Open (1)

• Pass the diff root explicitly on every gate re-run · New

What changed in this PR

Adds direct /code-review Skill-tool execution before existing fallback lanes.

Changes:

• Adds review-tree-aware direct, headless, user, and subagent lanes.
• Passes the review tree from review-pipeline.
• Updates documentation and bumps the plugin version.

File	Description
skills/​code-review-gate/​SKILL.md	Defines the direct lane and named fallback chain.
skills/​review-pipeline/​SKILL.md	Supplies the review tree to the gate.
README.md	Updates the gate description.
.claude-plugin/​marketplace.json	Bumps version to 2026.9.10.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approval recommended

The updated contracts, caller integration, fallback behavior, documentation, and version bump are consistent and complete.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Pass the diff root explicitly on every gate re-run

[Copilot]

Copilot review overview

🟢 Approval recommended

The lane flow, root contract, caller integration, documentation, and version bump are consistent and complete.

Review effort: Balanced
Findings: None