feat: add documentation, specifications, and pipeline configurations for GEWU agent system

docs/reviews/PRD_TARGET_READINESS.md

@@ -0,0 +1,67 @@
+# PRD target alignment and release readiness
+
+12 October 2026. Reviewed working-tree PRD 0.6 against GOAL.md; applied updates in PRD 0.7 and GOAL.md. Earlier reports and unrelated working-tree changes were preserved.
+
+## Assessment
+
+The PRD supports the intended product: a shared knowledge service that preserves evidence and project context, receives contributions from local agents through MCP, and lets people browse without an agent running. Its main remaining obstacle is the acceptance contract. Implementation can begin with a bounded pilot once the first client, source format and policy fixtures are selected. Full v1 is not yet a fixed delivery estimate.
+
+This review inspected the documents in this repository. No application implementation, executable schema or test suite is present. Existing Jev/Winnow probe results are historical reference evidence and were not rerun. This report makes no claim about current external implementations, protocol conformance, performance or deployment acceptance.
+
+## Owner decisions captured in this review
+
+| Decision | Product consequence |
+| --- | --- |
+| Smaller pilot before full v1; retain full v1 commitments | Pilot coverage is recorded separately. Four-client support, listed P0 source inputs and hybrid retrieval remain full v1 requirements. |
+| Dome interactive content and interactive video platform/service | Use these two domains for source fixtures, representative questions and cross-project reuse. Exact registry IDs and sources still need selection. |
+| Up to five people initially | Size the pilot around a small team. This does not specify simultaneous agent count or ingestion throughput. |
+| Admin, viewer and editor roles | Define role permissions now. Editor means MCP proposal capability under the existing read-only website target; this interpretation is explicit in the PRD. |
+| Each local agent has its own API key and identifier | Attribute changes to a server-bound identity; support separate revocation and key rotation without changing the stable agent ID. |
+| Same agent may extract and assess routine notes; record assessments and sample quality | Automatic acceptance can operate without mandatory separate-agent review. Sampling must measure semantic errors independently of quote matches. |
+| Restrict project access to different people later | Keep all-team read access initially and project permissions at P2. Stable principals and explicit ownership support that future change without claiming it is implemented. |
+
+## Findings and applied corrections
+
+| Priority | Finding and document evidence | Update / remaining decision |
+| --- | --- | --- |
+| High | PRD 5.2 puts sources/entities in shared, while the registry and automatic-acceptance section emphasize per-project policies. A project policy alone cannot establish authority over a shared source. | Added shared ownership and policy authority in 5.4. M0 must choose atomic bundles across all affected policies or ordered dependent proposals; partial success must be explicit. |
+| High | PRD 6.3.1 accepts external support assessments but did not decide whether the extractor could assess its own claims. This determines the routine acceptance workflow. | Owner permits same-agent assessment for routine notes. Bound assessments to exact assertions and evidence revisions; quality sampling is required. Sample ownership, cadence and error limits remain open. |
+| High | FR-P8 named capabilities without a concrete initial role or agent-credential model. | Added admin/editor/viewer roles, separate owner authority and per-agent keys/IDs. Required rotation, revocation, current-authorization checks and attribution. Owner authorization and bootstrap still need an M0 mechanism. |
+| High | Architecture permitted delayed indexing without defining how an agent retrieves the node its proposal just accepted. | Separated canonical acceptance from search visibility. M0 must choose canonical reads or a bounded pending response; a committed node cannot appear nonexistent solely because indexing lags. Added receipt reconciliation for a commit-before-receipt crash. |
+| High | M1 required all four clients before M2 ingestion and M3 UI; M4/M5 included P1 work without a distinct full-release gate. | Recorded the approved smaller pilot across M0–M3 and retained full v1 priorities. Added explicit release coverage for recovery, source artifacts, offline operation, budgets, client/OS coverage and VPS handover. |
+| Medium | PRD 6.3.2 required synthesis dependency warnings, but FR-C1 was P1. An implementer could defer warnings along with refresh tooling. | Clarified that displayed accepted syntheses carry P0 warnings; dedicated refresh and compilation workflows remain P1. |
+| Medium | Success metrics used 300 ms, ten minutes, 70% acceptance and cross-agent convergence without sufficient workload, denominator or error definitions. | Added a pre-evaluation decision gate. Existing values remain targets; no hardware, sampling threshold or recovery objective was invented. |
+| Medium | Open questions and examples assumed three starting projects, while M0 asked for two. | Recorded the two confirmed pilot domains, marked IDs as suggestions and kept agentic-design as an example. |
+
+## Recommended pilot and evidence
+
+Start with one local client, one source format whose locations can be preserved, and the two confirmed projects plus shared. Exact selections remain pending. A text-based PDF is a useful candidate if it represents the supplied material; the final fixture should follow the actual research inputs. Build enough read-only UI to find a problem, compare its linked approaches and open their evidence.
+
+The pilot should demonstrate:
+
+1. An editor's registered agent uploads a source and proposes a factual note with a quote, location and recorded support assessment. The service accepts an eligible proposal without human approval.
+2. A viewer finds that note and follows its citation to the exact archived revision while local agents are offline.
+3. The same shared source supports relevant notes in both pilot projects, with origin and requested scope preserved.
+4. Wrong-location evidence is rejected. A correctly located quote that fails to support the claimed year/population is included in the labeled semantic evaluation, so the evaluation measures errors deterministic quote matching cannot catch.
+5. A viewer cannot propose; an agent cannot self-authorize a policy change. Two separately registered agents produce distinguishable audit records. Rotation preserves identity and revocation prevents further authorized work with the old key.
+6. Retrying a proposal creates one acceptance; interruption and recovery preserve its source, decision and receipt. Search publication may lag with an explicit status.
+7. The designated reviewer samples accepted notes and records support errors, corrections and time spent. The sampling plan and pass limits are fixed before measuring the pilot.
+
+These are proposed acceptance cases, not existing tests. The pilot may have narrower format/client/retrieval coverage than full v1. It still needs a complete source-to-reading workflow to test the product's value.
+
+## Decisions still needed
+
+| Decision | Recommendation | Needed by |
+| --- | --- | --- |
+| Initial client, source format and real material | Pick the team's most-used client and a representative source format; collect sources and answerable questions for both projects. | Pilot fixture selection |
+| Shared ownership and first admin/project owners | Name the initial responsible people; specify protected-action authentication separately from agent keys. | M0 authorization contract |
+| Quality sampling | Assign a human reviewer initially and agree sample size, cadence, semantic-error limit and correction/escalation response. This is a recommendation, not a confirmed staffing decision. | Before pilot evaluation |
+| Concurrent agents and hosting | Specify simultaneous runs, typical/max source size, storage budget, VPS capacity, backup owner and recovery objectives. Five human users alone does not define service load. | Before performance and hosting acceptance |
+| Exact auto-acceptance matrix | Specify eligible types for project and shared records, interpretation/relationship rules and exceptions. | Before acceptance implementation |
+| Bundle/recovery contract | Choose cross-policy transaction behavior, proposal revision/state transitions and accepted-revision read behavior. | Before service persistence implementation |
+
+Optional brief tooling, graph canvas, rich comparison views and project-restricted access remain later work under their existing priorities. No launch expansion is implied by this review.
+
+## Change and verification record
+
+Updated PRD to 0.7, aligned GOAL.md with the owner's pilot decisions, and linked this report from the earlier review. Preserved the earlier implementation-reference review and probe artifacts. Documentation checks cover local Markdown links, unique requirement IDs and consistency of the newly recorded decisions. There is no runtime verification or commit in this review.