Redesign ACM around working-set judgment

AGENTS.md

@@ -44,14 +44,15 @@
 | `src/checkpoint-tool.ts` | checkpoint schema、target resolution、placement evidence |
 | `src/timeline-tool.ts` | strict single-view timeline、tree rendering、HUD 与 diagnostics |
 | `src/travel-tool.ts` | handoff validation、travel evidence、sync scheduling |
+| `src/tool-receipt.ts` | 所有 ACM tool result 的 matching receipt、intent/fact 分类与 renderer-safe parsing |
 | `src/travel-coordinator.ts` | 单次 backup → branch → verify → compensate transaction |
 | `src/host-bridge.ts` | readonly SessionManager 到公开 mutation/build capability 的唯一 guarded seam |
 | `src/runtime.ts` | 按 SessionManager 隔离 usage、refresh、tool-call correlation、context nudge 与 live sync state |
 | `src/runtime-lifecycle.ts` | context rebuild、hidden nudge delivery、tool end sync、usage、compaction、session cleanup |
 | `src/context-usage-nudge.ts` | 30/50/70 档位分类与分级 ACM reminder 文案 |
 | `src/live-agent-session-adapter.ts` | capability-probed live AgentSession association 与 message replacement |
 | `src/lib.ts` / `label-journal.ts` / `entry-resolution.ts` / `message-sanitizer.ts` | 可测试的 domain logic |
-| `src/generated-guidance.ts` | 从 canonical guidance 派生的 runtime strings |
+| `src/generated-guidance.ts` | 从 `CORE.md` 与 `TOOL-CONTRACTS.md` 派生的 runtime strings |
 | `src/prompt-registration.ts` | idempotent ACM CORE prompt segment |
 
 `src/context.ts` 和 `src/utils.ts` 属于 `/context` TUI，不应吸收 ACM tree mutation 或 live synchronization 逻辑。
@@ -73,7 +74,7 @@ Host Bridge 不保存跨操作的全局 rollback registry。backup rollback proo
 - alias index 由全部 label journal entries 重放，不依赖 host 的单一 latest label view
 - `target: "root"` 指第一个 top-level entry；多根时提示使用明确 checkpoint 或 node ID
 
-不要用 `pi.setLabel()` 替代 journal mutation；它不提供本项目所需的显式 target + 多 alias replay contract。
+不要用 `pi.setLabel()` 替代 journal mutation；它不提供本项目所需的显式 target + 多 alias replay contract。checkpoint result 必须携带 matching receipt：新 label 是 `mutationState=applied`，幂等复用是 `not_applied`，post-mutation 无法验证时是 `indeterminate`；三种状态都保持 `workingSetState=unchanged`。
 
 ## Timeline contract
 
@@ -90,13 +91,13 @@ Host Bridge 不保存跨操作的全局 rollback registry。backup rollback proo
 
 HUD 包含 official/cached usage、active node count、active summary depth、off-path summary count、nearest checkpoint distance、context refresh 与 live AgentSession sync diagnostics。
 
-checkpoint view 额外显示 `root` structural candidate 和每个候选 travel 后的 projected summary depth。这些都是 topology evidence，不是 rebase safety verdict；语义完整性只能由 agent 的 cold-start 检查判断。
+checkpoint view 额外显示 `root` structural candidate 和每个候选 travel 后的 projected summary depth。这些都是 topology evidence，不是 rebase safety verdict；语义完整性只能由 agent 的 cold-start 检查判断。timeline 是 read-only，receipt 固定为 `mutationState=not_applicable`、`workingSetState=unchanged`。
 
 ## Travel transaction
 
 `acm_travel` 的顺序：
 
-1. 解析 target，验证七槽 handoff：`Goal/State/Evidence/External/Exclusions/Recover/NEXT`；rebase snapshot 还必须满足 cold start
+1. 解析 target，验证七槽 handoff：`Goal/State/Evidence/External/Exclusions/Recover/NEXT`；handoff 必须保存 hot set、faithful uncertainty、surviving fronts 与 continuation fidelity
 2. prevalidate branch 与可选 backup alias
 3. coordinator 追加 backup label，并持有 operation-scoped rollback token
 4. 调用 `branchWithSummary(..., true)`
@@ -106,16 +107,16 @@ checkpoint view 额外显示 `root` structural candidate 和每个候选 travel
 
 travel 只改变 Pi session tree 和模型 context，不回滚文件、进程、浏览器、远端服务或其他外部副作用。
 
-结果报告 raw evidence：usage before/estimated after、token delta、percentage-point delta、message counts/direction、summary-depth before/after/delta、summary entry、backup、refresh 与 live sync state。不要恢复旧的 `estimatedEffect` / `structuralEffect` 阈值 verdict。
+结果报告 raw evidence：usage before/estimated after、token delta、percentage-point delta、message counts/direction、summary-depth before/after/delta、summary entry、backup、refresh 与 live sync state。matching receipt 以同一个 `toolCallId` 关联 call/result，并分别报告 `outcome`、`mutationState` 与 `workingSetState`：travel applied 后即使后续 message evidence 不完整，也不得渲染成未执行；branch 状态无法排除时不得渲染成成功。不要恢复旧的 `estimatedEffect` / `structuralEffect` 阈值 verdict。
 
-## Semantic rebase
+## Representation rebase
 
-rebase 是 agent 对现有 `acm_travel` 的高阶使用，不是新工具或 runtime mode。目标是把所有 surviving state 合并成一个 authoritative snapshot，并移动到**最早安全基底**。
+Rebase 是 agent 对现有 `acm_travel` 的高阶使用，不是新工具或 runtime mode。目标是把重复、竞争或 split-authority 的 active handoff layers 合并成一个 authoritative representation，并移动到**最早安全基底**。
 
-- 触发 rebase check：summary 已堆叠、稳定 chain/subchain 完成、新目标将开始、context pressure 上升
-- 候选从 earliest 到 latest 评估；`root` 是理想候选但不是默认 target
-- cold start 是硬门槛：fresh agent 必须能只凭新 handoff 与 direct evidence pointers 执行 `NEXT`
-- context pressure 不得降低 snapshot 完整性要求
+- rebase judgment：active handoff 出现 representation competition，且一个 handoff 能在最早候选处完成 structural replacement 与 continuation fidelity；summary depth、稳定 chain、新目标和 context pressure 只是 supporting evidence
+- 候选从 earliest 到 latest 评估；`root` 是 structural candidate，但不是默认 target
+- continuation fidelity 是语义门槛：fresh agent 必须能凭新 handoff 与 direct evidence pointers 继续当前 cognition，hot set、faithful uncertainty、fronts、invariants 与 evidence chains 都有一个权威归属
+- usage、message 与 pressure deltas衡量 attention economics，但不替代 representation quality
 - native `compaction` 不计入 semantic summary depth；只有 `branch_summary` 计入
 - runtime 只报告 summary depth、projected depth 和 deltas，不自动判断或执行 rebase
 
@@ -133,7 +134,7 @@ ACM context nudge 使用 Pi 公开的 hidden custom message channel，不修改
 - 普通 usage 回落不降低本周期 highest reached level；一次跳档只发送当前最高档；
 - 只有明确成功的 `acm_travel` 和 `session_compact` 开启新周期；失败或 indeterminate travel 不重置；
 - transition 后忽略可能仍然陈旧的即时 usage，以第一条真实 post-transition assistant prompt usage 建立无提醒 baseline；
-- reminder 只提高 agent 对安全 travel 时机的关注度，不强制 summary/travel/rebase；低 active context 是偏好，不得压过正确性、任务连续性、cold start 与 recoverability。
+- reminder 用 30/50/70 档位逐步提高对 attention economics 的关注：认知持续压缩，显式 fold 批量提交；pressure 提高 durable attention gain 的价值并可缩短 cadence，但每次 transition 仍需携带 hot set、保留 provenance 并避免 sediment 与 compression thrash。
 
 ## Persistent context rebuild
 
@@ -168,18 +169,20 @@ Pi extension tool context没有 command-only `navigateTree()`，因此 `acm_trav
 
 ## Guidance ownership
 
-- `skills/context-management/CORE.md`：normal-path guidance 的 canonical source
-- `skills/context-management/SKILL.md`：advanced-only router
-- `skills/context-management/references/`：target selection、archive recovery、exceptional recovery
+- `CONTEXT.md`：ACM ubiquitous language；只定义 domain terms，不写实现细节
+- `skills/context-management/CORE.md`：always-on representation、compression 与 cadence doctrine 的 canonical source（道与度）
+- `skills/context-management/TOOL-CONTRACTS.md`：tool descriptions、prompt snippets、prompt guidelines、result cues 与 recovery text 的 canonical source（术）
+- `skills/context-management/SKILL.md`：advanced technique router
+- `skills/context-management/references/`：handoff wire format、target selection、travel isolation、archive rehydration 与 exceptional host recovery
 - `src/generated-guidance.ts`：generated runtime artifact，不应手工漂移
 
-canonical 词汇固定为 working set、boundary、handoff、archive、chain、burst、rebase、cold start、anchor gravity。checkpoint 创建 recoverability；travel 才 fold boundary；rebase 仍复用 travel mutation contract。
+canonical leading words 固定为 working set、representation、uncertainty fidelity、evidence chain、hot set、compression cadence、recoverability、checkpoint、compression seam、handoff、continuation fidelity、archive、fold、rehydrate、rebase、representation competition、sediment、compression thrash、anchor gravity、front、request 与 receipt。认知压缩持续发生，显式 fold 按 coherent semantic batch 提交；checkpoint cadence 跟随 recoverability delta，fold cadence 跟随 durable representation delta，rebase 处理 competing representations。tool call 是 request，matching tool result 才是 receipt；receipt 区分 intent 与 applied / not-applied / indeterminate fact。Agent 默认自主调用 ACM；只有用户明确表示接下来不要 travel，才在该语义范围内暂停 travel。工具名、checkpoint suffix、action count、context pressure 与 summary depth 都不是 semantic state classifier 或固定调用阈值。
 
 ## Tool prompt 与 TUI 呈现
 
-三个 ACM 工具都必须显式提供 `promptSnippet`、以工具名开头的 `promptGuidelines`、`renderShell: "self"`、`renderCall` 和 `renderResult`。prompt metadata 只保留每个工具最关键的触发/安全门，不复制完整 CORE。
+三个 ACM 工具都必须使用 generated `promptSnippet`、以工具名开头的 generated `promptGuidelines`、`renderShell: "self"`、`renderCall` 和 `renderResult`。`TOOL-CONTRACTS.md` 是 descriptions、snippets、guidelines、cues 与 recovery text 的唯一真源；prompt metadata 不得在 behavior-owned modules 内复制 CORE。每个 tool result 的 provider-visible `content` 和 structured `details` 都必须附同一份 `ACM_RECEIPT`，公共参数 schema 不增加 required execute flag。
 
-self-shell 默认视图应紧凑展示调用意图和可判定 evidence；`expanded` 视图保留完整 raw tool result。renderer 只读取既有参数、`content` 与 `details`，不得改变发送给 LLM 的工具结果或 mutation contract；错误/indeterminate 结果不得套用成功样式。
+self-shell 默认视图应紧凑展示调用意图和可判定 evidence；`expanded` 视图保留完整 raw tool result。renderer 只读取既有参数、`content`、`details` 与 validated receipt，不得改变发送给 LLM 的 mutation contract；`applied`、`not_applied`、`indeterminate` 必须使用不同 chrome，applied-but-evidence-incomplete 也必须与未执行区分。
 所有来自 streaming 参数、host details 或 tool content 的动态文本，在进入自定义 `Text` renderer 前必须经过 `sanitizeTerminalText()`；保留换行和制表符，但不得把 C0/C1 终端控制字符带入 self-shell。
 
 ## 测试与验证
@@ -211,6 +214,8 @@ bun run verify:acm
 
 `verify:acm` 必须覆盖 generated-guidance check、全部 root tests、production TypeScript typecheck，以及 host fixture。不得退回只跑 guidance tests 的不完整 gate。
 
+开放式 model behavior eval 是非 CI 证据：`bun run eval:acm -- --candidate <model> --judge <model>`。mock ACM tools 必须复用 canonical descriptions、prompt snippets、prompt guidelines、schemas 与 receipts。后续场景族必须覆盖 recoverability、compression quality、uncertainty fidelity、continuation fidelity、compression cadence、sediment/thrash、travel isolation、receipt discipline 与 representation competition，并使用多种措辞；judge 只评 semantic invariants 和 acceptable cadence，不锁 exact tool order 或 global call count。评测 runner、场景和说明分别位于 `scripts/eval-acm-behavior.mjs`、`eval/acm-behavior-scenarios.mjs` 与 `eval/README.md`。
+
 host fixture 必须覆盖 exact Pi version、`/context` 的 exact `ExtensionRunner` 注册与 `pi-tui` 渲染、adapter capability/installation、successful shrinking travel、in-flight tool pair、provider context、native compaction accounting、failure fallback、repeated travel、off-path restore、resume、lifecycle cleanup、multi-session/subagent isolation。
 
 不要使用 `console.log`；用户可见 warning 使用 `ctx.ui.notify()`。

CONTEXT.md

@@ -0,0 +1,89 @@
+# Agentic Context Management
+
+Pi-context helps a coding agent continuously improve the representation in its live context while preserving precise recovery paths.
+
+## Language
+
+**Working set**:
+The live, task-sufficient representation used for the next stretch of reasoning. It carries settled knowledge, faithful uncertainty, constraints, hot detail, and provenance rather than replaying the transcript.
+_Avoid_: recent messages, full transcript
+
+**Representation**:
+The current model of the work: knowns, unknowns, competing hypotheses, attribution, constraints, external effects, excluded directions, parked fronts, and the next discriminator or action.
+_Avoid_: summary text, progress recap
+
+**Uncertainty fidelity**:
+The property that unresolved questions remain accurately unresolved after compression, with hypotheses, evidence, attribution gaps, and discriminators intact.
+_Avoid_: keeping all raw evidence live, guessing a conclusion
+
+**Evidence chain**:
+The measurements, baselines, deltas, causal links, and provenance that make attribution checkable. It may survive as sufficient statistics plus direct evidence pointers.
+_Avoid_: result dump, unsupported conclusion
+
+**Hot set**:
+Exact detail likely to be reused in the next stretch of work. Carry it through a fold at low loss so the agent does not immediately reread what it just archived.
+_Avoid_: every recent detail, all raw process
+
+**Compression cadence**:
+The rhythm of continuous cognitive compression and batched explicit folds. Cadence follows durable representation gain and recoverability value rather than action count or fixed phases.
+_Avoid_: one-step-one-fold, global tool frequency
+
+**Recoverability**:
+The option to return to a valuable prior state or recover archived precision through a durable pointer.
+_Avoid_: retaining everything live, backup alone
+
+**Checkpoint**:
+A semantic label attached to history when the value of a return state materially changes. It creates recoverability without changing the working set.
+_Avoid_: workflow state, mandatory task marker, fold
+
+**Receipt**:
+The structured outcome attached to one matching tool request. The call expresses intent; the receipt reports applied, not applied, or indeterminate fact.
+_Avoid_: assistant claim, parameters, planned action
+
+**Compression seam**:
+A point where the process behind an anchor can be replaced by a better representation. It may occur during unresolved work and does not require task or phase completion.
+_Avoid_: closed boundary, checkpoint location
+
+**Handoff**:
+The authoritative representation that survives a fold through the seven-slot wire shell. It carries the hot set, faithful uncertainty, evidence pointers, external state, exclusions, recovery, and an executable next action.
+_Avoid_: transcript digest, completion report
+
+**Continuation fidelity**:
+The standard that a fresh agent can continue the current cognition from the handoff and direct pointers without rereading the folded process.
+_Avoid_: completed task, structurally valid only, cold-start finality
+
+**Archive**:
+Raw history intentionally moved off the active path and retained behind a recovery pointer.
+_Avoid_: deleted history, authoritative handoff
+
+**Fold**:
+A recoverable context transition that commits one batched representation update at a compression seam.
+_Avoid_: checkpoint, mandatory phase transition
+
+**Rehydrate**:
+Recover exact archived detail for a precise decision, then integrate the resulting knowledge back into the authoritative representation.
+_Avoid_: resuming ordinary work on the archive branch
+
+**Rebase**:
+A fold that retires repeated or competing handoff layers into one authoritative representation at the earliest safe base.
+_Avoid_: automatic root travel, token reset
+
+**Representation competition**:
+Ambiguity or duplicated authority created when handoff layers repeat, conflict, or leave fronts without one authoritative home. Summary depth is evidence, not the condition itself.
+_Avoid_: context pressure, token count alone
+
+**Sediment**:
+Replaceable process left in the working set after a better representation exists.
+_Avoid_: any long task, unresolved work
+
+**Compression thrash**:
+Repeated low-yield folds, recalls, or rereads caused by tiny representation deltas or failure to carry the hot set.
+_Avoid_: all frequent folds, any rehydration
+
+**Anchor gravity**:
+The tendency to choose the nearest, root, or conveniently named history anchor instead of the last clean anchor before the process being replaced.
+_Avoid_: recency as verdict
+
+**Front**:
+One coherent line of work that can be active, parked, or complete while other work continues in the same session.
+_Avoid_: tool step, arbitrary task-list item