@k2works/claude-code-booster 4.15.0 → 5.0.0

package/lib/assets/.claude/skills/migrating-okf/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: migrating-okf
+description: プロジェクトドキュメント（docs/ 配下の要件定義・設計・運用手順・ADR など）を Open Knowledge Format（OKF）の知識バンドルに移行し、OKF 仕様のバージョンアップ（v0.1→v0.2 など）にも追従させる。移行は `docs/reference/OKF導入ガイド_V0.2.md` に準拠する。「ドキュメントを OKF に移行したい」「知識バンドルを作りたい」「Markdown にフロントマターを付けてエージェントが読める形にしたい」「OKF のバージョンを上げたい」「timestamp を generated に置き換えたい」「OKF に適合しているか検証したい」「index.md / log.md を整備したい」「エージェント向けのナレッジベースを整備したい」といった場面で必ず発動する。既存ドキュメントに来歴（sources）・信頼（generated/verified）・ライフサイクル（status/stale_after）を付与する作業や、エージェントが生成した知識の検証状態を管理したい場面でも積極的に使うこと。
+---
+
+# OKF 移行
+
+プロジェクトの Markdown ドキュメントを OKF（Open Knowledge Format）の**知識バンドル**に移行し、仕様バージョンアップに追従させる。
+
+仕様の日本語リファレンスは `docs/reference/OKF導入ガイド_V0.2.md`。**作業前に必ず読む**。特に §4（コンセプト文書）・§5（来歴・信頼・ライフサイクル）・§11（適合性）・§13（バージョン間の変更点）・§14（導入手順）が本スキルの根拠になる。ガイドと本スキルが食い違う場合はガイドを正とする。
+
+同じディレクトリに `PROJECT.md` があれば必ず読む。バンドルの置き場所・対象ディレクトリ・既定の `generated.by`・除外パターンなど、プロジェクト固有の値はそこにある。
+
+## なぜ OKF に移行するのか
+
+エージェントが繰り返し参照し、書き換えもする知識には「どこから来たか（来歴）」「誰が確認したか（信頼）」「まだ有効か（鮮度）」が要る。素の Markdown にはそれを置く場所がない。OKF は YAML フロントマターを持つ Markdown のディレクトリというだけの最小規約で、この 3 つを第一級にする。移行の本質はフォーマット変換ではなく、**各文書に「信頼してよい根拠」を持たせること**である。
+
+## モード
+
+| モード | 用途 |
+| :--- | :--- |
+| `--plan` | 対象文書を棚卸しし、バンドル構造と `type` 割り当て案を提示する。ファイルは変更しない |
+| `--migrate` | 文書に OKF フロントマターを付与し、`index.md`・`log.md` を整備する（既定） |
+| `--upgrade <version>` | 既存バンドルを指定バージョンの仕様に追従させる（例: `--upgrade 0.2`） |
+| `--check` | バンドルの適合性を検証し、違反と警告を報告する |
+
+指定がなければ、バンドルが未作成なら `--plan` → 確認 → `--migrate`、作成済みなら `--check` から始める。
+
+## 進め方
+
+### 1. 棚卸し（`--plan`）
+
+1. 対象ディレクトリ（既定 `docs/`。`PROJECT.md` で上書き可）の `.md` を列挙する
+2. 各文書を読み、次を判断する
+   - **コンセプトにするか除外するか**。`index.md`・`log.md` は予約名なのでコンセプトにできない。テンプレート（`docs/template/`）や一時的なジャーナルは通常除外する
+   - **`type`**。既存ディレクトリから素直に導く（例: `docs/adr/` → `ADR`、`docs/design/` → `Design`、`docs/operation/` → `Playbook`、`docs/reference/` → `Reference`）。中央登録はないので、説明的で一貫した値を選ぶことだけが要件
+   - **`resource` の有無**。テーブル・API・ダッシュボードなど実在の資産を説明する文書だけに付ける
+3. バンドル構造案を提示する。**既存ディレクトリ構造を尊重する**（移動はリンク切れと git 履歴の断絶を招く）。ガイド §14.2 の骨格はあくまで新規作成時の例
+4. 提案を表にまとめ、ユーザーの確認を得てから `--migrate` に進む
+
+### 2. 移行（`--migrate`）
+
+各コンセプト文書に対して：
+
+1. **フロントマターを付与する**。既存の見出し・本文はそのまま残す
+   - `type`（必須）、`title`（既存の `# 見出し` から）、`description`（本文冒頭から 1 文に要約。無ければ書く）、`tags`
+   - `generated: { by, at }`。`generated` は「**今の本文を誰がいつ書いたか**」を表す。フロントマターを付けただけで本文を変えていないなら、書いた人は変わっていないので、git log の著者から `human:<id>`、`at` は本文を最後に変えたコミットの日時にする。本文を書き換えた（要約を書き足した、構造化のため再構成した）なら本作業のエージェント（例: `claude-code/claude-fable-5`）と現在時刻。著者が git から辿れない（履歴が浅い、インポートされた文書）なら `generated` を省略し、レポートの要確認に載せる。移行しただけの文書にエージェントを著者として書くと、来歴が嘘になる
+   - 既存のフロントマター（Wiki.js の `dateCreated`/`editor`/`published`、Jekyll の `layout` など）があれば**併合**する。意味が対応するキーは OKF に写し（`dateCreated` → `generated.at`）、ツール固有で意味を失うキーは削除し、削除したことをレポートに書く。判断がつかないキーは残す（未知キーは仕様上有効）
+   - `status`。レビュー済みの安定文書は `stable`（省略可）、WIP は `draft`、置き換え済みは `deprecated`
+   - `sources`。文書が根拠にしている外部資料・上流文書（要件定義→設計など）があれば登録し、`id` を付ける。本文中で根拠を示す箇所は `[^id]` 脚注に変える
+   - `stale_after` は「定期的に見直すべき」文書（環境手順・技術スタック）にだけ付ける。全文書に一律付けると陳腐化警告がノイズになる
+2. **リンクをバンドル相対（`/` 始まり）に揃える**。既存の相対リンクが壊れていなければ無理に変えなくてよい（相対も仕様上有効）
+3. **本文を構造化する**。慣習見出し（`# Schema`・`# Examples`）が適用できる箇所だけ合わせる。文章を書き換えて意味を変えない。本文に NBSP（U+00A0）や全角スペースが混じっていることがあるので、文字列一致で編集する前に該当行を実際に読む
+4. 各ディレクトリの `index.md` を生成・更新する。エントリにはフロントマターの `description` を反映する。バンドルルートの `index.md` のみ `okf_version: "0.2"` を持つフロントマターを置く
+5. バンドルルートの `log.md` に移行エントリを追記する（`## YYYY-MM-DD` 見出し、新しい日付が上）
+6. `scripts/okf_check.py --check` を実行し、違反ゼロを確認する
+
+フロントマター付与の例：
+
+**Input**（`docs/design/data-model.md` 冒頭）
+
+```markdown
+# データモデル設計
+
+本ドキュメントは受注管理システムのデータモデルを定義する。要件定義書のユースケース一覧を基に...
+```
+
+**Output**
+
+```markdown
+---
+type: Design
+title: データモデル設計
+description: 受注管理システムの概念・論理データモデルとテーブル定義。
+tags: [design, data-model]
+status: stable
+generated: { by: human:k2works, at: 2026-06-10T09:12:00Z }   # 本文未変更なので git 著者と最終更新コミット
+sources:
+  - id: requirements
+    resource: /requirements/requirements_definition.md
+    title: 要件定義書
+---
+
+# データモデル設計
+
+本ドキュメントは受注管理システムのデータモデルを定義する。要件定義書のユースケース一覧を基に...[^requirements]
+
+[^requirements]: 要件定義書
+```
+
+### 3. バージョンアップ（`--upgrade <version>`）
+
+仕様が改訂されたとき、既存バンドルを新バージョンに追従させる。
+
+1. バンドルルート `index.md` の `okf_version` で現在バージョンを確認する（無ければ v0.1 相当とみなす）
+2. ガイドの「vX.Y からの変更点」節（v0.2 なら §13）を読み、**破壊的変更**と**追加的変更**を分けて把握する
+3. 破壊的変更を機械的に適用する。v0.1→v0.2 は `scripts/okf_check.py --upgrade 0.2` が対応している
+   - `timestamp` → `generated: { by, at }`（`by` は git log の著者から推定。人なら `human:<id>`。推定できなければ `unknown/legacy` とし、レポートに列挙する）
+   - 本文 `# Citations` リスト → フロントマター `sources`
+4. 追加的変更は「付けられるところだけ」付ける。無いことも仕様上有効なので、根拠の無いフィールドを埋めるためにでっち上げない
+5. `okf_version` を更新し、`log.md` に **Upgrade** エントリを追記する
+6. `--check` で違反ゼロを確認する
+
+将来のバージョン（v0.3 以降）でスクリプトが未対応なら、ガイドの変更点節を読んで変換規則を洗い出し、スクリプトに変換を追加してから適用する。手作業で全文書を直さない。
+
+### 4. 検証（`--check`）
+
+```bash
+python .claude/skills/migrating-okf/scripts/okf_check.py --check <バンドルルート>
+```
+
+運用手順書に登録済みの Gulp タスク `gulp okf:check`（同じスクリプトを呼ぶ）でもよい。`gulp okf:help` に `okf:upgrade`・`okf:viz`（上流ツールでグラフ可視化）などの一覧がある。
+
+検証内容はガイド §11 に対応する。
+
+| レベル | 内容 |
+| :--- | :--- |
+| ERROR | 予約名以外の `.md` にフロントマターが無い / `type` が空 / `index.md`（ルート以外）にフロントマターがある / `log.md` の日付見出しが `YYYY-MM-DD` でない |
+| WARN | `generated` が無い / `generated.by` の形式がアクター規約に合わない / 脚注ラベルに対応する `sources[].id` が無い / タイムスタンプに UTC オフセットが無い / バンドル内リンク切れ / `stale_after` を過ぎている |
+
+検査はコードフェンスとインラインコードの中を無視する（仕様例のリンクや脚注を誤検知しないため）。ERROR は移行完了前に必ず解消する。WARN は仕様上は適合なので、内容を確認して意図的なら残してよい。リンク切れは「まだ書かれていない知識」でも有効だが、移行直後のリンク切れはたいてい単なるパス間違いなので直す。
+
+## 判断に迷いやすい点
+
+- **`verified` を付けてよいのは、実際に人またはプロセスが内容を確認したときだけ。** 移行作業でエージェントが読んだだけでは `verified` にしない。信頼ティアの意味が壊れる
+- **`description` は検索スニペットと `index.md` に使われる。** 「〜について記述したドキュメント」のような自己言及ではなく、中身を 1 文で言う
+- **`type` の数は絞る。** ディレクトリごとに 1 つが目安。文書ごとに新しい型を発明すると消費側のルーティングが効かない
+- **本文の意味を変えない。** 移行は構造の付与であって推敲ではない。内容の誤りに気づいたらレポートに書き、別作業にする
+- **mkdocs との共存。** フロントマターは MkDocs でもメタデータとして無害に扱われる。`docs/index.md` は MkDocs のトップページでもあるので、OKF の `okf_version` フロントマターを追加しても既存本文は残す
+
+## 完了報告
+
+`--migrate` / `--upgrade` の最後に次を報告する。
+
+```markdown
+## OKF 移行結果
+
+- バンドル: <パス>（okf_version: <版>）
+- コンセプト: <N> 件（type 別内訳）
+- 除外: <N> 件（理由）
+- 検証: ERROR 0 / WARN <N>
+- 要確認: <generated.by を推定できなかった文書、リンク切れ、内容の疑義 など>
+```
+
+## 関連スキル
+
+- `operating-docs` — `docs/index.md`・`mkdocs.yml` の更新と Markdown Lint
+- `creating-adr` — ADR は `type: ADR` のコンセプトとして移行する
+- `git-commit` — 移行後のコミット（ユーザーの指示があるまでコミットしない）

package/lib/assets/.claude/skills/migrating-okf/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "migrating-okf",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "docs/ 配下の設計ドキュメントと ADR を OKF の知識バンドルに移行して。docs/reference/OKF導入ガイド_V0.2.md に沿ってやってほしい。まず案を見せてから実行して。",
+      "expected_output": "棚卸し表（type 割り当て）を提示後、各 .md に type/title/description/generated 等のフロントマターを付与し、index.md に okf_version、log.md に移行エントリを追加し、検証で ERROR 0 を報告する",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "knowledge/ にある OKF バンドルが古い v0.1 形式（timestamp と # Citations を使っている）なので v0.2 に上げて。",
+      "expected_output": "timestamp を generated.at に、# Citations を sources に変換し、okf_version を 0.2 に更新、log.md に Upgrade エントリを追記、検証結果を報告する",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "knowledge/ の OKF バンドルが仕様に適合しているかチェックして、問題があれば直して。",
+      "expected_output": "okf_check.py --check を実行し、ERROR を修正、WARN は内容を判断して報告する",
+      "files": []
+    }
+  ]
+}

package/lib/assets/.claude/skills/migrating-okf/scripts/okf_check.py

@@ -0,0 +1,468 @@
+#!/usr/bin/env python3
+"""OKF バンドルの適合性検証とバージョンアップ。
+
+標準ライブラリのみで動作する（PyYAML 不要）。
+
+使い方:
+  python okf_check.py --check <bundle_root>
+  python okf_check.py --upgrade 0.2 <bundle_root> [--by <actor>] [--dry-run]
+
+検証（--check）はガイド §11 の適合条件を ERROR、§5〜§7 の推奨事項を WARN として報告する。
+アップグレード（--upgrade）はガイド §13 の破壊的変更を機械的に適用する。
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+RESERVED = {"index.md", "log.md"}
+ACTOR_RE = re.compile(r"^([A-Za-z_][\w-]*:[^\s]+|[^\s/]+/[^\s]+)$")  # human:/process:/team: 等の <kind>:<id>、または <producer>/<version>
+ISO_TZ_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$")
+DATE_HEADING_RE = re.compile(r"^## (.+)$")
+FOOTNOTE_REF_RE = re.compile(r"\[\^([^\]]+)\](?!:)")
+LINK_RE = re.compile(r"(?<!\!)\[[^\]]*\]\(([^)\s]+)\)")
+SUPPORTED_UPGRADES = {"0.2"}
+FENCE_RE = re.compile(r"^[ \t]*(```|~~~)[^\n]*\n.*?^[ \t]*\1[ \t]*$", re.M | re.S)
+
+
+def strip_fences(body: str) -> str:
+    """コードフェンスとインラインコードを除去する。例示リンク・脚注を検査対象から外すため。"""
+    body = FENCE_RE.sub("", body)
+    return re.sub(r"`[^`\n]*`", "", body)  # インラインコードも除外
+
+
+# --------------------------------------------------------------------------- #
+# 最小 YAML パーサ（OKF フロントマターで使う範囲のみ）
+# --------------------------------------------------------------------------- #
+
+def _scalar(s: str):
+    s = s.strip()
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in "'\"":
+        return s[1:-1]
+    if s.startswith("[") and s.endswith("]"):
+        inner = s[1:-1].strip()
+        return [_scalar(x) for x in _split_top(inner)] if inner else []
+    if s.startswith("{") and s.endswith("}"):
+        return _flow_map(s[1:-1])
+    return s
+
+
+def _split_top(s: str) -> list[str]:
+    out, depth, cur, quote = [], 0, "", None
+    for ch in s:
+        if quote:
+            cur += ch
+            if ch == quote:
+                quote = None
+            continue
+        if ch in "'\"":
+            quote = ch
+        elif ch in "[{":
+            depth += 1
+        elif ch in "]}":
+            depth -= 1
+        if ch == "," and depth == 0:
+            out.append(cur)
+            cur = ""
+        else:
+            cur += ch
+    if cur.strip():
+        out.append(cur)
+    return out
+
+
+def _flow_map(s: str) -> dict:
+    d = {}
+    for part in _split_top(s):
+        if ":" in part:
+            k, v = part.split(":", 1)
+            d[k.strip()] = _scalar(v)
+    return d
+
+
+def parse_frontmatter(lines: list[str]) -> dict:
+    """フロントマター行（区切り `---` を除く）を dict にする。"""
+    data: dict = {}
+    i = 0
+    n = len(lines)
+    while i < n:
+        line = lines[i]
+        if not line.strip() or line.lstrip().startswith("#"):
+            i += 1
+            continue
+        m = re.match(r"^([A-Za-z_][\w-]*):(.*)$", line)
+        if not m:
+            i += 1
+            continue
+        key, rest = m.group(1), m.group(2).strip()
+        rest = re.sub(r"\s+#.*$", "", rest) if not rest.startswith(("'", '"')) else rest
+        if rest:
+            data[key] = _scalar(rest)
+            i += 1
+            continue
+        # ブロック値（リストまたはマッピング）
+        block: list[str] = []
+        i += 1
+        while i < n and (not lines[i].strip() or lines[i].startswith((" ", "\t"))):
+            block.append(lines[i])
+            i += 1
+        block = [b for b in block if b.strip()]
+        if not block:
+            data[key] = None
+        elif block[0].lstrip().startswith("- "):
+            data[key] = _parse_block_list(block)
+        else:
+            data[key] = _parse_block_map(block)
+    return data
+
+
+def _dedent(block: list[str]) -> list[str]:
+    indent = min(len(b) - len(b.lstrip()) for b in block)
+    return [b[indent:] for b in block]
+
+
+def _parse_block_list(block: list[str]) -> list:
+    items: list = []
+    block = _dedent(block)
+    cur: list[str] = []
+    for b in block:
+        if b.startswith("- "):
+            if cur:
+                items.append(_list_item(cur))
+            cur = [b[2:]]
+        else:
+            cur.append(b)
+    if cur:
+        items.append(_list_item(cur))
+    return items
+
+
+def _list_item(lines: list[str]):
+    first = lines[0].strip()
+    if len(lines) == 1 and not re.match(r"^[A-Za-z_][\w-]*:\s", first + " "):
+        return _scalar(first)
+    if first.startswith("{"):
+        return _scalar(first)
+    # 「- key: value」形式のマッピング。後続行のインデントを揃える
+    rest = [re.sub(r"^\s{2}", "", l) if l.startswith("  ") else l.strip() for l in lines[1:]]
+    return parse_frontmatter([first] + rest)
+
+
+def _parse_block_map(block: list[str]) -> dict:
+    return parse_frontmatter(_dedent(block))
+
+
+def split_document(text: str):
+    """(frontmatter_lines | None, body_text, fm_end_line_index) を返す。"""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None, text, -1
+    for j in range(1, len(lines)):
+        if lines[j].strip() == "---":
+            return lines[1:j], "\n".join(lines[j + 1:]), j
+    return None, text, -1
+
+
+# --------------------------------------------------------------------------- #
+# 検証
+# --------------------------------------------------------------------------- #
+
+class Report:
+    def __init__(self):
+        self.errors: list[str] = []
+        self.warns: list[str] = []
+
+    def error(self, path, msg):
+        self.errors.append(f"{path}: {msg}")
+
+    def warn(self, path, msg):
+        self.warns.append(f"{path}: {msg}")
+
+
+def iter_md(root: Path):
+    for p in sorted(root.rglob("*.md")):
+        if any(part.startswith(".") for part in p.relative_to(root).parts):
+            continue
+        yield p
+
+
+def check_actor(rep, rel, field, value):
+    if not isinstance(value, str) or not ACTOR_RE.match(value):
+        rep.warn(rel, f"{field} '{value}' がアクター規約（<producer>/<version> | human:<id> | process:<id> など <kind>:<id>）に合わない")
+
+
+def check_ts(rep, rel, field, value):
+    if not isinstance(value, str) or not ISO_TZ_RE.match(value):
+        rep.warn(rel, f"{field} '{value}' が UTC オフセット付き ISO 8601 ではない")
+
+
+def check_bundle(root: Path) -> Report:
+    rep = Report()
+    now = dt.datetime.now(dt.timezone.utc)
+    all_paths = {p.relative_to(root).as_posix() for p in iter_md(root)}
+    for p in iter_md(root):
+        rel = p.relative_to(root).as_posix()
+        text = p.read_text(encoding="utf-8")
+        fm_lines, body, _ = split_document(text)
+        body = strip_fences(body)
+        if p.name == "log.md":
+            for line in text.splitlines():
+                m = DATE_HEADING_RE.match(line)
+                if m and not re.match(r"^\d{4}-\d{2}-\d{2}$", m.group(1).strip()):
+                    rep.error(rel, f"log.md の日付見出し '{m.group(1)}' が YYYY-MM-DD 形式ではない")
+            continue
+        if p.name == "index.md":
+            if fm_lines is not None and p.parent != root:
+                rep.error(rel, "ルート以外の index.md にフロントマターがある")
+            elif fm_lines is not None:
+                fm = parse_frontmatter(fm_lines)
+                extra = set(fm) - {"okf_version"}
+                if extra:
+                    rep.warn(rel, f"ルート index.md に okf_version 以外のキー {sorted(extra)} がある")
+            _check_links(rep, rel, p, body, root, all_paths)
+            continue
+
+        if fm_lines is None:
+            rep.error(rel, "フロントマターが無い")
+            continue
+        fm = parse_frontmatter(fm_lines)
+        t = fm.get("type")
+        if not t or not str(t).strip():
+            rep.error(rel, "type が空")
+
+        gen = fm.get("generated")
+        if gen is None:
+            rep.warn(rel, "generated が無い（誰がいつ書いたか不明）")
+        elif isinstance(gen, dict):
+            if "by" not in gen:
+                rep.warn(rel, "generated.by が無い")
+            else:
+                check_actor(rep, rel, "generated.by", gen["by"])
+            if "at" in gen:
+                check_ts(rep, rel, "generated.at", gen["at"])
+        else:
+            rep.warn(rel, "generated がマッピングではない")
+
+        ver = fm.get("verified")
+        if ver is not None:
+            entries = ver if isinstance(ver, list) else [ver]
+            for e in entries:
+                if not isinstance(e, dict):
+                    rep.warn(rel, "verified の要素がマッピングではない")
+                    continue
+                if "by" in e:
+                    check_actor(rep, rel, "verified.by", e["by"])
+                if "at" in e:
+                    check_ts(rep, rel, "verified.at", e["at"])
+
+        if "timestamp" in fm:
+            rep.warn(rel, "v0.1 の timestamp が残っている（--upgrade 0.2 で generated.at に移行）")
+        if re.search(r"^#+\s*Citations\s*$", body, re.M):
+            rep.warn(rel, "v0.1 の # Citations 節が残っている（--upgrade 0.2 で sources に移行）")
+
+        status = fm.get("status")
+        if status not in (None, "draft", "stable", "deprecated"):
+            rep.warn(rel, f"status '{status}' は draft|stable|deprecated のいずれでもない")
+
+        sa = fm.get("stale_after")
+        if sa is not None:
+            check_ts(rep, rel, "stale_after", sa)
+            try:
+                when = dt.datetime.fromisoformat(str(sa).replace("Z", "+00:00"))
+                if when <= now:
+                    rep.warn(rel, f"stale_after {sa} を過ぎている")
+            except ValueError:
+                pass
+
+        ids = set()
+        sources = fm.get("sources")
+        if sources is not None:
+            if not isinstance(sources, list):
+                rep.warn(rel, "sources がリストではない")
+            else:
+                for s in sources:
+                    if not isinstance(s, dict) or "resource" not in s:
+                        rep.warn(rel, "sources の要素に resource が無い")
+                        continue
+                    if "id" in s:
+                        ids.add(str(s["id"]))
+                    if "author" in s:
+                        check_actor(rep, rel, "sources[].author", s["author"])
+                    if "last_modified" in s:
+                        check_ts(rep, rel, "sources[].last_modified", s["last_modified"])
+        for label in set(FOOTNOTE_REF_RE.findall(body)):
+            if label not in ids:
+                rep.warn(rel, f"脚注 [^{label}] に対応する sources[].id が無い")
+
+        if str(t) == "Attested Computation":
+            if "runtime" not in fm:
+                rep.error(rel, "Attested Computation に runtime が無い")
+            has_inline = re.search(r"^#\s*Computation\s*$", body, re.M) is not None
+            if "computation" in fm and has_inline:
+                rep.warn(rel, "computation ファイルと本文 # Computation の両方がある")
+            if "computation" not in fm and not has_inline:
+                rep.warn(rel, "computation ファイルも本文 # Computation も無い")
+
+        _check_links(rep, rel, p, body, root, all_paths)
+    return rep
+
+
+def _check_links(rep, rel, p: Path, body: str, root: Path, all_paths: set[str]):
+    for target in LINK_RE.findall(body):
+        if re.match(r"^[a-z]+:", target) or target.startswith("#"):
+            continue
+        target = target.split("#")[0]
+        if not target:
+            continue
+        if target.startswith("/"):
+            resolved = (root / target.lstrip("/")).resolve()
+        else:
+            resolved = (p.parent / target).resolve()
+        try:
+            r = resolved.relative_to(root.resolve()).as_posix()
+        except ValueError:
+            continue
+        if r.endswith("/") or resolved.is_dir():
+            continue
+        if not resolved.exists():
+            rep.warn(rel, f"リンク切れ: {target}")
+
+
+# --------------------------------------------------------------------------- #
+# アップグレード v0.1 → v0.2
+# --------------------------------------------------------------------------- #
+
+def git_author_actor(path: Path) -> str | None:
+    try:
+        out = subprocess.run(
+            ["git", "log", "--diff-filter=A", "--format=%ae", "--", str(path.resolve())],
+            capture_output=True, text=True, check=True, cwd=path.resolve().parent,
+        ).stdout.strip().splitlines()
+    except Exception:
+        return None
+    if not out:
+        return None
+    email = out[-1].strip()
+    local = email.split("@")[0]
+    return f"human:{local}" if local else None
+
+
+def upgrade_file_to_0_2(p: Path, default_by: str | None, dry_run: bool) -> list[str]:
+    """変更内容の説明リストを返す。"""
+    notes: list[str] = []
+    text = p.read_text(encoding="utf-8")
+    fm_lines, body, end = split_document(text)
+    if fm_lines is None:
+        return notes
+    fm = parse_frontmatter(fm_lines)
+    new_fm = list(fm_lines)
+
+    if "timestamp" in fm and "generated" not in fm:
+        ts = str(fm["timestamp"])
+        by = default_by or git_author_actor(p) or "unknown/legacy"
+        if by == "unknown/legacy":
+            notes.append("generated.by を推定できず unknown/legacy を設定（要確認）")
+        new_fm = [l for l in new_fm if not re.match(r"^timestamp:", l)]
+        new_fm.append(f"generated: {{ by: {by}, at: {ts} }}")
+        notes.append(f"timestamp → generated.at（by: {by}）")
+
+    m = re.search(r"^#+\s*Citations\s*$\n((?:\s*[-*]\s+.+\n?)+)", body, re.M)
+    if m and "sources" not in fm:
+        items = re.findall(r"^\s*[-*]\s+(.+?)\s*$", m.group(1), re.M)
+        if items:
+            new_fm.append("sources:")
+            for idx, item in enumerate(items, 1):
+                link = re.match(r"\[(.+?)\]\((.+?)\)", item)
+                if link:
+                    title, res = link.group(1), link.group(2)
+                    new_fm.append(f"  - id: cite-{idx}")
+                    new_fm.append(f"    resource: {res}")
+                    new_fm.append(f"    title: \"{title}\"")
+                else:
+                    new_fm.append(f"  - id: cite-{idx}")
+                    new_fm.append(f"    resource: {item}")
+            body = body[: m.start()] + body[m.end():]
+            body = body.rstrip("\n") + "\n"
+            notes.append(f"# Citations（{len(items)} 件）→ sources")
+
+    if notes and not dry_run:
+        out = "---\n" + "\n".join(new_fm) + "\n---\n" + body.rstrip("\n") + "\n"
+        p.write_text(out, encoding="utf-8")
+    return notes
+
+
+def upgrade_bundle(root: Path, version: str, default_by: str | None, dry_run: bool):
+    if version not in SUPPORTED_UPGRADES:
+        print(f"未対応のバージョン: {version}。ガイドの変更点節を読んで本スクリプトに変換を追加してから実行する。")
+        sys.exit(2)
+    changed = 0
+    for p in iter_md(root):
+        if p.name in RESERVED:
+            continue
+        notes = upgrade_file_to_0_2(p, default_by, dry_run)
+        if notes:
+            changed += 1
+            rel = p.relative_to(root).as_posix()
+            print(f"{'[dry-run] ' if dry_run else ''}{rel}")
+            for n in notes:
+                print(f"  - {n}")
+    idx = root / "index.md"
+    if not dry_run:
+        _set_okf_version(idx, version)
+    print(f"\n{changed} 件を更新{'（予定）' if dry_run else ''}。okf_version: \"{version}\" を {idx.name} に設定{'（予定）' if dry_run else ''}。")
+    print("log.md に **Upgrade** エントリを追記し、--check で確認すること。")
+
+
+def _set_okf_version(idx: Path, version: str):
+    if idx.exists():
+        text = idx.read_text(encoding="utf-8")
+        fm_lines, body, _ = split_document(text)
+        if fm_lines is not None:
+            fm_lines = [l for l in fm_lines if not l.startswith("okf_version:")]
+            fm_lines.append(f'okf_version: "{version}"')
+            idx.write_text("---\n" + "\n".join(fm_lines) + "\n---\n" + body.lstrip("\n"), encoding="utf-8")
+            return
+        idx.write_text(f'---\nokf_version: "{version}"\n---\n\n' + text, encoding="utf-8")
+    else:
+        idx.write_text(f'---\nokf_version: "{version}"\n---\n\n# Index\n', encoding="utf-8")
+
+
+# --------------------------------------------------------------------------- #
+
+def main():
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("root", help="バンドルルート")
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--check", action="store_true", help="適合性を検証する")
+    g.add_argument("--upgrade", metavar="VERSION", help="指定バージョンへアップグレードする（例: 0.2）")
+    ap.add_argument("--by", help="--upgrade 時の generated.by 既定値（git から推定できない場合）")
+    ap.add_argument("--dry-run", action="store_true", help="--upgrade 時にファイルを変更しない")
+    args = ap.parse_args()
+
+    root = Path(args.root)
+    if not root.is_dir():
+        print(f"ディレクトリが無い: {root}")
+        sys.exit(2)
+
+    if args.check:
+        rep = check_bundle(root)
+        for e in rep.errors:
+            print(f"ERROR {e}")
+        for w in rep.warns:
+            print(f"WARN  {w}")
+        print(f"\nERROR {len(rep.errors)} / WARN {len(rep.warns)}")
+        sys.exit(1 if rep.errors else 0)
+    else:
+        upgrade_bundle(root, args.upgrade, args.by, args.dry_run)
+
+
+if __name__ == "__main__":
+    main()

package/lib/assets/.claude/skills/migrating-okf-workspace/iteration-1/benchmark.json

@@ -0,0 +1,20 @@
+{
+  "metadata": {
+    "skill_name": "migrating-okf",
+    "skill_path": "<path/to/skill>",
+    "executor_model": "<model-name>",
+    "analyzer_model": "<model-name>",
+    "timestamp": "2026-08-25T02:22:14Z",
+    "evals_run": [],
+    "runs_per_configuration": 3
+  },
+  "runs": [],
+  "run_summary": {
+    "delta": {
+      "pass_rate": "+0.00",
+      "time_seconds": "+0.0",
+      "tokens": "+0"
+    }
+  },
+  "notes": []
+}