@shivaedev/work-board 0.10.0 → 0.12.0

package/dist/server/views/workHtml.js

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { inboxItems } from "#server/attention/inbox.ts";
+import { identityUrl } from "#server/metadata/links.ts";
+import { projectItems } from "./projection.js";
+import { viewTools } from "./tools.js";
+import { workCards } from "./workCards.js";
+import { workControls } from "./workControls.js";
+import { workDetail } from "./workDetail.js";
+import { workTable } from "./workTable.js";
+export const workHtml = Effect.fn("WorkBoard.workHtml")(function* (snapshot, state) {
+    const projection = projectItems(snapshot, state);
+    const waiting = new Map(inboxItems(snapshot)
+        .filter((item) => !item.problem)
+        .map((item) => [item.id, item.reason]));
+    const controls = workControls(projection, state);
+    const tools = viewTools(state);
+    if (!projection.validBoard) {
+        return {
+            html: `<h1>Board unavailable</h1>${tools}${controls}<p class="empty">${escapeHtml(state.board)} is missing, has a duplicate ID, or is not a declared board. Choose another board or open its <a href="${escapeHtml(identityUrl(state.board))}">source identity</a>.</p>`,
+            status: 404,
+        };
+    }
+    const issues = projection.issues.length > 0
+        ? `<details class="view-issues"><summary>Source issues (${projection.issues.length})</summary><ul>${projection.issues.map((issue) => `<li>${escapeHtml(issue)}</li>`).join("")}</ul></details>`
+        : "";
+    const source = state.board ? `<a href="${escapeHtml(identityUrl(state.board))}">Board source</a>` : "";
+    const empty = projection.items.length === 0
+        ? '<p class="empty">No identified work is declared here. Keep reading ordinary files, or add item IDs and explicit board membership in their Markdown sources.</p>'
+        : "";
+    const detail = yield* workDetail(projection, state, snapshot);
+    return {
+        html: `<header class="work-head"><p class="work-eyebrow">WORK · ${state.view.toUpperCase()} VIEW</p><h1>${escapeHtml(projection.title)}</h1><p>Views use recorded fields. A section heading does not set an item's status.</p>${source}</header>
+ ${tools}${controls}${issues}<p class="work-total" role="status">${projection.rows.length} shown · ${projection.items.length} items in this view</p>
+ <div class="work-layout${state.item ? " has-detail" : ""}"><section id="work-results" tabindex="-1" aria-label="Work items">${empty}${state.view === "table" ? workTable(projection.rows, state, waiting) : workCards(projection.rows, state, waiting)}</section>${detail}</div>`,
+        status: 200,
+    };
+});
+//# sourceMappingURL=workHtml.js.map

package/dist/server/views/workHtml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workHtml.js","sourceRoot":"","sources":["../../../src/server/views/workHtml.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC,oBAAoB,CAAC,CAAC,QAAQ,CAAC,EAAE,QAAkB,EAAE,KAAY;IAClG,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,GAAG,CACtB,UAAU,CAAC,QAAQ,CAAC;SAClB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;SAC/B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CACvC,CAAC;IACF,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QAC5B,OAAO;YACN,IAAI,EAAE,6BAA6B,KAAK,GAAG,QAAQ,oBAAoB,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,0GAA0G,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,4BAA4B;YACxQ,MAAM,EAAE,GAAG;SACX,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GACX,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAC3B,CAAC,CAAC,wDAAwD,UAAU,CAAC,MAAM,CAAC,MAAM,kBAAkB,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,iBAAiB;QAC/L,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;IACvG,MAAM,KAAK,GACV,UAAU,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAC5B,CAAC,CAAC,iKAAiK;QACnK,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9D,OAAO;QACN,IAAI,EAAE,4DAA4D,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,gBAAgB,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,0FAA0F,MAAM;GACrO,KAAK,GAAG,QAAQ,GAAG,MAAM,uCAAuC,UAAU,CAAC,IAAI,CAAC,MAAM,YAAY,UAAU,CAAC,KAAK,CAAC,MAAM;0BAClG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,sEAAsE,KAAK,GAAG,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,aAAa,MAAM,QAAQ;QAChR,MAAM,EAAE,GAAG;KACX,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/server/views/workStyle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workStyle.d.ts","sourceRoot":"","sources":["../../../src/server/views/workStyle.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,IAAI,MAAM,CAgBlC"}

package/dist/server/views/workStyle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workStyle.js","sourceRoot":"","sources":["../../../src/server/views/workStyle.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,SAAS;IACxB,OAAO;;;;;;;;;;;;;;CAcP,CAAC;AACF,CAAC"}

package/dist/server/views/workTable.d.ts

@@ -0,0 +1,4 @@
+import type { Item } from "./items.ts";
+import { type State } from "./state.ts";
+export declare function workTable(items: readonly Item[], state: State, waiting?: ReadonlyMap<string, string>): string;
+//# sourceMappingURL=workTable.d.ts.map

package/dist/server/views/workTable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workTable.d.ts","sourceRoot":"","sources":["../../../src/server/views/workTable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,KAAK,KAAK,EAAW,MAAM,YAAY,CAAC;AAgBjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,GAAG,MAAM,CAOxH"}

package/dist/server/views/workTable.js

@@ -0,0 +1,24 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { viewUrl } from "./state.js";
+function row(item, state, waiting) {
+    const fields = item.document.parsed.fields;
+    const selected = item.id === state.item;
+    const values = [
+        fields.kind,
+        waiting.has(item.id) ? `Waiting on you · ${fields.status ?? "Status not recorded"}` : fields.status,
+        fields.owner,
+        fields.nextAction,
+    ];
+    return `<tr data-item="${escapeHtml(item.id)}"${selected ? ' data-selected="true"' : ""}>
+ <th scope="row"><a href="${escapeHtml(viewUrl(state, { item: item.id }, "work-detail"))}"${selected ? ' aria-current="true"' : ""}>${escapeHtml(item.title)}</a><span class="work-id">${escapeHtml(item.id)}</span></th>
+ ${values.map((value) => `<td>${escapeHtml(value ?? "Not recorded")}</td>`).join("")}</tr>`;
+}
+export function workTable(items, state, waiting = new Map()) {
+    if (items.length === 0) {
+        return '<p class="empty">No work matches these filters.</p>';
+    }
+    return `<div class="work-table-wrap"><table class="work-table"><caption class="sr-only">Identified work, sorted by ${escapeHtml(state.sort)}</caption>
+ <thead><tr>${["Work", "Kind", "Status", "Owner", "Next action"].map((title) => `<th scope="col">${title}</th>`).join("")}</tr></thead>
+ <tbody>${items.map((item) => row(item, state, waiting)).join("")}</tbody></table></div>`;
+}
+//# sourceMappingURL=workTable.js.map

package/dist/server/views/workTable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workTable.js","sourceRoot":"","sources":["../../../src/server/views/workTable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAc,OAAO,EAAE,MAAM,YAAY,CAAC;AAEjD,SAAS,GAAG,CAAC,IAAU,EAAE,KAAY,EAAE,OAAoC;IAC1E,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,IAAI,CAAC;IACxC,MAAM,MAAM,GAAG;QACd,MAAM,CAAC,IAAI;QACX,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,oBAAoB,MAAM,CAAC,MAAM,IAAI,qBAAqB,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM;QACnG,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,UAAU;KACjB,CAAC;IACF,OAAO,kBAAkB,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,EAAE;4BAC5D,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,aAAa,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,6BAA6B,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;GACzM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAsB,EAAE,KAAY,EAAE,OAAO,GAAgC,IAAI,GAAG,EAAE;IAC/G,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,qDAAqD,CAAC;IAC9D,CAAC;IACD,OAAO,8GAA8G,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;cAC9H,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;UAC/G,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,wBAAwB,CAAC;AAC1F,CAAC"}

package/docs/delivery/README.md

@@ -0,0 +1,50 @@
+# Work Board delivery requirements
+
+Build the [north star](../north-star.md) as useful, reviewable changes. The [roadmap](../roadmap.md) owns completion, acceptance and maintainer decisions; numbers here name requirements and dependency order, rather than release dates.
+
+Each step names a reader outcome, prerequisites, bounded implementation and observable acceptance. Split a step when its review would mix independent risks. Extend the existing source and Effect boundaries, and deliver a visible use with its shared foundation.
+
+## Delivery sequence
+
+| Steps | Reader outcome | Review task |
+| --- | --- | --- |
+| [01–03](wave1.md#01-a-real-workspace-shell) | Browse and search a large folder | Use actual notes, keyboard navigation and a narrow layout |
+| [04–06](wave1.md#04-optional-identity-and-a-rebuildable-index) | Read the same work across views, relationships and claims | Understand the source model outside the board |
+| [07–09](wave1.md#07-an-attention-first-overview) | Find explicit attention and changes while keeping orientation | Return after an agent worked and identify the next judgment unaided |
+| [10–13](wave1.md#10-local-visual-evidence) | Inspect visual evidence and read a complete project workflow | Review combined technical, reader and device behavior |
+| [14–17](wave2.md#14-prove-one-safe-source-mutation) | Give durable direction without losing source or drafts | Exercise reviewed context, competing writers and clear outcomes |
+| [18–20](wave2.md#18-one-local-agent-handoff) | Give one agent direction and review its returned result | Complete a real revision and explicit acceptance |
+| [21–23](wave3.md#21-successive-contributions-with-clear-ownership) | Keep successive contributions and linked reviews coherent | Prove ownership and stale-contribution handling |
+| [24–26](wave3.md#24-one-optional-read-only-github-adapter) | Remove demonstrated evidence/attention work | Admit each extension by its concrete manual step |
+
+## Material for maintainer decisions
+
+| Decision | Material | Boundary to preserve |
+| --- | --- | --- |
+| D1 Source structure | [Source examples](source-examples.md), plain Markdown, duplicates and invalid fields | Optional metadata and explicit identities without mandatory migration |
+| D2 Responses and ownership | [Response contract](response-write-examples.md), [packet source](decision-write-examples.md), [result review](result-review-examples.md), [ordinary editing](source-editing-examples.md) | Human-owned response content, agent-owned project edits and practical recovery; authored report acceptance stays distinct from criterion evidence |
+| D3 Handoff | [Copied-file handoff contract](handoff-examples.md) | Ordinary direction and file-edited receipt for an existing session; receipt is separate from execution and acceptance |
+| D4 Evidence integration | Repeated manual step, authoritative fields, refresh/offline rules and maintenance owner | Explicit linked objects and usable local work without the adapter |
+
+The roadmap records whether each decision is settled and what it means for a step. The maintainer owns public APIs, file formats, dependencies and releases. Mockups do not choose a serialization or framework. Prepare concrete examples before asking for a new decision; normal acknowledgment must remain possible through ordinary agent file edits.
+
+## Extend the existing boundaries
+
+| Boundary | Owns | Preserve |
+| --- | --- | --- |
+| [Shell](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/page/shell.ts), [navigation](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/page/nav.ts), [styles](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/page/style.ts) | Layout and reading controls | Readable server HTML, system fonts and local assets |
+| [Board parser](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/render/board.ts), [Markdown renderer](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/render/markdown.ts) | Source interpretation and semantic reading | Heading boards, GFM, references and readable fallback |
+| [Page route](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/http/page.ts), [router](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/board.ts) | Locations, projections and HTTP composition | Loopback boundary, embedding and Effect scope/errors |
+| [Listing](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/files/list.ts), [watcher](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/files/changes.ts) | File discovery and freshness | Root policy, rename/delete handling and recovery |
+| [Native client](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/client/client.ts), [DOM swap](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/client/page/scripts.ts) | Scoped reads and retained reading state | Shared Effect contracts/live primitives, clear failures and reconciliation |
+| [Assets](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/server/http/assets.ts), [diagrams](https://github.com/ShivaeDev/platform/blob/main/packages/work-board/src/client/page/scripts.ts) | Local visual reading | Bounded access and locally loaded renderers |
+
+Keep CLI and embedding working together. Static mockup markup and fictional data are review aids, not the production data model. A new framework, persistent store or adapter must earn its cost through an agreed requirement.
+
+## Evidence required
+
+Name the step, visible outcome, source compatibility and exclusions in a change. Behavior tests must fail without the change. Use pure parser tests for interpretation, real filesystem/HTTP tests for serving/watching, and real browsers for focus, layout, history and actual Mermaid. DOM fixtures establish their asserted behavior; they do not establish browser-engine or device correctness.
+
+Use a 50-document/100-item workspace with duplicate headings, nested/encoded paths, missing references, diagrams, long text and malformed metadata, plus empty/small folders. The [browser checks](browser-acceptance.md) and [combined reading review](reading-review.md) provide repeatable procedures. Measure on a named machine and agree numeric budgets before enforcing them. Reader orientation targets require representative readers, not fabricated timing.
+
+Record results and revised scope only in the roadmap. History belongs in Git and the changelog. Preserve source compatibility, truthful evidence and ordinary conflict recovery when reducing scope. Optional adapters do not become prerequisites for the local product; no step adds cloud hosting, accounts or remote multiplayer.

package/docs/delivery/attention-examples.md

@@ -0,0 +1,71 @@
+# Explicit attention requests
+
+Work Board reads an optional `attention` list from richer item frontmatter. Each record names one request independently of the item's arbitrary status, owner or next action. A request ID is unique within that item and uses the existing case-sensitive ASCII ID syntax. Its identity is the pair (item ID, request ID). The overview at `/_board/overview` links each request to its exact source context.
+
+```yaml
+id: result.search
+kind: result
+attention:
+  - id: keyboard-review
+    kind: review
+    state: open
+    response_from: [marvin]
+    reason: Review the recorded keyboard evidence before continuing.
+    unblocks: [work.search#keyboard]
+  - id: matching-decision
+    kind: decision
+    state: open
+    response_from: [marvin]
+    reason: Choose literal matching or fuzzy matching for the next checkpoint.
+    unblocks: [decision.search-matching]
+```
+
+The ordinary Markdown body holds the options, rationale and evidence links. The overview shows two independent requests from the same item. Opening either leads to the existing source context and its explicit target links.
+
+A blocker is also an explicit request, not a deduction from a dependency edge:
+
+```yaml
+id: work.search
+kind: task
+attention:
+  - id: missing-fixture
+    kind: blocker
+    state: open
+    response_from: [agent-navigation]
+    reason: Supply a representative keyboard fixture to continue validation.
+    unblocks: [work.search#keyboard]
+```
+
+This says the author requests a response; it does not prove the target cannot proceed or start an agent. Recipients are literal local labels, not verified identities, an account directory, a permission boundary or a notification route.
+
+## Reading rules
+
+| Field | Source shape and meaning |
+| --- | --- |
+| `attention` | Optional list; absent/empty means no recorded request |
+| `id` | Required request ID, unique within the item |
+| `kind` | Required `decision`, `review`, or `blocker` |
+| `state` | Required `open` or `closed`; explicitly authored source state |
+| `response_from` | Required nonempty list of nonblank literal labels |
+| `reason` | Required nonblank text explaining why a response is needed |
+| `unblocks` | Required nonempty list of existing item/criterion reference shapes |
+| `managed` | Optional boolean; an execution integration may opt a generated decision into exact-context request acknowledgement |
+
+Only unique, valid open requests on unique identified items with resolvable targets enter the queues. Missing recipients/reason/state, unsupported fields or invalid reference syntax make the attention list uninterpreted, like the other frontmatter fields; retain the whole original list and report its source issue. Independent valid fields and ordinary Markdown remain readable. Duplicate request IDs, missing item IDs and unresolved/ambiguous targets stay unclassified with source diagnostics. No request silently chooses a duplicate winner.
+
+A closed request remains readable and searchable but leaves the open queue. Closing it records an author's state claim; it does not verify evidence or prove human acceptance, a response, authorship or approval. A response records direction against its captured context; it does not change that authored request state. See the [response contract](./response-write-examples.md).
+
+For a generated decision marked `managed: true`, a separate qualified `request_receipt` can remove the request from the open queue without changing its source state. The receipt must match the registered question's exact source path and bytes. Applying it requires the unique current answer; superseding it does not invent an answer. Ordinary authored requests keep the rules above. See the [managed acknowledgement rules](../../README.md#record-a-human-response).
+
+The overview groups decisions, reviews and blockers with visible counts, then orders each group by source title, item ID and request ID. Each entry shows the recorded reason, recipients, target links and origin file/line. Request text and recipients are searchable; source targets contribute backlinks. An incomplete workspace returns an explicit unavailable state and withholds queue counts and classification. Source issues are disclosed separately from a genuine quiet state. Files and requests remain local; the UI never writes their contents.
+
+## Ambiguity and quiet examples
+
+- `status: in-review` with `owner: marvin` and no attention list: no request.
+- `next_action: Ask Marvin`, a finished run, or repeated edits: no request.
+- Two `keyboard-review` records on one item: neither wins; show a source issue.
+- Two items with the same ID: do not assign either item's requests.
+- `unblocks: [missing.id]`: show a source issue outside the actionable queue; keep the request readable in its original file.
+- `state: closed`: no open queue entry, with no acceptance claim.
+- A complete workspace with only valid closed requests: quiet overview.
+- Malformed YAML: retain readable prose and disclose the source issue; do not present it as a confirmed quiet workspace.

package/docs/delivery/browser-acceptance.md

@@ -0,0 +1,147 @@
+# Workspace browser acceptance
+
+Use the production page with the shared 50-document, 100-item fixture. Happy DOM regressions cover preference handling and live rendering with a Mermaid stub; these checks cover layout, keyboard interaction, and the actual Mermaid package. Run them when shell, styling, navigation, or diagram rendering changes.
+
+From the repository root, after installing dependencies and building packages:
+
+```sh
+node --conditions=source --input-type=module <<'JS'
+import { folder, startBoard } from './packages/work-board/src/test-support/board.ts';
+import { workspaceFixture } from './packages/work-board/src/test-support/workspaceFixture.ts';
+const notes = folder(workspaceFixture());
+const board = await startBoard(notes.root, 'board.md');
+console.log(`Open ${board.url}\nEdit files in ${notes.root}`);
+process.on('SIGINT', async () => {
+  await board.stop();
+  notes.remove();
+  process.exit(0);
+});
+await new Promise(() => {});
+JS
+```
+
+Open the printed URL in a real browser. Record the browser/version, viewport, actual results, and any limitations in the PR. Stop with Ctrl-C after review.
+
+1. At 1440 × 1000, verify the board has multiple columns. Expand `notes/` and scroll its 49 entries independently of the board. The document content stays reachable; the navigation does not become a wall above it.
+2. Reload, press Tab, then Enter on **Skip to content**. Focus moves to the main content. Tab through Files, Theme, Density, folder summaries, and file links; focus must be visible. Open a nested document and check its file location.
+3. Select Dark and Compact, collapse Files, then reload and open another file. All three choices persist. Select Light with the operating system in dark mode; code colors and diagrams follow Light. Return to System and switch the system scheme; diagrams redraw. Changing density alone must not redraw them.
+4. Open `notes/flow & details.md`. Wait for the real diagram and open Review notes. Append a paragraph to that file in the printed fixture folder. The paragraph appears, details stay open, and the unchanged diagram stays drawn.
+5. In a fresh browser context at 390 × 844, verify Files starts collapsed, the board uses one column, and the page does not scroll horizontally. The top bar keeps Inbox with its count. Open Files: an overlay drawer contains the fixed Home, Inbox, Overview, Work, Changes and Diagnostics rows, and the project tree scrolls independently. Escape and an outside tap close the drawer and return focus to Files. Close it and open a document. Also check at 200% zoom.
+6. Disable JavaScript and reload. Content and navigation remain readable. With browser storage blocked, enable JavaScript and change appearance: controls work and explain that choices apply only to the current page.
+
+The fixture includes duplicate headings, a missing link, long prose, an encoded filename, a diagram, details, and malformed example metadata. The additional `identityFixture()` supplies richer items, explicit references, and recorded claims. Performance timings from this fixture are observations, not established budgets or proof of the north star's usability targets.
+
+## Document navigation acceptance — step 02
+
+1. In a document, open **On this page** and follow the second Evidence heading. Its hash and focused heading differ from the first. Copy a heading passage link, open it in a new tab, and verify the target. Check a Unicode heading too.
+2. Designate a home file in a nested folder. Serve it at `/` and follow a relative Markdown link to a sibling or parent folder. Repeat with encoded `#`, `?`, spaces, and `&` in a filename. Ctrl/Cmd-click should open a separate tab.
+3. Select text, open a content details block, and scroll down. Open another document, then use Back and Forward. Selection, details, and scroll restore. Reload the returned document and check tab-scoped reading state. Repeat after changing the theme on the other page; a cached diagram uses the current theme.
+4. Save a favorite, visit several documents, reload, and open Recent documents to use the reading-history dialog. Recents are unique and bounded. A second workspace must not inherit the first one's favorites. Block browser storage: controls work and display the notice.
+5. Delete a favorite's source file while another page is open. Its sidebar link remains visible with a missing label; following it explains the missing file. Remove a heading after copying its URL and check the missing-passage notice.
+6. Hold a page response in the browser's network tools, navigate elsewhere, then release it. The old response must not replace the new page. Simulate a failed navigation, restore network access, and retry the same link. Recheck desktop, mobile, keyboard, no-JavaScript rendering, and live updates of the active title.
+
+## Workspace search acceptance — step 03
+
+1. Open Search with Ctrl/Cmd+K. Search `project note`, a document filename, `Evidence`, and a phrase from a card. Check the result types, snippets, count, and 40-result limit. A nonexistent phrase must show an empty state.
+2. Search the text under a second duplicate heading in an encoded filename. Use arrows then Enter; the result opens the correct heading. Escape restores focus to the control that opened the dialog. Check the focus trap, dark theme, and dialog/results scrolling at 390 × 844 without horizontal overflow.
+3. With the dialog open, edit/add/delete a Markdown file in the fixture folder. Results must update. Drop and reconnect the event stream; results reconcile.
+4. Hold an earlier search response, type a different query, then release it. The older results must not replace the newer query. Fail a request and use Search to retry. Unreadable files must disclose incomplete results.
+5. Clear the query and use workspace/sidebar/density/theme commands. Confirm native modified clicks on file results still open another tab. With JavaScript disabled, Search is disabled and documents remain readable.
+
+Search observations from a named machine may be recorded as a baseline; they are not an agreed performance budget or usability proof. A source-in-editor affordance needs an agreed local editor mechanism.
+
+## Optional identity acceptance — step 04
+
+Add `identityFixture()` from `src/test-support/identityFixture.ts` to the large fixture.
+
+1. Open the legacy board: its 100 cards remain unchanged. Search an explicit ID, owner, and criterion phrase. Check source line labels, then use Enter to open an item/criterion. Criteria expand work details and receive keyboard focus, including when searching within the already active item.
+2. Inspect work details, relationship/source links, and original frontmatter. Missing fields say Not recorded. Evidence shows recorded revision/time/method and outcome with an explicit notice that the claim is not independently verified.
+3. Open content details and select prose. Rename the source file while its stable item URL is open; details, selection, and location remain. Edit the heading; its title updates. Navigate to its decision and use Back to restore details.
+4. Add a duplicate ID; the active item must become a conflict explanation with source choices. Remove the duplicate and recover. Delete the remaining source; its stable URL must show an explicit missing-item page.
+5. Read a malformed/unknown field and an unresolved reference. Prose and original metadata remain readable. Repeat item/criterion navigation at 390 × 844, in dark mode, and with JavaScript disabled. Check narrow overflow and page errors.
+
+## Work board/detail acceptance — step 05
+
+Add `viewsFixture()` from `src/test-support/viewsFixture.ts` to the large fixture.
+
+1. Confirm the legacy home still has 100 cards. Open Work and select Review work then Shared investigation. The same work.search ID appears in both with the source's recorded fields; counts exclude duplicates and undeclared members.
+2. Apply owner/status/text filters and sorting. Missing fields remain distinct from literal text. Open a card, follow its source/evidence link, then use Back. Reload its URL; board, filters, selected ID, and source pane must agree.
+3. Edit the selected item's status. Applied filters remain, even with no matching status; the detail explains it is outside the projection. Keep unsent text focused through that update. Delete its source; explain the missing selection. Duplicate an ID or membership and inspect source diagnostics, without silently selecting a winner or inflating counts. An unreadable index refuses counts.
+4. Repeat at 390 × 844, with dark theme and reduced motion. Real Mermaid in the pane must render; check overflow and errors. Disable JavaScript and submit GET filters/open detail through native links. Also run the table and saved-view checks below before assessing the combined projection.
+
+## Table and saved-view acceptance — step 05
+
+1. Use the same richer fixture. Switch Board/Table with an item selected and filters/sorting applied. IDs, counts, source fields, and selected detail agree. Use Back and reload the table URL; selected context remains. Missing sort fields stay last and missing cells remain explicit.
+2. Save a named table view, reload, choose it, and Open. Applied board/filters/sort/ layout return without retaining item selection or unsent filter edits. Save the same name in a different layout and confirm it updates rather than doubles. Remove one or Clear all. Another workspace must not inherit these names.
+3. Save 10 views. An eleventh name must request removal/update instead of silently evicting one. Malformed stored JSON recovers on a successful save; external or executable saved URLs are ignored and names render as text. Block browser storage: in-memory saving/opening/removal still works with an explicit notice.
+4. Edit a selected item's status, then delete it. The table/counts update while applied filters, focused unsent input, and selection explanations remain. Verify real Mermaid, compact density, 390 × 844/dark/reduced motion without page overflow, and readable no-JavaScript table/filter/detail navigation. Saved-view controls remain disabled without JavaScript.
+
+## Reasoning and evidence acceptance — step 06
+
+Add `reasoningFixture()` from `src/test-support/reasoningFixture.ts` to the large fixture.
+
+1. Open Search reasoning in Table with result.search selected. Follow its Implements link to plan.search and that plan's link to decision.search. The options comparison and rationale are readable in two navigation steps. Use the rationale heading anchor and Back to restore the selected view context.
+2. Open work.search#keyboard. It lists claims from both its own source and the result file; passage has no recorded evidence. Open the result's record link: its source details expand and the exact evidence record receives focus. Origin file/line, old revision/time, method and recorded outcome are visible; no claim says independently verified or human accepted.
+3. Follow its evidence source to the plain evidence file and inspect Referenced by. Metadata/Markdown backlinks reach their explicit sources, including the encoded review filename. Follow that file's rationale link. The missing local Markdown record remains visible and leads to an explanatory missing page.
+4. Edit the result's criterion reference, delete the evidence source, then remove the result. Claim associations/backlinks reconcile; missing sources/claims remain explicit. Duplicate IDs or unreadable files must prevent validated criterion association and disclose partial references.
+5. Repeat record navigation at 390 × 844/dark/reduced motion and verify overflow, errors, and real Mermaid. Disable JavaScript and follow result → plan → decision natively. Existing legacy home cards remain unchanged.
+
+## Explicit attention acceptance — step 07
+
+Use `attentionFixture()` alongside `workspaceFixture()` with the 100-card legacy home; add a Mermaid diagram to the keyboard task. Open Overview from the legacy home and verify three requests: the review and decision on `request.search`, and the fixture blocker. `ordinary.review` has status/owner/action but no request; `prior-review` is explicitly closed and must not enter the queue.
+
+1. Read why each request appears, its response labels and target links. Open the keyboard review: focus the exact record and expand its source context. Reload, follow its criterion claims and real Mermaid, then Back twice. The overview's issue disclosure remains open. Follow the decision into options/rationale.
+2. Repeat at 1440 × 1000 and 390 × 844, dark theme and reduced motion. Verify no page overflow and native request/criterion navigation with JavaScript disabled. Chromium opens the ancestor details for a fragment target natively.
+3. Close the review/decision in their source; only the blocker remains. Rename the blocker file with spaces and `&`; its identity and encoded source link survive. Delete the criterion's item; the remaining request leaves the queue with an unresolved source issue. No source issue becomes a quiet workspace.
+4. HTTP regressions cover invalid/duplicate/missing identities and requests, unreadable source files, malformed YAML, stable restart and genuine quiet states. Unreadable indexes return 503 and withhold counts/classification.
+
+For the proposed 30-second orientation target, ask a representative reader to identify the judgment requested from them and what it would unblock before opening the details, recording elapsed time and feedback. Then ask them to follow its rationale/evidence. Automated fixture behavior cannot establish this user acceptance; record the exercise separately in the roadmap.
+
+## Explicit change baseline acceptance — step 08
+
+Use the same 100-card legacy home plus attention/reasoning fixture.
+
+1. Open Changes: first visit has no history. Start remembering, then edit recorded status, an attention state and decision Markdown; add a file, move a unique-ID item, and rename a plain file. The view explains changes with current links and escaped remembered/current text. A plain rename is removal/addition; identity moves match only a unique ID. No edit implies authorship or accepted evidence.
+2. Keep the baseline unchanged through live updates, source navigation, Back and reload. Open a remembered-source disclosure and retain it through live edits and Back. Mark seen replaces the baseline; Clear removes it and reload stays off. Touching unchanged source must not create a content change.
+3. Inject an expired record, then open ordinary Markdown: the record is removed without silently rebaselining. Invalid/future/unsupported records establish no comparison. Another workspace key stays untouched. Block storage: explicitly marked history works for this page with a visible persistence limitation.
+4. Repeat at 1440 × 1000 and 390 × 844 with dark theme/reduced motion and check page overflow/errors. Old source containing script/image Markdown is plain text. Disable JavaScript: retention controls are disabled with an explanation, and native Work/source navigation remains available.
+5. HTTP regressions refuse an incomplete observation and a complete oversized workspace without deletion counts or partial snapshots. Schema regressions exercise exact UTF-8 limits, corrupt/unsupported records and unsafe/duplicate paths. Source-comparison fixtures cover ambiguous IDs and unknown frontmatter.
+
+These checks establish comparison behavior, not the separate representative-user orientation target for step 07.
+
+## Linked reference directory acceptance
+
+1. Symlink the main checkout's `docs` directory into the workspace as `repo-docs`. Open `/repo-docs/framework/README.md`, follow its relative roadmap link and return with Back. Read the same files with JavaScript disabled.
+2. Include a temporary external reference directory containing nested Markdown. Choose its nested file as `--home`: `/` retains the requested logical alias and resolves relative links. Open a source disclosure, edit the physical reference file and retain the disclosure through live refresh and navigation/Back. Search must find the edited source through its workspace-relative URL.
+3. Add another directory link while the server runs, then retarget it to a different reference folder. Its navigation and reads catch up, obsolete paths disappear, and later edits of the new target refresh the active page.
+4. Repeat at 1440 × 1000 and 390 × 844, including dark theme/reduced motion. Check overflow and browser errors. Native HTTP regressions separately cover cycles/ancestor traversal, broken links, hidden/dependency entries, escaping file links, internal aliases, external add/rename/delete and watcher recovery.
+
+Links explicitly include trusted reference directories; the server never writes those sources. A target missing when the watch was built needs a server restart once restored. Multiple aliases remain separate paths and existing duplicate-ID rules apply. These checks establish reference reading; run the native live/orientation checks for invalidation and pause/resume.
+
+## Explicit observation overlap acceptance
+
+1. Start with two Markdown sources. Hold an actual HTTP `observe` response after it captures the first source revision, then edit that physical source and let its native watcher/SSE page refresh finish. Release the response: Mark seen retains the captured revision and comparison reports the subsequent change. A later explicit Mark seen replaces that baseline and reports no changes.
+2. Hold another observation, then Clear from a second tab sharing this workspace and browser storage. Release the old response. Both tabs stay without history; the cancelled observation must not restore the deleted baseline.
+3. Check ordinary marking at 390 × 844 with dark theme/reduced motion, page overflow and browser errors. DOM regressions separately force the overlap before the HTTP observation begins and assert cancellation by another tab's storage event. Keep the existing expiry, size and blocked-storage checks.
+
+These checks preserve explicit observation semantics; they do not establish an atomic filesystem snapshot, source mutation or verified acceptance. Run the native lifecycle checks separately.
+
+## Native live/orientation acceptance — step 09
+
+Use the large workspace plus `viewsFixture()` and a nested home at `/`.
+
+1. Edit an unrelated known file: navigation changes while the mounted active document query and reading paragraph remain. Edit an explicitly linked item, criterion/evidence source or board member: both reference contexts update.
+2. Open details and a real Mermaid drawing. Edit another passage: unchanged details, drawing, selected work URL and focused/unsubmitted filters remain. Changed reading blocks receive a brief outline without animation or scrolling.
+3. Pause, edit the nested home and wait for a pending count. The displayed source stays retained; resume catches up. The 256+ bound counts hints, not source edits.
+4. Go offline and edit, then reconnect. Retain visible source with a failure/down disclosure until required reads settle; connection availability alone is not freshness. Separately stop the native HTTP server with a subscription active.
+5. Mark seen, update source, and verify the original baseline stays unchanged. Clear while paused; expired history must also disclose unknown history while paused. Never cancel explicit observation through background invalidation.
+6. Navigate away and use browser Back. Record whether pageshow is persisted and any CDP bfcache refusal reasons; no-store can require a fresh document. Verify persisted-pageshow registry recreation separately with the DOM regression.
+7. Repeat at 390 × 844 with dark/reduced-motion settings and JavaScript disabled. Links still perform GET navigation; Pause is disabled without JavaScript. Verify browser actions have changed no source files.
+
+Physical tab transitions and Capacitor remain separate evidence. Fixtures do not establish the step 07 representative-reader timing or a multi-tab capacity budget.
+
+### Local visual evidence
+
+Reference a source-relative PNG/JPEG/GIF/WebP in a nested home and an evidence record. Inspect embedded images and local image links by keyboard; choose gallery images and return focus with Escape. Replace an image while paused, then resume; check the image reloads and open reading details survive. An earlier preview must disclose source updates and require reopening before saving. Try a missing image, malformed path, escaping link and oversized attachment.
+
+Inspect a large Mermaid diagram, choose Actual size and zoom, scroll on a narrow screen, enter desktop fullscreen and return to the source. Save the current SVG locally; also test an invalid diagram and an unavailable fullscreen environment. With JavaScript disabled, local images and diagram source remain readable. Record actual results and limits in the [roadmap](../roadmap.md). Physical mobile fullscreen and representative-reader timing require their own evidence.

package/docs/delivery/change-history-examples.md

@@ -0,0 +1,46 @@
+# Local change history — step 08 contract
+
+This contract defines retained browser data and the meaning of “last looked”. Markdown files remain authoritative and are never written by the Changes view. Implementation and reader acceptance are tracked only in the roadmap.
+
+## One explicit review baseline per workspace
+
+The Changes view compares the current readable workspace with one snapshot the reader marked seen. First visit says **No previous snapshot**; **Start remembering changes** records the current workspace. Reading a diff or receiving a live update does not silently acknowledge it. **Mark current workspace seen** replaces the baseline after review. The view is **Changes since seen**.
+
+Browser storage is scoped by origin and workspace. Retain at most one snapshot, for at most 30 days, with at most 2 MiB of serialized data per workspace. It contains file paths and source text (including any recorded item IDs): old or deleted prose can therefore remain locally until replaced, cleared or expired. There is no server history, event journal, author identity, remote storage or synchronization.
+
+The private, versioned browser record has this shape:
+
+```json
+{
+  "version": 1,
+  "recorded_at": "2026-10-05T19:45:00Z",
+  "documents": [
+    {
+      "file": "items/search.md",
+      "source": "---\nid: work.search\nstatus: in-review\n---\n# Search\n"
+    }
+  ]
+}
+```
+
+The recorded time names the browser baseline observation, not when a source was written, who authored it or when a decision was accepted. Decode stored and HTTP boundary data with Schema; an invalid/unsupported record establishes no history.
+
+**Clear remembered history** removes the snapshot and stays off until the reader starts again. Expiry makes comparison unavailable at 30 days; stored data is removed on the next workspace visit (or a periodic check while the page remains open). On insufficient storage, an oversized workspace or an incomplete index, report why comparison is unavailable. Never silently truncate a baseline or interpret unreadable files as deletions. If persistence is blocked, a disclosed page-only baseline can still compare live source edits; reload cannot pretend that baseline survived. Ordinary source reading stays usable.
+
+## Concrete comparison examples
+
+| Recorded baseline → current source | Reader sees |
+| --- | --- |
+| `work.search` status `in-review` → `done` | Recorded status changed; no inferred acceptance |
+| Criterion evidence gains a record | Recorded evidence changed, with current source link and before/after plain text |
+| Decision options/rationale changes | Decision content changed; no invented new ruling |
+| Unchanged source repeatedly touched | No content change; activity is not progress |
+| New file after the baseline | Source added, with current source link |
+| Known file absent from a complete current index | Source removed; old source remains readable as retained text |
+| Same unique explicit item ID moves to another file | Source path changed for that item; compare its recorded content |
+| Plain file moves without a durable identity | Show old path removed/new path added; no claimed rename or authorship |
+| Duplicate item IDs at either observation | Do not choose an identity winner; disclose ambiguity |
+| First visit, clear, expiry or corrupt storage | History unavailable; no invented additions or progress |
+| One current file cannot be read | Comparison unavailable; no alleged removal |
+
+The browser owns its baseline. A same-origin, loopback-only private POST query validates the versioned record and compares it with the current observation; it does not retain server history or write source files. Old and current source are escaped plain text, never rendered as executable Markdown assets. A snapshot is an observation of readable files, not an atomic filesystem transaction or a verified Git revision. Revisions used to detect source changes must not be confused with recorded Git evidence.

package/docs/delivery/decision-write-examples.md

@@ -0,0 +1,83 @@
+# Rich question packets and recorded decisions
+
+A packet combines agent-authored Markdown context, question directives, human selections and extra text in one response. It uses the same independent immutable question/response files as plain questions. Ordinary Markdown questions and responses without typed answers remain valid.
+
+## Source example
+
+The agent writes a normal item file with an explicit attention request, then prepares a packet in its body. The full source revision and path are captured by registration. Options start unselected; agent-authored descriptions do not count as human choices.
+
+````markdown
+---
+id: review.direction
+kind: investigation
+attention:
+  - id: experience
+    kind: decision
+    state: open
+    response_from: [maintainer]
+    reason: Choose the response reading experience and next action.
+    unblocks: [review.direction]
+---
+# Response reading experience
+
+Keep the proposal, reasoning and the affected work together.
+
+```mermaid
+flowchart LR
+  Proposal --> Choice --> RecordedDirection
+```
+
+::::question{id="display" select="one"}
+### Which reading experience should we build?
+
+:::option{id="latest"}
+**Latest response** — compact, with history behind a link.
+:::
+
+:::option{id="history"}
+**Full history** — keep the reasoning and superseding direction visible.
+:::
+::::
+
+::::question{id="checks" select="many"}
+### Which checks matter?
+
+:::option{id="back"}
+Back/forward preserves the selected response.
+:::
+
+:::option{id="reload"}
+Reload restores the reading context.
+:::
+::::
+
+:::question{id="next" select="text"}
+### What should happen next, and why?
+
+Name the rationale, affected work and next action in your own words.
+:::
+````
+
+These are remark directives, a Markdown extension rather than standard CommonMark. Use top-level question containers and direct option containers. Single-choice (`select="one"`, the default) and multiple-choice (`select="many"`) questions have 1–32 options; `select="text"` has no options. Each packet has at most 32 prompts. Prompt IDs are unique within a request, option IDs within a prompt; each is a literal identity of at most 128 characters. Unknown attributes, duplicate IDs, invalid modes, nested controls and orphan options reject the template visibly. Examples inside fenced code remain examples. Other Markdown components remain available in descriptions.
+
+If the document has several open attention requests, each question directive must name `request="experience"` (or another declared request) explicitly. Only matching prompts form that request's packet. Shared ordinary context is shown above them.
+
+## Human interaction and delivery
+
+Every prompt permits additional human text, including a text-only rejection of the supplied framing. Clearing selections is explicit. An answer needs either a selection or nonempty text for every prompt; clarification and deferral can explain why the packet cannot be answered yet. The author label is local attribution, not authenticated identity. Preview shows the complete Markdown and metadata before one submission registers context if needed and publishes one response.
+
+The response's optional `answers` list records `{ prompt, selected, text }` entries in template order. `selected` contains stable option IDs and `text` contains the human's Markdown. The server validates IDs, selection modes and completeness against the captured context. It constructs the readable response body from the reviewed prompt/option descriptions, human text and optional overall response. Template links are resolved against the source so moving the record into `responses/` does not reinterpret them. Per-prompt text is bounded to 8192 characters; the complete recorded body remains bounded to 32768 characters and captured context to 256 KiB.
+
+The existing CLI wait returns that one response, including typed answers, readable body, author and reviewed context. It does not emit independent partial replies or consume responses. Registration deadlines, repeatable reads and `--after` retain the same semantics; the lightweight waiter does not load the directive parser or renderer.
+
+## Changed context and superseding direction
+
+A source edit or move does not silently carry selections into another context. The UI preserves human text, clears choices and retains a copy of earlier answers for recovery. Drafts retain the existing 30-day/2-MiB browser-local workspace policy. An edit during a pending save remains a separate unsaved draft with its own identity.
+
+An optional `supersedes` identity explicitly links a new response to an existing response for the same item's request, including an earlier source revision. This creates another immutable record rather than editing history. The UI qualifies old contexts and links superseding direction; it never infers task status, closes attention, claims criterion acceptance or launches an agent. Missing/moved source requires reviewing and registering the available context; historical records remain readable through their registered question identity. Ambiguous or malformed history is unknown, not an empty answer list. This includes syntactically damaged or unterminated frontmatter in `responses/`, even when the parser cannot recover its record kind. Ordinary malformed Markdown outside that record namespace does not establish a response or block feedback reads.
+
+## Content and filesystem boundaries
+
+Rich context, option descriptions and saved history on the response surface use the existing Markdown/highlighting/Mermaid pipeline with raw HTML disabled. Source HTML cannot manufacture controls or initiate writes. Mermaid remains local and strict, with its source fallback when JavaScript is unavailable. The ordinary trusted-folder reader keeps its existing compatibility; browser recording still requires JavaScript and explicit server write opt-in.
+
+The Linux/macOS no-replace publisher, revision/path checks and explicit rejected/ uncertain outcomes preserve the independent source records. The [ownership boundary](./source-editing-examples.md) keeps normal project editing with agents. Handoff and direct-editing decisions belong in the roadmap.

package/docs/delivery/handoff-examples.md

@@ -0,0 +1,72 @@
+# Local handoffs and ordinary agent file editing
+
+A person can prepare reviewed direction as a Markdown file, then copy a short instruction into an existing agent session. The agent reads and edits ordinary files to record receipt. The [roadmap](../roadmap.md) owns implementation status, acceptance and decisions about extending this boundary.
+
+## One bounded walkthrough
+
+Review a uniquely identified project item. Open **Prepare an agent handoff**, enter recipient, goal, constraints and next action, then preview and prepare. The existing `--responses` opt-in permits the local writer to create `handoffs/<stable-id>.md`; the original project item stays unchanged.
+
+The file's frontmatter records direction and the reviewed source SHA-256. Its body contains the complete source, including original frontmatter and declared criteria. A focused item's context is bounded to 256 KiB of UTF-8. The page renders its Markdown/Mermaid body through the safe local context renderer and discloses the exact source separately.
+
+```markdown
+---
+id: handoff.search.keyboard.1
+kind: handoff
+handoff:
+  item: work.search
+  recipient: agent-navigation
+  state: requested
+  source: items/search.md
+  reviewed_revision: 691e2b8c3ca54cd66afa1533e9917cbef69e8a13a5bb79275abf65a101ee6dde
+  prepared_at: 1791319869349
+  goal: Fix keyboard focus
+  constraints: Preserve no-JavaScript links and local-only operation.
+  next_action: Inspect the current source and report browser evidence.
+---
+---
+id: work.search
+kind: task
+criteria:
+  - id: focus
+    text: Escape returns focus to the opening control
+---
+# Keyboard focus
+
+Keep the source readable.
+```
+
+This complete example captures `items/search.md`, beginning at its own second frontmatter block. Its reviewed revision is the SHA-256 of those captured bytes, including the final newline. The server assigns `prepared_at` when it prepares the record.
+
+**Copy tiny prompt** gives a JSON-quoted absolute path and the instruction to read that file and edit receipt. Paste it into the intended existing agent session. When clipboard permission is unavailable, the UI selects the prompt for manual copying. Preparing a file records `requested`; it does not notify, wake or launch an agent. Existing agent sessions can still poll or wait for human answers through the independent question/response commands.
+
+## Receipt and source ownership
+
+The agent edits `handoff.state` to `acknowledged`, `rejected` or `unavailable` and can add `handoff.by` and `handoff.note` through its usual file tools:
+
+```yaml
+state: acknowledged
+by: agent-navigation
+note: Received; execution has not started.
+```
+
+These fields belong inside the record's `handoff` mapping. Recipient and `by` are literal local labels, not authenticated identities. `requested` means the file was prepared and receipt remains unconfirmed. Silence does not establish rejection or unavailability; receipt establishes neither execution nor verified acceptance. The agent owns project edits outside human response content. Returned-result review belongs to the delivery requirements for step 19.
+
+Same-ID preparation retries preserve raw receipt bytes and extra metadata, even if the original source disappears. Different direction or a moved/duplicate record identity is a conflict. Initial preparation checks the reviewed source revision and path. Later reads qualify earlier or unavailable context and retain saved history. Malformed or ambiguous history stays unavailable; task status does not supply a missing receipt.
+
+Browser drafts share the existing 30-day/2-MiB workspace store. Clearing workspace drafts clears response and handoff drafts together, without deleting saved records. There is no special acknowledgment command, editor lock or universal transaction with unrelated editors.
+
+## Native integration
+
+The public `handoffSource`, `handoffs` and `prepareHandoff` operations use the existing `workRpcs` session. `browserClient` exposes them under `handoffs`, beside its reading and response bindings. Read the source preview before preparing it; the command takes the exact reviewed revision and logical source path. Creation requires the existing response-write opt-in. Ordinary receipt edits remain sufficient after publication.
+
+Consume the published defining modules rather than private `#` aliases or a second publisher. The [README](../../README.md#use-the-native-browser-client) shows a complete native-client preparation program. The source SHA-256 identifies reviewed content; it is neither a session/turn ID, a wire replay token nor a Git commit.
+
+## Optional execution integration boundary
+
+Work Board owns the stable work ID, reviewed context, relationships and human feedback. An execution integration can attach its own session/turn receipts, reservations and stages to that work ID. It must not create a competing work identity or reinterpret `handoff.state` as completed work, criterion acceptance or permission to merge. Board reading and response/handoff files remain usable without the integration.
+
+An existing-session notification hook would need an actual supported tool API, delivery/restart evidence and an owner. Explicit CLI launch would also introduce executable, working-directory, credential, model-cost and process-lifetime choices. Keep those choices in the roadmap until the maintainer selects a concrete contract. Provider commands, credentials and private configuration belong outside public source. A copied instruction never promises automatic agent continuation.
+
+## Evidence boundaries
+
+The roadmap links the service and DOM regressions. They establish the asserted file, RPC, draft/navigation and manual-copy behavior. A browser fixture does not establish representative-reader timing, independent model task execution, physical-device behavior or support for every harness. CLI availability is not delivery or receipt proof. The passive wait's deadline/resource evidence is separate from handoff publication.