@shivaedev/work-board 0.10.0 → 0.12.0

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.

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.

package/docs/delivery/wave1.md

@@ -0,0 +1,66 @@
+# Wave 1 delivery — stay informed
+
+The [delivery plan](./README.md) explains gates and verification. These steps define the reading outcomes tracked in the [roadmap](../roadmap.md). This wave concerns reading and personal view state. Agents keep writing files through their existing tools. Follow numeric order unless the prerequisites below permit a useful independent change.
+
+## 01 A real workspace shell
+
+**Outcome:** opening the existing folder feels like a navigable workspace. Replace the wrapping top bar with a collapsible sidebar and breadcrumbs; use a readable document measure and a wider board canvas. Introduce shared color, spacing, typography, density, and light/dark/system theme tokens. Keep existing routes and `--home` behavior. Add the representative workspace and browser acceptance path alongside this visible change, not as a standalone framework. [Browser acceptance](./browser-acceptance.md) uses the shared large-workspace fixture. **Depends on:** the vision. **Accept:** 50 documents do not push the content out of reach; keyboard focus, narrow screens, diagrams, and live updates still work.
+
+## 02 Document locations and reading state
+
+**Outcome:** users can point to a passage and return without losing their place. Add heading anchors, an outline, active-file/title treatment, back/forward behavior, favorites, and recents. Resolve relative links from the source file, including a nested home file served at `/`. Preserve selection, open details, and scroll when navigating back. Scope local preferences to the workspace. **Depends on:** 01. **Accept:** duplicate headings have unambiguous anchors; encoded filenames work; a deleted target explains what happened. Document that generated heading anchors can change after a rename; durable item IDs come in 04.
+
+## 03 Find work from anywhere
+
+**Outcome:** one search locates a phrase, document, or heading across the folder. Add a keyboard-opened search/command dialog with snippets, explicit result types, empty results, and navigation to the matching passage. Begin with a small rebuildable text index and deterministic matching. Refresh it on file changes. Offer source-in-editor navigation only through an agreed local editor mechanism. **Depends on:** 02. **Accept:** a known phrase is findable in the large fixture; keyboard selection and Escape restore focus; stale requests cannot replace newer results. Review 01–03 with real project notes before expanding the model.
+
+## 04 Optional identity and a rebuildable index
+
+**Outcome:** richer work is recognizable without making plain Markdown invalid. Prepare D1's examples, then implement the agreed read-side schema and source locations. Model optional IDs, item kind, status, owner, next action, relationships, criteria, and evidence provenance as needed by the first real examples. Reuse and extend 03's index. Display useful diagnostics for malformed metadata, duplicate IDs, and unresolved references while keeping prose readable. **Depends on:** 03 and D1. **Accept:** existing boards render unchanged; the index rebuilds entirely from files; unknown metadata is not guessed or silently lost.
+
+## 05 One body of work, several views
+
+**Outcome:** document, board, and table offer consistent views of the same items. Add multiple board selection, filtering/sorting, saved local views, compact mode, and a side detail pane. URL state restores the view and selected item. Use the agreed board declaration to separate a view from a status; a section name alone must not become an inferred workflow rule. No dragging or content writes yet. **Depends on:** 01 and 04. **Accept:** counts and selections agree across views, filters remain applied during updates, and a disappearing selection is explained. Split board/detail and table/saved-views into two PRs if each needs a large review.
+
+## 06 Follow the reasoning and the evidence
+
+**Outcome:** a result leads to its criteria, plan, decision, and supporting files. Render decision options, rationale, backlinks, dependencies, and criterion-level evidence. Show origin, checked revision, and observed time where explicitly provided. Missing evidence and an agent's unsupported claim remain distinct from verified results. Begin with readable links; inline asset previews arrive in 10. **Depends on:** 04–05. **Accept:** the sample result reaches its source rationale in two navigation steps; broken links and evidence for an old revision stay visible.
+
+
+## 07 An attention-first overview
+
+**Outcome:** returning users can identify the next judgment without reading a log. Derive queues for explicit decision requests, blockers, and review requests. Each entry names why it appears, whose response is needed, and what it unblocks. Use simple visible ordering and link directly to 05/06's context. Include quiet and empty states. Do not treat file churn, heartbeat, or a finished agent run as progress. **Depends on:** 05–06. **Accept:** representative users can find the intended next judgment within the proposed 30-second target; ambiguous items stay unclassified.
+
+
+## 08 What changed since I last looked
+
+**Outcome:** readers distinguish meaningful changes from an unchanged busy process. Track local last-viewed markers and compare retained source revisions for explicit field/content changes. Show additions, removals, changed decisions, and evidence updates with source links. Define bounded retention and clearing before retaining snapshots. If history is unavailable, say so; modification time is not a diff. **Depends on:** 04 and 07. **Accept:** a returning view summarizes a known sequence of edits correctly; a first visit, cleared storage, or renamed source never invents history or authorship. No durable event journal is required.
+
+
+## 09 Live updates that preserve orientation
+
+**Outcome:** the workspace stays current without disturbing active reading. Use changed paths to invalidate affected documents, derived views, search results, and backlinks. Keep navigation updates when files are added/deleted. Add pause, pending-change count, restrained highlighting, and resume. Recover with a full reconciliation after reconnect or uncertain watcher state; never trust a path-only optimization when events may have been missed. **Depends on:** 05–08. **Accept:** unrelated edits avoid full active-document rerenders; focused controls, open details, and diagrams survive relevant changes; paused and reconnecting states catch up without claiming stale data is current.
+
+
+## 10 Local visual evidence
+
+**Outcome:** screenshots and diagrams are inspectable inside the work context. Serve an explicitly allowed set of local attachments with root containment and correct media handling; watch their changes as well as Markdown. Resolve paths relative to source files. Add image preview/gallery and Mermaid zoom, fullscreen, and local image/diagram downloads, with useful load/parse errors and keyboard dismissal. **Depends on:** 02 and 06; can precede 07–09 if needed by actual evidence. **Accept:** local images render and update; traversal/symlink escapes are refused; large diagrams can be read on narrow screens without losing the source context.
+
+
+## 11 A small vocabulary for visual documents
+
+**Outcome:** plans can communicate through comparisons, callouts, and progress. Implement the agreed readable conventions for callouts, option comparisons, metric/progress blocks, and a simple timeline. Use existing semantic data where possible. Keep the initial component list fixed, with text alternatives and no arbitrary executable content. Counts and metrics must name their source; unknown values should not display a fabricated percentage. **Depends on:** 04, 06, and 10. **Accept:** the real project brief communicates its plan using these blocks, remains useful in a text editor, and degrades intelligibly when a component's input is incomplete. Complex composition waits for 23.
+
+
+## 12 Start with useful project documents
+
+**Outcome:** a new user can begin locally and read useful project and agent reports. Provide copyable Markdown templates for a project, investigation, and agent result; useful empty-state instructions; and preserve basic browser print readability. Reports are ordinary source documents read through normal Work Board views, with links to plans, decisions and recorded criterion-level evidence. No report format creates verified acceptance or a new execution/handoff protocol.
+
+Document export is outside product scope: external shareable artifacts, portable snapshots and meeting packets have no demonstrated Work Board use case. Do not build HTML/PDF/ZIP packet generation, export previews, selection manifests, or a deferred export feature in another wave. Native browser printing remains a reading affordance, not a PDF service or artifact builder. An `init` CLI command still needs a separate API decision; copyable templates do not write source files. **Depends on:** 07 and 10–11. **Accept:** start from an empty folder, use the copyable templates through an existing editor/agent tool, and inspect the resulting project, investigation and result in ordinary Work Board views. Unknown outcomes and recorded evidence remain distinct from verified acceptance; the viewer does not create source files or mark history seen implicitly.
+
+
+## 13 Prove the complete reading workflow
+
+**Outcome:** wave 1 is a dependable tool, not only a convincing demonstration. Use it for real project notes while agents update the source through existing tools. Exercise the full large/empty/malformed fixtures, reconnects, rename/delete, keyboard focus, contrast, reduced motion, desktop/narrow layouts, and embedding. Measure agreed performance budgets and preserve all existing package guarantees. **Depends on:** 01–12. **Accept:** record the roadmap's wave 1 exit evidence and remaining limitations. Assess response/source ownership against the concrete examples; do not fix usability gaps by adding an agent execution engine.
+
+Use the [repeatable reading review](./reading-review.md) to gather technical, reader and device evidence. Record results and scope decisions in the roadmap.

package/docs/delivery/wave2.md

@@ -0,0 +1,43 @@
+# Wave 2 delivery — inform back and coordinate
+
+These requirements define contextual response and coordination outcomes. The [roadmap](../roadmap.md) owns completion and discussion decisions; the [delivery plan](./README.md) identifies the material needed for each review. Prefer one dependable response loop over many editing controls.
+
+## 14 Prove one safe source mutation
+
+**Outcome:** publish one intended source record without losing reviewed work. Use explicit question identity and expected revision. Preserve the agent-authored project document, revalidate workspace access, publish the new record without replacement, and expose typed rejection or an uncertain save outcome. A reviewed source can change after preflight; the independent record retains that context without claiming a transaction with every outside editor. Prove reconciliation and ordinary failure recovery, and document the filesystem limits. **Depends on:** 13 and D2. **Accept:** stale and competing writes, write failures, renames, permission failures, and repeated submissions cannot silently discard user content or report success without a known persisted result. Add a minimal visible action in this PR so the command is exercised through the real server.
+
+## 15 Respond to the exact thing you reviewed
+
+**Outcome:** feedback belongs to the proposal or result that prompted it. Build the agreed anchored response and revision-request surface over 14. Bind responses to the item and reviewed source revision; retain drafts during refresh, navigation, and recoverable failure. Show pending, saved, rejected, and uncertain outcomes distinctly. Recheck the content trust model and new write authorization; read-mode raw HTML must not gain permission to trigger edits simply because it is served by the same local application. **Depends on:** 14. **Accept:** changing the proposal while a response is drafted preserves the draft and identifies the revision difference before submission; failed submission does not clear input or produce a false saved confirmation.
+
+## 16 Record a decision and its consequence
+
+**Outcome:** a choice creates durable direction that the next contributor can use. Turn 06's read-only decision comparison into a decision action with selected option, rationale, reviewed revision, affected work, and next action. Show what will be recorded before saving. Distinguish a superseding decision from editing history. Keep this single-file where possible; do not automatically rewrite every affected task to simulate cross-file transactions. **Depends on:** 06 and 15. **Accept:** the choice survives reload and appears in linked context; a changed proposal does not inherit an earlier approval without qualification. Demonstrate recovery when the source moves or disappears.
+
+## 17 Narrow editing and honest undo
+
+The [ownership boundary](./source-editing-examples.md) keeps project edits in ordinary agent tools. Consult the roadmap before adding direct editing controls; the requirements below define what such controls would need to preserve.
+
+**Outcome:** routine updates no longer require leaving the work context. Add create/title/checklist/status actions one at a time through the same command path. Add explicit move controls, then optional drag-and-drop with the same keyboard behavior. Preserve unrelated formatting and meaningful source order. Offer undo based on the actual saved change and current revision; retain later editor or agent changes rather than restoring an entire obsolete file snapshot. **Depends on:** 14–16. **Accept:** edits round-trip to readable Markdown; an edit followed by another writer's change either undoes safely or explains the conflict. Keep cross-file moves and automatic one-file-per-item migration out until their partial-failure and recovery behavior has its own design and proof.
+
+## 18 One local agent handoff
+
+**Outcome:** one existing agent tool can receive complete direction and acknowledge it. Use D3's ordinary Markdown direction and copied instruction for an existing session. Carry goal, constraints, source path/revision, acceptance criteria, recipient, and next action. Record requested, acknowledged, rejected, and unavailable states. Use a handoff identity to recognize retries without creating duplicate work. An acknowledgment means receipt, not completed execution or accepted results. The [D3 walkthrough](./handoff-examples.md) defines ordinary receipt edits and copying a tiny prompt into an existing session. Preparing it does not launch agents. **Depends on:** 15–16, the ownership boundary, and D3. The agent must be able to acknowledge by editing ordinary files; a special writer or acknowledgment command cannot be mandatory. **Accept:** send one real handoff, observe receipt, and exercise unavailable tool, duplicate request, and lost-acknowledgment cases. Never silently switch agent/tool or assume a timed-out request was not received.
+
+## 19 Review a returned result against its criteria
+
+**Outcome:** the agent's result becomes inspectable work requiring explicit review. Receive artifact/source references, checked revisions, criterion-level claims, supporting evidence, and stated limitations. Keep execution state separate from work state. Support request-revision and explicit human acceptance through 15–16's versioned response path. Surface stale evidence or changes after review without silently carrying acceptance to a new result. **Depends on:** 06, 10, and 18. **Accept:** a returned run can be finished while its item remains in review; missing evidence stays missing; a human requests a revision, receives a new result, and accepts the specific reviewed version.
+
+The [ordinary-file result review walkthrough](./result-review-examples.md) composes existing result, attention, directive question and immutable response formats. Report status, work status and authored acceptance remain separate. Changed report contexts qualify earlier feedback; checked Git evidence revisions remain reported and are not compared with the current checkout. The roadmap records actual acceptance evidence and limits.
+
+## 20 Complete the first coordination loop
+
+**Outcome:** one real feature moves from proposal to accepted result locally. Run a real bounded feature through decision, handoff, acknowledgment, result, revision request, second result, and acceptance. Include a restarted browser/server, an offline/unavailable agent tool, and an editor changing a relevant file. Verify that another agent can resume from the resulting files without reconstructing a chat history. Record remaining failure modes and revise the interaction design. **Depends on:** 14–16 and 18–19, with the source ownership decision guiding 17. **Accept:** the roadmap's wave 2 exit is demonstrated with real source/evidence and no silent overwrites. Only then plan multiple contributors and broader adapters. This does not imply production-grade concurrent co-editing.
+
+## Deliberate exclusions
+
+No general rich-text editor, hidden task database, arbitrary script execution, agent scheduler, full terminal UI, or external two-way synchronization. The browser, local CLI/API, and tool adapter must share mutation semantics rather than invent parallel write paths. Use existing Effect and Platform conventions where needed; choose concrete API names and transports at their design gates.
+
+## Source contract references
+
+The [response contract](./response-write-examples.md) uses independently published question/response records, rather than replacing an agent’s project document. The [packet reference](./decision-write-examples.md) explains complete typed answers and explicit supersession. The [ownership boundary](./source-editing-examples.md) keeps ordinary agent file editing sufficient. Implementation status and acceptance evidence belong in the roadmap.

package/docs/delivery/wave3.md

@@ -0,0 +1,31 @@
+# Wave 3 delivery — collaborate locally
+
+These requirements extend [wave 2](./wave2.md) with successive contributions. The [roadmap](../roadmap.md) owns implementation status and admission decisions. Step 21 is the core collaboration outcome. The remaining steps are independently useful extensions; especially 24–26 should earn their place rather than block local collaboration.
+
+## 21 Successive contributions with clear ownership
+
+**Outcome:** several agents and a person can contribute without obscuring who owns the next action. Extend 18–19's single-contributor loop to explicit transfer, contribution references, conflicting proposals, and a visible current owner. Retain the expected source revision for every contribution and response. Start with coordinated turns and merges of reviewable proposals; simultaneous text co-editing is not a prerequisite and would need a separate design. **Depends on:** 20. **Accept:** two real contributors act on the same work, one stale contribution is identified, and the person resolves the next handoff without losing either proposal. An unavailable owner is visible, not reassigned silently. No remote multiplayer or new execution infrastructure is introduced.
+
+## 22 Several local projects, one attention view
+
+**Outcome:** a person can find the next judgment across explicitly selected local workspaces. Aggregate the attention/read model, preserving project-qualified IDs, source roots, per-project preferences, and independent availability. Opening a result returns to its original workspace and exact context. Scope folder access explicitly; do not scan the user's machine or widen serving to every filesystem. **Depends on:** 07–09 and 21. **Accept:** identical item IDs in two projects do not collide; one unavailable folder does not hide the others or route an action into the wrong project. Keep writes owned by the originating workspace.
+
+## 23 Richer plans and linked reviews
+
+**Outcome:** larger work can be understood and reviewed as a coherent whole. Extend the fixed component vocabulary with bounded split layouts, dependency maps, and timelines where explicit relationships/dates support them. Distinguish unknown dates from estimates and commitments. Help a reviewer follow linked plans, decisions, criteria, evidence, revisions and limitations inside the normal workspace. **Depends on:** 11–12 and 19. **Accept:** a reviewer follows those source links and sees missing or stale evidence clearly. Cycles and unresolved dependencies are shown. Shareable/exported packets are outside scope. Do not grow a freeform executable dashboard or plugin system to implement these views.
+
+## 24 One optional read-only GitHub adapter
+
+**Outcome:** a linked PR's current evidence no longer requires repeated copying. At D4, pick one repeated workflow and specify its authoritative fields. Read only explicitly linked PRs and their checks/review/merge state; record checked commit, last successful observation, refresh failures, and provenance. Keep credentials outside project content and make opt-in/out explicit. Local plans and decisions remain authored locally; the adapter does not overwrite them. **Depends on:** 19 and D4; can proceed independently of 22–23 after wave 2 exits. **Accept:** a changed PR revision makes old check evidence stale; unavailable or unauthorized GitHub access leaves the local board usable. No organization crawl, issue replication, write-back, cloud service, or generic connector framework.
+
+## 25 Read existing local test and build artifacts
+
+**Outcome:** locally produced results can support criteria without manual prose. Select one actual machine-readable report produced by the project's existing commands. Parse it through the same provenance/evidence model, including run identity, relevant source revision where available, completed/partial state, and failures. Observe results; do not turn the board into a command runner. Add another format only after the first reader proves useful. **Depends on:** 10 and 19; independent of GitHub adapter adoption. **Accept:** an interrupted report is incomplete, an unrelated revision does not verify the current work, malformed input yields a useful diagnostic, and deleting the artifact makes the evidence unavailable rather than leaving an eternal pass.
+
+## 26 Quiet rules and a real collaboration review
+
+**Outcome:** stable, explainable signals reduce attention overhead. Start with one observed need, such as surfacing a newly reviewable result. Show the source fact, the reason a rule fired, and its last action. Deduplicate unchanged events and allow disabling the rule. Rules may surface or suggest; handing off work or accepting results requires an explicit authority policy agreed separately. **Depends on:** 21 and a reliable trigger from 19, 24, or 25; no adapter is mandatory. **Accept:** repeated identical observations remain quiet, recovery does not flood the queue, and every surfaced item explains itself. Complete a real collaboration review, compare orientation/response effort with the earlier workflow, and retain only extensions that remove demonstrated friction.
+
+## Stop conditions for scope growth
+
+Pause an adapter or advanced view if it requires a second source of truth, organization-wide synchronization, a hosted component, or more maintenance than the manual step it replaces. Keep the existing local workflow complete when any extension is disabled. Expand only from observed use, not feature parity with a project-management suite. Release timing and additional API/package choices stay with the maintainer.