v1.58.0.0 feat: /pr-prep — pre-PR upstream duplicate audit + /ship Step 1.5 gate

[BenjaminDSmithy]

Summary

New /pr-prep skill: a pre-PR upstream duplicate audit. It walks git log base..HEAD, derives search keywords per commit from the subject + changed file
paths, queries the upstream repo's open issues and PRs via gh, and scores each
commit against open work (EXACT_DUP / OVERLAP / SIBLING / CLEAN). EXACT_DUP
refuses to proceed. /ship runs it as a Step 1.5 gate before any merge, test,
or version bump.

Why it helps you, the maintainer: it kills duplicate community PRs before
they're filed — the triage you do most. (Dogfood result below.)

What it does

• Step 1.4 — reads the upstream CONTRIBUTING.md: pre-push gates, test
  layout, branch/commit conventions, banned patterns. Used inline when writing
  the PR body.
• Step 4 — title-token + file-overlap Jaccard scoring, state-weighted. The
  bucketing is implemented in bin/gstack-pr-prep-score (pure, unit-tested) and
  referenced by the skill as the canonical scorer.
• Step 4.4 — optional codex second opinion on CLEAN commits (different model
  family for independent signal; soft-skips if codex is absent).
• Step 4.5 — per-commit pre-push gate + trigger-path + tests-added annotation.
• Step 4.6 — commit-message style conformance against the upstream repo's
  convention (sampled from its CONTRIBUTING.md + git log), not the
  contributor's personal house style.
• /ship Step 1.5 — invokes pr-prep with GSTACK_FROM_SHIP=1; EXACT_DUP aborts
  ship with resolution paths; skips cleanly on solo repos and --skip-pr-prep.

Dogfooded on itself

Ran /pr-prep on this branch against garrytan/gstack@main: CLEAN — 13/13
commits, no EXACT_DUP, no OVERLAP, in ~30-60s of gh queries. No existing
pr-prep / duplicate-audit skill upstream; the open ship PRs all touch unrelated
parts of the flow. Full audit is in a comment on this PR.

Tests + release

• test/pr-prep-score.test.ts — 13 deterministic cases pinning the scorer's
  bucket thresholds (gate-tier, free).
• Registered in AGENTS.md, docs/skills.md, scripts/proactive-suggestions.json,
  and test/skill-coverage-matrix.ts.
• Ship golden baselines refreshed (Claude / Codex / Factory); ALLOWED_SUBSTEPS
  updated for the new Step 1.5 sub-step.
• v1.58.0.0 (MINOR) + CHANGELOG entry; VERSION / package.json synced.
• bun test is green except environment-specific cases (local Swift toolchain,
  gbrain config, local git state) that also fail on a clean main.
• Note: as a cross-repo fork PR, the eval/E2E CI jobs can't receive base-repo
  secrets, so those will error regardless of code; happy to push the branch to a
  base-repo branch and re-target if you'd prefer green eval CI.

Motivation

Real case (2026-05-26): a contributor branch on garrytan/gbrain had 8 commits
ready for upstream PRs. Without pr-prep, 4 of 8 unverified commits would have been
duplicates of already-open work:

• e96332c5 (reindex CLI_ONLY one-char fix) → setup: add GSTACK_SKIP_PLAYWRIGHT to skip Chromium install #913, open 14 days, same fix
• 74819cec (sourceId fallback) → fix: make bin root detection CDPATH-safe #836, open
• 787da2af + 829099f9 (synopsis env-override) → setup --host cursor errors out despite README + hosts/cursor.ts declaring full Cursor support #1358, open, same pattern
• e0133d8a (LM Studio recipe + Ollama dims_options) → fix: normalize line endings in template reads for cross-platform generator #1051 + Multiple Claude Code security hook triggers in /codex and /autoplan skill templates #1329, crowded
• 2db6b6d4 (--lock-duration flag) → plan-eng-review: add throughput planning readout #1014 issue + Fix gstack build when Conductor creates a repo with unborn HEAD #1177 PR

Each would have cost a triage round and a close. pr-prep catches all of them in
one gh query pass before anything is filed.

[BenjaminDSmithy]

Updated this branch.

Rebased onto main (v1.57.8.0) — clean, no conflicts.

Commit messages now follow the repo convention across every commit: type(scope): subject, plain-prose body, and the Co-Authored-By trailer this repo uses. Also dropped a "+ tests" subject that didn't match its diff.

New — Step 4.6 in /pr-prep: commit-message style conformance. The audit now checks each commit against the upstream repo's own convention (CONTRIBUTING.md commit rules → de-facto shape sampled from git log upstream/<base> → conventional-commit fallback) and flags personal-template bodies, missing or extra trailers, and subjects that promise content they don't contain. Soft warning, never blocks — style isn't a duplicate, but it's the cheapest reviewer-goodwill win in the audit.

Test + registration fixes so the branch is green:

• Added 1.5 to ALLOWED_SUBSTEPS for the new Step 1.5 ship gate (skill-validation step-numbering).
• Registered /pr-prep in AGENTS.md and docs/skills.md (doc-inventory cross-check).
• Added /pr-prep to test/skill-coverage-matrix.ts with a gate-tier test.
• Regenerated pr-prep/SKILL.md and scripts/proactive-suggestions.json against the current resolvers.
• Refreshed the three ship golden baselines (test/fixtures/golden/{claude,codex,factory}-ship-SKILL.md) for the Step 1.5 block.

bun test passes on all PR-relevant checks. The only remaining failures are environment-specific (local Swift toolchain, gbrain config, local git state) and reproduce on a clean main.

[BenjaminDSmithy]

Dogfooded /pr-prep on this PR

Ran the skill's own audit against garrytan/gstack@main (the thing it's built to do — so it seemed only fair to point it at itself).

Result: CLEAN — 11/11 commits, no EXACT_DUP, no OVERLAP.

• No existing /pr-prep or pre-PR duplicate-audit skill upstream (closest hit, #1343 /plan-status, is an unrelated plan-progress checker).
• The /ship Step 1.5 gate doesn't collide with the open ship PRs (#1716 SHIP-RECEIPT, #632 ship log, #684 resume-safe reruns, #1862 package-lock sync, #842 stack-aware tests, #338 review-satisfies-ship, #1944 REST updates) — all touch different parts of the ship flow; none add a pre-PR audit step.

So this contribution isn't duplicating open work, and the skill demonstrably runs end-to-end on a real branch.

[time-attack]

@16francej — recommend closing this PR. Thanks for putting this together. We aren’t accepting new standalone skills right now, so we’re going to pass on this proposal. We can revisit the area later if it becomes part of GStack’s core workflow.

[BenjaminDSmithy]

TL;DR
  Split      Unrelated bug fix pulled out into #2640. This PR is /pr-prep only.
  Ask        Reconsider the standalone-skill call, or tell me to fold it into
             /ship Step 1.5 with no new catalog entry. Either ships same day.
  Evidence   Three tracker waves in five weeks closed 111+ stale or duplicate
             items. Your own v1.64.0.0 notes: contributors "independently
             fixed the same bug within days of each other".
  Ready      Clean branch off main: 15 files, +2,532/-10, suite green.
  Cost       Standalone version = one catalog entry. Ship-only version = zero.

@time-attack @16francej @garrytan: tagging all three, since this is a policy call rather than a code review.

Understood on the policy, and the reasoning holds: a new skill is a permanent cost to the discovery catalog that every user pays whether they run it or not. test/skill-size-budget.test.ts prices that exactly. If the answer stays no I'll close this.

Two things first.

Split for review

This PR had accumulated work that has nothing to do with /pr-prep. I've pulled the unrelated half out into #2640 (a heredoc deadlock that hangs ./setup --help on any Mac with Homebrew bash on PATH, 11 scripts affected, pure bug fix, no new skill). Judge them separately. #1696 is now only the duplicate audit.

Why this one is worth reconsidering

It isn't a workflow skill competing for catalog space. It reduces your triage load, and your own release notes make the case:

• v1.64.0.0: "82 contributors are named in this release, several of whom independently fixed the same bug within days of each other. That duplication is the tracker telling us how many people hit the same wall."
• v1.68.0.0: 90 open PRs and 21 stale issues closed with receipts in one day.
• v1.67.0.0: ~35 issues closed, 25 community PRs landed with credit.

Three waves in five weeks. A real share of that queue was people solving what someone else had already solved. Each one cost a contributor hours and cost you a triage slot. The data that would have prevented it was public and one gh call away the entire time. It just wasn't in anyone's workflow.

That's the gap. Before a branch becomes a PR, /pr-prep walks git log base..HEAD, queries your tracker, and buckets each commit: EXACT_DUP, OVERLAP, SIBLING, CLEAN. EXACT_DUP blocks and prints the colliding PR, its author, and three ways out (close yours and comment on theirs, cherry-pick the unique parts, or --force if already coordinated). OVERLAP and SIBLING don't block; they ride into the PR body as collapsed context.

Wider point: this isn't a gstack problem. Every project with an active tracker and drive-by contributions has it, and no tooling checks. gstack is already what runs at the moment a PR gets opened, which makes it the one place the check actually fires. Cutting duplicate-PR waste across open source looks on-mission for a workflow tool, and nothing else ships it.

Taking your condition literally

You said you'd revisit it "if it becomes part of GStack's core workflow". So: if the blocker is the catalog entry, I'll ship it as /ship Step 1.5 only. The audit runs inline in ship, bin/gstack-pr-prep-score stays as the tested scorer, nothing new appears in the skill list. Zero discovery-budget cost, and it fires exactly where duplicates get created. Say the word and I'll cut that version.

State of the branch

Already landed here:

• Brought up to v1.68.1.0.
• Tracker reads flow through bin/gstack-issue-guard per v1.66.1.0. Upstream titles are attacker-authorable and the model judges them for similarity, so they were exactly the ingress the trust envelope exists for. test/tracker-guard-wiring.test.ts caught it.
• The ship gate was calling bin/gstack-skill, a binary that has never existed in this repo. It now invokes the skill the way gstack actually invokes skills. Real bug, found by your test suite.
• Bucketing thresholds live in bin/gstack-pr-prep-score as a pure unit-tested function instead of prose, so behaviour and documentation can't drift.

Ready to swap in: a branch cut straight from main at 15 files, +2,532/-10. Skill, scorer, tests, ship gate, doc entry, nothing else. It also closes a gap I found preparing it: Step 7 documented a machine-readable report and the ship gate branched on it, but nothing ever wrote one. It's now written unconditionally in a single jq -n call, at a per-repo path so two ships in different worktrees can't read each other's verdict.

bun run test:free is green on it except three failures that reproduce identically on a pristine main checkout here: path-validation symlink case, touchfiles detectBaseBranch, and the codex-hardening watchdog (flaky ~2 runs in 3 on stock main).

A PR can't be repointed at another branch, so swapping means opening a replacement and closing this one. Tell me which version you want, standalone skill or ship-only, and it'll be up the same day.

One note: I ran the audit against this PR before writing this. It found #1696.

[BenjaminDSmithy]

Opened #2642 against this PR's surface: /pr-prep searches upstream issues as duplicate candidates, but the unit of audit is always a commit and the gate is always gh pr create, so there is no mode for auditing an issue you are about to file.

It came out of using this skill in anger today. Filing a Claude Code bug report (anthropics/claude-code#88113) surfaced a near-title-match, anthropics/claude-code#66279, that turned out to be a different bug on a closer read, plus four more siblings worth citing. Without that sweep the report would have gone up with no reference to any of them and could reasonably have been closed as a duplicate. The audit had to be run by hand: Step 3's fetch loop with --repo, keywords typed in from the report, and Steps 4.4 through 4.6 skipped since there is no commit to score.

The issue has a proposed shape that reuses Step 3 and bin/gstack-pr-prep-score unchanged rather than forking them.

I would be glad to build it, folded into this PR or as a follow-up. I would rather wait for a steer on this PR first, though: whether you want /pr-prep in gstack at all, and if so what shape it needs to land. Adding issue mode grows the surface further, and I would rather not keep extending a PR that may not be the direction you want. A "no thanks" is a perfectly good answer and costs me nothing.

[BenjaminDSmithy]

Dogfooded this skill against its own branch and it found a false positive in its own Step 4 bucketing. Fixed in d1cd1eb, now part of this PR.

The ≥3 OPEN issues OVERLAP clause had no score floor, so it counted raw gh full-text hits. Running the audit over this branch's 24 non-merge commits, three chore(build) commits bucketed OVERLAP off a topScore of 0.05. Verbatim, for chore(build): regenerate SKILL.md after v1.68.1.0 merge (keywords regenerate skill merge):

{"bucket":"OVERLAP","topScore":0.05,"openIssueCount":4,"reasons":["OVERLAP: 4 open issues"]}

The four issues it counted were a triggers-frontmatter bug, a review-bias issue, $CLAUDE_CONFIG_DIR support, and Windows Smart App Control. None relate to regenerating a SKILL.md. On any repo with a busy tracker, generic chore/build keywords will pull three unrelated open issues every time, so those commits would have read OVERLAP forever.

It never false-blocked — OVERLAP is informational and only EXACT_DUP refuses — but a bucket that always fires stops being read, which defeats the point of the audit.

The fix adds RELATED_OPEN_ISSUE_FLOOR = 0.15: the clause now counts only open issues that individually clear the floor. It sits below the single-hit threshold (0.3) so a genuinely crowded topic still trips it when no single issue is a strong match, which is the case the clause exists for. An open issue carries state weight 0.7, so 0.15 requires title Jaccard ≥0.214 — real shared tokens rather than one incidental word. openIssueCount keeps its old meaning and a new relatedOpenIssueCount carries what the clause counted, so the JSON stays additive for consumers. Reason strings now name the floor.

Same dogfood pass after the fix: 4 OVERLAP → 1, and the survivor is 50c474ba at topScore 0.3333, tripping the legitimate single-hit threshold rather than the count clause. 23 CLEAN, 0 EXACT_DUP.

Worth flagging that the existing unit test asserted the old behaviour with three issues at Jaccard 0 — it encoded the noise as signal. I retargeted it at genuinely related issues (each scoring 0.2, between the floor and the single-hit threshold) rather than deleting it, and added a regression case built from the four real issue titles above.

To be clear on scope: this is a fix to code already in this PR, not the issue-mode work in #2642. That one is still parked pending your steer on whether /pr-prep is a direction you want at all.