claw-score

claw-score

このスキルは、このリポジトリで OpenClaw の成熟度スコアカードを扱うときに使用します。 これはメンテナーの claw-score ワークフローの openclaw-local 版です。 分類体系とスコアカードの概念は維持しつつ、discrawl と古いコミット済みの inventory/ レポートツリーは対象外にしています。

権限

このスキルは、次の項目に関する運用ワークフローを管理します。

• taxonomy.yaml
• qa/maturity-scores.yaml
• docs/concepts/qa-e2e-automation.md
• qa/scenarios/index.yaml

個人固有の情報、メンテナー限定の情報、Discord アーカイブの情報、discrawl の情報は このリポジトリに含めないでください。スコアに非公開のエビデンスが必要な場合は、 OpenClaw QA ワークフローが生成する、情報を伏せた qa-evidence.json アーティファクトの形式を使用してください。

ソースモデル

• taxonomy.yaml は、サーフェス、レベル、QA プロファイル、カテゴリ、機能カバレッジ ID、 ドキュメント参照、LTS のオーバーライド、完全性に関する指示パスを定義する、 手動編集の信頼できる情報源です。
• 各機能の coverageIds エントリは必ず 1 つです。そのエビデンス ID は機能ごとに 一意にしてください。複数の機能にまたがる、より広範な多対多のエビデンス対応付けは、 現在の分類体系スキーマでは扱いません。
• カバレッジ ID は、ドット区切りの namespace.behavior 形式で、 小文字の英数字とハイフンのセグメントを使用します。プロファイル、サーフェス、 カテゴリの ID は、ハイフン区切りまたはドット区切りのままでもかまいません。
• カテゴリ名と機能名は、重複を避け、製品の実態に即したものとし、生の カバレッジ ID より広い意味を持たせてください。汎用的な ID を単独の機能名にしないでください。
• 1 つのカテゴリ内で、異なる機能名に同じカバレッジ ID の組み合わせを重複して割り当てないでください。
• qa/maturity-scores.yaml は、Quality、Completeness、LTS のレビュー状況を集約した コミット済みの情報源です。
• extensions/qa-lab/src/scorecard-taxonomy.ts は readValidatedQaMaturityScoreSources をエクスポートします。スコア出力の検証にはこれを使用してください。
• 生成される公開ドキュメントは docs/maturity/scorecard.md と docs/maturity/taxonomy.md です。どちらも pnpm maturity:render で生成されます。 スコア結果を変更するために、生成済みの Markdown を手動編集しないでください。
• qa-evidence.json アーティファクトは、実行ごとの QA スコアカードのエビデンスを提供します。 Coverage の信頼できる情報源はリリースプロファイルのアーティファクトです。 これらは生成されたアーティファクトのドキュメントを充実させることはできますが、 インベントリとしてコミットしません。

コマンド

openclaw リポジトリのルートから実行してください。

ソースを編集した後に、分類体系 YAML の構造と成熟度スコアのスキーマを検証します。

node --import tsx --input-type=module <<'NODE'
import fs from "node:fs";
import YAML from "yaml";
import { readValidatedQaMaturityScoreSources } from "./extensions/qa-lab/src/scorecard-taxonomy.ts";

for (const file of ["taxonomy.yaml", "qa/scenarios/index.yaml"]) {
  YAML.parse(fs.readFileSync(file, "utf8"));
}
readValidatedQaMaturityScoreSources();
NODE

ドキュメントの文章を変更した場合は、ドキュメントを確認します。

pnpm check:docs

カバレッジ ID またはプロファイルのメンバーシップを変更した場合は、対象を絞った QA／プロファイルチェックを実行します。

pnpm openclaw qa coverage --json

全体生成の実行

生成されたドキュメントを含むプルリクエストを公開する、直接の全体スコアカード実行では、 既定で変動する main の解決を使用してください。

gh workflow run maturity-scorecard.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f ref=main \
  -f expected_sha='' \
  -f publish_pull_request=true \
  -f allow_failures=true

通常の手動生成実行では、ローカルで main を解決し、そのコミットを ref と expected_sha の両方に渡さないでください。OpenClaw の main は頻繁に更新されるため、 検証前に呼び出し側が選んだコミットが古くなる可能性があります。その場合、プルリクエストの ベースにより新しい成熟度入力が含まれていると、ワークフローは公開を正しく拒否し、 QA は開始されません。

ref=main かつ expected_sha が空の場合、ワークフローの floating_default_branch パスは、検証中に現在のリモートの既定ブランチを取得して固定し、 下流のジョブには変更不能なリビジョンを渡します。指定したリビジョンにエビデンスを 厳密に紐付ける必要がある場合にのみ、明示的な SHA を使用してください。たとえば、 リリース候補のワークフロー呼び出しや、アーティファクトのみを使った過去の実行の再現などです。 その特定リビジョンでの実行でも公開を要求し、main の関連入力が変更されている場合は、 検証に失敗することを想定し、変動する main から再度実行してください。

スコアリングのワークフロー

サーフェスのスコアリングまたは更新を依頼された場合：

1. taxonomy.yaml でサーフェスを確認します。
2. .agents/skills/claw-score/references/completeness/ にある、サーフェスの完全性評価基準を確認します。
3. ドキュメント、ソース、テスト、QA シナリオのメタデータから、公開リポジトリのエビデンスを収集します。
4. 実行済みの証拠には、既存のリリースプロファイルの qa-evidence.json アーティファクトを優先します。
5. 公開済み、または秘匿化済みのアーティファクトエビデンスに裏付けられた品質、完全性、LTS のレビュー状態についてのみ、qa/maturity-scores.yaml を更新します。
6. このスキルに記載されたスキーマ検証コマンドを実行します。
7. ドキュメントの文章を変更した場合は pnpm check:docs を実行し、カバレッジ ID またはプロファイルのメンバーシップを変更した場合は、対象を絞った QA カバレッジチェックを実行します。

主観的なスコア変更は、正当化できる範囲で最小限にとどめ、エビデンスのパスを PR またはタスクの概要に記載します。手動で記述する文章は現行ドキュメントに保管し、スコアデータは qa/maturity-scores.yaml に保管します。

デフォルトの完全性評価プロセス

完全性は、テストの範囲や実装品質ではなく、各カテゴリで想定される、オペレーターから見えるワークフローに照らして評価します。references/completeness/ にある完全性の参照ファイルでは、カテゴリの対象範囲と、このデフォルトプロセスからサーフェスごとに異なる点を定義しています。

デフォルトでは、完全性は、そのサーフェスのユーザー、オペレーター、作成者、またはメンテナーのペルソナに向けて、OpenClaw が想定されるサーフェス機能一式をどの程度ユーザーに提供しているかを評価します。各カテゴリについて、セットアップ、通常利用、ステータス確認または調査、復旧、および該当する場合は重要なプラットフォーム、プロバイダー、チャネル、セキュリティ、ライフサイクルのバリエーションを含め、期待されるワークフロー全体を実現できるかをスコアリングします。

Surface-Specific Scoring Questions と Surface-Specific Guidance は、そのサーフェスに対する優先度の高い指示として扱います。サーフェスごとの指示によって、ここに示すデフォルトの考え方が補足、限定、または意図的に相反する場合があります。その場合はサーフェスごとの指示に従い、スコアの根拠にもその指示を反映します。参照ファイルにサーフェス固有の質問やガイダンスがない場合は、そのサーフェスの Category Scope にこのデフォルトプロセスを適用します。

各カテゴリについて、次の点を確認します。

• 想定されるユーザーまたはオペレーターは、カテゴリのワークフローを最初から最後まで完了できますか？
• タクソノミーに記載された機能は、単独の実装断片ではなく、サポートされた機能として提供されていますか？
• セットアップ、通常運用、ステータス確認または調査、復旧、該当する場合はアップグレードまたは削除といった、重要なライフサイクル段階が網羅されていますか？
• このサーフェスにおける重要な環境、プロバイダー、プラットフォーム、チャネル、またはセキュリティに関する分岐が網羅されていますか？
• 既知の不足によって、ユーザーから見える主要な機能分岐が欠けていませんか？

デフォルトのガイダンス：

• カテゴリが、タクソノミーとカテゴリのエビデンスに記載された、オペレーターから見えるワークフロー全体をサポートしている場合は、完全性を高く評価します。
• ハッピーパスしか存在しない場合、重要なバリエーションが文書化または実装されていない場合、あるいは復旧やステータス確認の経路が欠けている場合は、完全性を低く評価します。
• テストが不十分であることを理由に完全性を下げないでください。それはカバレッジの評価項目です。
• 実装品質が不安定であることを理由に完全性を下げないでください。それは品質の評価項目です。

デフォルトの完全性評価区分：

• Clawesome（95-100）：期待されるワークフロー、バリエーション、復旧の分岐を網羅しており、残るのは軽微な仕上げのみです。
• Stable（80-95）：期待されるワークフロー一式が概ねそろっており、不足している分岐も限定的です。
• Beta（70-80）：主要なワークフローは存在しますが、重要な分岐や復旧経路がまだ不足しています。
• Alpha（50-70）：提供されている機能は一部に限られ、ユーザーはいくつかの主要タスクを完了できますが、期待されるワークフロー全体は完了できません。
• Experimental（0-50）：カテゴリが公開しているのは、想定される機能の断片に限られます。

判断の背景

サーフェスおよびカテゴリのQuality/Completenessでは、scoreとlabelの横に、任意のdecisionを記録します。カテゴリのLTSでは、supportedの横に記録します。taxonomy.yamlでは、正規サーフェスのlevelの横に、任意のlevel_decisionを記録します。

各レコードには、value、rationale、reviewer、evidence_refs、revalidate_whenを含めます。Quality/Completenessには0〜100の整数、LTSにはブール値、level_decisionには宣言済みのタクソノミーレベルIDを使用します。テキストフィールドには空でない値を指定し、少なくとも1つの証拠参照を含めてください。実際のレビュー担当者と、再レビューのきっかけとなる条件を明記します。

入手できない履歴は記録しないでください。不明な情報であり、レビュー担当者、根拠、証拠を作り出す理由にはなりません。レコードによって現在のスコア、サポートフラグ、正規レベルが上書きされることはありません。値が異なる場合は両方を保持します。生成されるドキュメントでは、厳格な入力検証時も含め、ゲート判定には影響しない不一致として表示されます。

Coverage、計算された集計値、サーフェスのLTSサマリー、スコア集計にコピーされたレベルには、判断を紐付けないでください。判断の背景によって、Coverageの識別情報、スコア計算、サポートへの確約、リリースゲートが変わることはありません。

スコアの意味

• Coverage：リリースプロファイルのqa-evidence.jsonにあるscorecardの機能充足データから導出される、決定論的なリリース検証カバレッジです。
• Quality：カテゴリの信頼性、保守性、オペレーターの安全性、回帰に対する信頼度です。
• Completeness：カテゴリで、オペレーターから見えるワークフローが意図どおりにどこまで実装されているかです。このスコアを変更する前に、デフォルトのCompletenessプロセスと、サーフェス固有の差異があればそれも適用してください。
• LTS：Quality、リリース証拠に基づくCoverage、human_lts_overrideから導出されます。LTSのステータスを変更するために、生成されたMarkdownを直接編集しないでください。

評価帯：

• Clawesome：95-100
• Stable：80-95
• Beta：70-80
• Alpha：50-70
• Experimental：0-50

成果物

メンテナーのリポジトリにあるdocs/kevinslin/maturity-scorecard/inventory/ツリーをopenclawに追加しないでください。証拠を加えたスコアカードの出力は、リポジトリに明示的なレンダラー／チェックのワークフローが追加されるまでは、コミット対象の生成ドキュメントではなく、短期間だけ保持する成果物にしてください。