flows-external-app-submit

Flows 外部アプリの提出

これは Flows アプリ認定フローのステップ 4（最終ステップ）です。

flows-app-brief  →  build  →  flows-code-review  →  flows-design-review  →  flows-external-app-submit (this skill)

このスキルではレビューを再実行しません。先行する 3 つのステップで作成された成果物を検証し、その後にのみ CLI の提出コマンドを実行します。

前提条件（最初にユーザーに提示してください）

何かを行う前に、検証対象をユーザーが正確に把握できるよう、以下のチェックリストを表示してください。

1. App-Brief.md がリポジトリのルートに存在し、必須のフロントマター項目がすべて入力されています。
2. 最新の reviews/code-review/feedback-round-<N>/code-review-report.md が git にコミット済みで、Must Fix open: 0 と報告されています。
3. 最新の reviews/design-review/feedback-round-<N>/design-review-report.md が git にコミット済みで、Average score: X.X（X.X ≥ 3.8）と報告されています。
4. 認定成果物がコミット済みです。apps submit は git archive HEAD を使用するため、未コミットのファイルは通知なく除外されます。
5. .cognite-bundles/ にデプロイバンドルが存在し、HEAD より古くありません。

ステップ 0 — エアハッチの事前確認（レビューがない場合はスタブを提案）

App-Brief.md は必須です。認定レビュアーが最初に読む価値提案が記載されているためです。一方、コードレビューとデザインレビューについては、レビュアーが確認して対応できるよう、明確な「SKIPPED」ステータスを付けてエアハッチで代替できます。各レビューに 20 分以上かけずに提出したいユーザーには、この方法を使用してください。

git ls-files を使って各レビュー成果物を確認します。

git ls-files 'reviews/code-review/'   | grep -q 'code-review-report.md'   && echo code_present   || echo code_missing
git ls-files 'reviews/design-review/' | grep -q 'design-review-report.md' && echo design_present || echo design_missing

• 両方のレポートが存在する → ステップ 0 をスキップし、ステップ 1 に進みます。
• App-Brief.md がない → ステップ 1 に進みます。標準の「最初に flows-app-brief を実行してください」というメッセージとともに失敗します。エアハッチでは App-Brief は代替できません。
• いずれかのレビューがない → AskQuestion でエアハッチを提案します。

「レビュー成果物がありません：<不足しているもののリスト>。選択してください：

• 実際のレビューを実行 — ここで終了します。先にユーザーが flows-code-review／flows-design-review を実行します（各約 20 分）。初回提出時に推奨します。
• 簡易提出（スタブ） — 不足しているレビューのスタブレポートに SKIPPED と記載して作成します。Cognite の認定レビュアーは SKIPPED ステータスを確認し、承認前に実際のレビューを依頼しますが、今すぐ提出できます。
• キャンセル — 何もせずに停止します。」

実際のレビューを実行を選択した場合：次のステップのコマンド（flows-code-review、flows-design-review、またはその両方）を表示して終了します。

キャンセルを選択した場合：終了します。

簡易提出を選択した場合：不足しているレビューごとに、このスキル末尾の「スタブのテンプレート」を使ってスタブを作成します。

• reviews/code-review/feedback-round-0/code-review-report.md
• reviews/design-review/feedback-round-0/design-review-report.md

Round 0 とするのは意図的です。実際のレビュー用スキルは feedback-round-1 から開始します。後でユーザーが実際のレビューを実行すると、sort -V | tail -1 によって番号の大きいラウンドが選択されるため、手動で整理しなくてもスタブは自動的に置き換えられます。

スタブの作成後、ユーザーに次のように伝えます。

「スタブレポートを作成しました。App-Brief.md と一緒にコミットしてから、このスキルを再実行してください。

git add App-Brief.md reviews/
git commit -m 'chore: certification artifacts (reviews skipped)'」

終了します。ユーザーはコミット後にスキルを再実行します。

ステップ 1 — App-Brief.md の検証

test -f App-Brief.md

存在しない場合 → 次のメッセージを表示して失敗します：「App-Brief.md を作成するため、先に flows-app-brief を実行してください。」

YAML フロントマターを解析します（ファイル先頭の最初の --- と次の --- の間のブロック）。必須キーは、存在し、かつ空でない必要があります。

• appName
• customer
• tier
• owner
• userRole
• currentProblem
• oneSentenceStory
• successCriteria
• userEvidence

欠落または空の項目がある場合 → 不足している項目の一覧と、次のメッセージを表示して失敗します：「ブリーフを完成させるため、flows-app-brief を再実行してください。」

任意項目（なくても処理を続行できます）：userCount、businessValue、milestones、repoUrl。

ステップ 2 — コードレビューを確認する

最新のコミット済みラウンドレポートを見つけます。

git ls-files 'reviews/code-review/' | grep 'code-review-report.md' | sort -V | tail -1

結果がない場合 → 次のメッセージを表示して失敗します："まず flows-code-review を実行してから、成果物をコミットしてください。"

その code-review-report.md から Summary ブロックを解析します。

Summary ブロックに ^- Status: SKIPPED$ に一致する行が含まれている場合 → このチェックを SKIPPED として扱い（PASS でも FAIL でもありません）、数値チェックをスキップします。このスタブはステップ 0 のエアハッチによるもので、レビュー担当者には SKIPPED のステータスが表示されます。

それ以外の場合、次の完全一致の正規表現に一致する行が含まれている必要があります。

^- Must Fix open: (\d+)$

整数が 0 の場合 → 合格。それ以外の場合 → 次のメッセージを表示して失敗します："最新の code-review-report.md に未解決の Must Fix 項目があります。Must Fix open: 0 になるまで flows-code-review を再実行してください。"

Status 行も Must Fix 行もない場合 → 次のメッセージを表示して失敗します："最新のコードレビュー レポートに Summary ブロックがありません。flows-code-review を再実行してください。"

ステップ 3 — デザインレビューを確認する

最新のコミット済みラウンドレポートを見つけます。

git ls-files 'reviews/design-review/' | grep 'design-review-report.md' | sort -V | tail -1

結果がない場合 → 次のメッセージを表示して失敗します："まず flows-design-review を実行してから、成果物をコミットしてください。"

その design-review-report.md から Summary ブロックを解析します。

Summary ブロックに ^- Status: SKIPPED$ に一致する行が含まれている場合 → このチェックを SKIPPED として扱い（PASS でも FAIL でもありません）、数値チェックをスキップします。このスタブはステップ 0 のエアハッチによるもので、レビュー担当者には SKIPPED のステータスが表示されます。

それ以外の場合、次に一致する行が含まれている必要があります。

^- Average score: (\d+(?:\.\d+)?)$

数値が 3.8 以上の場合 → 合格。それ以外の場合 → 次のメッセージを表示して失敗します："デザインレビューの平均スコアがリリース基準（3.8）を下回っています。最新の design-review-report.md にある Must Fix 項目と Should Fix 項目に対応し、新しいフィードバックラウンドで flows-design-review を再実行してください。"

ステップ 4 — 認定成果物がコミット済みであることを確認する

apps submit は git archive HEAD を使用します。未コミットのファイルはソースアーカイブから黙って除外されます。3 つの認定成果物が追跡対象になっていることを確認します。

git ls-files --error-unmatch App-Brief.md 2>/dev/null
git ls-files --error-unmatch "<latest-code-review-report-path>" 2>/dev/null
git ls-files --error-unmatch "<latest-design-review-report-path>" 2>/dev/null

これらのファイルのうちいずれかが未コミットの場合 → 次の内容で BLOCK します。

"次の認定ファイルが git にコミットされていません。apps submit は git archive HEAD を使用し、これらのファイルをソースアーカイブから黙って除外するため、レビュー担当者には表示されません。\n\n次を実行してください。\n git add \n git commit -m 'chore: add certification artifacts'\n\nその後、このスキルを再実行してください。"

すべての認定成果物がコミット済みで、作業ツリーにほかの未コミット変更がある場合 → WARN（ブロックしません）。

"認定成果物以外に未コミットの変更があります。apps submit は git archive HEAD を使用するため、これらの変更は提出するソースアーカイブに含まれません。認定に含める必要がある場合は、先にコミットしてください。"

ステップ 5 — デプロイバンドルを確認する

ls .cognite-bundles/*.zip 2>/dev/null | head -1

バンドルが存在しない場合 → WARN（ブロックしません）：".cognite-bundles/ にデプロイバンドルが見つかりません。提出するソースアーカイブとデプロイ済みバンドルが同じコードから作成されるように、まず npx @cognite/cli apps deploy を実行してください。"

バンドルが存在する場合は、HEAD より古いかどうかを確認します。

bundle=$(ls -1t .cognite-bundles/*.zip 2>/dev/null | head -1)
if [ -n "$bundle" ]; then
  bundle_mtime=$(stat -f %m "$bundle" 2>/dev/null || stat -c %Y "$bundle")
  head_time=$(git log -1 --format=%ct HEAD)
  if [ "$bundle_mtime" -lt "$head_time" ]; then
    echo "WARN"
  fi
fi

バンドルが HEAD より古い場合 → WARN（ブロックしません）。

".cognite-bundles/ にあるデプロイバンドルは、現在の HEAD コミットより古いものです。認定レビュー担当者は、デプロイ済みバンドルと提出されたソースを比較します。前回のデプロイ後に変更をコミットしている場合、両者は一致しません。提出前に npx @cognite/cli apps deploy を再実行してください。（npm run build だけではバンドルは更新されません。更新されるのは apps deploy を実行した場合のみです。）"

ステップ 6 — 合否テーブルを出力する

次のようなテーブルを出力します。

Check                                  Result
-----                                  ------
App-Brief.md complete                  PASS / FAIL — reason
Code review Must Fix open: 0           PASS / FAIL / SKIPPED — reason
Design review average ≥ 3.8            PASS / FAIL / SKIPPED — reason
Certification artifacts committed      PASS / FAIL — reason
Deploy bundle present and current      PASS / WARN — reason

SKIPPED はコードレビューとデザインレビューの行にのみ適用され、ステップ 0 のエアハッチがスタブを書き込んだ場合に限ります。SKIPPED の行には注記 SKIPPED — user opted out via Step 0 air-hatch を表示します。

いずれかのチェックが FAIL の場合：ここで停止します。CLI は実行しないでください。ユーザーが次に実行すべきスキルを正確に表示してください。SKIPPED の行はブロックしません。ステップ 7 に進み、明示的な確認を追加します。

Step 7 — 確認して送信する

いずれかのチェックが SKIPPED の場合は、確認プロンプトの先頭に明示的な警告を追加します。

"警告 — 次のレビューは SKIPPED です：。Cognite の認定審査担当者には、提出されたレポートに SKIPPED のステータスが表示され、承認前に実際のレビューを求められます。それでも送信を続行しますか？"

それ以外の場合（すべて PASS で、警告は問題なし）は、標準の確認プロンプトを使用します。

"すべての認定チェックに合格しました。今すぐ npx @cognite/cli apps submit を実行しますか？リポジトリを zip 化し、Zendesk の提出フォームに事前入力します。"

yes の場合：

npx @cognite/cli@latest apps submit

出力をユーザーにストリーミングします。

Step 8 — 提出後の引き継ぎ

このスキルが Bash 経由で apps submit を実行すると、CLI は非対話モードで実行され（process.stdout.isTTY === false）、ブラウザーの自動起動／ファイルマネージャーでの表示の手順をスキップします。CLI はファイル一覧、画面録画のプロンプト、Zendesk の URL を引き続き表示しますが、これらの操作はユーザーが手動で行う必要があります。

CLI の実行が終わったら、次の内容をユーザーに表示します。

CLI は非対話モードで実行されたため、ブラウザーもファイルマネージャーも開きませんでした。完了するには、次の操作を行ってください。

1. 上記の CLI 出力にある Zendesk の URL を開きます。この URL を開くには support.cognite.com へのサインインが必要です。アカウントをお持ちでない場合は作成してから、リンクに再度アクセスしてください。
2. ファイルマネージャーで dist/submit/ を開き、認定対象のユーザージャーニーを短く画面録画して追加します。
3. dist/submit/ 内のすべてのファイル（ソースアーカイブ、デプロイバンドル、画面録画）を Zendesk チケットに添付します。
4. ブランチが origin より先行している場合は、コミットをプッシュします。

次に git status --short --branch を実行し、ブランチが origin より先行している場合は、手順 4 の下に先行／遅延コミット数を明示します。

Stub templates (used by Step 0 air-hatch)

Step 0 でユーザーが Quick submit (stubs) を選択した場合は、次の正確なテンプレートを使用して、不足しているレポートを作成します。親ディレクトリが存在しない場合は、先に作成してください。

コードレビューのスタブ

Path: reviews/code-review/feedback-round-0/code-review-report.md

# Code Review Report — Round 0

**Status: SKIPPED** — user opted out of `flows-code-review` at submit time.

The Cognite certification reviewer will see this SKIPPED status and request a real `flows-code-review` run before approval. Re-run `flows-code-review` to replace this stub with a real round.

## Summary

- Status: SKIPPED
- Must Fix open: 0
- Should Fix open: 0
- Nit open: 0

デザインレビューのスタブ

Path: reviews/design-review/feedback-round-0/design-review-report.md

# Design Review Report — Round 0

**Status: SKIPPED** — user opted out of `flows-design-review` walkthrough at submit time.

The Cognite certification reviewer will see this SKIPPED status and request a real `flows-design-review` walkthrough before approval. Re-run `flows-design-review` to replace this stub with a real round.

## Summary

- Status: SKIPPED
- Average score: N/A