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.

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

Input và output contract

llmwiki/wiki/

harness/scripts/*

~/.claude/harness/harness/scripts/

fdk/tools/skill-usage.py

## YYYY-MM-DD — lint

llmwiki/wiki/log.md

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.

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.

HOW

Main workflow

wiki-sync.py --check

phiên · ts · why

wiki-sync.py --mark-synced

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 .

   ).

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

RUN: python3 harness/scripts/unknown-ledger.py --list

(default, find-out-later)

[[150726-unknown-ledger]]

RUN: python3 harness/scripts/skill-health.py

skills/

desc

sprawl

negation

weak-criterion

### Task

[[skill-craft]]

RUN: python3 fdk/tools/skill-usage.py --weekly --no-html

fdk/tools

RUN: python3 harness/scripts/tidy.py check

/tidy

archive/

RUN: python3 harness/scripts/claim-receipts.py --check <draft>

claim-receipts.config.yaml

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

status: retired

RUN: grep "<tên-file-hoặc-id>" harness/metrics/provenance-log.jsonl | tail -5

writer_id

topic

ts_utc

git_sha

events.jsonl

scratch-log.jsonl

[[log-model]]

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

Branches

drift

harness/

fdk/tools

~/.claude/harness/...

fdk/tools

harness/mechanisms.yaml

Validation và stopping

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.

Delivery — Output Report

Steps

• 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

  )

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>
**Type:** draft
**Status:** proposed
**Tags:** <skill-name>, output-report
**Proposed:** YYYY-MM-DD

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

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

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- Invoked via: `/<skill-name>` skill

## Origin
- **Draft:** `wiki/sources/draft/DDMMYY-<ten>.md`
- **Commit:** _(filled by verify-before-commit)_
- **Date promoted:** _(filled by verify-before-commit)_

• 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

).