@shivaedev/work-board 0.11.0 → 0.12.0

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.

package/docs/delivery/reading-review.md

@@ -0,0 +1,27 @@
+# Reading workflow review
+
+Use this investigation to assess the combined reading experience, rather than accepting each feature from an isolated fixture. The [roadmap](../roadmap.md) owns status, observed evidence and maintainer judgments. This file describes a repeatable review; earlier observations remain in Git.
+
+## Read the actual project
+
+Serve the package's north star, roadmap and delivery requirements through an explicit reference-directory link. Read them at desktop and narrow viewports in light/dark themes and reduced motion. Follow the source relationships without JavaScript, then repeat with native navigation and real Mermaid enabled.
+
+Return to changed notes as a representative reader. Find the next judgment without coaching, explain what it unblocks, then follow its rationale and evidence. Record the elapsed orientation time and confusing moments separately from technical checks. A working queue cannot prove that a person understands its contents.
+
+## Exercise the combined boundaries
+
+Use the 50-document/100-item workspace from [browser acceptance](browser-acceptance.md), plus richer identity, attention and reasoning fixtures. Exercise search, favorites, duplicate-heading passages, external edits while paused, resume, offline changes and reconnect. Keep details open and selected text visible while navigating and refreshing. Rename/delete files and introduce malformed YAML; the board must explain missing or ambiguous source without hiding readable prose.
+
+Embed `boardLayer` beside an application health route in one Effect HTTP server. Check both routes, Work Board's page/asset loopback guards, and scoped server shutdown. The package's real HTTP embedding regression and packed consumer checks provide repeatable automated evidence; they do not prove a host application's adoption.
+
+For page-cache lifecycle, navigate away and return with Back. Record whether the browser actually restored a cached page and any refusal reason; a manually emitted persisted-pageshow event establishes only that handler's behavior. Test physical tab/device transitions separately. Record browser, viewport, input method, network state, actual Mermaid use and any limits.
+
+## Measure a named workload
+
+Agree a representative document/item count and reference machine. Record Node, OS, CPU, available memory, browser and competing workload. Measure first complete HTML response, cold and warm search separately, edit-to-searchable source, browser paint and interaction delay where available.
+
+Start fresh servers sequentially. State which process/filesystem caches were warm, which initial reads warmed the index, watcher debounce and polling interval. Use enough samples for any claimed percentile. Short warm-cache observations are not cold-start measurements or agreed budgets. Agree thresholds before enforcing a performance gate.
+
+## Record the conclusion precisely
+
+Place measured results, remaining acceptance and maintainer decisions in the roadmap. Separate automated behavior, actual browser observations, representative- reader feedback, physical-device evidence and host adoption. A source claim or completed run does not accept criteria. Keep exports and portable document packets outside the product direction; the investigation itself remains ordinary Markdown.

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

@@ -0,0 +1,32 @@
+# Local response contract
+
+Questions capture exact reviewed source bytes and path. Independent response Markdown retains human direction, while explicit write opt-in and browser-local drafts keep reading and publication separate. The [README](../../README.md#record-a-human-response) teaches the commands and current source/filesystem limits.
+
+## One real loop
+
+An agent records an explicit open attention request in `investigation.md`, then reads it with `work-board question investigation.model/review-model`. The command returns the full source, reason, generation ID and reviewed SHA-256 without writing or starting a deadline. `work-board wait investigation.model/review-model
+--revision <reviewedRevision>` registers that exact generation and waits.
+
+The person reviews the investigation, chooses **Respond to this request**, previews “Use explicit requests; preserve unknown evidence”, then records it. Question and response records are readable source files; the original investigation is unchanged. The wait returns one attributable JSON question/response with exit 0. If the shell was killed, repeating `work-board wait <question-id>` retrieves the same reply. No agent launcher, scheduler, acknowledgment protocol or verified acceptance is implied.
+
+## Current source records
+
+A question file has `id`, `kind: question` and `question` frontmatter. `question` contains `item`, `request`, `source`, `reviewedRevision`, `reason`, `registeredAt` and `deadline` (milliseconds). Its body preserves the exact original source bytes used for the hash. Generation identity includes item, request, reviewed hash and source path. The request and literal response-from labels still follow D1 attention rules; no owner/status inference is introduced.
+
+A response has `id`, `kind: response` and `response` frontmatter, with `question`, `reviewedRevision`, `author`, `type` (`answer`, `clarify`, `not_now`) and `recordedAt`. Its body is the authored Markdown. The label is local attribution, not authentication. An answer can say no; exit 0 means receipt of a reply, not approval. Recorded feedback remains distinct from criterion-level verified acceptance.
+
+## Failure and recovery
+
+A source change/rename during drafting preserves the text and shows the revision change. Previewing again binds a new response identity to the new reviewed generation; an old saved response never approves that new context. A changed source after the final check cannot be locked against every unrelated editor; records therefore retain the exact reviewed bytes rather than claiming a multi-file transaction or overwriting the editor's source.
+
+Publication runs on Linux and macOS with supported hard links/fsync; see the README for the macOS path-based limits. Read-only operation remains available elsewhere. New files publish without replacement; same-ID retries reconcile exact content. Moved/duplicated/conflicting identities, permission failures and changed/symlinked write boundaries are rejected. After a post-publication failure, an uncertain result retains the draft. Reconcile saved identity/content and directory synchronization before confirming a retry.
+
+Browser drafts are separate from Mark seen: one 2 MiB bound per workspace/origin, 30 days after edit, explicit clearing and expiry/storage failure disclosure. Saved source has no implicit retention deletion. A 48-hour unanswered deadline starts at durable registration; rearming/page visits do not reset it. It returns a distinct nonzero unanswered result, leaves the request intact, and permits a late reply. Service outages never establish that a person left it unanswered.
+
+Implementation, acceptance and handoff decisions belong in the [roadmap](../roadmap.md). The [ownership boundary](./source-editing-examples.md) keeps ordinary project editing with agents; a passive question wait is a reader for an existing harness.
+
+## Repeatable acceptance path
+
+Run `pnpm ready` for native types, regressions, the real local PostgreSQL suites and packed consumers. Start the production CLI against a disposable folder with an explicit attention request and `--responses`. Open Respond, enter a draft, reload, and modify the proposal externally. The draft must survive and require a new preview. Start concurrent `wait <item>/<request> --revision <hash>` commands; restart the server at the same port, kill and reattach one waiter, then record a reply. Every successful stdout result must name the same question generation and attributable reply. Repeating the wait must not consume it. Compare the original source bytes and inspect the independent Markdown records.
+
+Delay a successful response acknowledgment while typing another draft. Release it and reload: the later text must remain under a fresh response identity. Check narrow dark/reduced-motion layout and saved reply reading without JavaScript. For resources, sample `/proc/<pid>/smaps_rollup`, CPU ticks and descriptors for 20 registered idle waiters over five seconds, without concurrent repository handoff. Report PSS separately from summed RSS; neither a short idle observation nor an edited test deadline proves a 48-hour soak or automatic harness wakeup.

package/docs/delivery/result-review-examples.md

@@ -0,0 +1,108 @@
+# Review returned work through ordinary Markdown records
+
+A result is an ordinary file with `kind: result`, stable identity, explicit relationships, reported evidence and prose limitations. Review brings those sources together with human direction pinned to the exact report. The [roadmap](../roadmap.md) owns implementation status and acceptance; this file teaches the source and response contract.
+
+## Author the task and report
+
+Save this task as `items/task.md`:
+
+```markdown
+---
+id: work.keyboard
+kind: task
+status: in-review
+criteria:
+  - id: focus
+    text: Escape restores focus to its opening control
+  - id: narrow
+    text: Narrow layout stays readable
+---
+# Keyboard work
+
+Review the keyboard behavior and its recorded evidence before changing status.
+```
+
+The task declares two criteria and remains in review. Its source status is authored text, rather than a computed execution or acceptance state.
+
+Save the returned report as `items/result.md`:
+
+```markdown
+---
+id: result.keyboard
+kind: result
+status: finished
+relationships:
+  - kind: implements
+    target: work.keyboard
+attention:
+  - id: review
+    kind: review
+    state: open
+    response_from: [maintainer]
+    reason: Review this exact report and its limitations.
+    unblocks: [work.keyboard]
+---
+# Keyboard result
+
+The change is ready for review.
+
+## Evidence and limitations
+
+No keyboard or narrow-layout observation is recorded in this report.
+
+## Next action
+
+Review the missing evidence before deciding how to continue.
+
+::::question{id="verdict" select="one"}
+### What should happen with this report?
+
+:::option{id="revision"}
+Request another revision and explain the missing evidence.
+:::
+
+:::option{id="accept"}
+Accept this exact report version with its stated limitations.
+:::
+::::
+```
+
+This complete report deliberately contains no `evidence` records. Both criteria remain without recorded claims, even if a human accepts the report iteration with its stated limitations. Record actual observations and their supporting source only after they exist; the [evidence reference](source-examples.md#criterion-level-recorded-evidence) defines those optional fields.
+
+The open `review` attention request explicitly asks for judgment. Its two `verdict` options are authored labels, not reserved schema values. A person can choose a revision or this report version, add rationale, or reject the framing with text. The [packet contract](decision-write-examples.md) defines completeness, selection and source binding.
+
+## Review beside the source
+
+Open **Review returned result** on the report, or `/_board/result?item=result.keyboard`. A uniquely identified readable result uses both the ordinary GET page and the existing native page query. The report status is shown separately from its linked task's status. Neither report status nor a handoff receipt verifies execution or authorizes a merge.
+
+The page lists explicitly linked criteria, this result's claims, missing provenance, report/limitations and recorded human feedback. An unresolved or duplicate identity does not choose a convenient source. A missing local Markdown evidence source remains disclosed. Report and feedback context use the safe Markdown reader; exact reviewed source remains available separately.
+
+Choose the report's explicit review request to use the existing response surface. Review the exact source, preview and submit one complete response. That response captures the source path and SHA-256 of the original report bytes. Work Board leaves the project task and report unchanged.
+
+## Read or wait through the existing agent interface
+
+```sh
+work-board question result.keyboard/review
+```
+
+This reads the current question/context without registering it. For the complete LF report above, including its final newline, the reviewed SHA-256 is `49a45f23df2f56d8720c0fd8f8c86483a86f5b8eb016c1d17db4a56152f72060`. Inspect that context before registering the wait:
+
+```sh
+work-board wait result.keyboard/review --revision 49a45f23df2f56d8720c0fd8f8c86483a86f5b8eb016c1d17db4a56152f72060
+```
+
+The server must be running with `--responses` for registration and replies. A successful wait returns the same immutable question/response records as the browser. Its question ID supports later `response` reads, repeatable reattachment and the explicit next-reply cursor described in the [README](../../README.md#wait-for-an-attributable-reply). Feedback receipt is independent of automatic agent continuation.
+
+## Keep feedback on its reviewed report
+
+Feedback whose registered source path and SHA-256 both match the current report is labeled **Feedback on this exact result revision**. An ordinary edit creates a new report revision. Moving the report also qualifies earlier context, even when its bytes stay unchanged. The previous feedback and its exact reviewed snapshot remain inspectable; neither silently applies to the new report.
+
+After an agent records a revision, the next response can explicitly supersede the prior revision request. Supersession links immutable direction rather than rewriting history, task status or evidence. Malformed or ambiguous response history stays unknown instead of establishing that no feedback exists. Actual moved record paths remain the targets of source and supersession links.
+
+`evidence.checked_revision` is a reported full 40- or 64-digit Git revision. It is distinct from the report's content SHA-256. Work Board does not inspect the checkout or compare that reported revision with current Git state; evidence freshness remains unknown. Pinned report feedback does not verify a linked artifact. Closing attention, finishing a run, acknowledging a handoff and human acceptance remain separate facts.
+
+## Preserve the execution boundary
+
+Work Board owns source identity, reviewed context, relationships and human feedback. An optional execution integration may attach session/turn receipts and stages to the same work ID. It does not acquire authority to change criterion acceptance from a report status or chosen option. The existing metadata, question packets and independent response publisher carry result review; a second task ledger or acceptance writer would create a competing source of truth.
+
+The [handoff contract](handoff-examples.md#optional-execution-integration-boundary) and [ordinary editing ownership](source-editing-examples.md) define that boundary. The roadmap owns optional adapter admission and the complete coordination-loop acceptance. Regression fixtures establish their asserted behavior, rather than representative-reader timing, independent model execution or adoption.

package/docs/delivery/source-editing-examples.md

@@ -0,0 +1,32 @@
+# Ordinary file editing and response ownership
+
+Agents use their normal file-editing tools. Work Board adapts to those edits and owns the human response content it records. Product complexity should follow the coordination workflow, not rare concurrent-writer edge cases.
+
+## Ownership
+
+- Agent/project changes win outside the human response area: reasoning, task text, evidence, titles, checklists, status, and other surrounding Markdown.
+- Human response content wins within its own response area. Recording feedback does not give Work Board ownership of the rest of the document.
+- Agents do not have to use a special mutation command, cooperative lock, acknowledgment command, or editor protocol to edit files.
+- A ready-for-review question is normally answered while the agent is waiting, rather than deliberately editing that question at the same time.
+
+The current publisher creates independent question/context, response and handoff Markdown files. Agents edit handoff receipt through ordinary tools. This ownership rule preserves that implementation; it does not introduce an inline-response syntax or silently rewrite an agent's project document. If an inline response area is introduced later, the same ownership rule applies within the shared file.
+
+## Concrete example
+
+An agent adds keyboard evidence to its investigation while the person drafts:
+
+```markdown
+Use the full history view. Keep the keyboard evidence and proceed.
+```
+
+Work Board records that human direction in the response. The agent's investigation and new evidence remain authoritative. The response does not rewrite the item, change its status, close attention, or establish acceptance. The agent reads the feedback and updates its project Markdown using its ordinary tools.
+
+If future response editing shares a file, re-read the current content and change only the owned response area, retaining the agent's surrounding edits. Preserve the draft and explain a detected stale target or ordinary save failure. Do not restore an obsolete whole-file snapshot to implement undo.
+
+## Best-effort engineering
+
+Keep practical revision checks, drafts, ordinary filesystem failures and the local workspace boundary. Do not require a universal transaction with every outside editor, a native exchange/backup engine, or a special agent workflow as prerequisites for progress. Rare racing saves and possible text loss are accepted limitations of ordinary file editing. Detect obvious conflicts when inexpensive; avoid making every response a concurrency-management interaction.
+
+These are ownership priorities. They do not define an inline-response serialization or universal filesystem guarantees. Implementation and direct-editing/handoff decisions belong in the [roadmap](../roadmap.md). A handoff must let the chosen agent read and edit ordinary files; a required command for every acknowledgment would contradict this boundary.
+
+The [file/copy handoff contract](handoff-examples.md) carries reviewed direction without replacing the project item. An optional harness delivery or execution integration must preserve ordinary receipt edits and separate execution facts; it cannot acquire authority to accept work from a receipt state.