printing-press-polish

/printing-press-polish

生成された CLI を磨き上げ、検証に合格して公開できる状態にします。

レトロスペクティブでは Printing Press を改善します。Polish では生成された CLI を磨き上げます。このスキルはフォークされたコンテキスト（context: fork）で実行されるため、診断と修正のループが呼び出し元に影響しません。診断メッセージ、修正の反復、再診断のノイズは polish セッション内に留まり、呼び出し元にはクリーンな要約が返されます。

/printing-press-polish redfin
/printing-press-polish redfin-pp-cli
/printing-press-polish "$PRESS_LIBRARY/redfin"

実行するタイミング

/printing-press による生成後に実行してください。特に、次の場合に適しています。

• shipcheck の判定が ship-with-gaps の場合
• verify の合格率が 80% 未満の場合
• スコアカードが 85 未満の場合
• CLI を一度で公開可能な状態にしたい場合

$PRESS_LIBRARY/ 内にある任意の CLI に対して、単独で実行することもできます。

セットアップ

# min-binary-version: 4.0.0

PRESS_HOME="${PRINTING_PRESS_HOME:-$HOME/printing-press}"
PRESS_LIBRARY="$PRESS_HOME/library"

_pp_check_disk_space() {
  _pp_disk_warn_kb="${PRINTING_PRESS_DISK_WARN_KB:-3145728}"
  _pp_disk_fail_kb="${PRINTING_PRESS_DISK_FAIL_KB:-524288}"
  case "$_pp_disk_warn_kb$_pp_disk_fail_kb" in
    ""|*[!0-9]*) return 0 ;;
  esac

  _pp_disk_path="$PRESS_HOME"
  while [ ! -e "$_pp_disk_path" ] && [ "$_pp_disk_path" != "/" ]; do
    _pp_disk_path="$(dirname "$_pp_disk_path")"
  done

  _pp_disk_avail_kb="$(df -Pk "$_pp_disk_path" 2>/dev/null | awk 'BEGIN {
    if ((getline header) <= 0 || (getline record) <= 0) exit
    field_count = split(record, fields)
    if (field_count >= 4) print fields[4]
  }')"
  case "$_pp_disk_avail_kb" in
    ""|*[!0-9]*) return 0 ;;
  esac

  if [ "$_pp_disk_avail_kb" -lt "$_pp_disk_fail_kb" ]; then
    echo ""
    echo "[setup-error] Critically low disk space on the Printing Press workspace volume."
    echo "PRESS_DISK_PATH=$_pp_disk_path"
    echo "PRESS_DISK_AVAIL_KB=$_pp_disk_avail_kb"
    echo "PRESS_DISK_FAIL_KB=$_pp_disk_fail_kb"
    echo "Free disk space or set PRINTING_PRESS_HOME to a volume with more room, then re-run this skill."
    echo ""
    return 1
  fi

  if [ "$_pp_disk_avail_kb" -lt "$_pp_disk_warn_kb" ]; then
    echo ""
    echo "[low-disk] Printing Press workspace volume is low on free space."
    echo "PRESS_DISK_PATH=$_pp_disk_path"
    echo "PRESS_DISK_AVAIL_KB=$_pp_disk_avail_kb"
    echo "PRESS_DISK_WARN_KB=$_pp_disk_warn_kb"
    echo "This flow may need several GiB for generated files, Go build cache, module downloads, or repository clones."
    echo ""
  fi
}
_pp_check_disk_space || { return 1 2>/dev/null || exit 1; }

# Mid-pipeline callers may pass printing_press_bin: <abs-path> in the args
# bundle. Prefer it so forked polish runs keep using the parent skill's
# preflight-selected binary instead of re-resolving through PATH.
PRINTING_PRESS_BIN="${PRINTING_PRESS_BIN:-}"
if [ -z "$PRINTING_PRESS_BIN" ] && [ -n "${ARGUMENTS:-}" ]; then
  PRINTING_PRESS_BIN="$(printf '%s\n' "$ARGUMENTS" | sed -nE 's/^[[:space:]]*printing_press_bin:[[:space:]]*(.+)$/\1/p' | head -1)"
fi
if [ -z "$PRINTING_PRESS_BIN" ]; then
  PRINTING_PRESS_BIN="$(command -v cli-printing-press 2>/dev/null || true)"
fi

if [ -z "$PRINTING_PRESS_BIN" ]; then
  echo "cli-printing-press binary not found."
  echo "Install with:  go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest"
  return 1 2>/dev/null || exit 1
fi
if ! command -v go >/dev/null 2>&1; then
  echo ""
  echo "[setup-error] Go toolchain not found."
  echo ""
  echo "This Printing Press flow runs Go-based build or validation commands."
  echo "Install Go 1.26.9 or newer from https://go.dev/dl/, then verify with:"
  echo "  go version"
  echo "Then re-run this skill."
  echo ""
  return 1 2>/dev/null || exit 1
fi
echo "PRINTING_PRESS_BIN=$PRINTING_PRESS_BIN"

_pp_semver_lt() {
  if [ -z "${PP_SEMVER_A:-}" ] || [ -z "${PP_SEMVER_B:-}" ]; then
    echo "[setup-error] semver comparison inputs are missing." >&2
    return 2
  fi
  awk -v a="${PP_SEMVER_A:-}" -v b="${PP_SEMVER_B:-}" 'BEGIN {
    split(a, x, "."); split(b, y, ".")
    for (i = 1; i <= 3; i++) {
      if ((x[i] + 0) < (y[i] + 0)) exit 0
      if ((x[i] + 0) > (y[i] + 0)) exit 1
    }
    exit 1
  }'
}

_pp_go_version_norm() {
  printf '%s\n' "${PP_GO_VERSION_INPUT:-}" | sed -nE 's/.*go([0-9]+)\.([0-9]+)(\.([0-9]+))?.*/\1.\2.\4/p' | sed -E 's/\.$/.0/'
}

_pp_check_go_currency() {
  _pp_go_installed="$(PP_GO_VERSION_INPUT="$(go env GOVERSION 2>/dev/null)" _pp_go_version_norm)"
  _pp_go_required="$(PP_GO_VERSION_INPUT="$(go version "$PRINTING_PRESS_BIN" 2>/dev/null)" _pp_go_version_norm)"
  PP_SEMVER_A="$_pp_go_installed"
  PP_SEMVER_B="$_pp_go_required"
  if [ -z "$_pp_go_installed" ] || [ -z "$_pp_go_required" ] || ! _pp_semver_lt; then
    return 0
  fi

  echo ""
  if [ "${GOTOOLCHAIN:-auto}" = "local" ]; then
    echo "[setup-error] Go $_pp_go_required or newer is required by this cli-printing-press binary (installed: $_pp_go_installed)."
    echo "GOTOOLCHAIN=local disables automatic toolchain downloads, so later Go quality gates would fail."
    echo "Install Go $_pp_go_required or newer from https://go.dev/dl/, or unset GOTOOLCHAIN."
    echo ""
    return 1
  fi

  echo "[go-toolchain-old] Go $_pp_go_required or newer is required by this cli-printing-press binary (installed: $_pp_go_installed)."
  echo "PRESS_GO_INSTALLED=$_pp_go_installed"
  echo "PRESS_GO_REQUIRED=$_pp_go_required"
  echo "Default GOTOOLCHAIN behavior may download the required toolchain during Go commands."
  echo ""
  return 0
}
_pp_check_go_currency || { return 1 2>/dev/null || exit 1; }

セットアップ後、PRINTING_PRESS_BIN=<abs-path> を記録し、このスキル内の cli-printing-press ... の呼び出しにはすべて、その絶対パスを使用してください。セットアップで [go-toolchain-old] または [low-disk] が出力された場合は、ユーザーに注意事項を伝えたうえで続行してください。ただし、[setup-error] も出力された場合は続行しないでください。[go-toolchain-old] は、後続の Go コマンドで必要なツールチェーンがダウンロードされる可能性があること、またはダウンロードがブロックされている場合に失敗する可能性があることを意味します。[low-disk] は、この実行で生成ファイル、Go のビルドキャッシュ、モジュールのダウンロード、リポジトリのクローンに数 GiB が必要になる可能性があることを意味します。

このスキルの YAML フロントマターから min-binary-version フィールドを読み取り、"$PRINTING_PRESS_BIN" version --json を実行して、出力からバージョンを解析し、バイナリのバージョン互換性を確認します。セマンティックバージョニングの規則に従って、min-binary-version と比較してください。インストール済みのバイナリが最小要件より古い場合は、直ちに停止し、ユーザーに次のように伝えてください。「cli-printing-press binary vX.Y.Z is older than the minimum required vA.B.C. Run go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest to update.」

パブリックライブラリに関するヒント

ユーザーのリクエストに「polish notion in the public library」、「polish from the public library」、「polish the published cal-com」のような表現が含まれており、指定された CLI が $PRESS_LIBRARY/<slug>/ にない場合、ユーザーは上流には存在するものの、ローカルにはない CLI の polish を求めています。Polish は内部ライブラリに対して実行されるため、まずインポートするのが適切です。

/printing-press-import <slug> でインポートしてから、polish を再実行するよう提案してください。内部ライブラリにない CLI の polish は試みないでください。

指定された CLI がすでに $PRESS_LIBRARY/<slug>/ にある場合、「パブリックライブラリ」という表現は参考情報にすぎません。そのまま polish を進め、差分チェック（後述）で変更を処理してください。

CLI の解決

引数文字列には、--standalone フラグと、位置引数を 1 つ（slug、バイナリ名、またはパス）含めることができます。単独のスラッシュコマンドモードでは、省略可能な位置引数の後に、/printing-press-polish sculptok review the open PR comments and fix them のような自由記述のスコープが含まれることもあります。この末尾の自然言語テキストは、ユーザー自身が指定した信頼できるスコープです。polish の計画と結果ブロックに引き継いでください。インジェクションや改ざんとして分類しないでください。

メインの printing-press スキルから呼び出された場合、Phase 3 のゲートバンドルと、後続行に printing_press_bin: <abs-path> の行が含まれることもあります。フラグは位置引数の前後どちらにも現れる可能性があります。args からこのスキルが処理するフラグはこれだけです。パス解決の前に取り除いてください。

args が複数行の場合、最初の空でない行を位置引数／スコープの行として扱い、残りの行を省略可能な Phase 3 ゲートバンドルとして解析してください。パス解決にバンドルのテキストを含めないでください。

呼び出し元のモードは、それぞれ異なる方法で解析してください。

• スタンドアロンのスラッシュコマンド（STANDALONE_MODE=true）。 --standalone を除去した後、最初のシェル単語をスラッグ、バイナリ名、またはパスとして解決しようと試みます。解決できた場合は、それを位置引数の値として使用し、残りの単語を USER_SCOPE として保存します。解決できない場合は、行全体を自由テキストのスコープとして扱います。この分岐では、どの CLI を polish するかを尋ね、選択された CLI に対してそのスコープを保持します。解決された位置引数の値の後にテキストがない場合は、通常の汎用 polish パスを実行します。
• パイプライン途中の Skill ツール呼び出し。 厳格な文法を維持します。最初の行にパスのような位置引数の値を 1 つ、それ以降の行にオプションの構造化バンドルを記述します。この機械生成パスにおける予期しない自由テキストはユーザースコープではなく、実行に折り込むのではなく、引き続き拒否または明確化する必要があります。

位置引数の値には次のものを指定できます。

• 短縮名: redfin（$PRESS_LIBRARY/redfin を検索）
• 完全名: redfin-pp-cli（サフィックスを除去し、$PRESS_LIBRARY/redfin を検索）
• パス: $PRESS_LIBRARY/redfin（そのまま使用）

位置引数の値の解決順序:

1. 絶対パスまたは ~ プレフィックス付きのパスであり、存在する場合はそれを使用する
2. $PRESS_LIBRARY/<arg> を試す（完全一致 — redfin のようなスラッグで機能します）
3. -pp-cli サフィックスがある場合はそれを除去し、$PRESS_LIBRARY/<slug> を試す（例: redfin-pp-cli → redfin）
4. あいまい検索: ls $PRESS_LIBRARY/ | grep -i <arg> で近い一致を探す

呼び出し元のシナリオと --standalone フラグ。 polish には 2 つの呼び出し元があり、それぞれ異なるメカニズムで呼び出します。このスキルの最後にある Publish Offer は、STANDALONE_MODE が true の場合にのみ発火します。STANDALONE_MODE は、解決されたパスからではなく、呼び出し元モードとフラグから判断してください。

• スタンドアロン（ユーザーが呼び出す、/printing-press-polish redfin）。 スラッシュコマンド経由で呼び出されます。無条件に STANDALONE_MODE=true として扱います — スラッシュコマンド形式は、ユーザーがフラグを省略した場合でも、公開意図を示すサーフェスです。引数はスラッグまたはバイナリ名で、解決は $PRESS_LIBRARY/<slug>/ に到達します。これが公開されたコピーであり、正しいターゲットです。
• パイプライン途中（メインの printing-press スキル Phase 5.5、hold-path「Polish to retry」）。 Skill ツール経由で args: "$CLI_WORK_DIR" を指定して呼び出されます。引数は ~/printing-press/.runstate/.../runs/.../working/<api>-pp-cli/ への絶対パスであり、解決は必ずルール 1 に到達する必要があります。STANDALONE_MODE=false がデフォルトです — このパスではメイン SKILL が公開フローを所有するため、polish は待機します。引数をスラッグに言い換えないでください — Phase 5.5 は working CLI が昇格される前に発火するため、$PRESS_LIBRARY/<slug>/ は存在しないか、前回の実行の古い CLI を保持しています。
• Skill ツールのスタンドアロン上書き。 polish に公開を真に望むスラッシュコマンド以外の呼び出し元は、args に --standalone を含めることで明示的にオプトインする必要があります（例: args: "--standalone $PRESS_LIBRARY/redfin"）。このトークンがなければ、polish は Skill ツール呼び出しから決して公開しません — 解決されたパスがたまたま $PRESS_LIBRARY/ 配下にある場合でも同様です。フラグが契約であり、パスではありません。

この呼び出し元モード駆動のゲートは、以前のパス部分文字列ヒューリスティック（*.runstate/*）を置き換えます。このヒューリスティックは、メイン SKILL の Phase 5.5/5.6 の順序が反転した場合、または polish が .runstate 以外のスクラッチレイアウトから呼び出された場合に破綻しました。polish は $PRESS_LIBRARY/<slug>/ パスを見て「スタンドアロン」と判断し、パイプライン途中の実行内で Publish Offer（フォーク、グローバル git config、公開 PR）を発火していました。フラグは曖昧さがなく、より安全なデフォルトは no-publish です。

Phase 3 ゲートバンドル

パイプライン途中の呼び出し元は、args 内の CLI パスの後に次のフィールドを渡します。

phase3_transcendence_rows_planned: <planned>
phase3_transcendence_rows_built: <built>
phase3_transcendence_rows_missing:
  - <manifest row name or command>
prior_sub60_reprint: <true|false>
partial_transcendence_override: <none or build-log note path>

診断の前にバンドルを解析し、値を出荷判定ロジックで使用できるように保持します。バンドルフィールドが欠けている場合は、「Phase 3 の保留を強制しない」ことを意味し、単独でのポリッシュを妨げません。prior_sub60_reprint: true で、phase3_transcendence_rows_missing にいずれかの行が含まれ、partial_transcendence_override が空または none の場合、ローカル診断に問題がなくても、ポリッシュでは ship_recommendation: hold を出力する必要があります。保留中の問題に不足している行を追加し、昇格を妨げた具体的なゲートを親スキルが表示できるようにします。

次のコードブロックにあるロック状態チェックは、パイプライン途中のシナリオにおけるセーフティネットです。この CLI のビルドロックが（どちらの名前形式でも）保持されている場合、ポリッシュは実行を拒否します。cli-printing-press lock は内部でスラッグとバイナリ名を正規化するため、ベース名がどちらの形式になっていてもチェックは機能します。

一致する項目がない場合、または複数ある場合は、AskUserQuestion で提示します。更新日時の新しい順に並べた一致項目を最大 4 件表示し、わかりやすい相対時刻（例：「2 時間前に生成」）を使用します。

CLI_DIR="<resolved path>"
CLI_NAME="$(basename "$CLI_DIR")"
STANDALONE_MODE="<true|false>"  # true iff slash-command invocation or --standalone in args; default false for Skill-tool invocations

# Check if there's an active build lock — polish edits would be overwritten
# when the running build promotes to library.
_lock_json=$("$PRINTING_PRESS_BIN" lock status --cli "$CLI_NAME" --json 2>/dev/null)
if echo "$_lock_json" | grep -q '"held".*true'; then
  if echo "$_lock_json" | grep -q '"stale".*true'; then
    echo "Warning: stale lock exists for $CLI_NAME (build may have crashed)."
    echo "Proceeding with polish. Run '$PRINTING_PRESS_BIN lock release --cli $CLI_NAME' to clear."
  else
    echo "An active build is in progress for $CLI_NAME."
    echo "Polish edits would be overwritten when the build promotes."
    echo "Wait for the build to finish, then run polish."
    exit 1
  fi
fi

# Verify it's a valid Go CLI
if [ ! -f "$CLI_DIR/go.mod" ]; then
  echo "Not a valid CLI directory: $CLI_DIR"
  exit 1
fi

echo "Polishing: $CLI_NAME"
echo "Location: $CLI_DIR"

仕様とリサーチディレクトリを検索

API_SLUG="${CLI_NAME%-pp-cli}"
SPEC_PATH=""
for f in "$PRESS_HOME/manuscripts/$API_SLUG"/*/research/*.yaml "$PRESS_HOME/manuscripts/$API_SLUG"/*/research/*.json "$PRESS_HOME/manuscripts/$CLI_NAME"/*/research/*.yaml "$PRESS_HOME/manuscripts/$CLI_NAME"/*/research/*.json; do
  if [ -f "$f" ]; then
    SPEC_PATH="$f"
    break
  fi
done

# Build the spec flag once. Empty when no spec was found — diagnostic
# commands accept a missing --spec and degrade gracefully.
SPEC_FLAG=""
if [ -n "$SPEC_PATH" ]; then
  SPEC_FLAG="--spec $SPEC_PATH"
fi

# Locate the research dir. dogfood's --research-dir triggers
# checkNovelFeatures, which writes novel_features_built back into
# research.json AND syncs the verified list into .printing-press.json.
# Without this flag, legacy CLIs whose manifest predates the
# novel_features schema fail publish-validate's transcendence gate.
#
# Two layouts to handle, keyed on $CLI_DIR path structure (NOT on the
# absence of a manuscripts entry — re-generating a previously-published
# API leaves stale manuscript entries from prior runs that would point
# scorecard at the wrong research.json):
#  1. Mid-pipeline polish (invoked from the main printing-press flow
#     before promote): $CLI_DIR is under $PRESS_RUNSTATE/.../runs/<id>/working/<cli>
#     (i.e. the path contains `.runstate/`), and research.json lives at
#     $PRESS_RUNSTATE/.../runs/<id>/research.json — $CLI_DIR's grandparent.
#  2. Post-promote (standalone polish): research.json lives at
#     manuscripts/<api>/<run-id>/research.json.
RESEARCH_DIR=""
MANIFEST_RUN_ID=""
if [ -f "$CLI_DIR/.printing-press.json" ]; then
  if command -v jq >/dev/null 2>&1; then
    MANIFEST_RUN_ID="$(jq -r '.run_id // empty' "$CLI_DIR/.printing-press.json" 2>/dev/null || true)"
  fi
  if [ -z "$MANIFEST_RUN_ID" ]; then
    MANIFEST_RUN_ID="$(sed -nE 's/.*"run_id"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' "$CLI_DIR/.printing-press.json" | head -1)"
  fi
fi
case "$CLI_DIR" in
  *.runstate/*)
    _grandparent="$(dirname "$(dirname "$CLI_DIR")")"
    if [ -f "$_grandparent/research.json" ]; then
      RESEARCH_DIR="$_grandparent"
    fi
    ;;
  *)
    if [ -n "$MANIFEST_RUN_ID" ]; then
      for base in "$PRESS_HOME/manuscripts/$API_SLUG" "$PRESS_HOME/manuscripts/$CLI_NAME"; do
        if [ -f "$base/$MANIFEST_RUN_ID/research.json" ]; then
          RESEARCH_DIR="$base/$MANIFEST_RUN_ID"
          break
        fi
      done
    fi
    # Match publish package's fallback: API slug first, then CLI name, each
    # using the lexicographically latest run id when the manifest has none.
    if [ -z "$RESEARCH_DIR" ]; then
      for base in "$PRESS_HOME/manuscripts/$API_SLUG" "$PRESS_HOME/manuscripts/$CLI_NAME"; do
        if [ -d "$base" ]; then
          _latest="$(find "$base" -mindepth 2 -maxdepth 2 -name research.json -type f 2>/dev/null | sort | tail -1)"
          if [ -n "$_latest" ]; then
            RESEARCH_DIR="$(dirname "$_latest")"
            break
          fi
        fi
      done
    fi
    ;;
esac

# Use a bash array so the flag survives paths with spaces (e.g. when
# $HOME or $PRESS_RUNSTATE resolves through a path containing spaces).
RESEARCH_ARGS=()
if [ -n "$RESEARCH_DIR" ]; then
  RESEARCH_ARGS=(--research-dir "$RESEARCH_DIR")
fi

# pii-audit runs against the CLI dir, but publish package later copies the
# same run archive under .manuscripts/<run-id> before enforcing the PII gate.
# Pass the run dir here so polish sees the narrative manuscript files with
# the same relative paths publish will scan.
PII_ARGS=()
if [ -n "$RESEARCH_DIR" ]; then
  PII_ARGS=(--manuscripts-dir "$RESEARCH_DIR")
fi

差分の確認

フェーズ 1 の前に必ずこの手順を実行してください。省略しないでください。差分を確認し、相違を解消するまで診断に進まないでください。

公開リポジトリ（mvanhorn/printing-press-library）が最後に公開された後に誰かが直接編集した場合、$CLI_DIR にある内部コピーと公開ライブラリのコピーが乖離している可能性があります。古い内部コピーを整えて後から再公開すると、公開側にのみ存在する修正が気付かないうちに上書きされます。これは、公開済み CLI で実際に起きている問題です。

以下を必ず実行してください：

1. 公開ライブラリのクローンを特定します。 $PRINTING_PRESS_LIBRARY_PUBLIC が設定されている場合はその値を使用し、設定されていない場合は、このプラットフォームに適した方法でユーザーのファイルシステムを検索してください。候補ごとに、git のリモートが mvanhorn/printing-press-library を指していることを確認してください。同じ名前の別ディレクトリ（フォークや偶然の名前の重複など）が存在する可能性があります。有効なクローンが複数ある場合は、最終更新日時が最も新しいものを優先し、それでも判断できない場合に限り、ユーザーに確認してください。

2. クローン内でこの CLI を特定します。 find <clone>/library -type d -name "<api>-pp-cli" または同等の方法を使用してください。

3. 次の除外指定を付けて diff -r <public-cli-dir> $CLI_DIR を実行します。 これらは公開後に想定される差異です。

   • .printing-press-tools-polish.json（ローカルの台帳であり、公開対象外）
   • .printing-press-pii-polish.json（ローカルの台帳であり、公開対象外）
   • go.mod と go.sum — 公開時にモジュールパスが <api>-pp-cli から github.com/mvanhorn/printing-press-library/library/<category>/<api> に書き換えられます
   • 差異がインポートパスの書き換えだけであるすべての .go ファイル（公開手順では、すべての内部インポートに新しいモジュールパスが反映されます）。.go ファイルの差分を確認する際は、実質的な変更がないか調べてください。モジュールパスのプレフィックスの置き換え以外は、すべて実際の差異です。

   具体的には、次のコマンドを実行します。diff -r --exclude=go.mod --exclude=go.sum --exclude=.printing-press-tools-polish.json --exclude=.printing-press-pii-polish.json <public-cli-dir> $CLI_DIR。

   --exclude='<api>-pp-cli' や --exclude='<api>-pp-mcp' は指定しないでください。これらの名前はルート直下のバイナリファイルだけでなく、cmd/<api>-pp-cli/ および cmd/<api>-pp-mcp/ のソースディレクトリにも一致します。バイナリ名で除外すると cmd/ 以下全体が対象外になり、main.go の実際の差異を見落とします。ビルド済みバイナリの「Only in $CLI_DIR: -pp-cli」という行は、想定される出力の一項目であり、完全性を損なってまで除外するノイズではありません。

4. 続行する前に結果を明示します。

結果：

• クローンが見つからない → ユーザーのローカル環境に公開リポジトリがないことを明示し（「公開ライブラリがローカルに見つからないため、内部コピーを正本として続行します」）、続行します。
• クローンは見つかったが、この CLI が含まれていない → まだ公開されていないか、別の名前で登録されています。このことを明示して続行します。
• クローンが見つかり、差分がない → 同期されています。このことを明示して続行します。
• クローンが見つかり、差分がある → ここで停止します。 フェーズ 1 の診断はまだ実行しないでください。差異のあるファイルをユーザーに列挙してください。AskUserQuestion を使って、公開側から内部へ同期するか、同期せずに続行するかを尋ねます。ユーザーが同期を選んだ場合は、差異のあるファイルを公開側から内部へコピーしてから、同期した内部コピーの整備を続けます。

同期の選択肢を提示する前に、内部コピーに .printing-press.json のタイムスタンプより後に変更されたファイルがないか確認してください。ある場合は、ユーザーがローカルで作業中の可能性があることを明示してください。同期すると、まだ公開していないローカル作業が上書きされることを伝え、ローカルの編集を保持するか、公開側の変更を取り込むかを選んでもらいます。

同期後（または同期を明示的に見送った後）は、残りの整備で $CLI_DIR を正本として扱います。最終的な /printing-press-publish 手順で内部コピーを公開側に反映するため、そこで二度目の差分確認は不要です。

この確認は、上記 4 つの結果のいずれかが応答内で明示された場合にのみ、実施済みとみなされます。結果を示さずに省略した場合は、未実施として扱われます。

フェーズ 1：ベースライン診断

cd "$CLI_DIR"

# Build
go build -o "$CLI_NAME" ./cmd/"$CLI_NAME" 2>&1

# Diagnostics. SPEC_FLAG and RESEARCH_ARGS are set in the "Find spec
# and research dir" step above. RESEARCH_ARGS enables dogfood to
# verify novel features and sync them into .printing-press.json
# (required for publish-validate's transcendence gate).
"$PRINTING_PRESS_BIN" dogfood --dir "$CLI_DIR" $SPEC_FLAG "${RESEARCH_ARGS[@]}" 2>&1
"$PRINTING_PRESS_BIN" verify --dir "$CLI_DIR" $SPEC_FLAG --json 2>&1
"$PRINTING_PRESS_BIN" workflow-verify --dir "$CLI_DIR" --json > /tmp/polish-workflow-verify.json 2>&1 || true
"$PRINTING_PRESS_BIN" verify-skill --dir "$CLI_DIR" --json > /tmp/polish-verify-skill.json 2>&1 || true
# publish-validate is a publish-readiness gate, not a CLI-readiness gate.
# Mid-pipeline polish runs before the main SKILL's promote step and before
# the publish skill packages tools-manifest.json, so its prerequisites
# (manifest.printer from git config github.user, packaged tools manifest,
# phase5 acceptance proof relocated under $CLI_DIR/.manuscripts/<run>/proofs/)
# are not yet satisfied. Running publish-validate here would cascade
# parent-pipeline-owned failures into the polish ship_recommendation,
# which the main SKILL's Phase 5.5 verdict-override then turns into a
# CLI-level hold. Only run publish-validate when polish is the publish
# entry point (slash-command invocation or explicit --standalone).
if [ "$STANDALONE_MODE" = "true" ]; then
  "$PRINTING_PRESS_BIN" publish validate --dir "$CLI_DIR" --json > /tmp/polish-publish-validate.json 2>&1 || true
fi
# --live-check samples novel-feature outputs and populates
# live_check.features[].warnings (Wave B entity detection) — required for
# the "Output entity warnings" row below to have data to read.
# RESEARCH_ARGS points scorecard at the run's research.json when the
# CLI lives under $PRESS_RUNSTATE/runs/<id>/working/<cli> (mid-pipeline
# polish). Without it, scorecard looks adjacent to the binary, doesn't
# find research.json, and reports `unable: true`.
"$PRINTING_PRESS_BIN" scorecard --dir "$CLI_DIR" $SPEC_FLAG "${RESEARCH_ARGS[@]}" --live-check --json > /tmp/polish-scorecard.json 2>&1 || true
"$PRINTING_PRESS_BIN" scorecard --dir "$CLI_DIR" $SPEC_FLAG 2>&1
"$PRINTING_PRESS_BIN" tools-audit "$CLI_DIR" --json > /tmp/polish-tools-audit-before.json 2>&1 || true
"$PRINTING_PRESS_BIN" pii-audit "$CLI_DIR" "${PII_ARGS[@]}" --json > /tmp/polish-pii-audit-before.json 2>&1 || true
go vet ./... 2>&1
if command -v gosec >/dev/null 2>&1; then
  gosec -fmt=json -out=/tmp/polish-gosec-before.json ./... 2>&1 || true
else
  go run github.com/securego/gosec/v2/cmd/[email protected] -fmt=json -out=/tmp/polish-gosec-before.json ./... 2>&1 || true
fi

verify-skill と workflow-verify は dogfood/verify/scorecard と並行して実行されるため、polish は公開ライブラリの CI が検出するのと同じ種類の障害を検出できます。publish-validate は STANDALONE_MODE=true（スラッシュコマンドまたは --standalone による Skill-tool 呼び出し）の場合にのみ実行されます。publish-validate のレッグは スタンドアロン polish にとって 厳格な出荷ゲートです。このモードでは、"$PRINTING_PRESS_BIN" publish validate が passed: false を報告している間、polish は ship または ship-with-gaps を推奨できません。ミッドパイプラインの polish（STANDALONE_MODE=false）は publish-validate を完全にスキップします — その前提条件（git config github.user からの manifest.printer、パッケージ化された tools-manifest.json、$CLI_DIR/.manuscripts/<run>/proofs/ 配下に再配置された phase5 受け入れ証明）は親パイプラインが所有しており、この時点ではまだ満たされていません。メイン SKILL の Phase 6 公開フローは、適切なタイミングで publish-validate をゲートします。これが ship_recommendation にどう影響するかは、後述の「Ship logic」を参照してください。

ライブマトリックスの条件。 各 scorecard --live-check --json 実行後、/tmp/polish-scorecard.json を読み取り、live_check が実際にライブサンプルを実行したかどうかを記録します。live_check.unable が false で、少なくとも 1 つの機能が評価されている場合（passed + failed > 0、または同等の機能ステータス）にのみ、exercised として扱います。live_check.unable: true、live_check が存在しない、評価された機能がない、または認証情報/トークンが欠落している場合は、not_exercised として扱います。クリーンなモック dogfood/verify 実行は依然として有用ですが、それは ライブマトリックスの合格ではありません。

gosec は、手書きの Go に対する既製のセキュリティ静的解析レッグとして実行されます。インストール済みの gosec バイナリがあれば優先的に使用し、なければ固定バージョンの go run github.com/securego/gosec/v2/cmd/[email protected] フォールバックを使用して、別途セットアップ手順なしでもクリーンなマシンで再現可能なチェックが得られるようにします。ベースラインの検出件数と issue の詳細については /tmp/polish-gosec-before.json を読み取ります。JSON を書き出す前にコマンドが失敗した場合、スキャンの欠落を polish の失敗として扱います。remaining_issues に追加し、ship_recommendation: hold を設定し、stderr の概要を含めることで、次回の実行でネットワーク/ツーリングの失敗と CLI の欠陥を区別できるようにします。手書きファイルの検出結果を優先します。internal/cli/、internal/syncer/、internal/store/ 配下のファイル全体のうち、最初の 20 行に Generated by CLI Printing Press ヘッダーがないものは、polish が所有する新機能コードです。ジェネレーターが出力したファイルの検出結果は、仕様を変更して再生成することで恒久的に修正できる場合を除き、Printing Press のレトロ候補です。gosec を黙らせるためだけに生成ファイルを手で編集しないでください。

Phase 1 のベースラインで、基盤となる CLI の再 discovery が必要であることが判明した場合 — 壊れた HTML/SSR 抽出、乏しいキャプチャ（ソース原稿内の一意のエンドポイントが 5 件未満）、誤ったエンドポイント形状、GraphQL オペレーションハッシュの欠落、または CLI が不完全なキャプチャから生成されたことを示すあらゆるシグナル — 通常、polish はブラウザーキャプチャ自体を行いません。再 discovery が必要な場合は、新しいキャプチャフローを考案するのではなく、ランタイムがすでに公開しているキャプチャバックエンド（Claude chrome-MCP mcp__claude-in-chrome__* および computer-use mcp__computer-use__*）を使用してください。polish からの再 discovery はまれですが、実在します。

検出結果をカテゴリに分類します:

カテゴリ	ソース	確認する内容
検証の失敗	verify --json	スコアが 3 未満のコマンド
SKILL の静的チェックの失敗	verify-skill --json	severity=error の findings[] があるか（flag-names、flag-commands、positional-args、unknown-command、canonical-sections）。厳格な出荷ゲート：これらが存在する間は ship を実行できません。
ワークフローの不足	workflow-verify --json	判定が workflow-fail かどうか。ソフトゲート：remaining_issues に記録し、そのワークフローが CLI の主な価値である場合は hold に引き下げます。
公開検証の失敗	publish validate --json	passed: false かどうか。単独で行う仕上げのみ（STANDALONE_MODE=true の場合のみ実行）。公開の前提条件がまだ満たされていない中間パイプラインの仕上げではスキップされます。実行された場合は厳格な出荷ゲートとなり、publish validate が失敗している間は ship を実行できません。失敗したチェックが phase5 acceptance の不足だけの場合は、次のステップのコマンドとともに phase5 acceptance required と報告します：認証後、"$PRINTING_PRESS_BIN" dogfood --dir "$CLI_DIR" $SPEC_FLAG --live --level quick --write-acceptance <proofs-dir>/phase5-acceptance.json を実行します。validate エラーに proofs ディレクトリが記載されている場合は、そのディレクトリを使用してください。
セキュリティ静的解析の失敗	gosec JSON	Issues[] のエントリがあるか。特に G201/G202 の SQL 構築、G101 の認証情報リテラル、安全でないファイル／コマンド実行に注意します。手書きの新機能 Go コードに関する検出事項は、厳格な出荷ゲートとなります。
デッドコード	dogfood	デッド関数、使用されていないフラグ
古いファイル	dogfood	登録されていないコマンド
説明の問題	dogfood	定型文のルート Short
README の不足	scorecard	README のスコアが 8 未満
例の不足	dogfood	例がないコマンド
Go vet の問題	go vet	出力があるか
出力エンティティの警告	scorecard JSON	live_check.features[].warnings — 人が読む出力に含まれる生の HTML エンティティ
出力の妥当性	Phase 4.85	エージェントによる出力レビューの検出事項
MCP ツールの品質	tools-audit	Short が空、Short が簡素、読み取り専用アノテーションの欠落、MCP の説明が簡素
顧客の PII	pii-audit	高リスクファイル（manuscripts、fixtures、README）におけるカード番号の下 4 桁、メールアドレス、電話番号、ZIP+4、郵送先住所の形式

環境に起因する失敗と CLI の不具合。 Phase 1 の出力には、実際の CLI のバグではなく、出荷を妨げるべきでない失敗が含まれることがあります。

• scorecard --live-check が SQLITE_BUSY、ネットワークのタイムアウト、モックまたは期限切れのトークンによる 401、あるいはテスト用ワークスペースの権限／状態に依存する HTTP エラーを報告する場合。これらはテスト環境の問題であり、CLI の不具合ではありません。
• バイナリ出力を返すコマンド（例：部分文字列マッチャーでは検証できない PNG を返す qr）や、オプションの位置引数があり、dry-run の出力に verify のプローブ文字列が含まれないのが正当なコマンドで、verify のモックハーネスが不安定になる場合。
• Learn-loop コマンド：dogfood／verify マトリクスは、デフォルトで有効な learn 機能（teach、recall、learnings、playbook）をカバーするようになりました。teach と teach-playbook は、引数なしで実行すると意図的に終了コード 2 を返します。これは pp:typed-exit-codes で宣言されているため、verify は合格として採点し、dogfood --live は happy_path と json_fidelity のチェックを理由 declared non-zero exit 2 でスキップとして記録します。どちらも不具合ではなく、終了コードを「修正」する理由にもなりません。happy path がスキップされた場合、phase5 のライブカバレッジには数えられないため、happy path で常にゼロ以外の終了コードだけを返す新機能は、カバー済みではなく空疎と報告されます。新規の print で learnings stats がゼロや空のセクションを返すのは正当な動作です。これはローカルストアが空であることを示しており、不具合ではありません。

これらは具体的な理由とともに skipped_findings で環境要因として分類してください。Phase 2 の作業を費やして「修正」しようとしてはいけません。仕上げスキルの出荷ロジックでは、ライブチェックの失敗はすでにゲート判定から除外されていますが、レビュー担当者が検討のうえ意図的に却下されたことを確認できるよう、エージェントは注記を残してください。

フェーズ 4.85 — エージェント型出力レビュー（Wave B）

上記の機械的な診断が完了したら、Skill ツール経由で printing-press-output-review サブスキルを呼び出します。このサブスキルは context: fork を持ち、ディスパッチプロンプト、ゲートロジック、既知の盲点を管理します。これらはメインの printing-press スキルと共有する唯一の信頼できる情報源です。

Skill(
  skill: "cli-printing-press:printing-press-output-review",
  args: "$CLI_DIR"
)

返された ---OUTPUT-REVIEW-RESULT--- ブロックを解析します。status: WARN の指摘事項は上記の診断カテゴリに反映されるため、フェーズ 2 の修正でルールベースの問題と妥当性の問題の両方に対処できます。status: SKIP は参考情報です。記録しますが、ブロック要因にはしません。

Wave B ではゲーティングが適用されます。すべての指摘事項は警告であり、ブロッカーにはなりません。明白で容易な場合は修正し、先送りする場合は短いコメントを付けて記録します。

ベースラインのスコアを記録します。スコアカードの合計、検証の合格率、ドッグフーディングの判定、ライブマトリックスの判定（exercised / not_exercised）、go vet の問題数、gosec の検出数、出力レビューの指摘数です。

フェーズ 2：修正

優先順位の高い順に修正します。各優先順位のレベルが終わるごとに、ロックのハートビートを更新します。

"$PRINTING_PRESS_BIN" lock update --cli "$CLI_NAME" --phase polish 2>/dev/null

ランタイムのバリアントに関するデフォルトのチェックリスト

仕上げの修正でランタイムモード、データソースオプション、認証レベル、トランスポート、その他のユーザーに見えるデフォルトを追加または変更する場合は、デフォルトを選択する前に、次の短いチェックリストを記録します。

• ユーザーに見えるデフォルト： 追加のフラグや設定なしでユーザーが利用する動作。
• 互換性リスク： 既存のコマンド、スクリプト、MCP ツール、保存済み設定の動作が変わるかどうか。
• 検証コマンド： デフォルトと、デフォルト以外を選ぶための代替手段の両方が機能することを証明する正確なコマンド。

チェックリストは仕上げのメモまたは結果ブロックに記載します。ランタイムのバリアントやデフォルトを変更しない通常のバグ修正では不要です。

横断的な API 呼び出しの計装

クォータ台帳、リクエストログ、監査証跡など、すべての送信 API 呼び出しを監視する必要がある機能クラスを仕上げる場合は、個々のコマンドハンドラーではなく、internal/client/client.go の生成されたクライアントミドルウェアを計装します。共有のディスパッチ前フックがある場合はそれを優先し、ない場合は do() と doRead() の両方を対象にします。do() パスは標準のエンドポイントミラー、同期の反復処理、生成されたクライアントを使用する新しい機能を処理します。一方、doRead() パスは GraphQL クエリ、JSON-RPC の読み取り、mcp:read-only としてマークされた POST ベースの検索など、POST のようなトランスポートを利用する読み取り専用操作を処理します。 コマンドごとのフックでは、仕上げの対象となったコマンドしか確認できないため、カウントが不足します。

新機能のデータルーティング

polish が API レスポンスデータをローカルストアに読み込む新しいコマンドを追加または修正する場合は、レスポンス JSON をそのままテーブルに書き込むのではなく、生成された型付きスキーマを経由してデータをルーティングします。

1. キャッシュ対象のリソースについて、internal/types/<resource>.go と internal/store/<resource>.go を読みます。これらのファイルが出力する型付き insert/upsert ヘルパーがあれば、必ず使用してください。生成されたリソースにヘルパーがない場合は、永続化コードを書く前に作成します。
2. insert のマッピングが正しいと判断する前に、レスポンスの形状を仕様のスキーマと実際のサンプルレスポンスに照らして確認します。
3. 永続化する前に、API レスポンスを型付き構造体にデコードします。テーブルが手書きのマイグレーションで宣言された、polish が所有するカスタムテーブルでない限り、型なしの map[string]any や未加工の json.RawMessage 値から INSERT INTO ... 文を組み立ててはいけません。以下の未加工 SQL の例外を参照してください。
4. 挿入先のテーブルは、新しいコマンドが最初に実行したクエリではなく、リソースの型を基準に確認します。<child> レコードを取得したコマンドは、親の行や都合のよい隣接テーブルではなく、<child> の行を挿入する必要があります。
5. 挿入前に、ネストされたレスポンス ID を正規化します。API がメタデータも含むオブジェクト内にスカラー ID をラップしている場合は、スカラーの ID フィールドを取り出してその値を保存します。ID オブジェクト全体を主キーや外部キー参照として保存してはいけません。

未加工の database/sql による書き込みは、手書きのマイグレーションで宣言された、polish が所有するカスタムテーブルに限り使用できます。その場合は、テーブルスキーマを internal/store/ で明示し、生成されたリソースヘルパーが適用されない理由を記載します。また、永続化の前にネストされた ID をスカラー値にデコードしてください。

優先度 0：MCP サーフェスの移行（レガシー CLI）

Phase 1 の dogfood で MCP Surface: FAIL とパリティの不一致が報告された場合、その CLI はランタイムの cobratree ウォーカーが存在する前に生成されており、現在も静的な internal/mcp/tools.go サーフェスを使用しています。修正手順は機械的です。

"$PRINTING_PRESS_BIN" mcp-sync "$CLI_DIR"

これにより、MCP サーフェスがランタイムウォーカーに移行され、tools-manifest.json と internal/mcp/tools.go が再生成され、mcp-descriptions.json の上書き設定が適用されます。mcp-sync refused と reprint required で終了した場合は、この polish の実行を中止し、/printing-press-reprint に引き継いでください。対象 CLI の生成済みクライアントは現在の MCP ハンドラーに対して古すぎるため、tools.go だけを書き換えるとビルドが壊れます。引き継ぎには、再印刷フローで通常の dogfood ゲートを再生成された CLI に対して実行し、出荷前に MCP Surface: PASS を確認する必要があることを含めてください。古い $CLI_DIR に対して dogfood を再実行してはいけません。mcp-sync が成功したら、ここで dogfood を再実行します。パリティゲートは PASS に変わるはずです。ランタイムウォーカーをすでに使用している互換性のある CLI で mcp-sync を実行した場合は、更新なしでリフレッシュされます。

dogfood の MCP ゲートがすでに合格している CLI では、この優先度項目をスキップしてください。

優先度 1：セキュリティ静的解析の失敗

/tmp/polish-gosec-before.json にある各 gosec の検出結果について：

1. 指摘されたファイルを読み、手書きかどうかを確認します。internal/cli/、internal/syncer/、または internal/store/ 配下のファイル全体の先頭 20 行に Generated by CLI Printing Press が含まれていない場合、そのファイルは polish が所有する新機能コードです。
2. 検出結果が手書きコードに関するものであれば、優先度の低い polish 項目に取り組む前に、ソースの根本原因を修正します。例：SQL 文字列の組み立てをパラメーター化クエリに置き換える、信頼できない引数を使ったシェル呼び出しを避ける、認証情報に見えるリテラルを設定／環境変数の仕組みに移す。
3. gosec が生成コードを指摘した場合、生成ファイルを手作業で編集してはいけません。上流の仕様を修正して再生成するか、ルール ID とファイルパスを含む、ジェネレーター改修候補として skipped_findings エントリーを追加します。
4. gosec が誤検知を報告した場合、抑制の範囲を狭く保ち、その理由を説明します。コードが実際に安全で、理由が今後も変わらない場合に限り、ローカルな // #nosec G### -- reason を優先します。それ以外の場合はコードを修正します。

手書きの新機能 Go コードに未解決の gosec 検出結果がある場合、これは重大なブロッカーです。remaining_issues に記載し、ship_recommendation: hold とし、修正が機械的に行える可能性がある場合は further_polish_recommended: yes に設定する必要があります。

優先度 2：検証失敗

検証の dry-run または exec が失敗する各コマンドについて：

1. コマンドファイルを読みます。
2. Args: cobra.ExactArgs(N) または同様の制約を探します。
3. Args: フィールドを削除します。
4. RunE の先頭に次を追加します。

   if len(args) == 0 {
       return cmd.Help()
   }
   

5. 2 個以上の引数が必要なコマンドでは、if len(args) < 2 を使います。
6. dry-run で nil データによるクラッシュがないか確認し、ガードを追加します。

   if flags.dryRun {
       return nil
   }
   

優先度 3：デッドコード

1. dogfood が指摘した各デッド関数について、定義自身との一致だけではないことを確認するため、すべての .go ファイルを grep します。
2. 本当に使われていない場合は、関数を削除します。
3. 別のヘルパーから使われている場合は、そのまま残します（誤検知）。
4. 削除後、未使用のインポートを削除します。
5. 古いファイル（root.go に登録されていない昇格済みコマンド）を削除します。

優先度 4：CLI の説明とメタデータ

1. internal/cli/root.go にあるルートコマンドの Short を読みます。
2. 定型文（「Reverse-engineered...」や生の API タイトル）が含まれている場合は、次の形式に書き換えます。 パターン："<Product> CLI with <capability-1>, <capability-2>, and <capability-3>"
3. コマンドに Example フィールドがないか確認します。ドメイン固有の値を使った現実的な例を追加します。

優先度 5：README

最重要ルール：README に記載するすべてのコマンドで、<cli> <cmd> --help を実行します。 フラグ名、引数の形式、有効な値を推測してはいけません。--start-time と記載していても、実際のフラグが --start なら、README は間違っており、ユーザーは最初に試したときにエラーになります。

レンダリングされるセクションの正本ファイル

README.md、SKILL.md、または .printing-press.json を編集する前に、そのセクションがソースファイルからレンダリングされているかどうかを確認してください。dogfood と再生成を実行すると、これらのレンダリング済みセクションは上書きされます。そのため、直接編集しても一時的な変更にしかならず、現在の出力を確認する場合にのみ使用してください。

レンダリングされるセクションまたはフィールド	正本ファイル::フィールド	調整ワークフロー
README ## Unique Features	research.json::novel_features_built[]	元の research.json の機能の説明／例を編集し、--research-dir を指定して dogfood を再実行します。
SKILL ## Unique Capabilities	research.json::novel_features_built[]	元の research.json の機能の説明／例を編集し、--research-dir を指定して dogfood を再実行します。
internal/mcp/tools.go command_mirror_capabilities	research.json::novel_features_built[]	dogfood はディスク上の異なるブロックを報告し、変更せずに残します。research.json の内容で置き換える場合にのみ --overwrite-command-mirror を指定します。
README Quick Start	research.json::narrative.quickstart[]	research.json のコマンド／コメントを編集し、再生成するか、dogfood／レンダリングの手順を再実行します。
SKILL Recipes	research.json::narrative.recipes[]	research.json のレシピのタイトル、コマンド、または説明を編集し、再生成するか、dogfood／レンダリングの手順を再実行します。
README／SKILL Troubleshooting	research.json::narrative.troubleshoots[]	research.json の症状と解決方法の組を編集し、再生成するか、dogfood／レンダリングの手順を再実行します。
.printing-press.json display_name、description、mcp_*	WriteManifestForGenerate。説明／表示名の上書きについては、spec（info.title、info.x-display-name、info.description）を編集します	spec を編集するか、マニフェストライターを再実行します。一時的な診断を行う場合を除き、生成されたマニフェストのメタデータを手動で編集しないでください。

これらのレンダリング済みセクションに推奨されるループは、ソースフィールドを編集し、必要に応じて --research-dir "$RESEARCH_DIR" を指定して dogfood を再実行するか、CLI を再生成した後、2 回目のパスを実行して、レンダリングされた README／SKILL のテキストが維持されることを確認することです。これらのセクションで README.md または SKILL.md を直接編集すると、次回の dogfood による再同期または再生成で変更が上書きされることを想定してください。

原稿のソースを確認するには：

PRESS_HOME="${PRINTING_PRESS_HOME:-$HOME/printing-press}"
API_SLUG="${CLI_NAME%-pp-cli}"
RESEARCH_JSON=""
for f in "$PRESS_HOME/manuscripts/$CLI_NAME"/*/research.json \
         "$PRESS_HOME/manuscripts/$API_SLUG"/*/research.json; do
  if [ -f "$f" ]; then RESEARCH_JSON="$f"; break; fi
done

RESEARCH_JSON が存在し、レンダリングされたセクションの文章、例、フラグへの参照に問題がある場合は、まず該当するフィールドをそのファイルで修正してください。新機能については、dogfood が research.json::novel_features[] を検証し、残った項目を research.json::novel_features_built[] に書き込み、その検証済みの項目から README ## Unique Features、SKILL ## Unique Capabilities、.printing-press.json の novel_features、およびルートヘルプの Highlights を同期します。internal/mcp/tools.go の command_mirror_capabilities ブロックに差異がある場合、--overwrite-command-mirror を指定しない限り変更されません。

必須セクション（正確に記載すること）

1. タイトル：「# CLI」— 製品の正式名称を、正しい大文字・小文字と句読点で使用します（例：「Cal Com」ではなく「Cal.com」）。
2. サブタイトル：CLI がユーザーに何を提供するかを説明する一文で、ルートの Short フィールドと一致させます。API の説明ではありません。
3. インストール：正しいインストールコマンドを記載します。存在しない CLI ごとのリポジトリではなく、printing-press-library リポジトリの URL を使用します。
4. 認証：<API>_API_KEY 環境変数の設定方法と、キーの取得先（プロバイダーの設定ページへのリンク）、サポートされている場合はセルフホスト用 URL の上書き方法を記載します。config.go を確認して、すべての環境変数を特定します。
5. クイックスタート：最初に実際に実行する 3～5 個のコマンドを記載します。最も便利で（日常的に実行するもの）、CLI の価値を示す（curl ではなく、これをインストールする理由がわかる）コマンドを選びます。通常は doctor → sync → 超越コマンド（today、health）→ search の順です。生のリストコマンドは、CLI の存在意義を示さずにデータを大量に出力するため、避けてください。
6. コマンド：カテゴリ別の表にします。実装構造ではなく、ドメイン機能（スケジューリング、分析、アカウント、ユーティリティ）ごとに分類します。
7. 出力形式：--json、--select、--csv、--compact、--dry-run、--agent を示します。プレースホルダーではなく、実在するコマンドを使用します。
8. エージェントでの使用：エージェント向けの特性と終了コードを記載します。
9. クックブック：--help で確認済みのフラグ名を使ったレシピを 8～15 個記載します。CLI 独自の機能（超越コマンド、フィルター、SQL クエリ、パイプ）を示します。少なくとも 1 つの変更操作の例を含めます。
10. ヘルスチェック：プレースホルダーではなく、実際の doctor の出力を示します。
11. 設定：config.go にあるすべての環境変数を説明とともに列挙します。設定ファイルのパスも記載します。
12. トラブルシューティング：よくあるエラーを終了コードに対応付け、解決方法を記載します。

任意のセクション（必要に応じて追加）

• レート制限：API に公開済みの制限がある場合
• セルフホスティング：CLI が --api-url または BASE_URL の上書きに対応している場合
• ページネーション：API に特筆すべきページネーション動作がある場合
• ソースと参考情報：コミュニティプロジェクトへの謝辞（機械によって生成されたものなので、存在する場合はそのまま残します）

優先度 5.5: SKILL の静的チェック失敗 (verify-skill)

完全な検出結果の一覧については /tmp/polish-verify-skill.json を参照してください。各検出結果には check (flag-names、flag-commands、positional-args、unknown-command、または canonical-sections)、command (SKILL が主張したパス)、および不一致を説明する detail が含まれます。よくある形と修正方法:

• flag-names — SKILL が <cli> ... の呼び出しで --foo を参照しているが、internal/cli/*.go 内のどのコマンドもそれを宣言していません。例が間違っているか (SKILL を修正するかレシピを削除します)、フラグが削除されたか (復活させるべきか判断します) のいずれかです。対象外: 他のツールを呼び出す行のフラグ (例: npx -y @mvanhorn/printing-press install <api> --cli-only、gh pr create --base ...、go install ...)。レシピスコープの flag-names チェックは設計上それらを無視します — verify-skill を終了コード 0 にするために外部ツールのフラグを削除しないでください。また、インストール手順を捏造したスラッシュコマンドに置き換えないでください。検出結果がそれでも外部ツールのフラグで発火している場合、それは verify-skill のバグであり SKILL のバグではありません。SKILL を編集するのではなく、それを報告してください。
• flag-commands — --foo is declared elsewhere but not on <cmd>。フラグはどこかには存在しますが、SKILL がそれを呼び出したコマンドには存在しません。2 つの修正方法:
  1. フラグが addXxxFlags(cmd, ...) のような共有ヘルパーを介して追加されている場合、cmd.Flags().StringVar(...) の宣言を、影響を受けるコマンドのソースファイルに直接インライン化します。verify-skill の grep は関数呼び出しの間接参照を追跡できません。
  2. SKILL の例が本当に間違っている場合、コマンドが実際に宣言しているフラグを使うように例を修正します。
• positional-args — got N positional args; Use: "<cmd> <arg>" expects M-M。SKILL のレシピは N 個の位置引数を渡しましたが、コマンドの Use: は M 個を必須として宣言しています。2 つの修正方法:
  1. コマンドが --flag を介して値も受け入れる場合、Use: "cmd <arg>" を Use: "cmd [arg]" に変更します (角括弧 = 任意)。verify-skill は、任意の位置引数に対する --flag のみの呼び出しを正しく受け入れます。
  2. SKILL の例に必須の位置引数が欠けている場合、例を修正します。
• canonical-sections — install section drift: hand-edit detected in a generator-owned section。## Prerequisites: Install the CLI ブロックが、この CLI に対して今日ジェネレーターが出力する内容から編集されて乖離しています。インストールセクションを手動編集しないでください。 これは internal/generator/templates/skill.md.tmpl から (api_name, category, uses_browser_http_transport) をパラメーターとしてテンプレート化されています。乖離があれば、自動化ステップまたは人物がマシンが所有するテキストを変更したことを意味します。出力された CLI を再生成して解決します (このディレクトリに対して printing-press regen を実行するか、公開済みの CLI の場合はスペックから再生成して再公開します)。正規のテキスト自体が間違っている場合 (例: インストール手順に対する実際の変更が必要な場合)、出力された CLI ではなくテンプレートを修正します。

SKILL.md の他の部分を編集するときは、影響を受けるセクションをまず Read し、Edit の後に再度 Read してください。Edit はリテラル文字列を置き換えます。周囲のコンテキストが乖離している場合、1 回の Edit でブロックを置き換えるのではなく、ブロックの 2 つ目のコピーを 1 つ目に接ぎ木してしまう可能性があります。

修正後、"$PRINTING_PRESS_BIN" verify-skill --dir "$CLI_DIR" を再実行し、先に進む前に終了コード 0 を確認してください。

優先度 6: 残りのドッグフーディング問題

• パス有効性の不一致
• 認証プロトコルの不一致
• 例の乖離 (例が間違ったコマンドを参照している)
• データパイプラインの完全性の問題

優先度 7: MCP ツールの品質

ここでの目標は、この CLI が公開するすべての MCP ツールがエージェント品質の説明と正しい読み取り/書き込み分類を備えていることを確実にすることです。 ツールの説明と分類は、エージェントがツールを発見し、呼び出すかどうかを判断するための手段です。薄い説明と欠落したアノテーションはエージェントの UX を直接劣化させます。また、フェーズ 1 の機械的なゲート (verify、dogfood) はこの種の問題を検出しません。

作業を止めて、次を実行してください:

1. "$PRINTING_PRESS_BIN" tools-audit "$CLI_DIR" --json を実行して、機械的に検出された指摘 (空の Short、薄い Short、読み取り系のコマンド名に mcp:read-only が欠落) を洗い出します。
2. references/tools-polish.md を読み、その指示に従って指摘に対処するとともに、監査が指摘したかどうかに関係なく、すべてのコマンドに対して判断パスを実行する必要があります。監査が検出するのは機械的な問題です。説明の品質と境界線上の分類 (読み取り専用かローカル書き込みか) には、常にエージェントによる推論が必要です。これを省略してはなりません。
3. MCP 説明の指摘を受け入れることには、より厳格な契約が伴います。 thin-mcp-description および empty-mcp-description を受け入れるには、指摘ごとに 3 つの判断前フィールド (spec_source_material、target_description、gap_analysis) を設定する必要があります。バイナリは一括受け入れ (1 つの根拠を共有する 5 件超の指摘) を拒否し、MCPDescriptionQuality を引き上げずに「完了」として実行されます。修正はオーバーライドまたはジェネレーターの改善によるのが想定される道筋であり、受け入れはまれです。完全な契約については references/tools-polish.md の「指摘を受け入れ済みとしてマークする」を参照してください。

監査のサマリー行が no pending findings と表示され、incomplete: ブロックがなく、すべてのゲート (判断前フィールド、重複する根拠、スコアカードの差分) を通過した場合にのみ、「すべての修正後」に進んでください。

優先度 8: 顧客 PII ゲート

ここでの目標は、PII 台帳をクリアして promote および publish ゲートを通過させることです。 PII ゲートは、実際の顧客の値が公開ライブラリのコンテンツに到達するのを防ぐ決定論的な下限です。カード末尾 4 桁、メールアドレス、米国電話番号、ZIP+4、および住所の形式を高リスクファイル内で検出します。

作業を止めて、次を実行してください:

1. "$PRINTING_PRESS_BIN" pii-audit "$CLI_DIR" "${PII_ARGS[@]}" を実行して、保留中の指摘を洗い出します (または、フェーズ 1 のベースラインから /tmp/polish-pii-audit-before.json を読み取ります)。RESEARCH_DIR が存在する場合、これにはその実行の research.json および research/*.md が .manuscripts/<run-id>/... パス付きで含まれるため、受け入れは publish package に引き継がれます。
2. references/pii-polish.md を読み、その指摘ごとのデシジョンツリーに従う必要があります。ソース内の実際の値を一致しないプレースホルダーに修正するか、category と evidence_context の判断前フィールドを付けて受け入れます。
3. PII の指摘を受け入れることには、厳格な契約が伴います。 フィールドの欠落、1 つの根拠を共有する 6 件以上の受け入れ、またはソース修正なしで 10 件以上の指摘を一括受け入れすることは、いずれもゲートに失敗します。完全なルールについては references/pii-polish.md の「受け入れ契約」および「禁止される受け入れパターン」を参照してください。

pii-audit が no pending findings と表示され、incomplete: ブロックがない場合にのみ、「すべての修正後」に進んでください。

すべての修正後

go build -o "$CLI_NAME" ./cmd/"$CLI_NAME"
gofmt -w .

フェーズ 3：再診断

修正した CLI で診断を再実行します。

# RESEARCH_ARGS must travel with dogfood here too — without it,
# checkNovelFeatures doesn't re-sync novel_features_built after Phase 2
# edits, and publish-validate's transcendence gate reads stale state
# from Phase 1's pass.
"$PRINTING_PRESS_BIN" dogfood --dir "$CLI_DIR" $SPEC_FLAG "${RESEARCH_ARGS[@]}" 2>&1
"$PRINTING_PRESS_BIN" verify --dir "$CLI_DIR" $SPEC_FLAG --json 2>&1
"$PRINTING_PRESS_BIN" workflow-verify --dir "$CLI_DIR" --json 2>&1
"$PRINTING_PRESS_BIN" verify-skill --dir "$CLI_DIR" --json 2>&1
if [ "$STANDALONE_MODE" = "true" ]; then
  "$PRINTING_PRESS_BIN" publish validate --dir "$CLI_DIR" --json 2>&1
fi
"$PRINTING_PRESS_BIN" scorecard --dir "$CLI_DIR" $SPEC_FLAG 2>&1
"$PRINTING_PRESS_BIN" tools-audit "$CLI_DIR" 2>&1
"$PRINTING_PRESS_BIN" pii-audit "$CLI_DIR" "${PII_ARGS[@]}" 2>&1
go vet ./... 2>&1
if command -v gosec >/dev/null 2>&1; then
  gosec -fmt=json -out=/tmp/polish-gosec-after.json ./... 2>&1 || true
else
  go run github.com/securego/gosec/v2/cmd/[email protected] -fmt=json -out=/tmp/polish-gosec-after.json ./... 2>&1 || true
fi

最終的な scorecard --live-check --json の出力に含まれるライブマトリックスの判定も含め、修正後のスコアを記録します。gosec コマンドが /tmp/polish-gosec-after.json を書き込む前に失敗した場合は、修正後のスキャンがないことをポリッシュの失敗として扱います。remaining_issues に追加し、ship_recommendation: hold を設定して、stderr の概要を記載してください。verify-skill に severity=error の検出結果が残っている、workflow-verify が依然として workflow-fail を報告する、publish-validate が依然として passed: false を報告する（単独モードのみ。パイプライン途中のポリッシュではこのチェックを実行しません）、gosec が手書きの新機能 Go コードに未解決の検出結果を報告する、pii-audit に保留中の検出結果またはゲート失敗がある、あるいは最終的なライブマトリックスの判定が not_exercised の場合、出荷はできません（以下の出荷ロジックを参照）。ライブマトリックスが未実行の場合は、remaining_issues に「ライブマトリックス未実行（モックのみ／ライブトークンなし）。公開前にライブゲートを実行してください」のような項目を追加します。

出荷ロジック

出荷の推奨を計算します。

• ship：verify が 80％以上、scorecard が 75 以上、重大な失敗がなく、かつ verify-skill が終了コード 0（SKILL／CLI の不一致なし）を返し、かつ workflow-verify が workflow-fail ではなく、かつ（STANDALONE_MODE=true の場合）publish-validate が passed: true を報告し、かつ gosec が手書きの新機能 Go コードに未解決の検出結果を 1 件も報告せず、かつ tools-audit に保留中の検出結果がなく（すべての検出結果が修正済み、または根拠を明示して承認済み）、かつ pii-audit に保留中の検出結果もゲート失敗もない（すべての PII 検出結果がソースで修正済み、または有効な事前決定フィールドを使って承認済み）。SKILL／ワークフロー／公開／gosec／PII の各ゲートは必須要件です。CLI と実態が一致しない SKILL を添えて出荷すると（verify-skill の検出結果）、エージェントに誤った指示を与えてしまいます。主要なワークフローが検証に失敗する CLI は、実際には出荷できていません。publish-validate が拒否する CLI は公開できません。手書きの新機能コードに未解決のセキュリティ静的解析結果がある CLI は、レビューで問題になります。promote／publish ゲートで pii-audit に失敗する CLI は、いずれにせよ出荷が停止します。publish-validate ゲートが適用されるのは、ポリッシュの実行時に同チェックも実行した場合（単独モード）のみです。パイプライン途中のポリッシュでは、公開準備状況の確認はメイン SKILL のフェーズ 6 に委ねられます。

• ship-with-gaps：verify が 65％以上、scorecard が 65 以上で、重大ではない未解決の問題が残っており、かつ上記の SKILL／ワークフロー／gosec／PII ゲートを満たし、かつ（STANDALONE_MODE=true の場合）publish-validate ゲートを満たし、かつユーザー向けの問題を列挙した ## Known Gaps ブロックが README にあること。リファクタリングや外部依存関係の阻害要因により、完全な修正ができないという、まれなケースに限ります。

  ship-with-gaps では README の Known Gaps が必須です。 下流のユーザーが目にするのは公開されたライブラリのコピーです。判定で問題があるとされているのに README に記載がなければ、下流のユーザーは説明もなく正常に動作しない CLI に遭遇します。ship_recommendation: ship-with-gaps を出力する前に、次の手順を実施してください。

  1. CLI の README.md を読みます。## Known Gaps セクションがすでにある場合（たとえば、メイン SKILL のフェーズ 4 がポリッシュの実行前に作成している場合）は、remaining_issues にあるユーザー向けの項目が網羅されていることを確認します。ポリッシュで新たに判明したユーザー向けの問題があれば、箇条書きを追加します。

  2. ## Known Gaps がない場合は、## Quick Start の後（または ## Usage の前）に追加し、## Unique Features の配置規則に合わせます。remaining_issues にあるユーザー向けの項目を 1 つずつ箇条書きにします。ユーザーの視点で、どのコマンドがどのように動作しないのか、回避策は何かを記述します。例：

     ## Known Gaps
     
     - **`analytics export --csv`** は、イベント数が 1 万件を超えるワークスペースで行が途中で切り詰められます。エクスポートエンドポイントにページネーションが実装されるまで、回避策として `--json` を使用し、`jq` にパイプしてください。
     

  3. セクションを埋めるときは、remaining_issues をユーザー向けの項目でフィルタリングしてください。内部向けの項目 (非推奨フラグのドリフト検証、MCP の description 調整、内部向けの polish メモ) は、公開される Known Gaps に含めるべきではありません。エージェントが remaining_issues からユーザー向けのギャップを特定できない場合、判定は ship-with-gaps ではなく ship です。

  4. Known Gaps の書き込み/更新をそれぞれ fixes_applied に記載し、呼び出し元がその発生を把握できるようにしてください。

  polish が利用可能な証拠から Known Gaps を責任をもって埋められない場合 (たとえば、remaining_issues がユーザー向けの読み方がまったくない内部ジャーゴンばかりである場合) は、開示せずに ship するのではなく、判定を hold にダウングレードしてください。

• hold: verify < 65%、または scorecard < 65、または重大な失敗がある、または verify-skill に未解決の指摘がある、または workflow-verify が workflow-fail を報告し、そのワークフローが CLI の主要な価値である、または (STANDALONE_MODE=true の場合) publish-validate が passed: false を報告する、または gosec が手書きの新規機能 Go コードに未解決の指摘を依然として報告している、または pii-audit に保留中の指摘またはゲート失敗が依然としてある、または Phase 3 のゲートバンドルが、transcendence 行が欠落し、受け入れられた partial_transcendence_override もない、以前の sub-60 再掲であると示している。パイプライン途中の polish は publish-validate を理由に hold に到達することはありません。このチェックはそのモードでは実行されず、publish_validate_* は skipped (mid-pipeline) として出力されます。

ズルをせずにさらに高みを目指す

ship ゲートは下限であり、上限ではありません。それらを通過した後、まだ最大値に達していない scorecard の次元を見て、それぞれのギャップが実際のものか構造的なものかを問いかけてください:

1. スコアではなく、根本にある不足を見つける。 scorecard は品質の代理指標であり、目標そのものではありません。README が 8/10 でも、Cookbook セクションが欠けていたり、コマンドが古くなっていたりするかもしれません。それは実際に修正可能なギャップです。200 エンドポイントの API に対して mcp_surface_strategy が 2/10 である場合、サーフェスがほとんどエンドポイントのミラーであることを示している可能性があります。これも修正可能な場合があります。
2. 実際にエージェント品質の改善が可能なら、それを行う。 より良い description、欠けているフラグのドキュメント、弱い README セクション、実際の使用法を反映していない例。CLI は良くなり、スコアもそれに従います。
3. 不足が構造的なものであれば、文書化して受け入れる。 一部の次元は、CLI のドメインには存在しない能力を前提としています (読み取り専用 API を書き込みワークフローの次元で採点する、認証のない CLI を認証の次元で採点する、小さな API を大規模 API 向けに調整された surface_strategy のしきい値で減点する)。理由を skipped_findings に記録して先に進んでください。
4. 採点者を満足させるためにスキャフォールディングを追加しては決してなりません。 数値を少し動かすためだけに書かれた偽のコマンド、偽のテスト、偽のフラグ、定型文 — これらは代理指標を満たすために CLI を劣化させます。採点者は設計上不完全です (AGENTS.md の「scoring may be imperfect」という注意書きが当てはまります)。数値ではなく、根底にある判断を信頼してください。

MCP スコアカードの評価項目はジェネレーターのコードではなく、仕様のフィールドに対応します

mcp_token_efficiency、mcp_tool_design、mcp_remote_transport、mcp_surface_strategy のいずれかが満点に達していない場合、ほとんどの場合、修正方法は仕様を編集して再生成すること（または、新しく生成したツリーから regen-merge すること）であり、ジェネレーターテンプレートを変更することではありません。Polish でこれらに対応することは可能です。これらを「ジェネレーターが管理するファイルへの機能追加、レトロ候補」と分類しないでください。Cobratree のシェルアウトツールは、すでに Short（オペレーター向けの Long ヘルプではありません）からカタログ化されます。そのため、残っている mcp_token_efficiency の改善余地は、フレームワークの --help ではなく、型付きエンドポイントの説明にあります。

弱い評価項目	改善する仕様フィールド	spec.yaml の mcp: ブロックに追加する内容
mcp_remote_transport	mcp.transport	transport: [stdio, http]（spec.DefaultRemoteTransportEndpointThreshold 以下の小規模な API では、型付きエンドポイントにこれがデフォルトで設定されます。より限定的なリストを仕様で選択した場合、または API がしきい値を超えていてもリモートからのアクセスを可能にしたい場合にのみ、オーバーライドが必要です）
mcp_token_efficiency、mcp_surface_strategy	mcp.endpoint_tools、mcp.orchestration	endpoint_tools: hidden + orchestration: code（Cloudflare のパターン：生のエンドポイントツール約 70 個を <api>_search + <api>_execute に集約し、すべてのエンドポイントには引き続き execute 経由でアクセスできます）
mcp_tool_design	mcp.intents	API がサポートするワークフローについて、複数ステップのインテント構成を定義します
mcp_description_quality	mcp-descriptions.json（CLI ルートにあるオーバーライドファイル）	ツールごとの説明文をオーバーライドします。仕様から生成された簡素な説明文を、仕様を編集せずに、より充実したテキストにできます

推奨しきい値：型付きエンドポイントが 50 を超える場合は、4 項目すべて（transport、endpoint_tools=hidden、orchestration=code、主要なワークフロー向けの intents）を推奨するのがデフォルトです。小規模な API（spec.DefaultRemoteTransportEndpointThreshold 以下）では、http トランスポートがすでにデフォルトで設定されているため、仕様を編集しなくても mcp_remote_transport は 10/10 になります。明示的にリストを限定している仕様の場合にのみ、この項目を指摘してください。詳細なリファレンスは docs/SPEC-EXTENSIONS.md を参照してください。

仕様を編集した後、再生成するか、変更を公開済みライブラリに regen-merge して、更新した mcp: ブロックをテンプレートに反映してください。Cobratree が検出した新しいコマンドは、いずれの場合も引き続き MCP ツールとして表示されるため、仕様の変更は不要です。

経験則：スコアカードが存在しなくても価値がある修正なら、実施してください。スコアを上げることだけが動機なら、実施しないでください。

差分を表示し、結果ブロックを出力する

差分をユーザーに表示してから、構造化された ---POLISH-RESULT--- ブロックを出力します。このブロックにより、呼び出し元のスキル（例：メインの printing-press Phase 5.5）が推奨事項とスコアを確実に解析できます。上の人間向けの表はユーザー向けです。

Polish Results for <CLI_NAME>:

                    Before    After     Delta
  Scorecard:        XX/100    XX/100    +N
  Verify:           XX%       XX%       +N%
  Live matrix:      exercised/not_exercised -> exercised/not_exercised
  Tools-audit:      XX        XX        -N pending findings

Fixes applied:
  - <one-line description of each fix>

Skipped findings:
  - <finding>: <why you chose not to fix it>

Remaining issues:
  - <one-line description of each issue you tried to fix but couldn't>

---POLISH-RESULT---
scorecard_before: <N>
scorecard_after: <N>
verify_before: <N>
verify_after: <N>
dogfood_before: <PASS|FAIL>
dogfood_after: <PASS|FAIL>
dogfood_live_matrix_before: <exercised|not_exercised|unknown>
dogfood_live_matrix_after: <exercised|not_exercised|unknown>
govet_before: <N>
govet_after: <N>
gosec_before: <N>
gosec_after: <N>
tools_audit_before: <N pending>
tools_audit_after: <N pending>
publish_validate_before: <PASS|FAIL|skipped (mid-pipeline)>
publish_validate_after: <PASS|FAIL|skipped (mid-pipeline)>
fixes_applied:
- <one-line description of each fix>
skipped_findings:
- <finding>: <why you chose not to fix it>
remaining_issues:
- <one-line description of each issue you tried to fix but couldn't>
ship_recommendation: <ship|ship-with-gaps|hold>
further_polish_recommended: <yes|no>
further_polish_reasoning: <one sentence explaining the call>
---END-POLISH-RESULT---

3 つのリストは、それぞれ用途が異なります。

• fixes_applied：変更した内容です。呼び出し元がこれを表示します。
• skipped_findings：見つけたものの、理由を添えて意図的に修正しなかった問題です（例：「verify は stale を read と分類しています。これはスコアラーのバグであり、CLI の問題ではありません」「version の thin-short は正確で簡潔なため、そのままにしました」）。呼び出し元はこれを提示し、手動で対処するかどうかをユーザーが判断できるようにします。
• remaining_issues：修正を試みたものの、解決できなかった問題です。

publish_validate_* の値。 polish が publish-validate を実行した場合（スタンドアロンモード）は、PASS または FAIL を出力します。polish がこれをスキップした場合（ミッドパイプラインでの呼び出し、STANDALONE_MODE=false）は、文字列 skipped (mid-pipeline) をそのまま出力します。スキップ値は情報提供のみを目的とします。呼び出し元は、polish の ship_recommendation を CLI レベルの保留に連動させるかどうかを判断する際、これを失敗として扱ってはいけません。

dogfood_live_matrix_* の値。 live-check が実際のサンプルを 1 つ以上評価した場合に限り、exercised を出力します。モックのみ、トークンなし、調査なし、または評価済みサンプルなしの場合は、not_exercised を出力します。dogfood_after: PASS でありながら dogfood_live_matrix_after: not_exercised の場合、人間向けの要約には dogfood PASS (mock only; live matrix not exercised — run the live gate before publish) と記載し、親呼び出し元が後続のライブゲートを明示的に担当する場合を除き、ship_recommendation は hold にします。

gosec_* の値。 生成ファイルのトリアージ後も、この印刷用 CLI に関連する gosec の指摘件数を出力します。これらの値は、意図的に /tmp/polish-gosec-*.json の Issues[] の生の件数とは異なります。skipped_findings に振り分けられたジェネレーター由来の指摘は、再検討候補として数えないでください。ただし、保留を招く未解決の手書きコードの指摘は数えてください。

further_polish_recommended の選択

これは件数ではなく、あなたの判断で決めてください。残っている問題を別の polish 呼び出しで解決できる現実的な見込みがある場合は、yes にします。

• remaining_issues に、時間切れで対応できなかった verify または dogfood の失敗が含まれており、各失敗にもっと注意を払えば新たなパスで解決できそうな場合。
• 今回適用した修正により、依存する問題が解消され、今回対応できなかった問題に手を付けられるようになった可能性がある場合。
• 今回のパスでソースツリーを変更した後、SKILL と CLI の不整合を再確認する必要がある場合。

別の呼び出しをしても同じ作業を繰り返すだけの場合は、no にします。

• remaining_issues が、フラグシップコマンドの名前変更、デフォルトの動作の選択、構造上のトレードオフの受け入れなど、ユーザーだけが判断できる内容の場合。
• 今回、異なる 2 つの方法で修正を試み、どちらも同じ理由で失敗した場合。
• 障害の原因が外部要因（API の仕様変更、レート制限、認証情報の不足など）であり、新たな polish 実行でも状況が変わらない場合。
• remaining_issues が空で、skipped_findings がすべて環境要因または構造上の問題である場合。polish でできることは残っていません。

further_polish_reasoning は、呼び出し元がそのまま表示する 1 文にします。具体的に記述してください（例：「analytics export と report show の verify 失敗は解決できそうでしたが、早く諦めすぎました」）。「さらに polish を行うと役立つかもしれません」のような一般的な表現は避けてください。呼び出し元はこのシグナルに基づいて、次のプロンプトで「もう一度 polish」を提示するかどうかを決めます。理由が曖昧だと、プロンプトも曖昧になります。

公開の提案

STANDALONE_MODE が true でない場合は、このセクション全体をスキップしてください。 STANDALONE_MODE は、呼び出し元のモードに基づいて上記の「Resolve CLI」ブロックで設定されます。スラッシュコマンドによる呼び出し（/printing-press-polish ...）、または args で --standalone を渡す Skill ツール呼び出しの場合は true、それ以外は false です。false の場合、polish はメインの SKILL Phase 5.5 または保留パスの「Polish to retry」から呼び出されており、作業中の CLI はまだライブラリに昇格していません。この段階で /printing-press-publish <slug> を実行すると $PRESS_LIBRARY/<slug>/ が対象になりますが、そこは空か、以前の実行結果が古い状態で残っています。この時点で publish を実行すると、対象を解決できずに失敗するか、誤ったコピーを公開することになります。このパスでの公開フローは親スキルが担当するため、結果ブロックを出力して終了してください。

公開のターン境界ルールを適用してください。AskUserQuestion の回答で許可できるのは引き継ぎメッセージのみであり、同じターン内での公開は許可できません。公開するとパブリックライブラリの PR が作成または更新されるため、polish 完了後にユーザーが新たに作成したメッセージが必要です。根拠については references/publish-turn-boundary.md を参照してください。

簡単なチェック：

if [ "$STANDALONE_MODE" != "true" ]; then
  echo "non-standalone caller; skipping Publish Offer"
  return
fi

ゲートとなるのは呼び出し元モードのフラグであり、解決されたパスではありません。--standalone なしの Skill ツール呼び出しでは、パスが $PRESS_LIBRARY/<slug>/ 配下にあっても公開は保留されます。これはより安全なデフォルトであり、逆転した Phase 5.5/5.6 の障害モード（パイプラインの途中で実行した結果、パブリックフォークと PR が作成される）を polish の境界で検出する唯一の方法です。以前のパス部分文字列ヒューリスティック（*.runstate/*）は、ここではもはや重要ではありません。ただし、上記のリサーチディレクトリ解決ブロックには残されています。そこでは実際に存在する 2 つのディスク上のレイアウトから一方を選択しており、公開ゲートとは別の問題だからです。

スタンドアロンで呼び出された場合は、以下の提案に進んでください。

ship または ship-with-gaps の場合：

結果ブロックからプロンプトを作成してください。内容はデータに基づいて決まるため、polish 自体が次のパスは役に立たないと判断した場合に、ユーザーに「もう一度 polish」するか「公開」するかを選ばせることはありません。

推奨

polish の結果に基づいて、推奨するアクションを選んでください。

• ship かつ remaining_issues が空 → 公開を推奨します。
• ship かつ remaining_issues が空でなく、further_polish_recommended: yes → もう一度 polishを推奨します。
• ship かつ remaining_issues が空でなく、further_polish_recommended: no → 残りの問題が CLI の主要コマンドに関係しない場合は公開を推奨します。それ以外の場合は、現状のまま公開（ship 判定では README は自動更新されません）するか、完了するかをユーザーが選べるよう、トレードオフを示してください。
• ship-with-gaps かつ further_polish_recommended: yes → もう一度 polishを推奨します。
• ship-with-gaps かつ further_polish_recommended: no → 公開（polish の公開ロジックでは ship-with-gaps の場合に README の ## Known Gaps にギャップが記載されるため。上記の「Ship logic」を参照）または、公開を妨げるギャップがある場合は完了を推奨します（エージェントの判断）。

メニュー

further_polish_recommended: no の場合は、「もう一度磨き上げる」オプションを完全に非表示にします。「公開」と「完了」は常に選択できるようにします。

磨き上げで次のパスを推奨しない場合は、further_polish_reasoning を状況説明として表示します。ユーザーが、なぜ磨き上げが完了したのかを確認できるようにします。

AskUserQuestion で提示します。例を 2 つ示します。

磨き上げがきれいに収束した場合（remaining_issues が空、further_polish_recommended: no）：

「<CLI_NAME> の磨き上げが完了しました：スコアカード XX/100、検証 XX％。問題なく完了し、修正事項はありません。

推奨：公開。

1. 個別に公開（推奨）— 次のユーザーメッセージで実行する公開コマンドを表示します
2. 今回は完了 — CLI は $PRESS_LIBRARY/ にあります」

磨き上げで次のパスが有効だと判断された場合（remaining_issues が空でない、further_polish_recommended: yes）：

「<CLI_NAME> の磨き上げが完了しました：スコアカード XX/100、検証 XX％。 件の問題が残っています。

磨き上げのメモ：「<further_polish_reasoning>」

推奨：公開前にもう一度磨き上げる。

1. もう一度磨き上げる（推奨）— 残っている 件の問題を解消します
2. 個別に公開 — 次のユーザーメッセージで、そのまま公開するコマンドを表示します
3. 今回は完了 — CLI は $PRESS_LIBRARY/ にあります」

推奨する選択肢を先頭に置き、(推奨) のラベルを付けます。また、先頭に「推奨：」の行を表示し、エージェントの判断を明示します。順序から推測する必要がないよう、3 つの方法で補強します。

「個別に公開」の場合

同じターン内で /printing-press-publish <cli-name> を実行せず、ここで公開ライブラリの PR の確認や作成も行いません。ユーザー自身が新たに作成したメッセージによる明示的な確認が必要であることを伝える引き継ぎメッセージを表示します。公開後に、インライン公開が成功したときに磨き上げが提示していたものと同じ振り返りを公開時に提示できるよう、--from-polish マーカーを含めます。

「公開すると mvanhorn/printing-press-library のフォーク、ブランチのプッシュ、PR の新規作成または更新が行われる可能性があるため、別途ユーザーの確認が必要です。

公開するには、次のメッセージとして以下を送信してください：

/printing-press-publish <cli-name> --from-polish」

引き継ぎメッセージを表示したら、処理を終了します。後のメッセージでユーザーがコマンドを送信した場合は、公開スキルが検証、パッケージ化、公開ライブラリの PR の作成または更新、および --from-polish による公開後の振り返りの提示を担当します。

（STANDALONE_MODE が false の場合、このセクション全体には到達しません。セクション冒頭の Publish Offer ガードによって早期に戻るため、ここで追加のチェックは不要です。）

「もう一度磨き上げる」の場合

同じ CLI でフェーズ 1 → フェーズ 2 → フェーズ 3 を再実行します。追加の磨き上げは最大 2 回までです（最初の 1 回を含めて合計 3 回）。

「今回は完了」の場合

通常どおり終了します。

ルール

• すべて修正します。修正前に承認を求めないでください。磨き上げは自律的に行います。
• 結果は正直に報告します。改善した点と改善しなかった点を示します。
• 新機能は追加しません。磨き上げでは機能の不足ではなく、品質上の問題を修正します。
• 調査や生成を再実行しません。磨き上げは、現状の CLI を対象にします。
• printing-press ジェネレーターは変更しません。それは /printing-press-retro の担当です。
• $CLI_DIR の外にあるファイルは変更しません。
• 磨き上げで Cobra コマンドを追加または名前変更した場合、MCP サーフェスは、生成された internal/mcp/cobratree のランタイムミラーを通じて自動的に更新されます。README/SKILL の説明やレジストリの表示を変更する必要がある場合に限り、novel_features を更新します。デバッグ専用コマンドには cmd.Annotations["mcp:hidden"] = "true" を使用します。
• 磨き上げの 1 回の実行につき、修正と再診断は最大 1 回です。「もう一度磨き上げる」では追加の実行を行います（合計最大 3 回）。
• 創造的な判断を伴う修正より、機械的な修正を優先します。CLI の説明など、創造的な判断が必要な場合は、入手可能であれば manuscripts の調査概要を使用します。