docs: clarify survey evidence and proposal cleanup steps
This commit is contained in:
Tianyi Cui committed
1 parent
cf75d1d099
commit
4ffc8c7bef
10 files changed
+21
-21
No files matched your search
+2
-2
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-09-19-evidence-led-simplification-surveys.md
|
||||
2026-09-19-evidence-led-simplification-surveys.md: 412b4592ce8c6c2db5d586335cf59a2633d93c0f
|
||||
2026-09-19-evidence-led-simplification-surveys.zh.md: a84a5510c03468bc65e90a6be984997b621a2fe4
|
||||
2026-09-19-evidence-led-simplification-surveys.md: c217f80239690ee2f7310ca8e97956ec06fb75c7
|
||||
2026-09-19-evidence-led-simplification-surveys.zh.md: 1b1a11731967c87ab54aa9eba82253f90bb2abde
|
||||
@@ -14,13 +14,13 @@ The [simplification skill](../../../skills/dsh-find-simplifications/SKILL.md) tr
|
||||
|
||||
Production use changes the required trade-off evidence; it does not automatically veto a proposal or authorize implementation. Dynamic plugin discovery, installed consumers, generated runtime assets, profiles, applications, and Python participate in consumer tracing. Protected adapters and persistence designs, released data, trust boundaries, independent invariant observations, synchronous publication, cancellation, and quiescent disposal remain constraints.
|
||||
|
||||
The entry point is 1,372 whitespace-delimited words versus 2,222 previously. An [optional 897-word reference](../../../skills/dsh-find-simplifications/references/historical-patterns.md) pairs historical mechanisms with counterexamples and residual obligations. Archive mechanics remain at their existing owner, and the proposal skeleton uses the canonical headings.
|
||||
The entry point separates decision criteria from an [optional historical reference](../../../skills/dsh-find-simplifications/references/historical-patterns.md) pairing mechanisms with counterexamples and residual obligations. Archive mechanics remain at their existing owner, and the proposal skeleton uses the canonical headings.
|
||||
|
||||
## Historical evidence
|
||||
|
||||
The author sampled 26 of the 100 English implemented or archived simplification notes: 11 implemented and 15 archived. All nine rejected simplification notes supplied counterexamples. The sample covers producerless variants, inert request knobs, explicit inputs, public projections, derived data, shared composition, lifecycle ownership, and dependency replacements; it is purposeful, not random or exhaustive.
|
||||
|
||||
The reference teaches questions rather than current deletion recipes. An adapter-rejected knob differs from a working extension API; a simpler public status can retain internal residency distinctions; reading at feedback time changes the observation promise; replacing a dependency can lose deterministic clocks or necessary teardown. Archived records were read without following or repairing outbound links. No old note was edited, archived, or deleted.
|
||||
The frozen comparison inputs contained 2,222 whitespace-delimited words in the baseline entry, 1,372 in the revised entry, and 897 in its reference; the hashes below identify those measured artifacts. The reference teaches questions rather than current deletion instructions. An adapter-rejected knob differs from a working extension API; a simpler public status can retain internal residency distinctions; reading at feedback time changes the observation promise; replacing a dependency can lose deterministic clocks or necessary teardown. Archived records were read without following or repairing outbound links. No old note was edited, archived, or deleted.
|
||||
|
||||
## Bounded survey evidence
|
||||
|
||||
@@ -30,7 +30,7 @@ A third matched domain, covering `llm`, `compaction`, `context`, `skill`, and `e
|
||||
|
||||
The skill author derived the revision from historical notes while isolated from current candidates. The coordinator received accidental early baseline hints, but accepted the independent author's revision unchanged before revised runs. Candidate packets hid arm labels from a separate reviewer; the coordinator's integration was not blind. The frozen inputs had SHA-256 values `9830af2272a1a1c3832078f31a432c8abe0335a013bc6c248c072b388520e798` for the baseline entry, `3b101d16ae098855c9214ad7fed631a2f079b6078c83b49829ae87305f631a87` for the revised entry, and `9a6b674d1eeadb691481ea09838b211b8e94c94e5a8cd928726246b1c097b2b5` for its reference.
|
||||
|
||||
Each prompt requested exact source/search evidence, producer and consumer classification, note overlap, net reduction, the strongest counterargument, and acceptance requirements. Review applied those same criteria to every submission, distinguished local edits from durable decisions, and did not treat either public discoverability or a line-deletion count as a verdict by itself.
|
||||
After these runs, review replaced only the skill phrase “earns its place” with “is justified”; no discovery criterion changed and no new discovery run was performed. Each prompt requested exact source/search evidence, producer and consumer classification, note overlap, net reduction, the strongest counterargument, and acceptance requirements. Review applied those same criteria to every submission, distinguished local edits from durable decisions, and did not treat either public discoverability or a line-deletion count as a verdict by itself.
|
||||
|
||||
| Version | Domain | Cap | Submitted | Durable as submitted | Durable after refinement | Local | Deferred | Elapsed |
|
||||
|---|---|---|---:|---:|---:|---:|---:|---|
|
||||
@@ -45,7 +45,7 @@ The baseline yields six durable proposals as submitted and two after refinement.
|
||||
|
||||
Review narrowed the [query API proposal](../../proposed/simplification/2026-09-19-trim-session-query-convenience-api.md) to retain `filterEvents`, whose literal substring behavior differs from FTS. The [prompt-event proposal](../../proposed/simplification/2026-09-19-retire-prompt-registry-change-event.md) explicitly retires an active extension promise instead of claiming per-step assembly makes notifications redundant. Both refined baseline findings remain useful and are retained.
|
||||
|
||||
Three revised-only local follow-ups receive no standalone Agent Notes: [SessionCorpus](../../../../packages/session-query/session-query/src/corpus.ts) can replace its provider-mirroring child with one scope-aware lookup per operation while retaining that provider across awaits; [fs-local](../../../../packages/fs/fs-local/src/index.ts) can reuse `FsTarget`/`FsDirEntry` and return fresh resolve/list outputs while retaining cancellation and mode-filtering projections; [BlockAssembler](../../../../packages/llm/llm/src/assembler.ts) can use Map insertion order instead of synchronizing a second order array, preserving first-seen and replay order.
|
||||
The three revised-only local findings were a mirrored provider reference, copied filesystem results, and duplicate assembler ordering state. They were counted separately and were not written as active design proposals.
|
||||
|
||||
Review deferred replacing automatic Session-reference sizing with a fixed byte default. The [current budget decision](../bug-fix/2026-09-05-session-reference-model-budget.md) fixes lost useful context on large models; best-effort spill retrieval does not replace inline context. No new workload evidence justified restoring the problematic default. The proposal's deletion inventory was accurate, but that alone did not overcome the current requirement.
|
||||
|
||||
|
||||
+4
-4
@@ -14,13 +14,13 @@ Status: implemented
|
||||
|
||||
生产使用会改变所需的取舍证据，但不会自动否决提案，也不构成实施授权。动态插件发现、已安装消费方、生成的运行时产物、profile、应用和 Python 都纳入消费方追踪。受保护的适配器与持久化设计、已发布数据、信任边界、独立 invariant 观察、同步发布、取消及达到静止状态的释放仍是约束。
|
||||
|
||||
入口按空白分隔为 1,372 词，原版为 2,222 词。[可选的 897 词参考页](../../../skills/dsh-find-simplifications/references/historical-patterns.md) 将历史机制与反例、残留义务配对。归档操作仍由原有归属处负责，提案结构使用规范标题。
|
||||
入口将判断标准与[可选历史参考页](../../../skills/dsh-find-simplifications/references/historical-patterns.md) 分开，后者将机制与反例、残留义务配对。归档操作仍由原有归属处负责，提案结构使用规范标题。
|
||||
|
||||
## 历史证据
|
||||
|
||||
作者从 100 份英文已实现或归档简化记录中抽样 26 份：11 份已实现、15 份归档。全部九份已否决简化记录提供反例。样本涵盖无生产方变体、无效请求开关、显式输入、公共投影、派生数据、共享组合、生命周期所有权和依赖替换；这是有目的的抽样，并非随机或穷尽审查。
|
||||
|
||||
参考页提供问题，而非当前删除配方。所有适配器都拒绝的开关不同于有效扩展 API；更简单的公共状态可以保留内部驻留差别；反馈时读取会改变观察承诺；依赖替换可能丢失确定性时钟或必要的释放行为。阅读归档记录时未追踪或修复其出站链接。没有编辑、归档或删除任何旧记录。
|
||||
冻结的比较输入按空白分隔计数：基线入口为 2,222 词，新版入口为 1,372 词，参考页为 897 词；下方哈希标识这些已测量产物。参考页提供问题，而非当前删除指令。所有适配器都拒绝的开关不同于有效扩展 API；更简单的公共状态可以保留内部驻留差别；反馈时读取会改变观察承诺；依赖替换可能丢失确定性时钟或必要的释放行为。阅读归档记录时未追踪或修复其出站链接。没有编辑、归档或删除任何旧记录。
|
||||
|
||||
## 有界调研证据
|
||||
|
||||
@@ -30,7 +30,7 @@ Status: implemented
|
||||
|
||||
skill 作者与当前候选隔离，根据历史记录撰写修订。协调者意外提前收到少量基线提示，但在新版运行前原样接受独立作者的修订。交给独立审查方的候选材料隐藏了分组标签；协调者整合并非盲审。冻结输入的 SHA-256 为：基线入口 `9830af2272a1a1c3832078f31a432c8abe0335a013bc6c248c072b388520e798`，新版入口 `3b101d16ae098855c9214ad7fed631a2f079b6078c83b49829ae87305f631a87`，新版参考页 `9a6b674d1eeadb691481ea09838b211b8e94c94e5a8cd928726246b1c097b2b5`。
|
||||
|
||||
每份提示都要求精确源码/搜索证据、生产方与消费方分类、记录重叠、净减少量、最强反对理由和验收要求。审查对每个提交项使用相同标准，区分局部编辑与长期决策，既不单凭公共可发现性，也不单凭删除行数作结论。
|
||||
这些运行结束后，评审仅将 skill 中的「earns its place」改为「is justified」；没有改变发现标准，也没有重新运行发现测试。每份提示都要求精确源码/搜索证据、生产方与消费方分类、记录重叠、净减少量、最强反对理由和验收要求。审查对每个提交项使用相同标准，区分局部编辑与长期决策，既不单凭公共可发现性，也不单凭删除行数作结论。
|
||||
|
||||
| 版本 | 领域 | 上限 | 提交数 | 原样可用的长期提案 | 调整后可用的长期提案 | 局部项 | 暂缓 | 耗时 |
|
||||
|---|---|---|---:|---:|---:|---:|---:|---|
|
||||
@@ -45,7 +45,7 @@ skill 作者与当前候选隔离，根据历史记录撰写修订。协调者
|
||||
|
||||
审查缩小了[查询 API 提案](../../proposed/simplification/2026-09-19-trim-session-query-convenience-api.zh.md)，保留其字面子串语义不同于 FTS 的 `filterEvents`。[提示事件提案](../../proposed/simplification/2026-09-19-retire-prompt-registry-change-event.zh.md) 明确撤回当前扩展承诺，而非声称逐步骤组装让通知多余。这两项经调整的基线发现仍有价值，因此保留。
|
||||
|
||||
三个仅新版发现的局部后续项不单独建立 Agent Note：[SessionCorpus](../../../../packages/session-query/session-query/src/corpus.ts) 可用每操作一次的作用域感知查询替代镜像提供方的子实例，同时跨 await 保留所选提供方；[fs-local](../../../../packages/fs/fs-local/src/index.ts) 可复用 `FsTarget`/`FsDirEntry` 并直接返回新建的解析/列表结果，同时保留取消检查和过滤 mode 的投影；[BlockAssembler](../../../../packages/llm/llm/src/assembler.ts) 可用 Map 插入顺序替代同步维护第二个顺序数组，保留首次出现顺序与重放顺序。
|
||||
三个仅新版发现的局部项分别是镜像的提供方引用、复制的文件系统结果，以及重复的组装器顺序状态。它们单独计数，没有写成当前设计提案。
|
||||
|
||||
审查暂缓了将自动 Session 引用大小改为固定字节默认值的提案。[当前预算决策](../bug-fix/2026-09-05-session-reference-model-budget.zh.md) 修复了大模型丢失有用上下文的问题；尽力而为的 spill 检索不能替代内联上下文。没有新的工作负载证据支持恢复有问题的默认值。提案的删除清单准确，但仅此不足以推翻当前要求。
|
||||
|
||||
|
||||
+2
-2
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-09-19-retire-prompt-registry-change-event.md
|
||||
2026-09-19-retire-prompt-registry-change-event.md: 72e74be6445d322a5c41e995a1c262c3113a877c
|
||||
2026-09-19-retire-prompt-registry-change-event.zh.md: 2b9b9bb8aa207b8fdf3256ec9c341ee0b9088326
|
||||
2026-09-19-retire-prompt-registry-change-event.md: 1103675525e30c7f6c345a1fe92f07cbd0bcce4a
|
||||
2026-09-19-retire-prompt-registry-change-event.zh.md: a49df2eebad7134b7b038ee2e6ab54610bd4c635
|
||||
+2
-2
@@ -14,7 +14,7 @@ The active [Remote event delivery decision](../../implemented/architecture/2026-
|
||||
|
||||
Retire `system-prompt/change` and accept the loss of prompt-registry push observation for installed and dynamically authored Host plugins. Remove its declaration, emitter, current documentation, generated discovery entries, and notification-specific tests. No currently supported product path requires this extension.
|
||||
|
||||
Make [`ScopedLayers`](../../../../packages/core/scope/src/store.ts)'s constructor notification callback optional and omit it for `SystemPrompt`; do not supply a no-op callback. Preserve shared effects, action rollback, undo ordering, layer reclamation, and `tools/change` with its production consumers. Keep prompt-provider evaluation, scope shadowing, and assembly invariants.
|
||||
Make [`ScopedLayers`](../../../../packages/core/scope/src/store.ts)'s constructor notification callback optional and omit it for `SystemPrompt`; do not supply a no-op callback. Remove the existing no-op arguments in [jobs-local](../../../../packages/jobs/jobs-local/src/index.ts) and [mcp-resources](../../../../packages/mcp/mcp-resources/src/index.ts) when updating this shared constructor, and update jobs-local's adjacent notification explanation. Preserve shared effects, action rollback, undo ordering, layer reclamation, and `tools/change` with its production consumers. Keep prompt-provider evaluation, scope shadowing, and assembly invariants.
|
||||
|
||||
Implementation must amend the active Remote event delivery note to state that this proposal supersedes only its promise to retain `system-prompt/change`. Remove that event from the retained-extension statement and link the implemented retirement decision. Keep the Remote delivery note active and cross-linked: its forwarding policy and other extensions remain independently useful. Do not rewrite or archive that entire decision.
|
||||
|
||||
@@ -28,7 +28,7 @@ Implementation must amend the active Remote event delivery note to state that th
|
||||
|
||||
- Remove the event from source and current generated inventories, and amend the active retention promise in the implementation change.
|
||||
- Remove notification-count and notification-failure tests; retain provider-membership, disposer, duplicate-registration, shadowing, and HMR coverage. Keep mixed tests' independent assertions.
|
||||
- Run focused scope, tools, and system-prompt tests, loop request-reconstruction coverage, a relevant keyless recording, catalog generation, typecheck, lint, and doc-sync. Prompt/log output remains unchanged.
|
||||
- Run focused scope, tools, system-prompt, jobs-local, and mcp-resources tests, loop request-reconstruction coverage, a relevant keyless recording, catalog generation, typecheck, lint, and doc-sync. Prompt/log output remains unchanged.
|
||||
|
||||
## Risks
|
||||
|
||||
|
||||
+2
-2
@@ -14,7 +14,7 @@ Status: proposed
|
||||
|
||||
停用 `system-prompt/change`，接受已安装及动态编写的 Host 插件失去提示词注册表推送观测的代价。删除其声明、发出点、当前文档、生成的发现条目和通知专属测试。当前受支持的产品路径均不依赖此扩展。
|
||||
|
||||
将 [`ScopedLayers`](../../../../packages/core/scope/src/store.ts) 构造函数的通知回调改为可选，并让 `SystemPrompt` 省略它；不提供无操作回调。保留共享 effect、操作回滚、撤销顺序、层回收，以及 `tools/change` 及其生产消费方。保留提示词提供方求值、作用域覆盖和组装 invariant。
|
||||
将 [`ScopedLayers`](../../../../packages/core/scope/src/store.ts) 构造函数的通知回调改为可选，并让 `SystemPrompt` 省略它；不提供无操作回调。更新此共享构造函数时，同时删除 [jobs-local](../../../../packages/jobs/jobs-local/src/index.ts) 和 [mcp-resources](../../../../packages/mcp/mcp-resources/src/index.ts) 中现有的无操作实参，并更新 jobs-local 相邻的通知说明。保留共享 effect、操作回滚、撤销顺序、层回收，以及 `tools/change` 及其生产消费方。保留提示词提供方求值、作用域覆盖和组装 invariant。
|
||||
|
||||
实现时必须修订活动的 Remote 事件投递记录，说明本提案只取代其中保留 `system-prompt/change` 的承诺。从保留扩展的陈述中移除该事件，并链接到已实现的停用决策。让 Remote 投递记录保持活动并相互链接：其转发策略和其他扩展仍具有独立价值。不要重写或归档整个决策。
|
||||
|
||||
@@ -28,7 +28,7 @@ Status: proposed
|
||||
|
||||
- 从源代码和当前生成目录中删除该事件，并在实现变更中修订活动记录中的保留承诺。
|
||||
- 删除通知次数和通知失败测试；保留提供方成员关系、disposer、重复注册、作用域覆盖及 HMR（热模块替换）覆盖。保留混合测试中的独立断言。
|
||||
- 运行针对作用域、工具和系统提示词的测试、循环请求重建覆盖、相关无密钥录制回放、目录生成、类型检查、lint 和 doc-sync（文档同步门禁）。提示词和日志输出保持不变。
|
||||
- 运行针对作用域、工具、系统提示词、jobs-local 和 mcp-resources 的测试、循环请求重建覆盖、相关无密钥录制回放、目录生成、类型检查、lint 和 doc-sync（文档同步门禁）。提示词和日志输出保持不变。
|
||||
|
||||
## 风险
|
||||
|
||||
|
||||
+2
-2
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-09-19-trim-session-query-convenience-api.md
|
||||
2026-09-19-trim-session-query-convenience-api.md: f89ffe626275b0c19278365bd1928b872184cff1
|
||||
2026-09-19-trim-session-query-convenience-api.zh.md: 652f1dd6acc08a901295c7a696f1e4538658985d
|
||||
2026-09-19-trim-session-query-convenience-api.md: 1a3d558c9be5e16b5e9e84a59a9731b55174114c
|
||||
2026-09-19-trim-session-query-convenience-api.zh.md: 63c3ae309edee8366eae4d5db10cc59f0b72e843
|
||||
+1
-1
@@ -12,7 +12,7 @@ These entry points add replay-validation and result-copying paths, wrappers, pub
|
||||
|
||||
## Proposal
|
||||
|
||||
Remove the four methods, the unreferenced [`SessionLogSnapshot`](../../../../packages/session-query/session-query/src/types.ts) result type, and [`eventRecords`](../../../../packages/session-query/session-query/src/tracing.ts). Remove their imports and current documentation, then regenerate discovery metadata. The selected definitions occupy approximately eighty source lines before import cleanup; no replacement service is needed.
|
||||
Remove the four methods, the unreferenced [`SessionLogSnapshot`](../../../../packages/session-query/session-query/src/types.ts) result type, and [`eventRecords`](../../../../packages/session-query/session-query/src/tracing.ts). Remove their imports and current documentation, including the `SessionLogSnapshot` type-equivalence block and explanatory paragraph in both subsystem pages. Remove its hand-maintained entry in the [type-equivalence manifest](../../../../scripts/type-equiv.manifest.json) and its `LINK_MAP` entry in the [catalog generator](../../../../scripts/gen-cordis-catalog.ts), then regenerate discovery metadata. The selected definitions occupy approximately eighty source lines before import and metadata cleanup; no replacement service is needed.
|
||||
|
||||
Retain `filterEvents` and `_filterEvents`, together with their semantic extraction and filtering helpers. Retain `observeSession`, `readTitleSnapshots`, `readSurface`, `readEvent`, listing, search, and tracing. Preserve shared corpus resolution and its existing ownership and failure behavior.
|
||||
|
||||
|
||||
+1
-1
@@ -12,7 +12,7 @@ Status: proposed
|
||||
|
||||
## 提案
|
||||
|
||||
删除这四个方法、不再被引用的 [`SessionLogSnapshot`](../../../../packages/session-query/session-query/src/types.ts) 结果类型和 [`eventRecords`](../../../../packages/session-query/session-query/src/tracing.ts)。删除相关导入及当前文档，然后重新生成发现元数据。选定定义在清理导入之前约占八十行源代码；无须新增替代服务。
|
||||
删除这四个方法、不再被引用的 [`SessionLogSnapshot`](../../../../packages/session-query/session-query/src/types.ts) 结果类型和 [`eventRecords`](../../../../packages/session-query/session-query/src/tracing.ts)。删除相关导入及当前文档，包括两个子系统页面中的 `SessionLogSnapshot` 类型等价代码块和说明段落。删除[类型等价 manifest](../../../../scripts/type-equiv.manifest.json) 中手工维护的条目，以及[目录生成器](../../../../scripts/gen-cordis-catalog.ts) 中的 `LINK_MAP` 条目，然后重新生成发现元数据。选定定义在清理导入和元数据之前约占八十行源代码；无须新增替代服务。
|
||||
|
||||
保留 `filterEvents` 和 `_filterEvents`，以及语义提取和过滤辅助函数。保留 `observeSession`、`readTitleSnapshots`、`readSurface`、`readEvent`、列举、搜索和追踪。保留共享会话集合解析及其现有所有权和失败行为。
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ For copies, freezes, validators, and callback captures, name the value's origin,
|
||||
|
||||
For asynchronous machinery, map each promise, flag, cancellation path, disposer, and reservation to its owner and transition. Collapse mechanisms only when they express the same fact. Preserve synchronous publication and rollback, callback containment, first-terminal-outcome arbitration, worker/process ownership, and dispose-to-quiescence where required. Durable start/end markers can record real facts even when transcript renderers ignore them; dropping interrupted work is a capability loss, not redundant-log cleanup.
|
||||
|
||||
An invariant companion earns its place by comparing independently produced observations that can diverge. Checks of service presence, plugin metadata, fixed examples, or the same mutation's return value do not qualify. Removing a companion includes its export, build entry, invariant-only compiler references, dependencies, and tests; record the package-specific omission reason in both READMEs. Keep checks comparing independent event producers, durable history, or mutable data.
|
||||
An invariant companion is justified by comparing independently produced observations that can diverge. Checks of service presence, plugin metadata, fixed examples, or the same mutation's return value do not qualify. Removing a companion includes its export, build entry, invariant-only compiler references, dependencies, and tests; record the package-specific omission reason in both READMEs. Keep checks comparing independent event producers, durable history, or mutable data.
|
||||
|
||||
## Replace infrastructure only for a net reduction
|
||||
|
||||
|
||||
Reference in new issue
Block a user