@shivaedev/work-board 0.11.0 → 0.12.0

package/docs/north-star.md

@@ -0,0 +1,61 @@
+# Work Board north star
+
+Work Board is a local, file-backed workspace for a person and their agents to understand work and exchange direction. Open it to know what is happening, what changed, what needs judgment, and where the evidence lives. Close it without losing the work: the meaningful content remains readable in project files.
+
+The [roadmap](roadmap.md) owns implementation status, acceptance gaps and open maintainer decisions. The [README](../README.md) teaches current use. The [experience design](experience.md) and [interactive prototype](mockups/index.html) illustrate the product direction with fictional data. The [delivery requirements](delivery/README.md) define bounded steps and how to verify them, without keeping a second status list.
+
+## The problem
+
+Agents can produce plans, code, reports and questions faster than a person can read them. A terminal shows activity; a chat holds a conversation; neither makes it easy to return to a project and identify the judgment that matters. Evidence gets detached from the result it supports, and the difference between a completed run and an accepted piece of work disappears.
+
+A person needs a place to read that material together without maintaining a parallel project-management system. Agents should keep editing ordinary files. Editors and Git should remain useful independent of the board. Optional structure should connect the work, rather than turn every note into a form.
+
+## Who it serves
+
+The primary reader is a developer coordinating their own work and several agents across project files. A document can remain narrative while its identified work appears in a board or table. Relationships connect a goal to its plan, decision, implementation, criteria and result. Views arrange those sources for different questions; they do not create competing copies.
+
+Human responses belong to their reviewed context. Work Board owns the response content it records; agents own the surrounding project Markdown and use normal file edits. This [ownership boundary](delivery/source-editing-examples.md) accepts rare outside-editor races while requiring practical drafts, revision checks and clear ordinary save failures.
+
+A handoff preserves reviewed direction in another readable file. A copied pointer lets an existing agent session read it; ordinary edits record receipt. That receipt does not establish execution or acceptance. An execution integration can refer to the same work identity without becoming a prerequisite or another source of truth.
+
+Returned work needs the same discipline. An authored result and its evidence are claims to inspect. Human direction belongs to the exact report bytes and source path that prompted it; a later edit must not inherit an earlier acceptance. A report iteration can receive human acceptance while a criterion still lacks evidence. The board must keep those facts visible rather than compute a convenient overall success state.
+
+## What good looks like
+
+- **Readable source.** A folder and one command are enough to begin. Plain Markdown remains useful; metadata is optional; no hidden database holds the only meaningful copy of work.
+- **Calm awareness.** Attention means an explicit question, blocker or review request. Quiet ongoing work should remain quiet. File churn is not progress.
+- **Evidence before activity.** Running, producing output, finishing a run, recording a claim, receiving a response and satisfying criteria remain distinct.
+- **Direction in context.** Responses and handoffs stay connected to the source and evidence the person reviewed. They do not disappear into a second generic chat feed; receipt remains distinct from execution and acceptance.
+- **Honest freshness.** Source locations, reviewed revisions, provenance and uncertainty remain visible. A summary leads back to its supporting material.
+- **Coherent reading.** Documents, cards, tables, diagrams and decisions share navigation, source links and a readable visual language. Live changes preserve the reader's place, with deliberate pause and reconciliation.
+- **Local independence.** Core reading needs no hosted service, account or cloud sync. Optional integrations cannot become prerequisites for the local workflow.
+
+## The direction
+
+The product grows in three useful stages:
+
+1. **Stay informed.** Read plans, progress, results, questions and uncertainty while agents work through their existing tools.
+2. **Inform back and coordinate.** Respond in context, record direction, request revisions and make the next handoff understandable.
+3. **Collaborate.** Refine successive contributions with clear ownership, preserved context and inspectable evidence.
+
+A good reading experience is a product in its own right. Coordination earns its place by reducing repeated context assembly; it must not force a new agent runtime.
+
+## Trade-offs
+
+Readable source wins over richer hidden state. Explicit unknowns win over a helpful-looking guess about status, identity or acceptance. Preserved orientation wins over redrawing every view after every event; uncertain delivery still requires full reconciliation. Contextual direction wins over a general chat interface.
+
+Practical ownership wins over a universal filesystem transaction engine. A saved response retains the exact reviewed context; it cannot lock every unrelated editor or claim that several project files changed atomically. Retaining a draft and explaining an uncertain save are part of the product, not exceptional cleanup.
+
+Shared Effect and Platform primitives win over a second RPC, client state or live update implementation. Work Board owns its document/indexing policy and user experience. Existing agent tools own execution; existing editors own project edits. An adapter must remove a demonstrated manual step and keep that boundary visible.
+
+## How to judge progress
+
+The intended payoff is less effort to regain context and direct work. Useful questions are whether a returning reader can find the actual blocker, reach its source rationale and evidence, distinguish changes from churn, and respond without reassembling the context. A representative workspace should include dozens of documents and a hundred items, as well as empty, malformed and unavailable states.
+
+Tests establish specific behavior. A browser fixture establishes the interactions it exercises. Neither proves representative-reader orientation time, physical device behavior or adoption. Proposed targets and their acceptance remain in the roadmap until the maintainer accepts the evidence.
+
+## What it leaves out
+
+Work Board does not aim to become a generic project-management suite, agent scheduler, terminal fleet, plugin marketplace, arbitrary script dashboard, rich-text editor or event-sourcing system. Hosting, accounts, cloud sync, remote multiplayer, public publishing, document export and shareable packet generation are outside the product direction. A browser's ordinary printing and local image/diagram downloads remain reading tools, rather than an artifact-generation service.
+
+External evidence integration must be explicit and narrow: authoritative source, linked objects, refresh behavior, offline behavior and a maintenance owner. A read-only adapter may expose stale imported evidence; it must leave local authored plans and decisions usable. Two-way synchronization and organization-wide crawling would create competing sources of truth.

package/docs/roadmap.md

@@ -0,0 +1,75 @@
+# Work Board roadmap
+
+The [north star](north-star.md) defines the product direction. This file owns package implementation status, acceptance gaps and maintainer decisions. [Delivery requirements](delivery/README.md) describe the steps and repeatable checks; they do not track completion. The [framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md) owns composed Platform fixtures and host adoption/deployment, rather than repeating these package steps. History and release-by-release verification live in Git and the changelog.
+
+## Built
+
+The reading, response, handoff and result-review implementation has these capabilities. Each row links the delivery requirement and the regressions that establish its behavior.
+
+| Steps | Capability | Evidence |
+| --- | --- | --- |
+| [01](delivery/wave1.md#01-a-real-workspace-shell) | Workspace shell, theme/density/sidebar preferences | `src/server/page/shell.test.ts`, `src/client/page/runtime.dom.test.ts`, `src/client/page/sidebarScript.dom.test.ts` |
+| [02](delivery/wave1.md#02-document-locations-and-reading-state) | Passage links, reading navigation, favorites and recents | `src/render/documentHeadings.test.ts`, `src/client/page/navigationScript.dom.test.ts` |
+| [03](delivery/wave1.md#03-find-work-from-anywhere) | Local deterministic search and command dialog | `src/server/search/entries.test.ts`, `src/server/http/search.spec.ts`, `src/server/page/searchRequests.dom.spec.ts` |
+| [04](delivery/wave1.md#04-optional-identity-and-a-rebuildable-index) | Optional identity, metadata and rebuildable reference index | `src/server/metadata/parse.test.ts`, `src/server/metadata/model.test.ts`, `src/server/http/identity.test.ts` |
+| [05](delivery/wave1.md#05-one-body-of-work-several-views) | Shared board/table projections, URL state and named local views | `src/server/http/work.test.ts`, `src/server/http/tableViews.spec.ts`, `src/server/page/savedViews.dom.spec.ts` |
+| [06](delivery/wave1.md#06-follow-the-reasoning-and-the-evidence) | Relationships, source backlinks and recorded criterion claims | `src/server/http/reasoning.spec.ts`, `src/server/page/reasoning.dom.spec.ts` |
+| [07](delivery/wave1.md#07-an-attention-first-overview), implementation only | Explicit attention queues and source diagnostics | `src/server/metadata/attention.spec.ts`, `src/server/http/attention.spec.ts`, `src/server/page/attention.dom.spec.ts`; reader acceptance remains below |
+| Human Inbox | Human-owned actions, standalone questions, Fleet waiting work, option/text responses, live count and grouped Fleet records | `src/server/attention/inbox.test.ts`, `src/server/http/inbox.test.ts`, `src/server/responses/inboxQuestion.dom.spec.ts` |
+| [08](delivery/wave1.md#08-what-changed-since-i-last-looked) | Explicit browser-local seen baseline and source comparison | `src/server/history/baseline.test.ts`, `src/server/history/compare.test.ts`, `src/server/history/history.dom.spec.ts` |
+| [09](delivery/wave1.md#09-live-updates-that-preserve-orientation) | Native reads, targeted invalidation, pause/resume and reconciliation | `src/server/rpc/native.spec.ts`, `src/server/rpc/affected.test.ts`, `src/server/rpc/hints.test.ts`, `src/server/page/nativeUpdates.dom.spec.ts` |
+| [10](delivery/wave1.md#10-local-visual-evidence) | Contained local images and diagram/image inspection | `src/server/http/localImages.spec.ts`, `src/server/page/visuals.dom.spec.ts` |
+| [11](delivery/wave1.md#11-a-small-vocabulary-for-visual-documents) | Sourced metric/progress/timeline directives and callouts | `src/render/visualReading.spec.ts` |
+| [12](delivery/wave1.md#12-start-with-useful-project-documents) | Empty-workspace guidance and copyable project/report templates | `src/server/http/startReading.spec.ts`, `src/client/page/navigationScript.dom.test.ts` |
+| [14–15](delivery/wave2.md#14-prove-one-safe-source-mutation) | Opted-in immutable question/response publication, drafts and durable waits | `src/server/responses/response.spec.ts`, `src/server/responses/publicationFlow.spec.ts`, `src/server/responses/agentWait.spec.ts`, `src/client/responses/draftOwnership.dom.spec.ts` |
+| [16](delivery/wave2.md#16-record-a-decision-and-its-consequence) | Rich question packets and explicit superseding direction | `src/server/responses/template.test.ts`, `src/server/responses/questionnaire.spec.ts`, `src/server/responses/questionnaireForm.dom.spec.ts` |
+| [18](delivery/wave2.md#18-one-local-agent-handoff) | Reviewed Markdown handoffs, copied prompts and ordinary file-edited receipt | `src/server/handoffs/handoff.spec.ts`, `src/server/handoffs/handoffForm.dom.spec.ts` |
+| [19](delivery/wave2.md#19-review-a-returned-result-against-its-criteria) | Returned-result reading and version-pinned feedback without inferred criterion acceptance | `src/server/results/result.spec.ts` |
+
+Directory reference reading and watcher recovery are covered by `src/server/http/symlinks.spec.ts` and `src/server/liveUpdates.spec.ts`. Fetch-handler and real HTTP embedding are covered by `src/server/board.test.ts` and `src/server/embedding.spec.ts`. The packed-consumer gate checks the CLI and embedding declarations.
+
+Nested sidebar ancestry, home ordering, logical reference paths and folder expansion through live changes and navigation are covered by `src/server/page/nav.dom.test.ts`. Exact-context managed decision acknowledgements are covered by Work Fleet's `src/board/managedRequestReceipt.spec.ts` and `src/board/acknowledgementHttp.spec.ts`; those receipts leave source bytes intact and do not establish execution, acceptance or delivery authority.
+
+The sidebar Diagnostics view reads Codex usage windows, cached GitHub REST/GraphQL limits and Fleet health from the daemon's native HTTP RPC API. Synthetic source, command and app-server fixtures cover ready, missing, failing and malformed states, shared caching and refused provider approvals in `src/diagnostics/source.test.ts`, `readers.spec.ts` and `codexRateLimits.test.ts`. Real HTTP fixtures cover daemon responses, stopped-daemon recovery, ignored health files and stale observation times in `src/server/diagnostics/diagnosticsRpc.spec.ts`; `page.test.ts` and `liveRefresh.dom.spec.ts` cover navigation, rendering and native polling/pause/resume. These fixtures do not establish live account authorization.
+
+The static handoff, response and question forms use `effect-form` for Schema decoding, field messages and submission snapshots. The unchanged form and draft regressions above preserve reviewed context and durable storage. `src/client/effectForms.dom.spec.ts` exercises Schema feedback, response edits during a save, and form restoration after persisted pageshow in DOM/HTTP fixtures.
+
+The Board opens as a React shell with TanStack Router and `effect-react` query loaders in the shared native registry. The sidebar reads the native navigation query through `effect-react`; Document and item pages read the typed document query and mount `DocumentView`; `LegacyMain` hosts the configured home board and the remaining workspace views. The shell and hosted pages share the native atom registry and live connection. The server retains the existing layout as a no-JavaScript fallback; `src/server/page/shell.test.ts` checks its page and navigation content. `src/client/react/boardRouter.dom.test.tsx` renders a fixture tree, changes the main area through the router without replacing the shell, renders document tools and retains response text and caret through a document-query refresh. `src/client/react/documents.dom.spec.tsx` checks file and identity URLs, heading anchors, context links and initial read failures without requesting page HTML. `src/client/react/routeLoading.dom.spec.tsx` checks preloaded document, identity, failed-read, home-board and workspace URLs sharing one query execution with navigation, the displayed document staying mounted during a pending loader, and search-parameter changes loading their own page query. The DOM/HTTP regressions exercise the built shell, live invalidation, pause/resume, reading history and form drafts. These fixtures do not measure browser layout or establish physical-device or page-cache adoption. `src/server/board.test.ts` and the packed CLI fixture check the shell and asset delivery; `src/client/react/queryRendering.dom.spec.tsx` renders a search query through shared RPC handlers and the published `effect-react/testing.ts` helpers.
+
+## Next
+
+- [ ] Finish [07's representative-reader acceptance](delivery/wave1.md#07-an-attention-first-overview). The proposed target is finding the actual next judgment within 30 seconds. Automated queues and browser fixtures do not establish that outcome.
+- [ ] Finish [13's complete reading-workflow review](delivery/wave1.md#13-prove-the-complete-reading-workflow). Use the [repeatable reading review](delivery/reading-review.md), agree performance budgets, and gather representative-reader, physical-device and actual browser page-cache lifecycle evidence. Technical reading and embedding checks do not silently accept this step.
+- [ ] Prove [20's complete coordination loop](delivery/wave2.md#20-complete-the-first-coordination-loop). Use one bounded real feature for decision, manual handoff, receipt, result, revision and specific-report acceptance. Include restarts, unavailable delivery and ordinary external edits. Result fixtures do not establish that adoption loop.
+
+[17's direct item editing and undo](delivery/wave2.md#17-narrow-editing-and-honest-undo) are deferred. Agents use ordinary file tools and Work Board owns human response content. The original create/title/checklist/status/move controls are unimplemented; they do not block file-based handoffs. No inline-response source format is settled by this ownership decision.
+
+After that coordination loop, the following work stays in dependency order:
+
+| Step | Intended work | Prerequisite |
+| --- | --- | --- |
+| [21](delivery/wave3.md#21-successive-contributions-with-clear-ownership) | Successive contributions with visible ownership and stale proposals | Complete coordination loop |
+| [22](delivery/wave3.md#22-several-local-projects-one-attention-view) | Explicitly selected local projects in one attention view | Single-project collaboration |
+| [23](delivery/wave3.md#23-richer-plans-and-linked-reviews) | Bounded compositions, dependency views and linked in-app review | Existing source vocabulary and returned-result review |
+| [24](delivery/wave3.md#24-one-optional-read-only-github-adapter) | One read-only adapter for explicitly linked GitHub PR evidence | D4 and demonstrated repeated manual work |
+| [25](delivery/wave3.md#25-read-existing-local-test-and-build-artifacts) | One reader for existing local machine-readable check artifacts | Returned-result evidence model |
+| [26](delivery/wave3.md#26-quiet-rules-and-a-real-collaboration-review) | Explainable quiet rules and actual collaboration review | Reliable triggers and explicit ownership |
+
+## Maintainer decisions and open questions
+
+- **Source convention (D1).** Optional per-file YAML identity, explicit relationships, membership, criteria and claims coexist with plain Markdown and heading boards. Missing values stay unknown. The [source conventions](delivery/source-examples.md) define the current shape.
+- **Response ownership (D2).** Questions capture exact reviewed bytes and source path; independent immutable response files retain human direction. Publication is explicitly opted in and runs on Linux and macOS. Agents keep ordinary project-file edits; surrounding agent changes win outside human response content. Practical drafts, revision checks and ordinary save failures matter; universal outside-editor transactions and a mandatory special writer do not.
+- **Handoff contract (D3).** Ordinary Markdown direction, a copied pointer into an existing session and file-edited receipt are delivered. The [handoff contract](delivery/handoff-examples.md) keeps requested, acknowledged, rejected and unavailable receipt separate from execution and acceptance.
+- **Optional execution integration.** Does repeated manual work justify a supported existing-session notification hook or explicit local CLI launch? Who owns priority, assignment and execution authority in that integration? Keep manual copying useful and attach execution facts to the same work ID; the handoff receipt must not become a completion or acceptance state.
+- **Result-review meaning.** Human feedback is pinned to exact report bytes and source path. Authored acceptance options do not establish missing criterion evidence or change linked work status. Ordinary edits create another report revision; the existing response records retain prior reviewed context.
+- **Coordination acceptance.** Which bounded feature and real participants should establish step 20's complete loop? Decide the adoption evidence without treating an automated result fixture or supplied run status as independent agent execution.
+- **External evidence (D4, open).** Which repeated manual step justifies an adapter? Specify authoritative fields, opt-in, refresh/offline behavior and a maintenance owner before choosing dependencies or transport. Keep local authored plans and decisions authoritative.
+- **Acceptance bar.** Do the proposed 30-second orientation target and the current reader/device/page-cache checks remain the intended exit for 07/13? What realistic workspace, machine and performance budget should guide optimization?
+- **Integration surface.** The manifest exposes every defining `.ts` module. Which secondary client, rendering or indexing modules should receive the same consumer-facing guidance as the CLI, `boardLayer` and native handoff contract?
+- **Resource bounds.** What browser bundle, simultaneous-tab capacity and waiter resource budgets should be measured? A short idle sample or edited deadline does not prove a long-duration soak, 48-hour availability or automatic model wakeup in every harness.
+
+## Evidence limits
+
+Regression tests establish their asserted source, HTTP and DOM behavior. DOM fixtures use a Mermaid stub and do not establish layout, actual Mermaid rendering, physical device lifecycle or real page-cache adoption. The browser acceptance instructions exercise those boundaries separately; release observations in Git are not new verification from a documentation change.
+
+Question deadline regressions move registered timestamps beyond 48 hours. They prove deadline handling and late reply recovery, rather than a real 48-hour soak. Publication fault tests cover persisted files on the host filesystem and synchronization failures; they do not establish a universal transaction with unrelated editors. Example claims and linked evidence remain authored records, rather than accepted results.