BitPod-App · cjarguello · Apr 28, 2026 · Apr 28, 2026
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -6,6 +6,12 @@
 
 <!-- Link the related Linear issue, e.g. https://linear.app/bitpod-app/issue/BIT-000/... -->
 
+<!-- If this PR changes or closes tracked work, verify PR-to-Linear closeout per linear/docs/process/linear_operating_guide_v3.md rule 14. -->
+
+- [ ] PR-to-Linear mapping verified when applicable
+- [ ] Project scope / status class / labels verified when applicable
+- [ ] Bidirectional PR + Linear links verified when applicable
+
 ## Taylor01 Portability Check
 
 <!-- Required when the PR touches agents, workflows, process docs, workspace policy, or tool integration behavior. -->

diff --git a/linear/README.md b/linear/README.md
@@ -29,8 +29,20 @@ This folder contains the Linear tool surface plus the process canon that governs
 - `./docs/process/interim_ai_technical_qa_cj_acceptance_policy_v1.md`
 - `./docs/process/linear_admin_change_control_v1.md`
 - `./docs/process/linear_change_proposal_template_v1.md`
+- `./docs/process/linear_link_reference_policy_v1.md`
+- `./docs/process/linear_issue_template_evidence_contract_v2.md`
 - `./docs/process/linear_operating_guide_changelog.md`
 
+## PR-to-Linear closeout enforcement
+
+Before merge closeout, retroactive linking, or Linear normalization, read:
+
+1. `./docs/process/linear_operating_guide_v3.md` rule 14
+2. `./docs/process/linear_link_reference_policy_v1.md`
+3. `./docs/process/linear_issue_template_evidence_contract_v2.md`
+
+A closeout is not complete until the PR-to-Linear mapping, reciprocal links, project scope, status class, and labels have been verified or an explicit tooling blocker has been recorded.
+
 ## Supporting SOP and references
 
 - `./docs/linear_custom_configs_v1.md`

diff --git a/linear/docs/process/linear_issue_template_evidence_contract_v2.md b/linear/docs/process/linear_issue_template_evidence_contract_v2.md
@@ -23,6 +23,14 @@ Every "Done" claim must include:
 5. `Risk / follow-up`
 - Any deferred risk and next action.
 
+6. `PR-to-Linear closeout check` (required when a GitHub PR or Linear normalization is involved)
+- GitHub PR link(s) using `linear_link_reference_policy_v1.md` format.
+- Linear issue link(s) using canonical full-title format.
+- Project scope check: correct project, standalone issue, or explicit blocker if tooling cannot remove a wrong project.
+- Status class check: implementation, docs/design/audit, or future/unstarted.
+- Label check: finalized labels applied only to finalized items; future items do not receive completion labels.
+- Bidirectional linking check: PR comment plus Linear issue comment/link verified, with no duplicate link-spam.
+
 ## Taylor01 Portability Check (required when relevant)
 
 For issues touching agents, workflows, process docs, workspace policy, or tool integrations, also include:
@@ -84,6 +92,14 @@ T01_BYPASS: temporary-coupling
 T01_BYPASS_REASON: issue template is still evolving quickly and immediate generic refactor would slow current migration work
 T01_REVIEW_TRIGGER: revisit when the next reusable adapter template is introduced outside BitPod
 
+PR-to-Linear closeout check:
+- PR: [BitPod-App/repo-name PR #123 — PR Title](https://github.com/BitPod-App/repo-name/pull/123)
+- Linear: [BIT-000 — Full Issue Title](https://linear.app/bitpod-app/issue/BIT-000/issue-slug)
+- Project scope: correct / standalone / blocked by tooling limitation
+- Status class: implementation / docs-design-audit / future-unstarted
+- Labels: domain label + qa/pm result labels verified where finalized
+- Bidirectional links: PR comment verified; Linear attachment/comment verified; no duplicate retroactive comments
+
 Risk / follow-up:
 - `code_security` feature is plan-gated; tracked separately and not blocking this issue.
 ```
@@ -103,3 +119,5 @@ Risk / follow-up:
 - If a relevant issue omits the Taylor01 portability block, status must not be treated as decision-complete unless an explicit temporary-bypass note is present in the same update.
 - If uncertain, set/keep `In Review` and request missing evidence.
 - If a meaningful temporary bypass is used, add or update the active bypass register entry instead of silently relying on memory.
+- If a PR-to-Linear closeout check is required and missing, do not claim the issue/project/PR history is normalized.
+- If project membership cannot be corrected through available tooling, record that as an explicit blocker rather than marking the project cleanup fully complete.
diff --git a/linear/docs/process/linear_link_reference_policy_v1.md b/linear/docs/process/linear_link_reference_policy_v1.md
@@ -3,7 +3,7 @@
 Status: Active
 Owner: Product Development
 Related: BIT-43, BIT-33
-Last updated: 2026-03-09
+Last updated: 2026-04-28
 
 ## Purpose
 
@@ -35,15 +35,40 @@ Fallback:
 
 `[BitPod-App/repo-name PR #123](https://github.com/BitPod-App/repo-name/pull/123)` (title unavailable)
 
+## PR-to-Linear closeout comment formats
+
+Use these formats for merge closeout, retroactive linking, and Linear normalization work.
+
+GitHub PR comment body:
+
+```md
+Retroactively linked Linear issues:
+- [BIT-000 — Full Issue Title](https://linear.app/bitpod-app/issue/BIT-000/issue-slug)
+```
+
+Linear issue comment body:
+
+```md
+Retroactively linked to GitHub PR: [BitPod-App/repo-name PR #123 — PR Title](https://github.com/BitPod-App/repo-name/pull/123).
+```
+
+Rules:
+
+- Use one clean comment per PR and one clean comment per issue for the link-back record.
+- Update an existing retroactive-link comment instead of adding duplicates.
+- Include all mapped Linear issues in the PR comment when a PR closes multiple issues.
+- Attach the GitHub PR link to the Linear issue when tooling supports attachments/links.
+- If the PR title is unavailable, use the canonical PR fallback format rather than a bare URL.
+
 ## Guardrails
 
 - Do not output bare `BIT-000` IDs without a link unless explicitly requested.
 - Do not output bare `#123` PR references without a link unless explicitly requested.
+- Do not leave shorthand-only retroactive linking comments when the issue title and URL are available.
 - If verification certainty is low, mark the reference as inferred/degraded instead of guessing the title.
 
 ## Verification checklist
 
 - Confirm all new references in comments/docs follow canonical or degraded fallback format.
 - Confirm fallback still includes full URL.
 - Confirm policy is linked from the operating guide.
-
diff --git a/linear/docs/process/linear_operating_guide_changelog.md b/linear/docs/process/linear_operating_guide_changelog.md
@@ -30,6 +30,12 @@ Maintenance update — 2026-04-15:
 - make `Stale` the primary inactivity-close status and leave `Obsolete` as legacy/edge-case
 - align Vera-style QA guidance so it does not overclaim independent embodied QA authority
 
+Maintenance update — 2026-04-28:
+- add PR-to-Linear closeout guardrails for merge closeout, retroactive linking, and Linear normalization
+- require a mapping table covering PRs, Linear issues, project scope, status class, labels, and bidirectional links
+- require single clean retroactive-link comments instead of duplicate or shorthand-only comments
+- make project-scope cleanup fail closed when available tooling cannot remove a wrong project assignment
+
 Linked artifacts:
 - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/linear_operating_guide_v3.md`
 - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/linear_admin_change_control_v1.md`

diff --git a/linear/docs/process/linear_operating_guide_v3.md b/linear/docs/process/linear_operating_guide_v3.md
@@ -3,7 +3,7 @@
 Version: v3
 Status: Active
 Owner: Product Development (Codex + Taylor)
-Last updated: 2026-04-15
+Last updated: 2026-04-28
 Primary issue: [BIT-22 — Versioned Linear operating guide for agents (with rollback path)](https://linear.app/bitpod-app/issue/BIT-22/versioned-linear-operating-guide-for-agents-with-rollback-path)
 Supersedes: `linear_operating_guide_v2.md` as the active guide
 
@@ -20,6 +20,13 @@ Maintenance update — 2026-04-15:
 - treat current Vera-style QA as a truthful substitute surface, not proof of embodied independent Vera authority
 - keep GitHub-driven Linear truth, but fail closed when merge, QA, PM, or blocker truth is incomplete
 
+Maintenance update — 2026-04-28:
+
+- add a PR-to-Linear closeout guardrail so recent work cannot drift into ad hoc project/status/linking cleanup
+- require a small mapping table before merge, retroactive cleanup, or broad Linear normalization
+- make bidirectional GitHub PR and Linear issue links part of completion evidence
+- make project-scope classification explicit, especially for shared infrastructure that does not belong in product/model projects
+
 ## Scope
 
 - issue lifecycle handling for migration and operations work
@@ -129,13 +136,27 @@ Maintenance update — 2026-04-15:
 - Merge to `main` may move work from `Accepted` to `Done` only when QA, PM, blocker, and release truth are already satisfied.
 - Otherwise, the engine must leave a correction comment and stop short of closure.
 
+14. PR-to-Linear closeout guardrail
+- Before merge, retroactive linking, or Linear normalization, create a small mapping table with: GitHub PR, Linear issue(s), owning project, status class, required labels, and expected bidirectional links.
+- Status class must be explicit:
+  - PR-backed implementation: `Done` only after merge/evidence is real.
+  - Docs/design/audit: `Accepted` when reviewed/accepted but not an implementation closure.
+  - Future/unstarted work: `Backlog` or `Icebox 🧊`; do not add completion labels.
+- Finalized items should carry only the minimal meaningful labels for that lane, usually the domain label plus `qa-skipped` and `pm-accepted` when QA/PM were explicitly waived/accepted.
+- Project membership must match scope. Shared infrastructure, Project Sources, or process work must not be filed under a product/model project unless that project explicitly owns the infra work.
+- Each GitHub PR should have one clean Linear-link comment. Update the existing comment instead of adding duplicates.
+- Each relevant Linear issue should have the GitHub PR link attached and one clean comment using the canonical reference format from `linear_link_reference_policy_v1.md`.
+- If a required field cannot be changed through available tooling, record the blocker explicitly instead of claiming the closeout is complete.
+- A closeout is incomplete until the mapping table, reciprocal links, project hygiene, status checks, and label checks are all verified.
+
 ## Required issue evidence format
 
 - What was changed
 - Verification command(s) or UI check performed
 - Artifact path(s)
 - Pass/fail outcome
 - Transition reason
+- PR-to-Linear mapping / closeout check when a GitHub PR or Linear normalization is involved
 - Taylor01 Portability Check (when relevant)
 
 ## Active portability fields
@@ -169,6 +190,7 @@ This version corresponds to:
 - evidence-first completion protocol from `v2`
 - Taylor01 portability review gate from `taylor01_portability_review_gate_v1.md`
 - active issue evidence contract from `linear_issue_template_evidence_contract_v2.md`
+- PR-to-Linear closeout guardrail added to `linear_operating_guide_v3.md` on 2026-04-28
 - Linear admin/process change-control from `linear_admin_change_control_v1.md`
 - proposal workflow from `linear_change_proposal_template_v1.md`