Back to Details

lint

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: lint

Skill: lint

WHAT

概述

Purpose và context

目的与上下文

  • Purpose: Periodic wiki health check — orphans, missing links, contradictions, stale (wiki→wiki VÀ code→wiki drift), index gaps; mở đầu bằng cổng no-op tất định (wiki-sync, 0 token).
  • Trigger (when to invoke): After every 10 ingests, or when wiki stale/inconsistent, hoặc session_start báo 
    [wiki-sync] code đã đổi N commit
    .
  • Non-goals: không chọn phe khi hai trang mâu thuẫn (flag cho người); không tự đoán trigger nâng cấp cho marker 
    shortcut:
    ; không tự dời draft (đó là 
    /tidy
    , có gate người duyệt); không sửa lấy có khi wiki đã current.
  • 目的： 周期性 wiki 健康检查——孤立页面、缺失链接、矛盾、陈旧内容（wiki→wiki 以及 code→wiki drift）、索引缺口；以确定性的 no-op 门禁（wiki-sync，0 token）作为起点。
  • 触发条件（何时调用）： 每完成 10 次 ingest 后，或 wiki 陈旧/不一致时，或 session_start 报告 
    [wiki-sync] code đã đổi N commit
    时。
  • 非目标： 当两页互相矛盾时不替用户选边（标记后交由人工处理）；不自行推断 
    shortcut:
    marker 的升级触发条件；不自行移动 draft（这属于 
    /tidy
    ，需经过人工审批门禁）；wiki 已 current 时不做顺手修改。

Mental model

心智模型

wiki-sync --check (0 current · 3 drift · 2 chưa neo) → [hồ sơ cờ ⚑: events → scratch-log → provenance-log] → [docs-impact-plan + phân loại drift 4 nhánh] → quét nội-wiki (orphan · link · contradiction · stale · index · empty · Origin) → pulse báo-cáo-không-chặn (shortcut · unknown · skill-health · usage · tidy · claim-receipts · decision-liveness) → log → chốt neo
.
wiki-sync --check (0 current · 3 drift · 2 尚无 neo) → [⚑ 标记档案: events → scratch-log → provenance-log] → [docs-impact-plan + drift 四分支分类] → wiki 内扫描 (orphan · link · contradiction · stale · index · empty · Origin) → pulse 非阻塞报告 (shortcut · unknown · skill-health · usage · tidy · claim-receipts · decision-liveness) → log → 锁定 neo

Input và output contract

输入输出约定

FieldRequired?Ý nghĩa
In
llmwiki/wiki/
+ neo wiki-sync		cóneo mất → exit 2, làm trọn rồi chốt neo
In
harness/scripts/*
(hoặc bản global 
~/.claude/harness/harness/scripts/
)		códownstream không có harness/ trong repo dùng bản global
In
fdk/tools/skill-usage.py
khôngchỉ repo framework; downstream bỏ qua bước đó
Outsửa tại chỗ: missing links, index gaps; trang stale sửa surgicaltheo kết quảtruy về một thay-đổi-code cụ thể
Outdanh sách flag (contradiction, orphan, empty, Origin thiếu, pulse)cóchờ người quyết
Outdòng 
## YYYY-MM-DD — lint
trong 
llmwiki/wiki/log.md
+ neo mới		cókể cả khi no-op
Outdraft output reportcó (trừ khi 0 artifact)mục Delivery
字段是否必填含义
In
llmwiki/wiki/
+ neo wiki-sync		是neo 缺失 → exit 2；完成全部检查后锁定 neo
In
harness/scripts/*
（或全局版本 
~/.claude/harness/harness/scripts/
）		是下游仓库没有 harness/ 时使用全局版本
In
fdk/tools/skill-usage.py
否仅适用于 framework 仓库；下游仓库跳过此步骤
Out原地修复：missing links、index gaps；陈旧页面进行 surgical 更新视结果而定必须可追溯到具体的代码变更
Out标记列表（contradiction、orphan、empty、缺少 Origin、pulse）是等待人工决定
Out
llmwiki/wiki/log.md
中的 
## YYYY-MM-DD — lint
行及新 neo		是即使执行 no-op 也必须记录
Outdraft 输出报告是（除非没有 artifact）属于 Delivery 部分

Rules và capabilities

规则与能力

  • RULE-01 (MUST): Fix automatically: missing links (step 2), index gaps (step 5).
  • RULE-02 (MUST): Flag, not resolve: contradictions, orphans, empty pages — need human decision.
  • RULE-03 (MUST): Surgical update (distill openwiki 060726): sửa trang stale = thay đúng câu sai, KHÔNG viết lại trang còn đúng; ưu tiên sửa 1 câu hơn thêm 1 đoạn.
  • RULE-04 (MUST): Soft diff budget: <5 file code đổi → sửa tối đa 1–2 trang wiki; thấy cần sửa >3 trang → dừng lại tự vấn vì sao trước khi sửa rộng.
  • RULE-05 (MUST): Cấm formatting-only edit: không reformat bảng, không chuẩn hoá dòng trống/wording khi nội dung xung quanh không sai — diff nhiễu là nợ cho reviewer.
  • RULE-06 (MUST): Canonical home: mỗi concept một trang chính chủ; trang khác chỉ nhắc ngắn + 
    [[wikilink]]
    , không nhân bản giải thích.
  • RULE-07 (MUST): No-op hợp lệ: "wiki đã current, không sửa gì" là một kết quả lint thành công — ghi log rồi dừng, đừng sửa lấy có.
  • Capabilities: đọc wiki + metrics cục bộ; chạy script tất định 0-token; ghi trang wiki (surgical), index, log, neo sync.
  • RULE-01 (MUST)：自动修复 missing links（步骤 2）和 index gaps（步骤 5）。
  • RULE-02 (MUST)：仅标记、不解决 contradictions、orphans、empty pages——这些问题需要人工决定。
  • RULE-03 (MUST)：Surgical update（提炼自 openwiki 060726）：修复陈旧页面 = 精确替换错误句子，不要重写仍然正确的页面；优先只修改 1 句，而不是再增加 1 段。
  • RULE-04 (MUST)：Soft diff budget：改动的代码文件数 < 5 → 最多修改 1–2 个 wiki 页面；发现需要修改 > 3 个页面 → 广泛修改前先停下来思考原因。
  • RULE-05 (MUST)：禁止仅格式化编辑：不重新格式化表格，不在周围内容没有错误时统一空行或措辞——噪声 diff 是 reviewer 的负担。
  • RULE-06 (MUST)：Canonical home：每个 concept 只有一个主页面；其他页面只做简短提及并附加 
    [[wikilink]]
    ，不重复复制解释。
  • RULE-07 (MUST)：合理的 no-op：“wiki 已 current，无需修改”是 lint 成功的结果——记录日志后停止，不要顺手修改。
  • Capabilities：读取 wiki 和本地 metrics；运行确定性的 0-token 脚本；以 surgical 方式写入 wiki 页面，并更新 index、log 和 neo sync。

Failure boundaries

失败边界

  • Exit 0 và mục đích là "wiki có khớp code không" → dừng sớm, succeeded (no-op hợp lệ).
  • Trang nghi stale không truy được về thay đổi code nào → KHÔNG đụng.
  • Cần sửa >3 trang cho <5 file code đổi → dừng lại tự vấn trước khi sửa rộng (clarify).
  • Contradiction → flag cho người, không tự chọn winner.
  • Hồ sơ why rỗng → ghi "hồ sơ mỏng, cần mở diff" thay vì im.
  • Exit 0，且本次目的是确认“wiki 是否与代码一致” → 提前停止，succeeded（合理的 no-op）。
  • 疑似陈旧的页面无法追溯到任何代码变更 → 不得修改。
  • 代码变更文件数 < 5，却需要修改 > 3 个页面 → 广泛修改前先停下来思考（clarify）。
  • Contradiction → 标记给人工处理，不自行选择 winner。
  • why 记录为空 → 写入“依据薄弱，需要打开 diff”，而不是保持沉默。

HOW

执行方式

Main workflow

主工作流

StepTypeInputsActionOutputs/exitFailure/next
W01deterministicneo wiki-syncBước 0: 
wiki-sync.py --check
exit 0 / 3 / 20 + mục đích khớp-code → dừng; 3 → B01; 2 → B02
W02deterministicfile code "⇐"Bước 0b + 8f: hồ sơ cờ ⚑ (events, scratch-log, provenance-log)
phiên · ts · why
why rỗng → ghi "hồ sơ mỏng"
W03deterministicwikiBước 1–7: orphans, missing links, contradictions, stale, index, empty, Originsửa 2 và 5, flag phần còn lại—
W04deterministicrepoBước 8–8f: pulse báo cáo không chặndanh sách flagscript/đường dẫn không có → bỏ qua bước đó
W05effectkết quảBước 9: append logdòng log—
W06effectwiki đã ràBước 10: 
wiki-sync.py --mark-synced
neo mớinội dung không đổi → không ghi
W07effectkết quảOutput report draft (mục Delivery)draft + index + log0 artifact → skip
Chi tiết từng bước (nguồn chân lý cho W01–W07):
  1. Code-drift gate (0 token) — 
    RUN: python3 harness/scripts/wiki-sync.py --check
    (downstream không có harness/ trong repo thì dùng bản global: 
    python3 ~/.claude/harness/harness/scripts/wiki-sync.py --check --root .
    ).
0b. Hồ sơ cho từng cờ ⚑ (0 token — JOIN bộ nhớ thứ cấp 2 bước, wired 2026-07-18): với MỖI file code mà bước 0 báo "⇐" (nguyên nhân trang nghi stale):
  • Bước 1 — PHIÊN NÀO chạm (kho dày, file-level): 
    RUN: grep "<tên-file>" harness/metrics/events.jsonl | tail -3
    → lấy 
    session
    + 
    ts
    .
  • Bước 2 — VÌ SAO (why của phiên đó): 
    RUN: grep "<session-id-8-ký-tự>" harness/metrics/scratch-log.jsonl | tail -2
    . Đính 
    phiên · ts · why
    vào cờ khi báo user — cờ-có-hồ-sơ phán trong vài giây (đọc why đủ biết thay đổi có vô hiệu claim không), cờ-trần phải mò diff. Why rỗng/auto-đúc-từ-commit → ghi chú "hồ sơ mỏng, cần mở diff" thay vì im. (Giới hạn thật: scratch-log 1 why/phiên; events dày nhưng chỉ có path — độ giàu why phụ thuộc phiên có ghi tay không.)
  • Exit 0 (
    current
    ): code không đổi kể từ neo → nếu mục đích lượt lint này là "wiki có khớp code không" thì dừng tại đây, trả lời "wiki đã current" — no-op là kết quả tốt, đừng bịa việc. Vẫn muốn quét sức khoẻ nội-wiki (orphan/index/origin) thì đi tiếp bước 1.
  • Exit 3 (
    drift
    ): các trang nghi stale đã được cờ 
    code-drift
    trong 
    stale.json
    kèm file code gây ra. Lập docs-impact-plan TRƯỚC khi sửa: mỗi trang định sửa phải truy về một thay-đổi-code cụ thể (
    code đổi → trang → sửa gì → vì sao
    ); trang không truy được về thay đổi nào thì KHÔNG đụng.
    • Phân loại drift trước khi sửa (rubric 4 nhánh, mượn ý temporal-invalidation từ RedPlanetHQ/core, github.com/RedPlanetHQ/core 
      prompts/statements.ts
      )      : claim cũ và thực tế mới quan hệ với nhau kiểu gì?
      • contradiction — hai claim không thể cùng đúng (vd "API dùng key X" khi key đã đổi tên) → claim cũ SAI, sửa đè bình thường.
      • superseding — claim cũ TỪNG đúng, nay hết hiệu lực vì đổi kiến trúc (vd đổi engine/refactor) → đừng sửa đè câm lặng: thêm 2 trường vào frontmatter của trang — 
        invalid_at: YYYY-MM-DD
        + 
        invalidated_by: <commit-sha hoặc file gây invalidate>
        — rồi mới cập nhật nội dung. Trang vẫn giữ 1 dòng ngắn nói claim cũ từng đúng tới khi nào (đừng xoá lịch sử, chỉ đóng dấu).
      • progression — cả hai đều đúng, khác giai đoạn (vd "đang thiết kế X" → "đã ship X") → giữ cả hai, KHÔNG invalidate, chỉ nối thêm claim mới.
      • equivalence — cùng nghĩa khác lời (do ingest 2 lần) → coi là trùng lặp, gộp về 1 câu, không phải drift thật.
      • Field 
        invalid_at
        /
        invalidated_by
        là optional, R9 (okf_frontmatter) không chặn khoá lạ — an toàn thêm mà không cần sửa validator.
  • Exit 2 (chưa có neo / neo mất hiệu lực): làm trọn lint rồi chốt neo ở bước 10.
  1. Orphans — 
    RUN: grep -rL "wiki/" --include="*.md" llmwiki/wiki/concepts/ llmwiki/wiki/entities/
    → files not referenced anywhere. Flag each.
  2. Missing links — scan pages for entity/concept names that exist as wiki files but not written as 
    [[wikilinks]]
    . Fix in place.
  3. Contradictions — compare claims about same entity across ≤2 pages at a time. Flag pairs (file:line vs file:line). Do NOT pick winner — flag for human review.
  4. Stale claims — 
    RUN: grep -rl "raw/" --include="*.md" llmwiki/wiki/
    → pages referencing raw/. Flag each.
  5. Index gaps — 
    RUN: comm -23 <(find llmwiki/wiki -name "*.md" | sort) <(grep -o "llmwiki/wiki/[^)]*" llmwiki/wiki/index.md | sort)
    → files missing from index. Add rows.
  6. Empty pages — 
    RUN: for f in llmwiki/wiki/**/*.md; do [ $(wc -l < "$f") -lt 5 ] && echo "$f"; done
    → flag for deletion or content.
  7. Missing Origin — 
    RUN: grep -rL "## Origin" llmwiki/wiki/concepts/ llmwiki/wiki/entities/
    → flag each as incomplete.
  8. Marker nợ thiếu trigger — 
    RUN: grep -rn "shortcut:" --include="*.py" --include="*.js" --include="*.ts" --include="*.sh" . | grep -v ",";
    → mỗi marker 
    shortcut:
    cố ý phải có định dạng 
    <trần hiện tại>, <trigger nâng cấp>
    (dấu phẩy tách 2 vế). Dòng lọt qua grep này = marker thiếu trigger nâng cấp (nợ không hạn → dễ thành "never"). Flag từng dòng cho người viết bổ sung trigger; KHÔNG tự đoán trigger.
8c. Nợ unknown (fill-first, chờ verify — tất định, 0 token) — 
RUN: python3 harness/scripts/unknown-ledger.py --list
→ in số unknown mở + cái cũ nhất + SPEC nào nhiều nợ nhất. Đây là các default model điền "để việc chạy tiếp, tính sau" (
(default, find-out-later)
). BÁO CÁO, KHÔNG CHẶN — fill-first cố ý không chặn; chặn ở đây là phản bội cơ chế. Mục đích: nợ hiện ra để không chìm, người duyệt tự quyết khi nào trả (xem 
[[150726-unknown-ledger]]
).
8b. Skill-health (hình dạng skill, tất định — 0 token) — 
RUN: python3 harness/scripts/skill-health.py
(repo có 
skills/
) → in tổng context load model-invoked + skill nào có cờ: 
desc
(description quá dài) · 
sprawl
(SKILL.md quá dài mà không progressive disclosure) · 
negation
(tỉ lệ câu cấm cao — nên chuyển sang câu khẳng định) · 
weak-criterion
(khối 
### Task
thiếu điều kiện kiểm được ở cuối) · cặp description chớm-trùng. Tiêu chí gốc ở 
[[skill-craft]]
. Báo cáo, KHÔNG chặn — chất lượng, không phải an toàn. Flag để người viết cân nhắc, đừng tự sửa hàng loạt.
8b. Skill-usage pulse (0 token, chỉ repo framework) — 
RUN: python3 fdk/tools/skill-usage.py --weekly --no-html
→ bảng tần suất tuần + skill chết (idle ≥4 tuần). Đây là dây nuôi máy đo "skill nào đáng giữ" (wired 2026-07-18, vòng grower): usage tụt/chết là DỮ KIỆN cho quyết định cắt-giữ, không phải cảm tính. Downstream không có 
fdk/tools
→ bỏ qua bước này.
8c. Docs-sprawl pulse (0 token) — 
RUN: python3 harness/scripts/tidy.py check
→ exit 3 khi draft tầng gốc > 10 → báo user gợi ý chạy 
/tidy
(apply dời vào 
archive/
+ reindex — có gate người duyệt, tool không tự dời khi lint). Draft/html là RENDER ephemeral; để phình là chôn bản chất dưới rác — vòng đời phải có người quét theo nhịp (wired 2026-07-18).
8d. Claim-receipts trên draft ACTIVE (0 token) — với mỗi draft KEEP/TREO (không rà đồ sắp archive): 
RUN: python3 harness/scripts/claim-receipts.py --check <draft>
→ trích mọi file/path văn bản TRÍCH DẪN, verify còn resolve trên đĩa. Unresolved = bằng chứng tất định nội-dung-outdated (trỏ tới thứ đã chết/đổi tên) — flag kèm danh sách ref chết, người quyết sửa-hay-archive. Advisory (adapter 
claim-receipts.config.yaml
verified:false) — không chặn, chỉ soi (wired 2026-07-18, ca unwired thứ 7).
8e. Decision-anchoring liveness (0 token, tất định) — 
RUN: python3 harness/scripts/decision-liveness.py check
(downstream không có 
harness/
trong repo thì dùng bản global: 
python3 ~/.claude/harness/harness/scripts/decision-liveness.py check
; repo không có 
harness/mechanisms.yaml
→ bỏ qua bước này). In mọi mục có 
anchor_symbol
/
live_probe
kèm nhãn 
LIVE
/
STALE
/
ORPHAN
/
UNAVAILABLE
— người duyệt phân biệt ORPHAN (cần sửa neo hoặc xoá quyết định qua 
status: retired
, KHÔNG xoá vật lý) với STALE (cần đọc lại, có thể vẫn đúng) chỉ bằng nhãn, không phải đọc lại toàn bộ nội dung (SC-005). BÁO CÁO, KHÔNG CHẶN — khớp khuôn không-chặn của draft-age/unknown-ledger (bước 8c).
8f. Provenance-log lookup (0 token, tất định) — với mỗi file/quyết định bước 0b đang xét "vì sao đổi": 
RUN: grep "<tên-file-hoặc-id>" harness/metrics/provenance-log.jsonl | tail -5
(downstream dùng bản global tương tự bước 0). Mỗi dòng khớp mang 
writer_id
/
topic
/
ts_utc
(UTC tường minh)/
git_sha
— nguồn "vì sao" THỨ HAI cạnh 
events.jsonl
/
scratch-log.jsonl
ở bước 0b, khác biệt quan trọng: git-tracked, đi theo được khi clone sang máy khác (2 nguồn kia hoặc gitignored-local hoặc không tự động toàn diện — xem 
[[log-model]]
). Dùng làm CLUE bổ sung, không thay thế bước 0b. BÁO CÁO, KHÔNG CHẶN.
  1. Append to 
    llmwiki/wiki/log.md
    : 
    ## YYYY-MM-DD — lint
    with issues found/fixed vs flagged.
  2. Chốt neo — 
    RUN: python3 harness/scripts/wiki-sync.py --mark-synced
    (hoặc bản global như bước 0). Chỉ ghi khi nội dung wiki thực sự đổi (content-hash); tự xoá cờ 
    code-drift
    đã rà. Vòng phản hồi phải khép: không chốt neo = lần check sau báo drift giả.
步骤类型输入操作输出/exit失败/下一步
W01确定性neo wiki-sync步骤 0：
wiki-sync.py --check
exit 0 / 3 / 20 且目的是检查代码一致性 → 停止；3 → B01；2 → B02
W02确定性标记为“⇐”的代码文件步骤 0b + 8f：⚑ 标记档案（events、scratch-log、provenance-log）
session · ts · why
why 为空 → 写入“依据薄弱”
W03确定性wiki步骤 1–7：orphans、missing links、contradictions、stale、index、empty、Origin修复步骤 2 和 5，其余进行标记—
W04确定性repo步骤 8–8f：执行非阻塞 pulse 报告标记列表脚本或路径不存在 → 跳过该步骤
W05有副作用结果步骤 9：追加日志日志行—
W06有副作用已检查的 wiki步骤 10：
wiki-sync.py --mark-synced
新 neo内容未变化 → 不写入
W07有副作用结果输出 draft 报告（Delivery 部分）draft + index + log0 artifact → 跳过
各步骤详情（W01–W07 的唯一事实来源）：
  1. Code-drift 门禁（0 token） — 
    RUN: python3 harness/scripts/wiki-sync.py --check
    （下游仓库没有 harness/ 时，使用全局版本：
    python3 ~/.claude/harness/harness/scripts/wiki-sync.py --check --root .
    ）。
0b. 每个 ⚑ 标记的依据记录（0 token——连接二级记忆，分 2 步，已接入于 2026-07-18）： 对于步骤 0 报告“⇐”的每一个代码文件（页面被怀疑陈旧的原因）：
  • 步骤 1——是哪个会话触及了该文件（稠密存储，文件级）：
    RUN: grep "<tên-file>" harness/metrics/events.jsonl | tail -3
    → 获取 
    session
    + 
    ts
    。
  • 步骤 2——为什么变更（该会话的 why）：
    RUN: grep "<session-id-8-ký-tự>" harness/metrics/scratch-log.jsonl | tail -2
    。 向用户报告时，将 
    session · ts · why
    附加到标记上——有依据的标记几秒内即可判断（读取 why 已足以确定变更是否使 claim 失效），没有依据的标记则必须追查 diff。Why 为空或由 commit 自动生成时，写入“依据薄弱，需要打开 diff”，而不是保持沉默。（实际限制：scratch-log 每个会话只有一条 why；events 虽稠密但仅包含 path——why 的丰富程度取决于会话是否留下手写记录。）
  • Exit 0（
    current
    ）：自 neo 以来代码未发生变化 → 如果本次 lint 的目的是确认“wiki 是否与代码一致”，则停在这里并回答“wiki 已 current”——no-op 是良好结果，不要编造工作。如果仍希望扫描 wiki 内部健康状况（orphan/index/origin），则继续步骤 1。
  • Exit 3（
    drift
    ）：疑似陈旧的页面已在 
    stale.json
    中标记为 
    code-drift
    ，并附带导致漂移的代码文件。修改前先制定 docs-impact-plan：每个待修改页面都必须追溯到一项具体代码变更（
    代码变更 → 页面 → 修改内容 → 原因
    ）；无法追溯到任何变更的页面不得修改。
    • 修改前先对 drift 分类（四分支 rubric，借鉴 RedPlanetHQ/core、github.com/RedPlanetHQ/core 
      prompts/statements.ts
      中的 temporal-invalidation 思路）：       旧 claim 与新事实之间是什么关系？
      • contradiction——两个 claim 不可能同时成立（例如，密钥改名后仍写着“API 使用 key X”）→ 旧 claim 错误，正常覆盖即可。
      • superseding——旧 claim 曾经正确，但因架构变化而失效（例如更换 engine 或 refactor）→ 不要静默覆盖：先在页面 frontmatter 中添加两个字段——
        invalid_at: YYYY-MM-DD
        + 
        invalidated_by: <commit-sha hoặc file gây invalidate>
        ——然后再更新正文。页面仍保留一行简短说明，指出旧 claim 曾经正确到何时（不要删除历史，只需打上失效标记）。
      • progression——两者都正确，但处于不同阶段（例如从“正在设计 X”变为“已经交付 X”）→ 保留两者，不进行 invalidate，只追加新 claim。
      • equivalence——含义相同但措辞不同（例如重复 ingest 两次）→ 视为重复内容，合并为一句话，不属于真正的 drift。
      • invalid_at
        /
        invalidated_by
        字段是可选的，R9（okf_frontmatter）不会拦截异常键，因此可以安全添加，无需修改 validator。
  • Exit 2（尚无 neo / neo 已失效）：完成全部 lint，并在步骤 10 锁定 neo。
  1. Orphans — 
    RUN: grep -rL "wiki/" --include="*.md" llmwiki/wiki/concepts/ llmwiki/wiki/entities/
    → 未在任何地方被引用的文件。逐一标记。
  2. Missing links — 扫描页面，查找已作为 wiki 文件存在、但尚未写成 
    [[wikilinks]]
    的 entity/concept 名称。原地修复。
  3. Contradictions — 每次最多比较两个页面中关于同一 entity 的 claim。标记对应内容对（file:line vs file:line）。不要选择 winner——标记后交由人工审核。
  4. Stale claims — 
    RUN: grep -rl "raw/" --include="*.md" llmwiki/wiki/
    → 引用了 raw/ 的页面。逐一标记。
  5. Index gaps — 
    RUN: comm -23 <(find llmwiki/wiki -name "*.md" | sort) <(grep -o "llmwiki/wiki/[^)]*" llmwiki/wiki/index.md | sort)
    → 未出现在 index 中的文件。添加对应行。
  6. Empty pages — 
    RUN: for f in llmwiki/wiki/**/*.md; do [ $(wc -l < "$f") -lt 5 ] && echo "$f"; done
    → 标记为待删除或待补充内容。
  7. Missing Origin — 
    RUN: grep -rL "## Origin" llmwiki/wiki/concepts/ llmwiki/wiki/entities/
    → 逐一标记为不完整。
  8. Marker 债务缺少升级触发条件 — 
    RUN: grep -rn "shortcut:" --include="*.py" --include="*.js" --include="*.ts" --include="*.sh" . | grep -v ",";
    → 每个有意设置的 
    shortcut:
    marker 都必须采用 
    <trần hiện tại>, <trigger nâng cấp>
    格式（逗号分隔两部分）。通过该 grep 的行 = marker 缺少升级触发条件（无限期债务，容易变成“never”）。逐行标记，交由作者补充触发条件；不要自行推断。
8c. Unknown 债务（fill-first，等待 verify——确定性，0 token） — 
RUN: python3 harness/scripts/unknown-ledger.py --list
→ 输出尚未处理的 unknown 数量、最早的一项，以及债务最多的 SPEC。这些是 default model 为了“让工作继续推进，细节以后再算”而填写的值（
(default, find-out-later)
）。只报告，不阻塞——fill-first 有意不设阻塞；在这里阻塞将背离该机制的设计目的。其目的是让债务清晰可见，不至于被遗忘，由审批者决定何时偿还（参见 
[[150726-unknown-ledger]]
）。
8b. Skill-health（skill 结构检查，确定性——0 token） — 
RUN: python3 harness/scripts/skill-health.py
（仓库中有 
skills/
时执行）→ 输出 model-invoked 的上下文加载总量，以及存在以下标记的 skill：
desc
（description 过长）· 
sprawl
（SKILL.md 过长且缺少 progressive disclosure）· 
negation
（禁止性语句比例过高——应改为肯定式表述）· 
weak-criterion
（末尾的 
### Task
块缺少可测试条件）· description 近似重复的组合。原始标准见 
[[skill-craft]]
。只报告，不阻塞——这是质量问题，不是安全问题。标记后供作者考虑，不要批量自行修改。
8b. Skill-usage pulse（0 token，仅适用于 framework 仓库） — 
RUN: python3 fdk/tools/skill-usage.py --weekly --no-html
→ 输出每周频率表和闲置至少 4 周的失效 skill。这是衡量“哪些 skill 值得保留”的机器数据管线（已接入 2026-07-18，grower 循环）：使用量下降或 skill 失效是决定保留或裁剪的数据，不是主观感受。下游仓库没有 
fdk/tools
→ 跳过此步骤。
8c. Docs-sprawl pulse（0 token） — 
RUN: python3 harness/scripts/tidy.py check
→ 当底层 draft 超过 10 个时 exit 3 → 向用户建议运行 
/tidy
（apply 会将内容移至 
archive/
并重新索引——设有审批门禁，lint 期间工具不会自行移动）。Draft/html 属于 ephemeral RENDER；任由其膨胀，就是把本质埋进垃圾堆——其生命周期需要定期的人工清理（已接入 2026-07-18）。
8d. ACTIVE draft 上的 Claim-receipts（0 token） — 对每个 KEEP/TREO、尚未审查是否应归档的 draft：
RUN: python3 harness/scripts/claim-receipts.py --check <draft>
→ 提取文本中引用的每个 file/path，并验证其是否仍能在磁盘上解析。Unresolved = 确定性的 content-outdated 证据（指向已删除或已改名的内容）——连同失效引用列表一起标记，由用户决定修复还是归档。Advisory（adapter 
claim-receipts.config.yaml
verified:false）——不阻塞，只进行检查（已接入 2026-07-18；周六那次未接入）。
8e. Decision-anchoring liveness（0 token，确定性） — 
RUN: python3 harness/scripts/decision-liveness.py check
（下游仓库没有 
harness/
时，使用全局版本：
python3 ~/.claude/harness/harness/scripts/decision-liveness.py check
；仓库没有 
harness/mechanisms.yaml
→ 跳过此步骤）。输出所有包含 
anchor_symbol
/
live_probe
的条目及其 
LIVE
/
STALE
/
ORPHAN
/
UNAVAILABLE
标签——审批者无需重读全部内容（SC-005），只需根据标签区分 ORPHAN（需要修复锚点，或通过 
status: retired
退役该决定，不要物理删除）与 STALE（需要重新审阅，仍有可能保持正确）。只报告，不阻塞——与 draft-age/unknown-ledger 的非阻塞模式一致（步骤 8c）。
8f. Provenance-log lookup（0 token，确定性） — 对于步骤 0b 正在审查“为什么变更”的每个文件或决定：
RUN: grep "<tên-file-hoặc-id>" harness/metrics/provenance-log.jsonl | tail -5
（下游仓库使用与步骤 0 相同的全局版本）。每个匹配行都包含 
writer_id
/
topic
/
ts_utc
（明确使用 UTC）/
git_sha
——这是紧邻步骤 0b 中 
events.jsonl
/
scratch-log.jsonl
的第二个“为什么变更”来源，区别非常重要：它受 git 跟踪，克隆到其他机器后仍可随仓库迁移（另外两个来源要么仅存在于本地且被 gitignore，要么并非自动覆盖全面；参见 
[[log-model]]
）。将其作为额外的 CLUE，而不是步骤 0b 的替代方案。只报告，不阻塞。
  1. 追加到 
    llmwiki/wiki/log.md
    ：
    ## YYYY-MM-DD — lint
    ，并记录发现/修复的问题以及已标记的问题。
  2. 锁定 neo — 
    RUN: python3 harness/scripts/wiki-sync.py --mark-synced
    （或使用与步骤 0 相同的全局版本）。仅在 wiki 内容确实发生变化时写入（content-hash）；自动删除已检查的 
    code-drift
    标记。反馈循环必须闭合：如果不锁定 neo，下一次检查就会报告虚假 drift。

Branches

Branches

IDKindGuardHành viSkip / failureRejoin
B01conditional_requiredbước 0 exit 3 (
drift
)		docs-impact-plan + phân loại contradiction / superseding / progression / equivalence trước khi sửatrang không truy được → không đụngW03
B02conditional_requiredbước 0 exit 2 (chưa có neo / neo mất hiệu lực)làm trọn lint rồi chốt neo ở bước 10—W03
B03user_optionalbước 0 exit 0 nhưng vẫn muốn quét sức khoẻ nội-wikiđi tiếp bước 1không muốn → dừng "wiki đã current"W03
B04capability_optionaldownstream không có 
harness/
hoặc 
fdk/tools
trong repo		dùng bản global 
~/.claude/harness/...
; không có 
fdk/tools
hoặc 
harness/mechanisms.yaml
→ bỏ qua bước đó		—W04
ID类型Guard行为跳过/失败汇合点
B01conditional_required步骤 0 exit 3（
drift
）		修改前制定 docs-impact-plan，并按 contradiction / superseding / progression / equivalence 分类 drift页面无法追溯 → 不修改W03
B02conditional_required步骤 0 exit 2（尚无 neo / neo 失效）完成全部 lint，并在步骤 10 锁定 neo—W03
B03user_optional步骤 0 exit 0，但仍希望扫描 wiki 内部健康状况继续步骤 1不希望扫描 → 停止并报告“wiki 已 current”W03
B04capability_optional下游仓库没有 
harness/
或 
fdk/tools
使用全局版本 
~/.claude/harness/...
；没有 
fdk/tools
或 
harness/mechanisms.yaml
→ 跳过该步骤		—W04

Validation và stopping

验证与停止条件

Exit code wiki-sync quyết điểm vào (tất định); các pulse 8–8f chỉ báo cáo. Sau lint chốt neo để lần check sau không báo drift giả. Dừng sớm hợp lệ khi exit 0.
wiki-sync 的 exit code 是决定性依据；步骤 8–8f 的 pulse 只做报告。Lint 完成后锁定 neo，使下一次检查不会报告虚假 drift。Exit 0 时可以合理地提前停止。

Examples

示例

  • Positive: session_start báo 
    [wiki-sync] code đã đổi 3 commit
    → bước 0 exit 3, cờ 1 trang ⇐ 
    harness/scripts/tidy.py
    → hồ sơ why cho thấy đổi ngưỡng draft → phân loại superseding → thêm 
    invalid_at
    + 
    invalidated_by
    , sửa 1 câu → log + 
    --mark-synced
    .
  • Boundary/failure: bước 0 exit 0 và user chỉ hỏi "wiki có khớp code không" → dừng, trả lời "wiki đã current", ghi log, không sửa trang nào.
  • Positive： session_start 报告 
    [wiki-sync] code đã đổi 3 commit
    → 步骤 0 exit 3，标记 1 个“⇐”页面 
    harness/scripts/tidy.py
    → why 依据显示 draft 阈值发生变化 → 分类为 superseding → 添加 
    invalid_at
    + 
    invalidated_by
    ，修改 1 句 → 记录日志 + 执行 
    --mark-synced
    。
  • Boundary/failure： 步骤 0 exit 0，且用户只问“wiki 是否与代码一致” → 停止，回答“wiki 已 current”，记录日志，不修改任何页面。

Delivery — Output Report

Delivery — 输出报告

After all main skill tasks complete, write a propose draft to the wiki.
完成所有主要 skill 任务后，将结果写成 wiki 中的一份 proposed draft。

Steps

步骤

1. Build the filename:
  • Format: 
    DDMMYY-<ten>.md
  • DDMMYY
    = today (e.g., 
    020626
    for 2 June 2026)
  • <ten>
    = 2–4 kebab-case words summarising what was done (e.g., 
    landing-page-coteccons
    , 
    brand-kit-fintech
    , 
    ingest-auth-spec
    )
2. Write 
llmwiki/wiki/sources/draft/DDMMYY-<ten>.md
:
---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---
1. 构建文件名：
  • 格式：
    DDMMYY-<ten>.md
  • DDMMYY
    = 当天日期（例如 
    020626
    表示 2026 年 6 月 2 日）
  • <ten>
    = 2–4 个用于概括本次工作的 kebab-case 单词（例如 
    landing-page-coteccons
    、
    brand-kit-fintech
    、
    ingest-auth-spec
    ）
2. 写入 
llmwiki/wiki/sources/draft/DDMMYY-<ten>.md
：
---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-<ten>

DDMMYY-<ten>

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD
Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

What

What

<One sentence — what this skill invocation produced or decided>
<One sentence — what this skill invocation produced or decided>

Output

Output

<Key artefacts, files created/modified, or decisions made>
<Key artefacts, files created/modified, or decisions made>

Files

Files

FileAction
path/to/file
created / modified
FileAction
path/to/file
created / modified

Notes

Notes

  • Invoked via: 
    /<skill-name>
    skill
  • Invoked via: 
    /<skill-name>
    skill

Origin

Origin

  • Draft: 
    wiki/sources/draft/DDMMYY-<ten>.md
  • Commit: (filled by verify-before-commit)
  • Date promoted: (filled by verify-before-commit)

**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append one row: `| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — <skill-name> — <ten>`

> Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like `/caveman-stats`).
  • Draft: 
    wiki/sources/draft/DDMMYY-<ten>.md
  • Commit: (filled by verify-before-commit)
  • Date promoted: (filled by verify-before-commit)

**3. 更新 wiki index 与 log：**
- `llmwiki/wiki/index.md` — 追加一行：`| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — 追加：`## YYYY-MM-DD — <skill-name> — <ten>`

> 仅当 skill 没有产生任何 artifact 和决策时跳过（例如 `/caveman-stats` 这种纯展示模式）。