diff --git a/plugins/code-tidying/skills/tidy/SKILL.md b/plugins/code-tidying/skills/tidy/SKILL.md index 4250ae99b..4b6110c39 100644 --- a/plugins/code-tidying/skills/tidy/SKILL.md +++ b/plugins/code-tidying/skills/tidy/SKILL.md @@ -132,7 +132,11 @@ Self-review by the producing context is enough here — a fresh-context verifier ### Phase H — Ship -Create the PR (`gh pr create`) with title: +Never call `git commit` or `gh pr create` directly — Phase E already committed the tidyings, so what's left is PR creation, and that has a canonical gate (issue-linkage resolution, injection-safe body assembly, a pre-create check for a valid closing keyword or explicit opt-out) that a bare `gh pr create` skips entirely. + +If the `source-control` plugin is installed, invoke `/pull-request create`. Its stage-and-commit step is a no-op here (tree is already clean from Phase E), so it goes straight to rebase-check, issue-linkage resolution, and gated PR creation. Supply it this PR's title and body content — the canonical flow's body template is fixed to Summary + Test plan (`plugins/source-control/skills/pull-request/reference/create.md` §2.4.1), so give it only those two sections; tidy's own audit-trail content goes in a follow-up comment (below), not the PR body: + +Title: ```text (): @@ -144,13 +148,29 @@ Examples: - `docs(skills): repair stale cross-references` - `chore(tools): apply shellcheck/shfmt drift across tools/*.sh` -PR body sections: +Body sections: - **Summary** — 1-3 bullets: which lane, which tidyings, anchor commit. -- **Tidyings applied** — table: tidying type → file → line range → LOC delta. -- **Deferred items** — if the scope budget capped the run, link filed issue numbers. - **Test plan** — verification commands run + results. +`/pull-request create` reports the created `` back on completion (its own §2.6 "Report and stop"). Immediately post one follow-up comment on that PR with `tidy`'s own audit trail — content the canonical body template has no slot for: + +```bash +gh pr comment --body-file - <<'EOF' +## Tidyings applied + + + +## Deferred items + + +EOF +``` + +The comment itself is never optional when a PR was created — "Tidyings applied" is never empty at that point (Phase D's empty-PR-avoidance rule means no PR gets created when there's nothing to tidy), and it's the only place this content appears now that the canonical body template has no slot for it. Only the "Deferred items" subsection is conditional: omit it when nothing was deferred, and never post it as an empty table. + +If `source-control` isn't installed, apply the same invariants inline: resolve issue-linkage before writing a closing keyword (`Closes #N` only after confirming issue #N exists in this repo — e.g. `gh issue view N`; otherwise state `No related issue: `), assemble the body via a quoted heredoc (`<<'EOF'`) plus parameter-expansion concat rather than an unquoted `< --watch`) until green. Address review-bot findings: verify each against the current code — fix the correct ones, rebut the incorrect ones with evidence. **Manual merge by a human** — this skill does NOT auto-merge. ## Global HARD/SOFT EXCLUSIONS @@ -185,7 +205,7 @@ Full template: [reference/scope-budget.md](reference/scope-budget.md). Summary: - Every item the scope budget cuts becomes one filed work item. - Title format: `(): `. - Body must include: rationale, file list, scope estimate (LOC + files), and a link to the parent tidy PR. -- The PR body's "Deferred items" section links every filed item by number. +- Phase H's "Deferred items" follow-up comment (or, when `source-control` isn't installed, the PR body's own "Deferred items" section) links every filed item by number. ## Gotchas diff --git a/plugins/code-tidying/skills/tidy/reference/scope-budget.md b/plugins/code-tidying/skills/tidy/reference/scope-budget.md index 58dc61713..39a911403 100644 --- a/plugins/code-tidying/skills/tidy/reference/scope-budget.md +++ b/plugins/code-tidying/skills/tidy/reference/scope-budget.md @@ -51,7 +51,7 @@ When the hunt phase produces more candidates than fit in the budget: 3. **Defer the rest.** For each unselected candidate above a "would-be-worth-doing" threshold (i.e., not trivial micro-tidyings — those just go away), file a work item using the deferred-items template below: via `/work-items:track add` when that plugin is installed, else `gh issue create`, else present the list to the user. -4. **Record the deferred issue numbers in the PR body** under a `## Deferred items` section. This makes the PR's review obvious-by-default: "here's what I did, here's what I parked for next time, here are the issue numbers to hold me accountable." +4. **Record the deferred issue numbers** under a `## Deferred items` section — in Phase H's follow-up PR comment when `source-control` is installed, otherwise directly in the PR body. This makes the PR's review obvious-by-default: "here's what I did, here's what I parked for next time, here are the issue numbers to hold me accountable." ### Greedy vs. optimal selection @@ -128,6 +128,6 @@ No upper bound on deferred issues per run. If a single run defers >10 items, tha 1. **Phase D (Hunt + prioritize + scope-budget enforce)** — after building the prioritized findings table, sum the LOC deltas. Apply the greedy selection. 2. **Phase E (Implement)** — periodically check actual LOC delta against the running estimate (`git diff --stat origin/...HEAD`). This measures the full branch diff — all commits since the branch point, not just uncommitted changes relative to HEAD. If actual exceeds estimated by >25%, stop the current tidying mid-flight and re-budget. -3. **Phase H (Ship)** — the PR body's `## Deferred items` section comes directly from this protocol's filed-issue list. +3. **Phase H (Ship)** — the `## Deferred items` section (follow-up comment, or PR body when `source-control` isn't installed) comes directly from this protocol's filed-issue list. If the cap numbers themselves need to change, that's a research-driven update — not a tidy. See the SELF-UPDATE EXTRA HARD list in `reference/exclusions.md`.