eval: compare soft-start feedback on snapshot clones

README.md

@@ -298,6 +298,8 @@ Confirmed-outcome feedback reinforcementは、同じ candidate class の `confir
 
 Soft-start feedback reinforcementは、`soft_start_feedback_reinforcement=True`、`soft_start_feedback_ratio`、`confirmation_decay_ratio` を明示する別の default-off candidate です。credited relation edge の最初の新規 `used` は通常 bounded update の一部だけを provisional に適用し、最初の独立 `confirmed` が残りを補完します。後続 confirmation は既存 geometric decay に従い、same-source sibling normalization は `used` ではなく各 confirmation の actual delta だけへ適用します。confirmed-only candidate、hard quorum と同時には有効化できず、既存 q1/s0、q3/s1、confirmed-only、凍結評価 artifact と default fingerprint は変更しません。詳細は[Confirmed-outcome feedback reinforcement](docs/confirmed-outcome-feedback-reinforcement.md#soft-start-successor-candidate)を参照してください。
 
+local database上の比較は、[Soft-start snapshot evaluation](docs/soft-start-snapshot-evaluation.md)でtransaction-consistent private snapshot、固定4 arm、result-free manifest、one-time development、conditional holdout、privacy / mutation / rank hard gateとして分離しています。評価はsnapshotのfresh cloneだけを変更し、source database、live config、snapshot本体、private本文をpublic artifactへ含めません。支持結果も固定local snapshot上のcutover候補に限定し、このissue内でconfigやdefaultを変更しません。
+
 後続の feedback policy comparison に使う public source は、[feedback-policy-comparison-v1](corpora/feedback-policy-comparison-v1/README.md) に corpus-only で固定しています。development / holdout 各二 cluster の明示 link topology、source-only manifest、raw SHA-256、LF 改行規則、provenance、既存 fixture との identity contamination audit だけを含み、評価の選択入力と観測物は含めません。この source merge commit を後続の別 issue が唯一の入力として扱います。
 
 この corpus を使う `used + q3 + sibling normalization 1.0` と `confirmed + decay 0.5 + sibling normalization 1.0` の比較は、[Feedback policy comparison evaluation](docs/feedback-policy-comparison-evaluation.md) に result-free protocol、one-time development、conditional holdout、exclusive observed result、再計算可能な hard gate を固定しています。controlled result は default adoption や production quality を意味しません。

docs/Decision-Structure.md

@@ -18,7 +18,7 @@
 | [longitudinal-feedback-adaptation](https://github.com/Liplus-Project/neuron-graph-rag/wiki/longitudinal-feedback-adaptation) | active | longitudinal feedback-adaptation は、repository-native controlled corpus v3 の相互に独立した cluster と、その source 文書に明記した 0、1、3、10 credit ceiling を用いる。corpus phase は query、gold、schedule、runner、gate、manifest、result、既定値を定義・変更しない。 |
 | [single-corpus-real-feedback-validation](https://github.com/Liplus-Project/neuron-graph-rag/wiki/single-corpus-real-feedback-validation) | superseded | [repository-native-controlled-corpus](https://github.com/Liplus-Project/neuron-graph-rag/wiki/repository-native-controlled-corpus) がこの node を supersede する。以後の evaluation は、NGR repository に公開する固定 SHA の controlled corpus を source とし、D1 single-corpus experiment は capacity が増えるまで waiting とする。 |
 | [repository-native-controlled-corpus](https://github.com/Liplus-Project/neuron-graph-rag/wiki/repository-native-controlled-corpus) | active | repository-native controlled corpus v2 は、固定 SHA の公開 documentation と本文中の明示的な同一 directory 相対 link だけから、node、doc path、source URL、credited edge identity が相互に分離した development / holdout の各 3-edge path を導出する。v1 は provenance として保持する。これは controlled benchmark であり、外部 corpus への一般化、評価 query、gold、result、既定値変更を含まない。 |
-| [soft-start-feedback-reinforcement](https://github.com/Liplus-Project/neuron-graph-rag/wiki/soft-start-feedback-reinforcement) | active | 最初の credited `used` に通常 bounded update の小さな provisional fraction を適用し、最初の独立 `confirmed` が remainder、後続 confirmation が geometric decay を適用する。sibling normalization は confirmation の actual delta だけを使い、default と凍結 artifact は変更しない。 |
+| [soft-start-feedback-reinforcement](https://github.com/Liplus-Project/neuron-graph-rag/wiki/soft-start-feedback-reinforcement) | active | 最初の credited `used` に通常 bounded update の小さな provisional fractionを適用し、最初の独立 `confirmed` が remainder、後続 confirmation が geometric decayを適用する。transaction-consistent private snapshotの固定4 arm評価はdevelopment全hard gate通過時だけholdoutを一度開き、結果をlocal cutover候補に限定してsource database、live config、defaultを変更しない。 |
 | [github-rag-mcp-replacement-compatibility](https://github.com/Liplus-Project/neuron-graph-rag/wiki/github-rag-mcp-replacement-compatibility) | active | public GitHub repository一つのread-only snapshotをNGR local indexへ接続する。github-rag-mcp `search` の保存済み raw capture と source URL、根拠を比較する。共有 source identity を確認しても最小 doc 検索 path の候補に限り、production github-rag-mcp、MCP authentication / transport、remote deployment、default変更は含まない。 |
 
 ## Entry format

docs/requirements.md

@@ -100,6 +100,7 @@
 81. sibling normalization controlled evaluation は、評価対象 source commit / hash、相互に identity-disjoint な development / holdout cluster、明示 edge、baseline `0.0` / treatment `1.0`、query、used node、credited path、mutation scope、rollback、係数 / 時刻 schedule、hard gate、exclusive output を観測前に固定する。実 `NeuronGraphRAG` の `search_channels` relation trace ID を `record_success` に渡し、headroom strict improvement、ceiling・direct・lexical・directional-negative non-regression、path・mutation・atomicity・determinism の全 development gate 通過時だけ holdout を一度開く。観測後は protocol artifact と docs を変更せず、既定値と external D1 claim を変更しない。
 82. frozen evaluation の historical source hash は、manifest path の初回追加 commit または manifest が明示する lowercase full 40-hex source / baseline / prior commit の exact blob bytes に対して検証する。後続の committed manifest rewrite、mutable ref / revision expression、未知 commit、非 ancestor commit、manifest bytes差、欠落 path、hash 不一致を fail closed にし、同名 path の current working tree を過去の evidence として扱わない。既存 protocol が明記する raw-first LF / CRLF whole-file alternate だけを維持し、本文差、mixed newline、bare CR、その他の byte 差を拒否する。
 83. soft-start feedback reinforcement は明示 opt-in の relation-only candidate とし、最初の新規 `used` で通常 bounded increment の固定 ratio 分だけを credited path へ適用する。最初の独立 `confirmed` は同じ schedule の残量を一回分の通常 increment まで補い、後続 confirmation は固定 decay ratio で加算する。used 時は sibling normalization を行わず、confirmation の actual delta だけを同一 source の uncredited sibling へ配分する。duplicate、lexical、zero-hop、別 source、uncredited edge、negative outcome は変更せず、candidate mechanics の合格だけで default や local serving policy を変更しない。
+84. soft-start snapshot evaluation は、local source database を read-only URI と SQLite backup API で一度だけ transaction-consistent snapshot へ複製し、同じ snapshot のfresh clone上で `control`、`used_q3_s1`、`confirmed_r05_s1`、`soft_start_r025_r05_s1` の固定4 armを比較する。query、public node / edge identifier、outcome、3回のfresh trace schedule、checkpoint、metric、hard gate、exclusive output、snapshot / protocol hashを登録result生成前に固定する。source database、live config、snapshot本体、private本文、absolute private pathをpublic artifactへ含めず、developmentを一度だけ実行し、全hard gate通過時だけholdoutを一度開く。不支持または判定不能を保存してもprotocolを調整せず、local cutover、library default、external corpus、production qualityへ自動で一般化しない。
 75. v3 implementation、prompt、manifest、query override、schema、集約、path audit、hash規則、gate、stop rule、testsをresult-free commitでpushした後、development stage / 4 case packet / 12 responses / resultを各一度だけ生成する。
 76. development全12 gate通過時だけholdout stageを一度生成し、異なるfresh 12 judgesで同じgateを評価する。packet、response、resultの上書き、観測後の規則変更、実LLM品質値のCI再生成を拒否する。
 
@@ -136,3 +137,4 @@
 - [Sibling normalization controlled evaluation](sibling-normalization-controlled-evaluation.md) が repository-native corpus、result-free hash freeze、実 relation trace feedback、mutation / rollback gate、conditional holdout を定義する。
 - [Historical source verification](historical-source-verification.md) が frozen manifest path の初回追加 commit、明示 full source commit ID、exact blob、ancestor、path、newline portability、fail-closed 境界を定義する。
 - [Confirmed-outcome feedback reinforcement](confirmed-outcome-feedback-reinforcement.md) が confirmed-only と soft-start の明示 policy、永続 schedule、transaction、receipt、default-preserving boundary を定義する。
+- [Soft-start snapshot evaluation](soft-start-snapshot-evaluation.md) が transaction-consistent private snapshot、固定4 arm、result-free freeze、privacy、one-time development、conditional holdout、local cutover境界を定義する。

docs/soft-start-snapshot-evaluation.md

@@ -0,0 +1,70 @@
+# Soft-start snapshot evaluation
+
+## 目的と判断範囲
+
+この評価は、現在のlocal NGR databaseから一度だけ取得したtransaction-consistent snapshotを使い、次の4 armを同じquery、node role、event順序、checkpointで比較する。
+
+1. `control`: source-useとoutcomeを監査保存するがserving edgeを変更しない。
+2. `used_q3_s1`: relation feedback evidence quorum `3`、sibling normalization `1.0`。
+3. `confirmed_r05_s1`: confirmed-only、confirmation decay `0.5`、sibling normalization `1.0`。
+4. `soft_start_r025_r05_s1`: soft-start ratio `0.25`、confirmation decay `0.5`、sibling normalization `1.0`。
+
+判断対象は、この固定snapshot上でsoft-startがlocal serving cutover候補になれるかだけである。`0.25`と`0.5`は観測前に固定した比較値であり、library defaultや最終採用値ではない。このissueはsource database、live config、project defaultを変更しない。
+
+## Snapshotとprivacy境界
+
+acquisitionはsource databaseをSQLite URI `mode=ro`と`query_only`で開き、SQLite backup APIでprivate destinationへ一度だけ複製する。複製前後のsource container SHA-256が一致し、snapshotの`integrity_check`が`ok`であることを要求する。各armとfresh replayはsnapshotの別temporary cloneだけを開く。
+
+public manifestにはsource locator、capture timestamp、container / snapshot / schema hash、size、table name、選択tableのrow countだけを登録する。snapshot本体、source / snapshotのabsolute path、node本文、credentialを登録しない。fixtureは既にpublicであるnode / edge identifier、固定query、outcome role、mutation許可集合だけを保持する。runnerとverifierはpublic payloadを再帰走査し、private field、absolute path、credential-shaped valueを拒否する。
+
+## Result-free freeze
+
+`soft_start_snapshot_v1` namespaceはfixture、schedule、gate、result schema、result-free audit、manifestを新規作成し、既存の凍結評価artifactを読み替えも変更もしない。manifest pathを初めて追加したcommitのexact blob bytesがhistorical source of truthであり、登録stage実行とresult verificationはcurrent working treeの同名bytesではなく、そのcommitから検証済みbytesを読む。
+
+freeze commitをpushする前は、登録development / holdout outputが存在しないことを確認する。writer / verifierは登録外のplaceholder identityとtemporary outputだけでround-tripを証明する。registered outputはexclusive createし、上書き、再実行、再集計を拒否する。
+
+developmentはfreezeとCI確認後に一度だけ実行する。developmentの全hard gateがpassした場合だけholdoutを一度実行する。失敗または不支持でもquery、ratio、schedule、metric、gate、caseを変更しない。
+
+## Caseとschedule
+
+developmentとholdoutは、それぞれconfirmed cohort、corrected cohort、lexical control、zero-hop controlを持つ。各caseはbaseline後、異なるfresh search traceを使って次を固定順で実行する。
+
+`used_1` → `outcome_1` → `used_2` → `outcome_2` → `used_3` → `outcome_3`
+
+全eventでsource-use / outcome receiptとidempotency replayを保存する。各armは同じsnapshotのfresh cloneで再実行し、runtime identityを除くsemantic payloadが一致することを要求する。
+
+## Metricとhard gate
+
+各checkpointはrelation rank / MRR / Hit@k、score margin、top-k entry / exit、non-target churn、direct rank、reverse relation rankを保存する。全edgeについてweight、reinforced count、evidence count、confirmation countを保存し、credited edge、same-source sibling、unrelated edgeの変化を再計算可能にする。
+
+hard gateは次の7件である。
+
+1. snapshot、case、schedule、receipt、idempotency、fresh-clone replay、exclusive outputのintegrity。
+2. 最初の`used`で正のprovisional deltaを適用し、最初のconfirmedとの合計が通常bounded update一回分で、後続confirmationが固定decayへ従うこと。
+3. q3/s1が3回目前に不変、confirmed-onlyがconfirmed前に不変で、controlが不変であること。
+4. soft-startがcheckpoint 1で先に学習を開始し、最終confirmed cohortのrelation MRRがq3/s1へnon-regressionであること。
+5. corrected cohortのprovisional costを保存し、通常bounded incrementの`0.25`以下に限定し、自動negative reinforcementやrollbackを行わないこと。
+6. lexical、zero-hop、direct、reverse controlへmutationまたはrank regressionを漏らさないこと。
+7. mutationをcredited edgeとconfirmation時のsame-source siblingだけへ限定し、source snapshotを変更しないこと。
+
+## Result解釈
+
+全hard gateがpassしたstageだけを`支持`とする。一件でも不合格なら`不支持`、protocolを完走できなければ`判定不能`をexclusive observed resultへそのまま保存する。developmentが`支持`でない場合はholdoutを開かず、local cutoverを支持しない。holdoutまで`支持`でも、結論は固定local snapshot上のcandidate支持に限定し、別のconfig変更判断なしにlive configを変更しない。
+
+実行入口は次のとおりである。`SNAPSHOT`はpublic repository外のprivate pathを呼出側だけが渡す。
+
+```bash
+python tools/run_soft_start_snapshot_evaluation.py --probe --snapshot "$SNAPSHOT"
+python tools/run_soft_start_snapshot_evaluation.py --stage development --snapshot "$SNAPSHOT"
+python tools/run_soft_start_snapshot_evaluation.py --verify development
+```
+
+holdout commandはdevelopment resultの全hard gate passをpreflightが確認した場合だけ同じ形で一度実行する。
+
+## 関連
+
+- [Requirements](requirements.md)
+- [Confirmed-outcome feedback reinforcement](confirmed-outcome-feedback-reinforcement.md)
+- [Historical source verification](historical-source-verification.md)
+- [Decision Structure](Decision-Structure.md)
+- [Issue #104](https://github.com/Liplus-Project/neuron-graph-rag/issues/104)