task-explainer-html

Task living explainer page (task-explainer-html)

Each non-lightweight accounted task has one pageLiving visual explanation: task package artifacts/explainer.html. It is not a final report, but the task'sin progresssingle-file HTML updated with each work round—the owner does not read worker sessions, task_plan is only the static plan at kickoff, and this page is the owner's window into progress while the task is underway; the closeout final state is frozen. The Daemon's dispatch protocol specifies who this page is for and when it is updated.

Materialized at task creation, the artifacts/explainer.html top HTML comment is thesole authoritative sourcefor sections, color scheme, layout, scenario diagram types, and quality requirements. Neither the dispatch nor this skill duplicates these rules; after opening the page, fill in real task content round by round according to the comments.

Page authoring

The HTML comments of the materialized page are authoritative. The body must contain two ids:#now"What is happening now" (overwritten and rewritten each round) and #timeline"Process record" (append-only, newest on top); add other sections as the task requires, with no limit on number or titles. Use diagrams with real names and numbers (structure, flow, sequence, before/after comparison, data) to explain the problem as much as possible; do not draw diagrams that cannot depict real content. Do not maintain a second set of template guidance in this skill, the mission, or other copies; when template rules change, only change the preset template and its tests.

<task-context> injection specification

The mission dispatched for a task carries a framework-injected causal context XML (2048-byte budget,packages/daemon/src/dispatch-causal-context.ts is the sole authoritative source). Syntax:

<task-context>
<work ref="task/<id>">所属 Work 的标题</work>
<parent ref="task/<id>">父任务标题</parent>
<decision ref="decision/<id>" title="决策标题"/>
<chosen ref="decision/<id>" anchor="CH1">选定锚文本 — 理由</chosen>
<claims ref="decision/<id>">C1 载重断言; C2 断言</claims>
<fact ref="fact/<id>">事实陈述 (src:证据来源)</fact>
<goal ref="task/<id>">Work 目标一两句</goal>
<question ref="decision/<id>">决策待答问题</question>
<refs>task/… decision/… fact/…</refs>
</task-context>

Parsing rules (deterministic guarantees):

• Line-oriented: except for the leading and trailing <task-context> / </task-context> , each element is a complete line, and appearing independently or being absent is valid—budget trimming discards whole lines, and a fragment assembled from any subset of lines can still be parsed line by line.
• Escaping: text and attribute values are XML-escaped (& < > "), and are restored using standard entities when parsed.
• Attribution：chosen / claims / question uses the ref attribute to bind the owning decision, not nested indentation.
• Truncation marker: when the root element has truncated="yes" , it indicates that whole lines were trimmed by the budget;<refs> always retains the canonical id that can be looked up, and missing details are supplemented only within the scope authorized by the dispatch using this task's ha task read-set / ha task show ; restricted execution must not use this to query cross-task background or the whole-repository graph. When information is insufficient, report the specific missing items for the owner to provide, and do not make things up.
• Missing hierarchy：work / parent / decision / fact / goal any line may be absent (the task does not have that layer of relationship); empty blocks do not exist (tasks with no causal neighborhood are not injected).

The parsing specification only explains how to understand the causal context; how to present it on the page follows the HTML comments in the materialized template, and no separate identity section or scenario skeleton is set up here.

Living Deliverable Protocol

1. Round-by-round updates: after reading the materials at kickoff, first write the initial version (your understanding and plan); whenever there is substantive progress, a discovery, a change of direction, or red turning green, rewrite #now and in #timeline Append an entry at the top (time + what was done/what was discovered this round/why the direction was changed + evidence anchor). Do not save it all up to write at the end in one go.
2. Materialize on creation: tasks that are not lightweight profile have already materialized this page at ha task create (the preset template can be filled in incrementally directly); lightweight profile does not materialize this page, and the mission does not inject this protocol either. The first round of work starts by filling in the skeleton; do not create a new file.
3. closeout freeze: when the task enters a terminal state, the explanation page is submitted together with the task package and is no longer modified; the frozen version must be consistent with the conclusions in closeout.md.
4. Does not replace structured reporting: this page is an explanatory layer for people to read; ledger obligations such as the four sections of closeout.md, progress, and fact are not reduced by the existence of this page.

Placement and tools

• Only placement: this task package artifacts/explainer.html. Do not use any hosted Artifact / external gallery functionality; artifacts are version-managed and audited together with the task package.
• Tool selection: if the content is already clear (structure, numbers, and chart types are determined), write the HTML directly by hand; only dispatch an external worker when charts are heavy, and note the hard rules for this page in the skeleton (single-file inline / light color / full width / readable without JS).
• Self-check before delivery: leak grep → fact check (numbers in the page compared against the source report) → no-JS rendering verification → full-width whitespace self-check (when opened on a large screen, only margin-scale whitespace remains on the left and right).