diff --git a/ari-core/MASTER_PLAN_handoff_impl.md b/ari-core/MASTER_PLAN_handoff_impl.md new file mode 100644 index 00000000..34e126f0 --- /dev/null +++ b/ari-core/MASTER_PLAN_handoff_impl.md @@ -0,0 +1,51 @@ +# MASTER PLAN — Artifact/History Handoff 統制研究の実装マスター + +Status: 実装マスター計画(未実装)。Origin: 2026-06 設計議論+コードベース監査+関連研究調査。 +研究計画(why/what): [`PLAN_artifact_summary_handoff.md`](PLAN_artifact_summary_handoff.md)。本書は how/order(依存 DAG・クリティカルパス・削除要件・subtask 索引)。 + +## 削除要件 +配下の全 subtask Plan.md が削除要件を満たして削除され(全 subtask が main に land+実機検証)、結果が論文ドラフトまたは後継 PLAN に転記された時点で本マスターと研究計画を削除する。 + +## 原則 +1. 測定は evaluator が独占所有(agent は固定シグネチャ kernel のみ提供)。 +2. 評価契約は実験者が固定し全アーム・全モデルで同一(B3)。 +3. 各 handoff チャネルは per-arm で明示 gate。 +4. 機械情報(host/partition/port/path)は tracked artifact・commit に一切入れない(最優先規約)。 + +## Subtask 索引と依存 DAG +| subtask | Plan.md | 主担当 | 上流依存 | +|---|---|---|---| +| B2 deterministic evaluator+測定器 | [`ari/evaluator/Plan.md`](ari/evaluator/Plan.md) | evaluator | (根) | +| G1 HandoffConfig | [`ari/config/Plan.md`](ari/config/Plan.md) | config | (根) | +| ローカル決定性(seed/digest) | [`ari/llm/Plan.md`](ari/llm/Plan.md) | llm | (根) | +| B1 memory gate / B3 契約凍結 / G4 注入 | [`ari/agent/Plan.md`](ari/agent/Plan.md) | agent | config, evaluator, orchestrator | +| G3 node_summary_view / G9a selector | [`ari/orchestrator/Plan.md`](ari/orchestrator/Plan.md) | orchestrator | config, evaluator | +| G5 copy / G7 sterile / G12 timeout・overflow | [`ari/cli/Plan.md`](ari/cli/Plan.md) | cli | config | +| root 横断: core.py dispatch / cost_tracker provenance | [`ari/Plan.md`](ari/Plan.md) | ari(root) | evaluator, agent, llm | +| memory backend: RQ-C surface/topology / retrieved-text log | [`../ari-skill-memory/Plan.md`](../ari-skill-memory/Plan.md) | ari-skill-memory | agent, orchestrator(Phase C 主体) | +| ハーネス / run・analyze / scrub / cost | [`../scripts/Plan.md`](../scripts/Plan.md) | scripts | 上記すべて | + +依存の要点: **B2 → B3 → B1 が背骨**。B2 で採点固定 → B3 で契約外生化(しないと B2 が `agent/loop.py:1190` で上書きされる)→ B1 で memory 第3経路を gate(しないと全アームが state 共有)。 + +## クリティカルパス(ビルド順) +- **Stage 0(コード前)**: タスク確定(SpMV/SpMM、既存 fixture は全 SpMM)/事前登録 doc 凍結(ε・C/`_scientific_score` 正規化/invalid floor/N/failure codebook/単一 primary 対比/H-B・H-C・H-D の向き/model 水準)/seed kernel 固定/pilot 予約(qwen3:8b validity floor・最大サイズ infra 適合)。 +- **Stage 1**: B2+測定器(evaluator)/B3 契約凍結(agent)/G1 HandoffConfig(config)/ローカル決定性(llm)。 +- **Stage 2**: B1 memory gate/G4 注入(agent)/G3 node_summary_view(orchestrator)/G5・G7・G12(cli)/side-channel 凍結。 +- **Stage 3**: G9a deterministic selector(orchestrator)。 +- **Stage 4**: tracked ハーネス/run・analyze スクリプト/instrumentation/収集時スクラブ/cost ゲート(scripts)。 +- **Stage 5**: 推論(run 単位 cluster bootstrap・TOST・多重性・log 効果量・RQ-D 交差検定)・図表。 + +## MVP カット(Phase A/workshop 級) +Stage 0 全部 + Stage 1 全部 + Stage 2 の B1・G3・G4・G5・G7 + Stage 3 G9a + Stage 4 の tracked ハーネス・run/analyze・scrub・instrumentation 最小。 +これで **3 アーム(code_only / code_plus_summary / code_plus_full_log)×1 タスク×ローカル large×deterministic selector** を、契約固定・memory off・選択決定・valid 定義ありで回せる。落としてよい: linear search、memory topology ノブ、capability 勾配(RQ-D)、aide_journal、dosage、overflow 精緻化。 + +## 完了ログ(land 時に追記) +- [ ] B2 / 測定器 — land __ / 実機 gate __ +- [ ] G1 HandoffConfig — land __ / gate __ +- [ ] ローカル決定性 — land __ / gate __ +- [ ] B1 / B3 / G4 — land __ / 実機 gate __ +- [ ] G3 / G9a — land __ / 実機 gate __ +- [ ] G5 / G7 / G12 — land __ / 実機 gate __ +- [ ] root 横断 (core.py dispatch / cost_tracker provenance) — land __ / 実機 gate __ +- [ ] memory backend (RQ-C surface/topology・Phase C) — land __ / 実機 gate __ +- [ ] ハーネス / scripts / scrub — land __ / 実機 gate __ diff --git a/ari-core/PLAN_artifact_summary_handoff.md b/ari-core/PLAN_artifact_summary_handoff.md new file mode 100644 index 00000000..97b756c8 --- /dev/null +++ b/ari-core/PLAN_artifact_summary_handoff.md @@ -0,0 +1,96 @@ +# PLAN: What Should Branching LLM Code Agents Inherit? — Artifact / History Handoff の統制研究 + +Status: 研究計画(design 段階・未実装)。Origin: 2026-06 設計議論+コードベース監査+関連研究調査。 +削除条件: Phase A〜C(MVP pilot まで)完了し、結果が論文ドラフトまたは後継 PLAN に転記された時点で本ファイルを削除する。 +実装マスター: [`MASTER_PLAN_handoff_impl.md`](MASTER_PLAN_handoff_impl.md)(how/order と subtask Plan.md 索引)。 +英語題目: **What Should Branching LLM Code Agents Inherit? A Controlled Study of Artifact and History Handoff** + +--- + +## 0. 実装現状(監査済, paths=`ari-core/ari/`) + +以降は本検証を前提に読む。**0.2 は論文の前に必ず塞ぐ穴**で、塞がない限り統制比較は成立しない。各項目の実装計画は [`MASTER_PLAN_handoff_impl.md`](MASTER_PLAN_handoff_impl.md) と各 dir の `Plan.md` を参照。 + +### 0.1 流用可能な土台(検証済) +| 前提 | 実装 | +|---|---| +| per-node work_dir = `experiments/{run_id}/{node_id}/` | `paths.py:175-181`, `cli/bfts_loop.py:373-381` | +| 親→子 code 継承+結果除外(2段) | `_OUTPUT_BLACKLIST`+`is_meta_file()`, `cli/bfts_loop.py:398-445` | +| node_report.json(31 prop) | `orchestrator/node_report/builder.py:551-586` | +| cost_trace.jsonl(per-call node_id+prompt_tokens) | `cost_tracker.py` | +| 評価信号 `node.metrics["_scientific_score"]` | `orchestrator/bfts.py:336` 他、生成 `evaluator/llm_evaluator.py:662,713` | +| ancestor-scoped memory(Tier-1b/2) | `agent/loop.py:295-353`, scope 強制 `in_memory.py:101-106` | +| ローカル backend 既定(ollama, qwen3:8b/32b) | `config/__init__.py:581-582` | + +### 0.2 先に塞ぐ食い違い(=統制比較の前提条件) +1. **B1 第3 handoff 経路**: Tier-1a(`loop.py:193-216`)+Tier-1c(metric-contract obligation+`build_coverage_status`, `loop.py:218-290`)が ancestor ガード(`loop.py:292`)より前で無条件発火、`_PINNED_USER_MARKERS`(`loop.py:766-775`)で window を生存。塞がないと全アームが operational state を共有。→ [`ari/agent/Plan.md`](ari/agent/Plan.md)。 +2. **B2 evaluator が選択を回せない**: `node.metrics = eval_result["metrics"]`(`loop.py:1461`)で `metrics._scientific_score` 不在なら全ノード 0.0。evaluator は `core.py:195` ハードコード、loop は Protocol 外 `evaluate_sync`。→ [`ari/evaluator/Plan.md`](ari/evaluator/Plan.md)。 +3. **B3 契約が LLM 自己決定・run/model 依存**: `make_metric_spec`(core/pinned ツール, `workflow.py:172`/`loop.py:719`)が evaluator の metric_spec を実行時に上書き(`loop.py:1162-1196`)し、per-run 契約を `metric_contract.json` に書き Tier-1c で全子孫に注入。契約が条件ごとに変わると capability×handoff が capability×自己生成契約品質と交絡。→ 固定契約の外生化が必須。[`ari/agent/Plan.md`](ari/agent/Plan.md)。 +4. **sterile-gate の意味反転**: `compute_files_changed(parent,child)` 無条件 clamp(`cli/bfts_loop.py:631-656`)。copy-OFF では子 dir 空→全 deleted→sterile にならない。→ [`ari/cli/Plan.md`](ari/cli/Plan.md)。 +5. **timeout dead code**(`cli/bfts_loop.py:532-541`)/**full_log overflow 検出なし**で窓圧縮が黙って truncated 化(`loop.py:725,803-804`)。→ [`ari/cli/Plan.md`](ari/cli/Plan.md)。 +6. **バックエンド非決定性**: seed 不渡し(`client.py:180`)、gpt-5* は temp drop(`client.py:130`)。ローカルは seed plumb で再現性が立つ。→ [`ari/llm/Plan.md`](ari/llm/Plan.md)。 +7. 既存 fixture は全 SpMM(Y=AX)。タスクは Stage 0 で確定。 +8. harness が gitignore 全体無視(`.gitignore:31-37`)→ force-negate 必須。→ [`../scripts/Plan.md`](../scripts/Plan.md)。 +9. `search_trace.jsonl` 不在/`memory_access.jsonl` は取得テキスト非記録。 + +### 0.3 de-facto handoff(出発点) +ARI 既定は code(workdir copy)+ planner 側 summary(`bfts.py:64-108`)+ memory 側(Tier-1a/1b/1c/2)の混合。本研究はこれを制御可能な handoff policy に分解・統制比較する。 + +--- + +## 1. 中心的問い +分岐型 LLM コード生成で**子ノードが親から何を継承すべきか**。「code/summary/両方」の3択は自明(both 最良)かつ単一 trajectory で実質既出のため貢献ではない。貢献は1段深い粒度——summary の**どのフィールド**を**どの形式**で継承すれば必要十分か、その結論が**分岐継承で・モデル能力を超えて転移するか**——に置く。最も強い結末は「**最適な継承法は条件(capability/task/depth)で食い違う**」という contingency の発見であり、本研究はそれを confirmatory に検出する設計にする。 + +## 2. 新規性の位置づけ(RQ-A は scaffold、RQ-B/C/D が貢献) +| 先行研究 | 何をしたか | 本研究が埋める白地 | +|---|---|---| +| AIDE(2502.13138)/AI-Scientist-v2(2504.08066) | 分岐探索+親→子に code+単一サマリ Σ(T) | summary を固定し中身を割らない、retrieval/非親 reach 無し | +| Lindenbauer "Complexity Trap"(2508.21433) | raw/masking/summary 統制比較・masking≈summary(**単一 trajectory**) | 分岐/cross-node・モデル能力への転移は未検証 | +| MEMOIR(2605.17539, 並行) | tree-search の階層 memory ablation | 別ドメイン(組合せ最適化)・tier 有無を ablate(field 別でない)・surface 非対象 | +| AWM(2409.07429)/MemGPT/Context-Eng survey(2507.13334) | agent-memory の枠を所有 | content 固定で surface/topology/capability を振る統制は無し | + +差別化(1文): 先行研究は handoff サマリを固定し単一 run・単一モデルで文脈圧縮を比較したに留まる。本研究は **artifact と history チャネルを分離**し、**history の content を field 別に ablate** し、**masking≈summary が分岐継承で・モデル能力を超えて転移するか**を、LLM-judge を排した決定論評価で測る初の統制研究。⚠「分岐型 agent memory を統制した初」は MEMOIR が先取り済みのため主張しない。 + +## 3. handoff の分解 +- **artifact チャネル**(唯一直交): 親 code を work_dir で継承するか否か。 +- **history チャネル**: **FORM**(none→masked→truncated→extractive-summary→rolling、上限 full-trace)× **CONTENT**(field 別: delta_vs_parent/changed_files/concerns/next_steps/**known_failures**(導出)/key_metrics)× **SURFACE**(in-prompt push / memory-retrieval pull)。 +- **memory の扱い(確定)**: 第5チャネルにも headline にもしない。(i) RQ-A/B では off に統制すべき confound(B1)。(ii) RQ-C 配下に従属ノブ=inheritance TOPOLOGY(parent-only vs full-ancestor、content 固定。`loop.py:301`+`in_memory.py:103`、ARI 固有・未所有)。 + +## 4. 比較アーム +code_only / summary_only / code+summary / code+masked / code+full_trace / code+truncated / code+rolling / **aide_journal**(Σ 相当 baseline) / **+CONTENT ablation**(summary −1 field ずつ=RQ-B)/ **+TOPOLOGY ノブ**(RQ-C 従属)。上記を **model_size∈{small,large(同一ファミリ; 勾配なら 8/14/32 等)}** で交差(RQ-D)。 + +## 5. Research Questions +- **RQ-A(scaffold・貢献ではない)**: artifact と history のどちらが必要か。clean 比較の土台。 +- **RQ-B(primary・本命)**: history summary の**どの field** が効くか。**H-B: failure/concern 系が支配的で next_steps は寄与しない。** +- **RQ-C(differentiator)**: masking≈summary は分岐継承で転移するか。**H-C: 単一 trajectory では masking で足りるが、分岐では失敗情報が直近窓外に落ち extractive-failure-summary が masking 単独より有意に優る。** +- **RQ-D(capability × handoff・新規)**: handoff の価値はモデル能力に依存するか。**H-D(FORM×capability 交差): large は masking で足り small は failure-summary が必須**(RQ-C と接続)。勾配≥3点で「形(閾値/順位反転)」を検出。 +- sanity(格下げ・非 headline): S1 code+summary は code+full_trace と parity(TOST)。S2 注入トークン分離計測の上で削減確認。 + +## 6. タスク・測定器・モデル +- **6.1 タスク**: SpMV(y=Ax) か SpMM(Y=AX) を Stage 0 で確定(既存 fixture は全 SpMM)。 +- **6.2 deterministic evaluator が測定器を独占所有**: oracle(fp64 参照解)+ε(行ごと `C·γ_{nnz}·Σ|A||x|`)+timing(warmup/reps median+分散, pin, freq, OMP, NUMA)+checksum 固定 baseline+anti-gaming(matrix/timing/baseline/correctness 独占, correctness 用 x は call 時供給)+geomean 集計+hardware fingerprint。→ [`ari/evaluator/Plan.md`](ari/evaluator/Plan.md)。 +- **6.3 モデル**: 主バックボーン=ローカル qwen3(small/large、seed・temp 固定・digest pin)で確認的 run を高 n・無コスト・再現可能に。frontier API は robustness 1本。Stage 0 で qwen3:8b の validity floor を pilot。→ [`ari/llm/Plan.md`](ari/llm/Plan.md)。 + +## 7. 実験計画と統計 +事前登録(Stage 0 で凍結): ε・C/`_scientific_score` 正規化/invalid floor/N/failure codebook/単一 primary 対比/H-B・H-C・H-D の向き/model 水準。単位=run(1木=1スカラ)。run 単位 cluster bootstrap、speedup は log 領域、parity は TOST+事前マージン、多重性 Holm/BH。selector は deterministic 固定(G9a)。注入トークンを per-node prompt_tokens と分離計測。RQ-D は**交互作用基準の検出力**で順位反転を検定。summary 忠実性(導出 known_failures vs evaluator failure_signature)で「表現の差」と「生成品質の差」を分離。 + +## 8. 実装計画 +クリティカルパス(Stage 0-5)・依存 DAG・subtask 索引・MVP カットは [`MASTER_PLAN_handoff_impl.md`](MASTER_PLAN_handoff_impl.md) に集約。背骨は **B2 → B3 → B1**。各 subtask は該当 dir の `Plan.md` 参照。 + +## 9. スコープとフェーズ +- Phase A(MVP/workshop): 3 アーム×1 タスク×ローカル large×deterministic selector、事前登録、run 単位 n≥~8–10、cluster bootstrap、scrub+gitignore negation。 +- Phase B: RQ-B(field 別)+ masked/aide_journal(RQ-C)+ dosage sweep。 +- Phase C: RQ-D(small/large 勾配)+ topology ノブ+ frontier robustness+追加タスク(SE タスク or MLSys 判断)。 +- 各 Phase 入口で cost go/no-go(ローカル主体で大幅緩和)。 + +## 10. Threats to Validity +internal: B1 第3経路/sterile 非対称/dead timeout/selector 確率性/full_log overflow 自壊/side-channel/GPU 残留非決定性。construct: 主指標は handoff 質か selection 運か(selection-invariant 指標併報)/summary 忠実性交絡/starting kernel 交絡(全アーム同一・事前登録)/capability 操作が規模のみか(同一ファミリで担保)。external: 単一カーネル・単一言語(C/OpenMP)・主にローカル qwen3(→ frontier アームで補強)。 + +## 11. 再現性・アーティファクト・データ管理 +固定 commit/per-call の model digest/temp/seed 記録/frozen-trace から図表再生成/harness tracked(force-negate)/SuiteSparse は name+group+SHA256+snapshot 日付 pin/生成 native code の sandbox/timeout/**収集時の機械情報スクラブ**(tracked artifact・図・commit に機械情報を一切入れない)/GB 級 trace の保管。→ [`../scripts/Plan.md`](../scripts/Plan.md)。 + +## 12. リスクと対策 +最大リスク(cost×検出力)→ ローカル主バックボーンで緩和。新リスク=small の capability floor → Stage 0 pilot。新規性が弱い/3択縮退 → §2 差別化+RQ-B/C/D を主役+contingency(条件で食い違う)を背骨に+aide_journal baseline。null → H-B/H-C/H-D を向き付き事前登録で informative に。venue → SE タスク追加 or MLSys 明確化。 + +## 13. 投稿戦略 +初期: DL4C / MLSys・ASE workshop(Phase A)。本会議: MLSys(context 効率+capability 軸)または ASE/ICSE(要 SE タスク追加)。冒頭で AIDE・AI-Scientist-v2・Lindenbauer・MEMOIR(並行) を引き、「summary を発明したのでなく、何を・どの形式で継承すべきかを field 粒度で初めて統制分離し、分岐継承とモデル能力をまたぐ転移(および条件依存性)を検証した」と位置づける。 diff --git a/ari-core/PREREG_handoff_study.md b/ari-core/PREREG_handoff_study.md new file mode 100644 index 00000000..fb3808e0 --- /dev/null +++ b/ari-core/PREREG_handoff_study.md @@ -0,0 +1,29 @@ +# PREREG — Stage 0 凍結(What Should Branching LLM Code Agents Inherit?) + +Status: 事前登録(凍結値。実験開始後は変更しない)。Origin: 2026-06、ユーザ委任により推奨デフォルトを採択。 +親: [`MASTER_PLAN_handoff_impl.md`](MASTER_PLAN_handoff_impl.md)、研究計画 [`PLAN_artifact_summary_handoff.md`](PLAN_artifact_summary_handoff.md) §7。 +削除条件: 本研究の confirmatory run が完了し、凍結値と結果が論文ドラフトまたは後継 PLAN に転記された時点で削除。 + +## 採択した実行方針 +- **主タスク**: **SpMM(Y=AX, A=CSR)**。既存 fixture・評価運用実績があり MVP を最短で実物まで詰められるため。SpMV は Phase C。 +- **実装ブランチ**: **`bfts_compare`**(実装コード専用)。計画/PREREG は PR #31(`plan-artifact-summary-handoff`)に温存。 + +## 凍結値 +| # | 項目 | 凍結値 | +|---|---|---| +| 1 | valid 述語 | compile ∧ run ∧ correctness(ε) ∧ no-timeout ∧ 全必須行列完了 ∧ no protocol-violation。invalid=score 0 | +| 2 | ε 誤差モデル | 出力要素ごと `|y_cand−y_ref| ≤ C·γ_k·Σ|A||x|`、`γ_k=k·u/(1−k·u)`、`u`=fp64 unit roundoff、**C=8** | +| 3 | `_scientific_score` 正規化 | `s = min(geomean_speedup / TARGET, 1.0)`、**TARGET=4.0×** | +| 4 | invalid-family 規則 | 必須 family を1つでも落とせば node-invalid(geomean に 0 を混ぜない) | +| 5 | N(best valid @ N nodes) | **10** | +| 6 | failure codebook | COMPILE{syntax,linker,header} / CORRECTNESS{eps_exceeded,nan} / PROTOCOL{frozen_checksum} / TIMEOUT / NOOP_STERILE / PARENT_OUTPUT_MISUSE | +| 7 | primary 対比(単一) | **code_plus_summary vs code_plus_full_log**(SpMM・large モデル・deterministic selector) | +| 8 | 仮説の向き | H-B: failure/concern 系が支配・next_steps 寄与せず/H-C: 分岐で extractive-failure-summary > masking 単独/H-D(FORM×capability 交差): large=masking 十分・small=failure-summary 必須 | +| 9 | モデル水準 | 主=ローカル qwen3 dense **8B / 14B / 32B**(同一ファミリ)、large=32B が MVP。frontier API は robustness 1本 | +| 10 | 統計 | 単位=run(1木=1スカラ)、**n≥10/cell**、run クラスタ bootstrap、parity は TOST(**margin=log(1.05)**)、多重性 Holm | +| 11 | 固定定数 | seed kernel+最適化フラグ(全アーム同一・checksum)、timing **W=3 warmup / R=10 reps(median)**、`OMP_NUM_THREADS` 固定、turbo off、単一アーキ | + +## pilot ゲート(confirmatory 前に確認) +- (a) qwen3:8b が SpMM で validity を非ゼロで超えるか(床打ちなら small を 14B に上げる)。 +- (b) 最大サイズ(32B)が GPU 経路に載るか。 +- (c) deterministic selector が非ゼロ `_scientific_score` を消費するか(B2 land 後)。 diff --git a/ari-core/ari/Plan.md b/ari-core/ari/Plan.md new file mode 100644 index 00000000..80540866 --- /dev/null +++ b/ari-core/ari/Plan.md @@ -0,0 +1,22 @@ +# Plan — root ファイル横断: core.py evaluator dispatch / cost_tracker.py provenance + +Status: 実装計画(未実装)。Origin: 2026-06 handoff study 設計。 +親計画: [`../MASTER_PLAN_handoff_impl.md`](../MASTER_PLAN_handoff_impl.md)、研究計画 [`PLAN_artifact_summary_handoff.md`](PLAN_artifact_summary_handoff.md) §6.2 / §8 Stage 1 / §11。 +対象は `ari-core/ari/` **直下のファイル**(サブパッケージに属さない横断的改修)。 + +## 依存関係(他 Plan.md) +- 上流依存: + - [`evaluator/Plan.md`](evaluator/Plan.md)(B2)— dispatch が**選ぶ**対象(deterministic evaluator クラス)はそちらで定義。 + - [`agent/Plan.md`](agent/Plan.md)(B3)— make_metric_spec 自己決定の封じ込めは loop 側。本書は build 時 spec 構築(`core.py`)との整合のみ扱う。 + - [`llm/Plan.md`](llm/Plan.md)— provenance に載せる seed/digest/temperature の出所。 +- 下流: [`../../scripts/Plan.md`](../../scripts/Plan.md)(analyze が provenance を読む)。 + +## 削除要件 +core.py の evaluator dispatch と cost_tracker.py の provenance 拡張が main に land し、実機で「`ARI_EVALUATOR` で deterministic evaluator に切替わる」「per-call で seed/digest/temp が trace に残る」を確認、MASTER 完了ログに記録された時点で本 Plan.md を削除する。 + +## 実装項目 +1. **`core.py` evaluator dispatch**: `core.py:195` は現状 `LLMEvaluator(...)` ハードコード(`axis_mode` dispatch `core.py:155-182` は軸のみ)。`ARI_EVALUATOR`(or `cfg.evaluator.kind`)で [`evaluator/Plan.md`](evaluator/Plan.md) の deterministic evaluator に差し替え可能化。B3([`agent/Plan.md`](agent/Plan.md))で make_metric_spec の自己決定を封じた上で、build 時 spec(`core.py:62,151` `_make_metric_spec`)は固定/generic のまま evaluator が採点を所有する形に整合させる。 +2. **`cost_tracker.py` provenance 拡張**: per-call 記録(現状 model 名・token 数等)に **resolved model digest / seed / temperature** を追加(値の供給は [`llm/Plan.md`](llm/Plan.md))。capability 勾配(研究計画 RQ-D)と再現性(§11)はこの provenance で識別・検証する。 + +## 検証ゲート(実機) +`ARI_EVALUATOR` 切替で deterministic evaluator が使われること、`cost_trace` 各行に digest/seed/temperature が入ること、同一 (digest, seed) で再現性が立つことを確認。 diff --git a/ari-core/ari/README.md b/ari-core/ari/README.md index 0e52a78b..d2c90d0d 100644 --- a/ari-core/ari/README.md +++ b/ari-core/ari/README.md @@ -18,6 +18,7 @@ Core engine package for ARI. Each sub-package carries its own `README.md` - `memory_cli.py` — `ari memory` subcommand (migrate / backup / …). - `paths.py` — centralised `PathManager` for directory layout/resolution. - `pidfile.py` — `.ari_pid` write/read/cleanup for run-liveness detection. +- `Plan.md` — root ファイル横断(core.py evaluator dispatch / cost_tracker.py provenance)の実装計画(handoff study). - `agent/` — ReAct loop, environment capture, per-stage workflow guidance. - `README.md` — agent index. - `__init__.py` — package module-map docstring. @@ -25,6 +26,7 @@ Core engine package for ARI. Each sub-package carries its own `README.md` - `loop.py` — `AgentLoop` driver + per-node prompt builder. - `message_utils.py` — ReAct-message helpers (`_extract_job_ids`, `_tool_was_called`). - `metric_contract.py` — producer/agent half of the metric-correctness contract (mirrors `pipeline.claim_gate`): domain-neutral obligation text (`build_contract_obligation`), run-level claim-coverage + lineage-chaining steering (`build_coverage_status`, `build_expand_coverage_hint`, `build_inherited_data_note`, `collect_node_measurement_names`), and the post-emit continuation nudge (`build_emission_nudge`). + - `Plan.md` — B1 memory gate / B3 契約凍結 / G4 agent 面注入の実装計画(handoff study). - `react_driver.py` — generic ReAct driver for pipeline `react:` stages, with sandbox enforcement. - `run_env.py` — capture/read helper for `_run_env.json`. - `tool_manager.py` — OpenAI tool conversion, dispatch, phase-aware filtering. @@ -40,6 +42,7 @@ Core engine package for ARI. Each sub-package carries its own `README.md` - `commands.py` — misc top-level commands + `_safe_backup`. - `lineage.py` — end-of-phase lineage-decision helpers. - `migrate.py` — `ari migrate` sub-app. + - `Plan.md` — G5 copy / G7 sterile / G12 timeout・overflow の実装計画(handoff study). - `projects.py` — `ari paper` / `status` / `projects` / `show` commands. - `run.py` — `ari run` / `ari resume` commands. - `clone/` — `ari clone`: fetch + verify + extract curated EAR bundles. @@ -57,6 +60,7 @@ Core engine package for ARI. Each sub-package carries its own `README.md` - `README.md` — config index. - `__init__.py` — Pydantic config models + env-var overrides. - `finder.py` — workflow / profile YAML discovery. + - `Plan.md` — G1 HandoffConfig+env override の実装計画(handoff study). - `configs/` — external config tables (Phase PC). - `README.md` — configs index. - `__init__.py` — config-table exports + loader plumbing. @@ -68,11 +72,13 @@ Core engine package for ARI. Each sub-package carries its own `README.md` - `__init__.py` — public symbols + axis design. - `dynamic_axes.py` — venue/run-specific evaluation-axis derivation. - `llm_evaluator.py` — `LLMEvaluator`: extraction + multi-axis composite scoring. + - `Plan.md` — B2 deterministic evaluator+測定器ユニットの実装計画(handoff study). - `llm/` — thin LiteLLM wrappers for the agent loop and skills. - `README.md` — llm index. - `__init__.py` — public `LLMClient` + contract. - `cli_server.py` — OpenAI-compatible HTTP shim for agentic CLIs. - `client.py` — `LLMClient`/`LLMMessage`: completion + tool calling + cost recording. + - `Plan.md` — ローカルモデル決定性(seed/digest/thinking)の実装計画(handoff study). - `routing.py` — `resolve_litellm_model`: single source of truth for litellm provider-prefix rules so every caller routes a `(model, backend)` to the same id. - `mcp/` — MCP client talking to `ari-skill-*` subprocesses. - `README.md` — mcp index. @@ -102,6 +108,7 @@ Core engine package for ARI. Each sub-package carries its own `README.md` - `lineage_decision.py` — LLM lineage action + `lineage_decisions.jsonl` log. - `node.py` — `Node` data model + `NodeStatus` / `NodeLabel` enums. - `node_selection.py` — shared node-selection helpers + publication source-file selection. + - `Plan.md` — G3 node_summary_view / G9a deterministic selector の実装計画(handoff study). - `root_idea_selector.py` — run-start LLM root-idea pick + selection log. - `web_provenance.py` — read/write `bfts_web_provenance.json`, the marker recording that web search was opted into during BFTS exploration (flags the trajectory non-reproducible, P5). - `node_report/` — per-node `node_report.json` package. diff --git a/ari-core/ari/agent/Plan.md b/ari-core/ari/agent/Plan.md new file mode 100644 index 00000000..7e215b49 --- /dev/null +++ b/ari-core/ari/agent/Plan.md @@ -0,0 +1,23 @@ +# Plan — B1 memory gate / B3 契約凍結 / G4 agent 面注入 / ローカル決定性(loop側) + +Status: 実装計画(未実装)。Origin: 2026-06 handoff study 設計。 +親計画: [`../../MASTER_PLAN_handoff_impl.md`](../../MASTER_PLAN_handoff_impl.md)、研究計画 [`../../PLAN_artifact_summary_handoff.md`](../../PLAN_artifact_summary_handoff.md) §0.2(B1/B3) / §8 Stage 1-2。 + +## 依存関係(他 Plan.md) +- 上流依存: + - [`config/Plan.md`](../config/Plan.md)(G1 HandoffConfig)— gate/注入の全トグルを読む。 + - [`evaluator/Plan.md`](../evaluator/Plan.md)(B2)— **B3 の前提**(契約を凍結しても採点が壊れないのは固定 evaluator があるから)。 + - [`orchestrator/Plan.md`](../orchestrator/Plan.md)(G3 `node_summary_view`)— G4 が注入する view の生成元。 +- 下流: [`cli/Plan.md`](../cli/Plan.md)(copy/sterile)、[`../../scripts/Plan.md`](../../scripts/Plan.md)。 + +## 削除要件 +B1(memory per-arm gate)・B3(契約外生化)・G4(agent 面注入)・seed/thinking 統制が main に land し、**実機**で「code_only の子プロンプトに operational state ゼロ」「契約が run/model 間で不変」を確認、MASTER 完了ログに記録された時点で本 Plan.md を削除する。 + +## 実装項目 +1. **B1 memory gate**: monolithic `loop.py:164-355` の `build_working_context_messages` を **Tier-1a/1b/1c/2 の per-arm 独立 emit に分割**し `handoff.memory_off` で gate。ガード `loop.py:292` より上で無条件発火する Tier-1a(`193-216`)/1c(`218-290`) を必ず gate、**`_PINNED_USER_MARKERS`(`766-775`) の pin 対象も消す**(消さないと window 圧縮を生存)。`search_global_memory`(`650-672`)・auto-save(`920-930`) も対象に含める。 +2. **B3 契約外生化**: `ARI_FREEZE_CONTRACT` で `loop.py:1162-1196` の make_metric_spec 自己決定変異(`self.evaluator.metric_spec=` / `metric_extractor`)を封じ、`loop.py:1207-1219` の per-run 契約 obligation 生成も停止。固定 `metric_contract.json` を pin(or 無し)。`make_metric_spec` は core/pinned ツール(`workflow.py:172`,`loop.py:719`)なので survey/idea off では消えない=明示無効化必須。Tier-1c が残る場合は**固定契約のみ**注入。 +3. **G4 agent 面注入**: `handoff.inject_agent_block`/`log_mode` に応じ、子初回 user message(`loop.py:587-608`)に `node_summary_view`/log を `build_working_context_messages` 経由で append(`loop.py:640-647`)。log は **copy 除外前に親 work_dir から読む**。 +4. **ローカル決定性(loop側)**: qwen3 thinking-mode(`loop.py` 系)を全アーム一貫に(client 側は [`../llm/Plan.md`](../llm/Plan.md))。 + +## 検証ゲート(実機) +`code_only` の子プロンプトをダンプ → Tier-1a/1c/1b/2・契約 narrative が**ゼロ**。`code_plus_summary`/`code_plus_full_log` は view/log が子に届く。`ARI_FREEZE_CONTRACT` 下で同一 input の契約・採点 spec が run/model 間で不変。 diff --git a/ari-core/ari/agent/README.md b/ari-core/ari/agent/README.md index 5e4e0b5c..6ac717ab 100644 --- a/ari-core/ari/agent/README.md +++ b/ari-core/ari/agent/README.md @@ -12,6 +12,7 @@ MCP skills. - `loop.py` — `AgentLoop` driver + per-node prompt builder. - `message_utils.py` — ReAct-message helpers (`_extract_job_ids`, `_tool_was_called`). - `metric_contract.py` — producer/agent half of the metric-correctness contract (mirrors `pipeline.claim_gate`): domain-neutral obligation text (`build_contract_obligation`), run-level claim-coverage + lineage-chaining steering (`build_coverage_status`, `build_expand_coverage_hint`, `build_inherited_data_note`, `collect_node_measurement_names`), and the post-emit continuation nudge (`build_emission_nudge`). +- `Plan.md` — B1 memory gate / B3 契約凍結 / G4 agent 面注入の実装計画(handoff study). - `react_driver.py` — generic ReAct driver for pipeline `react:` stages, with sandbox enforcement. - `run_env.py` — capture/read helper for `_run_env.json`. - `tool_manager.py` — OpenAI tool conversion, dispatch, phase-aware filtering. diff --git a/ari-core/ari/cli/Plan.md b/ari-core/ari/cli/Plan.md new file mode 100644 index 00000000..9ace883a --- /dev/null +++ b/ari-core/ari/cli/Plan.md @@ -0,0 +1,21 @@ +# Plan — G5 copy トグル / G7 sterile-gate 対称化 / G12 timeout・overflow + +Status: 実装計画(未実装)。Origin: 2026-06 handoff study 設計。 +親計画: [`../../MASTER_PLAN_handoff_impl.md`](../../MASTER_PLAN_handoff_impl.md)、研究計画 [`../../PLAN_artifact_summary_handoff.md`](../../PLAN_artifact_summary_handoff.md) §0.2 / §8 Stage 2。 + +## 依存関係(他 Plan.md) +- 上流依存: + - [`../config/Plan.md`](../config/Plan.md)(G1/配線)— `copy_workdir` 等を `agent.handoff` 経由で読む。 +- 関連: [`../agent/Plan.md`](../agent/Plan.md)(配線の対側)。 +- 下流: [`../../scripts/Plan.md`](../../scripts/Plan.md)。 + +## 削除要件 +G5・G7・G12 が main に land し、実機で「copy on/off がアームで効く」「sterile 判定がアーム不変」「per-node 予算が強制 or 明示除外」を確認、MASTER 完了ログに記録された時点で本 Plan.md を削除する。 + +## 実装項目(すべて `bfts_loop.py`) +1. **G5 copy トグル**: 親→子 work_dir copy(`bfts_loop.py:414-445`)を `getattr(agent,"handoff",None).copy_workdir` で gate(既定 True で現状維持)。`_OUTPUT_BLACKLIST` はそのまま。 +2. **G7 sterile-gate 対称化**: `compute_files_changed(parent,child)`(`bfts_loop.py:631-656`)は無条件で score を 0 clamp。copy-OFF アームでは子 dir 空 → 全ファイル「deleted」→ sterile 判定が反転する。**copy-OFF では空 baseline 基準**(子が自分で書いた added/modified のみ数え、幽霊 deleted を無視)にし、アーム間で「no-op」の意味を一定化。 +3. **G12 timeout / overflow**: dead code の TimeoutError 分岐(`bfts_loop.py:532-541`、`as_completed` 後で発火不能)を、(a) 実 wall-clock kill(子をキャンセル可能プロセスで)に直すか、(b) 統制変数から明示除外し `max_react_steps` を唯一予算とする。いずれか事前登録。あわせて **full_log overflow カウンタ**と「overflow 時の full_log 定義」を導入(窓圧縮 `agent/loop.py:725` で full_log が黙って truncated 化するのを明示)。 + +## 検証ゲート(実機) +`copy_workdir=False` アームで親 code が子に来ない。do-nothing 子が copy-ON/OFF 両アームで同じ「sterile」判定。per-node 予算が全アーム同一で強制(or 明示除外を文書化)。 diff --git a/ari-core/ari/cli/README.md b/ari-core/ari/cli/README.md index bb19dcd5..d60cb898 100644 --- a/ari-core/ari/cli/README.md +++ b/ari-core/ari/cli/README.md @@ -12,6 +12,7 @@ construction logic is delegated to `ari.core`. - `commands.py` — misc top-level commands + `_safe_backup`. - `lineage.py` — end-of-phase lineage-decision helpers. - `migrate.py` — `ari migrate` sub-app. +- `Plan.md` — G5 copy / G7 sterile / G12 timeout・overflow の実装計画(handoff study). - `projects.py` — `ari paper` / `status` / `projects` / `show` commands. - `run.py` — `ari run` / `ari resume` commands. diff --git a/ari-core/ari/config/Plan.md b/ari-core/ari/config/Plan.md new file mode 100644 index 00000000..6b268455 --- /dev/null +++ b/ari-core/ari/config/Plan.md @@ -0,0 +1,23 @@ +# Plan — G1: HandoffConfig + env override + 配線 + +Status: 実装計画(未実装)。Origin: 2026-06 handoff study 設計。 +親計画: [`../../MASTER_PLAN_handoff_impl.md`](../../MASTER_PLAN_handoff_impl.md)、研究計画 [`../../PLAN_artifact_summary_handoff.md`](../../PLAN_artifact_summary_handoff.md) §8.1。 + +## 依存関係(他 Plan.md) +- 上流依存: なし(Stage 1 の根)。 +- 下流(本 subtask の単一情報源を読む): + - [`../agent/Plan.md`](../agent/Plan.md) — B1 memory gate / G4 agent 注入 / B3。 + - [`../orchestrator/Plan.md`](../orchestrator/Plan.md) — G3 field トグル。 + - [`../cli/Plan.md`](../cli/Plan.md) — G5 copy トグル / G7 / G12。 + +## 削除要件 +HandoffConfig・`apply_handoff_env_overrides`・呼出配線が main に land し、7 モードが env から再現選択でき、MASTER の完了ログに記録された時点で本 Plan.md を削除する。 + +## 実装項目 +1. **`HandoffConfig`(pydantic, `__init__.py:66-139` の `BFTSConfig` 兄弟)**: `mode`(7値)/`copy_workdir`/`inject_agent_block`/`inject_planner_block`/`log_mode`(none|full|truncated|masked)/`log_truncate_chars`/`summary_form`(extractive|rolling|failure_only)/`summary_fields_enabled: list[str]`/`memory_off`。 +2. **`resolve_mode()`**: 7 モード名 → 上記 bool 集合の写像(`ARI_HANDOFF_MODE` 1 値で run が完全特定)。 +3. **`apply_handoff_env_overrides(cfg)`**: `__init__.py:440-471` の `apply_bfts_env_overrides` を模倣。Literal の env ホワイトリスト検証も踏襲。**同じ呼出箇所から必ず呼ぶ**(定義だけで未配線にしない)。 +4. **配線**: `ARIConfig`(`__init__.py:281` は `extra:allow`)に `handoff:` を追加 → `../core.py:83` で `cfg.handoff` を読む。 + +## 検証ゲート +`ARI_HANDOFF_MODE=code_only|code_plus_summary|code_plus_full_log` の3値で、解決された bool 集合がログに正しく出ることを確認([`../agent/Plan.md`](../agent/Plan.md) の gate と連結)。 diff --git a/ari-core/ari/config/README.md b/ari-core/ari/config/README.md index a07ab2a4..00fc8065 100644 --- a/ari-core/ari/config/README.md +++ b/ari-core/ari/config/README.md @@ -8,6 +8,7 @@ their env-var overrides (`ARI_BACKEND`, `ARI_MODEL`, …). - `README.md` — this file. - `__init__.py` — Pydantic config models + env-var overrides. - `finder.py` — workflow / profile YAML discovery. +- `Plan.md` — G1 HandoffConfig+env override の実装計画(handoff study). ## See also diff --git a/ari-core/ari/evaluator/Plan.md b/ari-core/ari/evaluator/Plan.md new file mode 100644 index 00000000..bc263d96 --- /dev/null +++ b/ari-core/ari/evaluator/Plan.md @@ -0,0 +1,22 @@ +# Plan — B2: deterministic evaluator + 測定器ユニット + +Status: 実装計画(未実装)。Origin: 2026-06 handoff study 設計。 +親計画: [`../../MASTER_PLAN_handoff_impl.md`](../../MASTER_PLAN_handoff_impl.md)、研究計画 [`../../PLAN_artifact_summary_handoff.md`](../../PLAN_artifact_summary_handoff.md) §6.2 / §8 Stage 1。 + +## 依存関係(他 Plan.md) +- 上流依存: なし(Stage 1 の根)。 +- 下流(本 subtask を前提にする): + - [`../orchestrator/Plan.md`](../orchestrator/Plan.md) — G9a は `_scientific_score` を必要とする。 + - [`../agent/Plan.md`](../agent/Plan.md) — B3(契約凍結)は本 evaluator が固定採点を持つことを前提。 + - [`../../scripts/Plan.md`](../../scripts/Plan.md) — analyze は evaluator 出力を集計。 + +## 削除要件 +本 subtask(`deterministic_evaluator.py` + `core.py` の evaluator dispatch + 測定器ユニット)が main に land し、**実機 compute node** で検証ゲートを通過し、MASTER の完了ログに記録された時点で本 Plan.md を削除する。 + +## 実装項目 +1. **`deterministic_evaluator.py`(新規, 本 dir)**: `ari/protocols/evaluator.py` の `Evaluator` Protocol に準拠し、**`evaluate_sync(goal, artifacts, summary, node_id=None, node_label=None)` を必ず実装**(loop は `agent/loop.py:1454/1532/1600` で sync 版を呼ぶ)。戻り値 `{"metrics": {"_scientific_score": s∈[0,1], …}, "has_real_data": bool, "reason": str}`。`node.metrics = eval_result["metrics"]`(`agent/loop.py:1461`)経由で BFTS 選択(`orchestrator/bfts.py:336`)に効くため、**`metrics._scientific_score` を [0,1] 正規化して必ず格納**。 +2. **測定器ユニット(evaluator が独占所有)**: 参照解 oracle(fp64 / 補償加算)、行ごと ε(`C·γ_{nnz}·Σ|A||x|`)、timing(W warmup+R reps median+分散、core pin、freq 固定、OMP 明示、NUMA)、checksum 固定 baseline(candidate と同一フラグ)、anti-gaming(matrix/timing/baseline/correctness を独占、correctness 用 x は call 時供給)。 +3. **dispatch(`../core.py:195`)**: 現状 `LLMEvaluator(...)` ハードコード。`ARI_EVALUATOR` で差し替え可能に(`../core.py:155-182` の `axis_mode` dispatch を模倣)。 + +## 検証ゲート(実機) +固定タスクで `code+summary` を1本実行し、(i) valid node>0、(ii) selector が**非ゼロ** `_scientific_score` を消費、(iii) LLMEvaluator 非経由で採点が完走、を確認。 diff --git a/ari-core/ari/evaluator/README.md b/ari-core/ari/evaluator/README.md index 967e8f53..f521117d 100644 --- a/ari-core/ari/evaluator/README.md +++ b/ari-core/ari/evaluator/README.md @@ -10,6 +10,7 @@ orchestrator consumes. - `__init__.py` — public symbols + axis design. - `dynamic_axes.py` — venue/run-specific evaluation-axis derivation. - `llm_evaluator.py` — `LLMEvaluator`: extraction + multi-axis composite scoring. +- `Plan.md` — B2 deterministic evaluator+測定器ユニットの実装計画(handoff study). ## See also diff --git a/ari-core/ari/llm/Plan.md b/ari-core/ari/llm/Plan.md new file mode 100644 index 00000000..5724a472 --- /dev/null +++ b/ari-core/ari/llm/Plan.md @@ -0,0 +1,25 @@ +# Plan — ローカルモデル決定性: seed plumb / digest pin / thinking-mode 統制 + +Status: 実装計画(未実装)。Origin: 2026-06 handoff study 設計。 +親計画: [`../../MASTER_PLAN_handoff_impl.md`](../../MASTER_PLAN_handoff_impl.md)、研究計画 [`../../PLAN_artifact_summary_handoff.md`](../../PLAN_artifact_summary_handoff.md) §6.3 / §7 / §8 Stage 1。 + +## 依存関係(他 Plan.md) +- 上流依存: なし(Stage 1 の根、独立)。 +- 下流(再現性・統計が本 subtask に依存): [`../../scripts/Plan.md`](../../scripts/Plan.md)(分析の paired/seed 設計)、研究計画 §7。 + +## 削除要件 +seed plumb・digest pin・thinking-mode 統制・per-call provenance 記録が main に land し、実機で「同一 seed/digest で再現性が成立(GPU 非 bit 決定性は n で吸収)」を確認、MASTER 完了ログに記録された時点で本 Plan.md を削除する。 + +## 背景(検証済の現状) +- ローカル backend が既定(`config/__init__.py:581-582`、`ARI_BACKEND=ollama`、既定 `qwen3:8b`、`qwen3:32b` も使用)。 +- temperature はローカルに渡る(`client.py:131`、drop は gpt-5* のみ `client.py:130`)。 +- **seed は `litellm.completion`(`client.py:180`)に未 plumb**。qwen3 thinking-mode 抑制あり(`client.py:141`)。 + +## 実装項目(主に `client.py`) +1. **seed plumb**: `client.py:180/230` の completion kwargs に `seed` を追加(ollama/litellm が pass-through)。 +2. **digest pin**: モデルはタグでなく digest 固定で参照(タグは中身が動く)。 +3. **thinking-mode 統制**: qwen3 thinking を全アーム一貫に(`client.py:141`)。 +4. **provenance**: `cost_tracker.py` の per-call 記録に **resolved model digest / seed / temperature** を追加(現状 model 名のみ)。capability 勾配(small/large、研究計画 RQ-D)はこの provenance で識別。 + +## 検証ゲート(実機) +同一 (seed, digest, temperature, prompt) で複数回実行し、出力分散が API backend より大幅に小さいこと、provenance が trace に正しく残ることを確認。 diff --git a/ari-core/ari/llm/README.md b/ari-core/ari/llm/README.md index 26eb9ab9..8f725ca1 100644 --- a/ari-core/ari/llm/README.md +++ b/ari-core/ari/llm/README.md @@ -10,6 +10,7 @@ templates here (those live under `ari/prompts/`). - `__init__.py` — public `LLMClient` + contract. - `cli_server.py` — OpenAI-compatible HTTP shim for agentic CLIs. - `client.py` — `LLMClient`/`LLMMessage`: completion + tool calling + cost recording. +- `Plan.md` — ローカルモデル決定性(seed/digest/thinking)の実装計画(handoff study). - `routing.py` — `resolve_litellm_model`: single source of truth for litellm provider-prefix rules so every caller routes a `(model, backend)` to the same id. ## See also diff --git a/ari-core/ari/orchestrator/Plan.md b/ari-core/ari/orchestrator/Plan.md new file mode 100644 index 00000000..cf79b576 --- /dev/null +++ b/ari-core/ari/orchestrator/Plan.md @@ -0,0 +1,21 @@ +# Plan — G3 node_summary_view / G9a deterministic selector + +Status: 実装計画(未実装)。Origin: 2026-06 handoff study 設計。 +親計画: [`../../MASTER_PLAN_handoff_impl.md`](../../MASTER_PLAN_handoff_impl.md)、研究計画 [`../../PLAN_artifact_summary_handoff.md`](../../PLAN_artifact_summary_handoff.md) §3 / §8 Stage 2-3。 + +## 依存関係(他 Plan.md) +- 上流依存: + - [`../config/Plan.md`](../config/Plan.md)(G1)— `summary_fields_enabled` / `summary_form` を読む。 + - [`../evaluator/Plan.md`](../evaluator/Plan.md)(B2)— **G9a の前提**(`_scientific_score` が無いと fallback selector が全 0.0 に縮退)。 +- 下流: [`../agent/Plan.md`](../agent/Plan.md)(G4 が `node_summary_view` を注入)、[`../../scripts/Plan.md`](../../scripts/Plan.md)。 + +## 削除要件 +`node_summary_view`(field 別+FORM 変種)と `bfts_score_only` が main に land し、実機で「field トグルが view に反映」「同一 input で選択が再現」を確認、MASTER 完了ログに記録された時点で本 Plan.md を削除する。 + +## 実装項目 +1. **`node_summary_view.py`(新規, 本 dir)**: `node_report.json`(`node_report/builder.py:551-586`)から field 選択可能な view を生成。source=`delta_vs_parent`/`files_changed`/`self_assessment.concerns`/`next_steps_hints`/`metrics._scientific_score`。**`known_failures` は native field 非存在 → failed-node の evaluator_reason / concerns から導出**。FORM 変種: extractive / rolling(祖先要約の有界畳み込み)/ failure_only / masked / truncated。 + ※ 既存 `bfts.py:64-108` `_format_parent_report_block` は **planner プロンプト結合・field 非選択**のため流用不可(新規)。 +2. **G9a `bfts_score_only`**: `bfts.py:418-575` の LLM 一次選択を flag で bypass し、常に `_select_fallback`(`bfts.py:356-369`, `frontier_score=scientific_only`)を一次選択に。これで selector 由来分散を除去。 + +## 検証ゲート(実機) +`summary_fields_enabled` から1 field 落とすと view から当該 field が消える。`bfts_score_only` 下で同一 input の選択が決定的に再現。 diff --git a/ari-core/ari/orchestrator/README.md b/ari-core/ari/orchestrator/README.md index b76d4a14..0207dc1b 100644 --- a/ari-core/ari/orchestrator/README.md +++ b/ari-core/ari/orchestrator/README.md @@ -11,6 +11,7 @@ LLM node scoring, lineage decisions, and root-idea selection. - `lineage_decision.py` — LLM lineage action + `lineage_decisions.jsonl` log. - `node.py` — `Node` data model + `NodeStatus` / `NodeLabel` enums. - `node_selection.py` — shared node-selection helpers + publication source-file selection. +- `Plan.md` — G3 node_summary_view / G9a deterministic selector の実装計画(handoff study). - `root_idea_selector.py` — run-start LLM root-idea pick + selection log. - `web_provenance.py` — read/write `bfts_web_provenance.json`, the marker recording that web search was opted into during BFTS exploration (flags the trajectory non-reproducible, P5). - `node_report/` — per-node `node_report.json` package. diff --git a/ari-skill-memory/Plan.md b/ari-skill-memory/Plan.md new file mode 100644 index 00000000..9292b9dc --- /dev/null +++ b/ari-skill-memory/Plan.md @@ -0,0 +1,24 @@ +# Plan — memory backend 側: RQ-C surface/topology + retrieved-text ロギング + +Status: 実装計画(未実装、Phase C 主体)。Origin: 2026-06 handoff study 設計。 +親計画: [`../ari-core/MASTER_PLAN_handoff_impl.md`](../ari-core/MASTER_PLAN_handoff_impl.md)、研究計画 [`../ari-core/PLAN_artifact_summary_handoff.md`](../ari-core/PLAN_artifact_summary_handoff.md) §3(SURFACE/TOPOLOGY)/ §5 RQ-C / §8 Stage 4。 + +## 位置づけ +RQ-A/B(MVP)の memory **gate**(注入の on/off)は loop 側 [`../ari-core/ari/agent/Plan.md`](../ari-core/ari/agent/Plan.md)(B1)が担当する。本書は **memory backend 側**=RQ-C の「同一 content を push か pull か(surface)」「any-ancestor reach(topology)」を**統制可能にし検証する**ための backend 改修で、**Phase C 主体・MVP では不要**。 + +## 依存関係(他 Plan.md) +- 上流依存: + - [`../ari-core/ari/agent/Plan.md`](../ari-core/ari/agent/Plan.md)(B1 gate / G4 注入)— pure-PULL は loop 側で push ブロックを抑制して初めて成立。 + - [`../ari-core/ari/orchestrator/Plan.md`](../ari-core/ari/orchestrator/Plan.md)(G3)— surface 比較で「同一 content」を固定するため、view 生成と整合。 +- 下流: [`../scripts/Plan.md`](../scripts/Plan.md)(analyze が surface 検証ログを読む)。 + +## 削除要件 +retrieved-text ロギングと pure-PULL/topology の per-arm 制御が main に land し、実機で「push と pull で同一 content が届いたことを検証できる」「parent-only / full-ancestor の reach を arm で切替えられる」を確認、MASTER 完了ログに記録された時点で本 Plan.md を削除する。RQ-C を実施しない判断なら、その旨を MASTER に記録して削除。 + +## 実装項目(`src/ari_skill_memory/`) +1. **retrieved-text ロギング**: `access_log.py` の `build_read_event` は現状 entry_id / score(または type)のみ記録し**取得テキストを残さない**(write preview は約 200 字 cap)。read イベントに**取得テキスト**を記録し、「push 面と pull 面で同一 content が子に届いた」ことを事後検証可能にする。両 backend(`backends/in_memory.py`、`backends/letta_backend.py`)の read 経路に対応。 +2. **pure-PULL の成立条件(backend 側)**: backend は既に `search_memory` を提供。loop 側(B1)で Tier-1b/2 の in-prompt push を抑制した上で、agent 駆動 PULL が安定動作することを担保(ancestor-scope は `backends/in_memory.py:101-106` で既にサーバ側強制)。 +3. **topology ノブ**: reach は `ancestor_ids` 引数で決まる(`backends/in_memory.py:103` `allowed=set(ancestor_ids)`)。parent-only=`[parent_id]` / full=全祖先 / none=`[]` を arm で切替えられることを確認・必要なら明示 API 化(backend 改修は最小)。 + +## 検証ゲート(実機) +content を固定して push-only / pull-only / both を切替え、read ログから「同一 content が両 surface で配送された」ことを確認。`ancestor_ids` で parent-only と full-ancestor の reach 差が出ることを確認。 diff --git a/scripts/Plan.md b/scripts/Plan.md new file mode 100644 index 00000000..03855c11 --- /dev/null +++ b/scripts/Plan.md @@ -0,0 +1,27 @@ +# Plan — 実験ハーネス・run/analyze スクリプト・provenance・コストゲート + +Status: 実装計画(未実装)。Origin: 2026-06 handoff study 設計。 +親計画: [`../ari-core/MASTER_PLAN_handoff_impl.md`](../ari-core/MASTER_PLAN_handoff_impl.md)、研究計画 [`../ari-core/PLAN_artifact_summary_handoff.md`](../ari-core/PLAN_artifact_summary_handoff.md) §8 Stage 4-5 / §11。 + +## 依存関係(他 Plan.md) +- 上流依存(チェーン末端=下記すべてが land 済を前提): + - [`../ari-core/ari/evaluator/Plan.md`](../ari-core/ari/evaluator/Plan.md)(B2) + - [`../ari-core/ari/config/Plan.md`](../ari-core/ari/config/Plan.md)(G1) + - [`../ari-core/ari/agent/Plan.md`](../ari-core/ari/agent/Plan.md)(B1/B3/G4) + - [`../ari-core/ari/orchestrator/Plan.md`](../ari-core/ari/orchestrator/Plan.md)(G3/G9a) + - [`../ari-core/ari/cli/Plan.md`](../ari-core/ari/cli/Plan.md)(G5/G7/G12) + - [`../ari-core/ari/llm/Plan.md`](../ari-core/ari/llm/Plan.md)(seed/digest/provenance) + +## 削除要件 +run/analyze スクリプト・tracked ハーネス・スクラブ・instrumentation が main に land し、実機で end-to-end(run→trace→analyze→図表)が回り、MASTER 完了ログに記録された時点で本 Plan.md を削除する。 + +## 実装項目 +1. **tracked ハーネス**: `.gitignore:31-37`(`*.c`/`benchmarks/`/`experiments/` 等を repo 全体で無視)を**個別 `!` 否定**で例外化し、固定 baseline/candidate kernel・Makefile・seeded matrix generator(families+SuiteSparse SHA256 pin)・README(Contents 同期)を tracked 化。`git check-ignore -v ` で各 fixture が tracked であることを確認。 +2. **`run_handoff_ablation.py`**: arm × model_size × seed を固定予算で sweep。`ARI_HANDOFF_MODE` / `ARI_FREEZE_CONTRACT` / `ARI_EVALUATOR` / deterministic selector flag / `memory_off` / model+digest+seed を設定。出力は `workspace/checkpoints/_/`(リポジトリ規約、$HOME 直下・/tmp 禁止)。 +3. **`analyze_handoff_ablation.py`**: `tree.json` / `cost_trace.jsonl` / `node_report.json` / evaluator 出力(+新設 `handoff_trace.jsonl`)を集計。**`search_trace.jsonl` は存在しないので使わない**。run 単位 cluster bootstrap、parity は TOST、**注入トークンを per-node prompt_tokens と分離計測**、図表。 +4. **instrumentation**: `handoff_trace.jsonl`(per-node 注入トークン/チャネル別)、summary 忠実性(導出 known_failures vs evaluator failure_signature)、provenance([`../ari-core/ari/llm/Plan.md`](../ari-core/ari/llm/Plan.md) と連結)。 +5. **機械情報スクラブ(収集時)**: `node_report` 等に実在する hostname/partition 系(`ari-core/ari/schemas/node_report.schema.json` / `builder.py`)を**収集時にスクラブ**+commit 前 grep ゲート。tracked artifact・図・commit message に機械情報を一切入れない(リポジトリ最優先規約)。 +6. **cost go/no-go ゲート**: `cost_tracker` の `estimated_cost_usd` を集計し per-cell/全体の予算ゲート。ローカル主体・frontier アームのみ予算管理。 + +## 検証ゲート(実機) +`git check-ignore -v` で全 fixture が tracked。スクラブ後 trace に機械情報ゼロ(grep)。run→analyze が end-to-end で図表生成。 diff --git a/scripts/README.md b/scripts/README.md index 32bb939d..fa93ada1 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -7,6 +7,7 @@ Operational and utility scripts for building images, running services, and dev t - `README.md` — this file. - `build_pb_images.sh` — build the vendor PaperBench Docker images (`pb-env`, `pb-reproducer`). - `gpu_ollama_monitor.sh` — monitor the SLURM GPU node running Ollama and re-tunnel it. +- `Plan.md` — ハーネス・run/analyze・scrub・cost ゲートの実装計画(handoff study). - `readme_sync.py` — sync per-directory README `## Contents` indexes with the tree (`--check` gates drift, `--write` regenerates; no LLM/API). - `run_all_tests.sh` — run each skill's pytest suite in its own process. - `run_ollama_gpu.sh` — start Ollama on a SLURM GPU node and tunnel it to the login node.