health-check

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: health-check

Skill: health-check

WHAT

概述

Purpose và context

目的与上下文

  • Purpose: Trả lời nhanh 3 câu hỏi về bộ "pattern chuẩn" (tập file khai trong
    .template-manifest.json
    ) mà không cần diff tay từng file như
    sync-template
    :
    1. Đủ chưa? — mọi pattern khai báo có mặt trên disk không (MISSING).
    2. Có lệch local? — pattern nào đã bị sửa kể từ lần sync gần nhất (DRIFT).
    3. Cần sync remote? — remote có bản pattern mới hơn không (BEHIND / version cũ).
  • Trigger (when to use):
    • Đầu phiên harness tự chạy (SessionStart hook) — nếu lệch sẽ tự nhắc.
    • Người dùng gọi
      /health-check
      để kiểm thủ công bất cứ lúc nào.
    • Trước khi quyết định có chạy
      /sync-template
      hay không.
  • Non-goals: không tự kéo/đẩy file (đó là
    /sync-template
    — health-check chỉ chẩn đoán), không soi nội dung wiki (broken link, orphan, stale — đó là
    harness/scripts/wiki-health.py
    ).
  • 目的: 快速回答有关“标准 pattern”集合(在
    .template-manifest.json
    中声明的一组文件)的 3 个问题,无需像
    sync-template
    那样逐个手动 diff 文件:
    1. 是否齐全? — 所有声明的 pattern 是否都存在于 disk 上(MISSING)。
    2. local 是否偏移? — 自最近一次 sync 以来,哪些 pattern 已被修改(DRIFT)。
    3. 是否需要从 remote sync? — remote 是否有更新的 pattern 版本(BEHIND / version 较旧)。
  • 触发条件(何时使用):
    • harness 会话开始时自动运行(SessionStart hook)— 如果存在 drift,会自动提示。
    • 用户可随时调用
      /health-check
      手动检查。
    • 在决定是否运行
      /sync-template
      之前。
  • 非目标: 不自动拉取或推送文件(这是
    /sync-template
    的职责——health-check 只负责诊断),也不检查 wiki 内容(broken link、orphan、stale——这些由
    harness/scripts/wiki-health.py
    负责)。

Mental model

心智模型

Cơ chế: 1 file cấu hình duy nhất
harness/version.json
lưu
template_version
+ hash từng pattern. So 3 mốc: disk ↔ version.json (drift), local ↔ remote version.json (behind), manifest ↔ disk (missing). Kết quả mỗi pattern →
OK
·
DRIFT
·
NEEDS-SYNC
→ hành động khuyến nghị.
机制:唯一的配置文件
harness/version.json
保存
template_version
和每个 pattern 的 hash。比较 3 个基准:disk ↔ version.json(drift)、local ↔ remote version.json(behind)、manifest ↔ disk(missing)。每个 pattern 的结果为
OK
·
DRIFT
·
NEEDS-SYNC
→ 推荐对应操作。

Input và output contract

输入与输出约定

FieldRequired?Ý nghĩa
In
.template-manifest.json
+
harness/version.json
cótập pattern + fingerprint; thiếu version.json → báo phần local (fail-open)
In
--branch
/
--offline
/
--json
/
--fail-on
khôngnhánh remote; bỏ fetch; output máy đọc; exit 2 cho gate CI
Outbáo cáo status từng nhóm + dòng OKF v0.1có
OK
/
DRIFT
/
NEEDS-SYNC
+
✓ OKF v0.1: N/N …
Outexit codekhi
--fail-on
2 nếu nhóm chỉ định vi phạm
Out
harness/version.json
đã refresh
chỉ khi
--update
sau sync
hash khớp disk
字段必填?含义
输入
.template-manifest.json
+
harness/version.json
是pattern 集合与 fingerprint;缺少 version.json 时报告 local 部分(fail-open)
输入
--branch
/
--offline
/
--json
/
--fail-on
否remote 分支;跳过 fetch;机器可读输出;为 CI gate 设置 exit 2
输出按组划分的 status 报告 + OKF v0.1 行是
OK
/
DRIFT
/
NEEDS-SYNC
+
✓ OKF v0.1: N/N …
输出exit code使用
--fail-on
时
指定组违规时返回 2
输出已刷新的
harness/version.json
仅在 sync 后使用
--update
时
hash 与 disk 匹配

Rules và capabilities

规则与能力

  • RULE-01 (MUST): Fail-open tuyệt đối: lỗi mạng / thiếu version.json → báo cáo phần local, KHÔNG chặn phiên.
  • RULE-02 (MUST):
    harness/version.json
    là nguồn sự thật duy nhất cho version — không hardcode version ở chỗ khác.
  • RULE-03 (MUST): Pattern set =
    includes
    trong
    .template-manifest.json
    , TRỪ
    harness/version.json
    và các file "sống" theo project (
    index.md
    ,
    log.md
    ,
    active-context.md
    ,
    decisions.md
    ) — chúng được seed nhưng không tính drift.
  • RULE-04 (MUST):
    --bump
    chỉ ở repo template; project con chỉ
    --update
    .
  • RULE-05 (MUST): Thêm pattern mới: add vào
    .template-manifest.json
    includes
    TRƯỚC, rồi
    --update
    .
  • Capabilities: đọc disk + manifest + version.json cục bộ; đọc version.json remote (tuỳ chọn, có thể offline); ghi version.json chỉ khi
    --update
    .
  • RULE-01(MUST):必须绝对 fail-open:网络错误或缺少 version.json 时,报告 local 部分,不得阻止会话。
  • RULE-02(MUST):
    harness/version.json
    是 version 的唯一事实来源——不得在其他位置 hardcode version。
  • RULE-03(MUST):Pattern 集合 =
    .template-manifest.json
    中的
    includes
    ,减去
    harness/version.json
    和各 project 的“动态”文件(
    index.md
    、
    log.md
    、
    active-context.md
    、
    decisions.md
    )——这些文件会被 seed,但不计入 drift。
  • RULE-04(MUST):
    --bump
    只能在模板 repo 中使用;子 project 只能使用
    --update
    。
  • RULE-05(MUST):添加新 pattern 时:先将 pattern 添加到
    .template-manifest.json
    的
    includes
    中,然后运行
    --update
    。
  • 能力:读取 disk、本地 manifest 和 version.json;可选读取 remote version.json(可使用 offline 模式);仅在使用
    --update
    时写入 version.json。

Failure boundaries

失败边界

  • Mạng lỗi / remote không với tới → báo phần local, partial, không chặn (RULE-01).
  • Thiếu
    harness/version.json
    → báo phần kiểm được, không chặn.
  • --fail-on
    gặp nhóm vi phạm → failed (exit 2) cho gate CI.
  • DRIFT không rõ là cải tiến hay lỡ tay → clarify với user trước khi upstream hay revert.
  • 网络错误或无法访问 remote → 报告 local 部分,结果标记为 partial,不得阻止会话(RULE-01)。
  • 缺少
    harness/version.json
    → 报告可检查的部分,不得阻止会话。
  • --fail-on
    遇到指定组违规 → 状态为 failed(exit 2),用于 CI gate。
  • 无法确定 DRIFT 是有意改进还是误修改 → 在执行 upstream 或 revert 之前,先向用户 clarify。

HOW

操作指南

Main workflow

主工作流

StepTypeInputsActionOutputs/exitFailure/next
W01deterministicrepo, nhánhChạy báo cáo
harness/scripts/health-check.py
(có/không remote)
bảng status + dòng OKFoffline → B01
W02judgmentbáo cáoĐọc kết quả theo bảng statushành động khuyến nghị
OK
→ xong
W03effectkhuyến nghịHành động:
/sync-template
downstream/upstream hoặc
git checkout -- <file>
pattern đã đồng bộ/revertDRIFT mơ hồ → clarify
W04effectsau syncRefresh fingerprint
--update
(bump chỉ repo template, B02)
version.json khớp disk—
Chi tiết từng bước (nguồn chân lý cho W01–W04):
步骤类型输入操作输出/退出状态失败/下一步
W01deterministicrepo、分支运行
harness/scripts/health-check.py
报告(可访问或跳过 remote)
status 表 + OKF 行offline → B01
W02judgment报告根据 status 表读取结果推荐操作
OK
→ 完成
W03effect推荐操作执行操作:downstream/upstream
/sync-template
或
git checkout -- <file>
pattern 已同步或 revertDRIFT 含义不明确 → clarify
W04effectsync 后刷新 fingerprint:
--update
(仅模板 repo 可 bump,B02)
version.json 与 disk 匹配—
各步骤详情(W01–W04 的事实来源):

1. Chạy báo cáo (đối chiếu cả remote)

1. 运行报告(同时对比 remote)

bash
python3 harness/scripts/health-check.py --root . --branch orca
  • --offline
    : chỉ kiểm local (bỏ fetch remote) khi không có mạng.
  • --json
    : output máy đọc (dùng cho hook / CI).
  • --fail-on behind,drift,missing
    : exit 2 nếu nhóm chỉ định vi phạm (dùng cho gate CI).
bash
python3 harness/scripts/health-check.py --root . --branch orca
  • --offline
    :无网络时仅检查 local(跳过 fetch remote)。
  • --json
    :输出机器可读格式(用于 hook / CI)。
  • --fail-on behind,drift,missing
    :指定组违规时返回 exit 2(用于 CI gate)。

2. Đọc kết quả

2. 读取结果

statusnghĩahành động
OK
pattern đủ + khớp remotekhông cần làm gì
DRIFT
pattern bị sửa localcân nhắc upstream (
/sync-template
push) hoặc revert
NEEDS-SYNC
thiếu file hoặc remote mới hơnchạy downstream
/sync-template
Báo cáo còn kèm 1 dòng OKF v0.1:
✓ OKF v0.1: N/N concept đạt chuẩn
(mọi concept có YAML frontmatter +
type
) hoặc
⟳ OKF v0.1: x/N … cần migrate
. Đây là câu trả lời nhanh "project đã đạt chuẩn OKF chưa?". Chưa đạt →
python3 harness/scripts/okf-check.py --migrate
.
status含义操作
OK
pattern 齐全且与 remote 匹配无需操作
DRIFT
pattern 在 local 被修改考虑 upstream(
/sync-template
push)或 revert
NEEDS-SYNC
缺少 file 或 remote 版本更新运行 downstream
/sync-template
报告还包含一行 OKF v0.1:
✓ OKF v0.1: N/N concept đạt chuẩn
(所有 concept 都包含 YAML frontmatter +
type
),或
⟳ OKF v0.1: x/N … cần migrate
。这是对“project 是否达到 OKF 标准?”的快速回答。如果尚未达标 →
python3 harness/scripts/okf-check.py --migrate
。

3. Hành động theo khuyến nghị

3. 根据建议执行操作

  • BEHIND / MISSING → gọi
    /sync-template
    (downstream): kéo pattern mới/thiếu về.
  • DRIFT → nếu cải tiến muốn giữ:
    /sync-template
    upstream; nếu lỡ sửa:
    git checkout -- <file>
    .
  • BEHIND / MISSING → 调用
    /sync-template
    (downstream):拉取新的或缺失的 pattern。
  • DRIFT → 如果是希望保留的改进:
    /sync-template
    upstream;如果是误修改:
    git checkout -- <file>
    。

4. Sau khi sync xong — refresh version.json

4. sync 完成后——刷新 version.json

Mỗi lần downstream sync đổi nội dung pattern, cập nhật lại fingerprint:
bash
python3 harness/scripts/health-check.py --update            # giữ nguyên version
python3 harness/scripts/health-check.py --update --bump patch   # khi PHÁT HÀNH bản mới (chỉ làm ở repo template)
--bump
(major/minor/patch) CHỈ chạy ở repo template
Rheinmir/setup
khi muốn công bố version pattern mới cho mọi project. Project con chỉ
--update
(không bump) để đồng bộ hash sau khi pull.
每次 downstream sync 更改 pattern 内容后,重新更新 fingerprint:
bash
python3 harness/scripts/health-check.py --update            # giữ nguyên version
python3 harness/scripts/health-check.py --update --bump patch   # khi PHÁT HÀNH bản mới (chỉ làm ở repo template)
--bump
(major/minor/patch)只能在模板 repo
Rheinmir/setup
中运行,用于向所有 project 发布新的 pattern version。子 project 仅使用
--update
(不 bump),以便在 pull 后同步 hash。

Branches

分支

IDKindGuardHành viSkip / failureRejoin
B01user_optionalkhông có mạng / user muốn chỉ kiểm localthêm
--offline
, bỏ fetch remote
lỗi mạng khi không cờ → vẫn báo phần local (fail-open)W02
B02conditional_requiredđang ở repo template
Rheinmir/setup
và phát hành bản pattern mới
--update --bump patch
(major/minor/patch)
project con → chỉ
--update
kết thúc
B03capability_optionalchạy trong gate CI/hook
--json
và/hoặc
--fail-on behind,drift,missing
—W02 (hoặc exit 2)
ID类型条件行为跳过/失败汇合
B01user_optional无网络或用户只想检查 local添加
--offline
,跳过 fetch remote
未设置该参数但发生网络错误时,仍报告 local 部分(fail-open)W02
B02conditional_required位于模板 repo
Rheinmir/setup
且准备发布新 pattern 版本
--update --bump patch
(major/minor/patch)
子 project → 仅使用
--update
结束
B03capability_optional在 CI gate/hook 中运行使用
--json
和/或
--fail-on behind,drift,missing
—W02(或 exit 2)

Validation và stopping

验证与停止条件

Status do
health-check.py
tính tất định (hash + so version), không do model đoán. Dừng khi status
OK
, hoặc sau khi hành động khuyến nghị xong và
--update
đã đồng bộ hash.
Status 由
health-check.py
确定性计算(hash + version 比较),不是由 model 猜测。当 status 为
OK
时停止,或在完成推荐操作且
--update
已同步 hash 后停止。

Examples

示例

  • Positive: đầu phiên, remote
    orca
    có
    template_version
    mới hơn → báo
    NEEDS-SYNC
    (BEHIND) → gọi
    /sync-template
    downstream →
    python3 harness/scripts/health-check.py --update
    → chạy lại ra
    OK
    .
  • Boundary/failure: máy offline, chạy không
    --offline
    → fetch remote lỗi, vẫn in phần local (DRIFT/MISSING) và không chặn phiên; nhóm BEHIND không xác định được.
  • 正向示例: 会话开始时,remote
    orca
    的
    template_version
    更新 → 报告
    NEEDS-SYNC
    (BEHIND)→ 调用 downstream
    /sync-template
    →
    python3 harness/scripts/health-check.py --update
    → 再次运行得到
    OK
    。
  • 边界/失败: 机器处于 offline 状态且运行时未添加
    --offline
    → fetch remote 失败,仍会输出 local 部分(DRIFT/MISSING),且不会阻止会话;无法确定 BEHIND 组的状态。

Reference — Quan hệ với skill khác

参考——与其他 skill 的关系

  • [[sync-template]] — health-check chẩn đoán (có cần sync không); sync-template thực thi (kéo/đẩy file). Luôn chạy health-check trước, sync-template sau.
  • harness/scripts/wiki-health.py
    — anh em cùng tầng L4 nhưng soi nội dung wiki (broken link, orphan, stale), không soi version pattern.
  • [[sync-template]] — health-check 负责诊断(是否需要 sync);sync-template 负责执行(拉取/推送文件)。始终先运行 health-check,再运行 sync-template。
  • harness/scripts/wiki-health.py
    — 同属 L4 层的兄弟工具,但负责检查 wiki 内容(broken link、orphan、stale),不检查 pattern version。

Origin

来源

  • Draft:
    llmwiki/wiki/sources/draft/150626-health-check-pattern-sync.md
  • Draft:
    llmwiki/wiki/sources/draft/150626-health-check-pattern-sync.md