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.