Skip to content

Commit d5d1a7e

Browse files
committed
docs(planning): document default visibility and qualified input cost
Signed-off-by: huangruiteng <huangrt01@163.com>
1 parent 02311d2 commit d5d1a7e

7 files changed

Lines changed: 98 additions & 26 deletions

File tree

‎benchmark/edgebench/README.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -473,20 +473,21 @@ other replan reasons may trigger sooner. Both runtime and worker-profile receipt
473473
record the resolved cadence. Only newly launched attempts use the new default;
474474
keep existing runs and archived settings pinned.
475475

476-
### Optional Goal in the planning horizon
476+
### Default Goal context and advanced opt-out
477477

478-
For `heartbeat-resume` and `heartbeat-explore`, add `--planning-horizon-goal`
479-
to include the full same-source original Goal and acceptance in preselection
480-
planning context. `--no-planning-horizon-goal` explicitly disables it. Omission
481-
retains the ordinary disabled treatment. Plain and native-Goal workers reject
478+
New `heartbeat-resume` and `heartbeat-explore` trials include the same-source
479+
original Goal and acceptance in preselection planning context by default.
480+
`--no-planning-horizon-goal` disables it for rollback or comparison;
481+
`--planning-horizon-goal` explicitly enables it. Plain and native-Goal workers reject
482482
this setting. It does not enable stride, Explore or TurnEnvelope.
483483

484484
The adapter writes the shared `execution_profile.planning_horizon_goal` through
485485
`configure-goal`, checks the effective readback before work, and records an
486-
explicit setting in both worker profile and runtime receipt. Restore follows
487-
the same path: an explicit true/false overrides the donor setting. An omitted
488-
setting encountering an enabled donor fails the readback instead of silently
489-
labeling the run off. Historical receipts without this field remain absent;
486+
resolved boolean in both worker profile and runtime receipt, including when
487+
the command-line option is omitted. Restore follows the same path: the new
488+
attempt's resolved setting overrides the donor setting and must read back as
489+
that exact boolean before work. To preserve an older off treatment, explicitly
490+
pass `--no-planning-horizon-goal`. Historical receipts without this field remain absent;
490491
report export rejects mismatched or malformed settings.
491492

492493
Compare on/off from the same qualified pre-replan checkpoint with equal remaining

‎docs/architecture/rfcs/goal-outcome-refinement-v0.md‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,7 @@ threshold, forced Todo closure or periodic audit is introduced.
304304

305305
The replan source codec previously omitted default outcomes and retained only
306306
seven configured-check summary fields. Ordinary work context already carried
307-
the complete acceptance readback; the dedicated replan `core_goal` and optional
307+
the complete acceptance readback; the dedicated replan `core_goal` and
308308
Goal planning horizon did not. Both now reuse that same owner-projected readback,
309309
including cumulative requirements, self-review provenance, linked work, check
310310
results and lifetime/freshness facts. This removes a lossy parallel field list;
@@ -345,8 +345,39 @@ continuation observer qualifies only the complete old-to-new wording once with
345345
224 characters/bytes, no added lines or shapes. Missing clauses, an upgraded
346346
baseline, other carriers and excess growth retain ordinary rejection. The two
347347
host fixtures' guidance costs 1,984 bytes instead of 1,772, so their scoped
348-
advice ceiling becomes 2,000 instead of 1,800. The 8 KiB envelope warning and
349-
absolute CLI/runtime budgets are unchanged; this is a measured input cost.
348+
advice ceiling becomes 2,000 instead of 1,800. That guidance-only change retains
349+
the absolute CLI/runtime budgets; this is a measured input cost.
350+
351+
### Goal context before work selection
352+
353+
The original Goal and recorded acceptance now enter applicable preselection
354+
horizons by default. This is a context change, not another planning round or a
355+
new scheduling rule. The five-work-item summary and explicit completeness/detail
356+
paths remain bounded; seeing the Goal does not make that summary exhaustive.
357+
Flat runnable backlogs also receive the bounded work view. Missing declared
358+
dependencies or gaps do not establish sound ordering; they must not hide that
359+
view. The summary reports omissions and a complete-read route, not a claim that
360+
its five items are the whole plan. TurnEnvelope references identical selected
361+
work text when the reference is smaller, retaining other work and completeness.
362+
The existing configuration owner retains an explicit false for rollback and
363+
comparisons. Settings moves this control into Advanced settings, preserves
364+
machine/Goal precedence and sparse inherited values, and does not rewrite
365+
persisted configurations on read. EdgeBench heartbeat workers pin and record
366+
the resolved boolean before work, including for omitted CLI options; existing
367+
receipts remain historical. TurnEnvelope references an identical inline
368+
acceptance source instead of repeating its body, retaining mismatched evidence.
369+
Source/default qualification remains separate from installed/model adoption.
370+
371+
Matched public fixtures measure 8,077 → 9,370 characters for small Turn plan and
372+
20,805 → 23,745 for multi-Agent quota JSON. The latter initially exceeds the
373+
23,000-character ceiling and existing horizon migration's 2,800 compact growth
374+
allowance. The increase includes Goal context and a previously absent bounded
375+
work summary; discarding the latter would hide useful flat-backlog context.
376+
Retain it and change only that absolute ceiling to 24,000 and the one-time
377+
horizon migration's compact allowance to 3,000. Excess and same-schema growth
378+
remain rejected; other ceilings, per-Todo growth and the 8 KiB envelope warning
379+
are unchanged.
380+
This qualifies the input-cost tradeoff, not token, latency or model-quality gains.
350381

351382
## Decisive acceptance
352383

‎docs/architecture/rfcs/goal-outcome-refinement-v0.zh-CN.md‎

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ worker owner 负责,本基础切片不交付此行为。使用该 worker 的
228228
分数阈值、强制 Todo 关闭或定期审计。
229229

230230
此前 replan 来源适配会丢弃默认成果,仅保留已配置检查的七项摘要字段。普通工作
231-
上下文已有完整验收读取,专门的 replan `core_goal` 与可选 Goal 规划视野却没有。
231+
上下文已有完整验收读取,专门的 replan `core_goal` 与 Goal 规划视野却没有。
232232
现在两者复用同一 owner 投影的完整读取,保留累计要求、自查来源、关联工作、
233233
检查结果及生命周期/新鲜度事实,移除一份有损字段清单。Python 只传输来源,
234234
既有 TypeScript owner 继续决策,不新增能力、provider、持久词汇或 UI 操作。
@@ -258,7 +258,29 @@ provider 所有,本改动不开放隐藏反馈。
258258
观察器只对完整旧文案到新文案的一次转换给予 224 字符/字节额度,不增加行数或
259259
结构额度;缺失条款、已升级基线、其他载体或超额增长仍拒绝。两个 Host 夹具的
260260
引导从 1,772 增至 1,984 字节,对应局部文案上限从 1,800 调为 2,000。
261-
8 KiB envelope 警告与 CLI/运行绝对预算不变;这是实测输入成本。
261+
上述仅引导文案变更保留 CLI/运行绝对预算;这是实测输入成本。
262+
263+
### 选择工作前的 Goal 上下文
264+
265+
原始 Goal 与已登记验收现在默认进入适用的选工作前规划视野。这是上下文变化,
266+
不增加规划轮次或调度规则。五项工作摘要及明确的完整性/详情入口保持有界;
267+
看到 Goal 不代表摘要覆盖全部工作。既有配置 owner 保留显式 false 用于回滚与
268+
对照。平铺的可执行任务同样展示有界工作视野;没有登记依赖或缺口,不能证明排序
269+
合理,也不能据此隐藏该视野。摘要标明遗漏与完整读取入口,不把五项任务当成全部
270+
计划。TurnEnvelope 在引用更短时引用同包中完全相同的已选工作正文,保留其他工作
271+
及完整性说明。设置页把该选项移入高级设置,保留机器/Goal 优先级和稀疏继承值,读取
272+
不重写持久配置。EdgeBench heartbeat worker 在工作前固定并记录解析后的布尔值,
273+
包括省略 CLI 选项的情况;历史回执保持原样。TurnEnvelope 引用已有且完全相同
274+
的内联验收来源,避免重复正文;内容不一致时保留各自证据。
275+
源码/默认行为验证与已安装版本/模型采用仍需分别验证。
276+
277+
同一公开夹具中,small Turn plan 从 8,077 增至 9,370 字符,多 Agent quota JSON
278+
从 20,805 增至 23,745。后者起初超过 23,000 字符上限及既有 horizon 迁移的
279+
2,800 紧凑字符增长额度。增加部分包含 Goal 上下文及原本未展示的有界工作摘要;
280+
舍弃后者会隐藏有价值的平铺任务上下文。保留这些内容,仅将该绝对上限调为 24,000,
281+
一次性 horizon 迁移的紧凑额度调为 3,000;超额和同 schema 持续增长仍拒绝。
282+
其他上限、每 Todo 增长及 8 KiB envelope 警告不变。
283+
这验证输入成本取舍,不证明 token、延迟或模型质量收益。
262284

263285
## 决定性验收
264286

44.2 KB
Loading
105 KB
Loading

‎docs/reference/protocols/quota-planning-horizon-v0.md‎

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,14 @@
33
`quota_planning_horizon_v0` is the bounded, read-only context that lets an
44
agent reason beyond one locally selected Todo without inlining LoopX's full
55
Todo store or task graph. It is present on the default `quota should-run` path
6-
when a planning choice has strategic context. The optional `planning_horizon_goal`
7-
setting is **off by default**. When enabled it carries the current `core_goal`
6+
when a planning choice has strategic context. The `planning_horizon_goal`
7+
setting is **on by default**. It carries the current `core_goal`
88
before work selection, including for a single local Todo or flat backlog.
9-
When disabled, the existing strategic-context condition and projection are
10-
unchanged. Flat runnable alternatives remain owned by `action_portfolio`.
9+
The bounded work summary remains visible for a flat runnable backlog: missing
10+
declared dependencies or gaps do not establish that work ordering is sound.
11+
Completeness and detail references make omitted work explicit. Action selection
12+
still belongs to `action_portfolio`. When disabled, the previous
13+
strategic-context condition and projection are unchanged.
1114

1215
The problem it addresses is narrower than scheduling. A selected regression
1316
gate can be locally runnable while the strategic path also contains a facts
@@ -46,23 +49,28 @@ available, `core_goal.read_action` reads the same complete Goal state, with the
4649
source path shell-quoted. A corrected source is read on the next planning
4750
projection; no copied objective needs synchronization.
4851

49-
This extends planning context only after explicit opt-in. Existing Todo selection,
52+
This changes the default preselection context, including single-Todo and flat
53+
backlog cases; an explicit false retains the previous projection and skips the
54+
extra Goal-document read. Existing Todo selection,
5055
claim/lease, admission, replan precedence and settlement authority remain
5156
unchanged. Goal text is scoped decision input; public export remains a separate
5257
boundary. The complete original objective is not shortened to the Todo display
5358
budget. Transport-size warnings remain visible rather than discarding its tail.
5459

55-
## Enable, Read Back And Disable
60+
## Default, Read Back And Advanced Opt-Out
5661

5762
The existing **Goal review and stride** capability editor in Settings →
58-
Capabilities exposes **Show Goal in planning horizon** at machine and Goal scope.
63+
Capabilities → **Advanced settings** exposes **Show Goal in planning horizon**
64+
at machine and Goal scope. Ordinary use requires no configuration step.
5965
Use its preview, apply and readback flow. Its optional boolean is stored in the
6066
existing `execution_profile.planning_horizon_goal`; no new capability or Goal
6167
store is introduced. The v2 machine review configuration accepts the same
62-
optional boolean; omission preserves its previous shape and disabled default.
68+
optional boolean; omission preserves its stored shape and now resolves to on.
6369
As with stride, a Goal with an explicit review cadence uses its own configuration;
6470
a sparse Goal switch inherits the live interval. An explicit false overrides a
65-
machine opt-in. Clearing a Goal override restores the applicable inherited value.
71+
machine value. Clearing a Goal override restores the applicable inherited value.
72+
The form shows effective values without pinning an unchanged inherited horizon
73+
when another field is saved. Explicit JSON true/false remains an override.
6674

6775
```sh
6876
loopx configure-goal --goal-id example --execution-planning-horizon-goal --execute
@@ -71,8 +79,8 @@ loopx quota should-run --goal-id example --agent-id researcher --format json
7179
loopx configure-goal --goal-id example --no-execution-planning-horizon-goal --execute
7280
```
7381

74-
The quota readback contains `planning_horizon.core_goal` only when this projection
75-
is enabled and a preselection planning projection is applicable. It is not added
82+
The quota readback contains `planning_horizon.core_goal` when this projection
83+
is enabled (the default) and a preselection planning projection is applicable. It is not added
7684
to receipt-bound replays or ineligible work merely to repeat the Goal. Disabling
7785
skips the extra Goal-document read. Replan continues to read its existing Goal
7886
context independently. TurnEnvelope, stride, execution permission and quota are
@@ -210,6 +218,14 @@ may replace the repeated `detail_refs` object with
210218
`detail_refs_ref="$.detail_ref"`. The Turn envelope's top-level cold path then
211219
owns those reads. This is transport compaction only: it does not change the
212220
TypeScript reducer output, completeness accounting, or action authority.
221+
If the exact same acceptance contract is already inline in
222+
`work_context.sources`, `core_goal.acceptance_contract_ref` points to that source
223+
instead of repeating its body. The referenced content remains signed. Different
224+
scopes/revisions and unavailable sources retain the full inline contract.
225+
For the Goal-bearing horizon, an identical selected-work description may use
226+
`text_ref` to the envelope's selected Todo text or recommended action when
227+
that reference is smaller. Other work, completeness and mismatched text stay
228+
inline; the reference target remains covered by the action signature.
213229

214230
## Relation Semantics
215231

@@ -253,7 +269,8 @@ A conforming implementation must prove:
253269
- portfolio, horizon, and agent-Todo detail consume the same typed inventory;
254270
- task graph consumes the same canonical Todo selector, plus terminal evidence
255271
rows, without acquiring agent-scoped selection or claim authority;
256-
- omitted/false settings retain the prior horizon and skip extra Goal reads;
272+
- omitted settings expose the original Goal; explicit false retains the prior
273+
horizon and skips extra Goal reads;
257274
- when enabled, the same current Goal reaches preselection horizon and replan, with original
258275
trailing constraints and source readback intact;
259276
- missing, corrected and fallback sources stay explicit; scoped acceptance and

‎skills/loopx-self-repair/references/repair-patterns.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ teaches a reusable control-plane lesson.
55

66
| Pattern | Symptoms | Evidence To Read | Likely Root | Durable Repair |
77
| --- | --- | --- | --- | --- |
8+
| `planning_visibility_requires_declared_complexity` | A flat runnable backlog hides the Goal or broader work view because no dependency, blocked work or acceptance gap has been registered. | Same-source default/opt-out planning packets, original Goal, bounded work summary, omission counts and full-read routes. | A supplemental-context condition is mistaken for evidence that no strategic planning is needed; byte reduction removes useful visibility. | Show Goal and bounded work context by default at applicable preselection boundaries, including flat backlogs. Preserve omission counts, complete-read routes and action authority. Reduce exact duplication instead of hiding work; qualify input-cost changes with matched fixtures and keep model benefit unproven until measured. |
89
| `history_artifact_observation_failure` | History or status readback fails with `ENAMETOOLONG`, permission denial or an I/O error while checking a recorded artifact path. | Synthetic index row, failing filesystem observation, retained Run evidence, index digest and next-read recovery. | A derived artifact availability lookup propagates an OS error and hides otherwise readable durable history on older Python versions. | Isolate filesystem lookup errors in the shared artifact observer; report availability as unconfirmed through the existing false flag, retain Run evidence and retry on the next read. Do not suppress errors reading the index itself or rewrite evidence. Cover real history/status CLI readback with File and SQLite fixtures. |
910
| `status_cache_decode_failure` | Opt-in cached status or quota readback fails with a UTF-8 decoding error while live collection works. | Cache miss metadata and a disposable malformed-cache reproduction through both CLI consumers. | The shared cache reader handles JSON and filesystem errors but lets text decoding abort live fallback. | Classify invalid UTF-8 as an unreadable cache miss in the existing IO owner; preserve damaged bytes on reads, collect live facts, and rewrite only with the explicit cache-write option. Test current Todo selection and successful reuse after repair; never suppress canonical source failures. |
1011
| `lock_holder_decode_hides_timeout` | Lock diagnostics or a contended acquisition raises `UnicodeDecodeError` instead of reporting unreadable metadata or the typed timeout. | Synthetic damaged holder bytes, liveness readback, and a real held-lock timeout followed by normal reacquisition. | Holder text decoding fails before the JSON/error guard, masking advisory failure and incident recording. | Treat invalid UTF-8 as unreadable at the shared holder reader; retain valid alternate records and kernel ownership. Cover the incident, inspection guidance and recovery after the actual holder exits; never delete the lock as repair. |

0 commit comments

Comments
 (0)