From 74ed95d6f9c60f4319e2cd8ecc54ef50f08c081a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20J=2E=20Arg=C3=BCello?= <12516370+cjarguello@users.noreply.github.com> Date: Tue, 28 Apr 2026 02:16:16 -0600 Subject: [PATCH] Add Linear PR closeout guardrails --- .github/PULL_REQUEST_TEMPLATE.md | 6 ++++ linear/README.md | 12 ++++++++ ...ear_issue_template_evidence_contract_v2.md | 18 ++++++++++++ .../linear_link_reference_policy_v1.md | 29 +++++++++++++++++-- .../linear_operating_guide_changelog.md | 6 ++++ .../docs/process/linear_operating_guide_v3.md | 24 ++++++++++++++- 6 files changed, 92 insertions(+), 3 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 721a474..3176280 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,6 +6,12 @@ + + +- [ ] 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 diff --git a/linear/README.md b/linear/README.md index 76511bb..790ca33 100644 --- 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 index f436070..5363260 100644 --- 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 index 33a826b..e459033 100644 --- 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,10 +35,36 @@ 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 @@ -46,4 +72,3 @@ Fallback: - 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 index 94342c6..295a2a9 100644 --- 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 index 3c5a211..3fece86 100644 --- 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,6 +136,19 @@ 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 @@ -136,6 +156,7 @@ Maintenance update — 2026-04-15: - 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`