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

1. 回数上限: 同一 hint に対する revision は最大 5 回。超過したら exit 60 で新規 /intake を案内。
2. All-or-Nothing: PNG / mermaid が 1 つでも欠けたら旧版を維持 (Notion 公開と同原則)。
3. PATCH 更新固定: delete-then-insert ではなく block 単位 update。失敗時は rollback JSON を保存。
4. 内部解析非開示: internal-analysis.json をユーザーに直接見せない。要約済み「あなたの追加要望をこう理解しました」テキストのみ Gate R 直前に提示。
5. 日本語成果物: 本文・revision-log の user_request / applied_changes は日本語、schema key / CLI 引数 / page-id は英語。
6. 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 をその都度起動して反復することで、ユーザー意図の取り違えや中間生成物欠落にも頑健になる。

完了チェックリスト (停止条件)

• validate-notion-ready.py --check-api が exit 0 (config / Keychain トークン / hearing-sheet DB 疎通)。PASS 済みなら API キーを再質問しない。exit 44 のみ keychain-setup.md 案内で停止
• 既存 4 ファイル (intake.json / intake.md / notion-url.txt / internal-analysis.json) をロードし、Notion ページ ID を抽出した
• revision 回数を確認し、上限 (5) を超えていない
• AskUserQuestion で対象章 (§1〜§11) / 変更内容 / 変更理由を収集した
• analyze_user_intent.py を再実行し新しい internal-analysis.json を生成した
• 変更前後 diff を Claude Code チャットに提示し、要約済み理解テキストを Gate R 直前に表示した
• Gate R で apply / re-revise / cancel の判定を取得した
• apply の場合 render-intake-final.py で正本再生成 → intake_publish_pipeline.py --revise --page-id <既存 ID> で PATCH 更新した
• PNG / mermaid の全揃いを確認し、欠落時は旧版維持 + rollback JSON を保存した
• output/<hint>/revision-log.jsonl に {revision_no, timestamp, target_section, user_request, applied_changes, notion_page_url} を 1 行追記した
• 「足りなかった質問」を output/<hint>/question-bank-update.json の questions[] に記録し、update_question_bank.py dry-run 結果を提示した
• question-bank 別承認が approve なら update_question_bank.py --apply exit 0 と追記数を確認。decline なら question-bank-update.json に status: skipped / skip_reason: question_bank_update_declined を記録し、P8 success で停止した
• 内部解析 (internal-analysis.json) をユーザーに直接見せていない

未充足項目を特定 → 必要 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

1. page-id 不一致は致命: notion-url.txt と Notion DB 上のページが一致しなければ exit 51 で新規 /intake を案内 (PATCH 続行禁止)。
2. 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 を案内し停止する。
3. 回数上限超過: 5 回を超えたら exit 60 (新規 hint へ移行)。リセットしない。
4. cancel は完全巻き戻し: Gate R cancel で exit 2、既存ページ不変、ローカル中間生成物も巻き戻す。
5. rollback JSON: PATCH 失敗時は output/<hint>/notion-rollback-<rev>.json を必ず保存。次回実行で参照する。
6. 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 から再実行