Duyệt và approve task

Trang này hướng dẫn duyệt task qua 3 tầng checks, verdict của Reviewer Agent và nút Approve kèm merge vào nhánh chính. Đọc khi bạn đã hiểu máy trạng thái task và cần chốt code agent đúng cách.

Đối tượng: Tech Lead / Reviewer — chốt chặn cuối trước khi code agent vào nhánh chính. Role kỹ thuật: Board admin và actor.type === 'human' (cùng owner là 2 role duy nhất được approve). Điều kiện: hiểu Máy trạng thái task (peer-review → human-gate → approved).

Màn hình — Review View

Review View: hàng đợi duyệt ở cột trái, khung chi tiết bên phải hiện verdict peer-review, git diff và kết quả checks của task đang chọn

Vào Header → Review, tối ưu duyệt liên tục bằng bàn phím (j xuống, k lên, a approve):

ReviewQueue (sidebar): mọi task ở cột review, badge tầng hiện tại (Human Gate / Peer Review / Rework / Conflict / Escalated / Approved), kèm agentType/priority.
ReviewPanel: header itemKey + branchName; nút Rework / Approve; Description + Acceptance Criteria. Chú ý: nhãn nút ghi (R) / (A) nhưng chỉ a là phím tắt thật — R chưa được nối key handler trong ReviewView, dùng chuột hoặc phím a.
3 tab: Automated Verdict (điểm + findings của Reviewer Agent) / Code Changes (DiffViewer) / Quality Checks (lint/test/typecheck).
ReworkModal: nhập ghi chú khi từ chối.

Checks chỉ là dữ liệu tham khảo, không phải cổng chặn

Không state nào của review phụ thuộc kết quả checks. Quyết định dựa trên diff + verdict + acceptance criteria — đừng tin "checks xanh là đủ".

Human Gate nhìn một mạch

Duyệt và approve — 3 tầng

Tầng 1 — Task Checks: đọc kết quả lint/test/typecheck (POST /api/tasks/:id/checks). Đỏ không tự chặn task — bạn quyết có chấp nhận không. Ghi check mới cần đủ 3 trường checkType/name/status (pending/running/passed/failed/skipped):

curl http://<host>/api/tasks/<taskId>/checks
curl -X POST http://<host>/api/tasks/<taskId>/checks \
  -H 'Content-Type: application/json' \
  -d '{"checkType": "test", "name": "unit", "status": "passed"}'

Thiếu trường → 400 đúng tên trường (checkType is required and must be a string, name is required and must be a string, status must be one of pending, running, passed, failed, skipped).

Tầng 2 — Reviewer Agent: persona @reviewer (khác persona viết code) đọc toàn bộ diff, đối chiếu từng acceptance criteria, xuất .board/review-verdict.json:

{
  "score": 95,
  "verdict": "approved",
  "summary": "…",
  "findings": [
    { "file": "src/payment/webhook.ts", "severity": "minor", "message": "…" }
  ]
}

verdict ∈ approved | changes_requested | rejected; severity ∈ critical | major | minor | info. verdict: approved đẩy task sang human-gate, còn lại sang changes-requested. Tra cứu chuỗi verdict: GET /api/tasks/:id/reviews. Mặc định AGENTBOARD_REVIEWER_AGENT=auto chỉ chạy khi có LLM thật (mode live/record + key + model; timeout 120 giây) — không có LLM thì task đi thẳng tới bạn kèm cảnh báo, không kẹt. off tắt hẳn, heuristic/llm ép chế độ.

Tầng 3 — bạn: mở diff + verdict + checks → bấm Approve (a hoặc POST /api/tasks/:id/approve). Hệ thống ghi audit bắt buộc (reviews + Activity, không ngoại lệ) rồi merge theo mergeStrategy của Space:

curl -X POST http://<host>/api/tasks/<taskId>/approve \
  -H 'Content-Type: application/json' \
  -d '{"note": "Đã soi diff, checks xanh, đúng AC"}'

Thành công trả {"success": true, "task": {…}, "mergeStrategy": "merge-local"} với reviewState: approved, columnId: done.

merge-local
create-pr
manual

Chiếm mutex withRepoLock → git merge --no-ff nhánh agent vào baseBranch → task done. Merge kẹt conflict → repo gốc abort sạch, task sang merge-conflict, API trả 409 có cấu trúc ({"error","conflict": true,"reviewState": "merge-conflict"}) và auto-rework chạy đúng 1 lần. Dùng khi repo và server cùng host (mặc định).

Push nhánh lên origin, tạo Pull Request → task done. Repo local không bị chạm. Dùng khi quy trình PR bắt buộc.

Chỉ đánh dấu done. Bạn tự merge. Dùng cho repo đặc biệt cần kiểm soát tay hoàn toàn.

Duyệt nhanh nhiều task: ở Review View dùng j/k di chuyển, a approve liên tục (phím tắt tắt khi con trỏ đang trong input/textarea/select).

Lỗi hay gặp khi approve

Bạn làm	Kết quả	Vì sao
Script hoặc service token approve	`403` ở cả route lẫn cổng phân quyền (2 lớp)	Actor phân giải về `system`, không phải human — không có bypass
`member` / `viewer` approve	`403` thiếu vai trò `admin` của Space	Nhờ owner cấp `admin` nếu bạn là người duyệt
Merge kẹt conflict	`409` + `reviewState: merge-conflict`	Xem Xử lý rework và xung đột merge

Thông điệp gốc và mọi mã lỗi khác: Mã lỗi API.

Muốn pentest chốt này trước go-live: Pentest Human Gate (scope gate:approve cố ý không tồn tại trong scope-registry — không token nào xin được).

Duyệt Wiki draft

Vào Wiki View → Review Queue: xem draft do agent (wikiProposals) hoặc member đề xuất → sửa trong Draft Editor nếu cần → Approve ghi vào Arkon Wiki, hoặc Reject. Duyệt Wiki cũng cần admin + human như approve code. Cả hai đều bắt buộc projectId (thiếu → 400), và draft phải thuộc đúng Department của Space (lệch → 403 Draft does not belong to this Space):

curl -X POST 'http://<host>/api/wiki/drafts/<draftId>/approve?projectId=<spaceId>'
curl -X POST 'http://<host>/api/wiki/drafts/<draftId>/reject?projectId=<spaceId>' \
  -H 'Content-Type: application/json' \
  -d '{"note": "Chưa đủ căn cứ, bổ sung số liệu rồi gửi lại"}'

Thành công trả {"success": true, "approvedId": "<draftId>"} (reject: rejectedId). Arkon từ chối quyền → 502 Failed to approve draft: … — đó là cổng Arkon, liên hệ owner Space / sysadmin.

Duyệt retro draft ở hàng đợi gộp

Khi Epic đủ điều kiện (≥1 hậu duệ, mọi hậu duệ done, chưa từng retro), draft Retrospective: <Tên Epic> do @architect soạn nằm chờ ở Unified Review Queue cùng hàng với code:

Vào Header → Review → lọc Knowledge (hoặc All) để chỉ thấy draft/nhánh Wiki.
Mở draft retro → đối chiếu 4 mục với thực tế: số item + loại, số rework, tổng runtime agent (đếm lại ở Tree View thay vì tin số trong draft).
Đạt → Approve (ghi vào Arkon Wiki); chưa đạt → Reject / sửa rồi duyệt lại.

Human Gate không đổi: retro chỉ là đề xuất chờ người publish — không tự ghi Wiki, không tự chạy agent.

Việc bạn KHÔNG làm / KHÔNG được làm

Việc	Quy định
Approve bằng script CI / service token	403 và không có cách bypass — tự động hoá được thì nó không còn là chốt chặn
Sửa cấu hình Space, thêm/xoá thành viên	cần `owner` — liên hệ owner
Merge tay trong repo gốc khi hệ thống đang merge	cấm — phá mutex `withRepoLock`, gây conflict khó cứu
Xoá owner cuối cùng (khi bạn kiêm owner)	409 — cấp owner cho người khác trước

Không bao giờ chạy git tay trong repo gốc khi agent đang chạy

git checkout / merge / rebase / commit thủ công phá mutex withRepoLock (mutex trong-process, không biết terminal của bạn). Quy tắc bất di bất dịch.

Checklist tự xác minh

Duyệt 1 task end-to-end: verdict + diff + checks → approve → done/approved, code có mặt trên baseBranch (hoặc PR được tạo).
Phân biệt peer-review (AI đang xem) / human-gate (chờ bạn) / changes-requested / merge-conflict / needs-human.
Biết khi nào giao lại cho member (sửa mô tả), owner (đổi mergeStrategy/requireHumanGate), sysadmin (Reviewer Agent tắt vì thiếu LLM key).
Duyệt 1 Wiki draft end-to-end với projectId: approve → approvedId, trang mới có mặt trên Wiki.

Gặp lỗi? Xem Xử lý sự cố.

Đi tiếp: Từ chối, rework & xung đột merge · Pentest Human Gate · Máy trạng thái task

Màn hình — Review View​

Human Gate nhìn một mạch​

Duyệt và approve — 3 tầng​

Lỗi hay gặp khi approve​

Duyệt Wiki draft​

Duyệt retro draft ở hàng đợi gộp​

Việc bạn KHÔNG làm / KHÔNG được làm​

Checklist tự xác minh​