@femtomc/mu-agent 26.2.99 → 26.2.101

package/dist/operator.js

@@ -1,3 +1,4 @@
+import { HudDocSchema, normalizeHudDocs } from "@femtomc/mu-core";
 import { appendJsonl, getStorePaths, readJsonl } from "@femtomc/mu-core/node";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -6,6 +7,7 @@ import { CommandContextResolver } from "./command_context.js";
 import { createMuSession } from "./session_factory.js";
 import { DEFAULT_OPERATOR_SYSTEM_PROMPT } from "./default_prompts.js";
 const OPERATOR_RESPONSE_MAX_CHARS = 12_000;
+const OPERATOR_TURN_HUD_DOCS_MAX = 16;
 const SAFE_RESPONSE_RE = new RegExp(`^[\\s\\S]{1,${OPERATOR_RESPONSE_MAX_CHARS}}$`);
 const OPERATOR_TIMEOUT_MIN_MS = 1_000;
 const OPERATOR_TIMEOUT_HARD_CAP_MS = 10 * 60 * 1_000;
@@ -42,9 +44,18 @@ export const OperatorApprovedCommandSchema = z.discriminatedUnion("kind", [
         thinking: z.string().trim().min(1),
     }),
 ]);
+const OperatorTurnHudDocsSchema = z.array(HudDocSchema).max(OPERATOR_TURN_HUD_DOCS_MAX).optional();
 export const OperatorBackendTurnResultSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("respond"), message: z.string().trim().min(1).max(OPERATOR_RESPONSE_MAX_CHARS) }),
-    z.object({ kind: z.literal("command"), command: OperatorApprovedCommandSchema }),
+    z.object({
+        kind: z.literal("respond"),
+        message: z.string().trim().min(1).max(OPERATOR_RESPONSE_MAX_CHARS),
+        hud_docs: OperatorTurnHudDocsSchema,
+    }),
+    z.object({
+        kind: z.literal("command"),
+        command: OperatorApprovedCommandSchema,
+        hud_docs: OperatorTurnHudDocsSchema,
+    }),
 ]);
 function normalizeArg(arg) {
     return arg.trim();
@@ -244,6 +255,43 @@ function nonEmptyString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
+function isHudToolName(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    return normalized === "mu_hud";
+}
+function extractHudDocsFromToolResult(result) {
+    const rec = asRecord(result);
+    if (!rec) {
+        return [];
+    }
+    const details = asRecord(rec.details);
+    const candidates = [];
+    const topLevelHudDocs = rec.hud_docs;
+    if (Array.isArray(topLevelHudDocs)) {
+        candidates.push(...topLevelHudDocs);
+    }
+    if (details) {
+        const detailHudDocs = details.hud_docs;
+        if (Array.isArray(detailHudDocs)) {
+            candidates.push(...detailHudDocs);
+        }
+    }
+    return normalizeHudDocs(candidates, { maxDocs: OPERATOR_TURN_HUD_DOCS_MAX });
+}
+function collectHudDocsFromToolExecutionEvent(event) {
+    const rec = asRecord(event);
+    if (!rec) {
+        return [];
+    }
+    if (nonEmptyString(rec.type) !== "tool_execution_end") {
+        return [];
+    }
+    const toolName = nonEmptyString(rec.toolName);
+    if (!toolName || !isHudToolName(toolName)) {
+        return [];
+    }
+    return extractHudDocsFromToolResult(rec.result);
+}
 function finiteInt(value) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
         return null;
@@ -574,6 +622,7 @@ export class MessagingOperatorRuntime {
             return {
                 kind: "response",
                 message,
+                ...(backendResult.hud_docs && backendResult.hud_docs.length > 0 ? { hud_docs: backendResult.hud_docs } : {}),
                 operatorSessionId: sessionId,
                 operatorTurnId: turnId,
             };
@@ -594,6 +643,7 @@ export class MessagingOperatorRuntime {
         return {
             kind: "command",
             commandText: approved.commandText,
+            ...(backendResult.hud_docs && backendResult.hud_docs.length > 0 ? { hud_docs: backendResult.hud_docs } : {}),
             operatorSessionId: sessionId,
             operatorTurnId: turnId,
         };
@@ -905,6 +955,7 @@ export class PiMessagingOperatorBackend {
         const session = sessionRecord.session;
         let assistantText = "";
         let capturedCommand = null;
+        let capturedHudDocs = [];
         const unsub = session.subscribe((event) => {
             // Capture assistant text for fallback responses.
             if (event?.type === "message_end" && event?.message?.role === "assistant") {
@@ -933,6 +984,12 @@ export class PiMessagingOperatorBackend {
                     capturedCommand = parsed.data;
                 }
             }
+            const hudDocs = collectHudDocsFromToolExecutionEvent(event);
+            if (hudDocs.length > 0) {
+                capturedHudDocs = normalizeHudDocs([...capturedHudDocs, ...hudDocs], {
+                    maxDocs: OPERATOR_TURN_HUD_DOCS_MAX,
+                });
+            }
         });
         const promptText = buildOperatorPrompt(input);
         const promptOnce = async () => {
@@ -970,6 +1027,7 @@ export class PiMessagingOperatorBackend {
                 await session.agent.waitForIdle();
                 assistantText = "";
                 capturedCommand = null;
+                capturedHudDocs = [];
                 await promptOnce();
             }
         }
@@ -993,6 +1051,9 @@ export class PiMessagingOperatorBackend {
                 command: capturedCommand,
                 messagePreview: assistantText,
             });
+            if (capturedHudDocs.length > 0) {
+                return { kind: "command", command: capturedCommand, hud_docs: capturedHudDocs };
+            }
             return { kind: "command", command: capturedCommand };
         }
         // Otherwise treat the assistant text as a plain response.
@@ -1009,6 +1070,9 @@ export class PiMessagingOperatorBackend {
             outcome: "respond",
             messagePreview: responseMessage,
         });
+        if (capturedHudDocs.length > 0) {
+            return { kind: "respond", message: responseMessage, hud_docs: capturedHudDocs };
+        }
         return { kind: "respond", message: responseMessage };
     }
     dispose() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-agent",
-  "version": "26.2.99",
+  "version": "26.2.101",
   "description": "Shared operator runtime for mu assistant sessions and serve extensions.",
   "keywords": [
     "mu",
@@ -24,7 +24,7 @@
     "themes/**"
   ],
   "dependencies": {
-    "@femtomc/mu-core": "26.2.99",
+    "@femtomc/mu-core": "26.2.101",
     "@mariozechner/pi-agent-core": "^0.53.0",
     "@mariozechner/pi-ai": "^0.53.0",
     "@mariozechner/pi-coding-agent": "^0.53.0",

package/prompts/skills/heartbeats/SKILL.md

@@ -13,6 +13,7 @@ Use this skill when the user asks to schedule, inspect, tune, or debug `mu heart
 - [Preflight checks](#preflight-checks)
 - [Heartbeat lifecycle workflow](#heartbeat-lifecycle-workflow)
 - [Prompt design for bounded ticks](#prompt-design-for-bounded-ticks)
+- [Reusable status-voice snippet](#reusable-status-voice-snippet)
 - [Diagnostics and recovery](#diagnostics-and-recovery)
 - [Evaluation scenarios](#evaluation-scenarios)
 
@@ -107,15 +108,39 @@ Good pattern:
 - inspect queue/state
 - do exactly one action
 - verify
-- summarize progress
+- report project-level progress as a titled status note plus a concise narrative paragraph
+- narrative should cover project context, what milestone moved, impact, overall progress, and next step
+- keep low-level queue/worker internals out of default reporting; include them only for blocker/anomaly diagnosis
 - exit
 
 Example bounded prompt:
 
 ```text
-Review ready issues under root <root-id>. Perform exactly one bounded step:
-claim/work one ready issue (or report blocked), verify state, post concise progress,
-then exit.
+Review issues under root <root-id>. Perform exactly one bounded orchestration step,
+verify state, then report for a human as:
+- a short title that summarizes status
+- one concise paragraph: project context, what moved this pass, impact,
+  where the project stands overall, and what comes next
+Only include queue/worker details if diagnosing a blocker/anomaly.
+Then exit.
+```
+
+## Reusable status-voice snippet
+
+Use this copy/paste block in heartbeat prompts when updates should be written for
+non-operator humans:
+
+```text
+Write the update as a short status note for a human reader.
+- First line: a plain-language title that captures the status.
+- Then one concise paragraph explaining:
+  - what this project is trying to achieve,
+  - what meaningful milestone moved in this pass,
+  - what impact that creates (or what precondition was completed),
+  - where the overall project stands,
+  - what comes next and why it matters.
+Avoid low-level orchestration internals by default (queue snapshots, worker/session IDs,
+packet mechanics, raw issue-ID lists). Include them only when diagnosing a blocker/anomaly.
 ```
 
 For hierarchical DAG execution, pair this skill with:
@@ -161,7 +186,7 @@ mu store tail cp_outbox --limit 30 --pretty
 
 1. **Periodic progress heartbeat**
    - Setup: heartbeat created with bounded control-loop prompt and `--every-ms 15000`.
-   - Expected: each wake performs one bounded pass and exits; no unbounded run behavior.
+   - Expected: each wake performs one bounded pass, emits a high-level titled narrative status update, and exits; no unbounded run behavior.
 
 2. **Event-driven heartbeat mode**
    - Setup: heartbeat created/updated with `--every-ms 0`.

package/prompts/skills/hierarchical-work-protocol/SKILL.md

@@ -164,6 +164,7 @@ mu issues dep <step-a> blocks <step-b>
 - Scoped authority: mutate only current issue and descendants.
 - Non-executable containers/questions must not retain `node:agent`.
 - Forum updates are append-only and resumable (`START`/`RESULT` packets).
+- Orchestrator progress packets are human-facing and objective-linked: use a clear status title plus concise narrative paragraph (project context, milestone moved, impact, overall progress, next step); include low-level queue/worker internals only for blocker/anomaly diagnosis.
 - Every executable issue closes with explicit outcome.
 - `mu issues validate <root-id>` must pass before declaring completion.
 
@@ -192,7 +193,7 @@ Worker/orchestrator passes always choose one primitive at a time:
 2. Choose one primitive (`ask` | `expand` | `complete` | orchestration primitive)
 3. Apply
 4. Verify (`get`, `children`, `ready`, `validate`)
-5. Log concise progress to forum
+5. Log human-facing progress to forum as a titled narrative update (context -> milestone moved -> impact -> overall progress -> next), using the reusable status-voice style from `heartbeats`
 6. Exit bounded pass
 
 ## Minimal bootstrap template

package/prompts/skills/hud/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: hud
+description: "Defines HUD usage for `mu_hud` and `/mu hud`, including doc schema patterns, deterministic update rules, and rendering-safe conventions."
+---
+
+# hud
+
+Use this skill whenever you need to publish, update, or inspect HUD state.
+
+This skill is the canonical HUD reference for:
+
+- `mu_hud` tool calls (structured HUD state)
+- `/mu hud ...` command usage (inspection/control)
+- `HudDoc` conventions that render well in TUI/Slack/Telegram
+
+## Contents
+
+- [Core contract](#core-contract)
+- [HudDoc shape](#huddoc-shape)
+- [Recommended turn loop](#recommended-turn-loop)
+- [Planning and subagents profiles](#planning-and-subagents-profiles)
+- [Determinism and rendering limits](#determinism-and-rendering-limits)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Core contract
+
+### Tool (`mu_hud`)
+
+Actions:
+
+- `status`, `snapshot`
+- `on`, `off`, `toggle`
+- `set`, `update`, `replace`, `remove`, `clear`
+
+Key params:
+
+- `doc` (for `set`/`update`)
+- `docs` (for `replace`)
+- `hud_id` (for `remove`)
+- `snapshot_format` (`compact` or `multiline`)
+
+Notes:
+
+- `set` and `update` are both upsert-style single-doc writes.
+- `replace` is whole-inventory replacement.
+- Tool results include normalized `hud_docs` for downstream transport/rendering.
+
+### Command (`/mu hud ...`)
+
+Supported subcommands:
+
+- `/mu hud status`
+- `/mu hud snapshot [compact|multiline]`
+- `/mu hud on|off|toggle`
+- `/mu hud clear`
+- `/mu hud remove <hud-id>`
+
+Use the tool (`mu_hud`) for structured doc writes.
+
+## HudDoc shape
+
+HUD docs are validated against `HudDoc` (`@femtomc/mu-core`).
+
+Minimum practical fields:
+
+- `v: 1`
+- `hud_id: <non-empty>`
+- `title: <non-empty>`
+- `snapshot_compact: <non-empty>`
+- `updated_at_ms: <int>`
+
+Common optional fields:
+
+- `scope` (for root/session/issue scoping)
+- `chips` (`[{key,label,tone?}]`)
+- `sections`:
+  - `kv` (key/value)
+  - `checklist` (checkbox-style progress)
+  - `activity` (recent lines)
+  - `text` (free text)
+- `actions` (`[{id,label,command_text,kind?}]`)
+- `metadata` (machine-readable extras)
+
+Example checklist doc:
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "hud_id": "planning",
+    "title": "Planning HUD",
+    "scope": "mu-root-123",
+    "chips": [
+      { "key": "phase", "label": "phase:drafting", "tone": "accent" },
+      { "key": "steps", "label": "steps:2/5", "tone": "dim" }
+    ],
+    "sections": [
+      {
+        "kind": "checklist",
+        "title": "Checklist",
+        "items": [
+          { "id": "1", "label": "Investigate", "done": true },
+          { "id": "2", "label": "Draft DAG", "done": true },
+          { "id": "3", "label": "Review", "done": false }
+        ]
+      }
+    ],
+    "actions": [
+      { "id": "snapshot", "label": "Snapshot", "command_text": "/mu hud snapshot", "kind": "secondary" }
+    ],
+    "snapshot_compact": "HUD(plan) · phase=drafting · steps=2/5",
+    "updated_at_ms": 1771853115000,
+    "metadata": { "phase": "drafting" }
+  }
+}
+```
+
+## Recommended turn loop
+
+1. Ensure HUD is on:
+
+```json
+{"action":"on"}
+```
+
+2. Upsert exactly the docs you own (`set`/`update`).
+3. Emit compact snapshot for user-facing status:
+
+```json
+{"action":"snapshot","snapshot_format":"compact"}
+```
+
+4. Keep response text and HUD state aligned (no contradictions).
+
+## Planning and subagents profiles
+
+Use profile-specific `hud_id` values:
+
+- planning profile: `hud_id: "planning"`
+- subagents profile: `hud_id: "subagents"`
+
+Treat these as conventions layered on top of this generic contract.
+
+## Determinism and rendering limits
+
+- Keep one canonical doc per `hud_id`.
+- Keep `updated_at_ms` monotonic for each `hud_id`.
+- Prefer a small doc set (usually 1–3 docs total) for channel readability.
+- Keep command actions concise; long commands may degrade to text-only fallbacks on some channels.
+- Assume channel renderers cap docs/actions/lines; put critical state in `snapshot_compact` and first section items.
+
+If behavior is unclear, inspect implementation/tests before guessing:
+
+- `packages/core/src/hud.ts`
+- `packages/agent/src/extensions/hud.ts`
+- `packages/server/src/control_plane.ts`
+- `packages/agent/test/hud_tool.test.ts`
+
+## Evaluation scenarios
+
+1. **Planning review turn**
+   - Expected: `planning` doc updates phase/checklist/waiting state, then emits compact snapshot.
+
+2. **Subagents orchestration pass**
+   - Expected: `subagents` doc updates queue/activity/chips after each bounded pass.
+
+3. **HUD reset handoff**
+   - Expected: after phase completion, HUD is cleared or removed by `hud_id`, and status reflects no stale docs.

package/prompts/skills/mu/SKILL.md

@@ -98,7 +98,7 @@ mu session <session-id>
 mu turn --session-kind operator --session-id <session-id> --body "<follow-up>"
 ```
 
-In attached terminal operator chat, `/mu` helpers are available (`/mu events`, `/mu plan`, `/mu subagents`, `/mu help`).
+In attached terminal operator chat, `/mu` helpers are available (`/mu events`, `/mu hud ...`, `/mu help`).
 
 ## Durable automation handoff
 

package/prompts/skills/planning/SKILL.md

@@ -10,6 +10,7 @@ Use this skill when the user asks for planning, decomposition, or a staged execu
 ## Contents
 
 - [Planning HUD is required](#planning-hud-is-required)
+- [HUD skill dependency](#hud-skill-dependency)
 - [Shared protocol dependency](#shared-protocol-dependency)
 - [Core contract](#core-contract)
 - [Suggested workflow](#suggested-workflow)
@@ -28,10 +29,17 @@ For this skill, the planning HUD is the primary status/communication surface.
 
 Default per-turn HUD loop:
 
-1. Apply an atomic `update` with current `phase`, `waiting_on_user`, `next_action`, `blocker`, and `confidence`.
-2. Synchronize checklist items and `root_issue_id` with the issue DAG.
+1. Emit a fresh `planning` HUD doc (`mu_hud` action `set` or `update`) with current `phase`, `waiting_on_user`, `next_action`, `blocker`, and `confidence` in sections/metadata.
+2. Keep checklist progress and root issue linkage synchronized with the live issue DAG.
 3. Emit `snapshot` (`compact` or `multiline`) and reflect it in your response.
 
+## HUD skill dependency
+
+Before emitting or mutating planning HUD state, load **`hud`** and follow its canonical contract.
+
+- Treat `hud` as source-of-truth for generic `mu_hud` actions, `HudDoc` shape, and rendering constraints.
+- This planning skill defines planning-specific conventions only (for example `hud_id: "planning"`, planning phases, checklist semantics).
+
 ## Shared protocol dependency
 
 This skill plans DAGs for execution by `subagents`, so planning must follow the
@@ -58,6 +66,7 @@ Do not invent alternate protocol names or tag schemas.
    - Add clear titles, scope, acceptance criteria, and protocol tags.
 
 3. **Drive communication through the planning HUD**
+   - Load `hud` and use its canonical `mu_hud`/`HudDoc` contract.
    - Treat HUD state as the canonical short status line for planning.
    - Keep `phase`, `waiting_on_user`, `next_action`, `blocker`, and `confidence` current.
    - Ensure HUD state and your natural-language response never contradict each other.
@@ -72,6 +81,10 @@ Do not invent alternate protocol names or tag schemas.
    - Update issues/dependencies and re-present deltas.
    - Do not begin broad execution until the user signals satisfaction.
 
+6. **After user approval, ask user about next steps**
+   - On user acceptance of the plan, turn the planning HUD off.
+   - Read the `subagents` skill and offer to supervise subagents to execute the plan.
+
 ## Suggested workflow
 
 ### A) Investigation pass
@@ -86,46 +99,36 @@ mu memory search --query "<topic>" --limit 30
 Bootstrap HUD immediately (interactive operator session):
 
 ```text
-/mu plan on
-/mu plan phase investigating
-/mu plan waiting off
-/mu plan confidence medium
-/mu plan next "Investigate constraints and gather evidence"
-/mu plan snapshot
+/mu hud on
+/mu hud status
+/mu hud snapshot
 ```
 
 Tool contract (preferred when tools are available):
 
-- Tool: `mu_planning_hud`
-- Actions:
-  - state: `status`, `snapshot`, `on`, `off`, `toggle`, `reset`, `phase`, `root`
-  - checklist: `check`, `uncheck`, `toggle_step`, `set_steps`, `add_step`, `remove_step`, `set_step_label`
-  - communication: `set_waiting`, `set_next`, `set_blocker`, `set_confidence`
-  - atomic: `update`
-- Key parameters:
-  - `phase`: `investigating|drafting|reviewing|waiting_user|blocked|executing|approved|done`
-  - `root_issue_id`: issue ID or `clear`
-  - `waiting_on_user`: boolean
-  - `next_action`, `blocker`: string or `clear`
-  - `confidence`: `low|medium|high`
-  - `steps`: string[]
-  - `step_updates`: array of `{index, done?, label?}`
+- Canonical contract: see skill `hud`
+- Tool: `mu_hud`
+- Actions: `status`, `snapshot`, `on`, `off`, `toggle`, `set`, `update`, `replace`, `remove`, `clear`
+- Planning convention: maintain a HUD doc with `hud_id: "planning"`
+- Suggested planning doc structure:
+  - `title`: `Planning HUD`
+  - chips: `phase:<...>`, `steps:<done>/<total>`, `waiting:<yes|no>`, `conf:<low|medium|high>`
+  - sections:
+    - `kv` status block (`phase`, `root`, `waiting_on_user`, `confidence`, `next_action`, `blocker`)
+    - `checklist` block for plan milestones
+  - actions: include useful follow-ups (for example, `snapshot`)
 
 Example tool calls:
-- Atomic status update for an investigation turn:
-  - `{"action":"update","phase":"investigating","waiting_on_user":false,"next_action":"Draft root issue and child DAG","blocker":"clear","confidence":"medium"}`
-- Atomic handoff when waiting for approval:
-  - `{"action":"update","phase":"waiting_user","waiting_on_user":true,"next_action":"Confirm scope change","blocker":"Need approval","confidence":"low"}`
-- Clear communication fields after user reply:
-  - `{"action":"update","waiting_on_user":false,"blocker":"clear","next_action":"Incorporate feedback and re-draft DAG"}`
-- Customize checklist:
-  - `{"action":"set_steps","steps":["Investigate","Draft DAG","Review with user","Finalize"]}`
+- Turn HUD on:
+  - `{"action":"on"}`
+- Set/replace planning doc after investigation pass:
+  - `{"action":"set","doc":{"v":1,"hud_id":"planning","title":"Planning HUD","scope":"mu-root-123","chips":[{"key":"phase","label":"phase:investigating","tone":"dim"},{"key":"steps","label":"steps:1/4","tone":"accent"},{"key":"waiting","label":"waiting:no","tone":"dim"},{"key":"confidence","label":"conf:medium","tone":"accent"}],"sections":[{"kind":"kv","title":"Status","items":[{"key":"phase","label":"phase","value":"investigating"},{"key":"root","label":"root","value":"mu-root-123"},{"key":"waiting","label":"waiting_on_user","value":"no"},{"key":"confidence","label":"confidence","value":"medium"},{"key":"next","label":"next_action","value":"Draft root DAG"},{"key":"blocker","label":"blocker","value":"(none)"}]},{"kind":"checklist","title":"Checklist","items":[{"id":"1","label":"Investigate relevant code/docs/state","done":true},{"id":"2","label":"Create root + child issue DAG","done":false},{"id":"3","label":"Present plan + tradeoffs","done":false},{"id":"4","label":"Refine until approved","done":false}]}],"actions":[{"id":"snapshot","label":"Snapshot","command_text":"/mu hud snapshot","kind":"secondary"}],"snapshot_compact":"HUD(plan) · phase=investigating · steps=1/4 · waiting=no · conf=medium","updated_at_ms":1771853115000,"metadata":{"phase":"investigating","waiting_on_user":false,"confidence":"medium"}}}`
 - Human-facing status line:
   - `{"action":"snapshot","snapshot_format":"compact"}`
 
 If HUD behavior is unclear, inspect implementation/tests before guessing:
-- `packages/agent/src/extensions/planning-ui.ts`
-- `packages/agent/test/planning_ui_tool.test.ts`
+- `packages/agent/src/extensions/hud.ts`
+- `packages/agent/test/hud_tool.test.ts`
 
 Also inspect repo files directly (read/bash) for implementation constraints.
 
@@ -186,23 +189,17 @@ mu issues validate "$root_id"
 
 Required HUD updates during the loop:
 
-```text
-/mu plan root <root-id>
-/mu plan phase drafting
-/mu plan check 1
-/mu plan phase waiting-user
-/mu plan waiting on
-/mu plan next "Need your approval on tradeoff A/B"
-/mu plan snapshot
-```
+- Re-emit the `planning` HUD doc with current `phase`, checklist progress, `waiting_on_user`, `next_action`, and `blocker` after each meaningful planning step.
+- Use `{"action":"snapshot","snapshot_format":"compact"}` for concise user-facing HUD lines.
+- Keep `updated_at_ms` monotonic across updates so latest doc wins deterministically.
 
 ## Effective HUD usage heuristics
 
-- Prefer `update` for multi-field changes to avoid inconsistent intermediate state.
-- Reserve `waiting_user` for explicit user input/decision waits; use `blocked` for non-user blockers.
+- Keep one canonical planning doc (`hud_id: "planning"`) and refresh it whenever planning state changes.
+- Keep `updated_at_ms` monotonic so deterministic dedupe/ordering always keeps the latest planning state.
+- Use explicit, concise status fields (`phase`, `waiting_on_user`, `next_action`, `blocker`, `confidence`) in sections/metadata.
 - Keep `next_action` as one concrete action, not a paragraph.
-- Adjust `confidence` as evidence quality changes (`low` when assumptions are unresolved).
-- Customize checklist steps once scope is understood; check them off as milestones complete.
+- Customize checklist steps once scope is understood; mark them complete as milestones land.
 
 ## Evaluation scenarios