@shivaedev/work-board 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -8,6 +8,50 @@
   and delivery scope. Keep onboarding/report templates and linked in-app review.
 - Record the approved Platform-first live client direction and its actual shared HTTP/browser fixture evidence; Work Board adopts that foundation in 0.5.0 below.
 
+## 0.9.0 - 2026-10-06
+
+### Added
+
+- Agent-authored question directives with rich Markdown/Mermaid context, single-
+  and multiple-choice controls, open-text prompts and additional human text.
+  Submit one validated packet through the existing native response/wait path;
+  record optional typed answers alongside a readable Markdown account.
+- Explicit superseding responses with linked immutable history. Qualify earlier
+  reviewed contexts and preserve draft text/recovery while clearing selections
+  after a source edit or move. Keep legacy question/response files valid.
+
+### Changed
+
+- Render response context and history through the existing Markdown pipeline with
+  raw HTML disabled, retaining local strict Mermaid and no-JavaScript source
+  fallback. Resolve template links against the source before recording answers.
+- Scope in-memory drafts and their clearing to the workspace as well as persisted
+  storage. Keep existing retention, write opt-in, Linux publisher and wait limits.
+
+## 0.8.0 - 2026-10-06
+
+### Added
+
+- Explicit `--responses` / embedding opt-in for anchored local feedback with
+  separate immutable question/context and response Markdown records. Preserve
+  reviewed revisions and original source bytes; reject stale/conflicting writes
+  and distinguish pending, saved, rejected and uncertain outcomes.
+- Browser-local response drafts with a separate 2 MiB workspace bound, 30-day
+  retention since edit, explicit clearing and unavailable/expiry disclosure.
+- Native RPC `question`, `response` and per-question `wait` CLI commands, with
+  durable 48-hour registration deadlines, clarification/deferral, late replies,
+  nondestructive reattachment and an explicit next-response cursor. The waiter
+  bundle excludes server/rendering/watchers and transfers only the next reply.
+
+### Changed
+
+- Keep the default server read-only. The first safe publisher requires Linux
+  directory descriptors, hard-link publication and directory synchronization;
+  other platforms retain reading support. Reference symlinks do not grant writes.
+- Block source form actions/frames at the content-security boundary and require
+  native NDJSON for the opted-in command route. Existing readable Markdown,
+  static raw HTML, local visuals and no-JavaScript reading remain supported.
+
 ## 0.7.2 - 2026-10-06
 
 ### Changed

package/README.md

@@ -14,8 +14,7 @@ getting-started guidance at `/`. **Getting started** in the
 sidebar remains available at `/_board/start`, with copyable project, investigation
 and agent-result Markdown templates. Focus a template text area, select all and
 copy; save through your editor or agent tool. Replace example IDs and matching
-references, and record evidence only after an actual observation. The viewer
-does not create project files. Templates and links also work without JavaScript.
+references, and record evidence only after an actual observation. Read-only mode does not create project files. Templates and links also work without JavaScript.
 Browser print focuses on the document; document export is outside product scope.
 
 It listens on `127.0.0.1` only and answers only requests addressed to a loopback
@@ -63,8 +62,101 @@ preference says otherwise. A keyboard skip link moves directly to the content.
 | --- | --- | --- |
 | `<dir>` | required | The folder to serve. |
 | `--port` | `4747` | The port on `127.0.0.1`. `0` picks a free one. |
+| `--responses` | `false` | Explicitly enable local question/response writes. The first writer requires Linux, a real workspace directory, `/proc/self/fd`, hard links and directory synchronization. Reading remains available on other supported Node platforms. |
 | `--home` | none | The file shown at `/` as a board, relative to the folder. The command stops with an error unless it leads to one of the markdown files listed from the folder. Without it, `/` shows the first file as a document. |
 
+## Local responses and one logical wait per question
+
+Start one shared server with explicit write opt-in:
+
+```sh
+work-board ./project-notes --responses --port 4747
+```
+
+Use an existing explicit open attention request. In its **Work details and source**,
+choose **Respond to this request**, review the exact source and SHA-256, enter a
+local author label, and preview the Markdown before recording it. An answer may
+say no; **Ask back / clarify** and **Not now** are separate reply kinds. These
+labels are not authenticated identities. Recording a reply never changes source
+status, closes an attention request, executes an agent or establishes acceptance.
+
+The app creates immutable question/context and response Markdown files in
+`responses/`. Original documents remain untouched. Questions identify the item,
+request, source path and exact bytes reviewed; changing either the source bytes or
+path creates a different generation. A stale save retains the draft and requires
+review/preview again. The preview names both files and all authored fields; the
+server assigns registration and recorded timestamps when saving.
+
+Drafts use separate browser-local storage per workspace/origin: 2 MiB total and
+30 days since the last edit. **Clear workspace drafts** affects drafts, not saved
+source or Mark seen history. Expiry, corrupt/unavailable storage and quota failures
+are disclosed. Text remains in the current window after a storage/save failure.
+Navigation, reload and live source refresh preserve retained drafts; changed
+context must be previewed again. Another unsaved edit made during submission is
+retained. Saved feedback also remains readable without JavaScript.
+
+An agent uses these short command names against the shared server:
+
+```sh
+# Read the exact current question/context and its reviewedRevision (no write).
+work-board question investigation.model/review-model
+
+# Register that reviewed generation and wait for one attributable reply.
+work-board wait investigation.model/review-model --revision <reviewedRevision>
+
+# After registration, repeat this same wait after a killed shell or restart.
+work-board wait <question-id>
+
+# Retrieve the saved conversation without waiting or consuming any reply.
+work-board response <question-id>
+
+# After a clarification/deferral, wait for the next response explicitly.
+work-board wait <question-id> --after <response-id>
+```
+
+`--port` selects another local workspace/server; `--url` accepts only an HTTP
+loopback origin. There is no hidden workspace discovery or automatic server launch.
+Register-and-wait reports its stable question ID and deadline on stderr. Its stdout
+is one JSON result containing the attributable question/context and response;
+exit 0 means a recorded reply, including no/clarification/deferral, not approval.
+Exit 2 reports an unanswered 48-hour deadline; other failures exit nonzero with
+stderr diagnostics. `question` and `response` are explicit read commands.
+
+The human deadline starts at first durable registration and does not reset when
+rearming, revisiting a page or previewing. A deadline never deletes/cancels the
+question. Late replies remain readable and take precedence over an old timeout.
+A missing cursor fails explicitly. Replies can be read repeatedly; this provides
+recovery, not exactly-once agent action. The server's 30-second request leases and
+one-second reconciliation checks are distinct from the human's 48-hour deadline.
+During a transport/index outage, waits retry the same question; at the deadline,
+an unavailable service is reported as unavailable rather than falsely unanswered.
+
+The client uses bundled native Effect RPC over the existing local command path.
+Serving imports are loaded only for the server command. Each waiter has no
+renderer, Mermaid, filesystem watcher, AtomRegistry or daemon. A pending lease
+returns only its question and next reply, not the entire conversation history.
+Harnesses own model wakeup and shell lifetime: completion is not a universal
+promise of autonomous agent continuation. Re-read/reattach when your harness does
+not inject a completed shell result.
+
+Publication holds Linux directory descriptors, writes and synchronizes a private
+temporary file, publishes with a no-replace hard link, then synchronizes the
+response directory. Retries reconcile the same identity/content and never replace
+another contribution; a moved/duplicated/conflicting identity is rejected.
+Symlinked reference folders grant read access only. Changed/moved directories,
+permissions, unsupported filesystem capabilities and uncertain outcomes remain
+explicit. An unrelated editor can change the reviewed source after a preflight
+check; immutable replies still identify the exact reviewed bytes and never claim
+an atomic transaction with that editor. Directory moves after publication can
+produce an uncertain result; reconcile saved source before retrying.
+
+Source HTML cannot submit write forms: CSP disables form actions/frames, the
+native route requires same-origin/loopback and NDJSON when writes are enabled,
+and the official response surface renders reviewed context with raw HTML disabled,
+with an escaped exact-source disclosure. Embedded apps must
+explicitly opt in with `boardLayer({ root, responses: true })` and own the trusted
+host boundary. There is no write endpoint for arbitrary paths or source rewriting.
+
 ## Local visual evidence
 
 Use ordinary Markdown such as `![Review screenshot](shots/review.png)` or
@@ -421,3 +513,19 @@ unknown, invalid components retain their source with a diagnostic, and timelines
 preserve authored order. Recorded values do not establish verified acceptance.
 See [the complete source conventions](./docs/vision/delivery/visual-document-examples.md).
 GitHub alert blockquotes render as callouts; comparisons remain ordinary GFM tables.
+
+## Rich question packets
+
+Agents can prepare Markdown context with `question`/`option` directives and local
+Mermaid diagrams. People select options, always add text, and submit the whole
+packet once. Use `select="one"`, `select="many"` or `select="text"`; choices start
+unselected and a text-only answer can reject the framing. Preview the complete
+record before saving. The existing wait returns typed prompt/option IDs and human
+text with the readable Markdown and exact reviewed context.
+
+See [the full source example and contract](docs/vision/delivery/decision-write-examples.md).
+Ordinary Markdown and older response files still work. Decisions are authored
+feedback; superseding direction is explicit and does not establish acceptance or
+change tasks. Response-page raw HTML is disabled. Local strict Mermaid and
+no-JavaScript readable history/source fallback use the existing renderer; recording
+requires JavaScript and `--responses`. Linux-only write support is unchanged.