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を必要とする。

System development planning

Purpose & Output Contract

dev-graph の1 feature を、確定 system-spec を起点に P01..P13 各1件の exact 13 executable task specs へ分解し、13-entry inventory と 13-node の intra-feature DAG を持つ package にまとめる。

• 入力: --feature-id <graph-node-id> と --feature-context <repo-relative-json> (必須)、任意の --repo-root と --config。init は caller repository の layout だけを用意する。
• 出力 (pre-choice): staging の exact-13 package (feature-package.json・task-specs/phase-01..13.md・workstream-inventory.json・task-graph.json・system-build-handoff.json・staging-manifest.json)。C12 deterministic validation を通した path・digest・開き方を示す。
• 出力 (light/standard/detailed 選択後): 同じ canonical digest を再検証した atomic promotion の receipt・registration manifest・current pointer と、best-effort の plan-structure-report.html・task-specs.html。
• 禁則: 1 run で2つ以上の feature を扱わない。14件目の task と別の13 phase 文書を作らない。staging lock の JSON を C13 以外から作成・書換・削除しない。途中で失敗しても published/current の旧世代を壊さない。

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契約を継承する。

Invariants

• caller repository の解決と全 path 検査は ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/resolve-project-context.py に一元化する。${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}} は code/assets の位置決めだけに使い、caller の文書・状態の authority にはしない。
• 1 run は1 parent_feature のみを扱い、P01..P13 各1件の exact 13 executable tasks を生成する。別の13 phase 文書と14件目は生成しない。
• C08 readiness、C14 handoff producer、C12 deterministic validationが一致したactual exact-13 packageをusable draftとして書き出し、path/digest/開き方を先に提示する。fork evaluator C1..C4はlight/standard/detailed選択後だけ起動し、初回提示を待たせない。post-choiceのfinal promotion/publishは同じcanonical digestを再検証してから行う。
• staging lock は C13 ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/manage-system-plan-lock.py だけが生成・更新・解放する。repository_id/run_id/session_owner/feature_id/feature_digest/acquired_at/heartbeat_at/expires_at を束縛し、開始時に acquire、各動的計画反復に renew、成否にかかわらず終了処理で release を実行する。他 component は lock JSON を直接作成・書換・削除しない。
• ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/hooks/guard-implementation-readiness.py は run 識別 env に依存せず repository-local canonical lock を自己発見し、malformed same-repository lock を fail-closed 拒否し、expires_at 超過 lock は C13 と同じ audit receipt 規則で cleanup する。

init

python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/init-project-layout.py" --repo-root "$CLAUDE_PROJECT_DIR"

missing config keys/directories だけを作成し、既存値・docs/specs/tasks/issues を上書きしない。receipt と repository_id 導出元を保存する。

plan

--feature-id と --feature-context は必須。feature context は caller repository 相対 JSON で、graph_node_id, artifact_kind=feature, purpose, goal, scope_in, scope_out, acceptance, architecture_refs, updated_at を持つ。C09 が realpath containment を検証し、JSON の graph_node_id と --feature-id が一致しなければ staging 作成前に停止する。absolute path、..、root 外 symlink、別 repository の context は拒否する。

pre-choiceではmain contextがexact-13 packageの最小usable draftを1回生成し、C12 deterministic validationを通してpath/digestを提示する。以下の動的計画・fork evaluator・反復・promotionは利用者がlight/standard/detailedを選んだ後だけ開始する。

• C09 repo context と feature identity/context digest が確定している。
• C08 が system-spec index/requirements/architecture graph を complete と判定している。
• C13 が repository_id/run_id/session_owner/expires_at と feature id/digest を束縛した staging lock を atomic acquire し、各反復で heartbeat renew している。
• elicitor の goal-spec と architect の exact-13 package が同じ feature digestを参照する。
• C14 が exact-13 source の個別 SHA-256 と registration request/receipt owner 境界を持つ system-build-handoff.json を生成し、その bytes が staging-manifest.json の canonical digest に含まれている。handoff は receipt を自己発行しない。
• pre-choiceのC12 deterministic validationが提示対象digestをPASSしている。post-choiceではfork evaluator C1..C4がその同一digestを診断し、改善後はC12を再実行する。
• C11 が same-filesystem atomic promotion、immutable receipt、registration manifest、current pointerを生成している。
• C11 が promotion receipt/registration request を所有し、dev-graph の all-or-none apply が発行する registration receipt と境界が一意である。C13 lock が解放され、published path/digest/receipt が dev-graphへ返されている。
• 計画構造レポート (plan-structure) が生成されている: promotion 済み task-graph.json から「この feature で何をやるか + exact-13 タスク・ノード・依存の関係性」を 1 枚の自己完結 HTML (plan-structure-report.html) へ投影する。目的/本質的課題/できることの価値セクション (goal-spec / value-narrative.json 由来・非エンジニア/技術者の dual audience) と依存関係表を携帯し、build 前に計画の全体像を確認できるようにする。plugin-dev-planner と共通の完了ステップとして、両プランナーとも同一の共有 reporter を best-effort で呼ぶ (harness-creator 未配備環境では skip・非ゲート): 共有 reporter は別 plugin (harness-creator) にあるので、${PLUGIN_ROOT}/.. から推測せず、先に1回 python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/extract-plugin-root.py" harness-creator で root を解決し、表示された absolute path を <HARNESS_CREATOR_ROOT> に使う。非0 で終わったら未配備としてこのステップと次の仕様書ブラウザを skip する。 python3 "<HARNESS_CREATOR_ROOT>/scripts/project-task-status.py" --task-graph <PLAN_DIR>/task-graph.json --goal-spec <PLAN_DIR>/goal-spec.json --out-html <PLAN_DIR>/plan-structure-report.html --out-md <PLAN_DIR>/plan-structure.md --out-json <PLAN_DIR>/plan-structure-status.json --goal-spec を渡さないと reporter の価値セクション (目的/本質的課題/できること) は fail-soft で沈黙欠落する。非エンジニア向け平易層 (plain_intro 等) を出すには curated value-narrative.json を PLAN_DIR に用意する (未用意なら平易層のみ省略)。
• 仕様書ブラウザ (task-specs.html) が生成されている: 13 フェーズ仕様書 (phase-01..13) と task-specs/*.md の本文を、サイドバー index → 各仕様書へページ遷移 → ブラウザ back で戻れる自己完結 HTML にする (中身閲覧ビュー)。構造/依存/価値の plan-structure-report.html と対になり、相互リンクで往復できる。plugin-dev-planner と共通の完了ステップ (best-effort・非ゲート): python3 "<HARNESS_CREATOR_ROOT>/scripts/render-spec-browser.py" --plan-dir <PLAN_DIR>

Failure handling

light/standard/detailed選択後だけ component-inventory.json の goal_seek.max_loops=5 を有効化する。5周で未達なら自動続行せず findings と staging path を報告する。accept-as-isではこの周回を0回のまま終了する。途中失敗時も published/current は旧世代を維持する。発見した独立作業は package に追加せず follow-up feature candidate として返す。

Gotchas

• ${PLUGIN_ROOT} は caller の authority ではない: plugin root は script と asset の位置決めにだけ使う。caller repository の文書・状態の解決と path 検査は resolve-project-context.py に任せる。
• feature context の id 不一致は staging の前に止まる: JSON の graph_node_id と --feature-id が違うと、C09 は staging を作らずに停止する。absolute path、..、root 外 symlink、別 repository の context も拒否される。
• lock は C13 だけが触る: 開始時の acquire、各反復の renew、成否にかかわらない終了時の release を manage-system-plan-lock.py で行う。lock JSON を手で書き換えて形が崩れると、guard hook が malformed lock として fail-closed で拒否する。
• 兄弟 plugin を ${PLUGIN_ROOT}/.. で探さない: install 先では .. の先が同じ plugin の別 version 群になる。harness-creator の reporter は extract-plugin-root.py で解決する。
• reporter に --goal-spec を渡し忘れない: 渡さないと plan-structure-report.html の価値セクションが警告なしに欠ける。
• accept-as-is は周回を回さない: goal_seek.max_loops=5 が有効になるのは light/standard/detailed を選んだ後だけで、5周で未達なら自動続行せず findings と staging path を返す。