Pre-choice usable artifact execution
Purpose & Output Contractの最小の実成果物をmain contextで作成する。effect別のparse/open・secret・irreversible・corrupt guardだけを実行し、現物path・digest・開き方を提示してからaccept-as-is/light/standard/detailedを記録する。accept-as-isはその場でhandoff完了とし、後続sectionを実行しない。
Post-choice selected improvement execution
以下の既存workflow・goal-seek・評価・修正sectionはlight/standard/detailedが記録されてsemantic_evaluator_startedへ遷移した場合だけ実行する。release/exhaustiveは別の明示eventを必要とする。
<!-- external-mutation-guard-cli:v1 -->
Canonical external mutation receipt flow (mandatory)
Never execute the external mutation argv directly. Replace every angle-bracket placeholder
with the reviewed value from this run; the central CLI fails closed on missing/invalid values.
Resolve the guard plugin root once, before preview. An installed plugin cannot reach a sibling
plugin as <plugin root>/.., so never guess that path:
python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/extract-plugin-root.py" skill-governance-adapters
Use the printed absolute path as <GUARD_PLUGIN_ROOT> in preview, authorize and execute
(other Bash is blocked while the confirmation is pending, so do not resolve it again).
If the resolver exits non-zero, stop without any external mutation and tell the user to install
the skill-governance-adapters plugin.
python3 "<GUARD_PLUGIN_ROOT>/scripts/build-external-mutation-guard.py" preview --project-root "$PWD" --entrypoint-ref "plugin:<PLUGIN_NAME>/skills/<SKILL_NAME>/SKILL.md" --target-scope "<TARGET_SCOPE>" --diff-summary "<DIFF_SUMMARY>" --side-effect-summary "<SIDE_EFFECT_SUMMARY>" --command-json '<MUTATION_ARGV_JSON>'
Present that official preview output to the user. Only the exact user reply printed by preview
may trigger the registered hook-confirm producer. Then use the two returned receipt paths:
python3 "<GUARD_PLUGIN_ROOT>/scripts/build-external-mutation-guard.py" authorize --project-root "$PWD" --preview-receipt "<PREVIEW_RECEIPT_PATH>" --confirmation-receipt "<CONFIRMATION_RECEIPT_PATH>"
python3 "<GUARD_PLUGIN_ROOT>/scripts/build-external-mutation-guard.py" execute --project-root "$PWD" --authorization-receipt "<AUTHORIZATION_RECEIPT_PATH>" --command-json '<MUTATION_ARGV_JSON>'
Do not use an auto-approval flag or invoke the mutation command outside this receipt flow.
<!-- /external-mutation-guard-cli:v1 -->
run-intake-revise
Runtime root contract
runtime_root_policy: host-skill-path を適用する。- Claude Codeでは
CLAUDE_PLUGIN_ROOT をplugin rootとして使用する。
- Codexではホストが提示したこの
SKILL.md のabsolute pathから、plugin manifestを持つ祖先を上方探索して論理 PLUGIN_ROOT を解決する。
cwd からplugin rootを推測せず、literal placeholderをshellへ渡さない。各shell invocation内で解決済みabsolute pathを PLUGIN_ROOT に設定する。prompts/ 配下はこのowner Skill契約を継承する。
Purpose & Output Contract
既に公開済みの intake (output/<hint>/intake.md + Notion ページ) に対し、ユーザーから追加要望・改善点を Claude Code チャット内で対話聞き取りし、合意確定後に 同一 Notion ページを PATCH 更新 する。新規ページは作成しない。
入力: output/<hint>/intake.json / intake.md / notion-url.txt / internal-analysis.json、ユーザー追加要望 (AskUserQuestion で収集)
出力:
- 更新済み Notion ページ (同一 page ID、PATCH children)
output/<hint>/revision-log.jsonl への 1 行追記 (schemas/output.schema.json 準拠)output/<hint>/question-bank-update.json と update_question_bank.py の dry-run/apply 結果- 失敗時:
output/<hint>/notion-rollback-<rev>.json
完了条件: Gate R で apply 承認 → Notion PATCH 成功 → revision-log 追記 → question-bank dry-run の提示。別承認が approve なら apply exit 0、decline なら question-bank-update.json に status: skipped / skip_reason: question_bank_update_declined を記録して停止する。どちらも改訂本体は success (exit 0)。または Gate R cancel/上限/失敗で適切な exit code を返却。
Key Rules
- 回数上限: 同一 hint に対する revision は最大 5 回。超過したら exit 60 で新規
/intake を案内。
- All-or-Nothing: PNG / mermaid が 1 つでも欠けたら旧版を維持 (Notion 公開と同原則)。
- PATCH 更新固定: delete-then-insert ではなく block 単位 update。失敗時は rollback JSON を保存。
- 内部解析非開示:
internal-analysis.json をユーザーに直接見せない。要約済み「あなたの追加要望をこう理解しました」テキストのみ Gate R 直前に提示。
- 日本語成果物: 本文・revision-log の
user_request / applied_changes は日本語、schema key / CLI 引数 / page-id は英語。
- question-bank は別承認: 新規質問候補を
question-bank-update.json の questions[] に明示し、update_question_bank.py をまず dry-run する。承認時だけ --apply。拒否時は同 JSON に status: skipped / skip_reason: question_bank_update_declined を追記して P8 を success で停止し、PATCH/revision-log を巻き戻さない。
ゴールシーク実行
Goal
既存 intake への追加要望を、最大 5 回の制約下で対話的に確定し、Gate R 承認を得た上で 同一 Notion ページに PATCH 反映 し、revision-log.jsonl に 1 行追記された状態。失敗時は旧版維持 + rollback JSON 保存 + 明確な exit code 返却。
Why
Notion ページの新規作成は URL 変更とリンク断絶を招くため、PATCH 固定が不可避。LLM 推論を含むヒアリング結果と決定論的 render を分離しないと、検証 (PNG / mermaid 存在) を通らない部分更新がページを汚染する。固定手順を辿るのではなく、チェックリスト未充足を起点に必要 step をその都度起動して反復することで、ユーザー意図の取り違えや中間生成物欠落にも頑健になる。
完了チェックリスト (停止条件)
未充足項目を特定 → 必要 script (analyze_user_intent.py / render-intake-final.py / intake_publish_pipeline.py / update_question_bank.py) を該当ステップから起動 → revision-log 更新 → 再度チェックリストで自己評価、を反復する。固定手順は持たない。
参考: 主要 script 起動例
# 内部解析再実行
python3 ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-plugins/skill-intake}}/scripts/analyze_user_intent.py output/<hint>
# 正本再生成
python3 ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-plugins/skill-intake}}/scripts/render-intake-final.py output/<hint>
# Notion PATCH mutation: construct <MUTATION_ARGV_JSON> with the resolved intake_publish_pipeline.py path and --intake/--manifest/--revise/--page-id argv; pass it only to the canonical receipt flow above.
# question-bank 追記候補の機械プレビュー（questions=[] でも実行）
python3 ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-plugins/skill-intake}}/scripts/update_question_bank.py --diff output/<hint>/question-bank-update.json --hint <hint>
# 上の dry-run 結果を提示し、question-bank 変更を別承認された場合だけ実行
python3 ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-plugins/skill-intake}}/scripts/update_question_bank.py --diff output/<hint>/question-bank-update.json --hint <hint> --apply
# 別承認を拒否した場合は --apply せず、question-bank-update.json へ
# {"status":"skipped","skip_reason":"question_bank_update_declined"} を追記して exit 0 で停止
# --dry-run 指定時は Notion API 呼び出しを行わず差分のみ表示
Step/Gate の機械可読定義は workflow-manifest.json (P1-load / P2-hear / P3-analyze / P4-preview / P5-gateR / P6-patch / P7-log / P8-self-update) を参照。
Gotchas
- page-id 不一致は致命:
notion-url.txt と Notion DB 上のページが一致しなければ exit 51 で新規 /intake を案内 (PATCH 続行禁止)。
- Keychain / API キーは再質問しない: PATCH 前に
python3 ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-plugins/skill-intake}}/scripts/validate-notion-ready.py --check-api を 1 度だけ実行する。exit 0 なら API キー / Notion トークンは確認済みとして扱い、ユーザーへ再入力を求めない。exit 44 (service=notion-api-key.<keychain-prefix>, account=<keychain-prefix> 未登録) のときだけ keychain-setup.md を案内し停止する。
- 回数上限超過: 5 回を超えたら exit 60 (新規 hint へ移行)。リセットしない。
- cancel は完全巻き戻し: Gate R cancel で exit 2、既存ページ不変、ローカル中間生成物も巻き戻す。
- rollback JSON: PATCH 失敗時は
output/<hint>/notion-rollback-<rev>.json を必ず保存。次回実行で参照する。
- question-bank の暗黙更新禁止: Gate R は Notion PATCH の承認であり、question-bank 更新の承認を兼ねない。dry-run と別承認なしの
--apply は実行しない。別承認を拒否しても改訂本体を失敗/巻き戻しにしない。
Additional Resources
workflow-manifest.json — Phase (P1-P8) / Gate (C1-C8) / resource の機械可読定義schemas/output.schema.json — revision-log.jsonl の 1 行スキーマprompts/R1-main.md — R1 責務プロンプト (7 層 Markdown、ヒアリング+PATCH 制御)references/resource-map.yaml — リソース一覧 (machine-readable)../../scripts/update_question_bank.py — question-bank 追記候補の dry-run / 明示承認後 apply
エラー処理 (exit code)
revision-log 追記失敗と question-bank dry-run/apply 失敗はどちらも exit 61 とし、P7/P8 から再開する。
| exit | 意味 | 対処 |
|---|
| 0 | 正常反映 | revision-log に追記済み。question-bank 別承認拒否も skip_reason 記録後は正常停止 |
| 2 | Gate R で cancel | 既存ページ不変、ローカル変更も巻き戻し |
| 44 | Keychain Notion トークン取得失敗 | keychain-setup.md 参照 |
| 51 | Notion ページ ID 不一致 | 新規 hint で /intake を案内 |
| 60 | revision 回数上限超過 (>5) | 新規 hint へ移行 |
| 61 | revision-log 追記または update_question_bank.py dry-run/apply 失敗 | revision-log.jsonl と question-bank-update.json を確認し、修復後に P7/P8 から再実行 |