harness-update

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: harness-update

WHAT

概述（WHAT）

Purpose và context

目的与上下文

Purpose: Một lệnh gọi là xong cho dự án CŨ: cài/update harness stack (L0–L4) và tự động trả nợ wiki legacy thay user.
Trigger (when to use): "tự bảo trì framework", "self-maintain", "migrate harness", "update harness", "update overstack", "nâng cấp harness", "cài harness vào dự án cũ", "/harness-update" — dự án có llmwiki cũ cần migrate (case B) hoặc đã có harness cần update (case C).
Non-goals: KHÔNG dùng cho project chưa có gì + cần populate wiki từ code — đó là
```
/new-project-setup
```
(case A). Không chữa lỗi hạ tầng (network, python3, validator hỏng).

< 30s: dùng cờ

--self-heal

— installer tự backfill nợ (Origin + index + OKF) ngay trong process rồi re-audit 1 lần. Agent chỉ gọi 1 lệnh, đọc 1 kết quả, báo cáo. KHÔNG còn vòng lặp re-run phía agent (đó là cái làm chậm bản cũ — xem [[230626-harness-update-sub30s]]).

目的： 一条命令即可为旧项目完成全部工作：安装或更新 harness stack（L0–L4），并自动替用户处理 legacy wiki 的待补项。
触发条件（何时使用）：
```
tự bảo trì framework
```
（自行维护 framework）、
```
self-maintain
```
、
```
migrate harness
```
（迁移 harness）、
```
update harness
```
（更新 harness）、
```
update overstack
```
（更新 overstack）、
```
nâng cấp harness
```
（升级 harness）、
```
cài harness vào dự án cũ
```
（将 harness 安装到旧项目）、
```
/harness-update
```
——适用于存在旧版 llmwiki、需要迁移的项目（case B），或已有 harness、需要更新的项目（case C）。
非目标： 不用于什么都没有且需要从代码填充 wiki 的项目——那应使用
```
/new-project-setup
```
（case A）。也不修复基础设施问题（network、python3、validator 损坏）。

< 30 秒： 使用

--self-heal

标志——installer 会在同一 process 内立即 backfill 待补项（Origin + index + OKF），然后 re-audit 1 次。Agent 只调用 1 次命令、读取 1 次结果并报告。Agent 端不再有 re-run 循环（旧版本正是因此变慢——见 [[230626-harness-update-sub30s]]）。

Mental model

心智模型

installer --self-heal (1 process: cài L0–L4 → audit → backfill → re-audit → activate + smoke) → rc (0 sạch · 3 nợ còn lại · khác = hạ tầng) → nghiệm thu + refresh CAPABILITIES + log → báo cáo 4 ý

installer --self-heal（1 个 process：安装 L0–L4 → audit → backfill → re-audit → activate + smoke）→ rc（0 干净 · 3 仍有待补项 · 其他 = 基础设施）→ 验收 + refresh CAPABILITIES + log → 报告 4 点

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	dự án đích (thư mục hiện tại)	có	có llmwiki cũ (case B) hoặc harness cũ (case C)
In	`harness/scripts/install-harness.sh`	không	thiếu thì clone template `rheinmir/setup` nhánh `orca`
Out	harness L0–L4 đã cài + nợ wiki đã backfill	có	rc=0 là sạch
Out	`CAPABILITIES.md` sinh lại	khi có build-capabilities	bản cũ không có → bỏ qua
Out	dòng log `llmwiki/wiki/log.md` + báo cáo 4 ý	có	số backfill lấy từ dòng `[audit] backfill xong`

	字段	必填？	含义
In	目标项目（当前目录）	是	含有旧版 llmwiki（case B）或旧版 harness（case C）
In	`harness/scripts/install-harness.sh`	否	缺失时 clone template `rheinmir/setup` 的 `orca` 分支
Out	已安装 harness L0–L4，且 wiki 待补项已 backfill	是	rc=0 表示干净
Out	重新生成 `CAPABILITIES.md`	有 build-capabilities 时	旧版本没有则跳过
Out	`llmwiki/wiki/log.md` 日志行及 4 点报告	是	backfill 数量取自 `[audit] backfill xong` 行

Rules và capabilities

规则与能力

RULE-01 (MUST): Backfill là THÊM, không bao giờ sửa/xóa nội dung wiki có sẵn (self-heal trong installer giữ đúng quy tắc này).
RULE-02 (MUST): Không đụng
```
raw/
```
dưới mọi hình thức.
RULE-03 (MUST): rc=3 (nợ còn lại) cần user/skill xử 1 lần; rc khác (hạ tầng) là việc của user — phân biệt rõ, không cố chữa lỗi hạ tầng.
RULE-04 (MUST): Không cờ
```
--self-heal
```
→ installer chạy y hệt hành vi cũ (audit rồi exit 3 nếu nợ) — backward-compatible.
RULE-05 (MUST): Case A (chưa có llmwiki, cần đọc code populate wiki) → chuyển hướng sang
```
/new-project-setup
```
.
Capabilities: chạy installer cục bộ (có thể clone template qua mạng); ghi harness + wiki (chỉ thêm) + log; không ghi
```
raw/
```
.

RULE-01（MUST）：Backfill 是追加操作，绝不修改或删除已有 wiki 内容（installer 内的 self-heal 严格遵守此规则）。
RULE-02（MUST）：任何情况下都不得触碰
```
raw/
```
。
RULE-03（MUST）：rc=3（仍有待补项）需要 user/skill 处理 1 次；其他 rc（基础设施问题）由 user 负责——必须明确区分，不得尝试修复基础设施错误。
RULE-04（MUST）：未传入
```
--self-heal
```
时，installer 的行为与旧版完全一致（执行 audit，若存在待补项则 exit 3）——保持 backward-compatible。
RULE-05（MUST）：Case A（没有 llmwiki，需要读取代码并填充 wiki）→ 重定向至
```
/new-project-setup
```
。
能力：运行本地 installer（可通过网络 clone template）；写入 harness + wiki（仅追加）及 log；不写入
```
raw/
```
。

Failure boundaries

失败边界

```
rc=3
```
→ partial: danh sách nợ nằm trong output, sửa thủ công 1 lần rồi chạy lại W01.
```
rc
```
khác (1/4) → blocked (hạ tầng): DỪNG, báo user nguyên văn, không tự đoán.
Dự án chưa có llmwiki (case A) → cancelled ở skill này, chuyển
```
/new-project-setup
```
.

```
rc=3
```
→ 部分完成（partial）：待补项列表位于输出中，手动修复 1 次，然后再次运行 W01。
其他
```
rc
```
（1/4）→ 阻塞（blocked），属于基础设施问题：立即停止，原样向 user 报告，不得自行推测处理方式。
项目没有 llmwiki（case A）→ 在此 skill 中取消（cancelled），转至
```
/new-project-setup
```
。

HOW

执行方式（HOW）

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	effect	dự án đích	Chạy installer 1 lần với `--self-heal` (thiếu nguồn thì clone template)	output + rc	—
W02	deterministic	rc	Đọc exit code, KHÔNG vòng lặp re-run	rc=0 → W03	rc=3 → B01; rc khác → blocked
W03	effect	output W01	Nghiệm thu ⛔×3 + refresh CAPABILITIES + health-check tuỳ chọn + log	log + CAPABILITIES	không có build-capabilities → bỏ qua
W04	deterministic	kết quả	Báo cáo user đủ 4 ý	báo cáo	—

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

1. Chọn đường theo LAYOUT rồi chạy installer đúng 1 lần:

Dự án downstream layout dot (có
```
.llmwiki/.harness-stamp
```
— mọi máy cài từ v4): engine sống ở GLOBAL, nên cập nhật = chạy lại bootstrap. Nó refresh
```
~/.claude/harness
```
khi version lệch, kéo/cập nhật engine orca-graph cùng chuyến với shim, đóng lại stamp, và KHÔNG chép engine vào dự án:

bash

curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/harness/poc-vendor-neutral/bootstrap.sh | bash

Gọi nhầm

install-harness.sh . --self-heal

ở layout này → script tự DỪNG rc 5 và in đúng lệnh trên (đo 20/09/2026: đường cũ không cập nhật global mà còn chép 77 script vào dự án). Agent chạy trong terminal có pty: thêm

-s -- --with-graph

để khỏi chờ checklist 60 giây.

Repo framework (
```
repo_role: framework
```
): KHÔNG chạy installer vào đây — installer tự từ chối rc 3. Cập nhật framework =
```
git pull
```
.
Layout cũ trần (
```
llmwiki/
```
+
```
harness/
```
nằm trong dự án, chưa có stamp) — đường
```
--self-heal
```
(tự detect migrate/update; thiếu nguồn thì clone template):

bash

test -f harness/scripts/install-harness.sh \
  && bash harness/scripts/install-harness.sh . --self-heal \
  || { git clone -q --depth 1 -b orca git@github.com:rheinmir/setup.git /tmp/llmwiki-tpl \
       && bash /tmp/llmwiki-tpl/harness/scripts/install-harness.sh . --self-heal ; rm -rf /tmp/llmwiki-tpl; }

Installer tự làm trọn gói: cài L0–L4 → audit (Origin/index/OKF gộp 1 process qua

audit.py

) → nếu có nợ thì TỰ backfill (Origin lấy hash bằng 1 lượt

git log

cho cả lô; index thêm row thiếu; OKF migrate bold

**Type:**

→ YAML) → re-audit 1 lần → activate + smoke.

2. Đọc exit code (KHÔNG vòng lặp re-run — self-heal đã chạy bên trong):

```
rc=0
```
→ sạch (đã tự backfill xong). Sang bước 3.
```
rc=3
```
→ còn nợ self-heal KHÔNG tự sửa được (vd file conflict, type OKF không suy được): danh sách nằm ngay trong output. Sửa thủ công 1 lần rồi chạy lại bước 1.
```
rc khác
```
(1/4) → lỗi hạ tầng (network, python3, validator hỏng) — DỪNG, báo user nguyên văn, không tự đoán.

3. Nghiệm thu + log:

Xác nhận bảng "Harness tự kiểm" có ⛔×3 BỊ CHẶN ✓ trong output bước 1 (installer đã chạy
```
pre-commit install
```
nếu có pre-commit; chưa có thì nhắc user
```
pipx install pre-commit
```
).
Refresh bản đồ năng lực (để agent thấy đúng đồ nghề sau update — ADR-005):
```
python3 ~/.claude/harness/hooks/build-capabilities.py --root .
```
(bản deploy cạnh hooks) HOẶC
```
python3 fdk/tools/build-capabilities.py
```
(nếu đang trong repo framework) → sinh lại
```
CAPABILITIES.md
```
. Không có file build-capabilities (bản cũ) → bỏ qua, không lỗi.
Health-check (tuỳ chọn, xác nhận rào còn cắn sau update):
```
/health-check
```
hoặc
```
python3 ~/.claude/harness/hooks/health-check.py
```
.

Append vào

llmwiki/wiki/log.md

## YYYY-MM-DD — harness-update — migrate/update xong (--self-heal), nợ đã backfill: <n> file

. Số liệu lấy từ dòng

[audit] backfill xong — Origin:<a> index:<b> OKF:<c>

trong output.

4. Báo cáo cho user (bắt buộc đủ 4 ý):

Mode đã chạy (migrate hay update) + số nợ self-heal đã backfill (Origin/index/OKF từ dòng
```
[audit] backfill xong
```
)
Settings root: file backup
```
.bak.*
```
nếu có merge
Nhắc: mở session mới thì hooks mới load
Mời:
```
/harness-tour
```
để xem hàng rào cắn trực quan

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	effect	目标项目	使用 `--self-heal` 运行 installer 1 次（缺少源时 clone template）	output + rc	—
W02	deterministic	rc	读取 exit code，禁止 re-run 循环	rc=0 → W03	rc=3 → B01；其他 → blocked
W03	effect	W01 的 output	验收 ⛔×3 + refresh CAPABILITIES + 可选 health-check + log	log + CAPABILITIES	没有 build-capabilities → 跳过
W04	deterministic	结果	向 user 报告完整的 4 点信息	报告	—

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

1. 根据 LAYOUT 选择路径，然后只运行 installer 一次：

下游项目采用 dot layout（存在
```
.llmwiki/.harness-stamp
```
——所有从 v4 开始安装的机器均如此）：engine 位于 GLOBAL，因此更新方式是重新运行 bootstrap。它会在版本不一致时 refresh
```
~/.claude/harness
```
，在同一次操作中拉取或更新 orca-graph engine 及其 shim，完成 stamp 更新，并且不会将 engine 复制到项目中：

bash

curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/harness/poc-vendor-neutral/bootstrap.sh | bash

在此 layout 中误用

install-harness.sh . --self-heal

时，script 会自动停止并返回 rc 5，同时打印上述准确命令（截至 20/09/2026 的测量结果：旧路径不仅未更新 global，还会将 77 个 script 复制到项目中）。如果 Agent 在带 pty 的 terminal 中运行，请添加

-s -- --with-graph

，以免等待 60 秒的 checklist。

Framework repo（
```
repo_role: framework
```
）：不要在此运行 installer——installer 会自行拒绝并返回 rc 3。更新 framework 的方式是执行
```
git pull
```
。
旧版裸 layout（项目中包含
```
llmwiki/
```
+
```
harness/
```
，但没有 stamp）——使用
```
--self-heal
```
路径（自动检测 migrate/update；缺少源时 clone template）：

bash

test -f harness/scripts/install-harness.sh \
  && bash harness/scripts/install-harness.sh . --self-heal \
  || { git clone -q --depth 1 -b orca git@github.com:rheinmir/setup.git /tmp/llmwiki-tpl \
       && bash /tmp/llmwiki-tpl/harness/scripts/install-harness.sh . --self-heal ; rm -rf /tmp/llmwiki-tpl; }

Installer 会自动完成整个流程：安装 L0–L4 → audit（Origin/index/OKF 通过

audit.py

在同一 process 中合并处理）→ 如果存在待补项，则自动 backfill（Origin 通过一次

git log

批量计算 hash；index 添加缺失的 row；OKF 将加粗的

**Type:**

迁移为 YAML）→ re-audit 1 次 → activate + smoke。

2. 读取 exit code（禁止 re-run 循环——self-heal 已在内部完成）：

```
rc=0
```
→ 干净（已自动 backfill 完成）。进入步骤 3。
```
rc=3
```
→ 仍有 self-heal 无法自动修复的待补项（例如 file conflict、无法推断 OKF type）：列表会直接出现在 output 中。手动修复 1 次，然后再次运行步骤 1。
其他
```
rc
```
（1/4）→ 基础设施错误（network、python3、validator 损坏）——立即停止，原样向 user 报告，不得自行推测处理方式。

3. 验收与 log：

确认步骤 1 的 output 中，“Harness tự kiểm”表显示 ⛔×3 BỊ CHẶN ✓（如果存在 pre-commit，installer 已运行
```
pre-commit install
```
；如果不存在，则提醒 user 执行
```
pipx install pre-commit
```
）。
刷新能力地图（使 agent 在更新后看到正确的工具集合——ADR-005）：
```
python3 ~/.claude/harness/hooks/build-capabilities.py --root .
```
（部署在 hooks 旁的版本）或
```
python3 fdk/tools/build-capabilities.py
```
（如果当前位于 framework repo）→ 重新生成
```
CAPABILITIES.md
```
。如果没有 build-capabilities 文件（旧版本），则跳过且不报错。
Health-check（可选，用于确认更新后哪些护栏仍在生效）：
```
/health-check
```
或
```
python3 ~/.claude/harness/hooks/health-check.py
```
。

追加到

llmwiki/wiki/log.md

：

## YYYY-MM-DD — harness-update — migrate/update xong (--self-heal), nợ đã backfill: <n> file

。数量取自 output 中的

[audit] backfill xong — Origin:<a> index:<b> OKF:<c>

行。

4. 向 user 报告（必须包含完整的 4 点信息）：

已运行的模式（migrate 或 update），以及 self-heal 已 backfill 的待补项数量（Origin/index/OKF 取自
```
[audit] backfill xong
```
行）
Settings root：如果发生 merge，列出备份文件
```
.bak.*
```
提醒：开启新 session 后，新的 hooks 才会加载
邀请使用
```
/harness-tour
```
，直观查看当前有哪些护栏仍在生效

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	recovery	`rc=3`	sửa thủ công 1 lần các nợ self-heal không tự sửa được (danh sách trong output)	vẫn rc=3 → báo user	W01
B02	capability_optional	có `build-capabilities.py` (bản deploy hoặc repo framework)	sinh lại `CAPABILITIES.md`	bản cũ không có → bỏ qua, không lỗi	W03
B03	user_optional	muốn xác nhận rào còn cắn	`/health-check`	bỏ qua	W03

ID	类型	条件	行为	跳过/失败	汇合点
B01	recovery	`rc=3`	手动修复 1 次 self-heal 无法自动处理的待补项（列表位于 output 中）	仍为 rc=3 → 报告 user	W01
B02	capability_optional	存在 `build-capabilities.py` （部署版本或 framework repo）	重新生成 `CAPABILITIES.md`	旧版本没有 → 跳过，不报错	W03
B03	user_optional	希望确认哪些护栏仍在生效	`/health-check`	跳过	W03

Validation và stopping

验证与停止条件

Verdict do rc của installer (tất định) + bảng "Harness tự kiểm" có ⛔×3. Tối đa một vòng B01 → W01; rc khác 0/3 dừng ngay.

Verdict 由 installer 的 rc（确定性）以及“Harness tự kiểm”表中是否存在 ⛔×3 决定。最多允许一个 B01 → W01 循环；遇到 0/3 之外的 rc 时立即停止。

Examples

示例

Positive: dự án có llmwiki cũ thiếu
```
## Origin
```
ở 12 trang →
```
install-harness.sh . --self-heal
```
→
```
[audit] backfill xong — Origin:12 index:0 OKF:0
```
, rc=0 → log + báo cáo "migrate, backfill 12 file, mở session mới để hooks load".
Boundary/failure: máy không có
```
python3
```
→ rc=1 → DỪNG, báo user nguyên văn lỗi, không tự cài hay chạy lại.

正向示例： 项目中的旧版 llmwiki 有 12 个页面缺少
```
## Origin
```
→ 执行
```
install-harness.sh . --self-heal
```
→
```
[audit] backfill xong — Origin:12 index:0 OKF:0
```
，rc=0 → 写入 log 并报告“已迁移，backfill 12 个文件，请开启新 session 以加载 hooks”。
边界/失败示例： 机器没有
```
python3
```
→ rc=1 → 立即停止，原样向 user 报告错误，不得自动安装或重新运行。