lint

スキル：lint

WHAT

目的とコンテキスト

• 目的： 定期的な Wiki の健全性チェック — 孤立ページ、リンク切れ、矛盾、古い情報（Wiki→Wiki およびコード→Wiki の乖離）、インデックスの不足を確認します。まず、確定的な no-op ゲート（wiki-sync、0 トークン）から開始します。
• 実行タイミング： 10 回の取り込みごと、Wiki が古くなったり一貫性を失ったりしたとき、または session_start で [wiki-sync] code đã đổi N commit と表示されたとき。
• 対象外： 矛盾する 2 つのページのどちらかを選びません（人にフラグを提示します）。shortcut: マーカーのアップグレードを促すトリガーを推測しません。ドラフトを自動で移動しません（これは /tidy の役割であり、人の承認ゲートがあります）。Wiki が最新のときに、形だけの修正はしません。

メンタルモデル

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.

入力と出力の契約

	Field	必須？	意味
In	llmwiki/wiki/ + wiki-sync のアンカー	はい	アンカーが失われている場合は exit 2。処理をすべて完了してからアンカーを確定します
In	harness/scripts/*（またはグローバル版 ~/.claude/harness/harness/scripts/）	はい	リポジトリ内に harness/ がない下流プロジェクトでは、グローバル版を使います
In	fdk/tools/skill-usage.py	いいえ	framework リポジトリのみ。下流プロジェクトではこの手順を省略します
Out	その場で修正：リンク切れ、インデックスの不足。古いページは外科的に修正	結果による	具体的なコード変更にたどれること
Out	フラグの一覧（矛盾、孤立ページ、空ページ、Origin の不足、pulse）	はい	人の判断を待ちます
Out	llmwiki/wiki/log.md の ## YYYY-MM-DD — lint 行と新しいアンカー	はい	no-op の場合も含みます
Out	ドラフト形式の出力レポート	はい（artifact が 0 件の場合を除く）	Delivery の項を参照

ルールと機能

• RULE-01 (MUST)：自動修正するもの：リンク切れ（手順 2）、インデックスの不足（手順 5）。
• RULE-02 (MUST)：解決せず、フラグを提示するもの：矛盾、孤立ページ、空ページ — 人の判断が必要です。
• RULE-03 (MUST)：外科的更新（openwiki 060726 から抽出）：古いページを修正するときは、誤った文だけを置き換えます。正しい部分は書き直しません。段落を追加するより、文を 1 つ直すことを優先します。
• RULE-04 (MUST)：ソフト差分予算：コード変更が 5 ファイル未満なら、修正する Wiki ページは最大 1～2 ページです。3 ページを超える修正が必要に見える場合は、広範囲な修正の前に立ち止まり、理由を問い直します。
• RULE-05 (MUST)：フォーマットのみの編集は禁止：周辺の内容が誤っていない限り、表の再フォーマットや、空行・表現の統一はしません。ノイズの多い差分はレビュー担当者への負債になります。
• RULE-06 (MUST)：正規の掲載先：各コンセプトには正式なページを 1 つ設けます。他のページでは簡潔に触れるだけにし、[[wikilink]] を付けてください。説明を重複させません。
• RULE-07 (MUST)：有効な no-op：「Wiki は最新で、変更なし」は lint の正常な結果です。ログを記録して終了し、形だけの修正はしません。
• 機能：Wiki とローカルメトリクスの読み取り、確定的な 0 トークンのスクリプト実行、Wiki ページの書き込み（外科的な修正）、インデックス、ログ、同期アンカー。

失敗時の境界

• Exit 0 で、目的が「Wiki がコードと一致しているか」の確認なら、早期に終了して 成功 とします（有効な no-op）。
• 古くなっている疑いのあるページを、どのコード変更にも結びつけられない場合は、変更しません。
• コード変更が 5 ファイル未満なのに 3 ページを超える修正が必要な場合は、広範囲な修正の前に立ち止まり、理由を問い直します（確認）。
• 矛盾がある場合は、人にフラグを提示し、独自にどちらかを選びません。
• why の記録が空の場合は、黙って済ませず、「記録が不十分なため、diff を開いて確認してください」と記録します。

HOW

メインワークフロー

ステップ	種類	入力	アクション	出力／終了	失敗時／次の処理
W01	deterministic	neo wiki-sync	ステップ 0：wiki-sync.py --check	exit 0 / 3 / 2	0 ＋ 目的がコードと一致 → 停止；3 → B01；2 → B02
W02	deterministic	コードファイル「⇐」	ステップ 0b ＋ 8f：⚑ フラグの記録（events、scratch-log、provenance-log）	セッション · ts · why	why が空 → 「記録が不十分」と記載
W03	deterministic	wiki	ステップ 1–7：孤立項目、リンク切れ、矛盾、古い情報、インデックス、空項目、Origin	2 と 5 を修正し、残りにフラグを付ける	—
W04	deterministic	repo	ステップ 8–8f：ブロックしない pulse レポート	フラグ一覧	スクリプト／パスがない → そのステップをスキップ
W05	effect	結果	ステップ 9：ログに追記	ログ行	—
W06	effect	レビュー済みの wiki	ステップ 10：wiki-sync.py --mark-synced	新しいアンカー	内容に変更がない → 書き込まない
W07	effect	結果	出力レポートのドラフト（Delivery 項目）	ドラフト ＋ インデックス ＋ ログ	アーティファクトが 0 件 → スキップ

各ステップの詳細（W01–W07 の信頼できる情報源）：

0. コードのドリフト判定ゲート（0 トークン） — RUN: python3 harness/scripts/wiki-sync.py --check（下流の repo に harness/ がない場合は、グローバル版を使用：python3 ~/.claude/harness/harness/scripts/wiki-sync.py --check --root .）。

0b. ⚑ フラグごとの記録（0 トークン — 2 段階でセカンダリメモリを JOIN、2026-07-18 に組み込み）： ステップ 0 で「⇐」と報告されたコードファイルごとに実行します（ページが古くなっている疑いの原因）：

• ステップ 1 — どのセッションが変更したか（詳細な保存先、ファイル単位）：RUN: grep "<ファイル名>" harness/metrics/events.jsonl | tail -3 → session ＋ ts を取得します。
• ステップ 2 — 理由（そのセッションの why）：RUN: grep "<session-id-8-ký-tự>" harness/metrics/scratch-log.jsonl | tail -2。 報告時に セッション · ts · why をフラグに付記します。記録付きフラグなら数秒で判断できます（why を読めば、変更によって主張が無効になるか分かります）。記録なしのフラグでは diff を調べる必要があります。Why が空、またはコミットから自動生成されたものなら、黙って済ませず「記録が不十分なため diff を確認する必要あり」と記します。（実際の制限：scratch-log はセッションごとに why が 1 件のみ。events は詳細ですが、パスしかありません。why の詳しさは、セッション中に手動で記録したかどうかによります。）
• Exit 0（current）：アンカー以降、コードに変更なし → 今回の lint の目的が「wiki がコードと一致しているか」の確認なら、ここで停止し、「wiki は current です」と回答します — 何もしないことも良い結果です。作業をでっち上げないでください。wiki 内の健全性（孤立項目／インデックス／origin）も確認する場合は、ステップ 1 に進みます。
• Exit 3（drift）：古くなっている疑いのあるページには、原因となったコードファイルとともに stale.json 内で code-drift フラグが付いています。修正前に docs-impact-plan を作成します：修正予定の各ページを、具体的なコード変更に結び付けます（コード変更 → ページ → 修正内容 → 理由）。どの変更にも結び付けられないページには手を加えません。
  • 修正前に drift を分類します（RedPlanetHQ/core の temporal-invalidation の考え方を取り入れた 4 分岐の基準。github.com/RedPlanetHQ/core prompts/statements.ts）：古い主張と新しい実態は、どのような関係にあるか？
    • contradiction — 2 つの主張が同時に成立しない（例：「API はキー X を使用する」とあるが、キーの名前が変更済み）→ 古い主張は誤りです。通常どおり修正します。
    • superseding — 古い主張は以前は正しかったものの、アーキテクチャの変更により無効になった（例：エンジンの変更／リファクタリング）→ 黙って上書きしないでください：ページの frontmatter に invalid_at: YYYY-MM-DD ＋ invalidated_by: <commit-sha または invalidate の原因となったファイル> の 2 つのフィールドを追加してから、内容を更新します。ページには、古い主張がいつまで有効だったかを示す短い記述を 1 行残します（履歴は削除せず、無効になったことを示すだけです）。
    • progression — どちらの主張も正しく、段階が異なる（例：「X を設計中」→「X をリリース済み」）→ 両方を残します。invalidate は行わず、新しい主張を追記します。
    • equivalence — 表現は異なるが意味は同じ（2 回 ingest された場合など）→ 重複として扱い、1 文にまとめます。これは本当の drift ではありません。
    • invalid_at／invalidated_by フィールドは任意です。R9（okf_frontmatter）は未知のキーを拒否しないため、validator を変更せず安全に追加できます。
• Exit 2（アンカーがない／アンカーが無効）：lint をすべて実行し、ステップ 10 でアンカーを確定します。

1. 孤立項目 — RUN: grep -rL "wiki/" --include="*.md" llmwiki/wiki/concepts/ llmwiki/wiki/entities/ → どこからも参照されていないファイルです。それぞれにフラグを付けます。

2. リンク切れ — ページをスキャンし、wiki ファイルとして存在するエンティティ名や概念名が [[wikilinks]] として記述されていない箇所を探します。その場で修正します。

3. 矛盾 — 同じエンティティに関する主張を、一度に最大2ページまで比較します。該当する組み合わせ（file:line 対 file:line）にフラグを付けます。どちらが正しいかは決めず、人間による確認に回してください。

4. 古い主張 — RUN: grep -rl "raw/" --include="*.md" llmwiki/wiki/ → raw/ を参照しているページを特定します。それぞれにフラグを付けてください。

5. インデックスの漏れ — RUN: comm -23 <(find llmwiki/wiki -name "*.md" | sort) <(grep -o "llmwiki/wiki/[^)]*" llmwiki/wiki/index.md | sort) → インデックスにないファイルを特定します。行を追加してください。

6. 空のページ — RUN: for f in llmwiki/wiki/**/*.md; do [ $(wc -l < "$f") -lt 5 ] && echo "$f"; done → 削除または内容の追加が必要なページにフラグを付けてください。

7. Origin の欠落 — RUN: grep -rL "## Origin" llmwiki/wiki/concepts/ llmwiki/wiki/entities/ → 不完全なページとしてそれぞれにフラグを付けてください。

8. 不足しているトリガーの負債マーカー — RUN: grep -rn "shortcut:" --include="*.py" --include="*.js" --include="*.ts" --include="*.sh" . | grep -v ","; → 意図的な shortcut: マーカーは、それぞれ <現在の上限>, <引き上げトリガー> の形式（カンマで2つの節を区切る）でなければなりません。この grep に引っかかる行は、引き上げトリガーが欠けているマーカーです（期限のない負債は「いつか」に先送りされやすくなります）。執筆者にトリガーの追加を促すため、各行にフラグを付けてください。トリガーを推測してはいけません。

8c. 未知の項目の負債（先に埋めて、確認待ち — 決定的、0トークン） — RUN: python3 harness/scripts/unknown-ledger.py --list → 未解決の unknown の数、最も古いもの、負債が最も多い SPEC を出力します。これらは「処理を続けるため、後で調べる」とモデルがデフォルトで埋めた項目です（(default, find-out-later)）。報告し、ブロックしないでください — 先に埋める方式は意図的にブロックしません。ここでブロックするのは、その仕組みに反する行為です。目的は、負債を見える状態にして埋もれないようにすることです。いつ解消するかはレビュー担当者が判断します（[[150726-unknown-ledger]] を参照）。

8b. スキルの健全性（スキルの形状、決定的 — 0トークン） — RUN: python3 harness/scripts/skill-health.py（skills/ があるリポジトリの場合）→ モデルが呼び出すコンテキストの総量と、フラグが付いたスキルを出力します。フラグは desc（description が長すぎる）・sprawl（プログレッシブディスクロージャーがないのに SKILL.md が長すぎる）・negation（禁止文の割合が高い — 肯定文への変更を推奨）・weak-criterion（### Task ブロックの最後に検証可能な条件がない）と、description の重複しかけている組み合わせです。基準の原典は [[skill-craft]] にあります。報告し、ブロックしないでください — これは品質の問題であり、安全性の問題ではありません。執筆者が検討できるようフラグを付け、まとめて自動修正しないでください。

8b. スキル使用状況のパルス（0トークン、フレームワークリポジトリのみ） — RUN: python3 fdk/tools/skill-usage.py --weekly --no-html → 週ごとの頻度と、使用されていないスキル（4週間以上 idle）を表で出力します。これは「どのスキルを残す価値があるか」を測る計測器を動かす仕組みです（2026-07-18 に組み込み、grower のサイクル）。使用頻度の低下や停止は、取捨選択の判断材料となる事実であり、感覚的な判断ではありません。下流の環境に fdk/tools がなければ、この手順はスキップしてください。

8c. ドキュメント肥大化のパルス（0トークン） — RUN: python3 harness/scripts/tidy.py check → ルート階層の draft が10件を超えると exit 3 を返します。その場合、ユーザーに /tidy の実行を提案してください（apply は人間の承認ゲートを経て archive/ に移動し、インデックスを再生成します。lint 時にツールが自動で移動することはありません）。Draft/html は一時的なレンダリング成果物です。肥大化させると、本質がごみの下に埋もれます。ライフサイクルに合わせて、人間が定期的に整理する必要があります（2026-07-18 に組み込み）。

8d. ACTIVE な draft の主張の参照確認（0トークン） — KEEP/TREO の各 draft について（archive 予定のものは確認しません）：RUN: python3 harness/scripts/claim-receipts.py --check <draft> → 引用されている文書のファイル／パスをすべて抽出し、ディスク上で引き続き解決可能か検証します。解決できないものは、内容が古くなっていることの決定的な証拠です（存在しなくなった、または名前が変更された項目を参照しています）。古い参照の一覧を添えてフラグを付け、修正するか archive に移動するかは担当者に判断してもらいます。助言のみ（adapter claim-receipts.config.yaml verified:false）—ブロックせず、確認するだけです（2026-07-18 に組み込み、7番目の未接続ケース）。 8e. 意思決定アンカリングの稼働状況（0 トークン、決定論的） — RUN: python3 harness/scripts/decision-liveness.py check（downstream のリポジトリに harness/ がない場合は、グローバル版を使用します：python3 ~/.claude/harness/harness/scripts/decision-liveness.py check。リポジトリに harness/mechanisms.yaml がない場合は、この手順をスキップします）。anchor_symbol／live_probe を含むすべての項目を、LIVE／STALE／ORPHAN／UNAVAILABLE のラベル付きで出力します。レビュー担当者はラベルだけで、ORPHAN（アンカーを修正するか、status: retired を通じて決定を削除する必要があります。物理削除はしません）と、STALE（再確認が必要ですが、依然として正しい可能性があります）を見分けられ、内容全体を読み直す必要はありません（SC-005）。報告のみ。ブロックしません — draft-age／unknown-ledger の非ブロッキング方式（手順 8c）と一致します。

8f. Provenance-log の検索（0 トークン、決定論的） — 手順 0b で「なぜ変更されたのか」を確認している各ファイル／決定について、次を実行します：RUN: grep "<tên-file-hoặc-id>" harness/metrics/provenance-log.jsonl | tail -5（downstream では手順 0 と同様のグローバル版を使用します）。一致した各行には writer_id／topic／ts_utc（UTC と明記）／git_sha が含まれます。これは、手順 0b の events.jsonl／scratch-log.jsonl に加わる「なぜ」の第 2 の情報源です。重要な違いは、git で追跡され、別のマシンへのクローン時にも引き継がれることです（他の 2 つの情報源は gitignore 対象のローカルファイルであるか、自動的に網羅されるわけではありません。[[log-model]] を参照）。補足的な手がかりとして使い、手順 0b の代わりにはしません。報告のみ。ブロックしません。

9. llmwiki/wiki/log.md に ## YYYY-MM-DD — lint を追記し、見つけて修正した問題と、指摘のみの問題を記載します。

10. アンカーを確定 — RUN: python3 harness/scripts/wiki-sync.py --mark-synced（または手順 0 と同様のグローバル版）を実行します。Wiki の内容が実際に変更された場合に限り記録します（content-hash）。確認済みの code-drift フラグは自動的に削除されます。フィードバックループを完結させてください。アンカーを確定しないと、次回のチェックで誤った drift が報告されます。

分岐

ID	種別	条件	動作	スキップ／失敗	再合流
B01	conditional_required	手順 0 の終了コードが 3（drift）	修正前に docs-impact-plan を実施し、contradiction／superseding／progression／equivalence に分類する	ページにアクセスできない場合 → 変更しない	W03
B02	conditional_required	手順 0 の終了コードが 2（アンカーがない／無効になっている）	lint を最後まで実施し、手順 10 でアンカーを確定する	—	W03
B03	user_optional	手順 0 の終了コードが 0 だが、wiki 内の健全性もスキャンしたい場合	手順 1 に進む	希望しない場合 → 「wiki は最新です」として終了	W03
B04	capability_optional	downstream のリポジトリに harness/ または fdk/tools がない	グローバル版 ~/.claude/harness/... を使用します。fdk/tools または harness/mechanisms.yaml がない場合は、その手順をスキップします	—	W04

検証と停止

wiki-sync の終了コードで開始箇所を決定します（決定論的）。8～8f の各 pulse は報告のみです。lint の後にアンカーを確定し、次回のチェックで誤った drift が報告されないようにします。終了コードが 0 の場合は、早期終了しても問題ありません。

例

• 正常な例： session_start で [wiki-sync] code đã đổi 3 commit と表示 → 手順 0 の終了コードが 3、harness/scripts/tidy.py に対応する 1 ページにフラグ → 変更理由の記録から draft のしきい値が変更されたと判明 → superseding に分類 → invalid_at と invalidated_by を追加し、1 文を修正 → ログを記録し、--mark-synced を実行。
• 境界／失敗の例： 手順 0 の終了コードが 0 で、ユーザーが「wiki はコードと一致していますか」とだけ尋ねた場合 → 終了して「wiki は最新です」と回答し、ログを記録します。ページは変更しません。

提出 — 出力レポート

スキルの主要タスクがすべて完了した後、wiki に提案用のドラフトを作成します。

手順

1. ファイル名を作成します：

• 形式：DDMMYY-<ten>.md
• DDMMYY = 今日の日付（例：2026 年 6 月 2 日の場合は 020626）
• <ten> = 実施内容を要約する kebab-case の 2～4 語（例：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>
**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)_

3. wiki のインデックスとログを更新します：

• llmwiki/wiki/index.md — 次の行を 1 行追加します：| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |
• llmwiki/wiki/log.md — 次の行を追加します：## YYYY-MM-DD — <skill-name> — <ten>

スキルが成果物も決定事項も一切生成しない場合に限り、スキップします（例：/caveman-stats のような表示専用モード）。