スクリプト説明コメントを規格化

[YukiWorks432]

概要

Issue #42 に対応し、スクリプトの説明コメントを半構造化形式へ統一しました。

• 正本文書 docs/script-comment-block.md を追加
• pnpm new の通常版・ScriptUI版と pnpm add-app の example/index.ts に5項目のTODO雛形を追加
• 作成スキルとExtendScript編集指示へ規格を反映
• 作成スキルの完了報告へ Material Symbols 候補名または確認不能時のTODOを追加
• Google Fonts から公式リポジトリへ切り替える確認手順を明記
• After Effects、Illustrator、Photoshopの既存例を完成例へ更新
• README、プロジェクト概要、導入・初心者ガイドの生成例を整合

Issue: #42

対象外

• コメント専用のリンター、構文検査、検証コマンドの追加
• src/tests/index.ts への説明ブロック追加
• 個人用スクリプトの一括移行
• Material Symbols の画像・フォント資産の同梱
• KBar 固有設定やアイコン画像生成
• コメント保持を目的としたビルド設定の変更

Validation

対象 head SHA: da5d10deaa8fc4dec0bf8f2bfdb989cb51678cb9

• pnpm exec prettier --write <変更ファイル>: pass
• pnpm lint: pass
• pnpm test: pass（5件）
• pnpm build --all: pass（4件）
• 通常版・ScriptUI版・pnpm add-app の一時生成確認: pass（前段コミット）
• 生成された3アプリの .jsx に5項目の説明ブロックが保持されることを確認: pass
• レビュー指摘: 完了報告への候補名またはTODO記載を追加
• レビュー指摘: 公式リポジトリへの確認先切り替えを追加
• レビュー指摘: ScriptUI例のスクリプト名を整合
• git diff --check: pass
• gh signoff: pass
• gh signoff status --branch develop: ✓ signoff

版・リリースへの影響

版番号、タグ、リリース設定は変更しません。

残存リスク

Material Symbols の公式一覧へ接続できない環境では、作成スキルが指定のTODOを残します。候補名の自動選択は用途の記述に依存します。

再開点

最新head SHAに対する独立レビューでREADYを確認します。

[YukiWorks432]

独立レビュー結果

判定: FIX_REQUIRED

対象は develop（base 6cf756ef165946042a94b58309b5659213693248）から feature/issue-42-script-comment-standard（head ea44a3359c717bfaad3633541f9631630b937a23）への差分で固定しています。

中: Issue #42 の「Material Symbols候補」節には、作成完了報告で実際に記載した候補名を示す要件があります。作成スキルは自動選択とファイル確認を指示していますが、スケルトン完了／実装完了 の報告項目に候補名（公式確認不能時は規定の TODO）を示す指示がありません。両方の完了報告へ明示的に追加してください。

その他の受け入れ条件、Node.js 22/24 のCI、signoff、未解決レビューの有無は確認済みです。

[YukiWorks432]

独立レビュー結果（$review-pr）

判定: FIX_REQUIRED

対象を次で再確認し、固定しました。

• リポジトリ: YukiWorks432/extendscript-ts-template
• PR: スクリプト説明コメントを規格化 #51（open / Draft）
• base: develop @ 6cf756ef165946042a94b58309b5659213693248
• head: feature/issue-42-script-comment-standard @ d8b4da9444023d4256b28ac11dcf37f8d5b78da4
• Issue: スクリプト説明コメントを規格化し、Material Symbols候補を記載する #42「スクリプト説明コメントを規格化し、Material Symbols候補を記載する」
• 差分: base が merge base、head は 2コミット先行、12ファイル
• スタック情報: なし（develop 直下の単独 feature PR）

阻害事項

• 中 — .agents/skills/add-script/SKILL.md:148-157 は Google Fonts を参照できない時点で TODO を残します。しかし Issue スクリプト説明コメントを規格化し、Material Symbols候補を記載する #42 と正本文書は、先に Google 公式の material-design-icons リポジトリ の symbols / update/current_versions.json を確認し、両方へ接続できない場合だけ TODO とする契約です。Google Fonts だけが利用不能でリポジトリへ接続できる場合に、公式確認済みの3候補を記載できません。正本文書の 該当手順 と同じ確認順へ直してください。
• 中 — docs/project-overview.md:159-177 の ScriptUI 例は @script MyPanel なのに entryUI、entry、TODO本文が MyScript のままです。Issue スクリプト説明コメントを規格化し、Material Symbols候補を記載する #42 の「@script をディレクトリ名・設定名と完全一致」の規則、および生成例の整合性に違反するため、例内の名前を統一してください。

仕様適合

1. 通常版・ScriptUI版 pnpm new の5項目雛形: 満たす（scripts/newScript.mjs:221-275）
2. pnpm add-app の example/index.ts 雛形: 満たす（scripts/addApp.mjs:30-39,383-390）
3. 作成スキルで説明・手順・公式確認済み3候補を自動記載: 未達（公式確認先の切替手順が欠落）
4. 公式確認不能時だけ規定TODOを残す: 未達（Google Fontsのみの障害でもTODOへ進む）
5. 既存3アプリの完成例: 満たす（各 index.ts の5項目、順序、候補名、内容を確認）
6. ビルド後の .jsx への説明ブロック保持: 満たす（PR本文の対象SHA付き手動確認、既存Rollupの @description 保持設定と整合）
7. 品質ゲートと git diff --check: 満たす（対象headのCI Node.js 22/24が全工程成功）

技術品質・証跡

CI run #7 の Node.js 22/24 はともに成功し、対象headの signoff status も成功です。未解決レビュー・レビュー提出はありません。過去のトップレベルコメントは旧head ea44a3359c717bfaad3633541f9631630b937a23 に対するもので、現headの未解決スレッドではありません。版番号・タグ・リリース設定の変更もありません。

修正後にheadを更新し、同じ固定確認を新しいSHAで再レビューしてください。

[YukiWorks432]

独立レビュー結果（$review-pr）

判定: READY

対象

• リポジトリ: YukiWorks432/extendscript-ts-template
• PR: スクリプト説明コメントを規格化 #51（open / Draft）
• base: develop @ 6cf756ef165946042a94b58309b5659213693248
• head: feature/issue-42-script-comment-standard @ da5d10deaa8fc4dec0bf8f2bfdb989cb51678cb9
• Issue: スクリプト説明コメントを規格化し、Material Symbols候補を記載する #42「スクリプト説明コメントを規格化し、Material Symbols候補を記載する」
• 比較: base が merge base、head は3コミット先行、差分は12ファイル。運営方針に沿う単独の feature/* -> develop で、スタック情報はありません。

阻害事項

阻害事項なし。

仕様適合

1. 満たす — pnpm new の通常版・ScriptUI版が、ファイル先頭に5項目を正しい順序で生成する（scripts/newScript.mjs:221-275）。
2. 満たす — pnpm add-app の example/index.ts に同じ雛形を生成する（scripts/addApp.mjs:30-39,383-390）。
3. 満たす — 作成スキルがスケルトン時も説明・処理手順を完成させ、公式確認済みの異なる3候補を利用者への確認なしに選び、アルファベット順で記載する（.agents/skills/add-script/SKILL.md:125-159,177-202）。
4. 満たす — Google Fonts と公式の material-design-icons リポジトリの双方を確認できない場合だけ、規定の TODO を残す（同 SKILL.md:148-159）。
5. 満たす — After Effects、Illustrator、Photoshop の3例に、5項目・完成した説明・手順・候補を記載する（各 src/*/example/index.ts:1-12）。候補は公式リポジトリの symbols:: 一覧に存在し、重複なくアルファベット順です。
6. 満たす — コメント抽出と @description 保持の設定により、通常版・ScriptUI版のビルド後もブロック全体が残る経路を確認した（rollup.config.mjs:298-311,480-481）。
7. 満たす — 対象headの CI run feat: 各アプリ階層のlib が、グローバルなlibを再exportするように。 #8 は Node.js 22/24 とも成功し、PR差分にも追加行の末尾空白はありません。

技術品質・証跡

• 正本 AGENTS.md、docs/repository-operations.md、Issue本文・コメント（追加コメントなし）を確認しました。
• PR本文の対象head SHA、CI、signoffを照合しました。CI run feat: 各アプリ階層のlib が、グローバルなlibを再exportするように。 #8 は全工程成功、headの signoff status は成功です。
• レビュー提出は0件、未解決レビュー・スレッドは0件です。版番号、タグ、リリース設定の変更もありません。
• 公式候補の存在確認は Google公式リポジトリ の update/current_versions.json にある symbols:: 項目で再確認しました。
• PR本文の生成器一時確認は「前段コミット」と明記されていますが、最終コミットの変更対象は作成スキルとプロジェクト概要だけで、生成器コードは変わっていません。現headの生成器・ビルド経路を静的に再確認し、CIの現headビルドも成功しているため、判定を阻害する差はありません。

残存リスク・確認限界

After Effects等の実機実行、ネットワーク遮断時のスキル分岐そのものは実行していません。これらは既存運営方針・Issueの対象範囲に従う手動確認／手順確認です。コメント専用の自動検査はIssueの対象外です。

このREADYは da5d10deaa8fc4dec0bf8f2bfdb989cb51678cb9 にのみ適用します。