cdk-preflight 0.0.107 → 0.0.109

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

@@ -35,6 +35,11 @@ cdk-preflight のルール追加パイプライン。AGENTS.md の設計原則
 
 ## セッションの切り方（コンテキスト予算）
 
+**`run-preflight-issue`（オーケストレーター）経由で走っている場合、⑤⑥⑦ は 1 スライス = 1 サブエージェントが丸ごと持つ。**
+`/clear` は要らず、スライスの切り方（20〜25 本・候補 id のプレフィックス境界・同一サービスは直列）と
+push / PR の承認待ちはオーケストレーター側の責務。**自分がそのサブエージェントである場合、さらにエージェントを spawn せず、
+実機で落ちたルールはその場で削って報告する。** このスキルを人間が直接使うときだけ、下の `/clear` 運用に従う。
+
 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>/` 配下のファイルだけを引き継ぐ:
 
 | フェーズ | 入口 | 出口 |

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

@@ -93,6 +93,11 @@ EOL ランタイム、廃止インスタンスタイプ、リージョン非対
 
 ## セッションの切り方（コンテキスト予算）
 
+**`run-preflight-issue`（オーケストレーター）経由で走っている場合、フェーズ境界 = サブエージェント境界なので `/clear` は要らない。**
+オーケストレーターが成果物を読まないので親のコンテキストが伸びず、下の表の受け渡しはそのままサブエージェントへの
+プロンプトとファイルで実現される。**自分がそのサブエージェントである場合、さらにエージェントを spawn しない。**
+このスキルを人間が直接使うときだけ、下の `/clear` 運用に従う。
+
 このパイプラインの API コストは **`往復回数 × 平均コンテキスト長`** でほぼ決まる。2026-09-08 に本プロジェクトの全トランスクリプトを集計した実測（16 セッション / 3,352 往復 / cache_read 850 Mtok / 概算 $1.9k）:
 
 - **cache_read が入力トークンの 98%**。**1 往復あたりの固定費がコンテキスト長に比例する**ので、長いセッションを続けること自体が課金される

package/.claude/skills/run-preflight-issue/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: run-preflight-issue
+description: rule-discovery issue 1 本を 1 指示で完走させるオーケストレーター。棚卸し／API 一次選別／実装スライスをそれぞれ別のサブエージェントに投げ、報告と考慮事項を受け取って次のエージェントに渡し、進捗を台帳に書く。自分は成果物の中身を読まないのでコンテキストが膨らまない。issue 番号だけ渡して起動する。
+---
+
+# run-preflight-issue
+
+`/run-preflight-issue <issue 番号 | next> [--from=A|B|C]`
+
+rule-discovery issue 1 本（例 #64 Glue + Athena）を、**棚卸しから PR 承認待ちまで 1 指示で**通す。各フェーズは
+`find-preflight-rules` / `add-preflight-rule` をそのまま読むサブエージェントが実行し、このスキルを走らせている
+セッションは**オーケストレーター**として指示・検証・受け渡しだけを行う。
+
+## 鉄則：オーケストレーターはファイルの中身を開かない
+
+このやり方の価値は**コンテキストを汚さないこと**だけであって、それ以外の利点は無い。だから次を破ると全部無駄になる:
+
+- **サブエージェントが作った成果物を `cat` / `Read` しない。** 許されるのは `wc -l`、`grep -c`、`ls`、`head -20 handoff.md` だけ
+- GitHub への投稿は**本文を読まずに** `gh issue comment <n> --body-file <path>` で渡す（28KB のコメントでも 0 トークン）
+- サブエージェントの報告テキストは context に入るので、**報告の書式を指定して短く保たせる**（下記「報告の型」）
+- ドキュメント取得・テンプレート生成・ログ読みは全部サブエージェント側の仕事。オーケストレーターは 1 行も読まない
+
+コストの実測（2026-09-08 集計）は `find-preflight-rules` の「セッションの切り方」にある。要点は
+**cache_read が入力の 98%**、つまり長いコンテキストを抱えたまま往復を続けること自体が課金される、という点だけ。
+サブエージェントは cold start なので、この固定費を親から切り離せる。
+
+## 起動と再開
+
+1. 引数が `next` なら #91（rule discovery queue）の未着手の先頭を拾う。issue 番号ならそれ。
+2. 作業ディレクトリは `~/cdk-preflight-surveys/<service>-<issue>/`（例 `glue-athena-64/`）。無ければ作る。
+3. **現在フェーズは `head -20 handoff.md` の台帳から判定する**（無ければ A から）。`--from` はその上書き。
+4. issue に「着手します（日付）＋スコープと進め方」のコメントを投稿する（キューの運用メモが着手記録を求めている）。
+
+## 台帳（`handoff.md`）
+
+`handoff.md` の**先頭**に必ずこの表を置く。**この表を書き換えるのはオーケストレーターだけ**で、サブエージェントは
+自分のフェーズの節を下に追記するだけ。`/clear` されても落ちても、`head -20` だけで再開できるのが唯一の目的。
+
+```markdown
+| フェーズ | 状態 | エージェント | 成果物 | 人間待ち |
+|---|---|---|---|---|
+| A 棚卸し＋重複ガード | done | ae888…(A) | candidates.json / guard-out.txt | - |
+| B API 一次選別 | done | 3f12…(B) | api-triage.tsv / api-class.json | - |
+| C1 実装（athena 15 本） | done | 9ab0…(C1) | rules/athena/*, branch feat/athena-rules | push/PR 承認 |
+| C2 実装（glue job 系） | todo | - | - | - |
+```
+
+状態は `todo` / `running` / `done` / `blocked` の 4 つ。`blocked` には理由を 1 行で添える。
+
+## フェーズとエージェントの割り当て
+
+| エージェント | 読ませる手順書 | 入口 | 出口 |
+|---|---|---|---|
+| **A 調査** | `find-preflight-rules` 手順 1〜3 | サービス名 / issue 本文 | `inventory.md` / `candidates.json` / `guard-out.txt` / `issue-comment.md` |
+| **B API 一次選別** | `find-preflight-rules` 手順 3 の「サービス API を直接叩けるものは先に叩く」 | `candidates.json` / `base.py` | `api-triage.tsv`（id / クラス / 判定 / 実機メッセージ / 制約 / レンズ）/ `api-class.json` / `issue-comment-api.md` |
+| **C1..Cn 実装** | `add-preflight-rule` 手順 2〜6 | `api-triage.tsv` の該当スライス | `rules/<svc>/*` / `meta.yaml#repro` / ブランチ＋コミット |
+
+- **A を 1 個にまとめる**のは、棚卸し・仮説・ガードが同じドキュメント知識を共有するから。ここを割ると 2 個目が読み直す
+- **B を必ず分ける**のは、AWS 認証と課金物という A とは別種の危険があるから。B の失敗は金を使う
+- **C を割らない**（生成→ローカルゲート→実機ゲート→meta.yaml→コミットを 1 エージェントに持たせる）のは所有権の問題。
+  実機で落ちたルールはその場で削るのが正しく、⑥だけ別エージェントにすると⑤の成果物を他人が直す形になる
+- **issue コメントの投稿はオーケストレーターがやる**（A と B の直後）。サブエージェントに `gh` を握らせない
+
+## サブエージェントに渡すプロンプトの必須項目
+
+毎回この 7 つを入れる。1 つでも抜くと今までに踏んだ穴を踏み直す:
+
+1. **読ませるスキル名**を明示（「最初に `add-preflight-rule` スキルを Skill ツールで起動して従え」）。
+   同時に**起動してはいけないスキル**も書く（実装エージェントに `find-preflight-rules` を起動させない）
+2. **入力ファイルの絶対パスと 1 行説明**。そして「**最初に `inventory.md` を読め**」。
+   ファイルに書いてあるだけでは読まれない
+3. **前フェーズの「考慮事項」「申し送り」を逐語でコピー**する。台帳を参照させるのではなく、プロンプトに貼る
+4. **課金物の禁止**: 禁止リソース型を名指しし、「**create API を呼ぶ前に落とす**」「pass フィクスチャを作らない
+   （`--fail-only`）」「既存の無料下敷きは消さない」。`絶対に課金パネルのリソースを作らない`はユーザーの明示指示
+5. **git の縛り**: `main` に直接コミットしない / ブランチを切る / **push も `gh pr create` もしない** /
+   コミットメッセージに attribution 行を入れない
+6. **報告の型**（下記）と「日本語で」
+7. **迷ったら減らす方向に倒せ**。中途半端なルールを 1 本入れるより、確実な本数だけ入れて残りを報告させる
+
+### 報告の型
+
+サブエージェントの報告は親の context に入る。4 見出しだけを短く書かせ、詳細は `handoff.md` に追記させる:
+
+- **結果**（本数・ブランチ名・テスト結果）
+- **落としたものと理由**
+- **考慮事項**（次のフェーズが知らないと踏む穴。オーケストレーターが次のプロンプトに逐語でコピーする）
+- **人間の判断が必要**（ハード関門でなくてよい。台帳に溜める）
+
+## 受け取ったら必ずやる検証
+
+報告を信用しない。**安いものだけ自分で回す**（2026-09-13 実測: 報告の「エンジンは W3030 止まり」が誤りだった。
+ただし親の前提の方が間違っていたので、食い違ったら両方を疑う）:
+
+```bash
+ls rules/<svc> | wc -l                                                     # 本数が報告と一致するか
+npx ts-node --transpile-only --project test/tsconfig.json scripts/rule-check.ts check <svc>   # 0 NG か
+grep -rl '<禁止リソース型>' rules/<svc> | wc -l                             # 課金物が 0 件か
+git log --oneline -1 && git branch --show-current                          # コミットがあり main でないか
+```
+
+B の後は課金物の実在確認も回す（例 `aws athena list-capacity-reservations`）。**食い違ったら同じエージェントに
+`SendMessage` で差し戻す** — コンテキストが残っているので cold start より圧倒的に安い。3 往復で直らなければ人間に上げる。
+
+## スライスの切り方
+
+- 1 スライス **20〜25 本**まで、**候補 id のプレフィックス境界**で割る（実測: Athena 15 本で 20 万トークン / 55 分）
+- 同一サービスのスライスは**直列**。`rules/_lib/<svc>.rego` を 2 エージェントが同時に触ると必ず衝突する
+- 別サービスなら並列可。そのときだけ Agent の `isolation: "worktree"` を使う
+  （`node_modules` と `bundle-rules` の初回セットアップが重いので、必要なときだけ）
+- A の報告にスライス案があればそれを採用する（サービス構造を見ているのは A）
+
+## 関門
+
+**自動でやってよい**: issue コメントの投稿（着手・調査結果・API 結果）、実機再現ゲート（無料〜数円のスタックを多数作る）、
+ブランチへのコミット。
+
+**止まって人間に聞く**:
+
+- `git push` と `gh pr create` — レビューは他人の時間を使う。ここで**台帳に溜めた「人間の判断が必要」も一緒に出す**
+- 課金リソースが必要だと判明したとき（作らずに報告して止まる）
+- `.claude/settings*.json` の permission を足したくなったとき（**自分で書き換えない**）
+
+**絶対にしない**: 課金リソースの作成、issue の close、#91 のチェックボックス操作（PR マージが人間の手なので、
+その先は全部人間の仕事）、既存の無料下敷き（`pfdb` / `pfwg` / `cdkpf-*-probe` ロールやバケット）の削除。
+
+## やらないこと
+
+- **成果物のレビュー**。読んだ時点でオーケストレーターのコンテキストが調査セッション 1 本ぶんに膨らむ。
+  品質はサブエージェント側の手順書（`add-preflight-rule` の境界値規定・実機ゲート）と上の機械的検証で担保する
+- **フェーズごとにモデルを下げる**のは既定ではやらない。効いているのは「拒否メッセージ 97 本を 1 行ずつ読んで
+  候補の制約を名指ししているか判定する」「境界値の rego を詰める」という判断の質で、そこはケチらない。
+  実験するなら B から（`Agent` の `model` 引数）
+- **人間の判断待ちで全体を止める**。ハード関門（push/PR・課金・permission）以外は台帳に溜めて先へ進む

package/.jsii

@@ -9600,6 +9600,6 @@
       "symbolId": "src/index:PreflightOptions"
     }
   },
-  "version": "0.0.107",
-  "fingerprint": "wHYwJrMjh9M9p4HPkCELY2Lht9UN3h0QjBXtrLp50eA="
+  "version": "0.0.109",
+  "fingerprint": "7hgkCw7HE9enkziCXU5Md74La+RbSqXPtkVXUW7HurE="
 }

package/AGENTS.md

@@ -104,6 +104,33 @@ test/                       # 4 layers: rules / loader / structure / cli
 bench/                      # real-deploy verification (needs an AWS account; not part of CI)
 ```
 
+## Working a discovery issue (the skills)
+
+Three skills in `.claude/skills/` cover the work end to end. Pick the entry point by what you have:
+
+| You have | Skill | What it does |
+|---|---|---|
+| An issue number from the queue (#91) | **`run-preflight-issue`** | Orchestrates the whole issue. Dispatches each phase to a separate subagent and never opens a deliverable itself |
+| A service but no candidates yet | `find-preflight-rules` | Survey: inventory → 6 lenses → duplication guard → candidate checklist on the issue |
+| One constraint, or a candidate list | `add-preflight-rule` | Implement: rule.rego + fixtures → local gate → real-deploy gate → `meta.yaml` → commit |
+
+`/run-preflight-issue <issue number | next> [--from=A|B|C]` is the normal way in — `next` takes the first unstarted
+item off #91, and the phase is otherwise read from the ledger at the top of `~/cdk-preflight-surveys/<svc>-<issue>/handoff.md`,
+so a cleared or crashed session resumes from `head -20`. Phases map to agents as **A** survey + duplication guard,
+**B** API-direct triage (kept separate: it needs AWS credentials and can spend money), **C1..Cn** one implementation
+slice each (20–25 rules, split on candidate-id prefix, serial within a service so two agents never fight over
+`rules/_lib/<service>.rego`).
+
+Why the indirection: `cache_read` is 98% of input tokens, so a phase costs whatever parent context it drags along.
+A cold subagent drops that fixed cost — and reading its output in the parent puts the cost straight back, which is why
+the orchestrator is forbidden from opening deliverables (`wc -l`, `grep -c`, `gh issue comment --body-file`, nothing more).
+It verifies each report with four cheap mechanical checks instead, and re-dispatches to the same agent when they disagree.
+
+Human gates are explicit: posting issue comments and running the real-deploy gate are automatic; **`git push` and
+`gh pr create` stop for approval** (soft judgement calls are batched and presented there); billable resources are refused
+before the create call; and the orchestrator never edits permission settings, closes an issue, or ticks the queue.
+If you are a subagent running one of these phases, do not spawn further agents.
+
 ## Adding a rule (the pipeline)
 
 1. Identify a constraint that fails only at deploy time (doc page, API error message, war story).

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.107" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdk-preflight.Preflight", version: "0.0.109" };
     /**
      * Register the cdk-preflight rules on an App or Stage.
      */