required-work-context.md

Required work context

Ordinary Heartbeat/quota delivers the full effective selected Todo, enabled canonical acceptance and Agent-scoped User obligations at interaction_contract.agent_channel.work_context. These are current work sources, with readback/revision metadata; no TurnEnvelope switch is needed. The selected Todo's display body is a display-only view and may be bounded. Its exact detail read is authoritative for the current body and is validated against the selected identity, lifecycle, claim and source revision. When a full-body snapshot accompanies the selection, a mismatch remains pending and requires a fresh guard. When the selected body is byte-for-byte the same as the exact read, work_context.selected_todo_ref reuses it and the source retains its identity, lifecycle, claim, continuation, relations and authority revision without repeating the body. If no other canonical fields need a source record, work_context.selected_todo_authority carries the source and revision. When the view is bounded, the full canonical detail remains in work_context.sources. Registered Goal state uses the existing writer's strict generated-region ownership. When every recognized Todo region is explicitly marked, the source adapter delivers all other text verbatim in work_context.sources: Goal intent, frontmatter, arbitrary sections, comments, history and final stops. excluded_todo_regions retains each generated region's role, line interval and SHA-256; revision hashes the entire original file, including those regions. Canonical exact Todo and scoped User reads retain task requirements and authority. This default read changes the Goal obligation from the mixed document to its complete non-generated text; it does not summarize requirements or erase history. No source file or canonical record is rewritten.

Unmarked or mixed ownership keeps the original full progressive read in agent_channel.required_reads. Malformed markers, non-generated content inside a marked region, unavailable files and invalid UTF-8 fail closed. Unknown narrative is never classified by headings or clipped to a size budget. Read all delivered context and remaining reads before dependent work; changed sources need a fresh guard. Enabled scoped acceptance does not replace original Goal intent.

The Goal availability adapter still reads and UTF-8-validates the complete file and hashes all bytes for its revision. For unmarked or mixed ownership, only its path and revision cross the internal context-projection bridge, preserving the complete progressive read without an unused body copy. Explicitly owned sources send the complete non-generated narrative and region lineage to the typed consumer. Missing files and invalid UTF-8 still block dependent delivery. Byte reduction alone does not establish model-token, latency or outcome gains.

Already delivered sources disappear from required_reads; unresolved provider reads retain exact commands and ordering. The typed interaction owner owns this selection and fulfillment policy in both ordinary packets and TurnEnvelope. work_context.complete means no known source failure, not that pending reads have been consumed. TurnEnvelope signs the same content and obligations; its size warning never truncates current requirements or removes a pending read.

Preferences remain conditional on scoped records. The existing preference and Explore hooks return their actual read context through registered adapters; the generic kernel never executes the displayed shell commands. Discovery receipts stay separate from the single content carrier. Unconfigured hooks preserve their off-state. User Todo inventory views disappear only from exact Todo responses; scoped User decisions and gates remain in the work context and retain their existing admission/notification authority.

Source failure retains the unresolved read, identifies the unavailable source, and blocks dependent delivery until recovery and a fresh guard. Reading current content is not an execution grant or proof of Goal completion.

For selected work, the acceptance adapter reuses the canonical owner's exact Todo inspection. Its top-level tasks observations cover that Todo; the full Goal contract, configured scope, checks, held work and cumulative outcomes stay intact, including other owners' requirements. The separate selected-Todo source retains its complete body and declaration. Todo-less reads and the explicit goal-acceptance inspect command keep their existing full inventory. This reduces repeated binding observations without treating a shorter context as acceptance, authority or a measured model benefit.

For an exact Todo, the existing command now returns one complete record:

loopx --format json todo list --goal-id example-goal --todo-id todo_work

Read todo.text plus identity, status/claim, relations, source and canonical authority_read revision. The former todos, agent_todos and user_todos views are removed from exact responses. There is no opt-in compatibility flag. Inventory reads without --todo-id retain list views; --thin belongs to those bounded lists and is rejected with an exact identity. A full requirement tail must never be replaced by a summary. Markdown also renders the original once.

Ordinary JSON inventories keep the selected todos array intact. Repeated identical records in the role-summary lanes now use response-local JSON pointers, for example {"$ref":"#/todos/0"}. Read the complete record at that pointer; it is not a command or a new execution grant. A lane can contain a record outside an explicit --limit; its first complete projection remains in that lane, and later copies point there. Distinct projected facts are never merged by Todo id or body text. Counts, order, source revision, scoped User obligations and resume, claim and lease facts retain their original meaning. The todo_list_record_references field describes this readback.

This is the default JSON CLI presentation, without a compatibility flag. The native decision/frontend read model, Markdown, --thin and exact detail retain their existing shapes. Existing inventory excerpts remain excerpts and do not replace a full exact read or a fresh guard. Pointer expansion reconstructs the prior inventory; reduced response size does not prove model adoption, faster whole turns or better task outcomes.

Missing or filtered work returns matched=false, todo=null, not_found=true. Ambiguous records and source failures fail visibly, without stale-display fallback. Blocked, completed and archived records remain read-only observations. An exact read grants no claim, lease, execution, publication or quota authority. Changed requirements require fresh admission under the original owner.

The existing Python reader retains source resolution and filtering. It passes one source row to the registered TypeScript todo.context.page projection, without transporting duplicate body or role-summary views. Chat manager detail, Explore writeback and monitor settlement use the exact record rather than a removed list alias. No second authority store or selection rule is introduced.

This changes default exact CLI/API output and Heartbeat/Turn context delivery. Regenerate saved expanded heartbeat prompts after installing the change. Bootstrap prompts load installed rules on the next wake. TurnEnvelope transport remains an explicit projection choice; this change alone neither upgrades installed automations nor proves model adoption or token/latency gains. To roll back, install the prior revision and regenerate prompts; changing a transport flag does not restore the old exact Todo schema.

中文

普通 Heartbeat/quota 默认在 agent_channel.work_context 返回完整选定 Todo、 启用的验收与当前 Agent 相关的 User Todo，附带来源和修订，不需要开启 TurnEnvelope。 Goal Markdown 复用原 writer 对生成区域的严格归属规则：所有已识别 Todo 区域均有 显式标记时，work_context.sources 原样携带区域外的全部文字，保留目标、frontmatter、 任意章节、注释、历史和末尾停止条件。excluded_todo_regions 保留每段的角色、行区间 和 SHA-256，revision 仍覆盖完整原文件；任务要求与权限由 canonical 精确 Todo 和 scoped User 读取保留。默认 Goal 必读对象改为完整非生成正文，不摘要要求、不删除历史， 不重写原文件或权威记录。未标记或混合归属仍须渐进式读取全文；错误标记、标记内非生成 内容、来源缺失及非法 UTF-8 均拒绝。不能按标题猜测或为预算截断正文；依赖交付前须读取 全部已提供上下文与剩余必读，来源改变后重新准入，局部验收不能替代整体目标。 Goal adapter 仍完整读取文件、校验 UTF-8，并以全部字节计算修订摘要；未标记或混合归属 仅在内部桥接传路径与修订，避免未被消费的正文副本，Agent 仍须渐进式全文读取。显式 归属的来源才向 typed owner 传完整非生成正文和区域血缘。字节减少不能证明模型费用、 延迟或任务效果改善。 已附带的内容不要求重复读取；未提供的 provider 内容继续保留精确命令与顺序。 work_context.complete 只表示未发现来源失败，未完成的必读义务仍然有效。 偏好只在对应作用域有记录时出现；Explore 和偏好沿用各自 hook 的真实 adapter， 读取范围由 capability owner 决定。来源失败保留未完成必读项并阻止依赖交付，恢复后 重新准入；User gate 仍生效。大小告警不截断验收或移除剩余必读项。

已选定工作时，验收 adapter 复用 canonical owner 的精确 Todo 读取，顶层 tasks 只携带该工作的关联观察；完整 Goal 合同、已配置 scope、检查、受阻工作和累计 outcome 全部保留，包括其他 owner 的要求。选定 Todo 的完整正文与声明仍由独立来源携带。 没有选定工作的读取及显式 goal-acceptance inspect 保留完整列表；正文减少不等于 验收、执行权限或已经测得模型收益。

todo list --todo-id … 默认只返回一份完整 todo.text，保留来源、修订、身份、 状态和关系。精确响应移除列表及角色视图，不保留兼容开关；--thin 只用于概览。 缺失/过滤返回未匹配，歧义/来源故障报错，不退回旧摘要。读到记录不等于获得执行 权限；阻塞、已完成、归档记录仍只是观察。需求改变须重新准入。

普通 JSON CLI 列表保留完整的选定 todos 数组；角色视图内完全相同的重复记录 改为 {"$ref":"#/todos/0"} 等响应内指针，沿指针读取原记录。显式 --limit 之外的视图记录仍保留首份正文，后续副本引用它；同 ID 但事实不同的投影不会合并。 计数、顺序、来源、User 义务及恢复/claim/lease 条件保持原义，不增加执行权限。 原生决策/前端读模型、Markdown、thin 和精确详情保持既有结构。没有兼容开关； 原有摘要仍不能替代精确全文和 fresh guard。正文减少不等于模型采用、整轮加速或 任务效果改善。

安装后重新生成旧展开式 heartbeat 提示；此 PR 不热更新 runtime/automation， 也不证明模型已采用或获得质量收益。回滚需恢复旧版本并重新生成提示。