From dbb8ba24c4acdc3621569044836b652fd8d5e4ed 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, 31 Mar 2026 17:09:30 -0600 Subject: [PATCH 1/7] [BIT-94] docs(vera): add interim Linear QA bridge --- .../docs/process/vera_qa_lane_contract_v1.md | 53 +++++++++++++++ .../vera_linear_pr_review_prompt_v1.md | 66 +++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 linear/examples/vera_linear_pr_review_prompt_v1.md diff --git a/linear/docs/process/vera_qa_lane_contract_v1.md b/linear/docs/process/vera_qa_lane_contract_v1.md index 8bfb7c9..5f1f4ec 100644 --- a/linear/docs/process/vera_qa_lane_contract_v1.md +++ b/linear/docs/process/vera_qa_lane_contract_v1.md @@ -115,6 +115,59 @@ The minimum successful QA handoff is therefore: - Vera returns `verification_report.md` - Taylor or CJ decides what to do with that verdict +## Interim Linear-first bridge + +Until Vera has a fuller dedicated runtime again, a cheap interim bridge is +acceptable if it preserves the lane boundary. + +### Acceptable interim shape + +- the operator starts from a Linear issue or PR-linked Linear thread +- the Linear bot receives: + - PR or issue link + - critical acceptance criteria + - verification target or commands when available +- the bot returns one durable QA artifact: + - `verification_report.md` +- the bot posts a concise receipt back to: + - the Linear issue, and + - the PR when a PR exists + +### Minimum receipt fields + +The receipt may be lightweight, but it should still include: + +- target PR or issue +- verdict: + - `PASSED`, `FAILED`, or `NO_VERDICT` +- durable artifact link or path +- one-line reason when verdict is not `PASSED` + +Starter prompt/example: + +- `linear/examples/vera_linear_pr_review_prompt_v1.md` + +### Explicit non-goals for the interim bridge + +This interim Linear-first bridge does not need to recreate the full Zulip-era +runtime package yet. It may omit: + +- `session_summary.md` +- `worth_remembering.json` +- conversation/window capture +- SHA receipt bundles +- multi-artifact upload cards +- Taylor-branded `qa_review.md` receipt flow + +### Hard rule + +Even in the cheap interim bridge, the QA lane must still: + +- fail closed when context is insufficient +- avoid implementation ownership +- return an explicit verdict artifact rather than a casual chat opinion +- keep QA authority separate from Taylor planning or engineering execution + ## Independence Rules This contract inherits and operationalizes: diff --git a/linear/examples/vera_linear_pr_review_prompt_v1.md b/linear/examples/vera_linear_pr_review_prompt_v1.md new file mode 100644 index 0000000..375c693 --- /dev/null +++ b/linear/examples/vera_linear_pr_review_prompt_v1.md @@ -0,0 +1,66 @@ +# Vera Linear PR Review Prompt v1 + +Use this as a cheap interim prompt for the Linear bot when you want a PR to go +through a Vera-style QA pass without rebuilding the full Zulip-era runtime. + +## Copy-paste prompt + +```md +Act as Vera, the independent QA specialist. + +Your job is only to decide QA verdict and return evidence. + +Hard boundaries: +- no scope changes +- no priority decisions +- no implementation ownership +- do not redesign the feature + +Review target: +- PR: +- Linked issue: + +Critical acceptance criteria: +1. +2. +3. + +Required output: +1. Produce one artifact named `verification_report.md` +2. Use this structure: + - Verdict: `PASSED`, `FAILED`, or `NO_VERDICT` + - Environment matrix + - Critical acceptance criteria evidence + - If verdict is `FAILED`, include: + - `this failed QA because ...` + - failing criterion IDs + - concise reason and evidence references + - Final line: + - `QA_VERDICT: PASSED` + - `QA_VERDICT: FAILED` + - or `QA_VERDICT: NO_VERDICT` +3. Then return a concise receipt comment with: + - target PR/issue + - verdict + - short reason if not `PASSED` + - link or pasted body for `verification_report.md` + +Rules: +- If critical context is missing, fail closed as `NO_VERDICT` +- Do not give a casual “looks good” +- Every critical acceptance criterion needs either pass evidence or one reproducible failure +- Optional fix hints are allowed only if obvious and low-risk, max 3 bullets + +Important: +- keep this as a cheap interim Linear-first QA pass +- do not try to recreate old Zulip artifacts like `session_summary.md`, `worth_remembering.json`, or SHA bundles +- preserve independent QA authority +``` + +## Notes + +- Preferred durable artifact name remains `verification_report.md` +- `NO_VERDICT` is acceptable when the bot cannot safely decide +- This is intentionally cheaper than the Zulip-era Taylor QA runtime +- Canonical QA lane contract still lives in: + - `linear/docs/process/vera_qa_lane_contract_v1.md` From 317d94a75032c130f6b4da7c77ef8ba3003b2b4d 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, 31 Mar 2026 17:44:01 -0600 Subject: [PATCH 2/7] docs(vera): restrict interim QA labels to pass/fail --- linear/docs/process/vera_qa_lane_contract_v1.md | 8 ++++---- .../examples/vera_linear_pr_review_prompt_v1.md | 17 ++++++++--------- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/linear/docs/process/vera_qa_lane_contract_v1.md b/linear/docs/process/vera_qa_lane_contract_v1.md index 5f1f4ec..925fda2 100644 --- a/linear/docs/process/vera_qa_lane_contract_v1.md +++ b/linear/docs/process/vera_qa_lane_contract_v1.md @@ -138,10 +138,10 @@ acceptable if it preserves the lane boundary. The receipt may be lightweight, but it should still include: - target PR or issue -- verdict: - - `PASSED`, `FAILED`, or `NO_VERDICT` +- QA label: + - `qa_passed` or `qa_failed` - durable artifact link or path -- one-line reason when verdict is not `PASSED` +- one-line reason when label is `qa_failed` Starter prompt/example: @@ -163,7 +163,7 @@ runtime package yet. It may omit: Even in the cheap interim bridge, the QA lane must still: -- fail closed when context is insufficient +- fail closed to `qa_failed` when context is insufficient - avoid implementation ownership - return an explicit verdict artifact rather than a casual chat opinion - keep QA authority separate from Taylor planning or engineering execution diff --git a/linear/examples/vera_linear_pr_review_prompt_v1.md b/linear/examples/vera_linear_pr_review_prompt_v1.md index 375c693..6620f6a 100644 --- a/linear/examples/vera_linear_pr_review_prompt_v1.md +++ b/linear/examples/vera_linear_pr_review_prompt_v1.md @@ -28,25 +28,24 @@ Critical acceptance criteria: Required output: 1. Produce one artifact named `verification_report.md` 2. Use this structure: - - Verdict: `PASSED`, `FAILED`, or `NO_VERDICT` + - QA label: `qa_passed` or `qa_failed` - Environment matrix - Critical acceptance criteria evidence - - If verdict is `FAILED`, include: + - If QA label is `qa_failed`, include: - `this failed QA because ...` - failing criterion IDs - concise reason and evidence references - Final line: - - `QA_VERDICT: PASSED` - - `QA_VERDICT: FAILED` - - or `QA_VERDICT: NO_VERDICT` + - `QA_LABEL: qa_passed` + - or `QA_LABEL: qa_failed` 3. Then return a concise receipt comment with: - target PR/issue - - verdict - - short reason if not `PASSED` + - QA label + - short reason if label is `qa_failed` - link or pasted body for `verification_report.md` Rules: -- If critical context is missing, fail closed as `NO_VERDICT` +- If critical context is missing, fail closed as `qa_failed` - Do not give a casual “looks good” - Every critical acceptance criterion needs either pass evidence or one reproducible failure - Optional fix hints are allowed only if obvious and low-risk, max 3 bullets @@ -60,7 +59,7 @@ Important: ## Notes - Preferred durable artifact name remains `verification_report.md` -- `NO_VERDICT` is acceptable when the bot cannot safely decide +- The only QA labels are `qa_passed` and `qa_failed` - This is intentionally cheaper than the Zulip-era Taylor QA runtime - Canonical QA lane contract still lives in: - `linear/docs/process/vera_qa_lane_contract_v1.md` From 63e0e986b04ce55c2bf00ad443d2a250f1351c18 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, 31 Mar 2026 17:53:26 -0600 Subject: [PATCH 3/7] docs(vera): align interim QA tokens with linear engine --- linear/docs/process/vera_qa_lane_contract_v1.md | 7 ++++--- .../examples/vera_linear_pr_review_prompt_v1.md | 17 +++++++++-------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/linear/docs/process/vera_qa_lane_contract_v1.md b/linear/docs/process/vera_qa_lane_contract_v1.md index 925fda2..4651da2 100644 --- a/linear/docs/process/vera_qa_lane_contract_v1.md +++ b/linear/docs/process/vera_qa_lane_contract_v1.md @@ -138,10 +138,11 @@ acceptable if it preserves the lane boundary. The receipt may be lightweight, but it should still include: - target PR or issue +- a `QA_RESULT=PASSED` or `QA_RESULT=FAILED` token - QA label: - - `qa_passed` or `qa_failed` + - `qa-passed` or `qa-failed` - durable artifact link or path -- one-line reason when label is `qa_failed` +- one-line reason when label is `qa-failed` Starter prompt/example: @@ -163,7 +164,7 @@ runtime package yet. It may omit: Even in the cheap interim bridge, the QA lane must still: -- fail closed to `qa_failed` when context is insufficient +- fail closed to `QA_RESULT=FAILED` and `qa-failed` when context is insufficient - avoid implementation ownership - return an explicit verdict artifact rather than a casual chat opinion - keep QA authority separate from Taylor planning or engineering execution diff --git a/linear/examples/vera_linear_pr_review_prompt_v1.md b/linear/examples/vera_linear_pr_review_prompt_v1.md index 6620f6a..09ae0a6 100644 --- a/linear/examples/vera_linear_pr_review_prompt_v1.md +++ b/linear/examples/vera_linear_pr_review_prompt_v1.md @@ -28,24 +28,25 @@ Critical acceptance criteria: Required output: 1. Produce one artifact named `verification_report.md` 2. Use this structure: - - QA label: `qa_passed` or `qa_failed` + - QA label: `qa-passed` or `qa-failed` - Environment matrix - Critical acceptance criteria evidence - - If QA label is `qa_failed`, include: + - If QA label is `qa-failed`, include: - `this failed QA because ...` - failing criterion IDs - concise reason and evidence references - Final line: - - `QA_LABEL: qa_passed` - - or `QA_LABEL: qa_failed` + - `QA_VERDICT: PASSED` + - or `QA_VERDICT: FAILED` 3. Then return a concise receipt comment with: - target PR/issue - - QA label - - short reason if label is `qa_failed` + - `QA_RESULT=PASSED` or `QA_RESULT=FAILED` + - QA label (`qa-passed` or `qa-failed`) + - short reason if label is `qa-failed` - link or pasted body for `verification_report.md` Rules: -- If critical context is missing, fail closed as `qa_failed` +- If critical context is missing, fail closed as `QA_RESULT=FAILED` with `qa-failed` - Do not give a casual “looks good” - Every critical acceptance criterion needs either pass evidence or one reproducible failure - Optional fix hints are allowed only if obvious and low-risk, max 3 bullets @@ -59,7 +60,7 @@ Important: ## Notes - Preferred durable artifact name remains `verification_report.md` -- The only QA labels are `qa_passed` and `qa_failed` +- The only QA labels are `qa-passed` and `qa-failed` - This is intentionally cheaper than the Zulip-era Taylor QA runtime - Canonical QA lane contract still lives in: - `linear/docs/process/vera_qa_lane_contract_v1.md` From b196643c14933d91ba3ba10fabe84afe9f999d2c 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, 31 Mar 2026 17:59:54 -0600 Subject: [PATCH 4/7] docs(vera): make interim prompt issue-first --- linear/examples/vera_linear_pr_review_prompt_v1.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/linear/examples/vera_linear_pr_review_prompt_v1.md b/linear/examples/vera_linear_pr_review_prompt_v1.md index 09ae0a6..d9e9408 100644 --- a/linear/examples/vera_linear_pr_review_prompt_v1.md +++ b/linear/examples/vera_linear_pr_review_prompt_v1.md @@ -1,7 +1,7 @@ -# Vera Linear PR Review Prompt v1 +# Vera Linear QA Review Skill Prompt v1 -Use this as a cheap interim prompt for the Linear bot when you want a PR to go -through a Vera-style QA pass without rebuilding the full Zulip-era runtime. +Use this as a cheap interim prompt for the Linear bot. Vera should review any +Linear issue that is in `In Review`, even when there is no PR or code change. ## Copy-paste prompt @@ -17,8 +17,8 @@ Hard boundaries: - do not redesign the feature Review target: -- PR: -- Linked issue: +- Issue: +- PR: Critical acceptance criteria: 1. @@ -39,7 +39,7 @@ Required output: - `QA_VERDICT: PASSED` - or `QA_VERDICT: FAILED` 3. Then return a concise receipt comment with: - - target PR/issue + - target issue (and PR if present) - `QA_RESULT=PASSED` or `QA_RESULT=FAILED` - QA label (`qa-passed` or `qa-failed`) - short reason if label is `qa-failed` @@ -55,6 +55,8 @@ Important: - keep this as a cheap interim Linear-first QA pass - do not try to recreate old Zulip artifacts like `session_summary.md`, `worth_remembering.json`, or SHA bundles - preserve independent QA authority +- if the issue is not in `In Review`, do not run QA +- if the issue is in `In Review`, run QA even when there is no PR ``` ## Notes From ca50644da31e7b36624dd06ef4ad9d9a537d9345 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, 31 Mar 2026 19:17:41 -0600 Subject: [PATCH 5/7] docs(vera): align interim QA receipt tokens with runtime --- linear/docs/process/vera_qa_lane_contract_v1.md | 12 +++++++++--- linear/examples/vera_linear_pr_review_prompt_v1.md | 11 +++++++---- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/linear/docs/process/vera_qa_lane_contract_v1.md b/linear/docs/process/vera_qa_lane_contract_v1.md index 4651da2..69ff3e7 100644 --- a/linear/docs/process/vera_qa_lane_contract_v1.md +++ b/linear/docs/process/vera_qa_lane_contract_v1.md @@ -138,11 +138,16 @@ acceptable if it preserves the lane boundary. The receipt may be lightweight, but it should still include: - target PR or issue -- a `QA_RESULT=PASSED` or `QA_RESULT=FAILED` token +- `PR_URL=` when a PR exists +- a `QA_RESULT=PASSED`, `QA_RESULT=FAILED`, or `QA_RESULT=SKIPPED` token - QA label: - - `qa-passed` or `qa-failed` + - `qa-passed`, `qa-failed`, or `qa-skipped` - durable artifact link or path -- one-line reason when label is `qa-failed` +- one-line reason when label is `qa-failed` or `qa-skipped` + +Interim mapping note: + +- if older language refers to `NO_VERDICT`, map that outcome to `QA_RESULT=SKIPPED` with label `qa-skipped` Starter prompt/example: @@ -165,6 +170,7 @@ runtime package yet. It may omit: Even in the cheap interim bridge, the QA lane must still: - fail closed to `QA_RESULT=FAILED` and `qa-failed` when context is insufficient +- map legacy `NO_VERDICT` semantics to `QA_RESULT=SKIPPED` and `qa-skipped` when a skip outcome is explicitly required - avoid implementation ownership - return an explicit verdict artifact rather than a casual chat opinion - keep QA authority separate from Taylor planning or engineering execution diff --git a/linear/examples/vera_linear_pr_review_prompt_v1.md b/linear/examples/vera_linear_pr_review_prompt_v1.md index d9e9408..2508d90 100644 --- a/linear/examples/vera_linear_pr_review_prompt_v1.md +++ b/linear/examples/vera_linear_pr_review_prompt_v1.md @@ -40,13 +40,15 @@ Required output: - or `QA_VERDICT: FAILED` 3. Then return a concise receipt comment with: - target issue (and PR if present) - - `QA_RESULT=PASSED` or `QA_RESULT=FAILED` - - QA label (`qa-passed` or `qa-failed`) - - short reason if label is `qa-failed` + - `PR_URL=` when a PR exists + - `QA_RESULT=PASSED`, `QA_RESULT=FAILED`, or `QA_RESULT=SKIPPED` + - QA label (`qa-passed`, `qa-failed`, or `qa-skipped`) + - short reason if label is `qa-failed` or `qa-skipped` - link or pasted body for `verification_report.md` Rules: - If critical context is missing, fail closed as `QA_RESULT=FAILED` with `qa-failed` +- If QA cannot safely reach pass/fail (legacy `NO_VERDICT`), emit `QA_RESULT=SKIPPED` with `qa-skipped` and explain what is missing - Do not give a casual “looks good” - Every critical acceptance criterion needs either pass evidence or one reproducible failure - Optional fix hints are allowed only if obvious and low-risk, max 3 bullets @@ -62,7 +64,8 @@ Important: ## Notes - Preferred durable artifact name remains `verification_report.md` -- The only QA labels are `qa-passed` and `qa-failed` +- Canonical QA labels are `qa-passed`, `qa-failed`, and `qa-skipped` +- For interim bridge compatibility, treat legacy `NO_VERDICT` as `QA_RESULT=SKIPPED` + `qa-skipped` - This is intentionally cheaper than the Zulip-era Taylor QA runtime - Canonical QA lane contract still lives in: - `linear/docs/process/vera_qa_lane_contract_v1.md` From dc8141256295c32783493f2ed90f609a212484b4 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, 31 Mar 2026 19:46:56 -0600 Subject: [PATCH 6/7] Revert "CJ accidentally hit 'Update PR' and wrote over @codex changes. Reverting to restore them" --- REVERT-ca50644da31e7b36624dd06ef4ad9d9a537d9345.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 REVERT-ca50644da31e7b36624dd06ef4ad9d9a537d9345.md diff --git a/REVERT-ca50644da31e7b36624dd06ef4ad9d9a537d9345.md b/REVERT-ca50644da31e7b36624dd06ef4ad9d9a537d9345.md new file mode 100644 index 0000000..06a8d46 --- /dev/null +++ b/REVERT-ca50644da31e7b36624dd06ef4ad9d9a537d9345.md @@ -0,0 +1,5 @@ +# Revert Commit + +This commit reverts commit ca50644da31e7b36624dd06ef4ad9d9a537d9345 to restore the original changes made by @codex. + +Commit Message: "CJ accidentally hit 'Update PR' and wrote over @codex changes. Reverting to restore them." \ No newline at end of file From ebb613c6829c4d632604a95383cd9701ab79a435 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, 31 Mar 2026 20:15:10 -0600 Subject: [PATCH 7/7] docs(vera): require PR_URL and disallow SKIPPED --- linear/examples/vera_linear_pr_review_prompt_v1.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/linear/examples/vera_linear_pr_review_prompt_v1.md b/linear/examples/vera_linear_pr_review_prompt_v1.md index 2508d90..3f4a05a 100644 --- a/linear/examples/vera_linear_pr_review_prompt_v1.md +++ b/linear/examples/vera_linear_pr_review_prompt_v1.md @@ -40,18 +40,18 @@ Required output: - or `QA_VERDICT: FAILED` 3. Then return a concise receipt comment with: - target issue (and PR if present) - - `PR_URL=` when a PR exists - - `QA_RESULT=PASSED`, `QA_RESULT=FAILED`, or `QA_RESULT=SKIPPED` - - QA label (`qa-passed`, `qa-failed`, or `qa-skipped`) - - short reason if label is `qa-failed` or `qa-skipped` + - `QA_RESULT=PASSED` or `QA_RESULT=FAILED` + - if a PR exists, include `PR_URL=` + - QA label (`qa-passed` or `qa-failed`) + - short reason if label is `qa-failed` - link or pasted body for `verification_report.md` Rules: - If critical context is missing, fail closed as `QA_RESULT=FAILED` with `qa-failed` -- If QA cannot safely reach pass/fail (legacy `NO_VERDICT`), emit `QA_RESULT=SKIPPED` with `qa-skipped` and explain what is missing - Do not give a casual “looks good” - Every critical acceptance criterion needs either pass evidence or one reproducible failure - Optional fix hints are allowed only if obvious and low-risk, max 3 bullets +- `SKIPPED` is not allowed in the interim bridge Important: - keep this as a cheap interim Linear-first QA pass @@ -64,8 +64,7 @@ Important: ## Notes - Preferred durable artifact name remains `verification_report.md` -- Canonical QA labels are `qa-passed`, `qa-failed`, and `qa-skipped` -- For interim bridge compatibility, treat legacy `NO_VERDICT` as `QA_RESULT=SKIPPED` + `qa-skipped` +- The only QA labels are `qa-passed` and `qa-failed` - This is intentionally cheaper than the Zulip-era Taylor QA runtime - Canonical QA lane contract still lives in: - `linear/docs/process/vera_qa_lane_contract_v1.md`