printing-press-score

/printing-press-score

生成された CLI を Steinberger の基準で採点します。再採点、名前またはパスによる採点、2 つの CLI の比較に対応しています。

クイックスタート

/printing-press-score                              # rescore current CLI
/printing-press-score notion-pp-cli-4              # score by name
/printing-press-score ~/my-cli                     # score by path
/printing-press-score notion-pp-cli-4 vs notion-pp-cli-2  # compare two

前提条件

• Go 1.26.10 以降がインストールされていること
• cli-printing-press バイナリが PATH 上にあること（go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest でインストール）

ステップ 0：セットアップ

ほかのコマンドを実行する前に、セットアップコントラクトを実行して、cli-printing-press バイナリが PATH 上にあることを確認し、スコープ変数を初期化します。

# min-binary-version: 4.0.0

# Derive scope first — needed for local build detection
_scope_dir="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
_scope_dir="$(cd "$_scope_dir" && pwd -P)"

# Prefer local build when running from inside the printing-press repo.
_press_repo=false
if [ -x "$_scope_dir/cli-printing-press" ] && [ -d "$_scope_dir/cmd/cli-printing-press" ]; then
  _press_repo=true
  export PATH="$_scope_dir:$PATH"
  echo "Using local build: $_scope_dir/cli-printing-press"
elif ! command -v cli-printing-press >/dev/null 2>&1; then
  if [ -x "$HOME/go/bin/cli-printing-press" ]; then
    echo "cli-printing-press found at ~/go/bin/cli-printing-press but not on PATH."
    echo "Add GOPATH/bin to your PATH:  export PATH=\"\$HOME/go/bin:\$PATH\""
  else
    echo "cli-printing-press binary not found."
    echo "Install with:  go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest"
  fi
  return 1 2>/dev/null || exit 1
fi

# Resolve and emit the absolute path the agent must use for every later
# `cli-printing-press` invocation. `export PATH` above only affects this one
# Bash tool call; subsequent calls open a fresh shell and resolve bare
# `cli-printing-press` against the user's default PATH, where a stale global
# can silently shadow the local build. The agent captures this marker and
# substitutes the absolute path into every later invocation.
if [ "$_press_repo" = "true" ]; then
  PRINTING_PRESS_BIN="$_scope_dir/cli-printing-press"
else
  PRINTING_PRESS_BIN="$(command -v cli-printing-press 2>/dev/null || true)"
fi
echo "PRINTING_PRESS_BIN=$PRINTING_PRESS_BIN"

PRESS_BASE="$(basename "$_scope_dir" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9_-]/-/g; s/^-+//; s/-+$//')"
if [ -z "$PRESS_BASE" ]; then
  PRESS_BASE="workspace"
fi

PRESS_SCOPE="$PRESS_BASE-$(printf '%s' "$_scope_dir" | shasum -a 256 | cut -c1-8)"
PRESS_HOME="${PRINTING_PRESS_HOME:-$HOME/printing-press}"
PRESS_RUNSTATE="$PRESS_HOME/.runstate/$PRESS_SCOPE"
PRESS_LIBRARY="$PRESS_HOME/library"
PRESS_MANUSCRIPTS="$PRESS_HOME/manuscripts"
PRESS_CURRENT="$PRESS_RUNSTATE/current"

mkdir -p "$PRESS_RUNSTATE" "$PRESS_LIBRARY" "$PRESS_MANUSCRIPTS" "$PRESS_CURRENT"

セットアップコントラクトを実行した後、標準出力から PRINTING_PRESS_BIN=<abs-path> の行を取得します。このスキルで以降に実行するすべての cli-printing-press ... 呼び出しでは、この絶対パスを使用してください（文字列 $PRINTING_PRESS_BIN そのものではなく、その値に置き換えてください）。上記の export PATH が影響するのは、それを実行する単一の Bash ツール呼び出しだけです。そのため、後続の呼び出しでは新しいシェルが起動し、単独の cli-printing-press はユーザーのデフォルトの PATH で解決され、古いグローバル版がローカルビルドより優先される可能性があります。

バイナリのパスを取得したら、バイナリのバージョン互換性を確認します。このスキルの YAML フロントマターから min-binary-version フィールドを読み取ります。<PRINTING_PRESS_BIN> version --json を実行し、出力からバージョンを解析します。semver の規則に従って 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.」

今回の実行状態は $PRESS_RUNSTATE から解決します。公開済み CLI は $PRESS_LIBRARY から解決します。アーカイブ済み原稿は $PRESS_MANUSCRIPTS から解決します。

ステップ 1：引数を解析する

ユーザーが /printing-press-score の後に入力した内容を読み取ります。入力は自由形式です。構文を強制せず、意図を解釈してください。

除外する語句： compare、vs、versus、and、against、with、to

除外語句を取り除いた後、残りのトークン数を数えます。

• 0 トークン → 現在のものを再採点モード
• 1 トークン → 単一のものを採点モード
• 2 トークン → 比較モード

ステップ 2：CLI ディレクトリを解決する

各 CLI 識別子をディレクトリパスに解決します。

トークンに / または . が含まれる場合

パス（絶対パスまたは相対パス）として扱います。ディレクトリが存在することを確認してください。

トークンが単純な名前の場合

次の場所を順番に試します。

1. $PRESS_LIBRARY/<name>/ — 完全一致
2. $PRESS_LIBRARY/<name>-pp-cli/ — -pp-cli サフィックス付き
3. どちらも存在しない場合は、Glob $PRESS_LIBRARY/<name>-pp-cli*
4. Glob の一致がちょうど 1 件で、その項目がディレクトリなら、それを使用します
5. Glob の一致が複数ある場合は、AskUserQuestion を使って番号付きメニューを表示します

どちらも存在しない場合は、今回の実行状態とアーカイブ済み状態をスキャンします。 6. Glob を使って $PRESS_RUNSTATE/runs/*/state.json ファイルを検索します 7. 各ファイルを読み取り、output_dir または working_dir の値のベース名に名前が含まれているか確認します 8. 該当する項目が見つかり、そのディレクトリが存在する場合は、それを使用します

何も解決できない場合は、次のエラーを報告します：「CLI '' が見つかりません。パスを指定するか、名前を確認してください。」

現在のものを再採点（0 トークン）

1. Glob を使って、すべての $PRESS_CURRENT/*.json ファイルを検索します
2. 各ファイルから api_name、state_path、working_dir を取得します
3. working_dir が実際にディスク上に存在するものに絞り込みます
4. 見つからない場合は、Glob $PRESS_LIBRARY/*-pp-cli* を検索し、代わりにそれらのディレクトリを使用します
5. 1 件だけ見つかった場合 → 自動的に使用します
6. 複数見つかった場合 → AskUserQuestion を使って番号付きメニューを表示します。

   Multiple CLIs found. Which one to score?
   1. stripe-pp-cli ($PRESS_LIBRARY/stripe-pp-cli)
   2. notion-pp-cli ($PRESS_LIBRARY/notion-pp-cli)
   3. linear-pp-cli ($PRESS_LIBRARY/linear-pp-cli)
   

7. 何も見つからない場合 → 次のように報告します：「生成された CLI が見つかりません。名前またはパスを指定してください。」

ステップ 3：Tier 2 スコアリング用の仕様を見つける

解決した各 CLI ディレクトリについて、OpenAPI 仕様を見つけます。

1. <cli-dir>/spec.json を確認します。生成時にパイプラインが YAML 仕様を JSON に変換します。
2. 見つからない場合は、$PRESS_RUNSTATE/runs/*/state.json ファイルを検索し、この CLI のディレクトリに一致するものを探します。その spec_path フィールドを読み取ります。そのファイルがディスク上に存在する場合は、それを使用します。
3. 仕様が見つからない場合は、--spec を指定せずに続行します。ユーザーに次のように伝えます。「仕様が見つかりませんでした。仕様由来の評価項目は N/A として分母から除外されます。完全なスコアリングを行うには、仕様のパスを指定してください。」

ステップ 4：スコアカードを実行する

単一スコアモード

スコアカードコマンドを実行します。

cli-printing-press scorecard --dir <resolved-path> --json

仕様が見つかった場合は、--spec <spec-path> を追加します。

JSON 出力を解析します。構造は次のとおりです。

{
  "api_name": "...",
  "steinberger": {
    "output_modes": 8,
    "auth": 7,
    "error_handling": 6,
    "terminal_ux": 9,
    "readme": 5,
    "doctor": 10,
    "agent_native": 7,
    "local_cache": 4,
    "breadth": 7,
    "vision": 6,
    "workflows": 3,
    "insight": 5,
    "path_validity": 0,
    "auth_protocol": 0,
    "data_pipeline_integrity": 7,
    "sync_correctness": 6,
    "type_fidelity": 4,
    "dead_code": 3,
    "total": 72,
    "percentage": 72
  },
  "overall_grade": "B",
  "gap_report": ["..."],
  "unscored_dimensions": ["path_validity", "auth_protocol"]
}

unscored_dimensions が存在する場合、それらの評価項目は 0/x ではなく N/A として表示し、修正可能な CLI の欠陥ではなく、分母から除外された項目として説明してください。後方互換性のため、JSON では数値フィールドは引き続き 0 としてエンコードされます。実際のゼロと N/A を区別するには、コンシューマーが unscored_dimensions を使用する必要があります。

学習ループの評価は静的な動作に基づくものであり、存在するだけでは加点されません。スコアカードでは、ルートコマンドへの teach／recall／learnings の登録と、空ではないエンティティ検索シード（または仕様に記録された「エンティティなし」の例外）が評価されます。学習ループはデフォルトで有効なため、internal/learn/ が存在しても加点されません。学習ループの不足を説明する際は、ファイルの不足ではなく、シードの不足またはコマンドの未登録を指摘してください。実行証明（検証マトリックス、learnings stats）は検証とドッグフードに属し、スコアカードはバイナリを実行しません。

比較モード

2 つの Bash ツール呼び出しを同時に行い、両方のスコアカードコマンドを並列で実行します。

# Call 1:
cli-printing-press scorecard --dir <path1> --spec <spec1> --json

# Call 2:
cli-printing-press scorecard --dir <path2> --spec <spec2> --json

両方の JSON 出力を解析します。

ステップ 5：出力を表示する

単一スコア表

情報量の多い Markdown テーブルを表示します。注：Tier 1 の評価項目はすべて /10 です。Tier 2 の評価項目は、TypeFidelity と DeadCode が /5、それ以外は /10 です。

Scorecard: <api_name>

Infrastructure (Tier 1)
| Dimension      | Score |
|----------------|-------|
| Output Modes   | 8/10  |
| Auth           | 7/10  |
| Error Handling | 6/10  |
| Terminal UX    | 9/10  |
| README         | 5/10  |
| Doctor         | 10/10 |
| Agent Native   | 7/10  |
| Local Cache    | 4/10  |
| Breadth        | 7/10  |
| Vision         | 6/10  |
| Workflows      | 3/10  |
| Insight        | 5/10  |

Domain Correctness (Tier 2)
| Dimension               | Score |
|--------------------------|-------|
| Path Validity            | 9/10  |
| Auth Protocol            | 8/10  |
| Data Pipeline Integrity  | 7/10  |
| Sync Correctness         | 6/10  |
| Type Fidelity            | 4/5   |
| Dead Code                | 3/5   |

**Total: 72/100 — Grade B**

gap_report が空でない場合は、不足項目を列挙します。

Gaps:
- <gap 1>
- <gap 2>

unscored_dimensions が空でない場合は、表の後に注記を追加します。

Note: path_validity, auth_protocol were unscored and omitted from the denominator. Provide a spec path for full scoring.

比較表

差分列を含む左右並びの表を表示します。1 つ目の CLI 名と 2 つ目の CLI 名を列見出しにします。差分は（CLI 1 のスコア - CLI 2 のスコア）として計算します。正の値には +N、負の値には -N、ゼロには — を表示します。

Scorecard Comparison: <name1> vs <name2>

Infrastructure (Tier 1)
| Dimension      | <name1> | <name2> | Delta |
|----------------|---------|---------|-------|
| Output Modes   | 8/10    | 5/10    | +3    |
| Auth           | 7/10    | 7/10    | —     |
| ...            |         |         |       |

Domain Correctness (Tier 2)
| Dimension               | <name1> | <name2> | Delta |
|--------------------------|---------|---------|-------|
| Path Validity            | 9/10    | 6/10    | +3    |
| ...                      |         |         |       |

| **Total**  | **72/100 (B)** | **56/100 (C)** | **+16** |

エラー処理

• cli-printing-press バイナリが PATH にない場合 → インストール手順を表示します：go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest
• スコアカードコマンドが失敗した場合 → 標準エラー出力全体とともにエラーを報告します
• CLI ディレクトリが存在しない場合 → 解決できなかった名前を報告します
• JSON の解析に失敗した場合 → 生の出力を表示し、解析エラーを報告します