BR = Business Requirements — bản đặc tả yêu cầu đã chốt, nằm ở

br/BR.md

. Skill đặt tên theo artifact trung tâm mà nó sản xuất, không theo động từ. Mọi frame và mọi clause đều truy ngược về file đó, nên "lỗi sản phẩm ⇔ lỗi BR" (GH#15, 2026-07-03) là tiền đề của cả dây chuyền chứ không phải khẩu hiệu.

Hub 1-tên: user mô tả phạm vi (interview / compile / slice / run / status), KHÔNG phải nhớ nhiều lệnh. Nền tảng: council 028 (thin-slice, người-trong-vòng-lặp) + council 031/032 (loop v1 với 6 điều kiện bắt buộc — winner Taleb mean-rank 1.0).

• Purpose: biến tài liệu yêu cầu thô của user thành sản phẩm có kỷ luật qua dây chuyền BR-kỹ → frames → loop có harness, mọi frame và clause truy ngược về

  br/BR.md

  .
• Trigger (when to use):
  • User có tài liệu yêu cầu (thô/không cấu trúc) và muốn biến thành sản phẩm có kỷ luật.
  • User nói: interview / phỏng vấn yêu cầu / soạn BR / slice frame / chạy frame / trạng thái dây chuyền / ralph.
• Non-goals: không ghi vào

  llmwiki/raw/

  ; không viết lại đồ nghề tất định đã build (

  frame-lint.py

  ,

  loop-runner.py

  ,

  build-line-status.py

  …); không tự commit/merge thay người; không sửa UI tay ngoài

  /br run

  ; không hook auto-fire.

• RULE-01 (MUST): Người là cổng cuối — KHÔNG tự commit/merge output frame; dry-run + người duyệt (council 028).
• RULE-02 (MUST): Phanh bất khả xâm phạm — không bao giờ nâng max_iter hay tắt guard "để nó xong". Thừa phanh rẻ hơn thiếu phanh (council 031/032).
• RULE-03 (MUST): Prompt-dặn KHÔNG phải lớp an toàn — scope-jail/test-hash là code tất định (loop-runner guard 5/6), không phải lời dặn trong prompt (council 5/5 ghế).
• RULE-04 (MUST): Lens-fill luôn

  verified: false

  — không trộn với câu trả lời thật; luôn hiện ở bảng "Giả định đang gánh".
• RULE-05 (MUST): Slicer người-trong-vòng-lặp ở đợt đầu — chưa full-auto (lỗi slicer là lỗi tương quan, blast-radius = toàn BR).
• RULE-06 (MUST): File-first, on-demand — mọi artifact là file travel-được; skill gọi tay, KHÔNG hook auto-fire (ADR-004).
• RULE-07 (MUST): HTML sinh ra cho người xem phải giải nghĩa thuật ngữ + in full-path (R16).
• Capabilities: đọc tài liệu thô + codebase; ghi artifact dưới

  br/

  ; chạy tool tất định (lint, loop, monitor) cục bộ; gọi adapter model có tools bó hẹp; tạo issue ở tracker ngoài chỉ sau xác nhận.

• llmwiki/raw/

  trống → clarify: hỏi user bỏ tài liệu vào.

• br-fill.py check-contract

  ĐỎ → compile failed, sửa BR tới khi xanh.

• frame-lint.py check

  đỏ, hoặc working-tree bẩn →

  /br run

  blocked (từ chối chạy).
• Frame

  tier: compensable/irreversible

  chưa có

  --ack-tier

  → blocked (TIER-GATE).
• Điều kiện KILL (vd diff-jail cắn ≥2 lần / test-hash cắn 1 lần) → cancelled cả run, không cứu, không nâng phanh.
• Frame đỏ → nhánh dưới

  status: blocked

  (partial), nhánh không liên quan vẫn chạy.
• Kiểm UI không có FILE ẢNH thật +

  MANIFEST.json

  → coi là failed (chưa từng làm).

1. Đọc TẤT CẢ file trong

   llmwiki/raw/

   (chỉ đọc — luật cấm ghi raw/). Nếu trống → hỏi user bỏ tài liệu vào.
2. Đối chiếu bộ specs chuẩn

   skills/br/assets/spec-template.md

   : bóc thông tin từ raw map vào từng field S1–S10 → ghi

   br/spec-filled.md

   . MỖI field ghi

   status

   (

   filled|missing|conflict|assumed

   ) +

   provenance

   (

   raw:<file>

   ).
3. Gap-diff: field

   missing

   /

   conflict

   → sinh bộ câu hỏi. Mỗi field là MỘT spec rõ (rigor /orca-workflow): câu hỏi nêu field LÀM GÌ + "trả lời thế nào là ĐỦ" (tiêu chí chấp nhận của field), không hỏi mơ hồ. Ghi 2 file (cùng số thứ tự NNN):

   • br/interview/NNN-questions.html

     — xem theo section, có giải nghĩa thuật ngữ + tiêu chí-đủ mỗi field, in full-path (R16), dark-mode. CHỈ hỏi phần thiếu.

   • br/interview/NNN-answers.md

     — block điền theo field-id (vd

     ## S4.2

     … khoảng trống), để user gõ câu trả lời. 3b.

     --proactive

     (T-260714-01, gọi tắt

     /br auto

     ) — user muốn máy điền phần thiếu thay vì hỏi hết: chạy

     python3 fdk/tools/br-fill.py fill --root .

     (tất định, không model). Tool tra registry defaults (

     skills/br/assets/defaults.yaml

     — bảng 26 điều kiện loop + convention github/spec-kit; project override

     br/defaults.yaml

     thắng khi trùng field) và in 2 nhóm:
   • ĐỀ XUẤT MÁY ĐIỀN → dán vào

     NNN-answers.md

     , GIỮ NGUYÊN

     filled_by: <source>:<refs>

     +

     verified: false

     từng mục (kỷ luật lens-fill áp cho mọi tầng máy điền).
   • CÂU HỎI THẬT (field carve-out — auth/quyền, trust boundary, tiền — và field không có default): chọn ≤5 câu theo Impact × Uncertainty (carve-out đã xếp trước, chiếm suất hỏi trước) đưa vào questions.html; phần vượt trần thì lens-fill (bước 5). Carve-out KHÔNG BAO GIỜ nhận giá trị máy — kể cả registry có entry, kể cả lens.
4. STOP — báo user mở HTML xem + điền answers.md.
5. Nếu user bật

   --lens-fill

   (hoặc nói "cho chuyên gia điền mục chưa chắc"): bốc lens bằng

   python3 harness/scripts/council.py roster --case product --json

   , điền các field

   missing

   mà user đánh dấu "không chắc" → mỗi field đóng dấu

   filled_by: lens:<tên>

   +

   verified: false

   . KHÔNG trộn với câu trả lời thật của user.

1. Đọc

   br/spec-filled.md

   +

   br/interview/*-answers.md

   đã điền.
2. Sinh

   br/BR.md

   : mỗi điều khoản có

   clause_id

   (kế thừa field-id, vd

   S4.2

   ) + provenance (

   raw|user|lens:<tên>

   ). Đầu file là bảng "Giả định đang gánh" liệt kê mọi clause

   lens

   /

   assumed

   (fail-fast: nhìn một phát biết đang cược gì).
   • Sản phẩm có UI (S7.5): chốt một clause NFR (vd

     N01 giao-diện

     ) TRỎ tới

     br/DESIGN.md

     , KHÔNG chép luật design vào BR. Đồng thời copy

     skills/br/assets/design-template.md

     →

     br/DESIGN.md

     và điền §1/§2/§4/§6/§7 cho sản phẩm (giữ nguyên §3/§5 kế thừa). BR = phải có theme/design; DESIGN.md = design trông ra sao.
3. Sinh

   br/BR.clauses.json

   :

   {clause_id: {provenance, assumed: bool, fields: ["S4.2", …]}}

   —

   fields

   khai field spec S1–S10 mà clause hiện thực (khoá của checksum hợp đồng); monitor (

   /br status

   ) đọc file này để tô cam clause assumed. Bảng "Giả định đang gánh" nhóm theo nguồn fill (

   default

   /

   spec-kit

   /

   lens

   ) để người duyệt thấy đang cược gì từ đâu.
4. Gate checksum hợp đồng (vá G1 — council c9dc13d):

   python3 fdk/tools/br-fill.py check-contract --root .

   — mọi required field S1–S10 phải có clause đối ứng; ĐỎ là compile FAIL, sửa BR cho tới khi xanh, không có chuyện "compile xong mà hợp đồng thủng".

1. Đọc

   br/BR.md

   . ĐỀ XUẤT danh sách lát cắt: mỗi lát = {clause_ids, scope_code dự kiến (≤3 file), scope_test, acceptance_test, depends_on}. STOP cho user duyệt/sửa/gộp/tách TỪNG lát (người-trong-vòng-lặp — chốt chặn lỗi tương quan slicer). Lô đầu ≤ 3–5 frame.

   • depends_on

     là bắt buộc nghĩ, không bắt buộc có (GH#75, distill Atomic Task Graph): dây chuyền là ĐỒ THỊ chứ không phải danh sách. Frame B khai

     depends_on: [frame-A]

     khi B không thể xanh nếu A chưa xanh (B gọi API/store/schema A dựng). Không dựa ai →

     depends_on: []

     . Khai đúng thì được ba thứ miễn phí ở mode 4: thứ tự chạy tự đúng, frame đỏ tự chặn nhánh dưới, và sửa một frame chỉ phải chạy lại đúng nhánh của nó. Khai bừa (nối cho "có vẻ hợp lý") thì mất song song và tạo chờ giả — chỉ nối khi có phụ thuộc THẬT.
2. Ghi

   br/frames/frame-NNN-<slug>.md

   THEO TEMPLATE

   skills/br/assets/frame-template.md

   (schema v0 + 5 section body bắt buộc: Nghiệp vụ · Input/Output · Spec (FR/SC) · Tiêu chí nghiệm thu · Ngoài phạm vi — viết cho NGƯỜI VỀ SAU đọc-hiểu, frame-lint R7 gác cứng: frame_id phải có slug nghiệp vụ, muc_tieu không được generic, mỗi frame có FR-id/SC-id rõ, section không được rỗng) +

   parent_br_hash = sha256(br/BR.md)

   .
3. Sinh registry

   br/frames/index.md

   (bảng frame_id · clause_ids · scope_code · status · run_log_ref) từ frontmatter các frame.
4. Gác:

   python3 fdk/tools/frame-lint.py check br/frames --root . 

   — xanh hết mới coi là slice xong (gồm R6 exclusive-scope: 2 frame chưa xong không được giẫm cùng file).
   • R6 là HỢP ĐỒNG THUÊ, không phải sổ đỏ: frame đã xong (run-log

     verdict: SUCCESS

     ) nhả quyền giữ file. Nhờ vậy frame mới được nối vào điểm khởi động (

     main.ts

     ,

     state.ts

     ,

     server.ts

     …) mà frame cũ từng giữ — không có lease thì code mới xanh mà không tới tay người dùng (walleye 2026-09-10: 4 frame xanh, người chơi không thấy gì). Hai frame chưa xong cùng giữ một file vẫn ĐỎ — trừ khi

     depends_on

     đã xếp chúng nối tiếp (frame này là tổ tiên của frame kia): khi đó chúng không bao giờ cùng sửa một lúc, và nhiều tính năng lần lượt nối vào cùng một

     main.ts

     được.

     _manifest.json

     trao file cho người thuê sau cùng (hậu duệ).
   • Mỗi tính năng phải có một lát NỐI DÂY tới điểm khởi động, và frame UI phải nghiệm thu bằng test đi qua giao diện thật (e2e/route-shots), không bằng unit test của module đứng riêng.

5. python3 fdk/tools/br-prompts.py sync

   — bổ sung mục prompt cho các frame mới vào sổ

   br/prompts.md

   (user sửa tay được ngay).

• 📒 SỔ PROMPT TỔNG (nguồn ƯU TIÊN #1, user sửa tay không cần model):

  br/prompts.md

  — MỘT file, mỗi frame một mục

  ## <frame_id>

  . Mở ra, tìm frame, sửa/THÊM nội dung thoải mái (placeholder

  {{...}}

  giữ nguyên để máy điền lúc chạy).

  python3 fdk/tools/br-prompts.py sync

  tự thêm mục cho frame mới, KHÔNG BAO GIỜ đè mục đã sửa tay (chạy sau mỗi

  /br slice

  );

  list

  /

  get <frame_id>

  để tra. Thứ tự ưu tiên khi run: sổ prompt > queue inline > prompt_file > template mặc định.
• Template gốc (seed cho sổ):

  skills/br/assets/revise-prompt.md

  . Adapter

  fdk/tools/br-revise.py

  render nguồn thắng cuộc → gọi

  claude -p

  (tools bó hẹp). Xem prompt sẽ gửi:

  br-revise.py run --frame <f> --verify "<cmd>" --print

  .
• File QUEUE (

  br/queue.yaml

  , mẫu

  skills/br/assets/queue.example.yaml

  ): DANH SÁCH frame để chạy tuần tự; mỗi mục hoặc

  prompt_file:

  (trỏ file template) HOẶC

  prompt:

  (ghi text trực tiếp, vẫn hỗ trợ placeholder). Driver

  fdk/tools/br-queue.py run --queue br/queue.yaml

  chạy từng mục, ghi

  status

  back sau MỖI mục → chạy lại queue = bỏ qua

  done

  , chạy tiếp (resume).

  --dry-run

  xem mỗi mục dùng prompt nào;

  list

  xem trạng thái.
• Adapter

  claude -p

  là ranh giới

  verified:false

  (BNAL) — template + queue + render đều tất định + selftest (

  br-revise.py selftest

  ,

  br-queue.py selftest

  ).

1. Điều kiện KILL viết TRƯỚC (via negativa): vd diff-jail cắn ≥2 lần / test-hash cắn 1 lần → vứt cả run, không cứu, không nâng phanh.
2. Loop dừng → in tóm tắt MỘT DÒNG (verdict · số vòng · diffstat · lệnh verify cuối) + chạy

   python3 fdk/tools/medic.py --ci

   . STOP — người đọc diff trong worktree, tự quyết merge/chạy-tiếp/vứt.
3. Điền

   run_log_ref

   +

   outcome

   vào frame + registry. Ghi lesson (kể cả điều KHÔNG xảy ra — phanh nào chưa từng cắn).

/br run

• Code: gọi

  /qc-code

  (Skill tool →

  qc-code

  ) soi diff frame — 4 mục security/performance/naming/logic + sinh test tái hiện

  qc-*

  .
• UI/UX: gọi

  /qc-uiux

  (Skill tool →

  qc-uiux

  ) audit mockup — 4 mục a11y/hierarchy/consistency/antipattern; phần đo được (contrast/tap-target/overlap/misalign/missing-label) chạy qua engine visual-qa headless:

  node skills/visual-qa/assets/route-shots.mjs <base-url-mockup> --audit

• Verdict CẦN SỬA → sửa trước khi chốt frame. Advisory — verdict LLM là ý kiến; số đo engine + test

  qc-*

  mới gác cứng (đã tự chạy ở

  /br run

  và

  verify-before-commit

  bước 3b). Không có frame chỉ định → audit các route mockup hiện có.

1. python3 fdk/tools/build-line-status.py build --root .

   →

   br/line-status.json

   +

   llmwiki/html/line-status.html

   .
2. In tóm tắt 3 dòng (tổng quan trạng thái · frame đáng chú ý nhất · đường dẫn HTML). Trang cho truy ngược lỗi→frame→clause; clause assumed tô cam → quay

   /br interview

   vòng sau nếu lỗi rơi vào assumed.

automazeio/ccpm

gh

1. python3 fdk/tools/br-sync.py sync br/frames --root . --repo <owner/repo> --dry-run

   — LUÔN dry-run trước (không gọi gh, không ghi mapping).
2. Bỏ

   --dry-run

   khi chắc → tạo sub-issue cho frame chưa map, ghi

   br/frames/issue-mapping.json

   . Idempotent.

   --epic

   tạo epic-issue.

   status

   /

   selftest

   có sẵn.
3. Tạo issue là hành động ra-ngoài repo → xác nhận trước khi bỏ

   --dry-run

   .

1. Frame khai

   ui_role: none|screen|panel|widget|form|action

   +

   ui_screen

   (frame-template) + section "## UI hoạt động ra sao".

2. br/ui-layout.yaml

   :

   nav_style

   +

   screens[]

   (id·title·route thật·frames[]). Sửa file này gom màn KHÔNG đụng frame.

3. python3 fdk/tools/br-contract.py build br/frames --layout br/ui-layout.yaml --root .

   →

   br/UI-CONTRACT.md

   +

   .html

   . Bảng frame·làm gì·ui_role·màn·route·clause·acceptance + đếm frame/màn/route + cảnh báo lệch.

   selftest

   có sẵn.

• Positive: user bỏ 3 file yêu cầu vào

  llmwiki/raw/

  , nói "soạn BR" → interview sinh

  br/interview/001-questions.html

  hỏi 7 field thiếu → user điền → compile ra

  br/BR.md

  + check-contract xanh → slice đề xuất 4 lát, user duyệt →

  frame-lint.py check br/frames --root .

  xanh →

  br-run.py run br/frames/frame-001-dang-nhap.md --root .

  → SUCCESS, commit

  frame(frame-001-dang-nhap): …

  , tóm tắt một dòng + medic.
• Boundary/failure:

  /br run

  khi

  git status --porcelain

  không rỗng → từ chối chạy. Frame gửi mail khai

  tier: irreversible

  → TIER-GATE chặn tới khi

  --ack-tier

  . Frame-003 đỏ → frame-004 (

  depends_on: [frame-003]

  ) thành

  status: blocked

  , frame-005 không liên quan vẫn chạy.

hallmark

br/DESIGN.md

var(--…)

• /br compile

  copy

  design-template.md

  →

  br/DESIGN.md

  với bảng token §4 + §4.1 (token khoá) là NGUỒN CHÂN LÝ.
• Frame UI ở

  ## UI hoạt động ra sao

  chỉ dùng token DESIGN.md; thêm giá trị mới = thêm token vào DESIGN.md rồi trỏ, không tự chế tại frame.
• Drift token bị

  /qc-uiux

  (consistency) + engine visual-qa bắt → "stream" chạy bằng gate tất định, không bằng lời dặn. Kết quả: frame-01 và frame-09 trông như MỘT sản phẩm.

/orca-workflow

• Frame: frame-template có section

  ## Spec (FR/SC)

  (frame-lint R7 gác cứng) — mỗi frame khai FR-id (hệ thống PHẢI…) + SC-id (đo NGƯỜI), acceptance_test là bằng chứng của SC, mỗi dòng nghiệm thu truy về một FR. Frame thiếu FR/SC rõ = chưa xong, y như interview thiếu field.
• Interview: mỗi field S1–S10 hỏi ra phải là MỘT spec rõ — câu hỏi nêu field làm gì + tiêu chí "trả lời thế nào là ĐỦ" (không hỏi mơ hồ). Field còn

  missing/assumed

  = spec chưa đủ, hiện ở bảng "Giả định đang gánh" để không trôi.

ui_role≠none

/design-twice

## Thiết kế (design-twice)

• Vì sao: ý đầu tiên là ý dễ nghĩ nhất, không phải ý tốt nhất. Không có phương án để so thì agent chỉ biết vá phương án duy nhất — mỗi vòng vá đẻ một lỗi mới (theme Lume: 5 vòng vá).
• Tín hiệu phải quay lại vòng thiết kế: đang vá lần thứ 2 cho cùng một chỗ, hoặc user chê "xấu/bựa/không ưng" mà không chỉ ra lỗi cụ thể ⇒ hình dạng sai, vá thêm chỉ tốn công.
• Frame UI thiếu mục

  ## Thiết kế (design-twice)

  = chưa xong (R7 content coi là thiếu nội dung).
• Thiết kế xong mới tới

  ## UI hoạt động ra sao

  → code → gate

  /visual-qa

  bên dưới.

/br run

acceptance_test

• Frame

  ui_role≠none

  đặt:

  acceptance_test: "node skills/visual-qa/assets/route-shots.mjs --base <url> --route <route> --assert --user <u> --pass <p> --out <dir>"

  → exit 1 nếu route không 200/rỗng → frame ĐỎ tới khi UI render đúng.

  /br run

  lại sau mỗi sửa = tự re-verify.
• Sau green, agent

  Read

  ảnh (skill

  /visual-qa

  ) →

  FINDINGS.md

  (route·mức·cách sửa) → mỗi finding là một sửa spec+code của frame →

  /br run

  lại. Bắt lỗi theme/brand/empty-state unit-test không thấy; dùng khi extension MCP lỗi localhost.
• Cấm sửa UI tay ngoài

  /br run

  (nợ p28 05/07): sửa tay = mất gate + không re-verify. Mọi sửa UI phải qua frame.

• python3 fdk/tools/br-rail.py status --root .

  → trạng thái + LUÔN nhắc bật/tắt được.

• on

  (gác đủ) ·

  off

  (tắt gate MỀM tới khi bật lại) ·

  skip

  (bỏ gate mềm ĐÚNG 1 lần rồi tự bật lại + cảnh báo).
• AN TOÀN (bất biến): off/skip CHỈ tắt gate mềm — R7 content · visual-qa UI · assumption-gate. PHANH CỨNG (diff-jail · test-hash · scope-clean) + cấu trúc R1–R6 + hook bảo mật KHÔNG BAO GIỜ tắt qua đây.
• Wiring: đầu

  /br run

  , đọc

  br-rail.py consume

  → nếu off/skip thì gọi

  frame-lint … --soft-off

  (bỏ R7+assumption), loop-runner phanh cứng vẫn nguyên; IN trạng thái Rail + dòng nhắc mỗi lần chạy.