printing-press-output-review

printing-press-output-review（内部）

印刷された CLI のサンプル出力を確認し、dogfood、verify、およびルールベースの scorecard --live-check ルールでは検出できない妥当性に関するバグを探します。Wave B ポリシーでは、すべての検出事項を警告として表示し、エラーとして表示することはありません。

このスキルは内部専用です（user-invocable: false）。呼び出し元であるメインの printing-press スキルの shipcheck Phase 4.85 と、printing-press-polish スキルの診断ループから呼び出されます。単独で実行すると、船積み判定も修正の適用も公開の提案もないまま、検出事項のテキストだけが出力されます。実行可能なラッパーは /printing-press と /printing-press-polish です。このスキルは context: fork を指定しているため、レビュアーエージェントの診断時のやり取りは、呼び出し元のスキルのコンテキストから分離されます。

入力

呼び出し元は、印刷された CLI の作業ディレクトリの絶対パスを引数として $CLI_DIR に渡します。

検出対象

ルールベースのチェックでは見逃されるバグです。通常は 5 分ほどの手動テストで見つかりますが、dogfood、verify、および scorecard --live-check のルールをすり抜けます。

• 部分文字列の一致結果が、意味的には一致しないのに偶然クエリを含んでいる（たとえば、大きく無関係な用語の一部にクエリが一致する）
• 要求した N 件の一部しか返ってこない場合に、集約コマンドが一部のソースを黙って除外する
• ランキングまたはソートコマンドが、クエリに対して妥当な上位 N 件の結果を返さない（重み付けの不具合、抽出処理のフォールバック）
• 出力内の URL が、正規コンテンツのパーマリンクではなく、カテゴリのインデックスページ、フィードエンドポイント、またはランダム選択ルートを指している
• ルールベースのレイヤーでは検出できない形式の不具合（文字化け、複数形の不統一、セルの内容の切り詰めや折り返し）

手順

Step 1：サンプルデータを収集する

# Locate research.json. Adjacent to the binary covers the post-promote
# layout (standalone polish, shipcheck against the library copy). The
# grandparent fallback covers mid-pipeline invocations where $CLI_DIR is
# $PRESS_RUNSTATE/runs/<id>/working/<cli> and research.json lives at
# $PRESS_RUNSTATE/runs/<id>/research.json. Without the fallback, scorecard
# reports `unable: true` mid-pipeline and we SKIP the most informative review.
# Use a bash array so the flag survives paths with spaces.
RESEARCH_ARGS=()
if [ ! -f "$CLI_DIR/research.json" ]; then
  _grandparent="$(dirname "$(dirname "$CLI_DIR")")"
  if [ -f "$_grandparent/research.json" ]; then
    RESEARCH_ARGS=(--research-dir "$_grandparent")
  fi
fi

cli-printing-press scorecard --dir "$CLI_DIR" "${RESEARCH_ARGS[@]}" --live-check --json > /tmp/output-review-livecheck.json 2>&1 || true

scorecard の呼び出しに失敗した場合、または /tmp/output-review-livecheck.json が空の場合は、レビュアーを呼び出さずに SKIP の結果（Step 3）を返します。

呼び出す前に、live_check.review_status フィールドがある場合はその値を読み取ります。 値が skipped の場合、または live_check.features[] に status が pass の項目が 1 つもない場合は、理由を no eligible passing samples; plausibility not assessed として SKIP を返します。レビュアーを呼び出してはいけません。レビューがスキップされたことは合格を意味しません。サンプル対象のコマンドがすべて失敗または除外されたというだけで、 status: PASS を出力したり、結果を問題のないレビューと表現したりしてはいけません。

ステップ 2：レビュアーエージェントを起動する

Agent ツール（汎用）を使い、次のプロンプト契約を指定します。

$CLI_DIR にあるリリース済み CLI のサンプル出力をレビューしてください。次の正解データを参照できます。

• サンプルコマンド出力：/tmp/output-review-livecheck.json を読み込み、live_check.features[] 配列を確認してください。各エントリには、コマンド、実行例、編集済みの stdout 証拠（output_sample 内、約 4 KiB 以内）、編集済みの合否理由、警告の配列（raw HTML エンティティ検出器などのルールベースのチェックで設定）が含まれています。<redacted> マーカーはプライバシー保護のために値を置き換えたものであり、フォーマットの不具合ではありません。
• status: pass のエントリのみレビューしてください。 status: fail のエントリは、クラッシュ、タイムアウト、または実際の出力が得られないプレースホルダー引数（<id>、<url>）が原因です。サンプルは空であり、判断材料はありません。
• $CLI_DIR/research.json の novel_features（機能ごとの予定動作）と novel_features_built（ビルドが検証済みのコマンド）。
• $CLI_DIR/<cli-name>-pp-cli にある CLI バイナリ。指摘の確認が必要な場合は、追加のコマンドを実行してもかまいません。

次の各チェックについて、人が 5 分間の実地テストで気づくような問題だけを報告してください。報告は各項目 50 語未満にしてください。徹底的な QA で見つかるような、あらゆるエッジケースを報告する必要はありません。

1. 出力がクエリの意図と意味的に一致しているか。 クエリ引数がある新機能のサンプルについて、live-check が機械的に行ったクエリトークン検査を超えて関連性を判断してください。live-check の outputMentionsQuery テストに合格した機能でも、出力のどこかにクエリのトークンが含まれているだけの場合があります。「buttermilk」が「butter」の検索結果に部分文字列として現れるケースや、抽出処理が隣接するコンテンツにフォールバックした結果、「brownies」の検索でチリのレシピが返るケースは、機械的な検査をすり抜けます。人が上位の結果を見て「これは頼んだものと違う」と感じる場合に限り、指摘してください。実行例にクエリ引数がない場合、このチェックは省略してください。
2. 明らかなフォーマット不具合がないか。 出力に生の HTML エンティティ、文字化け（タイトル内の疑問符や置換文字）、不正な URL（正規のコンテンツパーマリンクではなく、カテゴリのインデックスページ、フィードエンドポイント、ランダム選択ルートを指すもの）が含まれていないか確認してください。ルールベースの live-check では数値エンティティを検出します。このチェックでは、より広い種類の不具合を見つけてください。
3. 集約コマンドが要求されたすべてのソースを表示しているか。 --source／--site／--region の CSV フラグがあるコマンドについて、ユーザーが N 個のソースを要求した場合、出力に N 個表示されますか。それとも、不足しているものについて stderr に説明がありますか。ファンアウトコマンドで失敗したソースが何も通知されずに除外されるのは、よくある重大な不具合です。
4. 結果の順序やランキングが妥当か。 ランク付けや並べ替えを行うとうたうコマンドについて、クエリを踏まえて最上位の結果がもっともらしく最良の結果になっているか確認してください。スコアの重み付けの不具合、ソートの 1 件ずれ、関連性の計算に失敗した際の、通知のない更新日時順へのフォールバックに注意してください。

learn-loop コマンドのサンプル（recall、learnings、playbook）に関する調整：初回の表示時はローカルの学習ストアが空のため、候補リストが空であること、learnings stats が 0 件を示すこと、「no learnings recorded」と表示されることは、妥当な動作である可能性があります。サイレントな失敗やデータ不足として指摘しないでください。

指摘事項のリストを返してください。各項目には、チェック名、重大度（Wave B では warning。error は Wave C 専用）、1 行の説明、1 文の修正提案を含めてください。CLI が 4 つのチェックすべてに合格した場合は、「PASS — 指摘事項なし」と返してください。

ステップ 3：構造化された結果ブロックを出力する

スキルの応答の最後に、親が解析する ---OUTPUT-REVIEW-RESULT--- ブロックを付けます。

問題なしの場合：

レビュー担当者が、対象となる status: pass のサンプルを少なくとも 1 つ評価した場合に限り、この結果を使用します。

---OUTPUT-REVIEW-RESULT---
status: PASS
findings: []
---END-OUTPUT-REVIEW-RESULT---

警告がある場合：

---OUTPUT-REVIEW-RESULT---
status: WARN
findings:
- check: <check-name>
  severity: warning
  description: <one-line>
  suggestion: <one-sentence>
- ...
---END-OUTPUT-REVIEW-RESULT---

レビュー担当者の失敗、または評価可能な出力がない場合（タイムアウト、エージェントの予算超過、ライブチェックデータの欠落、review_status: skipped、対象となる status: pass サンプルが 0 件）：

---OUTPUT-REVIEW-RESULT---
status: SKIP
reason: <one-line description>
findings: []
---END-OUTPUT-REVIEW-RESULT---

status: SKIP は合格ではありません。呼び出し元はこれをスキップとして報告し、合格したレビューとして数えてはいけません。

Wave B ポリシー（現行）

• すべての指摘は warning として表面化させます。error にはしません。Shipcheck はそのまま続行します。
• 呼び出し元は、実行の成果物ディレクトリ（例：manuscripts/<api>/<run>/proofs/phase-4.85-findings.md）に指摘を記録し、ユーザーに提示します。指摘は scorecard.json には保存しません。このパスは Wave C 用に確保されています。
• 出荷前に修正するかどうかは、ユーザーがケースごとに判断します。

非対話型の契約（CI、cron、一括再生成）：

• stdout が TTY でない場合、呼び出し元はログ記録を伴うフェイルオープン方式に従います。指摘は記録され、プロンプトを表示せずに Shipcheck は続行します。
• status: SKIP（レビュー担当者のクラッシュ、タイムアウト、データの欠落）は情報として扱います。Shipcheck はこれによってブロックされません。
• --auto-approve-warnings フラグはまだありません。Wave B ではすでに「警告ではブロックしない」ポリシーであるため、このフラグでゲートを制御しても効果はありません。

Wave C（今後の別 PR）では、ライブラリ全体のキャリブレーションデータで誤検出率が 10% 未満になった後、error 重大度の指摘をブロッキングに切り替えます。

エージェント方式をテンプレート方式のみより選ぶ理由

出力の妥当性に関する質問は、ソースとのパターンマッチでは判定できません。ルールベースのライブチェックルールで対応できるのは、正規表現で検出可能なもの（数値文字参照、クエリトークンの不在）です。それ以外のすべて――「これらの置換結果はクエリに対して妥当と思われるか？」「検索結果のトップ項目は関連性がありそうか？」――は LLM を必要とする質問です。トークンコストは上限が決まっており（コマンドごとではなく、実行ごとに 1 回）、このフェーズのきっかけとなったバグの種類に対する検出率を考慮すれば、ディスパッチする価値があります。

既知の盲点

• 数値の正確性（価格、評価、ランキングと正解データとの比較）は検証できません。CLI がレシピの評価を 4.8 と表示していて、実際は 4.2 だったとしても、このスキルでは検出できません。
• データの鮮度に関する問題（レシピの公開年が 2024 年ではなく 2019 年など）は検出できません。これには信頼できる情報源とのライブ比較が必要です。
• 主観的な好み（「チョコチップクッキーに最適なレシピか？」）は判断できません。
• サンプリングした出力のみが対象です。live_check.features[] に含まれるコマンドをカバーします。コマンドツリー全体のカバレッジは、このレビューではなく、メインの printing-press スキルの Phase 5 dogfood が担います。
• 英語以外の出力：レビュー担当者のクエリ意図チェックは、英語のクエリと出力を前提としています。英語以外の CLI については、プロンプトを別途調整してください。