02 主流程
單張 Issue
互動版：diagrams/02-main-flow.html（來源 diagrams/src/02-main-flow.workflow.json）
四條泳道：Operator（人）、Claude Code、GitLab、本機（worktree／Docker／hooks）。人只做三件事：確認需求與驗收、回答釐清問題與做產品決策、session 沒有推送權限時才 ! git push；推送預設由 agent 以 push-pinned.sh 自己做，所以它畫在 GitLab 泳道。
| 階段 | 入口 | 結果 |
|---|---|---|
| 需求討論 | 口頭、spec 或 bug 回報；可先用 /grilling、/to-spec 釐清，但它們不是流程的一部分 | 範圍、驗收條件、SQL 影響初步確認 |
| 開單 | node scripts/issue-create.mjs --title … --description-file …，唯一入口 | needs-triage；直接開成 ready-for-* 時 body 必須含 SQL prerequisite： 與 ## 關聯 區塊 |
| 分級 | /issue-queue：四區總覽 → 逐張釐清 | ready-for-agent／ready-for-human／needs-info／wontfix |
| 派工檢查 | batch-dispatch.mjs --prepare（/issue-run 內部呼叫） | 逐張印 READY 或 STOP |
| 認領 | issue-state.mjs --set <n> in-progress --expect ready-for-agent,in-progress | in-progress；此時才建 Issue worktree |
| 實作 | 由 /loop /issue-pilot 從池中挑單、派 /issue-run <n> --worker 執行（試行中；退路是直接 /issue-run <n>，見下方常駐交付），在 Issue worktree 內：tdd → implement → code-review；每步先跑 deliver-phase.mjs 記錄，checkpoint 在 .scratch/deliver-<n>/state.md | 本地 commit |
| 驗證 | 只跑本單 focused 測試：compile → spay4SourceCheck → spay4FastCheck → run-docker-tests.sh；再跑 check-test-guardrail.sh、check-sql-impact.mjs、pinned-sources.mjs、deliver-sync-baseline.mjs；review 用 run-codex-review.mjs，失敗時改用 code-review skill；每道校驗的邊界與手動指令見 08 品質校驗時間軸 | deliver-candidate.mjs 壓成一個候選 commit |
| 合入 | 說「結案 n」：close-issue.mjs 用 merge-into-integration.sh 合入整合分支，再跑 check-before-push.sh | 停在 PUSH_REQUIRED |
| 推送 | agent 執行 bash scripts/push-pinned.sh '<整合分支>' <SHA>，推送已驗收的那個 SHA；session 沒有這個權限時才把 gate 印出的 推送指令 交給 Operator ! … | 整合分支推上 remote；Issue 分支不用先推 |
| 結案 | agent 推完立即重跑同一個 close-issue.mjs（由 Operator 推送時，推完再說一次「結案 n」）：check-issue-closable.mjs →（動到 docs/workflow/ 時自動發布導讀站）→ 留言 → close → label completed → 刪 worktree 與分支 | 已結案 |
幾個刻意的設計：
- gates 失敗回到實作，Standards／Spec 雙軸 review 最多兩輪修正與重審，超過就停下來回報。
PUSH_REQUIRED是停點，不是錯誤：合入與結案之間隔著推送。agent 只被放行以push-pinned.sh推feature/ron/*，它推送的是已通過check-before-push.sh的固定 SHA，其他 session 同時繼續合入也不影響；推完就在同一輪接著結案。- 只改工具或文件（只碰
scripts/、.claude/、docs/、根目錄*.md）的分支不跑 Java 回歸，只跑check-contracts.sh，合入時可插隊。 - 整合分支要進
develop時才開 MR；Issue 層級沒有「審查中」狀態。
變體一：多張 Issue 批次
互動版：diagrams/06-batch.html（來源 diagrams/src/06-batch.workflow.json）
/issue-pilot 組批次、/issue-run <n> <m> …，或父 Issue 交付子單時：
- 開一個批次 worktree
feature-ron-batch-<key>（<key>=i<n>-<m>）。 - 各張在自己的 Issue worktree 內實作，只跑本單測試。
batch-merge.mjs merge/verify把各張候選合進批次分支，並檢查 drift。queue-regression.mjs排隊跑一次統一回歸（回歸與合入視為同一臨界區，FIFO 預約）。merge-into-integration.sh合入整合分支 →check-before-push.sh→ agent 以push-pinned.sh推送合入的 SHA（沒有權限才交 Operator）。- 確認推送已到 remote 後，同一輪用
batch-merge.mjs close逐張結案，不必等人說「結案」。
常駐交付：/loop /issue-pilot（試行中）
ready-for-agent Issue 的交付指令是在主 checkout 執行 /loop /issue-pilot。它是常駐的 coordinator：自己決定下一張做什麼、組批次、派 worker、落地，人只處理沒有規則能決定的事。試行期間仍可直接 /issue-run <n>，那是退路。
每一輪（tick）依序：
- 對帳：
pilot-sources.mjs --check檢查規則檔是否被其他 session 改過，改過就重讀；讀待處理的 gate、其他 session 轉來的請求、進行中的批次 checkpoint。 - 挑單：從
issue-queue.mjs的池挑。可挑的是依賴都已合入的ready-for-agent，以及needs-triage（pilot 自己照/issue-queue的釐清步驟處理；留下產品問題時改設ready-for-human並記成 gate）。needs-info、ready-for-human、wontfix、wayfinder:*、已在處理中或被其他批次認領的都略過。排序：擋住最多未結 Issue（blocksOpen）的先，ready-for-agent先於needs-triage，再依 iid 小者先。 - 派工：開批次 worktree 與
.scratch/batch-<key>/state.md（多一行controller: /issue-pilot），用batch-dispatch.mjs --worker為每張開一個 worker 終端執行/issue-run <n> --worker <checkpoint>，再用batch-watch.mjs在背景監看。 - 落地：worker 只做到候選 commit（最後一行印
DONE <iid> <SHA>或STOP <iid> <原因>），不排回歸、不合入、不推送、不結案。這些都由 coordinator 照上面的批次流程做：合進批次分支、統一回歸、合入整合分支、push-pinned.sh推送、逐張結案。漂移是PRODUCT_VERIFIED時直接重新整合並重跑回歸，不問人。
預設值：最多 3 個 worker 同時進行、每批最多 3 張，同一時間只有一個批次處在「派工到合入」之間（下一批可以在推送前就開始）。同一個 session 落地 2 批或第一次 compaction 後，用 pilot-handoff.mjs 在旁邊開新 session 接手。
人只做三件事：產品決策、共用環境 SQL 的執行與讀回、session 沒有 push-pinned.sh 權限時的推送。其餘由 coordinator 決定，記在主 checkout 的 .scratch/pilot/：
| 檔案 | 內容 |
|---|---|
gates.md | 等人回覆的問題、選項，以及 coordinator 已套用的預設 |
decisions.md | 每個決定的理由、證據與結果 |
status.md | 由 pilot-status.mjs 從 checkpoint 重產的現況，不手寫 |
requests.md | 其他 session 轉來的請求（插單、暫停、停止） |
在別的 session 執行 /issue-pilot <iid>…、/issue-pilot hold 或 /issue-pilot stop，請求會轉交給正在跑的 coordinator，不會多開一個。worker 遇到 SQL 時，coordinator 會開 SQL Issue、把 feature 標成等待並派 SQL worker，做到 ARTIFACT_PREPARED 為止，之後的執行與讀回仍由人處理；交付工具本身壞掉時，它開 feature-ron-fix-<slug> worktree 派修正 worker，修正走免回歸的工具合入路徑。正式規則見 issue-run Pilot。
變體二：SQL Issue
互動版：diagrams/07-sql-issue.html（來源 diagrams/src/07-sql-issue.workflow.json）
- 每張任務在開工、範圍變更、交付前都要做一次 SQL-first 評估；沒有 SQL 時在 feature Issue body 記
SQL prerequisite：無與理由。 - 需要目標 SQL 時走
sql-issue.mjs建 SQL Issue，feature Issue 的## 關聯寫Blocked by: #<sql>。 - agent 不連共用資料庫、不執行目標 SQL；SQL 以檔案交給人執行（貼到終端會被 CRLF 弄壞），人把結果貼回。
verify只跑政策固定的唯讀查詢。 - 本機可拋棄的 Docker MySQL 可以自由試跑。
- SQL Issue 用
close-sql-issue.mjs結案；close-issue.mjs會拒絕它。