GEWU/docs/PRD_REVIEW.md

# PRD review against the KB north star

12 October 2026 · Reviewed PRD 0.2; companion revision: PRD 0.6

Historical review: the current target/readiness assessment and owner decisions are in [PRD_TARGET_READINESS.md](reviews/PRD_TARGET_READINESS.md), applied in PRD 0.7. Unresolved choices below describe the earlier review; consult the current report for their latest status.

## Assessment

The product direction fits [GOAL.md](GOAL.md): explicit project scope, evidence-backed knowledge, human-owned intent, proposals as the write boundary, inspectable files and one core service. The PRD is a useful foundation, but version 0.2 was not yet a testable implementation contract. Its biggest gaps were what “verified” means, how writes are enforced and recovered, and what a shared team actually needs to operate the system.

The confirmed target is **a shared team plus local agents, with every team member allowed to read every project**. Development runs locally first; the shared service will later run on the owner’s VPS. The website only searches and displays knowledge. All knowledge contributions originate in local Codex, Claude, Antigravity and OpenCode agents through MCP. Eligible proposals auto-accept; humans do not approve every change. PRD 0.4 supersedes the earlier recommendation for a browser review inbox and mandatory initial human acceptance.

This is a document review, not a runtime or code audit. The workspace contained only GOAL.md and PRD.md at review start, with no implementation or referenced deep-research report. No retrieval, ingestion, performance, security or cross-agent acceptance result has been demonstrated here. Proposed targets below are recommendations, not measured results.

## Confirmed decisions and remaining choices

| Topic | State | Consequence |
| --- | --- | --- |
| Product target | Confirmed: shared team plus agents | Deliver MCP contributions and shared read-only retrieval, with attributable actions. |
| Read access | Confirmed: all team members may read all projects | Keep project confidentiality/ACLs at P2; enforce content scope for relevance and explicit reuse. |
| North star | GOAL.md is the review baseline | Preserve evidence, human-owned intent, proposals, git authority and local-first operation. |
| Initial autonomy | Confirmed: human approval is not required for every change | Automatic acceptance is P0; exact eligibility, support checks and exception rules remain to be finalized. |
| Hosting | Confirmed: local development, then owner’s VPS | Local agents connect through MCP; artifacts must reach server storage. Capacity, backup ownership and concurrency remain open. |
| Web and contribution boundary | Confirmed: read-only web; MCP-only contributions from local agents | Remove web review/edit/capture, generic REST writes and CLI authoring. |
| First-release P1 features | Unresolved | Decide whether compiled briefs are required for the first useful workflow. |

## Findings and updates

“Blocking” means resolve the contract before implementing the affected path. It does not mean stop all work on the product.

| Priority | Finding in 0.2 | Why it matters for the target | Change through 0.4 / remaining work |
| --- | --- | --- | --- |
| Blocking | Team access was described largely as logical project isolation, with access control deferred wholesale. | A team still needs to distinguish reading, proposing, accepting and changing intent, even when everyone can read everything. | Added P0 FR-P8 for authentication, mutation capabilities and actual caller identity; retained P2 project confidentiality. VPS deployment is confirmed; finalize policy ownership and protected-change authorization. |
| Blocking | Quote matching was too close to the definition of verification. | A real quote can be used to support a claim it does not actually establish. Finding a number somewhere does not prove the claimed unit, population or date. | Separated source reliability, quote/location validity, support assessment and confidence. Acceptance needs both checkable evidence and a support decision; semantic accuracy needs its own evaluation. |
| Blocking | “Agents cannot write files” was asserted without an enforceable operating model. | A harness with owner-level access to the canonical checkout can bypass a service validator. | Defined a service-owned canonical store and proposal-only agent credentials/mounts. Direct file authoring is unsupported; maintenance operations share validation rules. Deployment must prove the MCP contribution boundary. |
| Blocking | No acceptance concurrency, idempotency or crash contract. | Concurrent agent proposals, policy workers or retried submissions can otherwise duplicate work, overwrite decisions or leave git and search inconsistent. | Added FR-V5: proposal identity, base revision, revalidation, serialized acceptance, durable receipts and disclosed index lag. Finalize recovery state transitions in M0. |
| Blocking | Scope promises were contradicted by get_node(id), compare(ids), flag_stale(id), resources and traversal. | Correctly filtered search is insufficient if follow-up calls can silently broaden the project context. | Added explicit scope context throughout content tools/resources and destination-aware redirects. flag_stale now stages a proposal. |
| High | Immutable sources lacked a content-revision model; URL dedupe could hide changed pages. | Citations need to remain checkable after a source changes. | Added stable source identity, immutable captures, revision-specific locators and parser/extraction versioning. An unverifiable capture may remain a draft/reference but cannot supply an accepted factual claim. |
| High | Stable IDs include project names, while notes can be promoted to shared. | A namespace change can break incoming links and provenance. | Title/path renames preserve IDs; promotion is an atomic reviewed migration with permanent redirects and retained origin. Test both scope and history through promotion. |
| High | Evidence is duplicated across derived_from and evidence_quote; one status combines reviewed, stale and superseded. | Fields can disagree, and a node cannot express multiple simultaneous states. | Canonicalized the evidence list; separated review state, derived freshness and lifecycle. Schema still needs typed field/edge contracts. |
| High | Freshness was defined for nodes but not fully for syntheses and budgeted responses. | A brief can conceal stale inputs even when its own creation date is recent. | Added input revisions, dependency warnings and warning-preserving budget behavior. Define exact stale_after policies by content type. |
| High | The service tool list made brief P0 while FR-A4 made it P1; milestones mixed P0/P1 without an explicit release cut. | “v1 complete” could mean very different products to implementers. | Aligned timeline/compare/brief at P1 for internal consistency. This remains a release decision: if compiled answers are essential, promote the whole vertical slice together. |
| High | Performance and convergence metrics lack reproducible conditions. | “Fast” and “mostly overlapping” cannot be release gates without a corpus, workload and scoring method. | Clarified semantic coverage vs wording overlap and complete-payload budgets. Benchmark hardware, concurrency, latency percentile and numeric convergence thresholds remain to be fixed. |
| Medium | Architecture offered SQLite or Postgres despite choosing SQLite later; graph rationale implied a graph index necessarily displaced git. | The document gave contradictory implementation direction and overstated the storage tradeoff. | Made SQLite the v1 choice and based graph deferral on operational complexity and measured need. |

## Recommended first useful team workflow

Ship a vertical slice in which a local agent captures a source, transfers its artifacts through MCP, proposes evidence-backed notes and receives automatic acceptance when service policy passes. Team members then search and read the accepted knowledge in the website, while agents retrieve the same cited records through MCP. Failed proposals return actionable findings to the agent; exceptions are resolved in the local conversation. Demonstrate deliberate reuse in a second project with scope and origin intact.

That workflow exercises the product's main promise before investing heavily in subtype packs, graph exploration, four audience-specific views or every ingestion adapter. Those features can remain on the roadmap. The first UI provides search, node reading, evidence/source inspection and freshness/history display. It has no knowledge submission or review-decision controls.

Recommended release sequencing, subject to the remaining scope decision:

| Stage | Deliverable | Observable exit |
| --- | --- | --- |
| Contract and fixtures | Canonical schema, evidence locators, scope rules, proposal/acceptance lifecycle, human/agent capabilities; a small labeled corpus across two projects | Examples validate; seeded scope, quote, support and permission failures are rejected for the right reasons. |
| End-to-end team slice | One authoritative service/repo; read-only web access; MCP artifact transfer and proposals; policy acceptance; cited retrieval | A local agent submits an eligible proposal that auto-accepts; people and agents retrieve it. Invalid submissions receive repair findings. Web writes fail; retries do not duplicate acceptance. |
| Trust and recovery | Archive retention and restore, index rebuild, interrupted-run recovery, stale/contradictory evidence, independent source revisions | Restore preserves evidence checks and audit history; stale/contradictory results remain visible and qualified. |
| Release breadth | Required remaining P0 adapters, harness integrations and offline paths; P1 briefs only if selected for launch | Full agreed release matrix passes on the supported environments; the first-month reuse target is tracked after launch. |

This sequencing is a recommendation. PRD 0.4 retains existing P0 adapter, hybrid-search and four-harness commitments; it does not silently defer them. If the team wants a smaller release, explicitly revise their priorities before implementation estimates are treated as commitments.

## Acceptance criteria to make the target testable

These scenarios should become acceptance fixtures. They are not a claim that tests currently exist or pass.

| North-star invariant | Minimum acceptance scenario |
| --- | --- |
| Evidence before assertion | A quote exists but refers to a different population or year: location validation passes, support review rejects the proposed claim. A quote on the wrong page fails location validation. An unavailable archive cannot yield an accepted verified claim. |
| Explicit project scope | With project A plus shared selected, search, ID lookup, neighbors, comparison, brief and resources do not silently return project B content. Selecting B explicitly succeeds for any authenticated team member. |
| Human-owned intent | An agent can propose a north-star/policy change, but its credentials cannot accept that change; a project owner can do so with a recorded decision. |
| Proposal write boundary | Agent requests cannot directly edit notes, mark accepted nodes stale or merge duplicates. An eligible proposal auto-accepts without human action. A changed proposal is revalidated; simultaneous acceptance attempts produce one canonical outcome. Browser credentials cannot contribute. |
| Git/files authority | Delete the derived index and rebuild: canonical records, decisions, redirects and lineage remain recoverable. Restore the private source artifacts as well and verify citations against the restored revisions. |
| One core | MCP proposals use the canonical validator; maintenance validation applies the same rules. UI/HTTP reads obey the same scope rules as MCP reads, but web/REST/CLI contribution attempts cannot mutate knowledge. |
| Trust over time | A datapoint crosses its stale_after deadline without a curator run: the next response and dependent synthesis warn, including under a tight budget. Contradictions and superseded records remain traceable. |
| Local-first and agent-agnostic | With internet unavailable and a configured local model, existing captures can be read, processed and validated; remote capture reports unavailable explicitly. Two harnesses complete the same core workflow using the same service contracts. |
| Team operation | An interrupted acceptance after git commit but before index publication recovers without duplicate acceptance. Credentials can be revoked; rejected and accepted decisions retain actor and policy identity. After local-to-VPS handover only the VPS accepts writes; local agent artifacts remain verifiable on the server. |

## Metrics needing completion before acceptance

- Keep the 100% citation-location target as an accepted-corpus invariant, with an explicit denominator of factual assertions and datapoints. Do not equate it with 100% factual truth.
- Keep the current retrieval target of at least 80% correct-source top-5 on 20–30 questions per project as an initial benchmark. Label expected sources, record scope and add insufficient-evidence/contradiction cases so the evaluator can tell when no supported answer exists.
- Specify search latency at a named percentile, on stated hardware and corpus, under a defined simultaneous human/agent workload. Clarify whether the current 300 ms includes query embedding, network transport and graph expansion. Distinguish keyword, hybrid and compiled-answer paths.
- For the ten-minute rebuild target, specify whether embeddings are regenerated or reused. Record embedding model/version and provide a migration/rebuild strategy; derived vectors must not become the only copy of knowledge.
- Define the brief latency measurement separately for retrieval/assembly and total user-visible completion. The present five-second target excludes model time and therefore cannot stand alone as the answer-time promise.
- Define the 70% acceptance-rate denominator, treatment of reviewer edits and exclusions. Report acceptance alongside support errors, duplicate rate and review effort so accepting easy notes does not mask low value.
- Replace “mostly overlapping” with labeled finding coverage and an unsupported-claim measure. Agree numeric thresholds before comparing two agents; wording similarity is insufficient.
- Test complete-response token accounting at normal and undersized budgets. Citations, freshness and scope metadata are part of the useful result, not optional overhead to discard.
- Give the under-two-minute human answer target a representative question set, named start/end events and a chosen percentile across team participants.

## Compiled briefs and launch scope

A compiled brief combines several accepted notes into a cited summary, comparison or overview. For example, “Which branching techniques reduce production cost?” could assemble findings, case studies and cost datapoints with source links and caveats. This differs from a search result list or one node's summary.

Under the confirmed workflow, a local agent can retrieve evidence, write a synthesis and submit it through MCP. Once accepted, the website displays it as a readable node. The owner agreed with starting from search/reading and external agent workflows: initially there is no reasoning agent inside KB. A dedicated brief tool remains optional P1; it does not block problem/solution navigation or reading accepted syntheses.

## Source reference and knowledge navigation follow-up

PRD 0.5 adds concrete source and browsing contracts in sections 6.3.3 and 6.5. These are product requirements and a proposed transfer design, not implemented capabilities.

- **Files and URLs:** MCP exposes KB-defined intake tools. Original bytes live in private artifact storage; source metadata, immutable revision manifests and citation locations live in canonical records. A link-only record is allowed but cannot masquerade as archived evidence. A proposed local MCP connector reads selected files and transfers them to the VPS; a server cannot read a client-local path. Upload/resume limits and all four harness integrations need verification.
- **Reading references:** source pages show original links, capture/extraction availability, archive downloads/previews where supported and citing notes. Verify that a citation still opens the correct revision after the original URL changes, and that an interrupted upload never becomes accepted evidence.
- **Grouping:** problem and concept nodes provide persistent navigation; typed edges explain which approaches address a problem, under what conditions, and where the evidence comes from. Tags filter across these groups. A technique can address multiple problems without duplication.
- **Related results:** accepted incoming/outgoing links are separate from similarity suggestions with displayed reasons. Suggestions do not establish solution validity and cannot become canonical edges without MCP proposals. A graph canvas is optional; basic connected browsing is P0 FR-U9.
- **No internal agent:** test that people can navigate problems, alternatives, cases and references while all local agents are offline. External agents supply semantic judgments; deterministic service checks do not independently prove them true. Source parsing/indexing and read-time discovery do not imply an embedded agent.

The MCP distinction was checked against the official [tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) and [resources specification](https://modelcontextprotocol.io/specification/2025-11-25/server/resources): schema-defined tools and resource retrieval support building this workflow, while the upload API and connector remain KB implementation work.

## Remaining design decisions

1. **Automatic policy details:** finalize the proposed eligibility for additive sources and evidence-backed notes/datapoints, support-assessment rules and exceptions. Automatic acceptance is confirmed; blanket human approval is not a pending option.
2. **Deployment sizing:** VPS capacity, simultaneous agent/user load and backup/restore ownership. Local-first development followed by VPS operation is settled.
3. **Protected intent:** project/shared-policy ownership and a trustworthy way to record owner authorization through the local-agent/MCP workflow, without allowing agents to self-authorize policy changes.
4. **Optional briefs:** confirm later whether a dedicated brief tool adds value beyond agent-written synthesis nodes. It does not block the core search/read and MCP contribution workflow.
5. **Pilot material:** confirm the first two projects and provide representative sources/questions, including the referenced report when available.

## Changes made and review boundary

The subsequent [Jev and SCAR/Winnow implementation review](LOCAL_AGENT_IMPLEMENTATION_REVIEW.md) informs PRD 0.6. It adds durable external-agent run state, version/capability discovery, structured support assessments and explicit distinctions between reusable patterns and incompatible reference behavior. [Eight isolated probes](reviews/LOCAL_AGENT_PROBES.json) support that review; they do not establish live harness, source-extraction or VPS acceptance.

Updated PRD.md through 0.5 and aligned GOAL.md with the owner’s explicit MCP-only contribution, read-only web, automatic-acceptance, no-internal-agent and local-to-VPS target. Existing requirement IDs remain; FR-V3 is P0, FR-U6 is a read-only freshness view, FR-V2 handles MCP proposal feedback and exceptions, and FR-U9 adds problem/topic navigation. The exact automatic eligibility shown in the registry is an illustrative recommendation. The example note remains an unverified draft.

The report uses the supplied documents, the owner's answers and the protocol references above. It does not depend on external product comparisons or claims about unavailable Jev/Winnow implementations. Verification is limited to documentation and protocol contracts; no upload or browsing implementation has been tested. Git is now available in the workspace; these document changes remain uncommitted, preserving the existing working-tree edits.