diff --git a/.claude/skills/product-owner/SKILL.md b/.claude/skills/product-owner/SKILL.md index 905176cd..ccd4010e 100644 --- a/.claude/skills/product-owner/SKILL.md +++ b/.claude/skills/product-owner/SKILL.md @@ -54,12 +54,14 @@ like this: `dos-rate-services-services-antigravity-po-checkin.md` for Rate Services), outside the repository (in that PO's own notes or `po-state` folder), never committed, and never writes another PO's or line's file. -- **One promoter.** Only the Claude Code PO runs `promote.mjs` and the - `verify-live.mjs` check after it. The Qwen and Antigravity POs ask the - Claude Code PO (or JOY, if they cannot reach it) when their merged work +- **Authorized promoters.** Normally the Claude Code PO runs `promote.mjs` and + the `verify-live.mjs` check after it; on Claude Code quota failover or JOY's + assignment, the Antigravity PO runs them instead (DOS/Rate#1849). The Qwen PO + (and the Antigravity PO when neither on quota failover nor assigned by JOY) + asks the active promoting PO (or JOY, if it cannot reach it) when merged work needs a promotion. `promote.mjs` refuses to run when the session's claimant - (resolved as `board.mjs` does) is not `claude:` or cannot be resolved: a - guard against mistakes, not access control. + (resolved as `board.mjs` does) is not `claude:` or `antigravity:`, or cannot + be resolved: a guard against mistakes, not access control. - The claim lock (see "Claims") keeps their sub-sessions off each other's issues even when two take the same issue at the same moment. @@ -504,7 +506,9 @@ secrets and credentials (GitHub, Vercel, Supabase, `AI_API_KEY`, The normal `dev` -> `main` promotion is not one of these steps: it stays batched as `AGENTS.md` 0.2 and `Docs/Resources/RELEASE.md` say, needs no -per-release question, and is run by the Claude Code PO only (`node scripts/ops/promote.mjs`, +per-release question, and is run by the Claude Code PO (or the Antigravity PO +on quota failover / JOY's assignment, passing +`--claimant antigravity:`: `node scripts/ops/promote.mjs`, then `node scripts/ops/verify-live.mjs --wait 900`) at the first checkpoint: no ready backlog left, 10 or more PRs waiting on `dev`, the oldest unpromoted change older than 24 hours, or the end of a long working session. diff --git a/AGENTS.md b/AGENTS.md index d06318d5..09dcecf6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ Tài liệu này tổng hợp đầy đủ **User-Level Hard Rules (`~/AGENTS.md - Không bao giờ đưa lệnh terminal, shell snippet hay code bảo JOY tự chạy hoặc tự dán. Agent phải tự chạy tất cả. - Không bao giờ bảo JOY tự review code diff hay bấm nút Merge PR ("chờ mày merge"). Agent phải chạy code review (`superpowers:code-reviewer` / subagent fresh-context review), sửa hết lỗi, đợi CI xanh và **tự động merge PR** (`gh pr merge`). - Chỉ hỏi ý kiến JOY cho: quyết định sản phẩm/kiến trúc, thao tác rủi ro cao (xóa dữ liệu, thay đổi prod, tiêu tiền, sửa khác repo `cross-repo writes`), hoặc bước bắt buộc cần người thật (2FA, CAPTCHA, OAuth device code). - - **PR promote `dev` -> `main` (deploy production) cũng do agent tự merge.** JOY không phải coder, không biết merge và không bấm nút Merge cho bất kỳ PR nào, kể cả PR promote. **Promote theo đợt, không hỏi JOY mỗi lần:** agent cứ làm task liên tục, không kết thúc task bằng câu hỏi "deploy lên production nhé?". Agent tự mở và merge PR promote khi gặp một trong các mốc (khi có PO thì chỉ PO Claude Code promote, xem Mục 6): hết backlog; `dev` dồn từ 10 PR chưa promote trở lên; thay đổi cũ nhất chưa promote đã quá 24 giờ; hoặc agent kết thúc một phiên làm việc dài. Chỉ promote khi CI của `dev` head xanh và không có PR nào đang sửa dở một lỗi đã lên production. Merge bằng merge commit (`gh pr merge --merge`, không squash/rebase), rồi tự kiểm tra bản live theo `Docs/Resources/RELEASE.md`. Không bao giờ viết "chờ JOY merge", "JOY duyệt merge" hay "JOY merge bằng merge commit". Vẫn phải hỏi JOY trước những việc ngoài một lần promote thông thường (migration DOS-Me, sửa dữ liệu production, đổi credential). + - **PR promote `dev` -> `main` (deploy production) cũng do agent tự merge.** JOY không phải coder, không biết merge và không bấm nút Merge cho bất kỳ PR nào, kể cả PR promote. **Promote theo đợt, không hỏi JOY mỗi lần:** agent cứ làm task liên tục, không kết thúc task bằng câu hỏi "deploy lên production nhé?". Agent tự mở và merge PR promote khi gặp một trong các mốc (khi có PO thì chỉ PO Claude Code hoặc PO Antigravity khi failover quota / JOY giao mới promote, xem Mục 6): hết backlog; `dev` dồn từ 10 PR chưa promote trở lên; thay đổi cũ nhất chưa promote đã quá 24 giờ; hoặc agent kết thúc một phiên làm việc dài. Chỉ promote khi CI của `dev` head xanh và không có PR nào đang sửa dở một lỗi đã lên production. Merge bằng merge commit (`gh pr merge --merge`, không squash/rebase), rồi tự kiểm tra bản live theo `Docs/Resources/RELEASE.md`. Không bao giờ viết "chờ JOY merge", "JOY duyệt merge" hay "JOY merge bằng merge commit". Vẫn phải hỏi JOY trước những việc ngoài một lần promote thông thường (migration DOS-Me, sửa dữ liệu production, đổi credential). 3. **Ngôn ngữ & Định dạng Giao tiếp:** - **Trả lời trực tiếp JOY (Private / Direct Chat):** Luôn dùng **Tiếng Việt có dấu đầy đủ 100%** trên bề mặt giao tiếp trực tiếp với JOY (chat, câu hỏi `ask_question`, nhãn lựa chọn). Giữ nguyên thuật ngữ kỹ thuật thông dụng bằng tiếng Anh (`API`, `commit`, `branch`, `PR`, `CI`, `build`, `deploy`, `repo`, `merge`, `push`, `workflow`, `token`, `key`, `env`, `prod`, `staging`). @@ -43,7 +43,7 @@ Tài liệu này tổng hợp đầy đủ **User-Level Hard Rules (`~/AGENTS.md - Ngoại lệ duy nhất: **rollback** về một bản production cũ đã build từ Git (`vercel rollback`), vì không build lại. Sau đó sửa tiếp qua PR hotfix. - **Script vận hành có sẵn trong repo (`scripts/ops/`, dùng thay cho lệnh gõ tay):** - `node scripts/ops/merge-when-green.mjs `: chờ commit head xanh rồi merge, ghim theo SHA head. Xanh nghĩa là mọi check run và mọi commit status (Vercel) đều đạt, và các check mà ruleset bắt buộc đã báo kết quả. PR vào `main` luôn dùng merge commit, PR khác mặc định squash. `--ignore ""` chỉ dùng khi một check không bắt buộc đang hỏng có lý do đã ghi trong PR. - - `node scripts/ops/promote.mjs`: mở hoặc dùng lại PR promote `dev` -> `main`, liệt kê các PR được phát hành, merge bằng merge commit khi CI xanh. Script từ chối chạy khi claimant của session (tính như `board.mjs`) không phải `claude:` (#1675, xem Mục 6). + - `node scripts/ops/promote.mjs [--claimant :]`: mở hoặc dùng lại PR promote `dev` -> `main`, liệt kê các PR được phát hành, merge bằng merge commit khi CI xanh. Script từ chối chạy khi claimant của session (tính như `board.mjs`) không thuộc `claude:` hoặc `antigravity:` (#1675, #1849, xem Mục 6). - `node scripts/ops/verify-live.mjs --wait 900`: kiểm tra rate.vn chạy đúng commit của `main` (`/api/health` trả `commit`), database đọc được và các route chính trả 200. Script đọc lại `main` mỗi vòng chờ. Chỉ khi bản live chậm hơn `main`, nó mới in lệnh `vercel promote --scope metados`; nếu bản live đi trước hoặc lệch nhánh so với `main`, nó dặn không làm gì. Không bao giờ redeploy hay promote một deployment build từ commit khác (`promote` không build lại, và bật lại tự gán domain sau một lần `vercel rollback`). - `node scripts/ops/board.mjs --status in-progress|in-review|ready|backlog|done --agent [--claimant :]`: lấy, giữ hoặc nhả khóa claim `refs/claims/` của session, rồi cập nhật nhãn và Project #9 (xem mục 1). Script từ chối issue đang bị session khác giữ khóa, đang mang nhãn `agent:*` của agent khác hoặc nhãn `po:*` của PO khác; `--take-over` chỉ dùng khi agent đó đã bàn giao hoặc JOY chỉ định, `--adopt` chỉ cho claim cũ (trước khóa) của chính session này. `--force-release --agent PO --reason "..."` gỡ khóa mồ côi (PO). @@ -240,7 +240,7 @@ Quy tắc cho chính các PO: - **Nhiều PO song song trên cùng repo (#1673, #1805):** JOY có thể chạy các PO song song trên cùng repo trong Claude Code (`po:claude`), Qwen Code Desktop (`po:qwen`), và Antigravity (`po:antigravity`). Nhãn `po:claude`, `po:qwen`, và `po:antigravity` cho biết PO nào điều phối issue. Mỗi PO chỉ giao issue mang nhãn của mình hoặc chưa có nhãn `po:*`, và gắn nhãn của mình khi giao (ví dụ `gh issue edit -R DOS/Rate --add-label po:claude`). `board.mjs` tự thêm nhãn line theo claimant khi claim, và từ chối issue mang nhãn `po:*` của PO khác nếu không có `--take-over` (chỉ khi JOY giao). Claimant của công cụ không chạy PO (ví dụ `codex:...`) không được thêm nhãn `po:*` và không bị chặn theo line; agent đó vẫn phải tôn trọng nhãn `po:*` theo quy tắc này. Session con của PO Claude Code dùng claimant `claude:`, của PO Qwen dùng `qwen:`, của PO Antigravity dùng `antigravity:`. - **Trạng thái PO tách riêng:** mỗi PO có file trạng thái và check-in riêng theo công cụ và theo line (`po-state.claude.md`, `po-state.qwen.md`, hoặc file `*-antigravity-po-checkin.md` theo từng line trong `~/.claude/po-state/` cho PO Antigravity: `dos-rate-core-antigravity-po-checkin.md` cho Rate Core, `dos-rate-services-services-antigravity-po-checkin.md` cho Rate Services), đặt **ngoài repo** (trong thư mục ghi chú hoặc `po-state` riêng của chính PO đó), không bao giờ commit, và không bao giờ ghi vào file của PO khác hay line khác. -- **Chỉ một PO promote:** `promote.mjs` (`dev` -> `main`) và `verify-live.mjs` sau đó chỉ do PO Claude Code chạy. PO Qwen hoặc PO Antigravity cần promote thì nhắn PO Claude Code (qua JOY nếu không nhắn trực tiếp được), không tự chạy. `promote.mjs` từ chối chạy khi claimant của session không phải `claude:` hoặc không xác định được (#1675). Đây là rào chắn chống nhầm, không phải phân quyền: claimant có thể truyền tay bằng `--claimant`. +- **Chỉ PO được phép promote:** `promote.mjs` (`dev` -> `main`) và `verify-live.mjs` sau đó do PO Claude Code chạy (hoặc PO Antigravity khi PO Claude hết quota / được JOY giao, truyền `--claimant antigravity:`, #1849). PO Qwen (hoặc PO Antigravity khi chưa failover và chưa được JOY giao) cần promote thì nhắn PO đang giữ quyền promote (qua JOY nếu không nhắn trực tiếp được), không tự chạy. `promote.mjs` từ chối chạy khi claimant của session không phải `claude:` hay `antigravity:`, hoặc không xác định được (#1675, #1849). Đây là rào chắn chống nhầm, không phải phân quyền: claimant có thể truyền qua `--claimant`. Khi một session do PO mở (session con), các quy tắc sau thay đổi so với Mục 0 và Mục 1: @@ -252,5 +252,5 @@ Khi một session do PO mở (session con), các quy tắc sau thay đổi so v - **`merge-when-green.mjs` của chính PO cũng có thể bị từ chối** (bài học 2026-10-27, lý do "Merge Without Review") cho tới khi JOY duyệt đúng PR đó trong chat của PO. Một câu chung như "chủ động lên" không phải là lời duyệt merge. Khi đó, thay cho câu "agent tự merge" của Mục 0.2, PO không thử lại mà **gom mọi PR đã qua cổng chấp nhận nhưng chưa merge được (session con hoặc chính PO bị từ chối) vào MỘT câu hỏi ngắn** gửi JOY ("PR #a, #b, #c: merge?") thay vì hỏi từng PR, rồi tự chạy script cho đúng các PR JOY duyệt. Không bao giờ bảo JOY tự bấm Merge. - **Nhả issue (release) là một lần bàn giao:** session con nhả issue thì comment lý do và chỗ dừng rồi chạy `board.mjs --status ready --agent `; session sau được dùng `--take-over` và dẫn link comment đó. Claim không có bàn giao nhưng trông như bị bỏ rơi (ví dụ sau khi đổi máy) chỉ được lấy lại khi JOY đồng ý (Mục 0.6); khi đó session mới claim với `--take-over` (thay khóa cũ), hoặc nếu chưa có ai nhận thì PO gỡ khóa bằng `--force-release` như Mục 1. - **Done của thay đổi runtime:** issue tự đóng khi PR merge vào `dev`; với thay đổi runtime, PO chuyển sang `done` sau khi promote và `verify-live.mjs` đạt. Thay đổi docs, CI, tooling thì `done` ngay khi merge. -- PR promote `dev` -> `main` vẫn theo đợt như Mục 0.2, do PO Claude Code chạy (xem "Chỉ một PO promote" ở trên), không do session con. +- PR promote `dev` -> `main` vẫn theo đợt như Mục 0.2, do PO Claude Code (hoặc PO Antigravity khi failover quota / JOY giao) chạy (xem "Chỉ PO được phép promote" ở trên), không do session con. - **Rate Services khác Rate Core:** `DOS/Rate-Services` không có nhánh `dev`, không có check `task-claim` và không có `scripts/ops/`; PR vào `main`, và `board.mjs`/`merge-when-green.mjs` chạy từ checkout `DOS/Rate` với `--repo DOS/Rate-Services`. Chi tiết trong skill. diff --git a/docs/product-owner-config.md b/docs/product-owner-config.md index 12ea6e68..e6263449 100644 --- a/docs/product-owner-config.md +++ b/docs/product-owner-config.md @@ -86,8 +86,15 @@ side as "Triage" in that skill says. - test_environment: Vercel builds `dev` as a Preview deployment; check it there before a promotion (`Docs/Resources/RELEASE.md`). Previews have no database env. -- promotion_notes: `Docs/Resources/RELEASE.md`; promotions run - `node scripts/ops/promote.mjs`, then `node scripts/ops/verify-live.mjs`. +- promotion_notes: `Docs/Resources/RELEASE.md`; promotions are batched at + checkpoints without per-release owner approval (`AGENTS.md` 0.2) and need no + `main` -> `dev` back-merge (`promote.mjs` merges `dev` -> `main` with + `--merge`). Run `node scripts/ops/promote.mjs` (Antigravity PO passes + `--claimant antigravity:`), then + `node scripts/ops/verify-live.mjs --wait 900`. `promote.mjs` accepts + `claude:` or `antigravity:` claimants (Claude Code PO normally, or + Antigravity PO on Claude quota failover / JOY assignment; Qwen remains + blocked). ## Checks and review @@ -102,6 +109,7 @@ side as "Triage" in that skill says. says: a fresh-context subagent review of the diff (`AGENTS.md` sections 0.2 and 5), then a Codex review where Codex is available; a PR without one says so +- promotion_reviews: none - agent_model: sonnet (Antigravity: inherit on Orchestrator (Neon), Orchestrator (Carbon), Gemini 4 Neon, or Gemini 4 Carbon) ## Claim lock and parallel POs @@ -112,7 +120,7 @@ side as "Triage" in that skill says. environment other sessions (sub-sessions included) inherit. - pr_issue_keyword: Closes - po_labels: claude: po:claude, qwen: po:qwen, antigravity: po:antigravity -- promotion_po: claude +- promotion_po: claude (or antigravity on Claude quota failover / JOY assignment) ## Sessions diff --git a/scripts/ops/promote.mjs b/scripts/ops/promote.mjs index 7a1c5809..8c750325 100644 --- a/scripts/ops/promote.mjs +++ b/scripts/ops/promote.mjs @@ -8,30 +8,40 @@ // // Then check the release: node scripts/ops/verify-live.mjs --wait 900 // -// Only the Claude Code PO promotes (AGENTS.md section 6): the script refuses -// to run unless the session's claimant, resolved like board.mjs does, is a -// `claude:` one (DOS/Rate#1675). A guard against a Qwen or other session -// promoting by mistake, not access control: a claimant can be passed by hand. +// Only the Claude Code PO (or the Antigravity PO on quota failover / JOY's +// assignment) promotes (AGENTS.md section 6): the script refuses to run unless +// the session's claimant, resolved like board.mjs does, uses a tool prefix in +// PROMOTER_TOOLS (`claude:` or `antigravity:`, DOS/Rate#1675, DOS/Rate#1849). +// A guard against a Qwen or other session promoting by mistake, not access +// control: a claimant can be passed by hand. import { parseArgs } from 'node:util'; import { resolveClaimant } from '../claim-lock.mjs'; import { DEFAULT_REPO, fail, gh, ghJson, isMain } from './lib.mjs'; import { mergeWhenGreen } from './merge-when-green.mjs'; -/** The only tool whose sessions promote dev to main. */ +const ALLOWED_PROMOTER_TOOLS = new Set(['claude', 'antigravity']); + +/** Primary promoter runtime (kept for backward compatibility). */ export const PROMOTER_TOOL = 'claude'; +/** Tools whose PO sessions may promote dev to main (Claude, or Antigravity on quota failover). */ +export const PROMOTER_TOOLS = new Set(ALLOWED_PROMOTER_TOOLS); + /** * The claimant of the session running the promotion, or an error when it - * cannot be resolved or is not a Claude Code session. + * cannot be resolved or its tool prefix is not in PROMOTER_TOOLS. */ export function promoterClaimant({ flag, env = {} } = {}) { + if (flag !== undefined && !String(flag).trim()) { + throw new Error('no claimant: --claimant cannot be empty'); + } const claimant = resolveClaimant({ flag, env }); const tool = claimant.split(':')[0]; - if (tool !== PROMOTER_TOOL) { + if (!ALLOWED_PROMOTER_TOOLS.has(tool)) { throw new Error( - `only the Claude Code PO promotes dev to main (AGENTS.md section 6), ` + - `and this session's claimant is a ${tool}: one; ask the Claude Code PO ` + + `only the Claude Code or Antigravity PO promotes dev to main (AGENTS.md section 6), ` + + `and this session's claimant is a ${tool}: one; ask the Claude Code or Antigravity PO ` + '(through JOY if it cannot be reached) to promote' ); } diff --git a/scripts/ops/promote.test.mjs b/scripts/ops/promote.test.mjs index 57fa7028..1e8cbe37 100644 --- a/scripts/ops/promote.test.mjs +++ b/scripts/ops/promote.test.mjs @@ -3,6 +3,7 @@ import test from 'node:test'; import { PROMOTER_TOOL, + PROMOTER_TOOLS, ownPromotionPr, promoterClaimant, promotionBody, @@ -65,8 +66,9 @@ test('a fork PR from its own dev is never taken as the promotion', () => { assert.equal(ownPromotionPr([]), null); }); -test('only a Claude Code session may promote (DOS/Rate#1675, DOS/Rate#1805)', () => { +test('only Claude Code or Antigravity PO sessions may promote (DOS/Rate#1675, DOS/Rate#1805, DOS/Rate#1849)', () => { assert.equal(PROMOTER_TOOL, 'claude'); + assert.deepEqual([...PROMOTER_TOOLS], ['claude', 'antigravity']); assert.equal( promoterClaimant({ env: { CLAUDE_CODE_HOST_SESSION_ID: 'local_abcd1234' }, @@ -77,31 +79,75 @@ test('only a Claude Code session may promote (DOS/Rate#1675, DOS/Rate#1805)', () promoterClaimant({ flag: 'claude:local_abcd1234', env: {} }), 'claude:local_abcd1234' ); + assert.equal( + promoterClaimant({ + flag: 'antigravity:d0dc3655-856b-4c89-b2bd-3283a4e5e3da', + env: {}, + }), + 'antigravity:d0dc3655-856b-4c89-b2bd-3283a4e5e3da' + ); + assert.equal( + promoterClaimant({ + env: { + RATE_CLAIMANT: 'antigravity:d0dc3655-856b-4c89-b2bd-3283a4e5e3da', + }, + }), + 'antigravity:d0dc3655-856b-4c89-b2bd-3283a4e5e3da' + ); assert.throws( () => promoterClaimant({ flag: 'qwen:abcd1234', env: {} }), - /only the Claude Code PO promotes.*qwen: one/ + /only the Claude Code or Antigravity PO promotes.*qwen: one/ ); assert.throws( () => promoterClaimant({ env: { RATE_CLAIMANT: 'qwen:abcd1234' } }), - /only the Claude Code PO promotes/ + /only the Claude Code or Antigravity PO promotes.*qwen: one/ ); + assert.throws( + () => promoterClaimant({ flag: 'codex:abcd1234', env: {} }), + /only the Claude Code or Antigravity PO promotes.*codex: one/ + ); + assert.throws( + () => promoterClaimant({ flag: 'cursor:abcd1234', env: {} }), + /only the Claude Code or Antigravity PO promotes.*cursor: one/ + ); + assert.throws( + () => promoterClaimant({ flag: 'antigravity:', env: {} }), + /invalid claimant/ + ); + assert.throws( + () => promoterClaimant({ flag: 'CLAUDE:local_abcd1234', env: {} }), + /invalid claimant/ + ); + // Explicit blank --claimant fails closed even if env carries a valid claimant. assert.throws( () => promoterClaimant({ - flag: 'antigravity:d0dc3655-856b-4c89-b2bd-3283a4e5e3da', - env: {}, + flag: '', + env: { CLAUDE_CODE_HOST_SESSION_ID: 'local_abcd1234' }, }), - /only the Claude Code PO promotes.*antigravity: one/ + /no claimant/ ); assert.throws( () => promoterClaimant({ + flag: ' ', env: { RATE_CLAIMANT: 'antigravity:d0dc3655-856b-4c89-b2bd-3283a4e5e3da', }, }), - /only the Claude Code PO promotes.*antigravity: one/ + /no claimant/ ); - // No claimant at all: refused, not assumed to be Claude. + // No claimant at all: refused, not assumed to be an authorized PO. assert.throws(() => promoterClaimant({ env: {} }), /no claimant/); + + // External mutation of exported PROMOTER_TOOLS cannot widen the guard. + PROMOTER_TOOLS.add('qwen'); + try { + assert.throws( + () => promoterClaimant({ flag: 'qwen:abcd1234', env: {} }), + /only the Claude Code or Antigravity PO promotes.*qwen: one/ + ); + } finally { + PROMOTER_TOOLS.delete('qwen'); + } });