[BIT-94] docs(vera): add interim Linear QA bridge

[cjarguello]

Summary

• add a cheap interim Linear-first bridge to the Vera QA lane contract
• add a copy-paste Linear bot prompt for PR-linked Vera-style QA passes
• keep this intentionally narrower than the Zulip-era runtime package

Why

This gives Linear a low-cost interim QA path that preserves independent QA authority and a durable verification_report.md artifact without trying to rebuild the full Zulip-era orchestration yet.

Notes

• keeps verification_report.md as the preferred durable artifact
• explicitly allows PASSED, FAILED, or NO_VERDICT
• treats richer Zulip-era artifacts as future work, not a prerequisite

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dbb8ba24c4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 317d94a750

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b196643c14

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cjarguello]

@codex can you fix this to the best of your abilities. It's really not that important since it's just a cheap version of Vera, but the code should at least be consistent and make sense, and the feedback should be addressed.

[chatgpt-codex-connector]

Summary

• Updated the interim Vera prompt so receipt comments now include PR_URL=<full PR URL> (when present), runtime-parseable QA_RESULT tokens (PASSED|FAILED|SKIPPED), and canonical hyphenated QA labels (qa-passed|qa-failed|qa-skipped). linear/examples/vera_linear_pr_review_prompt_v1.mdL41-L47
• Added explicit guidance in the prompt to map legacy NO_VERDICT behavior to QA_RESULT=SKIPPED + qa-skipped, while preserving fail-closed behavior for missing context. linear/examples/vera_linear_pr_review_prompt_v1.mdL49-L51 linear/examples/vera_linear_pr_review_prompt_v1.mdL66-L69
• Updated the QA lane contract’s interim bridge section to match the same runtime-compatible receipt fields and label/token conventions, including the NO_VERDICT→SKIPPED mapping note and hard-rule language alignment. linear/docs/process/vera_qa_lane_contract_v1.mdL136-L150 linear/docs/process/vera_qa_lane_contract_v1.mdL170-L176
• Committed the changes on the current branch (6fe0e41) and created a follow-up PR via the make_pr tool as requested.

Testing

• ✅ rg -n "qa_passed|qa_failed|QA_LABEL|NO_VERDICT|QA_RESULT|PR_URL" linear/examples/vera_linear_pr_review_prompt_v1.md linear/docs/process/vera_qa_lane_contract_v1.md linear/src/engine.py linear/src/runtime.py
• ✅ git diff --check
• ✅ git status --short

View task →

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ca50644da3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cjarguello]

@codex even when trying to revert the damage I caused I failed. Can you fix all the issues you pointed out, and then just squash and merge forcefully and I will update the linear prompt based off the new prompt template

[chatgpt-codex-connector]

Summary

• Updated the interim Vera prompt so the required verification_report.md final-line format now explicitly allows QA_VERDICT: SKIPPED, matching the already-supported QA_RESULT=SKIPPED receipt path. linear/examples/vera_linear_pr_review_prompt_v1.mdL38-L46
• Clarified the skip-path rule in the same prompt: when mapping legacy NO_VERDICT to skipped, the report must also end with QA_VERDICT: SKIPPED and explain missing context. linear/examples/vera_linear_pr_review_prompt_v1.mdL50-L53
• Updated the QA lane contract’s required output section to support PASSED|FAILED|SKIPPED consistently, including a skipped-reason section and QA_VERDICT: SKIPPED in the final-line contract. linear/docs/process/vera_qa_lane_contract_v1.mdL81-L93
• Committed these changes on the current branch as 2d6142d, then created a follow-up PR via the make_pr tool (as requested).

Testing

• ✅ rg -n "QA_VERDICT:|verdict:|skipped because|QA_RESULT=SKIPPED|qa-skipped" linear/examples/vera_linear_pr_review_prompt_v1.md linear/docs/process/vera_qa_lane_contract_v1.md && git diff --check && git status --short
• ✅ git commit -m "docs(vera): allow skipped verdict in verification report contract"

View task →

[cjarguello]

Addressed outstanding Codex feedback in : receipt now requires , includes when a PR exists, and explicitly disallows .

[cjarguello]

Addressed outstanding Codex feedback in vera_linear_pr_review_prompt_v1.md: receipt now requires QA_RESULT=PASSED or QA_RESULT=FAILED, includes PR_URL when a PR exists, and explicitly disallows SKIPPED.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ebb613c682

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Allow SKIPPED in the starter QA receipt template

The starter prompt currently forbids SKIPPED, but the newly added interim bridge contract explicitly requires supporting QA_RESULT=SKIPPED/qa-skipped (including mapping legacy NO_VERDICT outcomes) and the runtime parser accepts SKIPPED in linear/src/engine.py (QA_TOKEN_RE). In cases where QA cannot safely issue pass/fail and should emit a skip-style outcome, following this prompt forces a FAILED result instead, which misclassifies the QA state and drives the wrong workflow transition.

Useful? React with 👍 / 👎.