Skill: br — dây chuyền sản xuất Ralph (BR-kỹ → frames → loop có harness)

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).

WHAT

Purpose và context

• 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.

Mental model

llmwiki/raw/ → interview (spec-filled S1–S10 + câu hỏi hỏi-bù) → compile (BR.md có clause_id + "Giả định đang gánh" + BR.clauses.json) → slice (frames có depends_on, frame-lint gác) → run (loop-runner 6 phanh, commit per-frame, sổ trace) → qc / find / status (truy ngược lỗi→frame→clause)

Input và output contract

llmwiki/raw/

br/interview/NNN-answers.md

--proactive

--lens-fill

--ack-tier

--worktree

--dry-run

br/spec-filled.md

br/interview/NNN-{questions.html,answers.md}

status

provenance

br/BR.md

br/BR.clauses.json

br/DESIGN.md

br/frames/*.md

br/frames/index.md

br/prompts.md

frame(<id>)

br/frames/<id>.run.json

.checkpoints.jsonl

br/line-status.{json,html}

llmwiki/html/line-status.html

Rules và capabilities

• 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.

Failure boundaries

• 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).

HOW

Main workflow

llmwiki/raw/

--proactive

--lens-fill

br-fill.py check-contract

frame-lint.py check

br-prompts.py sync

br-run.py run

build-line-status.py build

Đồ nghề tất định (đã build + selftest — KHÔNG viết lại)

skills/br/assets/spec-template.md

skills/br/assets/frame-template.md

skills/br/assets/design-template.md

/high-end-visual-design

br/DESIGN.md

fdk/tools/frame-lint.py

frame-lint.py selftest

harness/scripts/loop-runner.py

loop-runner.py selftest

fdk/tools/build-line-status.py

--check

build-line-status.py selftest

br/

br/spec-filled.md

br/interview/NNN-{questions.html,answers.md}

br/BR.md

br/BR.clauses.json

br/frames/*.md

br/frames/index.md

br/frames/<id>.run.json

br/line-status.{json,html}

Mode 1 —

/br interview

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.

Mode 2 —

/br compile

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".

Mode 3 —

/br slice

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).

Mode 4 —

/br run <frame>

python3 fdk/tools/br-run.py run br/frames/<frame>.md --root .
# xem prompt sẽ gửi mà không chạy: thêm --print-prompt
# chạy cả hàng đợi resumable: python3 fdk/tools/br-queue.py run --queue br/queue.yaml
# sửa 1 frame → chạy lại ĐÚNG nhánh của nó, không cả dây chuyền:
#   python3 fdk/tools/br-queue.py affected <frame_id> --queue br/queue.yaml --reset
#   python3 fdk/tools/br-queue.py run --queue br/queue.yaml
# cần cô lập thư mục thật sự (hiếm): thêm --worktree

• Topo order:

  br-queue

  đọc

  depends_on

  của từng frame và tự sắp thứ tự (không phụ thuộc thì giữ nguyên thứ tự khai — queue cũ chạy y như trước).
• Frame đỏ CHẶN cả nhánh dưới nó (

  status: blocked

  , ghi

  blocked_by

  ): input của nhánh đó đã hỏng, chạy tiếp chỉ tốn lượt model cho một cái chắc chắn fail. Nhánh KHÔNG liên quan vẫn chạy bình thường — một frame hỏng không còn đứng chặn cả dây chuyền.
• Sửa cục bộ (

  affected

  ): sửa một frame → chỉ frame đó + nhánh dưới nó về

  pending

  , mọi frame xanh khác giữ nguyên. Đây là chỗ trả tiền: trước đây một frame hỏng giữa chuỗi buộc chạy lại nhiều hơn mức cần.
• KHÔNG làm subgraph-reuse cache (paper có, ta bỏ có chủ ý):

  status: done

  đã bỏ qua frame xanh rồi; thêm cache theo hash ở quy mô vài chục frame chỉ đẻ bug stale. Giới hạn của chính paper cũng áp ở đây — lợi ích còn nguyên khi đồ thị nhỏ và acceptance_test tất định; graph rất lớn hoặc test/tool trả kết quả bấp bênh thì lịch chạy này mất tác dụng.

  br-run.py

  tự: (0) TIER-GATE — frame khai

  tier: compensable|irreversible

  trong frontmatter (effect không-đảo: gọi API ngoài/gửi mail/ghi DB) bị CHẶN cho tới khi người chạy lại với

  --ack-tier

  (SHEPHERD gate-before-materialize), (1) frame-lint, (2) kiểm working-tree sạch, (3) chạy loop-runner NGAY TRONG cây hiện tại với revise đã trỏ tới

  fdk/tools/br-revise.py

  (render

  skills/br/assets/revise-prompt.md

  →

  claude -p

  tools bó hẹp), (4) frame xanh → commit vào nhánh hiện tại, message gắn frame_id (mốc revert/blame), (5) in tóm tắt 1 dòng, (6) ghi

  run_log_ref

  vào frame, (7) ghi mốc vào SỔ TRACE

  .checkpoints.jsonl

  (checkpoint-trace/SHEPHERD — record trỏ commit sẵn, không double-commit) → xem cả dây chuyền:

  python3 fdk/tools/checkpoint.py list

  ; rollback cả pipeline về frame bất kỳ theo TÊN:

  checkpoint.py rollback <frame_id>

  (giữ lịch sử, cảnh báo effect tier không-đảo sau mốc). Vì sao in-place là mặc định (feedback user 05/07): N frame = N worktree = N folder ma không ai lục; luồng người thường là bật app lên xem, sửa phải hiện ngay trong cây đang chạy app. Kiểm soát không-phạm-scope nằm ở HARNESS (diff-jail revert mỗi vòng + FINAL SCOPE SWEEP + test-hash + scope_clean + R6 exclusive-scope), không nằm ở cô lập thư mục. Không ưng kết quả →

  git revert <commit frame>

  .

1. frame-lint check

   frame đó xanh. Kiểm working-tree SẠCH (

   git status --porcelain

   rỗng) — bẩn thì từ chối.
2. Tạo git worktree riêng từ

   baseline_ref

   của frame (jail filesystem — frame đầu KHÔNG đụng harness/hook/CI).
3. Chạy loop — commit per-frame VÀO WORKTREE BRANCH (không phải main); người vẫn merge tay:

   python3 harness/scripts/loop-runner.py run \
     --verify "<acceptance_test>" --revise "<adapter claude -p>" \
     --state "<scope_code>" --scope "<scope_code>" --protect "<scope_test>" \
     --baseline "<baseline_ref>" --commit-on-success \
     --commit-message "frame(<frame_id>): <muc_tieu> [<clause_ids>]" \
     --max-iter <g> --budget-seconds <g> --no-progress-k <g> --escalate-after <g> \
     --log br/frames/<id>.run.json --cwd <worktree>

   Adapter revise =

   claude -p

   với tools bó hẹp (

   --allowedTools Edit,Write,Read,Grep,Glob

   — KHÔNG Bash tự do, không network), prompt dựng từ

   muc_tieu

   +

   scope_code

   + output verify fail gần nhất. Truy vết frame→code (điều kiện tiên quyết — chắc frame tạo code nào + không phạm scope):
   • Run-log ghi

     changed_files

     = file THẬT frame đã đổi (≠ scope dự định);

     scope_clean

     =true khi mọi file ⊆

     scope_code

     ;

     attempted_out_of_scope

     = file frame ĐỊNH ghi ngoài scope nhưng đã bị revert.
   • FINAL SCOPE SWEEP: mọi lần loop dừng (kể cả PROTECT_VIOLATION), loop-runner revert sạch mọi file ngoài

     scope_code

     → worktree LUÔN scope-clean,

     changed_files

     LUÔN ⊆

     scope_code

     . Kiểm soát hoàn toàn, không chỉ dựa lời dặn prompt.

   • --commit-on-success

     chỉ commit khi verdict=SUCCESS VÀ scope_clean; message gắn

     frame_id

     →

     git blame

     truy đúng frame.

     --baseline

     = commit gốc để tính diff (thường HEAD của worktree lúc bắt đầu).

Prompt & queue (chạy nhiều frame, resume được)

• 📒 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).

Mode 4b —

/br find <file-hoặc-từ-khoá>

— trỏ vào chỗ lỗi, ra frame/prompt phụ trách

python3 fdk/tools/br-find.py "src/auth/login.py"     # theo file
python3 fdk/tools/br-find.py "đăng nhập"              # theo từ khoá / clause

_manifest.json

git blame

frame(<id>)

Mode 4c —

/br qc [frame]

— audit senior QC (LLM 4-mục) trên mockup/frame

/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ó.

Mode 5 —

/br status

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.

Mode 6 —

/br sync

(frame ↔ GitHub sub-issue)

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

   .

Mode 7 —

/br contract

(UI Contract chốt thực hiện, md+html)

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.

Branches

--proactive

/br auto

br-fill.py fill

verified: false

--lens-fill

council.py roster --case product --json

filled_by: lens:<tên>

verified: false

br/DESIGN.md

design-template.md

br/DESIGN.md

ui_role

/design-twice

acceptance_test

route-shots.mjs --assert

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

tier: compensable

irreversible

--ack-tier

--worktree

baseline_ref

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

affected <frame_id> --reset

/br find <file-hoặc-từ-khoá>

br-find.py

/br qc [frame]

/qc-code

/qc-uiux

/br sync

br-sync.py sync --dry-run

--dry-run

/br contract

br-contract.py build

br/UI-CONTRACT.md

.html

/br rail off

skip

frame-lint … --soft-off

Validation và stopping

frame-lint.py check

br-fill.py check-contract

medic.py --ci

frame-lint.py selftest

loop-runner.py selftest

build-line-status.py selftest

br-revise.py selftest

br-queue.py selftest

Examples

• 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.

Reference — Stream UI thống nhất + Spec rõ ràng (distill hallmark + orca-workflow)

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.

Reference — Vòng THIẾT KẾ cho frame UI (skill

/design-twice

) — chạy TRƯỚC khi code

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.

Reference — Vòng tự-kiểm THỊ GIÁC cho frame UI (skill

/visual-qa

)

/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.

Reference — Rail — công tắc harness của dây chuyền (

/br rail on|off|skip

)

• 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.

Reference — Bằng chứng > lời (luật kiểm UI — feedback 2026-07-13)

MANIFEST.json

/visual-qa