Tạo và kiểm card

Một card là một phiên build được giới hạn phạm vi. Đây là vòng lặp bạn sẽ dành phần lớn thời gian sau khi planning xong.

Điều kiện trước

/flow card sẽ từ chối cho đến khi cả sáu gate planning đã pass hoặc có dòng debt mở tương ứng. Nếu bị từ chối, chạy /flow rồi sửa stage mà nó nêu tên.

Tạo card

/flow card

Lệnh này tạo cards/C-NNN.md kế tiếp. Trước khi viết một dòng code, đọc và điền những gì template hỏi:

Section	Để làm gì
## Allowed files	Những path duy nhất mà phiên này được chạm vào. Đây chính là bán kính nổ (blast radius).
implements:	Các id requirement trong PRD (FRn) mà card này nhận (claim).
## Verify	Những lệnh bạn sẽ chạy thật — chứ không phải nguyện vọng.
## Independent test	Bằng chứng cho lát cắt mà người dùng nhìn thấy — hoặc infra / none nếu thật sự không thuộc loại nào.
## Evidence	Để trống cho tới khi xong. Bằng chứng thế giới thật dán vào đây.
risk / risk-reason	Hạng rủi ro — bắt buộc phải có trước mọi lần chạy tự động.

[FILL] còn sót trong ## Independent test sẽ làm check fail — đừng bỏ qua.

Nạp tri thức cũ trước

/flow recall

Debt mở, retro gần nhất, scope card trước, friction của harness, playbook đã promote. Hãy coi output là ngữ cảnh để áp dụng, chứ không phải nhiễu.

Tùy chọn: đánh dấu in flight

/flow card start C-001

Lệnh này ghi nhận card đang làm vào registry portable cards/.inflight để nó hiện trên /flow status. Không bao giờ chạm tới trường status: có gate — và hoàn toàn tùy chọn, sửa tay vẫn được.

Build trong vạch

Ba luật ràng buộc mọi phiên build:

1. Một card mỗi session. Không hai card, và không hai card song song cho đến khi /flow ready nói chúng an toàn.
2. Chỉ chạm ## Allowed files. Drift ra ngoài list đó chính là thứ reviewer tìm.
3. Contract là seam. Build theo đúng cấu trúc mà stage 05 đã khai. Cấu trúc sai thì sửa contract trước, rồi mới sửa code.

Với card UI, mock card phải được duyệt trước mọi code frontend, và /flow design <file> chạy kiểm tra cơ học DESIGN.md trên file đó.

Kiểm card nào chạy song song được

/flow ready

Liệt kê các card todo có thể build, kèm gợi ý an toàn song song dựa trên overlap của allowed files.

Kiểm card

/flow check C-001

Lớp cơ học kiểm tra card trước: status có hợp lệ không, còn [FILL] sót không, đủ section bắt buộc không, và ## Evidence có thật sự được điền không. Chỉ sau khi pass mới tới review ngữ nghĩa — diff so với scope, drift allowed-files, cấu trúc có đúng contract không, DESIGN.md cho UI, và bằng chứng có thật sự là thế giới thật không.

Lỗi bạn sẽ gặp nhiều nhất:

  [x] status is 'done' but ## Evidence is empty (paste world-state proof: URL/curl/DB row)
FAIL: C-001 has gate violations (above).

Lỗi này vẫn xuất hiện ngay cả khi build đã xong và mọi test đều xanh. “Tests pass” và “merged” mới chỉ là trạng thái giữa pipeline.

Dán bằng chứng được tính

Bằng chứng nào được tính tùy thuộc loại dự án:

Loại dự án	Bằng chứng pass
web	URL đã deploy đang chạy, cộng output curl thật
cli	Một lần gọi thật với output và exit code thật
library	Public API import được, ví dụ dùng chạy được, đạt ngưỡng coverage
skill	Đã cài vào skill home, cộng một lần chạy thật đạt done-definition

Artifact quy trình — PR đã duyệt, badge CI xanh, release notes — không phải bằng chứng. Ngưỡng sàn cơ học từ chối prose chỉ nói về quy trình, nên card không thể được đánh dấu xong bằng giấy tờ.

Luật đầy đủ về bằng chứng nào được tính: Done nghĩa là bằng chứng thế giới thật.

Flip sang done

/flow check C-001
PASS: C-001 is valid (status: done).

Hoặc để CLI thực hiện lần flip:

/flow card done C-001

card done áp cùng luật done với check và revert nếu gate fail — nên không bao giờ tạo ra báo xong. Sửa tay status: done rồi chạy check vẫn hợp lệ như nhau.

Converge kế hoạch với code

Build thật luôn drift: code được viết mà plan không hề hỏi, và việc đã plan thì lặng lẽ không bao giờ thành hình. /flow converge là công cụ đóng gap đó. Nó không phải gate next. Opt-in.

Đánh giá code hiện có đối chiếu với plan (PRD FRn, interface trong contract, INV-n của constitution). Viết payload flow-converge/v1 mô tả gap, rồi chạy:

/flow converge

Hoặc flow.sh converge --file <path>.

Ba luật ràng buộc verb này:

1. Chỉ append. Không bao giờ sửa, đánh số lại, hay xóa cards/C-*.md đã có. Không chạm tới application code. Các remainder card được tạo ra; session sau sẽ build chúng.
2. Tất cả hoặc không. Runner chạy transactional: hoặc mọi remainder card đều được viết, hoặc không card nào. Không có chuyện append dở dang.
3. CONVERGED nghĩa là không ghi gì. Zero findings (hoặc không có payload) thì in CONVERGED và để cards/ nguyên.

Việc đã tồn tại trong code nhưng chưa từng được yêu cầu sẽ thành card review (implements: none) — không bao giờ thành lệnh xóa. Quyết định gỡ bỏ cái gì là việc của operator.

Payload chấp nhận các gap type: missing, partial, contradicts, unrequested. Loại nào khác sẽ bị từ chối và không ghi gì.

Viết findings vào .flow/converge-pending.md trước (run-state, đã gitignore — nên một lần chạy CONVERGED không bao giờ chạm tới cards/). Trình bày bảng findings trước khi ghi bất kỳ card nào. Format:

schema: flow-converge/v1
findings: 2

---
gap-type: missing
severity: HIGH
implements: FR2
source-ref: 03-prd.md:FR2
title: implement the mark-task-done endpoint
deps: C-002
allowed: src/app.py
---
gap-type: unrequested
severity: LOW
implements: none
source-ref: src/app.py:debug_dump
title: the debug_dump surface no feature asked for
deps:
allowed: src/app.py

Card được append mang [FILL] ở Verify và Evidence vì chưa build. Tạo card, điền, rồi check như card khác.

Phân loại gap và schema payload đầy đủ nằm ở skills/flow/references/converge.md.

Xem thêm

• Done nghĩa là bằng chứng thế giới thật
• Skip gate bằng debt
• Chạy auto-build