cdk-preflight 0.0.65 → 0.0.66

package/.claude/skills/add-preflight-rule/SKILL.md

@@ -12,14 +12,11 @@ cdk-preflight のルール追加パイプライン。AGENTS.md の設計原則
 ## 手順
 
 1. **入力の確定**: 追加したい制約を 1 文で書く（対象リソース型、プロパティ、条件、出典 URL または実際に観測したデプロイエラーメッセージ）。制約がまだ特定できていない（「このサービスで何かルールを増やしたい」段階の）場合は、このスキルではなく `find-preflight-rules` を先に使う。
-2. **重複チェック（先にやる）**: 違反最小テンプレートを書き、エンジンに直接かける:
+2. **重複チェック（先にやる）**: 違反最小テンプレートを書き、素のエンジンに直接かける:
    ```bash
-   npx ts-node --project test/tsconfig.json -e "
-   import { loadEngine } from './src/private/enforce';
-   const e = loadEngine();
-   const r = new e.RegoEngine({}).validateDetailed(new e.TemplateFile('<template>'), {});
-   console.log(JSON.stringify(r.diagnostics, null, 2));"
+   npx ts-node --transpile-only --project test/tsconfig.json scripts/rule-check.ts guard <dir>
    ```
+   出力は 1 件 1 行（`BLOCK <file> <ruleId>/<severity>` か `clean <file>`）。
    ERROR/FATAL（source: SCHEMA / CFN_LINT）が既に出るなら**ルールは書かない**。終了し、その旨を報告する。
    判定の全体像（WARN クラスのみ出るがデプロイは失敗するグレーゾーン、L2/cfn-lint/サーバー側検証との棲み分け）は AGENTS.md の「Where this pack sits among validation layers」に従う。L2 (aws-cdk-lib) が同じ検証を持っていても不採用理由にならず、既存ルールの廃止理由にもならない（原則 5）。廃止の引き金は同梱エンジン（か CFN サーバー側検証）がカバーしたときだけで、そのとき重複ガードが自動で赤くなる。
 3. **ルール作成**: `rules/<service>/<rule-id>/` に 4 ファイル。規約:
@@ -27,7 +24,7 @@ cdk-preflight のルール追加パイプライン。AGENTS.md の設計原則
    - ヘルパーは `_pf_<短縮名>_` プレフィックスで一意に
    - `walk` ビルトインは無い。`to_number`/`object.get`/`flatten_list`/`resolve` で明示的に書く
    - fail テンプレートはこのルール**だけ**に違反、pass テンプレートは完全クリーン
-4. **ローカルゲート**: `npx projen bundle-rules && npx jest test/rules.test.ts test/structure.test.ts` が全緑になるまで直す。
+4. **ローカルゲート**: まず `npx ts-node --transpile-only --project test/tsconfig.json scripts/rule-check.ts check <service|rule-id>...` を回す。`rules/` を直接読んで 1 エンジンに全ルールを載せ、fail が自分のルールで鳴るか / pass が全ルール無音か / どちらも組み込みエンジンに止められないかを返す（`bundle-rules` も meta.yaml の evidence も要らないので、実機ゲート前の直しはここで回す。80 本で数秒）。全部 `ok` になってから `npx projen bundle-rules && npx jest test/rules.test.ts test/structure.test.ts`。**jest は `-t` で対象を絞る**。フルスイートは PR 直前の 1 回だけでよく、実測では 401 回中 73 回がフル実行で合計 5.8 時間を溶かしている。
 5. **実機再現ゲート**: `bash bench/verify-rule.sh <rule-id>`（要 AWS 認証）。観測したエラーメッセージと日付を `meta.yaml#repro.evidence` に記録。
    - fail テンプレートがデプロイに**成功**したら、それはドキュメント側の誤り（BROKEN-EXPECTATION）。ルールを削除し、証拠を issue に残して終了する。CloudFront では明文化された制約 9 件中 3 件がこれだった（2026-09-02）
    - **予想と違う理由**で失敗した場合（他アカウントの ARN、ドメイン所有権の検証など）は証拠にならない。サービスエラーが対象の制約そのものを名指しするまでテンプレートを作り直すか、除去できない交絡は `evidence` に明記する
@@ -36,7 +33,7 @@ cdk-preflight のルール追加パイプライン。AGENTS.md の設計原則
 
 ## セッションの切り方（コンテキスト予算）
 
-API コストは **`往復回数 × 平均コンテキスト長`** でほぼ決まる（実測 2026-09-06: cache_read がトークン総量の 96%、AgentCore 回は 1,289 往復 × 平均 365k = 471M）。**1 サービスぶんを 1 セッションで通さない**。`find-preflight-rules` から `candidates.json` を受け取り、下の境界で `/clear` して scratchpad の `<service>/` 配下のファイルだけを引き継ぐ:
+API コストは **`往復回数 × 平均コンテキスト長`** でほぼ決まる（実測 2026-09-08、全 16 セッション集計: cache_read が入力の 98%、平均 258k tok/往復。平均 372k のセッションはルール 1 本 $5.2、213k で切ったセッションは $1.7）。**1 サービスぶんを 1 セッションで通さない**。`find-preflight-rules` から `candidates.json` を受け取り、下の境界で `/clear` して scratchpad の `<service>/` 配下のファイルだけを引き継ぐ:
 
 | フェーズ | 入口 | 出口 |
 |---|---|---|
@@ -46,7 +43,8 @@ API コストは **`往復回数 × 平均コンテキスト長`** でほぼ決
 
 守ること:
 
-- **rule.rego と fail/pass テンプレートを 1 本ずつヒアドキュメントで書かない**。`candidates.json` を読むジェネレータ（`rgen.py` 相当）を 1 個置き、直しはジェネレータ側に入れて再生成する。実測では打ち込んだコマンド文字列のコストが Bash 出力とほぼ同額（$318 対 $389）で、その 73% が 4k 超のヒアドキュメント
-- **書いたファイルを `cat` で読み返さない**。確認は `npx projen bundle-rules` と `npx jest` の結果だけで足りる
+- **rule.rego と fail/pass テンプレートを 1 本ずつヒアドキュメントで書かない**。`candidates.json` を読むジェネレータ（`rgen.py` 相当）を 1 個置き、直しはジェネレータ側に入れて再生成する。実測では打ち込んだコマンド文字列（2.22 Mtok）が Bash 出力（2.52 Mtok）とほぼ同額で、その **63% が 416 回の 4k 超コマンド**
+- **書いたファイルを `cat` で読み返さない**。確認は `scripts/rule-check.ts check` と `npx jest` の結果だけで足りる
+- **独立した呼び出しは 1 レスポンスにまとめる**（実測 3,352 往復の 55% がツール 1 個だけ）。`git status` / `log` / `diff` の確認ループも同様で、1,592 回・3.4 時間かかっている
 - **実機ゲートは 1 本ずつ対話で回さない**。`pending.txt` を回す 1 スクリプトをバックグラウンドで走らせ、ログは `bench-out/<rule-id>.log` に書かせて、戻すのは 1 行のサマリだけにする。完了待ちのポーリングを 1 往復 1 回やらない（1 往復 ≒ 平均コンテキスト長ぶんの再読み込み）
 - ⑤ で候補が数十本あるなら、ジェネレータの入力（`candidates.json`）を直すサイクルに寄せる。個別ルールのデバッグは失敗した数本に絞る

package/.claude/skills/find-preflight-rules/SKILL.md

@@ -78,14 +78,11 @@ EOL ランタイム、廃止インスタンスタイプ、リージョン非対
 
 1. **制約の棚卸し**。そのサービスについて、次の順で拾う。ユーザーガイドの Limits / Quotas ページ、API リファレンスのパラメータ制約、CloudFormation リソースタイプのドキュメント（スキーマではなく散文の方）、実際のデプロイ失敗エラーメッセージ。数値・順序・組み合わせ・排他・命名・リージョン依存に印を付ける。サービスが作成時バリデータを無料 API で公開している場合（Step Functions の `validate-state-machine-definition` は CreateStateMachine と同じバリデータで `--type` も取る）、定義レベルの仮説はまずそれに掛けて一次選別する（2026-09-05、100 件を数分で判定）。ここで拾ったドキュメントの 1 文は**仮説であって証拠ではない**。CloudFront の棚卸し（2026-09-02）では明文化された制約 9 件のうち 3 件が実機でそのままデプロイできた（BROKEN-EXPECTATION）。候補リストは「実機ゲートに掛ける仮説の列」として書き、ドキュメントの断言を根拠に採用を確定させない
 2. **6 レンズで狩り場を回る**。レンズ 3 と 4 から始めると当たりが早い。**レンズに当てはまらない制約もここでは捨てない** — 足切りは次の重複ガードと、実装側の実機ゲートだけ
-3. **重複ガード**。残った候補ごとに最小の違反テンプレートを書き、素のエンジンにかける
+3. **重複ガード**。残った候補ごとに最小の違反テンプレートを 1 つのディレクトリへジェネレータで吐き、素のエンジンに**全件まとめて**かける。1 枚ずつ `ts-node -e` で回さない（エンジン初期化が毎回効いて実測 51 秒/回、しかもコマンド文字列を打ち直すぶん課金される）
    ```bash
-   npx ts-node --project test/tsconfig.json -e "
-   import { loadEngine } from './src/private/enforce';
-   const e = loadEngine();
-   const r = new e.RegoEngine({}).validateDetailed(new e.TemplateFile('<template>'), {});
-   console.log(JSON.stringify(r.diagnostics, null, 2));"
+   npx ts-node --transpile-only --project test/tsconfig.json scripts/rule-check.ts guard <dir>
    ```
+   出力は 1 件 1 行（`BLOCK <file> <ruleId>/<severity>` か `clean <file>`）。
    `ERROR` / `FATAL`（`source` が `SCHEMA` か `CFN_LINT`）が出たら**その候補は捨てる**。`WARN` クラスだけ、あるいは `INFO` だけならグレーゾーンなので、上流に severity の issue を出す候補として記録し、つなぎで実装するなら `upstream: pending-engine` を付ける
    - **CLI のサービスモデルが API より古いことがある**（2026-09-05、`aws wafv2` は `Monetize` と `PreParseTextTransformations` を知らず ParamValidation で落ちた）。CLI が拒否するフィールドだけスタックを立てる。名前が scope / region 単位で一意なサービス（WAFv2）は、並列 bench のフィクスチャ名にルール ID を混ぜる
    - **`--cli-input-json` の blob は base64**（`SearchString` を平文で書くとクライアント側で "Invalid base64" になり、サーバに届かないまま全滅する）
@@ -95,7 +92,11 @@ EOL ランタイム、廃止インスタンスタイプ、リージョン非対
 
 ## セッションの切り方（コンテキスト予算）
 
-このパイプラインの API コストは **`往復回数 × 平均コンテキスト長`** でほぼ決まる。実測（2026-09-06、過去のサービス調査ジョブのトランスクリプト集計）では cache_read がトークン総量の 96%: AgentCore 回が 1,289 往復 × 平均 365k = 471M、Bedrock 回が 461 往復 × 平均 274k = 126M。**1 往復あたりの固定費がコンテキスト長に比例する**ので、長いセッションを続けること自体が課金される。
+このパイプラインの API コストは **`往復回数 × 平均コンテキスト長`** でほぼ決まる。2026-09-08 に本プロジェクトの全トランスクリプトを集計した実測（16 セッション / 3,352 往復 / cache_read 850 Mtok / 概算 $1.9k）:
+
+- **cache_read が入力トークンの 98%**。**1 往復あたりの固定費がコンテキスト長に比例する**ので、長いセッションを続けること自体が課金される
+- 全体平均 258k tok/往復。平均 **372k** で通したセッションはルール 1 本あたり **$5.2**、**213k** で切ったセッションは **$1.7** — 同じ「1 サービス調査 → PR」の仕事で 3 倍差
+- コンテキストに居座っている中身は **Bash の結果 41% ＋ 打ったコマンド 32% = 73%**、ドキュメント取得の結果 12%、thinking 5%。削る先はこの 3 つしかない
 
 後段が必要とするのは前段の**成果ファイルだけ**で会話履歴ではない。フェーズ境界で `/clear` し、受け渡しは scratchpad の `<service>/` 配下のファイルに限る:
 
@@ -110,10 +111,11 @@ EOL ランタイム、廃止インスタンスタイプ、リージョン非対
 
 守ること:
 
-- **ドキュメント本文をコンテキストに残さない**。`read_documentation` / WebFetch は 1 ページ 20〜30k 文字がそのまま以後の全往復ぶん再読みされる（実測で 1 セッション 53 回・$122 相当）。ファイルに落として grep で必要な段落だけ読む
-- **同じテキストを二度載せない**。ヒアドキュメントで書く → `cat` で確認 → diff で再表示、で 3 倍払う。書いたものの確認は `wc -l` / `md5` / `assert` で済ませる。実測では**打ち込んだコマンド文字列のコストが出力とほぼ同額**（$318 対 $389）で、その 73% は 4k 超のヒアドキュメント
-- 候補テンプレートを 1 件ずつ手書きしない。`candidates.json` からジェネレータで吐き、重複ガードも 1 スクリプトで全件回してサマリ行だけ読む
-- 独立した呼び出しは 1 レスポンスにまとめる（実測 1,289 往復中 848 がツール 1 個だけだった）
+- **ドキュメント本文をコンテキストに残さない**。`read_documentation` / WebFetch は 1 ページ 20〜30k 文字がそのまま以後の全往復ぶん再読みされる（占有シェア 12%、実測で 1 セッション 53 回・$122 相当）。ファイルに落として grep で必要な段落だけ読む。AWS のドキュメントは URL に `.md` を付ければ markdown で落ちる
+- **4k 文字超のコマンドを打たない**。打ち込んだコマンド 2.22 Mtok のうち **63% がたった 416 回の 4k 超コマンド**（ジェネレータや rego をヒアドキュメントで流し込んだもの）。スクリプトは一度ファイルに書いて、以後は `node gen.js` と数語で呼ぶ
+- **同じテキストを二度載せない**。書く → `cat` で確認 → diff で再表示、で 3 倍払う。確認は `wc -l` / `md5` / `assert` で済ませる
+- 候補テンプレートを 1 件ずつ手書きしない。`candidates.json` からジェネレータで吐き、重複ガードは `scripts/rule-check.ts guard <dir>` で全件 1 プロセス。返ってくるのは 1 件 1 行
+- **独立した呼び出しは 1 レスポンスにまとめる**（実測 3,352 往復の **55% がツール 1 個だけ**。ここは丸ごと空いている削り代）
 
 ## issue コメントの書式
 

package/.jsii

@@ -9599,6 +9599,6 @@
       "symbolId": "src/index:PreflightOptions"
     }
   },
-  "version": "0.0.65",
-  "fingerprint": "vJo2BVa0aXST+nhFwpZ5A2gGvinnf2lCZE6R5OMlFgE="
+  "version": "0.0.66",
+  "fingerprint": "E/AJjnWQnQQBzEEa+66DGuXFmNoN5Q3eFhyDAgYRsS8="
 }

package/AGENTS.md

@@ -93,6 +93,7 @@ src/index.ts                # Preflight.apply / PreflightOptions (jsii surface
 src/private/enforce.ts      # enforce-mode plugin (calls the engine directly)
 src/rules.generated.ts      # GENERATED from rules/ — never edit; run `npx projen bundle-rules`
 scripts/bundle-rules.ts     # generator + structural validation
+scripts/rule-check.ts       # one-process local gates: `guard` (bare engine) and `check` (fixtures, pre-bundle)
 test/                       # 4 layers: rules / loader / structure / cli
 bench/                      # real-deploy verification (needs an AWS account; not part of CI)
 ```
@@ -114,7 +115,7 @@ bench/                      # real-deploy verification (needs an AWS account; no
    - Helper rules must use a unique `_pf_<rule>_...` prefix (all rules share one package).
    - A helper several rules of one service need (parsing an opaque DSL, enumerating nested scopes) goes in `rules/_lib/<service>.rego` with a `_pf_<service>lib_` prefix (`rules/_lib/sfn.rego` is the reference: ASL from `DefinitionString` *or* the L1 `Definition` object, nested Parallel/Map scopes to depth 3, effective QueryLanguage). Rules never reference another rule's helpers — `exclude` can unload any rule, a lib is always loaded.
    - **Cheap screen for definition-level constraints**: some services expose their create-time validator as a free API (`aws stepfunctions validate-state-machine-definition --type STANDARD|EXPRESS` is the same validator CreateStateMachine runs). Use it to triage doc hypotheses before spending a CloudFormation deploy on each — 100 Step Functions hypotheses took minutes (2026-09-05). The real-deploy gate stays.
-3. `npx projen bundle-rules` then `npx jest test/rules.test.ts test/structure.test.ts` — the duplication guard and fixture checks run here.
+3. `npx ts-node --transpile-only --project test/tsconfig.json scripts/rule-check.ts check <service|rule-id>` while iterating: it reads `rules/` straight from disk into a single engine (no bundle, no meta validation, no jest) and reports, per rule, whether the fail template fires its own rule, the pass template is silent for every rule, and neither trips a built-in ERROR/FATAL. Then `npx projen bundle-rules` and `npx jest test/rules.test.ts test/structure.test.ts` — the duplication guard and fixture checks run there for real. Prefer `jest -t` while iterating; the full suite is 3,228 tests / ~2 min (measured 2026-09-08), so keep it for the pre-PR run.
 4. **Real-deploy gate**: `bash bench/verify-rule.sh <rule-id>` deploys the fail template (expects CREATE to fail; records the service error message) and, where cheap, the pass template (expects success, then deletes). Paste the observed error into `meta.yaml#repro.evidence` with the date. Only `doc-only` rules may skip this, with justification.
 5. Update nothing else by hand — `docs/rules.md` and `src/rules.generated.ts` are generated.
 
@@ -122,6 +123,8 @@ bench/                      # real-deploy verification (needs an AWS account; no
 
 | Task | Command |
 |---|---|
+| Local rule gates, one process (pre-bundle) | `npx ts-node --transpile-only --project test/tsconfig.json scripts/rule-check.ts check [service\|rule-id]` |
+| Duplication guard for candidate templates | `... scripts/rule-check.ts guard <dir>` |
 | Regenerate bundle + docs | `npx projen bundle-rules` |
 | Unit tests | `npx jest` |
 | Full build (jsii, lint, tests, package) | `npx projen build` |

package/lib/index.js

@@ -17,7 +17,7 @@ const rules_generated_1 = require("./rules.generated");
  * Preflight.apply(app);
  */
 class Preflight {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdk-preflight.Preflight", version: "0.0.65" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdk-preflight.Preflight", version: "0.0.66" };
     /**
      * Register the cdk-preflight rules on an App or Stage.
      */

package/package.json

@@ -89,7 +89,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.65",
+  "version": "0.0.66",
   "jest": {
     "coverageProvider": "v8",
     "testMatch": [