OKF v0.2 対応で status が衝突した。docsweep で文書状態と作業状態を分けた

AI コーディングエージェントが残す plan_*.md や bugfix_*.md を、ほかのツールでも読める形に持ち出したい。その目的で docsweep の OKF v0.2 対応を進めたら、途中で本質的な衝突が出ました。OKF にも docsweep にも status があり、同じキーなのに意味が違ったのです。文書の寿命は status、作業の進み具合は docsweep_state へ分け、版ごとの規則は JSON profile に切り出しました。

記事全体の要約（AI 生成のインフォグラフィック）。

この記事のテーマ

OKF（Open Knowledge Format）の status は draft / stable / deprecated の 3 値で、「この知識文書を今後どう扱うか」を表します。一方、docsweep が以前から使っていた status は in-progress のような作業の進み具合でした。同じキーに両方を押し込むと、OKF から見れば in-progress はライフサイクル値ではなく、docsweep から見れば draft では仕事が終わったのか分かりません。そこで軸を 2 本に分け、人が一覧で見るための表示は H1 の [計画] / [完了] に任せました。

既存文書の扱いも同時に決めています。読み取りは「docsweep_state があればそれを使う → 無ければ旧 status を読む → それも無ければ H1 やファイル名から判定する」の優先順位にし、新形式への正規化は書き出すときだけ、しかも原本ではなく Bundle 内のコピーに対して行います。加えて、仕様の版ごとの機械可読な規則を JSON profile へ切り出しました。profile は wheel 同梱・ローカルファイル・明示指定した GitHub Raw URL の 3 経路から読め、外部 URL は利用者が指定したときだけ取得し、失敗しても別の版へ黙って落ちません。記事では書き出した Bundle を自分で検査する okf-check の設計と、「実装完了」と「リリース完了」を混ぜずに報告するという話までを扱っています。

同じ「完了っぽさ」でも、片方は作業の進み具合、片方は文書の寿命を表している。

版ごとの規則を Python に直書きせず、差し替えられるデータとして外へ出す。