diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index ba739fedeb..3659227d16 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -334,6 +334,13 @@ Paired diffs do not certify translation accuracy. §11 targets one provider-result/adopted-work/next-review episode. Matched research continuation and adaptive promotion retain separate gates; see the [implementation comparison](../long-running-execution-exploration-and-correction.md). +- [Joint Target, Yardstick and Stride Decisions v0](target-yardstick-stride-decisions-v0.md) + ([中文版](target-yardstick-stride-decisions-v0.zh-CN.md)) + - **Delivery on `main`:** Design only; no new runtime behavior or default. + - **Current boundary:** Extends the Stride owner with joint direction/measurement + selection, a minimal ordinary-Turn cue and full replan composition. Scoped + fidelity, actual adoption, compatibility and matched outcome/cost qualification + remain implementation acceptance, not measured benefits. - [Post-Outcome Memory Utility Attribution v0](post-outcome-memory-utility-attribution-v0.md) ([中文版](post-outcome-memory-utility-attribution-v0.zh-CN.md)) - **Delivery on `main`:** Stage 1 implemented. diff --git a/docs/architecture/rfcs/STATUS.md b/docs/architecture/rfcs/STATUS.md index 9506d7e94a..4d28fa41ad 100644 --- a/docs/architecture/rfcs/STATUS.md +++ b/docs/architecture/rfcs/STATUS.md @@ -18,7 +18,7 @@ appendix may keep dated history, but no dated log heading may precede it. [中文版](STATUS.zh-CN.md) is the semantic mirror of this file. -## Accepted (47) +## Accepted (48) | RFC | Header status | Supersedes / closes | Ledger | | --- | --- | --- | --- | @@ -68,7 +68,8 @@ appendix may keep dated history, but no dated log heading may precede it. | [RFC: Shared Goal Alignment and Governed Amendment Protocol (v0)](shared-goal-alignment-and-governed-amendment-v0.md) | Accepted | none | [2 entries](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC: LoopX Shared Control-Plane Authority and Pluggable State Providers (v0)](shared-goal-authority-state-provider-v0.md) | Accepted | none | [24 entries](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | Accepted | none | — | -| [RFC: TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.md) | Accepted | none | [18 entries](ledger/typescript-control-plane-migration-v0/) | +| [RFC: Joint Target, Yardstick and Stride Decisions (v0)](target-yardstick-stride-decisions-v0.md) | Accepted | none | — | +| [RFC: TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.md) | Accepted | none | [27 entries](ledger/typescript-control-plane-migration-v0/) | ## Superseded (1) diff --git a/docs/architecture/rfcs/STATUS.zh-CN.md b/docs/architecture/rfcs/STATUS.zh-CN.md index c7999f5343..952c0ca578 100644 --- a/docs/architecture/rfcs/STATUS.zh-CN.md +++ b/docs/architecture/rfcs/STATUS.zh-CN.md @@ -15,7 +15,7 @@ [English](STATUS.md) 与本文互为语义镜像。 -## 已接受 (47) +## 已接受 (48) | RFC | 头部状态 | 替代 / 关闭 | Ledger | | --- | --- | --- | --- | @@ -65,7 +65,8 @@ | [RFC:共享 Goal 对齐与受治理 Amendment 协议(v0)](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md) | 已接受 | 无 | [2 条](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC:LoopX 共享控制面权威与可插拔状态 Provider(v0)](shared-goal-authority-state-provider-v0.zh-CN.md) | 已接受 | 无 | [24 条](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | 已接受 | none | — | -| [RFC:LoopX 控制面 TypeScript 渐进迁移方向 v0](typescript-control-plane-migration-v0.zh-CN.md) | 已接受 | 无 | [18 条](ledger/typescript-control-plane-migration-v0/) | +| [RFC:Target、Yardstick 与 Stride 联合决策(v0)](target-yardstick-stride-decisions-v0.zh-CN.md) | 已接受 | none | — | +| [RFC:LoopX 控制面 TypeScript 渐进迁移方向 v0](typescript-control-plane-migration-v0.zh-CN.md) | 已接受 | 无 | [27 条](ledger/typescript-control-plane-migration-v0/) | ## 已被替代 (1) diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md index b7fd0935ed..c8f7b41181 100644 --- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.md +++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.md @@ -568,6 +568,7 @@ subsystem was not performed. Section 8 records the focused audit. | [Research Exploration Control Plane v0](research-exploration-control-plane-v0.md) | S11/S3 | Accepted; partial M2 composition/successor; §11.5 result/adoption refinement proposed | P1: one real provider result -> scoped interpretation -> adopted step/successor, exact lineage/shared write gate and packaged readback; qualify shadow before opt-in, retain composition gaps; defer inference and M4 portfolio ranking | | [LoopX × LayerFS Engineering Exploration and Evaluation v0](layerfs-engineering-exploration-evaluation-v0.md) | S4/S8/S11 | Proposal; no integration or benefit claim | Bounded experiment: real environment fork/handoff/clean export, then matched warm-worktree and control-policy comparisons; preserve existing research-state/authority owners, count complete cost and negative results; no new priority or default | | [Hierarchical Agent Stride Control v0](hierarchical-agent-stride-control-v0.md) | S11/S7 | Accepted; M1 observation and source-level replan decision followthrough; adaptive policy/continuation unqualified | P2: §7.6 mechanism/evidence scope review -> actual probe/adoption/full cost; §7.7 same-state continuation and recovery before adaptive promotion. Preserve per-Turn settlement and authority; no forced-hour pivot or default cadence change | +| [Joint Target, Yardstick and Stride Decisions v0](target-yardstick-stride-decisions-v0.md) | S3/S6/S11 | Design only; no runtime or default change | P1: reuse the Stride owner for joint direction/measurement selection and a minimal ordinary-Turn cue; M1–M3 qualify identity/recovery, scoped fidelity, actual adoption and complete outcome/cost comparisons before promotion | | [Goal-scoped Capability Portfolio v0](goal-scoped-capability-portfolio-v0.md) | S1/S3/S6/S8/S11 | Accepted; read-only settings/context inspection slice | P1: correction→fresh-session decision across existing owners, then demand-driven composition and measured method evolution; no universal memory database or second opt-in | | [Post-Outcome Memory Utility Attribution v0](post-outcome-memory-utility-attribution-v0.md) | S6/S11 | Accepted; Stage 1 verified-outcome binding | P1 read-only reducer→P2 pilot: distinguish recalled/applied/utility, no automatic ranking change | | [Obelisk Session Evidence Provider v0](obelisk-session-evidence-provider-v0.md) | S6/S8 | Accepted; optional read-only evaluation | P2: explicit gap recall with resolvable provenance/access, off-path parity; no work authority | diff --git a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md index 6ef962f3ed..09d9dfd877 100644 --- a/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md +++ b/docs/architecture/rfcs/loopx-overall-roadmap-v0.zh-CN.md @@ -435,6 +435,7 @@ Muse 设计页在浏览器超时,其文章通过网页检索读取。本次调 | [Research Exploration Control Plane v0](research-exploration-control-plane-v0.zh-CN.md) | S11/S3 | 已接受;M2 composition/successor 局部实现;§11.5 result/adoption 修订为提案 | P1:一条真实 provider result -> 有范围 interpretation -> adopted step/successor,精确 lineage/shared write gate 与 packaged readback;shadow 资格先于 opt-in,保留 composition gap;推断与 M4 portfolio 排序继续 defer | | [LoopX × LayerFS 复杂工程探索与效果评测 v0](layerfs-engineering-exploration-evaluation-v0.zh-CN.md) | S4/S8/S11 | 提案;无集成或收益声明 | 有界实验:真实环境 fork/handoff/干净导出,然后匹配预热 worktree 与控制策略进行比较;保留现有研究状态/权限 owner,计入完整成本和负结果;不新增优先级或默认值 | | [Hierarchical Agent Stride Control v0](hierarchical-agent-stride-control-v0.zh-CN.md) | S11/S7 | 已接受;M1 观测及源码层面的 replan 决策接续;自适应策略/恢复接续未资格化 | P2:§7.6 机制/证据范围复盘 -> 真实探针/采用/完整成本;§7.7 同起点接续及恢复验证先于自适应 promotion。保留每 Turn 结算与权限,不按固定小时强制转向、不改变默认 cadence | +| [Target、Yardstick 与 Stride 联合决策 v0](target-yardstick-stride-decisions-v0.zh-CN.md) | S3/S6/S11 | 仅设计;无运行时或默认变化 | P1:复用 Stride owner 联合选择方向/尺子,并提供最小普通 Turn 提示;M1–M3 验证身份/恢复、范围化 fidelity、真实采用和完整效果/成本,先于推广 | | [Goal-scoped Capability Portfolio v0](goal-scoped-capability-portfolio-v0.zh-CN.md) | S1/S3/S6/S8/S11 | 已接受;只读配置/上下文检查切片 | P1:复用既有 owner 验收纠正→新会话决策,再做按需组合与可测方法演化;不建万能记忆库或第二个启用开关 | | [Post-Outcome Memory Utility Attribution v0](post-outcome-memory-utility-attribution-v0.zh-CN.md) | S6/S11 | 已接受;Stage 1 verified-outcome 绑定 | P1 只读 reducer→P2 pilot:区分 recalled/applied/utility,归因不自动改 ranking | | [Obelisk Session Evidence Provider v0](obelisk-session-evidence-provider-v0.zh-CN.md) | S6/S8 | 已接受;可选只读评估 | P2:显式 gap recall、来源与权限可解析、关闭不影响主流程;不当 work authority | diff --git a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md new file mode 100644 index 0000000000..7238fa7b52 --- /dev/null +++ b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.md @@ -0,0 +1,517 @@ +# RFC: Joint Target, Yardstick and Stride Decisions (v0) + +- **RFC status:** Accepted (effective on merge; this PR is a proposal) +- **Supersedes / closes:** none +- **Delivery maturity:** Proposal +- **Authors / owners:** LoopX maintainers +- **Created:** 2026-11-05 +- **Last normative revision:** 2026-11-05 +- **Implementation baseline:** `aa82591fb0a129f3ea9cc5e67343e742899c7ccd` +- **Related contracts:** [Hierarchical stride](hierarchical-agent-stride-control-v0.md), [Research exploration](research-exploration-control-plane-v0.md), [Research measurement](long-horizon-harness-benchmark-research-program-v0.md), [Controller/executor composition](controller-executor-unified-contract-v0.md) +- **Language mirror:** [中文版](target-yardstick-stride-decisions-v0.zh-CN.md) + +## Document map and maintenance contract + +Sections 1–3 and 5–11 propose the design and acceptance contract; section 4 records +audited implementation facts. Section 12 names unresolved implementation choices. +Appendix A identifies sources and the limits of their evidence. Merge accepts a +design basis, not implementation, deployment, a default change or measured benefit. +Keep both language versions semantically synchronized. Later execution evidence +belongs in the existing RFC ledger convention, with explicit normative revisions +when a decision changes. No runtime changes or experiments are delivered here. + +## 1. Decision summary + +Extend the existing Stride decision owner to consider **which target to pursue, +how to measure it, and how much work to do before another useful observation**. +Use one decision model through two entry points: a small ordinary-Turn projection +and the existing full replan review. Do not make every Turn a replan. + +Three related judgments must remain distinguishable: + +| Judgment | Question | Example consequence | +| --- | --- | --- | +| Target/yardstick co-discovery | Which direction and measurement method together justify investment? | Narrow a broad optimization target, or try a different high-impact component. | +| Yardstick fidelity | Does this measurement distinguish candidates reliably under these conditions? | Recalibrate or replace a misleading proxy while retaining the target. | +| Stride | What coherent work, mechanism distance and validation breadth should come next? | Expand supported work, compare a different mechanism, or resolve uncertainty. | + +The selected object is a **target–yardstick pair**; `grow / switch / verify` +still describes the action. Fidelity is evidence about a pair, not a fourth +Stride action. Continuing unchanged is a legal decision and needs no fabricated +`grow` record on quiet Turns. A target can also use direct authoritative +evaluation without a proxy. + +The new ordinary-Turn and yardstick treatment starts explicitly off. Existing +Stride defaults, configured periodic reviews, acceptance, budgets and host +continuation retain their meaning. This RFC does not approve automatic tool +execution, benchmark-protocol changes or autonomous acceptance changes. + +## 2. Problem and motivation + +A long-running agent may optimize a large component but spend most of its budget +building an affordable evaluator. Conversely, it may repeatedly improve an easy +microbenchmark whose code contributes almost nothing to the real objective. +Checking the current proxy's fidelity addresses neither target-selection error. + +For example, a broad scheduler target may have large potential but no cheap +representative workload. A per-step prefill allocation model may support many +cheap candidate comparisons; an isolated copy operation may support a reliable +microbenchmark. Neither wins automatically: the allocation model may misrank +real workloads, and copying may account for very little end-to-end cost. +Compare these **pairs**, including direct evaluation of the broad target. + +[DuoDiscover](https://arxiv.org/abs/2610.17184v1) motivates this separation. Its +agents discover targets and local yardsticks together, search cheaply, then +confirm gains with the true evaluator. Appendix E.1 compares a yardstick per +target with one per task. Reported validated shares are 58% versus 21% on its +repository tasks and 73% versus 33% on kernels; corresponding yardstick costs +are 4% versus 29% and 2% versus 18% of a true evaluation. These are results of +that study, with different target/task denominators, not predicted LoopX gains. + +### Invariants + +1. Task acceptance and authoritative evaluation stay with their existing owner. + A proxy can guide search; it cannot certify an accepted gain. +2. Every measurement binds the actual candidate, target, evaluator version, + workload and comparison conditions. Missing evidence remains unknown. +3. A declaration, schema-valid decision or read receipt does not prove execution, + fidelity, adoption or goal improvement. +4. Cheap checks cannot discharge an existing replan or acceptance obligation. + Review due-ness alone cannot invalidate a still-useful task identity. +5. Budget includes building and repairing the yardstick, unsuccessful exploration, + confirmation, control overhead and opportunity cost. Preserve failures. +6. No added model call, tool call or durable event is required merely because an + otherwise unchanged ordinary Turn started or settled. + +## 3. Scope and non-goals + +In scope: joint local research decisions, scoped measurement evidence, bounded +ordinary-Turn context, replan composition, decision followthrough, failure/replay +semantics and a qualification program. This refines Stride §§7.5–7.7 and the +roadmap's S3/S6/S11 work; it is not a parallel research roadmap. + +Out of scope: a new scheduler, new global goal authority, a learned controller, +a generic plugin registry, automatic model fleets, changing frozen evaluations, +or implementing numerical fidelity in the kernel. Non-numerical work can use +Stride without inventing a score or proxy. This first design serves the existing +single-agent ordinary-Turn and replan callers; shared evidence does not grant +cross-agent mutation rights. + +## 4. Current-system contract + +The named `main` baseline has these relevant seams: + +| Owner | Audited behavior | Implication | +| --- | --- | --- | +| [`stride_policy.ts`](../../../loopx/control_plane/work_items/stride_policy.ts), `normalizeStrideDecision` | `stride_decision_v2` requires a delivered `replan-context-*` and admitted `replan-*` obligation. It carries action, three plan/reason axes, next probe and prior review. | The current replan-shaped record cannot simply be required on ordinary Turns. | +| [`replan_semantics.ts`](../../../loopx/control_plane/work_items/replan_semantics.ts), `qualify` | Enabled periodic/observed-stall reviews require a current evidence-linked decision; stale context and mismatched prior evidence are checked. | Preserve due-review enforcement and same-obligation recovery. | +| [`replan_history.ts`](../../../loopx/control_plane/work_items/replan_history.ts), `periodicTrigger` | Counts qualified settled work; unchanged monitor polls do not count as work. | A cheap decision/check is not another effective Turn or a counter reset. | +| [`machine_defaults.py`](../../../loopx/capabilities/todo_replan_cadence/machine_defaults.py), `default_replan_cadence_configuration` | Inherited defaults enable evidence-conditioned Stride and review after six settled work Turns; explicit off and saved legacy configuration retain meaning. | The new treatment must have its own explicit opt-in, not silently change these defaults. | +| [`replan_context.ts`](../../../loopx/control_plane/work_items/replan_context.ts), `decisionFollowthrough` | Projects the previous accepted decision and subsequent progress; actual execution/goal gain remain to be established. | Extend this feedback path; do not create a second decision journal. | +| [`Explore result writeback`](../../../loopx/capabilities/explore/result_writeback.py) and [`turn context`](../../../loopx/capabilities/explore/turn_context.py) | Existing ordinary work can attach findings; primary commit survives a retryable attachment failure. Bounded views retain access to omitted evidence. | Reuse attachment/replay and source-bound evidence, without treating bounded delivery as bounded total source work. | + +There is no shipped Yardstick capability in this audited source. Numerical +fidelity below is a proposed profile, not a renamed existing feature. The +[integration guide](../long-running-execution-exploration-and-correction.md) +separates source delivery, actual use and outcome benefit. Open controller +composition work such as [#7430](https://github.com/loopx-project/loopx/pull/7430) +is related transport work, not an implementation dependency or proof of this RFC. + +## 5. Proposed architecture + +### 5.1 One semantic owner, existing storage and specialized measurement + +Keep the joint proposal semantics beside the typed Stride owner in +`control_plane/work_items`. Replan and ordinary-Turn adapters compose this owner; +Python adapters must not implement another policy. Reuse the existing cadence +capability for configuration and the existing Explore result/evidence owner for +findings. No new top-level capability or provider distribution is needed yet. + +Domain measurement adapters own score meaning, correctness, noise, coverage, +headroom estimates and fidelity computation. A first numerical profile can use +the benchmark toolkit's existing evidence boundary. The kernel validates typed +identities and legal transitions, not scientific truth. Two callers sharing +decision semantics justify a shared helper; they do not justify a general agent +decision framework. + +### 5.2 Evidence and identity model + +The following are conceptual fields, not a shipped wire schema. Final naming +must reuse the registered vocabularies and existing reference owners. + +| Record | Required meaning | +| --- | --- | +| Target | Stable reference/revision; goal-acceptance reference; bounded change region or hypothesis; incumbent candidate; allowed scope; headroom evidence and uncertainty. It is a research subproblem, not a replacement Goal. | +| Yardstick | Optional reference/revision; target applicability; executable or rubric identity; workload/input revision; metric direction/units; correctness rule; cost estimate/observations; authoritative evaluator/profile reference. | +| Measurement | Immutable result reference; exact candidate/content identity; target and evaluator revisions; conditions; score and correctness separately; actual cost or unknown; observed/ingested ordering. | +| Fidelity assessment | Target–yardstick–oracle/profile scope; exact evidence set and selection policy; noise/coverage; resolved comparisons; state/reason; evidence watermark and tested validity range. | +| Decision | Original Goal/Agent/work-Turn binding; optional real replan binding; source revision; prior decision; chosen pair or direct evaluation; changed axes/probe; triggering evidence; stop/cost bounds and next review condition. | +| Followthrough | Decision → actual method/artifact → applicable measurement → adoption → authoritative outcome, each allowed to remain unknown. | + +Same-target candidate edits do not automatically invalidate a proxy: those are +what it evaluates. Edits outside its declared applicability, changed workload, +metric, correctness rule, yardstick implementation or authoritative evaluator +require a new scope/revision and fresh qualification. Retain old measurements; +do not transfer a `validated` label by name similarity. Omission retains an +unchanged field; explicit direct-evaluation selection clears only the active +proxy binding, never its evidence history. + +Two entry bindings are a tagged union: **work Turn with Todo** or **real replan +obligation**. Reject mixed/stale bindings. Preserve existing replan decision +references and add an ordinary-work reference form through the same owner; +never synthesize a replan obligation to satisfy the current regex. Exact +serialization/migration is an M1 design task, not an implicit v2 relaxation. + +### 5.3 Co-discovery: invest in a pair + +The model compares the incumbent pair, direct evaluation and a small relevant +set of alternatives, expanding source-bound detail only when needed. It asks: + +- Is there evidence of useful end-to-end headroom, and what is still uncertain? +- Can this yardstick distinguish plausible candidates on this target? +- How much useful search remains after building/calibrating it and confirming + results? Does the remaining horizon justify that investment? +- Would changing target, measurement method, or both resolve the bottleneck? + +Use complete marginal cost: construction + search + repair/calibration + true +confirmation + model/control + switching/opportunity cost. Cheap evaluation time +alone is insufficient. For speed optimization, a measured cost share `w` can +bound ideal whole-program speedup by `1/(1-w)`; this is an upper bound under its +assumptions, not attainable headroom or a universal objective for other domains. +Prefer defensible comparisons/ranges over a fabricated universal utility score. + +Bound proxy construction by an evidence-producing checkpoint and cost budget. +At that checkpoint, compare continued construction, a different proxy kind, +narrowing/changing target and direct evaluation. An untested proxy may support +bounded exploration while confirmations accumulate. An easy proxy is not a reason +to remain on a low-impact target; no reliable proxy is not a reason to idle. + +Retain a promising incumbent while testing alternatives. Switching must name +what changes: only yardstick, only target, or both. Replacing a broken yardstick +is usually `verify`; it is not automatically a mechanism-changing `switch`. + +### 5.4 Fidelity and revalidation + +The proposed numerical-profile states below are scoped assessments, not global +properties. `suspect` is a LoopX proposal, not a fourth state attributed to the +paper. Non-numerical providers need an explicit comparable evidence contract; +do not force Kendall correlation onto document review or qualitative acceptance. + +| State | Evidence | Permitted use / next step | +| --- | --- | --- | +| Untested | Insufficient applicable/noise-resolved comparisons. | Bounded candidate screening with uncertainty; obtain confirmations or use direct evaluation. Never declare validation. | +| Validated | The named profile passes on the scoped evidence set. | Use for search within that scope; authoritative confirmation still required for accepted gains. | +| Suspect | New conflict or applicability uncertainty requires assessment; rejection is not yet established. | Protect incumbent, reduce reliance and perform a bounded discriminating check; no promotion from the proxy alone. | +| Invalidated | Applicable evidence fails the named rejection rule. | Stop using this revision to rank/promote candidates; retain evidence, rebuild or use direct evaluation. | + +New authoritative results trigger a deterministic fidelity reassessment over +applicable paired observations, reusing existing true evaluations. Executing the +proxy against an old candidate still has a cost and requires admission; a trigger +does not launch that work inside `postwriteback`. Untested/suspect assessments can +become validated when sufficient evidence arrives; validated can become suspect +or invalidated. A rejected revision stays historical: repair creates a new +revision, rather than overwriting the failure. Unavailable/corrupt evidence is a +typed observation failure, not statistical invalidation. + +DuoDiscover Appendix A.1 measures noise on identical content states, excludes +unresolved/tied pairs and tests rank agreement, not equality of numeric scores. +Its benchmark recipe uses at least six resolved states, Kendall-style rank +agreement ≥0.5 and one-sided permutation significance at 0.05; its expensive +real-world setting uses a smaller evidence floor. These are study-specific +recipes. LoopX must version the profile, including selection policy, minimum +evidence, noise/tie handling and re-test policy, rather than install universal +thresholds. Repeated tests and proxy-selected candidates create statistical +selection risks: track them, use independent/held-out confirmations where +feasible, and do not interpret nominal significance as a lifetime guarantee. + +### 5.5 Ordinary Turn and full replan + +| Property | Ordinary Turn | Full replan | +| --- | --- | --- | +| Trigger | Newly relevant evidence, a pair applicability change, reached probe boundary, or the model's explicit local reconsideration. | Existing due review/stall obligation, or a proposed change requiring broader work/authority reconciliation. | +| Context | Current task and acceptance, active pair, changed evidence/counterevidence, applicable uncertainty/cost, prior decision followthrough and omitted-detail routes. | Existing Goal/Vision/work graph, competing routes, dependencies, unresolved decisions and selected pair evidence. | +| Model work | In the existing work response; assess changed facts and author only the needed delta. No fixed three-option form each Turn. | Existing explicit planning/review response with required Stride fields and applicable wider comparison. | +| Effects | Existing admitted task, same lease and settlement. A local probe may change within its declared scope. | Existing Todo/Goal/authority operations; newly selected work starts after original settlement and its own admission. | +| Recovery | Original Turn and work identity. | Original obligation, Turn and replan context/recovery owner. | + +Per-Turn **availability** does not mean per-Turn mandatory deliberation. No new +evidence and no reached decision boundary means continue the current authorized +slice with no extra decision payload. Existing settlement and periodic-review +duties still apply. The new record is optional on ordinary Turns; when supplied, +identity, evidence and scope validation are mandatory. Do not describe a rejected +write as advisory guidance. + +Change magnitude and authority determine escalation, not the action word. A +small local `switch` can stay inside the current task. A `grow` that changes +dependencies or crosses permissions needs existing authoring/authority handling. +Acceptance, task protocol and budget changes always go to their current owner. +If a review is already due, combine the local evidence with that review once; +an ordinary decision cannot reset its counter or acknowledge its obligation. + +### 5.6 Lifecycle, writeback and delayed results + +```mermaid +flowchart TD + A[Current task and new evidence] --> B{Existing full review due?} + B -->|Yes| C[Full replan context] + B -->|No| D{Relevant local decision boundary?} + D -->|No| E[Continue current authorized work] + D -->|Yes| F[Small pair and evidence projection] + C --> G[Model chooses pair and stride in existing response] + F --> G + G --> H[Existing scoped work and writeback] + E --> H + H --> I[Deterministic evidence association and review marker] + I --> J[Next admitted work checks adoption and outcome] +``` + +`quota`/guard composes available facts and trigger reasons without a separate +model invocation. Selection remains model judgment. Normal work can inspect +feedback and adjust the next in-scope probe; the final decision is committed +with existing writeback. `postwriteback` only associates committed evidence, +updates materialized assessments when inputs already exist, and records the +next review condition. It does not run an evaluator, edit a Todo graph, request +a new model plan or grant execution authority. + +Use the existing original-Turn effect identity plus an attachment identity. +Exact replay repairs missing associations without re-executing work, duplicating +quota debit or changing the chosen task. Same identity with different contents +is rejected. New decisions within a Turn need explicit ordered identities; they +cannot overwrite a committed proposal. Pre-commit checks reject malformed/stale +attachments. A post-commit delivery failure preserves the primary result and +returns retryable status, following Explore's established boundary. + +Late evaluation belongs to the candidate/pair that produced it, even after the +agent switches direction. It may create a new review reason for the current +agent but cannot silently replace its active pair. Preserve event/ingestion +order and evidence watermarks; resume/compaction may change context delivery, +not reset scientific state or imply the model remembers an omitted finding. +Multiple consumers can cite evidence; only the existing authorized writer can +change the active decision. Conflicting source revisions require reconciliation. + +### 5.7 How the decision changes the model's next action + +Use a **minimal current-work cue derived from the accepted decision**, not a +new Todo, a note on a future Todo, or an invisible ranking hint. This is a +projection of the existing decision's axes and `next_probe`, with source-bound +evidence; it is not another editable planning store or a new Step lifecycle. +Todo owns the deliverable, acceptance, dependencies and lease. The decision +owns the current method, measurement choice and next evidence boundary within +that task. The host still owns individual tool calls. + +Default to one short sentence expressing the decision-relevant uncertainty; +use a second only when needed to avoid misunderstanding. This is a presentation +preference, not a token ceiling, required four-field form or mandatory action +sequence. With no material change, add no repeated cue. For example: + +> Local scores improved, but overall gains are unconfirmed; reconsider whether +> this yardstick is worth continuing to use. + +The model chooses how to investigate, how much in-scope work to do and whether +to retain or replace the method. Do not prescribe tool order, candidate count, +an exhaustive checklist or a canned plan. The durable decision may contain its +reason, evidence and review boundary; those are available on demand and need +not all appear in the cue. Carry +opaque identity and revision metadata through the existing host/context owner. +Full constraints and cited sources remain accessible through their original +owners; shortening the cue cannot omit a newly relevant constraint or contrary +fact from the overall task input. A controller/executor +host uses its existing natural-language work exchange; a single-agent host uses +the current task context. This does not require deploying a second controller +model or waiting for the controller-composition PR. + +| Boundary | How the decision is carried | What must not happen | +| --- | --- | --- | +| Feedback arrives during the same work Turn | The model revises its local next probe while working; commit the meaningful decision with ordinary writeback. | Do not insert another guard/model invocation after every tool result. | +| Next ordinary work Turn on the same task | Project a changed cue beside existing task context; keep evidence and prior adoption available on demand. | Do not create a Todo/Step solely to transport the cue or repeat unchanged guidance. | +| A real new deliverable, dependency or acceptance boundary | Use normal Todo authoring; its first input may reference the applicable decision. | Do not copy a stale decision into arbitrary task notes or let it leak into unrelated work. | + +The cue is explicit, revisable guidance within the current task. It does not +have priority over new user direction, acceptance or fresh counterevidence. +The agent can act on it, revise it or explain why it is no longer applicable +within the existing response; no separate acknowledgement call or compulsory +form is introduced. An unchanged applicable decision can be reused only when +context continuity is established; otherwise the current projection is delivered +again under the existing recovery contract. + +Prompt delivery cannot guarantee obedience. At the next meaningful evidence +boundary, inspect actual calls, candidate/artifact identities and measurements +to distinguish **delivered, adopted, and beneficial**. If the agent continued +an unsupported parameter sweep, record non-adoption and the remaining gap; +do not mark the probe executed because it appeared in a plan. Repeated +non-adoption is evidence for existing stall/replan handling, not an infinite +loop forcing the agent to repeat the same sentence. Hard enforcement remains +limited to real scope, identity, budget and acceptance constraints. Adoption +means addressing the decision-relevant question, not copying a suggested tool +sequence; an independently better route is not a compliance failure. C13 and the +A–D study must establish that the cue helps without narrowing model capability. +Reuse available artifact/measurement evidence for this review; do not require +new per-tool tracing or reread the entire trajectory on each Turn. + +## 6. Alternatives and design choices + +| Alternative | Decision / trade-off | +| --- | --- | +| Separate Stride and Yardstick planners | Reject for the first slice: duplicate reviews can disagree about which target is worth measuring. Keep specialized fidelity computation, share the research decision. | +| Full replan every Turn | Reject: creates fake obligations, broad context and unnecessary work-graph churn. | +| One scalar action or utility score | Reject: conflates target value, measurement reliability and work shape; hides uncertainty and unlike cost units. | +| Calibrate a fixed target only | Insufficient: may spend the horizon repairing a yardstick for an uneconomical target. | +| Always use the true evaluator | Retain as comparator/fallback, especially for cheap evaluation or a short remaining horizon. Proxy construction has no guaranteed benefit. | +| Mandatory form in every writeback | Reject: unchanged work should not need repeated explanation. Shared semantics do not require maximal payloads. | +| A Todo, Step or future-Todo note for each decision | Reject as the transport: the existing decision already owns the method/probe; project it onto the current work input. Create tasks only for actual work boundaries. | +| Model planning inside post-writeback | Reject: introduces hidden cost and failure after the primary commit; use the next admitted work response. | + +## 7. Safety, privacy and compatibility + +The new treatment must be explicitly enabled through the existing configuration +owner; preserve independent existing Stride configuration. Disabled mode adds +no prompt guidance, model/tool calls, decision requirement or change to ordinary +settlement. On readback, historical extra records remain accessible without +being treated as current authority. A shadow experiment must not deliver its +recommendations to the baseline actor; use isolated replay, or label exposure +as a treatment. + +No hidden test access, protocol/cooldown change, scorer replacement or outcome +relabeling is permitted by pair selection. Providers may expose only authorized +evidence. Raw tasks, traces, credentials and private evaluator data stay at the +runtime boundary; public docs/fixtures use synthetic examples. Failed controls +and unknown costs remain visible. Choosing direct evaluation still respects +its availability, cost and permission gates; otherwise report the evidence gap. + +Preserve `stride_decision_v2` readers, writers and due-review validation. Do not +make its required replan identities nullable. New attachments use negotiated +support through existing version handling. An old writer cannot erase new +records or silently downgrade an enabled treatment; unsupported activation +returns an actionable typed result, while feature-off work keeps its old path. + +## 8. Migration and rollback + +First characterize existing replan/off behavior and the ordinary attachment +path. Implement the shared semantics with no default switch. Opt in an isolated +Goal/profile with a source-bound current task, measurement profile and initial +unknown fidelity; historical proxy claims receive no automatic validation. +Read back the exact decision and its first adopted work before broader use. + +Disable at a settled boundary, retain measurements/decisions and finish pending +attachment delivery under the original identities. Disable does not cancel a +healthy task or erase a due replan. Before binary downgrade, verify no pending +new-schema write remains; otherwise finish recovery with a supporting binary +or keep the affected write paused with its original receipt. No destructive +conversion or journal rewrite is part of this proposal. + +## 9. Validation and acceptance + +### 9.1 Conformance scenarios + +These are implementation acceptance requirements, not tests already passed. + +| ID | Scenario | Required observable result | +| --- | --- | --- | +| C1 | No new evidence on an ordinary Turn | Same task/lease/settlement, no new model/tool call or decision event; no manufactured replan. | +| C2 | Strong local proxy gain, tiny target cost share | Compare goal headroom and alternatives; no accepted whole-goal gain inferred from the local number. | +| C3 | High-impact target, unaffordable/unreliable proxy | Bound construction; allow narrowing/other target/direct evaluation. Do not idle or rebuild indefinitely. | +| C4 | Proxy ordering disagrees with applicable true results | Profile-scoped suspect/invalidation; incumbent protected; failed revision and confirmation cost retained. | +| C5 | Too few/noisy/tied observations, or missing evidence | Unknown/untested rather than validated or disproven; failed transport distinguished from scientific evidence. | +| C6 | Candidate within target versus changed workload/oracle | Former can add fidelity evidence; latter requires a new applicability assessment. No transfer of validation by name. | +| C7 | Late true result after a target switch | Result attaches to original candidate/pair; current decision changes only through explicit authorized review. | +| C8 | Crash after primary commit, before evidence association | Repair under original identity; no repeated experiment or second debit. | +| C9 | Local check coincides with due full replan | One combined review; all existing obligations remain enforced. | +| C10 | Local mechanism switch versus scope/authority expansion | In-scope probe stays on task; broader change uses owning authoring/authority path. No implicit permission. | +| C11 | Stale/foreign refs, partial context, concurrent writer, mixed schema | Reject unsupported identity/effect; recover source-bound detail without pretending omitted evidence was read. | +| C12 | Treatment off, old configuration, disable/re-enable | Existing behavior/history retained; no new default, prompt, required field or schedule effect. | +| C13 | Cue raises ranking uncertainty; actor ignores it, finds a better method, or receives contrary user direction | Actual artifacts distinguish delivery from addressing the question; allow improved alternatives and justified revision. Compare concise cue versus no cue for useful action and overhead; never require a scripted tool sequence. | + +Replay typed scenarios with synthetic evidence against real File/SQLite owners +where persistence is touched. Use actual host/CLI settlement and packaged +readback for the first adopted slice; schema-unit tests alone are insufficient. + +### 9.2 Outcome and cost study + +Use staged comparisons, not all combinations immediately: + +| Arm | Treatment / question | +| --- | --- | +| A | Current Stride at existing replan boundaries. | +| B | A + lightweight ordinary-Turn decision path, no proxy machinery: does timely local judgment help? | +| C | B + fidelity-aware yardstick for a fixed target: what does calibration add? | +| D | C + joint target/yardstick selection: does co-discovery justify switching/build cost? | + +First use matched saved starting states for focused decision episodes; then +whole tasks across distinct workloads and repeated seeds. Freeze model, +available tools, feedback/acceptance protocol, starting artifact, task budget, +stopping rules and resource contention policy. Compare both equal total cost +and score over wall time; the same token ceiling alone does not equalize cost. +Fixed-target C and joint D must share initial target and candidate information; +target freedom is the intended treatment. Keep arms/results traceable after +reruns and include valid zero outcomes and agent failures. + +Primary measures are authoritative accepted outcome versus **complete cost** +and time to first accepted gain, with paired uncertainty and cost/quality +frontiers. Also measure control tokens/calls/latency, evaluator construction and +repair share, true evaluations per accepted gain, selected-pair lifetime, +unsupported promotions, unnecessary switches and abandoned useful work. +Decision → adopted work → useful information → confirmed gain are separate +columns; more decisions or higher proxy scores are not success metrics. + +Before a confirmatory run, register task split, repeats, non-inferiority margin, +cost/latency budgets and stopping/analysis rules. Do not choose thresholds after +seeing a favorable case. Promotion requires conformance, no authority/protocol +regression, and repeated evidence of better accepted outcomes at comparable +cost or lower complete cost for comparable outcomes. Keep inconclusive/negative +results. Paper gains and a successful synthetic replay do not qualify LoopX. + +## 10. Operational contract + +CLI, App and Lark reuse the same projection: current target, current yardstick +or direct evaluation, fidelity/uncertainty, last true outcome, why the next +action was chosen, cost to the next boundary and any full review due. Show +details on demand; do not make users read the decision schema. Configuration +activation/disable and unsupported-version feedback belong in existing editors. + +Keep a compact current projection plus immutable evidence references and +explicit omitted counts/detail access. Measure total source-reading work, +returned context, writes and latency: a short JSON view does not establish +bounded backend cost. Batch known required reads; avoid an extra discover/read +round trip when the current pair already supplies the needed references. +Unavailable optional measurement evidence keeps the current legally supported +task path, with utility unknown; unavailable authority still obeys its existing +fail-closed owner. No evidence outage authorizes fake scientific progress. + +## 11. Normative delivery plan + +| Milestone | Useful slice | Entry / exit evidence | Rollback | +| --- | --- | --- | --- | +| M1 | One typed proposal owner with replan compatibility, an opt-in ordinary-Turn attachment and minimal work cue | Approved binding/version seam; C1/C8–C13; source and packaged same-Turn readback; no default changes. | Disable new treatment; retain records and settle pending attachments. | +| M2 | One real numerical target/yardstick profile, bounded context and joint decision through both callers | M1; C2–C7; complete build/search/confirmation costs; real adopted probe and truthful CLI/App/Lark readback. | Direct authorized evaluation or existing task path; preserve failed evidence. | +| M3 | Matched episodes then full-task outcome/cost qualification | C1–C13 and registered A–D study; actual adoption, negative cases, uncertainty and full cost. | Keep opt-in; reject or revise unsupported policy. | + +M1 and M2 are delivery slices, not claims of long-horizon gain. Reuse the +existing Stride/Explore owners and downstream callers; remove prototype +duplicates when adopted. Do not add a registry, second journal or speculative +provider abstraction to make these milestones appear complete. + +## 12. Open decisions + +| Decision | Owner / recommendation | Evidence needed / deadline | +| --- | --- | --- | +| Exact attachment schema and configuration field | Work-items and cadence maintainers: additive tagged work/replan binding, independent opt-in; preserve v2. | Producer/reader inventory and C8–C12 before M1 implementation. | +| First fidelity profile and evidence floor | Measurement provider maintainer: rank-based profile for a numerical task; no universal six-state rule. | Noise, selection/re-testing risks and affordable true confirmations before M2. | +| Automatic triggers and context budget | Stride/context maintainers: typed evidence deltas and reached probe conditions; no prose classifier or fixed per-Turn form. | Full-path overhead and missed-decision counterexamples in M1/M2; thresholds fixed before M3. | +| Default promotion | Product owner: remain off until matched evidence justifies promotion. | M3 including regressions, uncertainty and actual user journey. | + +## Appendix A: Evidence registry and limitations + +| Evidence | Source | What it supports / limit | +| --- | --- | --- | +| E1 | [DuoDiscover v1](https://arxiv.org/html/2610.17184v1), §§2.2–2.4; Appendices A.1, E.1, F.1–F.5 | Joint search, rank fidelity, per-target ablation and failure behavior. Author-reported results; not independently reproduced here. | +| E2 | Baseline source links in §4; [Stride §7.6](hierarchical-agent-stride-control-v0.md#76-research-scope-and-evidence-conditioned-control) | Current replan identity, axis and followthrough seams. A source audit, not installed/new-feature validation. | +| E3 | [Research measurement model](long-horizon-harness-benchmark-research-program-v0.md#6-measurement-model) | Shared outcome/cost/adoption comparison owner; this RFC adds a bounded treatment matrix. | +| E4 | Scenarios C1–C13 | Proposed falsifiable acceptance cases; unexecuted until implementation. | + +The paper's favorable fallback observations do not prove a no-regret guarantee: +failed yardstick construction has already consumed budget. Per-target versus +task-wide validation rates use different units. Candidate selection and +repeated fidelity tests limit statistical interpretation. These caveats motivate +complete-cost accounting and authoritative confirmation, not rejection of +co-discovery. There is no implementation decision log yet; recommendations in +this proposal are not maintainer approval. diff --git a/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md new file mode 100644 index 0000000000..59801c6fec --- /dev/null +++ b/docs/architecture/rfcs/target-yardstick-stride-decisions-v0.zh-CN.md @@ -0,0 +1,407 @@ +# RFC:Target、Yardstick 与 Stride 联合决策(v0) + +- **RFC 状态:** Accepted(合并后生效;本 PR 仍是提案) +- **替代 / 关闭:** none +- **交付成熟度:** Proposal +- **作者 / 归属:** LoopX maintainers +- **创建日期:** 2026-11-05 +- **最近规范修订:** 2026-11-05 +- **实现基线:** `aa82591fb0a129f3ea9cc5e67343e742899c7ccd` +- **相关契约:** [分层 Stride](hierarchical-agent-stride-control-v0.zh-CN.md)、[研究探索](research-exploration-control-plane-v0.zh-CN.md)、[研究测量](long-horizon-harness-benchmark-research-program-v0.zh-CN.md)、[Controller/Executor 组合](controller-executor-unified-contract-v0.zh-CN.md) +- **语言镜像:** [English](target-yardstick-stride-decisions-v0.md) + +## 文档地图与维护契约 + +第 1–3、5–11 节提出设计与验收契约;第 4 节记录已核对的当前实现; +第 12 节列出尚待决定的实现选择。附录 A 标明来源及证据边界。 +合并只接受设计依据,不证明实现、部署、默认启用或效果收益。 +双语版本保持语义一致。后续执行证据沿用 RFC ledger 约定;改变设计时显式修订规范。 +本 PR 不交付运行时改动,也不启动实验。 + +## 1. 决策摘要 + +扩展现有 Stride 决策归属,让它共同考虑:**研究哪个方向、如何测量、 +在下一次有用反馈前做多少工作**。同一套判断通过两个入口使用: +普通 Turn 的精简投影,以及现有完整 replan。不要把每个 Turn 都变成 replan。 + +三种相关判断必须可以区分: + +| 判断 | 回答的问题 | 可能产生的行动 | +| --- | --- | --- | +| Target/yardstick co-discovery | 哪种“方向+测量方法”值得共同投入? | 收窄过大的优化目标,或转向另一处高收益组件。 | +| Yardstick fidelity | 在这些条件下,这把尺子能否可靠地区分候选? | 保留方向,校准或替换误导性的代理评测。 | +| Stride | 下一步做多大工作、改变多少机制、验证多宽? | 扩大有依据的工作、比较不同机制,或消除不确定性。 | + +选择对象是 **target–yardstick 组合**;`grow / switch / verify` 仍描述行动。 +Fidelity 是关于组合的证据,不是第四种 Stride 动作。保持原计划合法, +没有变化的 Turn 不必补造 `grow` 记录。方向也可以直接使用权威评测,不配置代理。 + +新增普通 Turn 与 yardstick 行为初始显式关闭。现有 Stride 默认值、配置的周期复盘、 +验收、预算和宿主续跑语义保持。本 RFC 不批准自动工具执行、benchmark 协议改动, +也不允许 Agent 自行改变验收。 + +## 2. 问题与动机 + +长程 Agent 可能选择了很有空间的大组件,却把大部分预算花在制作便宜评测上; +也可能不断改善一个很好测、但对整体目标几乎无贡献的微基准。 +只检查当前尺子的 fidelity,无法解决这两种方向选择错误。 + +例如,整个调度器或许有很大空间,但找不到便宜且有代表性的 workload。 +每步 prefill 配额可以用成本模型快速比较候选;隔离的数据复制操作可能很好测。 +二者都不是天然优选:成本模型可能错排真实 workload,复制也可能只占整体成本的一小部分。 +应该比较这些**组合**,也保留直接评测整个调度器的选项。 + +[DuoDiscover](https://arxiv.org/abs/2610.17184v1) 提供了这个区分的研究依据。 +Agent 联合发现 target 和局部 yardstick,便宜地搜索,再用真实评测确认收益。 +附录 E.1 对比每个 target 一把尺子与每个 task 一把尺子:仓库任务报告的通过 +fidelity 检查比例分别为 58% / 21%,kernel 为 73% / 33%;尺子成本占真实评测的 +比例分别为 4% / 29% 和 2% / 18%。这是论文结果,且 target/task 的分母不同, +不能作为 LoopX 收益预测。 + +### 不变量 + +1. 任务验收和权威评测仍由原 owner 决定。代理可以引导搜索,不能证明收益已获验收。 +2. 每项测量绑定实际候选、target、评测版本、workload 和比较条件。缺失证据保持未知。 +3. 声明、合法 schema、读取回执都不等于执行、fidelity、采用或 Goal 改善。 +4. 轻量检查不能抵消既有 replan 或验收义务;复盘到期本身不能废弃仍有价值的工作身份。 +5. 成本包含造尺子、修尺子、失败探索、真实确认、控制开销和机会成本。失败证据必须保留。 +6. 不能仅因无变化的普通 Turn 启动或结算,就要求新增模型调用、工具调用或持久化事件。 + +## 3. 范围与非目标 + +范围包括联合局部研究决策、有适用范围的测量证据、普通 Turn 有界上下文、 +replan 组合、决策采用追踪、失败/重放语义及资格验证。 +这是 Stride §§7.5–7.7 和 roadmap S3/S6/S11 的细化,不另建研究路线图。 + +不包括新 scheduler、新全局 Goal 权威、学习型 controller、通用插件注册中心、 +自动模型集群、修改冻结评测,或在 kernel 中实现数值 fidelity。 +非数值工作可以只用 Stride,不必发明分数或代理。首版服务现有单 Agent 的普通 Turn +和 replan 两个调用方;共享证据不授予跨 Agent 修改权限。 + +## 4. 当前系统契约 + +在标明的 `main` 基线上核对了以下接缝: + +| Owner | 当前行为 | 对设计的影响 | +| --- | --- | --- | +| [`stride_policy.ts`](../../../loopx/control_plane/work_items/stride_policy.ts),`normalizeStrideDecision` | `stride_decision_v2` 要求已交付的 `replan-context-*` 和已准入的 `replan-*` obligation,携带 action、三个 plan/reason 轴、next probe、previous review。 | 不能直接要求普通 Turn 填这份 replan 结构。 | +| [`replan_semantics.ts`](../../../loopx/control_plane/work_items/replan_semantics.ts),`qualify` | 已启用的周期/停滞复盘要求当前、证据关联的决策;校验过期 context 和不匹配的前序证据。 | 保留到期复盘要求及原 obligation 恢复。 | +| [`replan_history.ts`](../../../loopx/control_plane/work_items/replan_history.ts),`periodicTrigger` | 计数合格的已结算工作;无变化 monitor poll 不算工作。 | 轻量判断不是额外有效 Turn,也不重置计数。 | +| [`machine_defaults.py`](../../../loopx/capabilities/todo_replan_cadence/machine_defaults.py),`default_replan_cadence_configuration` | 继承默认启用 evidence-conditioned Stride,每六个已结算工作 Turn 复盘;显式 off 和旧配置保持原含义。 | 新行为要独立显式启用,不能悄悄改变默认。 | +| [`replan_context.ts`](../../../loopx/control_plane/work_items/replan_context.ts),`decisionFollowthrough` | 投影前次已接受决策和后续进展;实际执行/Goal gain 仍需判断。 | 扩展现有反馈路径,不新建决策 journal。 | +| [`Explore 写回`](../../../loopx/capabilities/explore/result_writeback.py)、[`Turn context`](../../../loopx/capabilities/explore/turn_context.py) | 普通工作可附加 finding;附件可重试失败不抹掉主提交;有界视图保留被省略证据的读取入口。 | 复用附件/重放和来源绑定,不能把投影有界等同于总读源成本有界。 | + +核对的源码中没有已交付的 Yardstick capability。下文数值 fidelity 是提案, +不是给既有产品能力改名。[整合说明](../long-running-execution-exploration-and-correction.zh-CN.md) +已经区分来源交付、实际使用和结果收益。尚未合入的 controller composition +工作如 [#7430](https://github.com/loopx-project/loopx/pull/7430) 属于相关传输改进, +不是本 RFC 的实现前置依赖,也不构成本方案有效的证据。 + +## 5. 提议架构 + +### 5.1 一个决策 owner,复用存储,测量归专业层 + +联合提案语义放在 `control_plane/work_items` 的既有 typed Stride owner 附近。 +replan 和普通 Turn adapter 组合它;Python adapter 不另写一套策略。 +配置复用 cadence capability,finding/证据复用 Explore owner,暂不新建顶层 capability +或 provider distribution。 + +领域测量 adapter 负责分数意义、正确性、噪声、覆盖、headroom 估计和 fidelity 计算。 +首个数值 profile 可复用 benchmark toolkit 既有证据边界。Kernel 检查身份和合法转换, +不判科学结论。两个调用方共享判断,足以支持一个共用 helper;不足以支持通用 Agent 决策框架。 + +### 5.2 证据和身份模型 + +以下为概念字段,不是已交付 wire schema。最终命名应复用已注册词汇和 reference owner。 + +| 记录 | 必须表达的含义 | +| --- | --- | +| Target | 稳定引用/版本、Goal 验收引用、有界修改区域或假设、当前候选、允许范围、headroom 证据及不确定性。它是研究子问题,不替代 Goal。 | +| Yardstick | 可选引用/版本、target 适用范围、程序或 rubric 身份、workload/input 版本、指标方向/单位、正确性规则、成本估计/观测、权威 evaluator/profile 引用。 | +| Measurement | 不可变结果引用、精确候选/content 身份、target/评测版本、条件、分开记录的分数与正确性、实际成本或未知、观测和接收顺序。 | +| Fidelity assessment | Target–yardstick–oracle/profile 范围、精确证据集合及选择规则、噪声/覆盖、可区分比较、状态/原因、证据 watermark 和已测有效范围。 | +| Decision | 原 Goal/Agent/工作 Turn 绑定、可选的真实 replan 绑定、来源版本、前次决策、所选组合或直接评测、变化的轴/probe、触发证据、停止/成本边界与下次判断条件。 | +| Followthrough | 决策→实际方法/产物→适用测量→采用→权威结果,各环节都允许保持未知。 | + +同一 target 内修改候选不会自动让尺子失效,这正是它要评测的对象。 +超出适用范围、改变 workload、指标、正确性规则、yardstick 实现或权威 evaluator, +才需要新范围/版本和重新确认资格。保留历史测量,不能凭名字相似转移 `validated`。 +省略字段表示保持;显式选择直接评测只清除当前代理绑定,不清除其证据历史。 + +入口绑定是 tagged union:**有 Todo 的工作 Turn**,或**真实 replan obligation**。 +拒绝混合/过期绑定。保留现有 replan decision reference,并通过同一 owner 添加普通工作引用形式。 +绝不为满足当前 regex 伪造 replan obligation。精确序列化/迁移属于 M1 设计, +不能隐式放宽 v2。 + +### 5.3 Co-discovery:投资于组合 + +模型比较当前组合、直接评测及少量相关替代方案,需要时才扩读有来源绑定的细节。它考虑: + +- 是否有整体收益空间的证据,哪些部分还不确定? +- 这把尺子能否区分这个方向上的合理候选? +- 扣掉构造、校准和真实确认后还剩多少搜索空间?剩余 horizon 是否值得这笔投入? +- 改 target、改测量方法,还是同时改,最可能解除瓶颈? + +比较完整边际成本:构造+搜索+修复/校准+真实确认+模型/控制+切换/机会成本。 +不能只看单次小评测有多快。对于性能优化,已测成本占比 `w` 可在假设成立时提供 +`1/(1-w)` 的理想整体加速上界;它不是可实现 headroom,也不是其他领域的统一目标函数。 +优先使用有依据的比较与区间,不捏造通用 utility 标量。 + +造尺子要有能产出证据的 checkpoint 和成本边界。到边界时比较继续构造、换尺子类型、 +收窄/改变 target、直接评测。Untested 尺子可以支持有界探索,同时积累真实确认。 +容易测不是留在低收益方向的理由;找不到可靠尺子也不是空转的理由。 + +试替代方案时保护有前景的 incumbent。切换明确改的是尺子、方向还是两者。 +只替换坏尺子通常属于 `verify`,不自动意味着研究机制发生 `switch`。 + +### 5.4 Fidelity 与重新验证 + +以下数值 profile 状态是带适用范围的判断,不是全局属性。`suspect` 是 LoopX 提案, +不把它说成论文第四种状态。非数值 provider 需定义可比较证据契约, +不能把 Kendall correlation 强加到文档评审或定性验收上。 + +| 状态 | 证据 | 允许用途 / 下一步 | +| --- | --- | --- | +| Untested | 适用或超出噪声的比较不足。 | 带不确定性的有界筛选,补真实确认或直接评测;不声称已验证。 | +| Validated | 指定 profile 在该范围证据上通过。 | 在范围内用于搜索;收益验收仍需权威确认。 | +| Suspect | 新冲突或适用范围不确定,尚未达到否定条件。 | 保护 incumbent、减少依赖,做有界区分检查;不能仅凭代理推广。 | +| Invalidated | 适用证据满足指定否定规则。 | 停止用该版本排名/推广候选;保留证据,重建或直接评测。 | + +新权威结果触发基于已有适用配对观测的确定性重评,复用已做的真实评测。 +在历史候选上再运行代理仍有成本,需要准入;不能因触发条件成立,就在 `postwriteback` +里偷偷执行。证据充分后,untested/suspect 可变为 validated;validated 可变为 +suspect/invalidated。被否定版本保持历史,修复创建新版本,不覆盖失败。 +证据不可用/损坏属于带类型的观测失败,不等于统计否定。 + +DuoDiscover 附录 A.1 在相同 content state 上估计噪声,排除不可区分/并列 pair, +检验排序一致而非分数相等。论文 benchmark recipe 使用至少六个可区分状态、 +Kendall 式排序相关 ≥0.5、单侧置换显著性 0.05;昂贵的真实任务采用更小的证据下限。 +这些是特定实验的规则。LoopX 应版本化 profile,包括样本选择、最低证据、噪声/并列处理 +和重测规则,而非全局固定阈值。重复检验和代理筛出的候选存在选择偏差:需要记录, +可行时使用独立/留出确认,不把名义显著性当成终身可靠保证。 + +### 5.5 普通 Turn 与完整 replan + +| 属性 | 普通 Turn | 完整 replan | +| --- | --- | --- | +| 触发 | 新相关证据、组合适用范围变化、probe 到边界,或模型显式重新考虑局部方案。 | 现有到期/停滞复盘义务,或需要更广工作/权限协调的变更。 | +| 上下文 | 当前任务/验收、组合、变化证据/反证、适用的不确定性/成本、前次采用及省略细节入口。 | 既有 Goal/Vision/工作图、竞争路线、依赖、未决问题和组合证据。 | +| 模型工作 | 在现有工作回复中判断变化,只写必要 delta;不要求每轮填三选一。 | 原 planning/review 回复及必需 Stride 字段,按需更广比较。 | +| Effects | 原准入任务、同一 lease 和 settlement;可在声明范围内调整局部 probe。 | 既有 Todo/Goal/权限操作;新工作在原结算完成并再次准入后启动。 | +| 恢复 | 原 Turn 和工作身份。 | 原 obligation、Turn、replan context/recovery owner。 | + +每轮**可用**不等于每轮强制审议。无新证据且未到判断边界时,继续当前合法工作, +不附加决策 payload;原结算及周期复盘要求仍适用。普通 Turn 的新记录是可选的; +一旦提交,身份、证据和范围校验是强制的。不能把会拒绝写回的规则称为“建议”。 + +是否升级由变更幅度和权限决定,不由动作词决定。小范围 `switch` 可以留在当前任务; +改变依赖或越过权限的 `grow` 要走原 authoring/authority 路径。 +验收、协议、预算变更始终由原 owner 处理。若复盘已经到期,局部证据合入该次复盘, +只判断一次;普通决策不能重置计数或确认该义务已完成。 + +### 5.6 生命周期、写回与延迟结果 + +```mermaid +flowchart TD + A[当前任务与新证据] --> B{既有完整复盘已到期?} + B -->|是| C[完整 replan context] + B -->|否| D{到达相关局部判断边界?} + D -->|否| E[继续当前已授权工作] + D -->|是| F[精简组合与证据投影] + C --> G[模型在现有回复中选择组合与 Stride] + F --> G + G --> H[现有范围内工作与写回] + E --> H + H --> I[确定性证据关联和复盘标记] + I --> J[下次已准入工作核对采用与结果] +``` + +`quota`/guard 组合已有事实和触发原因,不另调模型。选择由模型判断。 +普通工作可检查反馈并调整下一项范围内 probe,最终决策和原 writeback 一起提交。 +`postwriteback` 只关联已提交证据、在输入齐备时更新物化判断、记录下次 review 条件; +不运行 evaluator、不编辑 Todo 图、不调用模型重新计划、不授予执行权限。 + +复用原 Turn effect identity 并绑定 attachment identity。精确重放只补缺失关联, +不重复执行、不重复扣额、不切换当前任务;同身份不同内容拒绝。 +同 Turn 新决策需显式有序身份,不能覆盖已提交提案。提交前拒绝错误/过期附件; +提交后交付失败保留主结果并返回可重试状态,沿用 Explore 边界。 + +即使 Agent 已换方向,延迟评测仍归产生它的原 candidate/pair。它可以产生新的 review 原因, +不能悄悄替换当前组合。保留事件/接收顺序和 evidence watermark。 +恢复/压缩只影响上下文交付,不重置研究状态,也不假定模型记得省略的 finding。 +多个消费者可以引用证据,只有既有授权 writer 可以改变当前决策;来源版本冲突需核对。 + +### 5.7 如何驱动模型的下一步行动 + +用**由已接受决策生成的最小当前工作提示**,不新建 Todo,不塞下个 Todo 的 note, +也不靠模型看不到的排序暗示。这是现有决策 axes、`next_probe` 和来源证据的投影, +不是另一个可编辑计划库,也不新建 Step 生命周期。Todo 管交付物、验收、依赖和 lease; +决策管任务内当前方法、尺子选择与下一次证据边界;具体工具调用由宿主承载。 + +默认一句短提示,指出当前值得判断的不确定性;确实有歧义时才补第二句。 +这是呈现偏好,不是 token 硬上限、强制四字段表格或操作顺序。没有实质变化时不重复提示。例如: + +> 局部指标变好了,但整体收益未确认;先判断这把尺子是否值得继续用。 + +模型自主决定怎么调查、在范围内做多少、保留还是替换方法。不规定工具顺序、候选数量、 +完整 checklist 或固定计划。持久化决策可以包含理由、证据和复盘边界, +这些按需可查,不必全部塞进提示。Opaque identity/revision 由现有 host/context owner 携带。 +完整约束和引用材料仍通过原 owner 可用;不能因缩短提示,从整体任务输入中丢掉新相关约束或反证。 +Controller/Executor host 复用既有自然语言工作交互,单 Agent host 使用当前 task context。 +不需要部署第二个 controller 模型,也不等待 controller composition PR。 + +| 边界 | 如何交付决策 | 不应发生的事 | +| --- | --- | --- | +| 同一工作 Turn 中反馈到达 | 模型工作时修正局部 probe,有意义的决策随普通写回提交。 | 每个工具结果后再插一次 guard/模型调用。 | +| 同任务下一普通 Turn | 在既有任务旁投影变化的短提示,证据和前次采用按需可查。 | 仅为运送提示创建 Todo/Step,或重复无变化建议。 | +| 真有新交付物、依赖或验收边界 | 正常 Todo authoring,首个工作输入可引用适用决策。 | 把过期决策复制到随意的 task note,或带到无关工作。 | + +提示是显式、可修正的任务内建议,不高于新用户指令、验收或新反证。 +Agent 可以执行、修正,或在现有回复中说明已不适用;不新增 ACK 调用或强制表格。 +仅在上下文连续性成立时复用无变化的适用决策,否则按既有恢复契约重新交付当前投影。 + +Prompt 交付不能保证模型执行。到下一次有意义的证据边界,检查实际调用、候选/产物身份和测量, +区分**送达、采用、获益**。若它仍在无依据地扫参数,记录未采用和剩余差距; +不能因为计划中出现过 probe 就说做过。反复未采用可成为现有停滞/replan 的证据, +不能强迫模型无限复述同一句话。硬约束只保留真实范围、身份、预算和验收。 +“采用”指处理了相关判断问题,不是照抄建议的工具序列;自主发现更好方案不算不服从。 +C13 和 A–D 实验需要证明短提示有帮助,同时不压缩模型能力。 +复用已有产物/测量证据,不要求新增逐工具 tracing,也不每 Turn 重读整条轨迹。 + +## 6. 替代方案与设计选择 + +| 方案 | 选择 / 取舍 | +| --- | --- | +| Stride、Yardstick 各一个 planner | 首版不采用:两次复盘可能对哪个方向值得测产生冲突。保留专业 fidelity 计算,共享研究判断。 | +| 每 Turn 完整 replan | 不采用:伪造义务、扩大上下文、造成无必要工作图变化。 | +| 一个标量 action 或 utility | 不采用:混淆方向价值、尺子可靠性和工作形状,掩盖不确定性及不同成本单位。 | +| 固定方向,只校准尺子 | 不充分:可能把整个 horizon 用来修一个不划算方向的尺子。 | +| 始终真实评测 | 保留为对照/回退;评测便宜或剩余 horizon 很短时尤其合理。造尺子并无必然收益。 | +| 每次 writeback 强制填表 | 不采用:无变化工作无需重复解释;语义共享不要求最大 payload。 | +| 每次决策变 Todo、Step 或下个 Todo note | 不作为传输方式:方法/probe 已有决策 owner,投影到当前工作输入即可;任务只随真实工作边界创建。 | +| post-writeback 中调模型 planning | 不采用:主提交后引入隐含成本和失败,放在下一次已准入工作回复里。 | + +## 7. 安全、隐私与兼容 + +新增行为通过现有配置 owner 显式启用,保留独立的原 Stride 配置。 +关闭时不加 prompt 指引、模型/工具调用、决策义务,也不改变普通结算。 +历史扩展记录仍可读取,但不作为当前权威。Shadow 实验不能把建议送给基线执行模型; +使用隔离 replay,否则把“看到了建议”列为 treatment。 + +组合选择不允许访问隐藏测试、修改协议/cooldown、替换 scorer 或重标结果。 +Provider 只暴露授权证据。原始任务、trace、凭据、私有 evaluator 数据留在 runtime 边界; +公共文档/fixture 使用合成例子。失败对照、未知成本保留。直接评测同样受可用性、成本、 +权限限制;不能执行时报告证据缺口。 + +保留 `stride_decision_v2` 的 reader、writer 和到期校验,不能把必需 replan identity 变为 nullable。 +新附件通过原版本处理协商支持;旧 writer 不得擦除新记录或静默降级启用的 treatment。 +不支持的启用返回可操作的 typed result;feature-off 工作保留旧路径。 + +## 8. 迁移与回滚 + +先刻画既有 replan/off 行为和普通 attachment 路径,不切默认值地实现共享语义。 +在隔离 Goal/profile 中启用,绑定当前任务和 measurement profile,初始 fidelity 未知; +不自动验证历史 proxy 声明。扩大使用前回读精确决策和首次实际采用工作。 + +在已结算边界关闭;保留测量/决策,用原身份完成 pending attachment delivery。 +关闭不会取消健康任务或抹除到期 replan。降级 binary 前确认无 pending 新 schema 写入; +否则用支持版本完成恢复,或保留原 receipt 暂停受影响的写入。 +本提案不包含破坏性转换或 journal 改写。 + +## 9. 验证与验收 + +### 9.1 语义场景 + +这些是实现验收要求,不是已经通过的测试。 + +| ID | 场景 | 必须看到的结果 | +| --- | --- | --- | +| C1 | 普通 Turn 无新证据 | 原 task/lease/settlement;无新模型/工具调用或决策事件;不制造 replan。 | +| C2 | 局部代理大幅提升,但 target 成本占比很小 | 比较整体 headroom 和替代方向;不从局部分数推断整体已验收收益。 | +| C3 | 高收益方向没有便宜可靠尺子 | 构造有界,允许收窄/换方向/直接评测;不空转或无限重建。 | +| C4 | 代理排序与适用真实结果冲突 | 按 profile suspect/invalidate;保护 incumbent;保留失败版本和确认成本。 | +| C5 | 样本少、噪声大、并列或缺证据 | 未知/untested,而非 validated 或已否定;传输失败与科学证据分开。 | +| C6 | target 内改候选,对比改变 workload/oracle | 前者可积累 fidelity 证据,后者需新适用范围判断;不能凭名字转移资格。 | +| C7 | 换方向后旧真实结果才到达 | 归原 candidate/pair;当前决策只能经显式授权判断改变。 | +| C8 | 主提交成功、证据关联前崩溃 | 原身份修复;不重复实验、不重复扣额。 | +| C9 | 局部检查与完整 replan 同时到期 | 合并判断一次,保留所有既有义务。 | +| C10 | 局部机制变化,对比跨范围/权限扩展 | 范围内 probe 留在原任务;更大变化走原 authoring/authority;无隐含授权。 | +| C11 | 过期/外部 refs、部分 context、并发 writer、混合 schema | 拒绝不支持身份/effect;恢复有来源绑定的细节,不冒充读过省略证据。 | +| C12 | Treatment off、旧配置、关闭再开启 | 保留既有行为/历史;不加默认、prompt、必需字段或调度效果。 | +| C13 | 提示指出排序疑问,模型忽略、找到更好方法或收到相反用户指令 | 产物区分交付与解决问题;允许改进方案及有据修正。比较短提示/无提示的有效行动和开销,不强制工具脚本。 | + +若涉及持久化,用合成证据在真实 File/SQLite owner 上重放 typed 场景。 +首次采用要覆盖实际 host/CLI settlement 和 packaged readback;schema 单测不足以验收。 + +### 9.2 效果与成本研究 + +分阶段比较,不立即展开全部组合: + +| 实验臂 | Treatment / 问题 | +| --- | --- | +| A | 当前 Stride,仅在既有 replan 边界。 | +| B | A+轻量普通 Turn 决策,无 proxy 机制:及时局部判断是否有用? | +| C | B+固定 target 的 fidelity-aware yardstick:校准增加什么收益? | +| D | C+target/yardstick 联合选择:co-discovery 是否值得切换和构造成本? | + +先从相同保存状态做聚焦 decision episode,再做不同 workload、重复 seed 的整任务。 +冻结模型、可用工具、反馈/验收协议、起始产物、任务预算、停止规则和资源争用策略。 +同时比较等完整成本及随墙钟时间的得分;同 token 上限不等于同成本。 +C/D 共享初始 target 和候选信息,方向自由度是有意 treatment。 +补跑后仍可追踪实验臂和原结果,包含有效零分与 Agent 故障。 + +主指标是权威验收结果对**完整成本**的关系、首个已验收收益时间,给出配对不确定性和 +成本/效果前沿。辅指标包括 control tokens/调用/耗时、造尺子/修尺子占比、 +每次已验收收益需要的真实评测数、组合寿命、无据推广、不必要切换和放弃的有用工作。 +决策→采用→有用信息→真实收益分别列出;决策多、代理分高不算成功。 + +确认性实验前注册 task split、重复数、非劣界限、成本/延迟预算和停止/分析规则, +不看过有利 case 后再选阈值。推广需语义合格、无权限/协议回归,以及可重复证据: +同成本下更好验收结果,或同结果下更低完整成本。保留不确定/负结果; +论文收益和合成 replay 成功都不能替 LoopX 通过资格验证。 + +## 10. 运维契约 + +CLI、App、Lark 复用同一投影:当前方向、尺子或直接评测、fidelity/不确定性、 +最近真实结果、下一行动原因、到下个边界的成本及是否有完整 review 到期。 +细节按需,不让用户学习决策 schema。启用/关闭和版本不支持反馈复用现有配置编辑器。 + +保留精简当前投影、不可变证据引用和明确的省略数量/详情入口。 +测量总读源工作、返回 context、写入和耗时;短 JSON 不代表后端成本有界。 +已知所需引用时直接批量读取,当前组合已有引用就不再多走发现/读取往返。 +可选测量不可用时,继续当前仍有合法依据的任务路径,utility 保持未知; +权限来源不可用仍由原 fail-closed owner 处理。证据故障不允许伪造研究进展。 + +## 11. 规范交付计划 + +| 里程碑 | 有用切片 | 入口 / 出口证据 | 回滚 | +| --- | --- | --- | --- | +| M1 | 一个 typed proposal owner,兼容 replan,支持 opt-in 普通 Turn 附件和最小工作提示 | 批准 binding/version 接缝;C1/C8–C13;源码/打包后同 Turn 回读;不改默认。 | 关闭新行为,保留记录,结清 pending attachment。 | +| M2 | 一个真实数值 target/yardstick profile、有界 context,两个调用方都能联合判断 | M1;C2–C7;完整构造/搜索/确认成本;真实采用 probe 和准确 CLI/App/Lark 回读。 | 直接授权评测或原工作路径;保留失败证据。 | +| M3 | 配对 episode 再整任务效果/成本验证 | C1–C13、预注册 A–D 研究;真实采用、负例、不确定性和完整成本。 | 保持 opt-in,拒绝或修改无证据策略。 | + +M1/M2 是交付切片,不代表长程收益。复用既有 Stride/Explore owner 和下游调用方, +采用后移除原型重复实现;不为凑齐里程碑加入 registry、第二个 journal 或假想 provider 抽象。 + +## 12. 待决事项 + +| 决策 | Owner / 建议 | 需要的证据 / 截止边界 | +| --- | --- | --- | +| 精确附件 schema 和配置字段 | Work-items/cadence maintainer:追加 tagged work/replan binding,独立 opt-in,保留 v2。 | M1 实现前核对 producer/reader 及 C8–C12。 | +| 首个 fidelity profile/证据下限 | Measurement provider maintainer:先用于数值任务的排序 profile,不全局规定六状态。 | M2 前核对噪声、选择/重复检验风险及可负担真实确认。 | +| 自动触发与 context 预算 | Stride/context maintainer:typed evidence delta 和 probe 到边界,不用 prose classifier 或每轮固定表格。 | M1/M2 实测完整路径开销和漏决策反例;M3 前固定阈值。 | +| 默认推广 | Product owner:有配对证据前保持关闭。 | M3,包含回归、不确定性和实际用户流程。 | + +## 附录 A:证据登记与局限 + +| 证据 | 来源 | 支持内容 / 边界 | +| --- | --- | --- | +| E1 | [DuoDiscover v1](https://arxiv.org/html/2610.17184v1),§§2.2–2.4;附录 A.1、E.1、F.1–F.5 | 联合搜索、排序 fidelity、按 target 的消融和失败行为;作者报告,本地未独立复现。 | +| E2 | 第 4 节基线源码;[Stride §7.6](hierarchical-agent-stride-control-v0.md#76-research-scope-and-evidence-conditioned-control) | 当前 replan 身份、轴和 followthrough 接缝;源码核对,不是本机/新能力验收。 | +| E3 | [研究测量模型](long-horizon-harness-benchmark-research-program-v0.md#6-measurement-model) | 公用效果/成本/采用比较归属;本 RFC 添加有界 treatment 矩阵。 | +| E4 | C1–C13 场景 | 可证伪验收要求;实现前尚未执行。 | + +论文中回退的有利观测不代表无后悔保证:失败造尺子已经消耗预算。 +每 target 与每 task 的通过率单位不同;候选选择和重复 fidelity 检验限制统计解释。 +这些边界要求完整成本及权威确认,不是否定 co-discovery。 +目前没有实现决策日志;本提案建议不等于 maintainer 批准。