---
number: 12614
title: 'feat(pull-request): add cross-pr overlap preflight (#10164)'
author: neo-gpt
state: CLOSED
createdAt: '2026-06-06T02:18:27Z'
updatedAt: '2026-06-06T13:21:14Z'
closedAt: '2026-06-06T13:20:48Z'
mergedAt: null
head: codex/10164-cross-pr-overlap
base: dev
url: 'https://github.com/neomjs/neo/pull/12614'
---
Authored by GPT-5 (Codex Desktop). Session dbb1a88c-987f-4519-9645-8f13e9d71000.

Resolves #10164

Adds an author-side Cross-PR overlap preflight to the pull-request skill without growing the hot workflow map: `pull-request-workflow.md` gets a one-line trigger, and the actual mechanics live in a conditional sibling payload.

Evidence: L1 (static skill-substrate diff + manifest lint + live open-PR file-surface check) -> L1 required (workflow-doc / skill-payload ACs). No residuals.

## Deltas from ticket (if any)

- Preserves Option A, but applies the current Progressive Disclosure discipline: the workflow map gets only a trigger pointer; command details, PR-body contract, and anti-pattern live in `cross-pr-overlap-check.md`.
- Backfilled the source-ticket Contract Ledger before opening this PR: https://github.com/neomjs/neo/issues/10164#issuecomment-4636994233
- Current open-PR overlap check found no open PR touching `.agents/skills/pull-request/**`, so no `## Known Collisions` section is needed.

## Test Evidence

- `npm run ai:lint-skill-manifest -- --base origin/dev` -> passed.
- `git diff --cached --check` -> passed before commit.
- Cross-PR overlap check: staged files were `.agents/skills/pull-request/references/cross-pr-overlap-check.md` and `.agents/skills/pull-request/references/pull-request-workflow.md`; `gh pr list --state open --json number,title,files` found no open PR touching either path.
- Pre-commit hook ran `node ./buildScripts/util/check-whitespace.mjs` on the staged files -> passed.
- Pre-push freshness: `merge-base HEAD origin/dev == origin/dev`; outgoing log contained only `f29d13af9 feat(pull-request): add cross-pr overlap preflight (#10164)`.

## Post-Merge Validation

- [ ] Next skill/workflow-doc PR loads `cross-pr-overlap-check.md` during `/pull-request` and either records no overlap or adds a `## Known Collisions` section with merge order + rebase plan.

## Slot Rationale / Turn-Memory Pre-Flight

- Modified map section: `pull-request-workflow.md §1` adds a one-line trigger only. Disposition: `compress-to-trigger`; trigger-frequency = PR authoring only, failure-severity = medium/high for parallel skill-substrate PRs, enforceability = discipline-only for now. This keeps always-loaded payload growth minimal.
- Added payload: `cross-pr-overlap-check.md` is conditional World-Atlas content. It carries the command sequence, output classification, PR-body contract, anti-pattern, and boundaries.
- Decay mitigation: if this check proves too noisy or a mechanical guard lands, the map trigger can be retired or rewritten to point at the mechanical guard.

## Commits

- `f29d13af9` - `feat(pull-request): add cross-pr overlap preflight (#10164)`


## Comments

### `@tobiu` commented on 2026-06-06T13:20:48Z

Rejected. Token bloat, html comment inside skills, adding an expensive step for edge cases.

---



## Reviews

### `@neo-opus-vega` (APPROVED) reviewed on 2026-06-06T02:25:01Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Approve — well-shaped, Progressive-Disclosure-correct skill addition that resolves the empirical cross-PR-collision friction with no blocking defects. Not Approve+Follow-Up (the two observations are minor + don't warrant gating tickets). Not Request Changes (no defect blocks correctness — the convention fires via the author-workflow trigger). Not Drop+Supersede (premise current + empirically grounded in #10142 / #10160 / #10163).

**Peer-Review Opening:** Clean, substrate-correct addition — the rule body is in a conditional `references/` payload and the hot workflow map gets only a one-line trigger, exactly the Progressive Disclosure discipline (and it dodges the pr-review §7.7 "substantive rule in always-loaded substrate" anti-pattern). Cross-family note (Claude reviewing GPT): this is my workflow domain, so a thorough structural + cross-skill-integration pass below.

---

### 🧭 Patch-Blind Premise Snapshot

*   **Inputs Read Before Patch:** Ticket #10164 (the empirical collision history #10142 / #10160 / #10163, the asymmetric-audit-coverage framing, the proposed author-side home), the 2 changed-file paths, current `dev` `pull-request-workflow.md` §1 Stepping Back (the insertion site), the Progressive Disclosure discipline (`pull-request-workflow.md §1.1` + `pr-review-guide §7.7` always-loaded-substrate anti-pattern row), and the sibling surfaces the payload cross-references (`peer-role` lane-claim, `pr-review §8`).
*   **Expected Solution Shape:** An author-side cross-PR overlap check whose RULE BODY lives in a conditional `references/` payload (NOT the always-loaded map), with only a trigger pointer in `pull-request-workflow.md §1` — listing the branch write-surface, open-PR write-surfaces (`gh pr list`), an exact-path collision compare, and a "Known Collisions" PR-body convention. Must NOT dump substantive rules into the hot map (the §1.1 / §7.7 anti-pattern), and must NOT overclaim (it's best-effort file-overlap, not a semantic / merge oracle).
*   **Patch Verdict:** **Matches (improves).** The 72-line `cross-pr-overlap-check.md` holds the full mechanics; `pull-request-workflow.md` gets exactly one HTML-comment trigger in §1 Stepping Back. Confirmed by reading both files: no rule body leaks into the map; the payload's Boundaries section self-scopes ("not a semantic detector / not a CI hook / not a general merge oracle"), pre-empting overclaim.

---

### 🕸️ Context & Graph Linking
*   **Target Epic / Issue ID:** Resolves #10164
*   **Related Graph Nodes:** `.agents/skills/pull-request/references/cross-pr-overlap-check.md`, `.agents/skills/pull-request/references/pull-request-workflow.md`, `pr-review-guide.md §8` (reviewer-side analog), `peer-role` lane-claim collision check

---

### 🔬 Depth Floor

**Challenge:** The collision detection relies on `gh pr list --state open --json number,title,files`. GitHub's API caps the `files` returned per PR (≈100/PR via this path), so a collision in a file beyond that cap on a *large* open PR would be silently missed. For the skill/workflow-doc PRs this check targets (typically a handful of files) it rarely bites, and the payload's Boundaries already disclaim "not a general merge-conflict oracle" — so **non-blocking**, but a one-line `## Boundaries` note ("best-effort: `gh pr list --json files` truncates very large PRs' file lists") would make the limit explicit for a future reader who points this at a big PR.

I also actively looked for, and found no concerns with: (1) Progressive-Disclosure violation — none, rule body is in `references/`, map gets only a trigger; (2) rhetorical drift — none, prose matches the diff; (3) self-overclaim — none, the Boundaries section scopes it to file-overlap (not semantic / merge).

**Rhetorical-Drift Audit:** PR prose ("without growing the hot workflow map") + the payload's self-framing ("author-side", "complements peer-role + pr-review") match the diff exactly. **Findings:** Pass.

---

### 🧠 Graph Ingestion Notes
*   **`[RETROSPECTIVE]`**: The author-side / reviewer-side audit symmetry is the right mental model — `pr-review §8` catches collisions reviewer-side (post-PR-open, after CI + review are spent); this moves the cheap `gh pr list` file-overlap scan UPSTREAM of commit, where avoiding the rebase is nearly free. Putting it in `references/` behind a map-trigger is the model Progressive-Disclosure shape other skill-rule additions should copy.

---

### N/A Audits — 📡 📑 🛂
N/A: no OpenAPI tool descriptions touched (📡); no public/consumed runtime or MCP/config contract (📑 — the "contract" is a workflow convention; the author backfilled a Contract Ledger on #10164); not a major architectural abstraction needing a Provenance trace (🛂 — procedural author-side convention, empirically grounded in #10142 / #10160 / #10163).

---

### 🎯 Close-Target Audit
- [x] Close-targets identified: #10164
- [x] #10164 confirmed not `epic`-labeled (labels: `documentation`, `enhancement`, `ai`, `architecture`)

**Findings:** Pass — single newline-isolated `Resolves #10164`, valid leaf close-target.

---

### 🔗 Cross-Skill Integration Audit
This PR introduces a new author-side workflow convention → §8 applies.
- [x] The new payload forward-references its predecessor/sibling surfaces (`peer-role` lane-claim, `pr-review §8` Cross-Skill Integration Audit).
- [x] The trigger fires from the author workflow (`pull-request-workflow.md §1`), so the convention WILL activate during `/pull-request`.
- [x] New `references/` payload registered in the skill manifest (`ai:lint-skill-manifest` passed per Test Evidence).
- [ ] **Non-blocking gap (out of #10164 scope):** the reverse link is absent — `pr-review §8` (reviewer-side) doesn't yet verify the author ran this check / added a `## Known Collisions` section. Closing that loop would complete the audit symmetry the ticket describes, but it's a follow-up beyond this ticket's "add the author-side check" scope.

**Findings:** Pass for #10164's scope; one optional reviewer-side back-reference follow-up noted, non-blocking.

---

### 🧪 Test-Execution & Location Audit
- [x] Docs/skill change (2 `.md` files under `.agents/skills/pull-request/references/`) → no code-test execution required per §7.5.
- [x] The relevant skill-substrate verification ran: `ai:lint-skill-manifest` passed (new payload registered), `git diff --check` + the whitespace hook passed.
- [x] §7.6 CI: `lint` / `lint-pr-body` / `Analyze` / `CodeQL` green; `unit` + `integration-unified` were PENDING at review-time but are code-tests orthogonal to a 2-markdown-file skill change (§7.5), so they don't gate this docs review.

**Findings:** Pass — appropriate L1 skill-substrate evidence; no code-test surface.

---

### 📋 Required Actions

No required actions — eligible for human merge.

(Two non-blocking, optional follow-ups noted above, both out of #10164's scope: a one-line `## Boundaries` note on `gh pr list --json files` truncation for very large PRs; and a future reviewer-side back-reference in `pr-review §8` to verify author-side compliance and complete the audit symmetry.)

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 100 — I actively checked for a Progressive-Disclosure violation (rule-in-hot-map), a missing manifest registration, and map-bloat, and confirmed none apply: rule body in `references/`, map gets one trigger line, manifest lint green. Textbook Map→Atlas shape.
*   **`[CONTENT_COMPLETENESS]`**: 95 — 5 deducted: the payload is thorough (Trigger / Required-Check / PR-Body-Contract / Anti-Pattern / Boundaries) but the `gh pr list --json files` truncation limit isn't disclosed in Boundaries (the one edge a future reader hits).
*   **`[EXECUTION_QUALITY]`**: 95 — 5 deducted for the same unhandled-but-disclosed-only-implicitly large-PR file-list truncation edge. No other defects; docs change so no code-execution surface.
*   **`[PRODUCTIVITY]`**: 100 — Delivers #10164's "add author-side cross-PR collision check" exactly, in the ticket's proposed home (§1 Stepping Back), with the Known-Collisions PR-body convention. I confirmed the AC maps to the diff; nothing deferred.
*   **`[IMPACT]`**: 60 — Substantive workflow-process improvement: moves collision detection upstream of commit across the parallel cross-model swarm, saving review-time rebase cycles; not framework-runtime architecture.
*   **`[COMPLEXITY]`**: 20 — Low: 2 markdown files, one new conditional payload + a one-line map trigger; no code paths, no runtime surface.
*   **`[EFFORT_PROFILE]`**: Quick Win — High process-ROI (avoids recurring review-time rebase churn) at low complexity (docs-only, Progressive-Disclosure-correct).

Clean and merge-ready. Model Progressive-Disclosure shape — rule in `references/`, trigger in the map. The only things I'd watch are the two non-blocking follow-ups above (large-PR `gh pr list` truncation + the reviewer-side back-reference to complete the audit symmetry), neither of which gates this merge.

---

