@shivaedev/work-board 0.11.0 → 0.13.0

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 use effect-form’s seven-day/256-KiB browser-local per-draft 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 use effect-form persistence with a seven-day lifetime and 256 KiB limit per draft. Clearing the current draft restores its form’s initial values without deleting saved records or other drafts. 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: effect-form persistence keyed by workspace, item and request, a 256 KiB bound per draft, seven days after edit and explicit current-form clearing. 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 the ordinary GET route and the typed native `result` 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. [Result tests](../../src/server/results/result.spec.ts) cover HTTP reads, typed result queries, missing evidence, ambiguous identities and feedback pinned to exact report bytes and paths.
+
+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.

package/docs/delivery/source-examples.md

@@ -0,0 +1,129 @@
+# Optional source structure
+
+Work Board reads optional YAML frontmatter at the beginning of a Markdown file. The file remains authoritative; the in-memory identity/search index is rebuilt from readable files and invalidated by the watcher. No database, generated source files, cloud service, or migration is required. Parsing uses `yaml` 2.9.0 and Effect Schema. The UI reads this structure and never rewrites it.
+
+## Existing heading boards
+
+```markdown
+# Navigation delivery
+
+## In progress
+
+### Search the workspace
+
+Find document titles, headings, and passages.
+
+## In review
+
+### Remember reading state
+
+Evidence: [navigation PR](https://github.com/ShivaeDev/platform/pull/77).
+```
+
+Existing heading boards render as before. Section names are presentation, never inferred workflow transitions. An unannotated card has no durable identity, owner, acceptance decision, or machine-readable status. Its passage URL can change when its heading changes. Richer identity uses one file per item.
+
+## A richer item
+
+```markdown
+---
+id: work.search
+kind: task
+status: in-review
+owner: agent-navigation
+next_action: Review keyboard and mobile evidence
+criteria:
+  - id: keyboard
+    text: Escape returns focus to the opening control
+  - id: passage
+    text: A search result reaches the second duplicate heading
+relationships:
+  - kind: implements
+    target: decision.search-matching
+---
+# Search the workspace
+
+Use deterministic local matching first. Keep Markdown authoritative.
+```
+
+Every top-level field is optional. Missing values show as **Not recorded** in work details. `owner` records responsibility, without claiming authorship. `status` and `next_action` are explicit source text; no status vocabulary or transition rules are inferred.
+
+| Field | Source shape |
+| --- | --- |
+| `id` | Workspace-local, case-sensitive ID: ASCII letter/digit first, then letters/digits, `.`, `_`, or `-` |
+| `kind` | `task`, `investigation`, `decision`, `result`, `project`, `board`, `question`, `response`, or `handoff` |
+| `status`, `owner`, `next_action` | Nonblank strings |
+| `criteria` | List of `{ id, text }`; criterion IDs use the item ID syntax and are unique within the file |
+| `relationships` | List of `{ kind, target }`; kind is `implements`, `informs`, `depends_on`, or `relates_to`; target is an item ID or `item.id#criterion-id` |
+| `items` | Explicit list of item IDs declaring board membership, independent of status or section headings |
+| `evidence` | List of records described below |
+| `attention` | List of explicit request records; [shapes and reading rules](./attention-examples.md) |
+| `question`, `response` | Optional dedicated record provenance; [anchored response contract](./response-write-examples.md) |
+| `handoff` | Optional direction/source snapshot and explicit receipt; [ordinary-file handoff contract](./handoff-examples.md) |
+| `request_receipt` | Optional immutable acknowledgement of an exact managed decision request; [response and acknowledgement rules](../../README.md#record-a-human-response) |
+
+A unique ID resolves at `/_board/item/work.search/`. This URL survives file and heading renames while the ID remains unchanged and unique. A criterion resolves at `/_board/item/work.search/#criterion-keyboard`. Normal file and generated heading URLs continue working; favorites/recents still refer to file paths.
+
+Search includes declared ID, kind, status, owner, next action, and criteria. Results show source lines where known; criterion results open and focus the criterion's work-details context. Source diagnostics identify file/line, and **Original frontmatter** exposes the retained header.
+
+## Relationships and board declarations
+
+```markdown
+---
+id: decision.search-matching
+kind: decision
+status: proposed
+relationships:
+  - kind: informs
+    target: work.search
+---
+# Deterministic matching
+
+Option A: token matching with deterministic ranking.
+Option B: fuzzy ranking with additional tuning.
+
+Recommendation: A. A person's acceptance remains a separate decision.
+```
+
+```yaml
+id: board.navigation
+kind: board
+items: [work.search, work.reading-state]
+```
+
+Relationships and membership resolve only against explicit IDs. They are shown as readable links; unresolved or ambiguous targets stay visible with diagnostics. These declarations do not turn a section name into a workflow rule.
+
+## Criterion-level recorded evidence
+
+Each record requires a nonblank `source`. All other evidence fields are optional: `criterion` names an item or criterion reference; `checked_revision` is a full 40- or 64-digit hexadecimal Git revision; `observed_at` is a parseable ISO timestamp with a timezone; `method` and `outcome` are nonblank strings.
+
+```yaml
+evidence:
+  - source: ../evidence/browser-walkthrough.md
+    criterion: work.search#keyboard
+    method: real Chromium walkthrough
+    outcome: passed
+```
+
+This example deliberately has no revision or observation time; they remain **Not recorded**. Supply real values when available. Relative source links resolve from the file containing the record. HTTP(S) sources are ordinary links; executable URL schemes stay plain text. Local image sources use the contained PNG/JPEG/GIF/WebP attachment route described in the README; other non-Markdown assets are not served.
+
+Records are labeled **Source claims — not independently verified**. A recorded outcome, test link, agent run completion, or proposed decision does not establish verified acceptance. Work Board neither runs checks nor verifies freshness here.
+
+## Invalid, unknown, and unavailable sources
+
+- A header opens with `---` on the first line, optionally after a BOM, and closes with a separate `---` line. CRLF is supported. Scalar/list headers and unclosed headers retain the original Markdown and show a diagnostic.
+- YAML syntax errors, duplicate keys, unsupported tags, or excessive alias expansion leave the header uninterpreted and retain readable body prose.
+- Unknown top-level fields stay in the original header with a diagnostic. An invalid known field, including unknown nested keys, stays uninterpreted as a whole. Independent valid fields still render. No source bytes are rewritten.
+- Duplicate IDs show all matching source files and a conflict page; no winner is chosen. Duplicate criterion IDs do not receive selectable criterion links.
+- Missing IDs/criteria remain unresolved. Removing the source yields an explicit missing-item page. Removing or changing its ID does not preserve that identity.
+- If any listed file cannot be read, identity links report an incomplete index rather than asserting uniqueness. Readable documents and partial search remain usable; reference validation waits for a complete index.
+
+## Reading the reasoning and recorded claims
+
+Decision options, comparison tables, and rationale remain body Markdown. A result can declare `kind: implements` with `target: plan.search` in a relationship record; that plan can declare an `implements` relationship to `decision.search`. The reader reaches its rationale in two links without adding decision-specific frontmatter fields. `reasoningFixture()` in `src/test-support/reasoningFixture.ts` supplies the executable example with a plan, decision, result, ordinary evidence file, and shared board.
+
+Criteria list claims from all readable files that explicitly name their unique item/criterion reference. Claim counts are not acceptance counts. Records expose origin file/line and supplied provenance; old checked revisions remain visible without a comparison to current Git state. Missing/ambiguous criteria or an incomplete index prevent association rather than selecting a winner. Record anchors use their array position and can change on insertion/reordering.
+
+Source backlinks also include explicit Markdown hyperlinks and evidence-source paths, resolved relative to each source file, with `/` mapped to the configured home or first file. Code examples, external URLs, and self references are excluded. Plain files can show incoming links without acquiring an ID or inferred work kind. Evidence associations retain source links; image inspection follows the local attachment boundary described in the README.
+
+
+Questionnaire responses may additionally record `response.answers` entries with `prompt`, `selected` option IDs and human `text`, plus an optional `response.supersedes` identity. These fields are optional; older plain responses remain valid. See the [packet contract and complete source example](./decision-write-examples.md) for validation, reviewed-context binding and human selection semantics.

package/docs/delivery/visual-document-examples.md

@@ -0,0 +1,74 @@
+# Visual document conventions
+
+Work Board parses these directives with `remark-directive` and renders their body through its Markdown/GFM pipeline. These are Markdown extensions, not built-in CommonMark elements. Other readers can show literal directive markers and readable Markdown contents. No migration of ordinary Markdown or D1 frontmatter is required.
+
+## Fixed component vocabulary
+
+Use `:::metric`, `:::progress` or `:::timeline` containers. Start each with a nonblank Markdown label paragraph. Body text, links and emphasis remain Markdown. Attribute values are strings decoded with Effect Schema; unknown attributes are not interpreted. Values are recorded source claims, never verified acceptance.
+
+### Metric
+
+```markdown
+:::metric{value="50" unit="documents"}
+Representative fixture target
+
+Source: [Reading checks](browser-acceptance.md)
+:::
+
+:::metric{value="unknown" unit="seconds"}
+Representative-reader orientation
+
+Source: [Reader acceptance](../roadmap.md)
+:::
+```
+
+`unit` is required and nonblank. `value` is a finite number, `unknown`, or omitted. An unknown or omitted value displays “Not recorded”, never zero. Preserve a source paragraph beginning `Source:` with a Markdown link. Source links identify provenance; their existence or statements are not verified by the component.
+
+### Progress
+
+```markdown
+:::progress{completed="3" total="8"}
+Example reading checks recorded
+
+This tally records checks, not verified acceptance.
+
+Source: [Reading checks](browser-acceptance.md)
+:::
+```
+
+`completed` and `total` are nonnegative safe integers, `unknown`, or omitted. Known counts require `completed <= total`. Only a known positive total produces a native, labeled progress bar. Missing/unknown counts and 0/0 retain their explicit tally and say “Percentage unavailable”. Counts are never inferred from statuses, owners, task lists or criterion evidence. A `Source:` linked paragraph is required. A zero completed count is a recorded zero, not missing information.
+
+### Timeline
+
+```markdown
+:::timeline
+Reading delivery
+
+1. **First:** inspect [source conventions](source-examples.md).
+2. **Then:** review [response context](response-write-examples.md).
+:::
+```
+
+Use one ordered list containing 1–100 entries. Each entry needs text and a source link. Keep author order and literal labels, including planned/recorded qualifiers; do not parse dates, infer deadlines, schedule work or derive agent state. Timeline attributes are not supported. Ordinary Markdown emphasis and links remain intact. Mermaid continues to handle diagrams, including its own timeline diagram syntax.
+
+## Callouts and comparisons
+
+Use GitHub's five alert markers: NOTE, TIP, IMPORTANT, WARNING and CAUTION. Unknown markers stay ordinary blockquotes. Comparisons stay GFM tables, as D1 already specifies; colors, columns and ordering never select an option or assert an approval.
+
+```markdown
+> [!IMPORTANT]
+> A recorded browser result does not establish representative-reader acceptance.
+
+| Option | Benefit | Cost | Source |
+| --- | --- | --- | --- |
+| Ordinary Markdown | Familiar everywhere | Fewer visual affordances | [Source conventions](source-examples.md) |
+| Fixed directives | Explicit visual intent | An extension to document | [Delivery plan](wave1.md) |
+```
+
+## Fallback and ownership
+
+- Unknown/invalid containers, unknown attributes, missing labels/sources, invalid ratios and nonfinite values retain the complete original source as code with a local diagnostic. Later components and ordinary prose stay readable.
+- Inline/leaf visual forms are unsupported. Inline directives retain their literal source; unsupported leaf forms show source and a diagnostic. Unclosed or malformed syntax follows the established directive parser's reading rules.
+- A component is limited to 64 KiB of source. Nested visual directives are unsupported; original source remains visible.
+- Render fixed semantic elements on the server. No author-supplied JavaScript, JSX, executable MDX, templates, queries, plugin loading or remote data fetching.
+- Preserve headings, local links, search/backlinks, print text alternatives, native update ownership and the explicit Mark seen baseline. No source writes, new D1 fields, YAML visual fences or acceptance inference.