fdk-uat

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: fdk-uat

WHAT

Purpose và context

目的与背景

Purpose: nghiệm thu một bản framework sắp phát hành ở tầng "người mới
```
curl
```
về": dựng dự án TRỐNG, cài overstack qua đường remote thật, kiểm năng lực MỚI của chính bản đó tới tay người dùng — qua HAI PHA (canary trước merge, main-URL smoke ngay sau merge); fail thì gỡ khỏi remote.
Trigger (when to use):
Sắp công bố một bản có năng lực mới (skill mới, rule mới, engine mới).
Nghi ngờ "doc hứa mà user không nhận được" (lớp lỗi GH#77).
Sau khi
```
medic --ci
```
đã xanh — UAT là tầng TRÊN nó, không thay thế nó.
- User nói "uat", "test thật", "test downstream", "kiểm tra người mới cài có chạy không", "acceptance",
```
/fdk-uat
```
  ; hoặc
```
/ship
```
  mức release/pr/mr có năng lực mới.
Non-goals: không thay
```
medic --ci
```
(UAT là tầng TRÊN nó), không phải
```
fresh-install-smoke --local
```
(working-tree
```
file://
```
), không live-run model LLM thật (trần cố ý — acceptance làm tay), không sửa lỗi tìm thấy (gỡ + ghi problem-tree).

Bối cảnh — vấn đề nó giải (nguyên văn):

medic --ci

và

fresh-install-smoke --local

cài từ working-tree qua

file://

. Chúng chứng minh "code trong máy tôi lành", không chứng minh "người lạ

curl

về là chạy được". Hai thứ khác nhau: tarball thiếu file,

.gitignore

nuốt mất thứ cần ship, skill hỏng frontmatter bị CLI bỏ qua trong im lặng, engine global không refresh — mọi lỗi này chỉ lộ ra trên đường remote thật.

Đường remote chỉ tồn tại sau khi push — nhưng không nhất thiết là push lên nhánh chính. Một nhánh tạm cũng có raw URL. Nghịch lý con-gà-quả-trứng biến mất, với một điều kiện: phải override cả ba biến nguồn, vì

install.sh

mặc định kéo skill từ nhánh chính.

Và canary vẫn không đủ: nó chạy với ref khác + biến override, nên mù với chính các giá trị mặc định — mà mặc định là chỗ chứa chuỗi tên nhánh hardcode. Nên phải có pha hai: chạy đúng cái lệnh người mới gõ, không override gì cả.

Purpose: 在“新用户通过
```
curl
```
安装”的层级验收即将发布的 framework 版本：创建空白项目，通过真实 remote 路径安装 overstack，验证该版本自身的新能力是否真正到达用户手中——分为两个阶段（merge 前的 canary，以及 merge 后的 main-URL smoke）；失败时从 remote 撤销。
Trigger (when to use):
准备发布具备新能力的版本（新 skill、新 rule、新 engine）。
怀疑“文档承诺了，但用户没有收到”（GH#77 那一类问题）。
```
medic --ci
```
已经通过——UAT 位于其上层，并不替代它。

用户说

uat

、

test thật

、

test downstream

、

kiểm tra người mới cài có chạy không

、

acceptance

、

/fdk-uat

；或

/ship

处于 release/pr/mr 层级且包含新能力。

Non-goals: 不替代
```
medic --ci
```
（UAT 位于其上层）；不是
```
fresh-install-smoke --local
```
（working-tree
```
file://
```
）；不实际运行 LLM model（这是有意设置的上限——acceptance 仍由人工执行）；不修复发现的问题（撤销并记录 problem-tree）。

背景——本流程解决的问题（原文）：

medic --ci

和

fresh-install-smoke --local

都从 working-tree 通过

file://

安装。它们只能证明“我本机上的代码是好的”，不能证明“陌生用户通过

curl

下载后可以运行”。这是两件不同的事：tarball 缺少文件、

.gitignore

吞掉了本应发布的文件、skill 的 frontmatter 损坏后被 CLI 静默忽略、global engine 没有刷新——所有这些错误都只会在真实 remote 路径上暴露。

remote 路径只有推送之后才存在——但不一定非要推送到主分支。临时分支同样有 raw URL。于是出现了“鸡生蛋还是蛋生鸡”的悖论，但它有一个前提条件：必须覆盖全部三个源变量，因为

install.sh

默认从主分支拉取 skill。

而 canary 仍然不够：它使用不同的 ref + 变量覆盖运行，因此对真正的默认值是盲的——而默认值正是硬编码分支名的位置。因此必须有第二阶段：不覆盖任何变量，原样运行新用户会输入的命令。

Mental model

medic --ci xanh → khai checklist năng lực mới (mỗi dòng = một lệnh) → PHA 1: push HEAD:uat/<ts> → dự án trống curl từ raw canary (HARNESS_BASE + REPO_RAW + SKILLS_REF) → UAT checklist + workspace Orca thật (assert) → PHA 2: push nhánh chính → chờ sentinel CDN → đúng lệnh README không override → smoke → PASS chốt | FAIL gỡ (revert/reset --force-with-lease) + problem-tree

. Canary kiểm NỘI DUNG; main-URL smoke kiểm GIÁ TRỊ MẶC ĐỊNH.

medic --ci

通过 → 列出新能力 checklist（每行 = 一条命令）→ 阶段 1：push HEAD:uat/<ts> → 创建空白项目，从 canary raw 执行 curl（HARNESS_BASE + REPO_RAW + SKILLS_REF）→ 执行 UAT checklist + 真实 Orca workspace（assert）→ 阶段 2：push 主分支 → 等待 sentinel CDN → 按 README 原样执行，不覆盖任何变量 → smoke → PASS 则定案 | FAIL 则撤销（revert/reset --force-with-lease）+ problem-tree。Canary 检查内容；main-URL smoke 检查默认值。

Input và output contract

Input 与 output contract

	Field	Required?	Ý nghĩa
In	repo framework, `medic --ci` xanh, git sạch	có	tiền đề bước 0; đỏ thì không push
In	`<owner>/<repo>` + nhánh chính	có	dựng `RAW` + `SKILLS_REF`
In	checklist năng lực mới	có	viết trước khi push; không khai thành lệnh được = không tính
In	duyệt push (canary / nhánh chính)	có	push là side-effect remote
In	`--keep`	không	giữ dự án UAT để soi
Out	`BASE` + danh sách commit sắp đẩy	có	mốc gỡ nếu fail
Out	kết quả UAT từng mục (số đo thật)	có	3 trụ · test-broad PASS · năng lực mới · orchestration-ready · worktree Orca assert · layout dot
Out	verdict	có	PASS → log vào `wiki/log.md` ; FAIL → commit đã gỡ khỏi remote + node `status: open` trong `llmwiki/html/fdk-problem-tree.html`
Out	nhánh canary	—	đã xoá ở CẢ HAI lối ra

	Field	Required?	含义
In	repo framework、 `medic --ci` 通过、git 干净	是	步骤 0 的前提；失败则不得 push
In	`<owner>/<repo>` + 主分支	是	用于构建 `RAW` + `SKILLS_REF`
In	新能力 checklist	是	在 push 前编写；无法具体化为命令的项目不计入
In	push 审批（canary / 主分支）	是	push 会对 remote 产生副作用
In	`--keep`	否	保留 UAT 项目以便检查
Out	`BASE` + 待推送 commit 列表	是	失败时用于撤销的基准
Out	各 UAT 项结果（真实测量值）	是	3 个支柱 · test-broad PASS · 新能力 · orchestration-ready · Orca worktree assert · dot layout
Out	verdict	是	PASS → 记录到 `wiki/log.md` ；FAIL → 从 remote 撤销 commit，并在 `llmwiki/html/fdk-problem-tree.html` 中添加 `status: open` 节点
Out	canary 分支	—	两种退出路径均已删除

Rules và capabilities

Rules 与 capabilities

RULE-01 (MUST): Nhánh chính KHÔNG BAO GIỜ nhận bản chưa qua canary. Pha 1 tồn tại để điều đó đúng.
RULE-02 (MUST): Canary KHÔNG thay được main-URL smoke. Nó chạy với ref khác + biến override → mù với các giá trị mặc định, mà mặc định chính là chỗ hardcode tên nhánh. Bỏ pha 2 là bỏ đúng thứ người dùng thật chạm vào.
RULE-03 (MUST): Không bao giờ push rồi bỏ mặc. Đã push để UAT thì phải chạy UAT trong cùng phiên. Push xong đi ngủ là để lại một bản chưa nghiệm thu cho người khác kéo về.
RULE-04 (MUST): Dọn nhánh canary ở CẢ HAI lối ra (pass và fail). Bước 0 liệt kê
```
git branch -r | grep uat/
```
để dọn rác của phiên chết giữa chừng.
RULE-05 (MUST): CDN propagate không đồng đều — CHỜ SENTINEL, đừng đo ngay sau push.
```
raw.githubusercontent
```
có thể trả file A đã mới còn file B còn cũ trong cùng một lần cài → bản lai, và cổng báo đỏ giả (hoặc xanh giả, nguy hiểm hơn). Poll một chuỗi CHỈ có ở bản mới cho tới khi raw trả đúng, rồi mới đo. Đo được thật ngày 2026-07-14: engine mới + policy cũ → test-broad 72/74, luật mới không cắn; chờ vài phút rồi chạy lại → 74/74.
RULE-06 (MUST): Không đếm skill/rule bằng trí nhớ — đếm LIVE trong dự án vừa cài. Con số trên đĩa repo không phải con số tới tay người dùng (đã cháy: doc báo 74 skill, installer giao 67 — 7 skill hỏng frontmatter bị CLI nuốt im lặng).
RULE-07 (MUST): Rule mới phải CẮN, không chỉ có mặt. File
```
policy.yaml
```
có dòng luật ≠ luật chặn được. Luôn test bằng một file BAD thật.
RULE-08 (MUST): Trần (ceiling) cố ý: UAT headless không spin được model LLM, nên "
```
/orchestration
```
chạy được" chỉ kiểm ở mức tất định (cài đủ + reachable + ping runtime). Live-run bằng model thật vẫn là acceptance làm tay.
RULE-09 (MUST): Fail thì gỡ, không "để đó sửa sau". Remote là thứ người khác kéo về.
RULE-10 (MUST): Workspace Orca hiện thật là BẮT BUỘC, có assert kiểm tên, không phải "tuỳ chọn thấy được bằng mắt". Bị nhắc lặp lại 2 lần (2026-07-21, 2026-07-24) vì trước đây ghi là tuỳ chọn nên bị bỏ qua khi chạy vội — filesystem-only test KHÔNG tính là UAT hoàn chỉnh dù mọi lệnh CLI khác xanh hết.
Capabilities: chạy gate cục bộ; push/xoá nhánh remote và revert/reset nhánh chính (cần quyền ghi remote); tải từ raw CDN; tạo dự án tạm + đăng ký repo/worktree trong Orca; ghi log wiki + problem-tree.

RULE-01 (MUST): **主分支绝不能接收尚未通过 canary 验证的版本。**阶段 1 正是为了确保这一点。
RULE-02 (MUST): **Canary 无法替代 main-URL smoke。**它使用不同的 ref + 变量覆盖运行，因此对默认值是盲的，而默认值正是硬编码分支名的位置。省略阶段 2，就省略了真实用户真正会接触到的部分。
RULE-03 (MUST): **绝不能 push 后置之不理。**既然为了 UAT 而 push，就必须在同一会话中完成 UAT。Push 完就离开，等于给他人留下一个未经验收、却可被拉取的版本。
RULE-04 (MUST): 无论从哪条路径退出，都必须清理 canary 分支（PASS 和 FAIL 都要）。步骤 0 先列出
```
git branch -r | grep uat/
```
，以清理中途会话终止后遗留的分支。
RULE-05 (MUST): CDN 传播并不一致——等待 SENTINEL，不要在 push 后立即测量。
```
raw.githubusercontent
```
可能在同一次安装中返回已更新的文件 A，同时仍返回旧版文件 B，从而产生混合版本，并造成假失败（或更危险的假成功）。应轮询一个只存在于新版本中的字符串，直到 raw 返回正确内容后再测量。2026-07-14 的实测：新 engine + 旧 policy → test-broad 72/74，新 rule 没有生效；等待几分钟后重跑 → 74/74。
RULE-06 (MUST): **不要凭记忆统计 skill/rule——必须在刚安装的项目中 LIVE 统计。**repo 磁盘上的数字并不是用户实际收到的数字（曾出现：文档声称有 74 个 skill，而 installer 只交付了 67 个——7 个 frontmatter 损坏的 skill 被 CLI 静默吞掉）。
RULE-07 (MUST): 新 rule 必须真正 CẮN，而不只是存在。
```
policy.yaml
```
中有一行规则 ≠ 该规则能够实际阻止违规。始终使用真实的 BAD 文件进行测试。
RULE-08 (MUST): **有意设置上限（ceiling）：**UAT headless 无法启动 LLM model，因此“
```
/orchestration
```
可以运行”只能在确定性层级检查（安装完整 + reachable + ping runtime）。使用真实 model 进行 live-run 仍属于人工 acceptance。
RULE-09 (MUST): 失败时必须撤销，不能“留到以后再修”。Remote 是其他用户会拉取的内容。
RULE-10 (MUST): **Orca workspace 真实显示是强制要求，必须使用 assert 检查名称，不能仅靠肉眼判断是否“可选可见”。**该要求已被重复提醒两次（2026-07-21、2026-07-24），因为过去它被写成可选项，导致匆忙运行时被跳过——filesystem-only 测试不属于完整 UAT，即使所有其他 CLI 命令都通过。
Capabilities: 运行本地 gate；push/删除 remote 分支并对主分支执行 revert/reset（需要 remote 写权限）；从 raw CDN 下载；创建临时项目并在 Orca 中注册 repo/worktree；写入 wiki 日志 + problem-tree。

Failure boundaries

```
medic --ci
```
đỏ / git bẩn → blocked ở bước 0, không push.
Không khai được năng lực mới thành lệnh → clarify: đó là lời hứa suông, không tính.
PHA 1 FAIL → failed, xoá canary; nhánh chính chưa bị bẩn.
Assert worktree Orca không thấy tên → failed tạm: DỪNG, không báo PASS, sửa
```
worktree create
```
rồi verify lại.
Sentinel CDN hết 30 lượt chưa mới → chưa đo (không kết luận đỏ/xanh); grep-verify MARK trên file local trước.
PHA 2 FAIL → failed, gỡ commit ngay (bước 5) + ghi problem-tree.

```
medic --ci
```
失败 / git 脏 → 在步骤 0 blocked，不得 push。
无法把新能力具体化为命令 → clarify：这只是空头承诺，不计入。
阶段 1 FAIL → failed，删除 canary；主分支尚未被污染。
Orca worktree assert 找不到名称 → 临时 failed：停止，不得报告 PASS；修正
```
worktree create
```
后重新验证。
Sentinel CDN 经过 30 次轮询后仍未更新 → 尚未测量（不能得出失败/成功结论）；先在 local 文件上执行 grep-verify MARK。
阶段 2 FAIL → failed，立即撤销 commit（步骤 5）+ 写入 problem-tree。

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	repo	Bước 0 — tiền đề: `medic --ci` , `git status --short` , `git log origin/<nhánh>..HEAD` , ghi `BASE`	mốc BASE	đỏ/bẩn → blocked
W02	judgment	diff	Bước 1 — khai checklist năng lực mới, mỗi dòng một lệnh	checklist	không thành lệnh → bỏ dòng đó
W03	effect	HEAD	Bước 2 — PHA 1: push `HEAD:uat/<ts>` , dựng dự án trống, curl từ raw canary với cả 3 biến	dự án UAT	thiếu `SKILLS_REF` = UAT ảo giác
W04	deterministic	dự án UAT	Bước 3 — chạy checklist (3 trụ, test-broad, năng lực mới, orchestration, workspace Orca + assert, layout dot)	PASS/FAIL	FAIL → xoá canary, dừng (B01)
W05	effect	PASS pha 1	Bước 4 — PHA 2: push nhánh chính, xoá canary, chờ sentinel CDN, chạy đúng lệnh README không override, smoke ~1 phút	PASS/FAIL	FAIL → W06
W06	effect	FAIL pha 2	Bước 5 — gỡ commit (revert hoặc reset `--force-with-lease` ) + ghi problem-tree (B02)	remote sạch	—
W07	effect	PASS	Bước 6 — chốt: dọn dự án UAT (hoặc `--keep` ), ghi số đo vào `wiki/log.md`	bản đã nghiệm thu	—

Chi tiết từng bước (nguồn chân lý cho W01–W07):

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	repo	步骤 0——前提：执行 `medic --ci` 、 `git status --short` 、 `git log origin/<nhánh>..HEAD` ，记录 `BASE`	BASE 基准点	失败/脏 → blocked
W02	judgment	diff	步骤 1——列出新能力 checklist，每行一条命令	checklist	无法转化为命令 → 删除该项
W03	effect	HEAD	步骤 2——阶段 1：push `HEAD:uat/<ts>` ，创建空白项目，使用全部三个变量从 canary raw 执行 curl	UAT 项目	缺少 `SKILLS_REF` = 虚假 UAT
W04	deterministic	UAT 项目	步骤 3——执行 checklist（3 个支柱、test-broad、新能力、orchestration、Orca workspace + assert、dot layout）	PASS/FAIL	FAIL → 删除 canary，停止（B01）
W05	effect	阶段 1 PASS	步骤 4——阶段 2：push 主分支，删除 canary，等待 sentinel CDN，按 README 原样执行且不覆盖变量，执行约 1 分钟的 smoke	PASS/FAIL	FAIL → W06
W06	effect	阶段 2 FAIL	步骤 5——撤销 commit（revert 或 reset `--force-with-lease` ）+ 写入 problem-tree（B02）	remote 恢复干净	—
W07	effect	PASS	步骤 6——定案：清理 UAT 项目（或使用 `--keep` ），将测量结果写入 `wiki/log.md`	已验收版本	—

以下各步骤的详细信息（W01–W07 的事实来源）：

0. Tiền đề — không được bỏ

0. 前提——不可省略

bash

python3 fdk/tools/medic.py --ci          # PHẢI xanh. Đỏ mà vẫn push là cố ý đẩy rác lên remote.
git status --short                        # sạch (không untracked lạc)
git log --oneline origin/<nhánh>..HEAD    # in ĐÚNG những commit sắp đẩy — ghi lại, đây là thứ sẽ gỡ nếu fail

Ghi lại
BASE=$(git rev-parse origin/<nhánh>)
— mốc để quay về.

bash

python3 fdk/tools/medic.py --ci          # PHẢI xanh. Đỏ mà vẫn push là cố ý đẩy rác lên remote.
git status --short                        # sạch (không untracked lạc)
git log --oneline origin/<nhánh>..HEAD    # in ĐÚNG những commit sắp đẩy — ghi lại, đây là thứ sẽ gỡ nếu fail

记录
BASE=$(git rev-parse origin/<nhánh>)
——这是用于回退的基准点。

1. Khai năng lực mới của bản này (checklist UAT)

1. 列出本版本的新能力（UAT checklist）

Trước khi push, viết ra cụ thể bản này hứa gì mới. Mỗi dòng phải kiểm được bằng lệnh:

Skill mới →
```
~/.claude/skills/<tên>/SKILL.md
```
tồn tại sau khi cài, và có trong
```
CAPABILITIES.md
```
của dự án mới.
Rule mới → phải CẮN THẬT trong dự án mới (viết một file BAD → bị chặn; file GOOD → qua).
Engine/tool mới → reachable trong global harness home.

Không khai được thành lệnh thì không tính là năng lực — đó là lời hứa suông.

在 push 前，明确写出本版本具体承诺了哪些新能力。每行都必须能通过命令验证：

新 Skill → 安装后
```
~/.claude/skills/<tên>/SKILL.md
```
存在，并且出现在新项目的
```
CAPABILITIES.md
```
中。
新 Rule → 必须在新项目中真正 CẮN（创建一个 BAD 文件 → 应被阻止；GOOD 文件 → 应通过）。
新 Engine/tool → 在 global harness home 中 reachable。

如果无法具体化为命令，就不算新能力——那只是空头承诺。

2. PHA 1 — nhánh CANARY (nhánh chính KHÔNG nhận gì cả)

2. 阶段 1——CANARY 分支（主分支不接收任何内容）

Đường remote chỉ tồn tại sau khi push — nhưng không nhất thiết phải push lên nhánh chính. Một nhánh tạm cũng có raw URL, và

curl

không quan tâm nhánh nào.

bash

CANARY="uat/$(date +%y%m%d-%H%M)"
git push origin HEAD:"$CANARY"

Dựng dự án trống, cài từ raw của chính nhánh canary — phải trỏ cả ba biến, không thì nó lặng lẽ kéo nội dung của nhánh chính:

bash

D=~/orca/overstack-uat-$(date +%y%m%d-%H%M)
mkdir -p "$D" && cd "$D" && git init
RAW="https://raw.githubusercontent.com/<owner>/<repo>/$CANARY"
curl -fsSL "$RAW/harness/poc-vendor-neutral/bootstrap.sh" \
  | HARNESS_BASE="$RAW/harness/poc-vendor-neutral" \
    REPO_RAW="$RAW" \
    SKILLS_REF="<owner>/<repo>#$CANARY" \
    bash
git add -A && git commit -m "fresh overstack install"    # Orca cần ≥1 commit mới nhận repo

Thiếu
SKILLS_REF
là bài UAT thành ẢO GIÁC.
install.sh
mặc định cài skill từ
<repo>#<nhánh chính>
— nên nếu không override, canary sẽ cài skill của nhánh chính, tức nó chấm bản CŨ rồi báo PASS cho bản MỚI. Một cổng nói dối mà vẫn xanh còn tệ hơn không có cổng.

Chạy checklist bước 3. PASS → sang pha 2. FAIL → xoá canary, nhánh chính chưa hề bị bẩn:

bash

git push origin --delete "$CANARY"

remote 路径只有在 push 之后才存在——但不一定必须推送到主分支。临时分支同样有 raw URL，而

curl

不关心具体是哪个分支。

bash

CANARY="uat/$(date +%y%m%d-%H%M)"
git push origin HEAD:"$CANARY"

创建空白项目，从canary 分支自身的 raw 安装——必须指向全部三个变量，否则它会静默拉取主分支的内容：

bash

D=~/orca/overstack-uat-$(date +%y%m%d-%H%M)
mkdir -p "$D" && cd "$D" && git init
RAW="https://raw.githubusercontent.com/<owner>/<repo>/$CANARY"
curl -fsSL "$RAW/harness/poc-vendor-neutral/bootstrap.sh" \
  | HARNESS_BASE="$RAW/harness/poc-vendor-neutral" \
    REPO_RAW="$RAW" \
    SKILLS_REF="<owner>/<repo>#$CANARY" \
    bash
git add -A && git commit -m "fresh overstack install"    # Orca cần ≥1 commit mới nhận repo

缺少
SKILLS_REF
会让 UAT 变成假象。
install.sh
默认从
<repo>#<nhánh chính>
安装 skill——因此如果不覆盖该变量，canary 会安装主分支的 skill，也就是用旧版本为新版本打分并报告 PASS。一个会说谎却仍然变绿的检测门，比没有检测门更糟。

执行步骤 3 的 checklist。PASS → 进入阶段 2。FAIL → 删除 canary，主分支从未被污染：

bash

git push origin --delete "$CANARY"

3. UAT — chạy checklist bước 1 trong dự án ĐÓ

3. UAT——在该项目中执行步骤 1 的 checklist

Tối thiểu, theo

fdk/docs/fresh-install-gate.md

3 trụ có mặt:

.harness/poc-vendor-neutral/policy.yaml

.claude/settings.json

.pre-commit-config.yaml

.llmwiki/wiki/index.md

CAPABILITIES.md

Harness cắn thật:
```
bash .harness/poc-vendor-neutral/test-broad.sh
```
→ PASS (validator GOOD-pass / BAD-block).
Năng lực MỚI tới tay — phần riêng của bản này (checklist bước 1). Đây là mục hay bị bỏ nhất, và cũng là mục duy nhất chứng minh bản MỚI có giá trị.

Orchestration-ready: skill

orchestration

orca-cli

orca-dispatch-reference

reachable.

Module repo riêng tới nơi (orca-graph):
```
python3 ~/.claude/harness/harness/scripts/orca-graph.py --version
```
trong HOME của dự án trống phải in
```
orca-graph X.Y.Z
```
(rc 0). rc 3 = shim tới mà engine không tới → FAIL, kể cả khi mọi thứ khác xanh. Cài với
```
--no-graph
```
thì kỳ vọng NGƯỢC LẠI: rc 3 kèm đúng một lệnh cài.
```
fresh-install-smoke.sh
```
mục (G) kiểm tự động; UAT ghi kết quả vào checklist.
BẮT BUỘC (không phải tuỳ chọn — feedback 2026-07-24, lần thứ 2 bị nhắc vì skip bước này): dựng workspace Orca thật + TỰ VERIFY nó hiện trong app, đừng chỉ chạy filesystem-level. Chỉ curl-cài vào một thư mục tạm rồi test bằng CLI KHÔNG tính là UAT hoàn chỉnh — user không thấy được gì, "không visual = không dùng được". Đây là cổng CỨNG: UAT KHÔNG được coi là PASS nếu bỏ qua bước này.

bash

WT_NAME="uat-$(date +%y%m%d-%H%M)"                          # tên xác định, dùng để verify ở bước sau
REPO_ID=$(orca repo add --path "$D" --json | python3 -c "import json,sys; print(json.load(sys.stdin)['result']['repo']['id'])")
orca worktree create --repo "id:$REPO_ID" --name "$WT_NAME" --setup skip --no-parent --activate --json

Cạm bẫy đã dính:
orca repo add <path>
positional →
Unknown command
. Repo chưa có commit → Orca không nhận.
repo add
không làm workspace hiện trong app — phải
worktree create
.

Cổng verify — chạy NGAY sau lệnh trên, đây không phải bước phụ:

bash

orca worktree list --repo "id:$REPO_ID" --json | python3 -c "
import json, sys
d = json.load(sys.stdin)
names = [w['displayName'] for w in d['result']['worktrees']]
assert '$WT_NAME' in names, f'KHÔNG THẤY worktree tên {\"$WT_NAME\"} — UAT KHÔNG ĐƯỢC TÍNH LÀ PASS. Có: {names}'
print(f'✓ worktree \"$WT_NAME\" hiện thật trong Orca — {names}')
"

Assertion FAIL ở đây → DỪNG, không được tiếp tục báo PASS cho user — quay lại sửa lệnh

worktree create

(thường do

--repo

sai định dạng selector hoặc

repo add

chưa commit) rồi verify lại. Đây chính là gate cấu trúc thay cho việc "phải nhớ tự giác dựng workspace mỗi lần" — nhớ tay đã fail 2 lần liền (2026-07-21, 2026-07-24), giờ ép bằng assert. 6. Layout đúng chuẩn dot: không tồn tại

llmwiki/

hay

harness/

trần ở gốc dự án UAT — chỉ

.llmwiki/

.harness/

(AP-7 layout hallucination).

最低要求，按照

fdk/docs/fresh-install-gate.md

：

3 个支柱存在：

.harness/poc-vendor-neutral/policy.yaml

.claude/settings.json

.pre-commit-config.yaml

.llmwiki/wiki/index.md

CAPABILITIES.md

。

Harness 真正生效：
```
bash .harness/poc-vendor-neutral/test-broad.sh
```
→ PASS（validator 对 GOOD 放行 / 对 BAD 阻止）。
新能力到达用户手中——本版本专属部分（步骤 1 的 checklist）。这是最常被遗漏的一项，也是唯一能够证明新版本确实有价值的部分。
**Orchestration-ready：**skill
```
orchestration
```
/
```
orca-cli
```
/
```
orca-dispatch-reference
```
reachable。
**独立 repo module 成功交付（orca-graph）：**在空白项目的 HOME 中执行
```
python3 ~/.claude/harness/harness/scripts/orca-graph.py --version
```
，必须输出
```
orca-graph X.Y.Z
```
（rc 0）。rc 3 = 存在 shim，但 engine 未交付 → FAIL，即使其他所有内容都通过。使用
```
--no-graph
```
安装时，预期相反：rc 3，并附带一条准确的安装命令。
```
fresh-install-smoke.sh
```
的项目 (G) 会自动检查；UAT 将结果记录到 checklist。
**强制要求（不是可选项——2026-07-24 反馈，第二次提醒是因为该步骤曾被跳过）：创建真实的 Orca workspace + 自行验证它显示在 app 中，不能只做 filesystem-level 测试。**仅通过 curl 安装到临时目录后再运行 CLI，不属于完整 UAT——用户看不到任何内容，“不可见 = 不可用”。这是硬性门禁：遗漏此步骤时，UAT 不得被判定为 PASS。

bash

WT_NAME="uat-$(date +%y%m%d-%H%M)"                          # tên xác định, dùng để verify ở bước sau
REPO_ID=$(orca repo add --path "$D" --json | python3 -c "import json,sys; print(json.load(sys.stdin)['result']['repo']['id'])")
orca worktree create --repo "id:$REPO_ID" --name "$WT_NAME" --setup skip --no-parent --activate --json

已经踩过的坑：使用 positional 参数执行
orca repo add <path>
→
Unknown command
。Repo 没有 commit → Orca 不会接收。
repo add
不会让 workspace 出现在 app 中——必须执行
worktree create
。

验证门禁——紧接上面的命令执行，这不是可选子步骤：

bash

orca worktree list --repo "id:$REPO_ID" --json | python3 -c "
import json, sys
d = json.load(sys.stdin)
names = [w['displayName'] for w in d['result']['worktrees']]
assert '$WT_NAME' in names, f'KHÔNG THẤY worktree tên {\"$WT_NAME\"} — UAT KHÔNG ĐƯỢC TÍNH LÀ PASS. Có: {names}'
print(f'✓ worktree \"$WT_NAME\" hiện thật trong Orca — {names}')
"

此处的 Assertion FAIL → 停止，不得继续向用户报告 PASS——返回并修正

worktree create

命令（通常是因为

--repo

selector 格式错误，或

repo add

前尚未 commit），然后重新验证。这正是用来替代“必须靠自觉记住每次都创建 workspace”的结构性门禁——靠记忆已经连续失败 2 次（2026-07-21、2026-07-24），现在通过 assert 强制执行。 6. **符合 dot layout 标准：**UAT 项目根目录中不得存在裸

llmwiki/

或

harness/

——只能存在

.llmwiki/

.harness/

（AP-7 layout hallucination）。

4. PHA 2 — main-URL smoke, NGAY SAU merge (canary KHÔNG thay được bước này)

4. 阶段 2——merge 后立即执行 main-URL smoke（canary 无法替代此步骤）

Pha 1 chạy với ref khác và ba biến override → nó mù với chính các giá trị mặc định. Mà mặc định là chỗ chứa chuỗi nhánh hardcode (

bootstrap.sh

BASE=

install.sh

REPO_RAW=

SKILLS_REF=

). Chỉ pha này kiểm được đúng cái lệnh người mới thật sự gõ.

bash

git push origin HEAD:<nhánh chính>          # merge — bản này ĐÃ qua canary
git push origin --delete "$CANARY"          # dọn nhánh tạm

CHỜ CDN PROPAGATE TRƯỚC KHI ĐO — bắt buộc.

raw.githubusercontent.com

không phục vụ bản mới ngay sau push, và độ trễ không đồng đều giữa các file: đã đo được cảnh engine (

bin/llmwiki-validate.py

) đã mới trong khi

policy.yaml

còn cũ → bản cài ra là một thứ lai, và cổng báo ĐỎ GIẢ. Nguy hiểm hơn: cùng cơ chế đó có thể cho XANH GIẢ nếu file cũ tình cờ vẫn qua được test.

Chốt bằng một sentinel — poll tới khi raw trả đúng nội dung mình vừa đẩy:

bash

RAW="https://raw.githubusercontent.com/<owner>/<repo>/<nhánh chính>"
MARK="<một chuỗi CHỈ có ở bản mới>"      # vd tên rule/field vừa thêm
  # ⚠ GREP-VERIFY MARK trên file bản mới TRƯỚC (grep "$MARK" <file local>) — chọn pattern đoán
  #   mà không khớp file → vòng lặp chờ hết lượt rồi tưởng raw còn cũ, dù raw ĐÃ mới (p-32).
for i in $(seq 1 30); do
  curl -fsSL "$RAW/harness/poc-vendor-neutral/policy.yaml" | grep -q "$MARK" && break
  echo "  raw còn cũ, chờ CDN… ($i)"; sleep 10
done

Rồi mới chạy đúng lệnh trong README — không override một biến nào:

bash

D2=$(mktemp -d) && cd "$D2" && git init -q
curl -fsSL "$RAW/harness/poc-vendor-neutral/bootstrap.sh" | bash

Rút gọn (~1 phút): 3 trụ có mặt ·

bash .harness/poc-vendor-neutral/test-broad.sh

PASS · skill mới reachable trong

~/.claude/skills/

FAIL → gỡ ngay (bước 5). Cửa sổ rủi ro của nhánh chính thu từ "cả bài UAT dài" xuống "một lần smoke ~1 phút".

阶段 1 使用不同的 ref 和三个覆盖变量运行，因此它对真正的默认值是盲的。而默认值正是硬编码分支字符串的位置（

bootstrap.sh

的

BASE=

，以及

install.sh

的

REPO_RAW=

、

SKILLS_REF=

）。只有此阶段才能检验新用户真正输入的命令。

bash

git push origin HEAD:<nhánh chính>          # merge — bản này ĐÃ qua canary
git push origin --delete "$CANARY"          # dọn nhánh tạm

测量前必须等待 CDN PROPAGATE。

raw.githubusercontent.com

不会在 push 后立即提供新版本，而且不同文件之间的延迟并不一致：实测曾出现 engine（

bin/llmwiki-validate.py

）已经更新，而

policy.yaml

仍是旧版——最终安装出的是一个混合版本，并造成假失败。更危险的是，同一机制还可能造成假成功：如果旧文件碰巧仍能通过测试。

使用一个 sentinel 定案——轮询直到 raw 返回刚推送的正确内容：

bash

RAW="https://raw.githubusercontent.com/<owner>/<repo>/<nhánh chính>"
MARK="<một chuỗi CHỈ có ở bản mới>"      # vd tên rule/field vừa thêm
  # ⚠ GREP-VERIFY MARK trên file bản mới TRƯỚC (grep "$MARK" <file local>) — chọn pattern đoán
  #   mà không khớp file → vòng lặp chờ hết lượt rồi tưởng raw còn cũ, dù raw ĐÃ mới (p-32).
for i in $(seq 1 30); do
  curl -fsSL "$RAW/harness/poc-vendor-neutral/policy.yaml" | grep -q "$MARK" && break
  echo "  raw còn cũ, chờ CDN… ($i)"; sleep 10
done

然后运行 README 中的准确命令——不覆盖任何变量：

bash

D2=$(mktemp -d) && cd "$D2" && git init -q
curl -fsSL "$RAW/harness/poc-vendor-neutral/bootstrap.sh" | bash

精简版（约 1 分钟）：3 个支柱存在 ·

bash .harness/poc-vendor-neutral/test-broad.sh

PASS · 新 skill 在

~/.claude/skills/

中 reachable。

FAIL → 立即撤销（步骤 5）。主分支面临风险的时间窗口由此从“整个冗长 UAT”缩短为“一次约 1 分钟的 smoke”。

5. KHÔNG PASS → gỡ commit khỏi remote NGAY

5. 未通过 → 立即从 remote 撤销 commit

Chỉ dùng khi PHA 2 đỏ (hoặc ai đó đã lỡ push thẳng, bỏ qua canary). Chọn theo tình huống:

bash

undefined

仅在阶段 2 失败（或有人误将代码直接 push、跳过 canary）时使用。根据情况选择：

bash

undefined

(a) Nhánh chia sẻ / đã có người kéo → REVERT (không viết lại lịch sử):

git revert --no-edit <sha>..HEAD && git push origin <nhánh>

(b) Nhánh chỉ mình dùng, vừa đẩy xong, chắc chắn chưa ai kéo → RESET:

git reset --hard "$BASE" && git push --force-with-lease origin <nhánh>

`--force-with-lease` chứ **không** `--force`: nếu trong lúc đó có người đẩy lên, lệnh sẽ từ chối thay vì xoá mất việc của họ.

Gỡ xong: ghi lại **vì sao fail** vào `llmwiki/html/fdk-problem-tree.html` (node mới, `status: open`) — thất bại UAT là dữ liệu, không phải chuyện xấu hổ.

git reset --hard "$BASE" && git push --force-with-lease origin <nhánh>

使用 `--force-with-lease`，**不要**使用 `--force`：如果期间有人 push 了内容，该命令会拒绝执行，而不是删除他们的工作。

撤销完成后：将**失败原因**写入 `llmwiki/html/fdk-problem-tree.html`（新节点，`status: open`）——UAT 失败是数据，不是可耻的事。

6. PASS → chốt

6. PASS → 定案

Dọn dự án UAT (hoặc giữ lại
```
--keep
```
nếu cần soi).
Ghi kết quả (số đo thật, không phải lời hứa) vào
```
wiki/log.md
```
.
Bản trên remote coi như đã được nghiệm thu ở tầng "người mới cài".

清理 UAT 项目（如果需要继续检查，则使用
```
--keep
```
保留）。
将结果（真实测量值，而不是口头承诺）写入
```
wiki/log.md
```
。
此时 remote 上的版本视为已在“新用户安装”层级完成验收。

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	recovery	PHA 1 FAIL	`git push origin --delete "$CANARY"` ; nhánh chính không đụng	—	kết thúc (failed)
B02	recovery	PHA 2 FAIL (hoặc lỡ push thẳng bỏ canary)	nhánh chia sẻ → `git revert --no-edit <sha>..HEAD` ; nhánh riêng chưa ai kéo → `git reset --hard "$BASE"` + `--force-with-lease` ; ghi node problem-tree	không bao giờ `--force` trần	kết thúc (failed)
B03	recovery	assert worktree Orca FAIL	DỪNG, sửa `--repo` selector / commit trước `repo add` , verify lại	không được báo PASS	W04 mục 5
B04	user_optional	`--keep`	giữ dự án UAT để soi thay vì dọn	—	W07
B05	recovery	bước 0 liệt kê `git branch -r` thấy còn nhánh `uat/` cũ	dọn canary rác của phiên chết giữa chừng	—	W01

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	recovery	阶段 1 FAIL	执行 `git push origin --delete "$CANARY"` ；不触碰主分支	—	结束（failed）
B02	recovery	阶段 2 FAIL（或误将代码直接 push、跳过 canary）	共享分支 → `git revert --no-edit <sha>..HEAD` ；无人拉取的独立分支 → `git reset --hard "$BASE"` + `--force-with-lease` ；写入 problem-tree 节点	绝不使用裸 `--force`	结束（failed）
B03	recovery	Orca worktree assert FAIL	停止，修正 `--repo` selector / 在 `repo add` 前创建 commit，然后重新验证	不得报告 PASS	W04 第 5 项
B04	user_optional	`--keep`	保留 UAT 项目以便检查，而不是清理	—	W07
B05	recovery	步骤 0 列出 `git branch -r` 时发现旧 `uat/` 分支	清理会话中途终止后遗留的 canary 分支	—	W01

Validation và stopping

Validation 与停止条件

PASS chỉ khi mọi mục checklist bước 3 xanh bằng lệnh (kể cả assert worktree tên

$WT_NAME

) VÀ smoke pha 2 xanh sau sentinel. Đếm skill/rule LIVE trong dự án vừa cài, không theo trí nhớ. Sentinel poll tối đa 30 × 10s. Không bao giờ push rồi bỏ mặc: UAT chạy trong cùng phiên.

只有当步骤 3 的所有 checklist 项都通过命令验证为绿色（包括

$WT_NAME

的 worktree assert），并且阶段 2 在 sentinel 之后通过 smoke，才能判定 PASS。必须在刚安装的项目中 LIVE 统计 skill/rule 数量，而不是凭记忆。Sentinel 最多轮询 30 × 10s。绝不能 push 后置之不理：UAT 必须在同一会话中运行。

Examples

Positive: bản thêm skill
```
record-episode
```
→ checklist "
```
~/.claude/skills/record-episode/SKILL.md
```
tồn tại + có trong
```
CAPABILITIES.md
```
" → push
```
uat/260919-1030
```
, curl với
```
SKILLS_REF="<owner>/<repo>#uat/260919-1030"
```
→ test-broad PASS, skill reachable,
```
orca worktree list
```
thấy
```
uat-260919-1030
```
→ push nhánh chính, sentinel khớp, smoke không override PASS → xoá canary, ghi
```
wiki/log.md
```
.
Boundary/failure: PHA 2 đo ngay sau push không chờ sentinel → engine mới +
```
policy.yaml
```
cũ → test-broad 72/74, luật mới không cắn → đây là đỏ GIẢ: chờ sentinel rồi đo lại (74/74). Nếu sau sentinel vẫn đỏ → gỡ commit bằng revert, ghi node
```
status: open
```
.

**Positive：**版本新增 skill
```
record-episode
```
→ checklist 为“
```
~/.claude/skills/record-episode/SKILL.md
```
存在 + 出现在
```
CAPABILITIES.md
```
中” → push
```
uat/260919-1030
```
，使用
```
SKILLS_REF="<owner>/<repo>#uat/260919-1030"
```
执行 curl → test-broad PASS、skill reachable、
```
orca worktree list
```
找到
```
uat-260919-1030
```
→ push 主分支、sentinel 匹配、无覆盖 smoke PASS → 删除 canary、写入
```
wiki/log.md
```
。
**Boundary/failure：**阶段 2 在 push 后未等待 sentinel 就立即测量 → 新 engine + 旧
```
policy.yaml
```
→ test-broad 72/74，新 rule 没有生效 → 这是假失败：等待 sentinel 后重新测量（74/74）。如果经过 sentinel 后仍然失败 → 使用 revert 撤销 commit，并添加
```
status: open
```
节点。

Origin

Luồng distill từ
```
fdk/docs/fresh-install-gate.md
```
(§ "Luồng chuẩn: dựng workspace Orca mới rồi test fresh-install") + yêu cầu của user 2026-07-14: cho phép push trước để test thật, không pass thì gỡ commit khỏi remote.
Hai pha là kết quả của một phản biện của user cùng ngày: "nếu vậy thì nó có test được đúng cái curl của main không?" — không. Canary chứng minh nội dung cài được qua remote; chỉ main-URL smoke chứng minh cái lệnh mặc định chạy được. Kèm phát hiện
```
install.sh
```
hardcode
```
#orca
```
không có đường override — thiếu nó thì canary chấm nhầm bản cũ.

蒸馏流程源自
```
fdk/docs/fresh-install-gate.md
```
（§“标准流程：创建新的 Orca workspace，然后执行 fresh-install 测试”）+ 用户在 2026-07-14 提出的要求：允许预先 push 以进行真实测试，若未通过，则从 remote 撤销 commit。
两阶段源于用户同一天提出的反问：“如果这样，能真正测试 main 的 curl 吗？”——不能。Canary 证明通过 remote 安装的内容可行；只有 main-URL smoke 证明默认命令能够运行。此外还发现
```
install.sh
```
硬编码了
```
#orca
```
且没有 override 路径——缺少它，canary 会误测旧版本。