品質 workflow 操作與接入

2026-10-05：QA 真 API 試行本機連 dev，唯讀 12 項、寫入／回讀 15 項通過，三輪測資均清理確認。 contracts 已補兩個手動、非阻斷 CI Job；遠端未跑、部署 SHA 未核對。dev 工程整合與 stg 正式 QA 驗收分開。原工程试行證據保留於下文，不將這次本機結果當成 CI／全產品驗收。

共用能力已在 codex/quality-workflow-plan 實作；正式產品品質政策尚未啟用。 2026-10-04 導入方向：先選 1～2 張 IM 小單沿既有流程跟跑，再決定逐項採用。 IM-1421 已完成工程測試交付示範，含 FE／BE 單元測試、QA mock browser、Runner smoke、MR 審查與修正；最終 contracts Pipeline 30306 通過。三張 MR 保持 Draft，未合併或部署，未宣告完整產品驗收。教學、固定版本與各 Pipeline 證據見團隊教學。

現在先做：少量跟跑

沿用既有需求、AC、各端 MR、審查、QA 與發布規則；補上測試、版本與證據連結，不重填兩套文書。每張單開工前確認試行範圍、負責人、額外時間上限及退回方式。新增試行 Job 明確限制分支、手動且非阻斷，保留既有必要 CI；工具卡住超時可停止跟跑，產品 bug 仍按既有缺陷規則處理。新單的 Runner 容量、測試入口與資料隔離依實際範圍確認；既有 smoke 證據可沿用為能力參考，不能推定所有新單的 DB、部署與權限已備妥。報告保留到完成審查及試行回顧，過期時明列限制或重驗。

此階段沿用目前 framework pin 與角色設定，不執行下方完整品質政策 opt-in，也不以啟用 collector／自動通知作為第一張單的前置條件。已有政策啟用的產品不藉此停用既有關卡。 IM QA 測試放在 contract repo 的 qa/，不另增 QA repo 或專職 CI、UI、替補。 2026-10-02 的完整接線責任規劃為 Leo（@ptp_leo）暫代 QA／整合 owner，Dino（@ptp_dino）技術 reviewer；這是職責規劃，不代表正式 QA 角色已啟用，也不取代新單既有審查與發布授權。

日後啟用完整品質 Gate：配置與責任

以下為完整品質政策的接線要求，不是前述非阻斷跟跑的開工清單。待團隊決定採用、必要配置與權限已確認後，先依正常 MR／發布流程升級 framework pin，再由授權者合併 .delivery-contracts 的版本化 opt-in：

yaml

quality:
  enabled: true
  config: governance/quality.json
  reason: "owner 已核對 QA/CI/部署權限，啟用完整品質政策"

共用 schemas 是 schemas/quality-{config,standard,candidate,event}.schema.json； dcx doctor 檢查配置，啟用卻缺資料或 QA inactive 時拒絕。每產品各自配置 contract/BE/FE/QA project ID、repo、owner（須有 ownership/gitlab_ids）、 required_jobs/report_jobs、實際 adapter argv、workspace_env、保存有效期限、可信 runner_ids、各產品保護 merge_ref、collector、部署 probe 和通知 adapter。不得在設定或工作包放 token 值。

QA 可與 contract 共用 project ID／URL，須明列 repositories.qa.suite_path=qa；BE／FE 仍各自獨立，QA 不與產品實作庫共用。獨立 QA repo 可省略 suite_path（預設根目錄）。

兩個不同票號／project ID 的設定範例在 examples/quality-qa-repo/products/；範例 ID 與人名是假設值，需換成真實配置。第二產品只改設定與 adapter。 QA 與技術 reviewer 是審查職責，可由同一位自然人兼任；collector 是 ownership 的 delivery-bot。 owners 是責任對應，所有責任欄位均可兼任。技術 reviewer 不限定 QA 組長；負責核對案例、斷言、測試程式及執行可靠性。 CI 維護責任可由整合 owner 統籌，接線與檢查由 Agent 協助；不需要另外增加專職人員。設計稿由 PM 逐張 Jira 判斷是否需要，不以後台／App 一律決定。需要時 UI 手動畫 Figma， PM 暫代交接窗口，彙整固定版本、畫面／節點、AC 對應與必要狀態給 FE／QA；不需要時記下原因與沿用依據，FE 依 AC 及既有畫面規則補操作／狀態說明。職責兼任不會自動取得契約寫入權限，設計欄位仍由已授權角色維護。替補依團隊實際需要安排，不是目前 schema 的必要欄位或本輪試行的前置條件。

目前工具限制（2026-10-05）： IM 釘選的 v0.6.17 只有產品級 roles_inactive，尚未支援逐張 Jira 的設計稿適用判斷。試行先在原 Jira 記錄「需要／不需要／待確認」及設計連結，不新增未支援的 manifest 欄位，也不直接全面啟用 UI。逐單判斷及 PM 兼任設計交接的角色權限，須另行接線後才能由工具檢查。IM-1421 本輪後台範例不需設計稿，不能據此判定缺交付。

每 Slice 維護 features/<ticket>/quality/standard.json（QA/PM）與 candidate.json（整合 owner）。標準含 AC→case、三種自動層＋manual、固定介面、 QA suite commit、authority_files、script_state 與演練觸發。script_state 可逐層為 designed/writing/ready。QA suite 的標準內容 hash 排除 suite_commit，避免 Git 自引用；suite pin 和完整 standard_version 仍另外核對及綁定核准。

候選可先只有 BE 或 FE。各端 binding／證據分開綁定，不等待另一端完成；整合另要求兩端 merged/retested、deployment ID、digest、環境鎖及設定版本。

Contract 與 QA 共用 repo（IM）

contract 的 features/<ticket>/quality/ 保留標準、候選與證據；qa/ 下放 cases/<ticket>/standard.json、tests/、fixtures/、profiles/、adapter 與鎖檔。 QA suite 的 cases 是 runner 使用的受審標準快照，plan hash 必須與 contract 標準一致；不可各自放寬。 sample-orders 示範獨立 QA repo，sample-messages 示範共用 contract repo。

先提交 qa/ 測試與 cases 快照，取得 commit A；再於後續提交將 features 標準的 suite_commit 固定為 A。suite 內的 plan hash 排除 suite_commit，避免把 commit 寫進自身的循環。
--binding 會帶 suite_path=qa。quality_job.py --suite 仍傳完整 repo 的乾淨 checkout 根目錄；工具核對 commit，再從 qa/ 讀取 profile.plan、以 qa/ 為測試工作目錄及 QUALITY_SUITE_DIR。profile.plan 是相對測試區路徑，例如 cases/IM-XXXX/standard.json。profile 也應取自核准的測試版本。
在 suite commit A 的受保護 ref 手動／API 啟動 QUALITY_ACTION=integration。binding／候選來自另外保留的最新 contract 快照，profile／binding 暫存於 checkout 外，不能依舊 A 的候選判定。BE／FE 仍測各自固定產品 commit。
來源 pipeline 完成後，在最新受保護 contract 分支另開 QUALITY_ACTION=collect，提示同一 project 的來源 pipeline ID。證據 MR 合併後再開 QUALITY_ACTION=notify。禁止 collector 收集自身 pipeline；測試與收集 job 名稱不同。
qa.gitlab-ci.yml 是 job-only include，不覆蓋既有 contract workflow。root workflow 須允許明確的 web/api/trigger 測試及 api collect/notify；保留原契約檢查。push／證據 MR 不啟動整合測試，回寫不串成循環；不要用整個 repo 的 changes 作整合觸發。
寫入 token 只給 quality-collector environment 的收集 job，設 protected／masked 並使用精確 environment scope，不能使用全域 *。整合測試、before_script、依賴安裝均不得收到寫入憑證；受保護 CI 定義與 MR 審查須防止其他 job 自行索取此 environment。正式站台需驗證這項隔離。
qa/ 修改由具名 QA／技術 reviewer 提交並審查；品質權限設定分開合併。collector publisher 只追加該 ticket 的 events.jsonl，拒絕夾帶 qa/、標準或其他檔案。CI 使用 dcx bot check-mr，qa/ 單獨變更即使沒有受影響 Slice 也會核驗作者。

同 repo 共用存取權；目錄區隔不代表測試程式看不到契約或整份 checkout。若需執行隔離，另外限制 runner 的 workspace／憑證。環境變數隔離依 GitLab environment scope；environment.action=prepare 不建立部署。

每次開工／續接

在產品 contract root 執行（替換實際 ticket 與 role）：

./bin/dcx doctor --json
./bin/dcx open <ticket> --role <pm|ui|be|fe|qa> --json
./bin/dcx quality <ticket> --json
./bin/dcx quality <ticket> --binding be > binding.json
./bin/dcx quality <ticket> --layer be --json

open.quality_workflow 給並行狀態、立即待辦、等待 owner、實際 argv／目錄、輸入輸出與交接條件；未提供 workspace 或 adapter 不存在時明列 unavailable。查詢不授予寫入權限。Runner 鎖住 quality_basis，候選/標準/環境換版後重新 open。 --stage 仍只是要求的契約檢查，不能當作已完成的流程。單端 layer Gate 可先合併；總 dcx gate 仍加上原有角色/版本條件、無 blocking Gap、三層可信測試、適用演練、必要 manual 及具名 QA 接受。

標準與故障演練

--review-request request.json 由 QUALITY_GITLAB_TOKEN（或 --token-env 的安全引用）呼叫配置 GitLab 的 /user，只接受 active 且 bot=false 的具名 owner。 request 需 current basis、完整 standard hash、reason；kind 為 standard_review 加 decision=approve/reject，並指定 review_role=qa 或 technical_reviewer。業務與技術審查分別記錄；作者 Agent 不能代替人。同人兼任時 review_role 必填，一次核准只完成所指定的職責。分人審查的既有紀錄可由具名 owner 推定職責；新 request 建議一律明列。看板與查詢以 review_mode 顯示 same_person（同人兼任）或 different_people（分人審查），不把同人自審宣稱為獨立第二人審查。測試審查核准不代替整合完成後的 QA 最終接受。

drill_decision 加 required、scope、相同 reason，兩項審查職責確認相同 proposal； first_standard/important_test_change/high_risk/escaped_defect 觸發時不能任意免做。先正常通過，再隔離演練。drill_review 的 drill 包含 isolation_id、隔離三項、 expected_case、suite_commit、normal/fault/restored 的精確 project/pipeline/job，以及 restoration_evidence。工具下載原始 JUnit/metadata，核對套件、隔離、正常/復原綠、只有指定 business assertion 紅與程式確實復原。環境/編譯 error 不算抓錯。兩項審查職責必須核准同一組三段證據；修改測試後重新核准與演練。

標準 review 另綁定契約、ownership 與政策內容；更換候選不單獨要求重審標準，變更驗收依據則要求重新核准。責任人變更保留歷史紀錄，舊接受標為 stale，現任 QA／reviewer 重新核驗。

CI 與可信回寫

examples/quality-qa-repo/{product,qa,collector}.gitlab-ci.yml 分別是單端、手動固定候選整合與事後收集範本。產品 adapter 提供 prepare/start/ready_url/ self_test/test/measure_artifact/cleanup argv，使用 QUALITY_DATA_DIR/QUALITY_ISOLATION_ID； tools/quality_job.py 控制 timeout/cancel、保存原始 runner 狀態及無條件清理。 QA suite checkout 必須乾淨且為核准 SHA；MR 的 measure_artifact 從實際啟動服務／容器讀 commit/digest，測前後核對，不能照填 binding。測試不可反向生成必要清單。

BE 真 API＋資料副作用；FE 真畫面＋固定契約 mock，SSR/BFF 另設 mock服務。整合使用 real 邊界，probe command 在測前/後核對部署；collector 又核對 GitLab 保護分支的 merge-base（不能只自報 merged=true）、部署紀錄、部署 job 的 quality/deployment.json、配置的 HTTPS live probes。 QA pipeline SHA 是測試程式，BE/FE SHA 是 candidate 產物，兩者分開。

受保護 contract collector 在 source pipeline 完成後執行：

./bin/dcx quality <ticket> --collect-hint hint.json --json
./bin/dcx quality <ticket> --publish --json

hint 只有 layer/project_id/pipeline_id。工具自行讀 allowlist API，核對必要 job、不可跳過/optional、來源 SHA、保留期、原始 JUnit 與 metadata。異常保存 error 診斷，不可沿用刷新前的綠燈。重送去重，較舊 pipeline 不覆蓋同候選新版。證據時效依 GitLab pipeline／job 的實際 finished_at 及 artifact 保存期核對；延後收集不能把舊測試刷新成新證據。 publisher 只允許該 Slice 的 append-only quality/events.jsonl，拒絕需求/標準/人的接受，採 force-with-lease 開受控 MR，不自行合併。正式生效需 contract MR CI 的 authenticated author 差異檢查及受保護主線；本地追加只是可審查的提案。

MR CI 不持 contract 寫入憑證。站台須保護固定 CI 定義、必要 job、QA 庫審核、 collector 分支與標準/政策 owner；fork、Runner executor、artifact保留與合併旁路必須正式接線時核對。正式人類 MR 驗權需要 /users/:id 可讀權限；API無權限拒絕。

品質啟用後，contract 的受保護 bot check-mr 檢查 job 必須提供僅供 Users API 核驗的 QUALITY_IDENTITY_TOKEN（read_api），以 MR 作者 ID 核對 active 自然人；CI_JOB_TOKEN 不保證能讀 Users API。該憑證不可下發產品 job，也不得在可任意修改的 MR CI 中暴露，正式接線須以受保護 CI 定義執行。

合併證據後，另啟新的受保護 main collector API pipeline，設定 QUALITY_ACTION=notify 才發通知（預設 collect）：

./bin/dcx quality <ticket> --notify --json
./bin/dcx quality <ticket> --publish --json

通知 adapter 從 stdin 收 JSON（ticket、候選、scope、evidence、QA next），目的地由產品配置。接收端必須依 idempotency_key 去重；失敗保存 failed可重試，不抹掉測試；證據未提交時不送。CLI/工作包可主動查詢，不能假設 Agent 會收到推播。

QA 人工接受與 Gap

QA 讀最新 quality 結果、操作固定產物並確認 manual。decision request 明確包含 candidate_id、basis、evidence_version、完整 scope、manual_cases、accept/reject、reason：

./bin/dcx quality <ticket> --decision-request decision.json --json

核驗自然人和當前部署後追加；任意 --author、bot、一般 Run accepted、CI 綠都不能代替。request 的版號/範圍不同、資料過期、必要案例/演練/Gap不齊時拒絕接受。程式/套件/標準/必要環境換版或原始證據保存到期會 stale；純證據/通知不改 basis。

實作 bug 用 dcx blocked --role qa --kind implementation_defect --defect-context context.json --blocks <AC...>。context 含 related_ac、violation_required、reproduction、 expected、actual、versions（be/fe/qa）、environment、evidence。修復端提出轉派理由，QA 用既有 reassign；修復端 submit-fix 仍待 QA resolve。解除單筆後仍須另作整體接受。合法改善為 improvement、violation_required=false、 blocks可空；reclassify 追加理由及證據，禁止清掉必要AC阻擋。需求範圍改變先由 PM 更新契約，再由 QA 重驗/解除，保留原缺陷歷史。

本地驗證與正式待辦

python3 -m unittest discover -s tests -p test_quality_workflow.py
python3 examples/quality-workflow/run_demo.py
python3 examples/quality-qa-repo/run_local_fixture.py
python3 tools/check_generated.py

browser fixture 需固定 Playwright/Chromium；QUALITY_PLAYWRIGHT_MODULE 可以指已安裝模組；QUALITY_CHROMIUM_EXECUTABLE 可指定已安裝的明確 Chromium 執行檔。它驗真瀏覽器 mock 下的請求/處理中/防重複/提示、錯請求會紅，以及真實 BE+FE HTTP/SQLite副作用。輸出標記 local-fixture-only，不是正式 CI來源／部署證據。完整必要檢查同 framework CI：Python回歸、Node導覽、dashboard tests/build/offline、 Go tests/build、生成檔同步。實際產品 W1/W2/W4/W6 與 W8 試行須先填妥正式接線資料。