executing-univer-plans

Univer プランの実行

作成済みの Univer ワークブックプランを、Migration Pack ごとに実行します。このスキルでは、ワークブックのドメイン契約を損なわずに、プランを SaC のソース作業に変換します。

開始時に、次のように伝えます。「Univer プランを実行するため、executing-univer-plans スキルを使用します。」

`writing-univer-plans` で作成されたプランなしに、複雑な SaC ワークブックタスクを実行してはいけません。

プランが不完全な場合は、アサーションや Migration Pack を作成する前に停止し、プランを修正してください。

ルール

実行用ファイルに触れる前に、ワークブックの成功基準とプランを確認し、各 Pack でテスト駆動の Univer 開発を行います。

digraph executing_univer_plans {
    "Written Univer plan" [shape=doublecircle];
    "Load success criteria and plan" [shape=box];
    "Plan complete?" [shape=diamond];
    "Stop and repair the plan" [shape=box];
    "Pick next Migration Pack" [shape=box];
    "Load test-driven-univer-development" [shape=box];
    "Write plan-derived failing assertion" [shape=box];
    "Implement pack minimally" [shape=box];
    "Verify and repair from report" [shape=box];
    "More packs?" [shape=diamond];
    "Final handoff" [shape=doublecircle];

    "Written Univer plan" -> "Load success criteria and plan";
    "Load success criteria and plan" -> "Plan complete?";
    "Plan complete?" -> "Stop and repair the plan" [label="no"];
    "Stop and repair the plan" -> "Load success criteria and plan";
    "Plan complete?" -> "Pick next Migration Pack" [label="yes"];
    "Pick next Migration Pack" -> "Load test-driven-univer-development";
    "Load test-driven-univer-development" -> "Write plan-derived failing assertion";
    "Write plan-derived failing assertion" -> "Implement pack minimally";
    "Implement pack minimally" -> "Verify and repair from report";
    "Verify and repair from report" -> "More packs?";
    "More packs?" -> "Pick next Migration Pack" [label="yes"];
    "More packs?" -> "Final handoff" [label="no"];
}

手順

ステップ 1：成功基準を読み込み、プランを確認する

1. プランで参照されている成功基準ファイルを読みます。
2. プランファイルを読みます。
3. 成功基準、ワークブックの契約、範囲の役割、判断の根拠、Pack の順序、アサーションゲート、検証コマンドに照らして、内容を批判的に確認します。
4. 懸念点がある場合は、実行を開始する前に停止し、成功基準またはプランを修正します。
5. 懸念点がない場合は、Migration Pack ごとに 1 件のタスクを含むタスクリストを作成または更新します。

ステップ 2：タスクを実行する

Pack の各タスクについて、次の手順を実施します。

1. Pack のタスクを in_progress にします。
2. プランの各チェックボックスの手順に正確に従います。
3. プランでアサーションまたはマイグレーションの作業に進んだら、test-driven-univer-development を読み込みます。
4. プランと TDD スキルで指定された検証を実行します。
5. 意味のあるアサーションの合格根拠が得られた場合にのみ、Pack のタスクを completed にします。

ステップ 3：開発を完了する

すべての Pack タスクが完了したら、完了を宣言する前に superpowers:verification-before-completion またはリポジトリ内の完了ゲートを使用します。Univer SaC の作業では、完了時に univer sac verify <package.univer> --json の最終ステータスと、返されたアサーションの根拠も必要です。

成功基準を読み込み、プランを確認する

assertions.ts または migrations/ を編集する前に、成功基準とプランを批判的に確認します。

次の内容が含まれていることを確認します。

• チェックリスト、明示的な対象外事項、プラン作成時点での曖昧な点を記載した、参照先の success-criteria/<topic>.md ファイル
• ワークブック上で確認できる目標と明示的な対象外事項
• 取得済みのベースライン根拠と読み取り専用プローブ
• 読み取り／書き込み／保持のルールを含む範囲の役割
• タスクに関連するワークブック動作契約のフィールド
• リスクの高い判断に関する契約上の判断根拠
• Migration Pack の順序
• 重要な変更を含むすべての Pack のアサーションゲート
• 完了時に実行する検証コマンド

項目が不足している場合は、停止してプランを修正します。記憶に頼って作業を進めてはいけません。

プランを停止して修正する

次の場合は、実行前にプランを修正します。

• プランに成功基準への参照がない
• 成功基準のチェックリスト項目がプランにない、またはプランと矛盾している
• 範囲の役割が不明確である
• リスクの高い判断に根拠の強さが示されていない
• 前提が暗黙のままになっている、または証明として提示されている
• Pack に永続的なワークブック上の意図がない
• Pack にアサーションゲートがない
• 検証コマンドがない
• プランが観測済みのワークブックの根拠と矛盾している

プランの修正では、読み取り専用の univer プローブが必要になることがあります。役立つ結果はプランに記録してから続行します。目標の結果が変わった場合は、プランの詳細を修正する前に成功基準を更新します。

Migration Pack を一度に1つずつ実行する

各パックについて：

1. そのパックを現在の実行単位として設定します。
2. パックのタスクを in_progress に設定します。
3. 計画に記載された各チェックボックスの手順に正確に従います。
4. test-driven-univer-development を読み込みます。
5. 計画から導いたアサーションゲートを最初に作成または更新します。
6. 適用済みのパックの場合は、univer sac verify <package.univer> --json を実行し、意図したブック上で確認できる理由でアサーションが失敗することを確認します。新規の保留中パックの場合は、空または実質的な変更のないパックで意図的に RED にしてはなりません。代わりに、ベースラインの証拠から動作が欠けていることを確認してから、最小限の実際のマイグレーションソースファイルを作成します。
7. アサーションを満たすはずの最小限の Migration Pack 変更を実装します。
8. TDD スキルの要求に従って apply／verify を実行します。
9. univer sac verify <package.univer> --json のアサーション証拠を読み、証拠に基づいて修正します。
10. 実行によって動作の契約変更が明らかになった場合は、計画を更新します。
11. パックのタスクを completed に設定します。
12. 現在のパックで意味のあるアサーション通過の証拠が得られてから、次のパックに進みます。

計画に未設定のアサーションゲートがある状態で Migration Pack を編集してはなりません。 複数のパックを、検証なしの1つの実装手順にまとめてはなりません。

レビューゲート

各パックの後に、次の点を確認します：

• 実装前のアサーションは、正しい理由で失敗しましたか？
• 通過したアサーションは、コマンドの成功だけでなく、ブック上で確認できる動作を証明していますか？
• 保持に関する制約と否定的な制約は網羅されていますか？
• 実行中に計画の変更が必要だと判明した場合、記録しましたか？
• パックがスキップされていませんか？変更されたパックの中にアサーションがゼロのものはありませんか？
• RED／GREEN の証拠に SAC_EMPTY_MIGRATION_PACK、SAC_PACK_FILE_INVALID、checkedPacks: 0、またはすべてスキップされた verify の実行結果が使われていませんか？使われている場合、それは意味のある証拠ではありません。

停止して支援を求める場合

次の場合は、直ちに実行を停止します：

• ブックの成果物、依存関係、コマンドなどが不足しているといった阻害要因に直面した場合
• 計画の指示が不明確または矛盾している場合
• 検証に繰り返し失敗する場合
• 前提が不確定で、ユーザーがブック上で確認できる動作に影響する場合
• 計画とブックの証拠が一致しない場合
• verify レポートでソースとアサーションが明確に分けられていない場合
• Univer 以外のスプレッドシートライブラリへのフォールバックが必要と思われる場合

ブック上で確認できる動作に関わる判断については、推測せずに確認を求めてください。

前の手順を見直す場合

次の場合は、「計画の読み込みとレビュー」に戻ります：

• ユーザーがスコープ、要件、またはブックの成果物を更新した場合
• 実行によって、範囲の役割、判断事項、またはアサーションゲートの不足が判明した場合
• verify の証拠によって、期待される動作が変わった場合
• 計画にパックの順序変更または分割が必要な場合

阻害要因を無理に突破しないでください。まず計画を修正してから、パックの実行を続けてください。

忘れないでください

• まず計画を批判的にレビューしてください。
• 各チェックボックスの手順に正確に従ってください。
• 検証コマンドを省略しないでください。
• アサーションまたはマイグレーションソースを作成する手順では、test-driven-univer-development を参照してください。
• 阻害要因があれば停止し、ブックの意味を推測しないでください。
• univer sac apply を完了の証拠として扱わないでください。

インテグレーション

必須のワークフロースキル：

• writing-univer-plans：このスキルが実行する、ブック領域の計画を作成します。
• test-driven-univer-development：各パックをアサーション優先で実装します。
• superpowers:verification-before-completion：完了を宣言する前に最終状態を検証します。

要注意のサイン

次のような考えが浮かんだら、作業を止めてください。

考え	実態
「計画はほぼ完成しているので、コーディングしながら不足分を補えばよい」	実行には、完成したワークブックの仕様が必要です。
「まずパックを実装してから、アサーションを書く」	各パックでは、計画に基づく失敗するアサーションを最初に用意する必要があります。
「複数のパックは関連しているので、まとめて実装しよう」	実行をまとめると、パック単位の証拠が失われます。
「verify コマンドが一度通ったので、すべてのパックが完了した」	変更したパックには、意味のあるアサーションの証拠が必要です。
「失敗したアサーションは、移行の出力に一致させて修正できる」	ワークブックの証拠に基づいて、ソースとアサーションのどちらに誤りがあるかを判断してください。

最終引き継ぎ

外部ハーネスから納品または停止のゲートが指定されている場合は、必須の引き継ぎ成果物を作成した後、そのハーネスに従ってください。引き継ぎ後に、補助的な証拠を集め続けないでください。

引き継ぎには、次の項目を含めてください。

• 計画のパス
• 成功基準のパス
• 実行した Migration Pack の順序
• 検証コマンド
• 最終ステータス
• 変更した各パックのアサーションの証拠
• 該当する場合は、スキップしたパック
• 依然として特定できていない前提