vasily/GEWU
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Ajasra committed 2026-10-13 12:36:21 +08:00
1 parent b7c11bbe2d
commit 7fb257095f
31 files changed
+1770 -317
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/GOAL.md
+14 -5
View File
@@ -1,21 +1,30 @@
# Project North Star: KB
# Project North Star: GEWU
KB is a local-first, multi-project knowledge base for people and AI agents. It turns collected sources into scoped, evidence-backed notes and linked syntheses that remain traceable, reviewable, and reusable across projects and tools.
**Tagline:** Investigate. Connect. Remember.
**Name:** GEWU (格物) draws on *géwù zhìzhī* (格物致知), a classical phrase commonly rendered as investigating things and extending knowledge. Its interpretations vary across traditions. Here it evokes examining sources, connecting evidence-backed ideas, and preserving what teams learn for reuse.
GEWU is a local-first, multi-project knowledge base for people and AI agents. It turns collected sources into scoped, evidence-backed notes and linked syntheses that remain traceable, reviewable, and reusable across projects and tools.
## Core Mission
Help project teams find and reuse trustworthy knowledge without losing its source, scope, freshness, or uncertainty. People can explore and curate the knowledge through a web UI; agents can retrieve cited, budgeted results through typed MCP and HTTP interfaces, and contribute only through validated proposals.
Help project teams find and reuse trustworthy knowledge without losing its source, scope, freshness, or uncertainty. People search, explore and read knowledge through a read-only web UI. Local agents running in Codex, Claude, Antigravity and OpenCode retrieve cited, budgeted results and contribute exclusively through typed MCP proposals. The service validates and automatically accepts eligible proposals under owner-defined policy; humans do not approve every knowledge change. Development runs locally first, with the shared service deployed to the owner’s VPS afterward.
Initially GEWU contains no reasoning agent. It stores original source artifacts or explicit reference-only records, exposes traceable citations, and lets people navigate problems, approaches, concepts and their connections without an agent running. Local agents perform interpretation and propose new knowledge and relationships. Tags support filtering; typed links explain how nodes relate.
The initial pilot serves up to five people across 'Dome interactive content' and an 'Interactive Video Platform/Service'. Start with a smaller pilot while retaining the full v1 requirements. Human roles are admin, editor and viewer; editing uses MCP proposals under the read-only web target. Each local agent has its own revocable API key and stable identifier for attribution. Same-agent extraction and support assessment are allowed with recorded assessments and quality sampling. All team members initially read all projects; restricted project access is a later phase.
## Invariant Non-Negotiables
1. **Evidence before assertion**: Every claim and datapoint must trace to a source and a quote location. Validation checks the evidence against the archived source when available; unsupported interpretations remain clearly identified as interpretations.
2. **Project scope is explicit**: Every node belongs to one registered project or the shared library. Cross-project relevance is represented through explicit typed links and project-specific lens fit, never by silently copying or blending project knowledge.
3. **Humans own project intent**: Project owners control the north star, key questions, and autonomy policy. Agents can propose changes, but cannot directly change those human-owned goals.
4. **Proposals are the write boundary**: Agents submit changes to staging. Shared validators enforce schemas, scope, link rules, and evidence requirements before a proposal can be accepted into the knowledge base.
4. **Proposals are the write boundary**: Local agents submit changes to staging through MCP. Eligible proposals can be accepted automatically under the configured policy; exceptions remain reviewable through the local agent workflow. Shared validators enforce schemas, scope, link rules, and evidence requirements before a proposal can be accepted into the knowledge base.
5. **Git files are the source of truth**: Markdown and YAML records remain directly inspectable and versioned. Search indexes are derived, disposable, and rebuildable from those files.
6. **One core, multiple interfaces**: The UI, CLI, MCP server, and HTTP API use the same scoped service and validation rules. No interface grants agents a privileged write path or exposes raw database queries.
6. **One core, multiple interfaces**: The read-only UI/HTTP API, maintenance CLI and MCP server use one scoped core. Knowledge contributions enter exclusively through MCP proposals; no interface grants an unvalidated write path or exposes raw database queries.
7. **Trust survives change**: Preserve history and audit records; link contradictions instead of overwriting them; retain superseded knowledge; and disclose staleness whenever dated information is retrieved.
8. **Local-first and agent-agnostic**: The system remains useful with local files and local models, runs across Windows, macOS, and Linux, and does not depend on any one agent harness or vendor integration.
9. **Replaceable modules**: Development separates responsibilities behind explicit public contracts. Service components, local-agent capabilities, skills, pipelines and UI modules can be updated or replaced through tested compatibility and migration paths without rewriting unrelated parts of the system.
## Definition of Success
docs/LOCAL_AGENT_IMPLEMENTATION_REVIEW.md
+103
View File
@@ -0,0 +1,103 @@
# Lessons from Jev and SCAR/Winnow for KB
12 October 2026 · Implementation and skill review · Companion PRD: 0.6
## Recommendation
Build KB as its own service, borrowing Jev's shared-runtime engineering and Winnow's research procedures. Local agents remain the reasoning layer. KB owns canonical sources, schemas, scope, durable proposals, automatic acceptance policy, retrieval and the read-only web application. Neither reference implementation provides KB's complete evidence-and-acceptance boundary today.
Use patterns and selectively port small utilities after testing their assumptions. Do not make KB depend on Jev's semantic provider, lifecycle hooks, or Winnow's direct access to the canonical vault.
## Review scope and evidence
| Reference | Snapshot inspected | Evidence boundary |
| --- | --- | --- |
| Jev | `D:/01_GIT/Jev`, HEAD `bca82bb245389dc3ccdcef516878f33b11b71d47`, with substantial existing modified/untracked implementation and test files | Findings describe the current working tree, not just that commit. Read contracts, registry, MCP transport, knowledge/verification/context code, storage claims, installer, diagnostics, selected tests and acceptance records. |
| SCAR/Winnow | `D:/07_RESEARCH/SCAR/.agents` is a symlink to `.opencode`; owning configuration repo HEAD `d67763617a5c9f16689332737878e4d81b9c9f99`, with clean reported status | Read canonical skills/protocols and source-processing wrappers/scripts. Skills are instructions for an external agent; a section called “State Machine” is not evidence of a persisted execution engine. |
| Current-turn probes | Eight isolated Python probes, with temporary files/SQLite and no provider calls | [Results](reviews/LOCAL_AGENT_PROBES.json). No live MCP/harness, real PDF quality, VPS upload, concurrency or complete test suite was exercised. |
The reference repositories were not edited or installed. A command-scoped safe.directory setting allowed read-only Git inspection of the administrator-owned Winnow configuration repo; no global Git settings changed. Existing Jev acceptance documents were read as historical records, not treated as current live verification.
## What to take from Jev
| Pattern and implementation evidence | What is already useful | Application to KB |
| --- | --- | --- |
| [Tool registry](D:/01_GIT/Jev/src/jev/registry.py:37) and [MCP adapter](D:/01_GIT/Jev/src/jev/transports/mcp.py:12) | Tools declare handlers once and MCP exposure is generated. The probe resolved all eight registered tools to handlers. | Use one versioned operation catalog with request/response schema, read/propose/maintenance capability and allowed transport. HTTP exposes reads; MCP exposes proposals. A mutating flag alone is not authorization. |
| [Neutral contracts](D:/01_GIT/Jev/src/jev/contracts.py:54) | Core contracts carry workspace/session/agent/invocation identity and explicit capabilities. | Keep KB requests independent of harness-native events. Include project, run, proposal, source revision and authenticated actor; keep self-reported harness/model separate from authorization. |
| [Context envelope](D:/01_GIT/Jev/src/jev/core/context.py:17) | Current request, session objective and project goal are separate; output is bounded. | Supply local agents with explicit H1/H2 plus authoritative project context/H3 from KB. Avoid uploading entire transcripts. Never infer canonical project identity or owner intent from cwd or the first prose line of a README. |
| [Replay claims](D:/01_GIT/Jev/src/jev/services/storage.py:502) | Claims use identity, operation digest and policy version. Same-operation replay and changed-digest re-evaluation were observed. | Adapt to proposal IDs plus payload digest/base revision/schema/policy versions. Add fencing for stale workers and atomic git/receipt recovery. Jev's single-process probe does not establish those stronger guarantees. |
| [Owned config merge](D:/01_GIT/Jev/src/jev/install/opencode.py:158) | The merge function preserves other MCP entries and existing skill paths; the installer has backup/manifest/uninstall machinery. | A KB connector installer should change only owned entries, preserve other tools, record installed versions and offer a copy/configuration fallback where symlinks are unavailable. Review exact rollback behavior before code reuse. |
| [Diagnostics](D:/01_GIT/Jev/src/jev/install/doctor.py:102) and [acceptance protocol](D:/01_GIT/Jev/.agents/protocols/cross-platform-acceptance-protocol.md) | Paths, identities, registered capabilities and explicit per-harness evidence are exposed. | Add diagnostics for service identity, local/VPS endpoint, authenticated capability, selected project, schema/skill versions, transfer limits and index lag. Separate “configured,” “connected,” and “workflow passed.” |
| [Knowledge presentation tiers](D:/01_GIT/Jev/src/jev/core/knowledge.py:47) | Stronger matches can supply content; weaker ones become lightweight hints. | Adopt progressive disclosure: concise search cards, full nodes and bounded neighbors. Keep relevance separate from evidence confidence. Hooks that auto-inject content remain optional P2. |
### Jev behavior not suitable for direct reuse
1. **The verifier is advisory, not an evidence gate.** [evaluate_verification](D:/01_GIT/Jev/src/jev/core/verification.py:121) returns `verified: true` with `support_level: extrapolated` when reference context or the provider is absent, and similarly on provider error. The missing-reference behavior was reproduced. KB must return pending/unavailable and hold acceptance when a required check is missing. Retrieval can degrade to keyword search; evidence validation cannot degrade into success.
2. **Knowledge writes bypass the required KB boundary.** [learn](D:/01_GIT/Jev/src/jev/core/knowledge.py:95) creates/updates files directly, chooses a potential existing item using model confidence and appends prose. A direct call succeeded with empty evidence. [knowledge_learn](D:/01_GIT/Jev/src/jev/tooling.py:16) also catches audit-record failures after writing. KB needs complete proposal bundles, explicit dedupe decisions, preserved disagreements and acceptance receipts that are not best-effort telemetry.
3. **Its search is a routing mechanism.** The inspected path selects one item; the model candidate list is capped at 254 items. The no-provider keyword match uses ASCII word extraction and is capped at 0.69, yielding a hint. This is not multi-result, project-scoped hybrid retrieval for 100,000 nodes. Adopt the presentation idea, not this retrieval implementation.
4. **Its budget is measured in characters.** [merge_results](D:/01_GIT/Jev/src/jev/contracts.py:124) slices context strings to the remaining character count. The probe cut a citation mid-string. KB needs token accounting over complete serialized result groups, including citations and warnings.
5. **Harness coverage is bounded.** The inspected enum/adapters name Antigravity, Codex and OpenCode, not Claude. Shared MCP support may be portable, but it is not proof of all four KB client workflows. A stored [Codex acceptance record](D:/01_GIT/Jev/docs/testing/windows-antigravity-codex-acceptance.md:34) reports a workspace-root mismatch; that historical issue was not retested here. It reinforces the need for explicit service/project identity and live receipts.
## What to take from SCAR/Winnow
| Procedure and source | Useful part | Required KB adaptation |
| --- | --- | --- |
| [Research pipeline](D:/07_RESEARCH/SCAR/.agents/skills/research-pipeline/SKILL.md:19) | Separate intake, atomization, auditing and a final report. | External agents run these stages against MCP. Persist inputs, source revision, skill version, outputs and receipts so another agent can resume a run. |
| [Skill template and concerns mapping](D:/07_RESEARCH/SCAR/.agents/skills/skill-architect/references/sample-skill.md:33) | A skill declares only the protocols it needs; inputs, processing and outputs are explicit. | Maintain a portable KB skill pack with concerns such as evidence, scope, relationships, proposals and synthesis. Reference authoritative schemas rather than restating rules in every prompt. |
| [Atomic shatterer](D:/07_RESEARCH/SCAR/.agents/skills/atomic-shatterer/SKILL.md) | A source becomes reusable, linked units with traceable origins. | Produce claim/problem/technique/entity proposals with field-level evidence. Use goal relevance and bounded batches; account for skipped or deferred source sections rather than extracting every term without limit. |
| [Concept consolidator](D:/07_RESEARCH/SCAR/.agents/skills/concept-consolidator/SKILL.md:44) | Preserve conflicting perspectives, explain how concepts interact, retain extracts, and redirect merged identities. | Use typed relationships with conditions and evidence. Keep separate claims/framings where they differ; merge only demonstrated duplicates. Derive incoming links instead of writing reciprocal edges into every node. |
| [Epistemic auditor](D:/07_RESEARCH/SCAR/.agents/skills/epistemic-auditor/SKILL.md) and [fact grounder](D:/07_RESEARCH/SCAR/.agents/skills/fact-grounder/SKILL.md) | Distinguish contradictions, methodological tension and claims missing references; audit statements individually. | Return structured assessments citing claim and source-revision IDs, method, assessor and rationale. Link presence is not support proof; supplementary web findings must first become checkable source captures. |
| [Comparative matrix](D:/07_RESEARCH/SCAR/.agents/skills/comparative-matrix/SKILL.md) | Compare methodology, evidence/sample, findings and limitations; preserve agreement, discrepancy and gaps. | Use this as an external-agent synthesis skill and as guidance for web problem/solution pages. Tailor comparison fields to technical/math conditions; keep unknowns explicit. |
| [Grounding protocol](D:/07_RESEARCH/SCAR/.agents/protocols/GROUNDING_CITATION.md) | Put citations directly beside claims, with granular locations. | Replace informal wikilink/page text with stable IDs and typed revision/location references; generate readable links from these records. |
### Winnow behavior not suitable for direct reuse
1. **PDF extraction loses locators.** [pdf_conv.py](D:/07_RESEARCH/SCAR/.agents/scripts/pdf_conv.py:13) concatenates page text and collapses blank lines without recording page IDs or source offsets. A two-page mocked extraction reproduced the loss of page boundaries. Keep original bytes and a page/block/span map with parser version and explicit extraction status. Real multi-column, mathematical and scanned-page quality still needs a labeled corpus; conversion success is insufficient.
2. **arXiv retrieval creates cards, not an original-file archive.** [arxiv_fetch.py](D:/07_RESEARCH/SCAR/.agents/scripts/arxiv_fetch.py:56) extracts metadata and links and strips the version from the separate arxiv_id field. The original URL is retained, but [arxiv_puller.ts](D:/07_RESEARCH/SCAR/.agents/tools/arxiv_puller.ts) writes title-named cards; it does not download the PDF. KB must preserve versioned identifiers and source bytes when claiming an archived original. Use stable source identity rather than title-only paths, and do not overwrite reading notes on re-import.
3. **Prompt instructions are not durable orchestration.** The reviewed pipeline has numbered states in Markdown, but no executable state store or restart contract for those stages. KB should persist run manifests and receipts while leaving stage execution with external agents. Interrupted jobs resume from verified artifacts rather than conversational recollection.
4. **Canonical sources should remain immutable.** The shatterer [prepends a table of contents](D:/07_RESEARCH/SCAR/.agents/skills/atomic-shatterer/SKILL.md:47) to its input and writes new notes directly. In KB, such a table belongs in a source reading view or separate synthesis, never in archived source bytes.
5. **Avoid the blanket git-safety pattern.** [git_safety_commit.ts](D:/07_RESEARCH/SCAR/.agents/tools/git_safety_commit.ts:26) stages all changes in the current repository. Its shell wrappers also interpolate file paths or messages into command strings. KB should use argument-vector subprocess calls where needed, bounded local artifacts and service-owned commits of exactly the accepted change set. Local agent skills must not stage unrelated user files.
6. **Keep portability explicit.** The skills share one canonical directory, but wrappers are OpenCode plugin tools and assume `.opencode` relative paths. Do not assume those tool names exist in Codex, Claude or Antigravity. A KB connector and skill manifest should expose the same contract through each client without requiring vault layout or symlinks.
## Recommended division of responsibilities
| Component | Owns | Does not own |
| --- | --- | --- |
| Local KB skill pack | Source triage, atomic extraction, semantic support assessment, typed links, comparisons and synthesis proposals | Canonical writes, policy overrides, user-global safety commits |
| Local MCP connector | Explicit file selection/read, bounded transfer, endpoint/auth configuration and compatibility diagnostics | Reasoning, semantic acceptance decisions or independent knowledge storage |
| KB service | Artifact integrity, immutable revisions, schema/scope/evidence-location checks, run state, proposal policy, durable receipts, git and derived indexing | An embedded agent or unrecorded semantic judgments |
| Read-only web app | Search, source/quote reading, problem/solution/topic navigation, labeled related suggestions and history | Ingesting, editing, approving or generating knowledge |
### Initial external-agent skill pack
Use four public entry points with shared protocols and internal stages, rather than installing every Winnow writing skill:
- **kb-ingest:** identify source/project, capture/upload, fetch project intent, triage, extract evidence-backed nodes, assess support, propose links, submit bounded bundles and report accepted/pending outcomes.
- **kb-query:** retrieve scoped results, inspect evidence and neighbors, answer with citations and freshness; explicitly identify insufficient evidence.
- **kb-curate:** find duplicates, contradictions, stale records and orphan nodes; propose links, corrections or reversible merges under policy.
- **kb-synthesize:** assemble a cited comparison or guide from accepted node revisions and submit a synthesis proposal; preserve conditions, disagreements and missing data.
Each skill declares its version, compatible KB schema/tool versions, concerns, input/output contracts and resume behavior. Skills stay outside the server reasoning path. No hooks, embedded model, or automatic watcher is needed to exercise the complete v1 workflow.
### Bounded acceptance recommendations
- Permit automatic acceptance of eligible additive knowledge with all required evidence/support records. A high routing confidence or a “verified” boolean from an external tool cannot substitute for the KB contract.
- Persist semantic support as an external assessment, including assessor identity, cited revision and rationale. Missing or failed assessment is pending/unavailable, not successful. The service enforces completeness and deterministic checks without claiming to independently prove meaning.
- Separate transient diagnostics from durable acceptance receipts. Optional telemetry loss must not undo accepted work; missing canonical acceptance evidence must never be silently ignored.
- Bind replay to operation content and authoritative revisions. Persist enough information outside the disposable search index to recover after reindexing or a commit/index crash. Do not assume an SQLite hook lease solves git publication concurrency.
## Applied to PRD 0.6
1. Made external-agent skills and versioned protocol/schema discovery explicit.
2. Added P0 durable external-run manifests and resumable, bounded ingestion (FR-I11).
3. Added P0 client/service capability diagnostics and version compatibility checks (FR-A10).
4. Strengthened missing-evidence failure semantics, page-map extraction, bounded atomization and preservation of disagreements.
5. Required operation-catalog transport permissions, digest-bound replay, durable receipts, citation-safe budgets and per-harness workflow evidence.
These updates refine the existing product boundary. They do not add an internal agent, a writeable web UI, mandatory manual approval, or a dependency on Jev/Winnow at runtime.
## Verification and remaining uncertainty
The [probe receipt](reviews/LOCAL_AGENT_PROBES.json) records eight observed behaviors, including mismatches with KB requirements. Those observations are not a blanket pass for either project. Jev tests were read but its full suite was not run; the MCP SDK registration path and all four client integrations were not exercised. Winnow skill quality, complete source processing and PDF extraction fidelity remain unmeasured by this review. Historical acceptance reports include qualified and user-reported results and are not proof of the current working tree.
The next implementation gate is one local source-to-proposal-to-read workflow with exact evidence, replay and restart checks; then demonstrate it through each supported harness and the VPS transfer path. Use the findings here as design and test inputs rather than assuming copied code is already accepted for KB.
docs/PRD.md
+368 -312
View File
@@ -1,10 +1,24 @@
# Multi-Project Knowledge Base for Humans and AI Agents
# GEWU — Multi-Project Knowledge Base for Humans and AI Agents
Working name: KB | Version 0.2 (draft) | 12 Oct 2026 | Status: for review
**Tagline:** Investigate. Connect. Remember.
**Name:** GEWU (格物) draws on *géwù zhìzhī* (格物致知), a classical phrase commonly rendered as investigating things and extending knowledge. Its interpretations vary across traditions. Here it evokes examining sources, connecting evidence-backed ideas, and preserving what teams learn for reuse.
Version 0.7 (draft) | 12 Oct 2026 | Status: target-alignment and release-readiness review; owner decisions pending
Current review: [Target alignment and release readiness](reviews/PRD_TARGET_READINESS.md). This revision clarifies acceptance and delivery gates without changing existing P0/P1 priorities. Earlier reviews below retain their historical scope.
Owner decisions confirmed during this review: a smaller pilot precedes full v1; the pilot projects are Dome interactive content and an interactive video platform/service, for up to five people initially. Routine notes may be extracted and support-assessed by the same local agent, with recorded assessment and quality sampling. Human roles are admin, editor and viewer. Each local agent receives its own API key and stable identifier. Project-restricted access follows later; all-team read access remains the initial target. “Editor” is interpreted as MCP proposal permission under the existing read-only web target.
Review report: [PRD_REVIEW.md](PRD_REVIEW.md). Target confirmed on 12 Oct 2026: a shared team plus agents; every team member may read every project in v1. Confirmed workflow: local development first, deployment to the owner’s VPS later; a read-only web app; knowledge contributions exclusively through MCP from local Codex, Claude, Antigravity (agy) and OpenCode agents. Eligible proposals may be accepted automatically; exact eligibility rules remain to be finalized.
Implementation-reference review: [Jev and SCAR/Winnow lessons](LOCAL_AGENT_IMPLEMENTATION_REVIEW.md), with [isolated probe evidence](reviews/LOCAL_AGENT_PROBES.json). Reuse recommendations are bounded by the reviewed working trees; neither project is a required runtime dependency.
## Summary
KB is a local-first, git-based knowledge base that turns collected material (web pages, papers, reviews, NotebookLM exports, talks, internal notes) into verified, linked, reusable knowledge. It serves two kinds of readers equally: people (through a web UI) and AI agents (through MCP and an HTTP API). One installation hosts many projects, each identified by a project_id (for example interactive-video, dome-performance, agentic-design). Projects keep their own goals, taxonomies and curated notes, and can draw on a shared library of sources, entities and concepts.
GEWU is a local-first, git-based knowledge base that turns collected material (web pages, papers, reviews, NotebookLM exports, talks, internal notes) into evidence-backed, linked, reusable knowledge. It serves two kinds of readers equally: people (through a web UI) and AI agents (through MCP and an HTTP API). One installation hosts many projects, each identified by a project_id (for example interactive-video, dome-performance, agentic-design). Projects keep their own goals, taxonomies and curated notes, and can draw on a shared library of sources, entities and concepts.
The core idea is three layers: immutable sources, atomic notes extracted from them with evidence, and compiled syntheses (briefs, market overviews, timelines, comparison tables) built from the notes. Agents write only by submitting proposals that pass a validator.
The v1 delivery target is a team-operated KB service with a shared web UI and agent access. One authoritative repository and service coordinate accepted changes. Team members may read all projects; project scope controls relevance, not confidentiality. Authentication and permissions to propose, evaluate, and manage project intent are required. The service validates and automatically accepts eligible proposals under the project policy; routine knowledge does not require human approval. Development runs locally first, then the same service and canonical data move to the owner’s VPS. Local agent harnesses connect to that service through MCP. The web app only searches, navigates and displays knowledge; it has no capture, edit, review-decision or acceptance controls.
## Problem and opportunity
- Research for a project is scattered across browser tabs, PDFs, NotebookLM notebooks and chat histories, and is hard to reuse by a different person, agent or project.
@@ -22,40 +36,25 @@ Goals
6. Multi-audience value. The same nodes serve developers, product managers, project managers and sales through facets and saved lenses.
7. Trustworthy over time. Dated claims, staleness tracking, contradiction links and a full audit trail.
Non-goals (v1)
- Real-time multi-user collaborative editing (git-based collaboration only).
- Real-time collaborative editing of the same document. Shared search and reading are in scope; MCP proposal processing and accepted changes are serialized through the service into git.
- Hosting copyrighted source texts for redistribution. KB stores notes, short quotes and links, and keeps archived copies private.
- Replacing project management, CRM or code search tools. KB feeds them knowledge but does not manage tasks or deals.
- A general-purpose chatbot. Agents use KB as a tool, and the UI is for navigation, review and reading.
- A general-purpose chatbot. Agents use KB as a tool, and the UI is for search, navigation and reading.
- A story-map authoring editor (a canvas for drawing branching story flows) and an embedded in-UI copilot. Agents reach KB through MCP, and story authoring is a separate product.
- An internal reasoning agent, autonomous research loop or server-hosted curator in the initial system. Ingest, interpretation, semantic linking and synthesis run in external local agents. Server parsing, indexing, retrieval and policy validation are ordinary service functions; embedding computation does not imply an agent inside KB.
## Users and use cases
User
Typical needs
Example
Developer
Problems and proven techniques, architecture precedents, case studies
How do interactive movies avoid combinatorial explosion of branches?
Product manager
Market shape, competitors, user problems, feature precedents, comparisons
Compare how three titles handled player choice pacing.
Project manager
History, timelines, cost and schedule datapoints, risks
Timeline of interactive film production tooling for a kickoff deck.
Sales
Market overview, positioning, proof points, objections, as-of numbers
Current market size claims and who made them.
Ingest agent
Digest a source against the project goal and propose notes
Process a new paper into proposals with evidence and edges.
Consumer agent
Retrieve cited knowledge during coding, writing, budgeting, marketing
Fetch a brief for a presentation with token budget 2,000.
Curator agent
Find stale, duplicate, contradictory or orphan nodes
Weekly report of stale market datapoints.
Project owner
Define the goal, review proposals, set autonomy levels
Approve new notes, update the north star.
| User | Typical needs | Example |
| --- | --- | --- |
| Developer | Problems and proven techniques, architecture precedents, case studies | How do interactive movies avoid combinatorial explosion of branches? |
| Product manager | Market shape, competitors, user problems, feature precedents, comparisons | Compare how three titles handled player choice pacing. |
| Project manager | History, timelines, cost and schedule datapoints, risks | Timeline of interactive film production tooling for a kickoff deck. |
| Sales | Market overview, positioning, proof points, objections, as-of numbers | Current market size claims and who made them. |
| Ingest agent | Digest a source against the project goal and propose notes | Process a new paper into proposals with evidence and edges. |
| Consumer agent | Retrieve cited knowledge during coding, writing, budgeting, marketing | Fetch a brief for a presentation with token budget 2,000. |
| Curator agent | Find stale, duplicate, contradictory or orphan nodes | Weekly report of stale market datapoints. |
| Project owner | Define intent, set autonomy policy and resolve exceptions through local agent workflows | Authorize a goal change or resolve an ambiguous knowledge proposal without approving every note. |
## Multi-project model
This section defines how one database serves many projects.
@@ -68,366 +67,373 @@ Each project has a registry entry projects/<project_id>/project.md with frontmat
- key_questions, watch_list (competitors, technologies, titles, people), out_of_scope.
- audiences: which audiences the project cares about.
- taxonomy_extensions: project-specific domain tags and node subtypes added to the core vocabulary.
- autonomy_policy: per node type, one of suggest, auto-merge-safe, research-on-gap.
- autonomy_policy: per node/change type, suggest or auto-merge-safe, with required evidence/support checks and exception rules. research-on-gap is a separate research trigger, not an acceptance permission.
- default_includes: other projects or shared whose nodes appear in this project's searches by default.
Horizons 1 (current request) and 2 (session objective) are not stored in the registry. The agent derives them per task and records them in the run log.
### 5.2 Scope of every node
Every node has project_id, which is either a registered project or the reserved value shared.
Scope
What lives there
Rule
Project
Notes, syntheses, project-specific cases and datapoints
Owned by one project. Reviewed against that project's lens.
Shared
Sources, entities (companies, people, tools, titles), general concepts, cross-domain techniques
Deduplicated globally. Any project can reference them.
| Scope | What lives there | Rule |
| --- | --- | --- |
| Project | Notes, syntheses, project-specific cases and datapoints | Owned by one project. Reviewed against that project's lens. |
| Shared | Sources, entities (companies, people, tools, titles), general concepts, cross-domain techniques | Deduplicated globally. Any project can reference them. |
Rules:
1. Sources and entities default to shared, so one paper or company is stored once and referenced by many projects.
2. Notes default to the project that triggered ingestion. A note can be promoted to shared when it is useful beyond the project, through a review action that records who promoted it and why.
3. Cross-project links are allowed and explicit. A project node can link to a shared node or to a node in another project with a typed edge. The edge records the project pair, and the UI and API mark it as cross-project.
4. Relevance is per project. A node has lens_fit keyed by project: a note about agentic design patterns can carry a high score for agentic-design and a medium score for interactive-video, without being copied.
5. Default query scope is the active project plus its default_includes and shared. Other scopes are opt-in (projects=[...] or all).
5. Every content operation supplies an explicit project/scope context. If includes are omitted, the server resolves that project's default_includes plus shared. Other scopes are opt-in (projects=[...] or all). Responses report the resolved scope and origin of each returned node; no transport silently infers a project from an earlier session.
6. Scope applies to direct ID lookups, graph traversal, comparisons, citations, syntheses and MCP resources as well as search. An out-of-scope ID cannot expand a request's scope. Cross-project targets outside the resolved scope are marked as omitted, with an explicit action to widen scope.
### 5.3 Identity and layout
- Node IDs are globally unique and stable: <project_id>:<slug> for project nodes and shared:<slug> for shared nodes. Renames create redirects.
- Node IDs are globally unique: <project_id>:<slug> for project nodes and shared:<slug> for shared nodes. IDs remain stable on title and file renames. Promotion to shared changes the namespace through one reviewed migration that creates a permanent old-ID redirect, updates references, and preserves origin and history; IDs are never reused. Redirect resolution remains subject to the destination scope.
- Repository layout (single repo, namespaced):
```text
kb/
shared/{sources,entities,notes,synthesis}/
projects/<project_id>/{project.md,notes,synthesis,staging,runs,lens/}
schema/ protocols/ skills/ src/ docs/
```
- A separate repo per project is not used in v1, because shared sources and cross-project links would need duplication or submodules. The repo can still be split later because every node carries its project_id.
### 5.4 Isolation and export
- v1 is a single-owner or small-team setup. Isolation is logical: every API call takes an explicit scope, and the validator rejects nodes with an unknown project_id.
- v1 serves one trusted team and its agents. All authenticated team members may read every project, but every content API call still supplies scope and the validator rejects unknown project_id values. Logical project separation is not a confidentiality boundary.
- All network interfaces authenticate callers. The service authorizes reader, proposer, reviewer and project-owner capabilities; agent credentials are limited to reading and proposing. Changes to human-owned intent and autonomy policy require attributable project-owner authorization submitted through the MCP workflow; agents cannot self-authorize those changes. The owner-authorization mechanism is an M0 contract decision and must not rely on an agent merely claiming that approval occurred. Audit records distinguish the authenticated caller from a self-reported agent/model identity.
- Per-project export (nodes, linked shared nodes, and an index) must be possible so a project can be handed over or archived.
- Per-project access control (read, propose, merge) is a P2 requirement and the schema must not block it.
- Per-project confidentiality and granular project ACLs remain P2 under the confirmed all-team-read target. Team authentication and mutation permissions are P0 and cannot be deferred with those ACLs.
Acceptance authority follows the records changed, not just the project that initiated a run. A project policy cannot authorize mutations to shared records or another project's records. Shared has explicitly assigned owners and its own acceptance policy. M0 must define whether bundles spanning policy domains are accepted atomically under every affected policy or submitted as ordered dependent proposals. Partial application must never be reported as complete acceptance; missing policy or authorization holds the affected change. Read scope and lens relevance grant no mutation authority.
Initial human roles and agent identity:
| Principal | Initial permissions | Boundary |
| --- | --- | --- |
| Viewer | Read all projects through the website and permitted read tools | Cannot propose or decide changes. |
| Editor | Viewer permissions plus knowledge proposals and corrections through MCP | Cannot change protected intent/policy or administer credentials without a separate owner/admin grant. The website remains read-only. |
| Admin | Manage members, role assignments, agent credentials and project/shared ownership; bootstrap the first owner | Protected knowledge/intent changes still use validated, attributable MCP workflows. Credential administration is a control-plane operation, not a knowledge-authoring bypass. |
| Local agent | Read and propose within capabilities assigned to its credential | Has a unique stable agent_id and its own revocable API key; cannot inherit admin powers from the human running its harness. |
Project-owner authority is an explicit grant, separate from the editor role. M0 specifies how admin and owner grants interact and how humans authenticate protected decisions without disclosing their credentials to an agent. Agent credentials bind server-side to agent_id, responsible human, capabilities and a non-secret key identifier. Rotation preserves agent_id; revocation prevents subsequent requests and acceptance evaluation rechecks current authorization. Audit records retain agent_id, key identifier, responsible human, proposal/run IDs, policy and resulting revisions; self-reported model/harness labels cannot override that identity. Never store raw keys in git, logs or node metadata. Key issuance, rotation, revocation and attribution are P0 acceptance cases. Simultaneous agent load remains to be sized separately from the five-person pilot.
## Content model
### 6.1 Layers
1. Source (immutable): archived snapshot or reference, hash, bibliographic and reliability metadata. Never edited by agents.
2. Note (atomic): one finding, claim, problem, technique, case, datapoint or event, with evidence quote and location.
3. Synthesis (compiled): topic pages, briefs, market overviews, timelines and comparisons, regenerated from notes.
3. Synthesis (compiled): topic pages, briefs, market overviews, timelines and comparisons assembled from accepted notes. A compiled brief is a cited summary across multiple notes, such as a comparison of branching techniques. Local agents can create or refresh a saved synthesis and submit it through MCP; once accepted, the website displays it like other knowledge. Whether KB also needs a dedicated brief retrieval/assembly tool remains a P1 scope decision; a model running on the VPS or generation inside the website is not required.
### 6.2 Node types
Source, Finding/Claim, Problem, Technique/Solution, Case, Entity, Datapoint, Event, Concept, Synthesis. Projects may add subtypes through taxonomy_extensions.
Project subtype packs. A project adds subtypes and fields through its registry, and the same validator checks them. The interactive-video pack starts with these four, taken from the deep-research report:
Subtype
Based on
Key fields
Production case
Case
release year, studio, delivery medium (FMV, real-time 3D, streaming player, theatrical), budget, reported revenue, units sold, total and average playthrough runtime, shooting ratio, decision points, endings
Narrative mechanism
Technique
paradigm (branch-and-bottleneck, state variable, storylet, database cinema, foldback), complexity class, authoring overhead, agency profile
Technical constraint
Problem
domain (buffering, state storage, bandwidth, platform parity), severity 1-5, mitigation
Market metric
Datapoint
metric type (market size, conversion, ticket premium, completion drop-off), demographic, value, unit, sample size, reporting year
| Subtype | Based on | Key fields |
| --- | --- | --- |
| Production case | Case | release year, studio, delivery medium (FMV, real-time 3D, streaming player, theatrical), budget, reported revenue, units sold, total and average playthrough runtime, shooting ratio, decision points, endings |
| Narrative mechanism | Technique | paradigm (branch-and-bottleneck, state variable, storylet, database cinema, foldback), complexity class, authoring overhead, agency profile |
| Technical constraint | Problem | domain (buffering, state storage, bandwidth, platform parity), severity 1-5, mitigation |
| Market metric | Datapoint | metric type (market size, conversion, ticket premium, completion drop-off), demographic, value, unit, sample size, reporting year |
Other projects define their own packs. All subtype fields follow the evidence rules in 6.3.
### 6.3 Metadata
All nodes: id, project_id, type, title, summary (1-2 sentences for agents to scan), created, updated, status (draft, reviewed, stale, superseded), confidence (low, medium, high), tags, schema_version.
All nodes: id, project_id, type, title, summary (1-2 sentences for agents to scan), created, updated, review_state (draft, reviewed), lifecycle (active, superseded), confidence (low, medium, high), tags, schema_version. Freshness (current, stale, unknown) is derived at read time from the recorded dates and dependencies.
Facets: audience (dev, product, pm, sales), domain (project-extensible core set: tech, design, market, history, legal, production, marketing), use_for (presentation, budget, comparison, architecture decision, pitch).
Lens fit: lens_fit: {<project_id>: {score, horizon, key_question, reason}}.
Provenance: derived_from: [{source, quote, loc}], run_id of the agent run that proposed it, agent and model identity.
Provenance: derived_from: [{source, revision, quote, loc}], run_id of the agent run that proposed it, agent and model identity. This evidence list is canonical; displayed evidence quotes and provenance edges are derived from it rather than separately editable copies.
Source-specific: URL, author, publisher, publication date, access date, source type (paper, review, press, vendor, internal), reliability grade, archive path, license note.
Claims and datapoints: evidence_quote (short, with page or timestamp), evidence_type (measured, reported, opinion, vendor marketing), as_of, stale_after.
Claims and datapoints: evidence_type (measured, reported, opinion, vendor marketing), as_of, stale_after, and claim_support (pending, supported, unsupported) with a review rationale. Each assertion or factual field maps to one or more canonical evidence entries. Source reliability, quote validity, claim support and confidence are separate attributes; no one implies the others.
Datapoint values: value, unit, sample_size, reporting_year and demographic (where relevant) are separate fields from the quote, so numbers can be compared and charted.
Entities: aliases (alternate names) and merged_from (IDs merged into this node, so a merge can be undone).
### 6.3.1 Evidence and source revisions
- A source has a stable identity and immutable captured revisions, each with a content hash, capture time, original artifact and normalized extraction when available. A URL identifies a source candidate, not an immutable revision: changed content at the same URL creates a new revision. Fetch failure never replaces an existing capture.
- Evidence locators identify the exact revision and extraction version, with format-specific locations (PDF page and text span; web/text block and span; transcript timestamp and span). Quote checks use documented normalization and verify the stated location, not merely the presence of the quote somewhere in the document. OCR and parser limitations are recorded.
- Quote validation proves that text occurs at a location. Claim-support review separately assesses whether that text supports the assertion, number, unit, population, date and qualifiers. A passing quote check alone must never label a claim verified.
- Support assessments are structured records from external agents or an authorized human: claim ID, source/extraction revision, assessor/run, method, status and rationale. Missing references, unavailable assessment or a failed check never become a successful verification. The server checks required assessment records and policy without claiming to independently establish semantic truth. Optional relevance/index features may degrade; acceptance evidence requirements may not.
- Unavailable archives or failed extraction produce an explicit unverifiable state. Such sources and draft proposals may be retained, but their claims cannot enter the accepted evidence-backed corpus until checkable evidence and support review are available. This preserves the 100% merged-claim citation target.
- An AI-synthesized report is evidence of what that report says. Its underlying factual claims require checked primary evidence before being presented as primary-source-backed. A reference list alone does not establish that evidence.
- Interpretations are explicitly labeled and cite their supporting notes; they are never presented as source statements. Factual assertions embedded in interpretations or syntheses follow the same evidence rules as notes.
### 6.3.2 Lifecycle and freshness
Review state, freshness and lifecycle are separate dimensions in the schema; a reviewed node may also be stale. Source immutability applies to captured content; corrected bibliographic metadata is a versioned, reviewed change.
Datapoints require as_of and a stale_after deadline with a recorded policy or rationale. The service evaluates freshness at read time, even if the curator has not run. Syntheses record input node revisions and compilation time; changed, stale or superseded inputs trigger a visible warning until reviewed regeneration. These warnings survive every output format and budget reduction.
Displaying accepted syntheses and their dependency warnings belongs to the P0 read contract whenever such nodes exist. Automated discovery of refresh work and the dedicated compilation/brief workflow remain P1 (FR-C1/FR-A4). Deferring refresh tooling cannot hide known dependency warnings. Read-time freshness uses the current service time and canonical dependency revisions even when the search index lags.
### 6.3.3 Source intake and later reference
Each source page distinguishes the source identity, immutable revisions and attached artifacts. It displays title, authors/publisher when known, original URL if present, capture time, hash, archive availability, extraction status and notes that cite that source. References target a specific revision and location, not the latest bytes at a URL.
| Input through MCP | What KB retains | Later reference |
| --- | --- | --- |
| Local original file | Original bytes in private artifact storage, hash, file/MIME metadata and a source-revision record; extracted text with parser/version and location mapping where supported | Authenticated original download/preview and exact citation location; previews depend on supported format |
| Public URL with capture requested | Original URL, fetch/final URL, capture time and immutable captured content where fetching succeeds | Both live original link and captured revision; changed content produces a new revision |
| URL registered without a usable capture | URL and bibliographic metadata, with explicit reference-only or capture-failed state | A useful bookmark/source record, but not checkable evidence for accepted factual claims until evidence is archived |
| Locally obtained restricted/dynamic page, transcript or export | Agent-submitted capture plus original URL, capture method and provenance; original and derived artifacts distinguished | Cite the supplied artifact accurately; a transcript or export must not be labeled the original recording/page |
Source registration is separate from knowledge extraction. Staging an upload does not accept its metadata or claims; completing the artifact and source proposal returns a stable source ID, revision ID and acceptance/validation status. Multiple nodes and projects reuse that source without duplicating its bytes. Interrupted uploads cannot become citable revisions. Hash dedupe does not discard distinct provenance records.
Extraction preserves page/block/span mapping to the captured revision and records parser version, empty/scanned pages and unsupported content explicitly. Converting a PDF to one text string is not sufficient citation evidence. Keep native source versions (for example an arXiv revision) distinct from title and source identity. Metadata/abstract retrieval alone is not original-file capture. Agent-generated contents tables and reading guides remain separate from immutable originals.
Store source metadata, artifact manifests, hashes and evidence references in git; store large original binaries in private content-addressed artifact storage alongside the service, included in backup/restore. A manifest reference alone is not an archived original. Reading/downloading an existing artifact from the website is within the read-only boundary. Active source content is not executed inside the application; unavailable previews still offer the original download and available extracted text.
**MCP implementation boundary.** KB defines application tools for source registration and artifact transfer. MCP provides schema-defined tool calls and resource retrieval; merely connecting an MCP client or passing a local path does not upload a file. Recommended implementation: a small local MCP connector offers a file-path tool, reads the explicitly selected local file, and transfers its bytes to the authoritative KB using authenticated, bounded upload-session/chunk/finalize tools. The connector is ordinary transport code, not an agent. File bytes stay outside model-visible tool responses. Remote-only clients can register URLs or use supported artifact-transfer tooling; the VPS cannot dereference a path on the user's computer. This proposed connector/transfer design must be tested in all four harnesses; tool schemas, maximum sizes and resumption rules are M0 deliverables.
Protocol references: [MCP tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) and [MCP resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources). Upload tools described here are KB-specific, not protocol-standard file upload methods.
### 6.4 Typed edges
solves, causes, supports, contradicts, instance_of, part_of, precedes, supersedes, compared_with, derived_from, plus applies_to (node to project) for cross-project relevance. Edges live in frontmatter and are validated: the target must exist and the edge type must be allowed between the two node types.
Projects add extension edges in their registry, each with allowed source and target types. The interactive-video pack adds implements (case to mechanism), introduces (mechanism to constraint, a project-level form of causes), mitigates (technique to constraint), has_metric (case to datapoint) and incurs_cost (problem to datapoint). documented_in is the core derived_from edge. The core set stays small so other projects are not forced to carry these.
Add core addresses (technique to problem) for a relevant or partial approach without asserting that it solves the problem completely. A solves edge requires support for its stated applicability. Edges that make substantive claims carry evidence references or an explicitly labeled interpretive rationale, proposer/run identity and relevant conditions. Conditions belong to the technique-problem relationship when they vary by use case. Tags or similarity scores cannot establish a solves, supports or contradicts relation.
### 6.5 Grouping and navigating knowledge
Use several complementary forms of organization:
| Mechanism | Purpose | Example |
| --- | --- | --- |
| Problem node | A stable question/problem page gathering incoming addresses/solves links, cases and evidence | How can we control branch explosion? |
| Technique/Solution node | A reusable method linked to each applicable problem, with conditions and limitations | State-based branching linked to several problems, without copying the technique |
| Concept/topic node | A browseable subject with explicit part_of membership, under documented allowed edge types | Numerical optimization groups methods and problems |
| Tags and facets | Broad many-to-many filtering by subject, audience, use or domain | numerical-methods, real-time, dev |
| Synthesis node | An agent-authored, cited reading guide or comparison over selected nodes | Overview of approaches to one problem |
| Similarity suggestions | Discovery candidates computed from the index, with the reason shown | Similar text, overlapping tags or a shared neighbor |
Problem pages are computed from accepted nodes/edges; they do not require a prewritten synthesis or an internal agent. Show approaches with applicability, assumptions, limitations, supporting references and case studies. Mathematical/technical methods may record input requirements, guarantees versus heuristics, accuracy, computational cost and known failure conditions when supported. Unknown values remain unknown. Multiple solutions remain distinct; shared tags or a common problem do not establish equivalence or a universal ranking.
Every node page separates **linked knowledge** (accepted typed relationships, including incoming links) from **suggested related nodes** (derived similarity candidates). Each related item states why it appears. The server computes inverse navigation from stored edges rather than requiring duplicate reverse-edge writes. Similarity never silently becomes an accepted graph edge; a local agent can propose such a connection through MCP with its rationale/evidence. All lists honor the resolved project scope and disclose omitted cross-project targets. When no accepted approaches exist, show that gap; suggestions must not be labeled proven solutions.
Example navigation: a problem page lists Technique A and Technique B through their addresses/solves edges; each technique links to its case studies and cited source revisions. A separate related section may suggest another problem with overlapping concepts. Clicking a tag filters the collection; clicking a typed relation explains the specific connection. These read-only pages are P0; an interactive graph canvas and rich comparison matrix remain P1.
## Functional requirements
Priority: P0 required for v1, P1 important, P2 later.
### 7.1 Project management
ID
Requirement
Pri
FR-P1
Create, archive and list projects from a registry entry, and the validator rejects nodes with unregistered project_id.
P0
FR-P2
Every read and write API takes a project scope, with the documented default scope.
P0
FR-P3
Shared library with global dedupe of sources and entities.
P0
FR-P4
Promote a note to shared, and mark links as cross-project in API and UI.
P1
FR-P5
Per-project lens (north-star, key questions, watch list) read by ingest and curation.
P0
FR-P6
Per-project export and import.
P1
FR-P7
Per-project access control.
P2
| ID | Requirement | Pri |
| --- | --- | --- |
| FR-P1 | Create, archive and list projects from a registry entry, and the validator rejects nodes with unregistered project_id. | P0 |
| FR-P2 | Every read and write API takes a project scope, with the documented default scope. | P0 |
| FR-P3 | Shared library with global dedupe of sources and entities. | P0 |
| FR-P4 | Promote a note to shared, and mark links as cross-project in API and UI. | P1 |
| FR-P5 | Per-project lens (north-star, key questions, watch list) read by ingest and curation. | P0 |
| FR-P6 | Per-project export and import. | P1 |
| FR-P7 | Per-project access control. | P2 |
| FR-P8 | Authenticate team members with admin/editor/viewer roles and explicit project-owner grants; issue each local agent its own API key and stable agent_id. Enforce capabilities, rotation/revocation and human-owned intent; record the actual caller and credential identifier on proposals and decisions without recording secrets. All authenticated team members may read all projects initially; project-restricted access remains P2. | P0 |
### 7.2 Ingestion
ID
Requirement
Pri
FR-I1
Capture from URL, PDF, file, text paste and NotebookLM export through an inbox/ folder, CLI and API.
P0
FR-I2
Archive source snapshot, hash, normalize metadata, dedupe by hash and URL across the whole base.
P0
FR-I3
Triage against the project lens: relevant or skip, with score and reason.
P0
FR-I4
Digest extracts schema-valid notes with quote and location for every claim.
P0
FR-I5
Analyze writes learnings and points of interest per horizon, labeled as the agent's interpretation and kept separate from source claims.
P1
FR-I6
Link resolves entities to a canonical name plus aliases (name normalization and embedding similarity find candidates, the agent judges borderline matches), logs every merge so it can be undone, proposes typed edges and flags contradictions.
P0
FR-I7
Verify re-checks quotes, numbers and dates against the archived source and assigns evidence grade.
P0
FR-I8
All writes go to staging/ as proposals, with a run log.
P0
FR-I9
Tag each source with the projects it was ingested for, so one source can serve several projects.
P0
FR-I10
Task brief: agent derives H1 and H2 for each run and stores them in the run record.
P1
| ID | Requirement | Pri |
| --- | --- | --- |
| FR-I1 | Local agents capture URL, PDF, file, pasted text and NotebookLM exports and submit source artifacts and proposals through typed MCP tools. A local inbox may be an agent input but never an alternate server write path. MCP transfers required artifact bytes and hashes to service-managed storage and returns source/revision IDs; local absolute paths alone cannot identify files on the VPS. | P0 |
| FR-I2 | Archive immutable source revisions, hash and normalize metadata, dedupe identical captures globally, and use URL matches to find prior source identities without discarding changed revisions. | P0 |
| FR-I3 | Triage against the project lens: relevant or skip, with score and reason. | P0 |
| FR-I4 | Digest extracts schema-valid notes with quote and location for every claim. | P0 |
| FR-I5 | Analyze writes learnings and points of interest per horizon, labeled as the agent's interpretation and kept separate from source claims. | P1 |
| FR-I6 | Link resolves entities to a canonical name plus aliases (name normalization and embedding similarity find candidates, the agent judges borderline matches), logs every merge so it can be undone, proposes typed edges and flags contradictions. | P0 |
| FR-I7 | Verify checks quotes at their locations against the exact source revision and records claim-support assessment separately from source reliability and confidence. Unverifiable or unsupported claims remain outside the accepted evidence-backed corpus. | P0 |
| FR-I8 | All writes go to staging/ as proposals, with a run log. | P0 |
| FR-I9 | Tag each source with the projects it was ingested for, so one source can serve several projects. | P0 |
| FR-I10 | Task brief: agent derives H1 and H2 for each run and stores them in the run record. | P1 |
| FR-I11 | Durable manifests for external-agent runs: run/project/source revision, stage, skill/schema versions, input/output hashes, proposal IDs and last receipt. Bounded batches record coverage, skips and deferred work. An interrupted local agent can inspect and resume verified stages through MCP without recreating accepted nodes. KB records progress; it does not execute a reasoning agent. | P0 |
### 7.3 Validation and review
ID
Requirement
Pri
FR-V1
kb validate checks schema, required fields, link resolution, edge-type rules, project scope and that every quote appears in the archived source. A proposal that fails cannot be committed.
P0
FR-V2
Review inbox with accept, edit, reject and merge-duplicate actions. Decisions are logged and reused as examples for the skills.
P0
FR-V3
Autonomy policy per node type and per project, with graduated promotion from suggest to auto-merge once acceptance rate is demonstrated.
P1
FR-V4
Contradictions are linked, never overwritten. Superseded nodes stay with superseded_by.
P0
| ID | Requirement | Pri |
| --- | --- | --- |
| FR-V1 | kb validate checks schema, required fields, link resolution, edge-type rules, project scope and each quote at its stated location in the archived revision. Acceptance also requires the applicable support-review decision and authorized reviewer/policy. Failed proposals may persist in staging but cannot enter the accepted corpus. | P0 |
| FR-V2 | MCP proposal/status operations let local agents inspect validation findings, submit corrected revisions, provide support assessments and propose duplicate merges. Eligible proposals auto-accept through service policy; exceptions are handled in the local agent conversation. Record decisions and policy identity. No web review inbox or mutation controls. | P0 |
| FR-V3 | P0 policy-controlled automatic acceptance per project and change type. Valid eligible proposals proceed without human approval; failed checks return actionable findings for agent correction, while ambiguous or protected changes await the applicable decision. Policies cannot waive schema, scope or evidence requirements. Quality audits and graduated tuning can follow as P1. | P0 |
| FR-V4 | Contradictions are linked, never overwritten. Superseded nodes stay with superseded_by. | P0 |
| FR-V5 | Proposal lifecycle is staged, validating, accepted or rejected; needs-review is an exception state rather than a mandatory step. Validation-failed and conflict outcomes allow correction. Each proposal carries an ID, base revision, author, change bundle, evidence results and decision history. Acceptance revalidates against current state, serializes repository writes, and returns a durable receipt with commit and index status. Retrying a proposal ID cannot create a second acceptance. Any proposed-content or support-assessment edits invalidate prior validation. | P0 |
### 7.4 Retrieval and agent interface
ID
Requirement
Pri
FR-A1
MCP server and HTTP API expose: search, get_node, neighbors, timeline, compare, brief, list_projects, propose_note, flag_stale. All take project scope.
P0
FR-A2
Hybrid retrieval: keyword plus embeddings, then graph expansion by typed edges.
P0
FR-A3
Responses are structured JSON with citations, confidence, as_of and project of origin, bounded by a token budget parameter.
P0
FR-A4
brief(topic, audience, purpose, budget) returns a compiled, cited summary for one audience.
P1
FR-A5
Agents cannot write to notes/ or synthesis/ directly. They can only submit proposals.
P0
FR-A6
Single canonical AGENTS.md, with thin CLAUDE.md and GEMINI.md pointers, a shared skills folder, and an install script that links skills and MCP config into OpenCode, Claude, Codex and Antigravity.
P0
FR-A7
Optional hook integration so a coding harness can inject relevant KB nodes at turn start, with high-confidence full items and low-confidence hints.
P2
FR-A8
MCP resources (schema, project registry, node by ID) and prompts (per-project roles, for example an architecture advisor) alongside the tools.
P1
FR-A9
Typed tools only. No raw query language (Cypher, SQL) is exposed to agents, and every write goes through a proposal.
P0
| ID | Requirement | Pri |
| --- | --- | --- |
| FR-A1 | MCP exposes P0 tools search, get_node, neighbors, list_projects, source-artifact submission, proposal submission/status/revision and flag_stale. The website HTTP API exposes read operations only; it has no knowledge mutation endpoints. MCP may use HTTP as its transport without creating a separate REST write interface. Content tools take explicit project/scope context; list_projects is a team-level discovery operation. timeline, compare and brief are P1 to match their compiled-content and UI dependencies. flag_stale submits a proposal rather than directly editing an accepted node. | P0 |
| FR-A2 | Hybrid retrieval: keyword plus embeddings, then graph expansion by typed edges. | P0 |
| FR-A3 | Responses are structured JSON with citations, confidence, as_of, freshness warnings, project of origin, resolved scope and index revision, bounded by a token budget parameter. The published API contract names a tokenizer/counting method and counts the complete serialized payload. Truncation preserves complete evidence/citation groups, reports omissions, and never drops required warnings; too-small budgets return a defined budget-too-small error rather than an uncited fragment. Transport framing and error-envelope minimums are documented separately. | P0 |
| FR-A4 | Optional brief(topic, project/scope, audience, purpose, budget) returns an accepted saved synthesis or a deterministic cited evidence bundle for a local agent to summarize. New generated prose is explicitly labeled and enters the KB only through an MCP synthesis proposal; no website or VPS-hosted generation is required. Final saved-brief versus evidence-bundle semantics remain a P1 decision. | P1 |
| FR-A5 | Agents can only submit proposals. Enforced deployments keep canonical files and service credentials outside agent-writable mounts; a readonly snapshot may be provided for inspection. A harness with unrestricted owner filesystem access cannot be claimed to satisfy this boundary. Direct file edits and generic HTTP/CLI writes are unsupported knowledge-contribution paths. Imports also submit MCP proposals. Operator backup/restore and schema migration remain maintenance operations using the shared validation rules; they cannot be used as a routine authoring bypass. | P0 |
| FR-A6 | Single canonical AGENTS.md, with thin CLAUDE.md and GEMINI.md pointers, a shared skills folder, and an install script that configures shared skills and MCP access in OpenCode, Claude, Codex and Antigravity. Symlinks are optional; a supported configuration/copy fallback preserves portability. | P0 |
| FR-A7 | Optional hook integration so a coding harness can inject relevant KB nodes at turn start, with high-confidence full items and low-confidence hints. | P2 |
| FR-A8 | MCP resources (schema, project registry, node by ID) and prompts (per-project roles, for example an architecture advisor) alongside the tools. | P1 |
| FR-A9 | Typed tools only. No raw query language (Cypher, SQL) is exposed to agents, and every write goes through a proposal. | P0 |
| FR-A10 | Expose service/connector diagnostics and compatible tool/schema/skill versions, authenticated capability, selected scope, source-transfer limits, and index status without secrets. Distinguish configured, connected and workflow-verified clients. Installers preserve unrelated client configuration and support a non-symlink fallback. | P0 |
### 7.5 Compilation and curation
ID
Requirement
Pri
FR-C1
Regenerate affected syntheses when notes change and show a diff for review.
P1
FR-C2
Curator agent reports stale nodes, duplicates, orphans, contradictions and cross-project promotion candidates.
P1
FR-C3
Staleness: nodes past stale_after are flagged in the UI and returned with a warning by the API.
P0
FR-C4
Optional topic-cluster summaries: detect clusters in the graph and write a summary per cluster for broad questions. Enabled only when a project outgrows its syntheses.
P2
| ID | Requirement | Pri |
| --- | --- | --- |
| FR-C1 | Mark affected syntheses when inputs change; local agents discover pending refresh work through MCP and submit regenerated syntheses as proposals. Service acceptance follows policy. Until an agent refreshes them, the website displays their dependency warnings. | P1 |
| FR-C2 | Curator agent reports stale nodes, duplicates, orphans, contradictions and cross-project promotion candidates. | P1 |
| FR-C3 | Staleness: nodes past stale_after are flagged in the UI and returned with a warning by the API. | P0 |
| FR-C4 | Optional topic-cluster summaries: detect clusters in the graph and write a summary per cluster for broad questions. Enabled only when a project outgrows its syntheses. | P2 |
### 7.6 Web UI
ID
Requirement
Pri
FR-U1
Project switcher, with an "all projects" view and clear marking of shared and cross-project items.
P0
FR-U2
Global search with filters for type, audience, domain, date, confidence and project.
P0
FR-U3
Node pages with summary, evidence, source links, typed neighbors and history.
P0
FR-U4
Problem to solutions to cases matrix, market datapoint table with as-of badges, timeline view, comparison view.
P1
FR-U5
Graph explorer.
P1
FR-U6
Review inbox and staleness list.
P0
FR-U7
Audience lenses: saved filters plus brief templates for developers, product, project managers and sales.
P1
FR-U8
Export a synthesis or timeline to slides or markdown.
P2
| ID | Requirement | Pri |
| --- | --- | --- |
| FR-U1 | Project switcher, with an "all projects" view and clear marking of shared and cross-project items. | P0 |
| FR-U2 | Global search with filters for type, audience, domain, date, confidence and project. | P0 |
| FR-U3 | Node/source pages with summary, evidence, original URL, archived revision/download and supported location preview, incoming/outgoing typed neighbors and history. Source pages list citing notes; archive/extraction availability is explicit. | P0 |
| FR-U4 | Problem to solutions to cases matrix, market datapoint table with as-of badges, timeline view, comparison view. | P1 |
| FR-U5 | Graph explorer. | P1 |
| FR-U6 | Read-only staleness list and visible evidence/freshness status. Proposal corrections, decisions and mutations remain in the MCP agent workflow. | P0 |
| FR-U7 | Audience lenses: filter presets and reading views for developers, product, project managers and sales. Agent brief templates live in shared skills; the website does not generate or author knowledge. | P1 |
| FR-U8 | Export a synthesis or timeline to slides or markdown. | P2 |
| FR-U9 | Read-only problem/topic browsing: show applicable approaches, assumptions/limitations, cases and source references; distinguish accepted typed links from labeled related-node suggestions. Tags/facets filter across groups. No internal agent or prewritten synthesis is required to render connections. | P0 |
## Architecture summary
1. Source of truth: markdown and YAML files in git.
2. Derived index: SQLite (full text and vectors) or Postgres plus pgvector, with an edges table. It is disposable and can always be rebuilt from the files.
3. KB service: one core with MCP, HTTP and CLI transports derived from a single registry of tools. It is the only code path that reads the index and commits to the repo.
2. Derived index: SQLite with full text, vectors and an edges table for v1. It is disposable and rebuildable from canonical files and required source artifacts. Hosted clients use the service rather than opening the database file directly.
3. KB service: one scoped core with a typed MCP contribution/retrieval interface and a read-only HTTP API for the website. CLI utilities support diagnostics, validation, rebuild and maintenance, not knowledge authoring. Only the MCP proposal path can initiate new knowledge changes; the service validates, applies acceptance policy and commits them.
4. Skills: judgment procedures (capture, triage, digest, analyze, link, verify, compile, report), kept as one canonical set with a shared concerns to protocol mapping.
5. UI: a client of the same API with no privileged access.
5. UI: a read-only client for search, navigation and knowledge display. Its credentials and API surface cannot submit, edit or accept knowledge.
6. Principle: deterministic strictness lives in code (validator, indexer), not in prompts, so different agents and models are held to the same floor.
Reuse from existing work: the one-core-with-thin-adapters and registry pattern, confidence tiers, observe-then-enforce promotion and acceptance receipts from Jev, and the skill template, state-machine pipelines and symlink-based cross-agent setup from Winnow.
Storage decision (v1). Files in git plus SQLite (full text, vectors and an edges table). A graph database such as Neo4j was evaluated and is not used in v1: it adds a server to run and back up, and it moves the source of truth out of git, which loses diffs, undo and direct file access for agents. A graph engine can be added later as a second derived index. Revisit when the base passes the 100,000-node target, when multi-hop path queries become too slow in SQLite, or when live multi-user editing is required. Also left out of v1: cloud document parsers (local-first), separate entity-tagging models and heavy entity-matching pipelines. Agents get typed tools only, never a raw query language.
Reuse from existing work: Jev's contracts, tool registry, owned configuration merging, replay patterns and diagnostics; Winnow's concern-specific protocols, atomic extraction, claim audits and relational synthesis procedures. The [reference review](LOCAL_AGENT_IMPLEMENTATION_REVIEW.md) records limits: Jev's advisory verification/direct writes/character truncation and Winnow's direct vault writes/flattened extraction/prompt-only stages do not satisfy KB's gates. Reimplement those boundaries against KB contracts; no wholesale runtime import is assumed.
Storage decision (v1). Files in git plus SQLite (full text, vectors and an edges table). A graph server is deferred to limit operational complexity; using one as a derived index would not inherently move the source of truth out of git. Revisit after measured graph-query or scale limits. Cloud document parsers, separate entity-tagging models and heavy entity-matching pipelines are also deferred. Agents get typed tools only, never a raw query language.
Accepted mutations produce a git commit and a durable acceptance record before index publication. A crash between commit and indexing is recoverable by replay/rebuild; responses disclose index lag and never report an uncommitted change as accepted. Proposal decisions, redirects, run manifests, project intent and audit records must survive a full index deletion. Private source artifacts need a documented storage, access, retention and backup policy; git history alone is not a backup of files stored outside git. Backup/restore and crash-recovery acceptance tests are required for the shared-team release.
Acceptance and search visibility are separate outcomes. Receipts report accepted node revisions and index publication status. M0 must specify how a client reads the accepted revision before index publication (canonical read or a bounded wait with an explicit pending result); it must not report a committed node as nonexistent merely because indexing is delayed. Search reports its indexed revision. Crash recovery must reconcile an existing commit with its receipt before accepting a replay, including a crash between those durable writes.
One versioned operation catalog declares schemas, handlers, required capabilities and permitted transports. Generate MCP and read-only HTTP exposure from explicit allowlists; descriptive tool annotations alone do not enforce permissions. Idempotency binds proposal identity to payload digest, base revision, schema and policy versions; changed input cannot reuse an old success. Acceptance serialization needs worker fencing and recovery across git/receipt/index boundaries. Durable receipts are distinct from best-effort diagnostic telemetry. Commits contain only the accepted change set; external skills never stage unrelated user files.
### External-agent skill and run contract
Provide a canonical, harness-neutral pack with four initial entry points: ingest, query, curate and synthesize. Skills declare concerns and load only relevant protocols (evidence, scope, relationships, proposals and synthesis). They reference service-published schemas and tool versions instead of copying validator rules. Harness setup translates discovery/connection details; it does not duplicate business logic or require lifecycle hooks. Claude requires its own verified client path rather than inheriting a claim of support from another harness.
The local agent reads authoritative project intent and scope through MCP. H1/H2 are explicit task/run context; client cwd and inferred README descriptions are not authority for project selection or H3. External ingestion stages persist source capture, extraction references, triage, bounded note proposals, support assessments and proposed links, then receive validation/acceptance receipts. Resume uses those records instead of conversation history. If lease-based stage ownership is used, an expired worker cannot publish a stale result without revalidation and the current fence.
Atomization optimizes for relevant, reusable knowledge rather than maximum note count. Record source coverage and reasons for skipped/deferred portions; do not silently claim exhaustive processing after a budget limit. Curation keeps incompatible perspectives and conditions separate, uses explicit merge/redirect proposals for duplicates and derives backlinks from stored forward edges. Strong similarity or common sources alone do not establish equivalence.
The capability acceptance matrix records each affected OS/harness pair as PASS, FAIL, BLOCKED, NOT RUN or UNSUPPORTED, with application/connector/service versions and evidence origin. Listing tools or parsing configuration is not the v1 gate: each supported client must perform source transfer, invalid-proposal rejection, eligible automatic acceptance, retry/resume and cited retrieval on the tested deployment. Record local and VPS evidence separately.
### Deployment and execution boundary
During development, the service, repository, private archives, index and web app run locally. For team operation they run on the owner’s VPS; ingestion, reasoning and synthesis agents continue to run in local Codex, Claude, Antigravity and OpenCode sessions. The VPS serves retrieval, validates submitted artifacts/proposals, applies policy, commits accepted records and maintains the derived index. Initially KB hosts no reasoning agent or autonomous curator. Semantic support assessments and proposed connections come from external agents; the server checks required records, deterministic evidence rules and policy, without claiming to independently prove semantic truth. Reading and relationship navigation work when no local agent is running; new semantic analysis and synthesis refresh wait for an external agent run.
Migration to the VPS transfers canonical records, private source artifacts, proposal/run/audit records and configuration, then rebuilds or verifies the index. The local service stops accepting writes before the VPS becomes authoritative; v1 does not promise synchronization between independently writable local and VPS copies. Agent MCP endpoint/credential settings change without changing the contribution contract. Local operation remains supported, but remote VPS access requires connectivity.
### Automatic acceptance and exceptions
Automatic acceptance is a v1 requirement. The proposed initial eligibility policy is additive source captures and evidence-backed notes/datapoints whose schema, scope, links, locations and recorded support assessments pass. This concrete starting policy is a recommendation to finalize in M0, not a user-approved list of automatic change types. Confidence alone is never sufficient. Support assessment may be performed by local agents and records its actor, source revision and rationale; it is not mislabeled as human review or deterministic proof of truth.
For routine factual notes, the proposing local agent may also assess support, as confirmed by the owner. Record the assessment and sample accepted notes for quality; no independent assessor is mandatory for every routine note. A second pass by the same model is not recorded as independent human review. Bind assessments to the exact proposed assertion/field and evidence revisions; changed assertions invalidate prior support decisions. M0 defines any higher-risk exceptions, who reviews quality samples, the sampling cadence/size, correction procedure and response when errors exceed the agreed limit. Numeric semantic-error limits are agreed before the pilot evaluation, not inferred from proposal acceptance rate. Sampling is part of pilot acceptance; it does not require an internal agent or a web review interface.
Invalid proposals return errors for agent repair. Ambiguity, destructive merges/deletions, promotions and changes outside the configured policy remain staged for an exception decision in the local agent workflow. Contradictory evidence can be added with explicit links; it must not overwrite the earlier assertion. Human-owned goals and autonomy policy retain owner authorization. Every automatic or exceptional decision records the policy version and actor and has a traceable correction/supersession path. No mandatory per-note approval or browser review workflow is introduced.
## Non-functional requirements
Area
Requirement
Performance
Search under 300 ms for a project of 10,000 nodes on a laptop. brief under 5 s excluding model time.
Scale targets
10,000 nodes per project and 100,000 total, with full index rebuild under 10 minutes.
Local-first
Everything runs offline with local models as an option. Cloud models are configurable.
Portability
Plain files, no lock-in. Works on Windows, macOS and Linux. No required symlinks.
Reliability
Index is rebuildable. Every write is a git commit. Ingest runs are resumable from file artifacts.
Auditability
Every node records run, agent and model. Every proposal decision is logged.
Security
Source text is treated as data, never as instructions. Ingest agents have no write access beyond proposals. Secrets are kept out of the repo.
Legal
Store notes, short quotes and links. Archived copies stay private. License field on every source.
Versioning
schema_version on every node and run record, with migration scripts.
Agent-agnostic
No required use of tool-specific hooks, plugins or subagents in the core pipeline.
| Area | Requirement |
| --- | --- |
| Performance | Search under 300 ms for a project of 10,000 nodes on a laptop. brief under 5 s excluding model time. |
| Scale targets | 10,000 nodes per project and 100,000 total, with full index rebuild under 10 minutes. |
| Local-first | Reading, validation of existing captures, local-file ingestion and indexing run without internet; model-assisted steps support configured local models. Fetching new external URLs requires connectivity and reports offline/unavailable explicitly. Cloud models are optional and configurable. |
| Portability | Plain files, no lock-in. Works on Windows, macOS and Linux. No required symlinks. |
| Reliability | Index is rebuildable. Every accepted canonical mutation is recorded in git; staged artifacts and run progress persist durably without requiring a commit for every intermediate file write. Ingest runs are resumable from file artifacts. |
| Auditability | Every node records its origin: human author or agent run/model as applicable. Every proposal decision records the authenticated actor, validation version, policy version and resulting revision. |
| Security | Source text is treated as data, never as instructions. Ingest agents have no write access beyond proposals. Secrets are kept out of the repo. Shared service access is authenticated and transport-protected, with revocable credentials. Fetching and parsing untrusted inputs enforce URL/network restrictions, redirect checks, file/path containment, size/time limits and parser isolation; private network fetching requires an explicit operator policy. Exact deployment controls are defined before team hosting. |
| Legal | Store notes, short quotes and links. Archived copies stay private. License field on every source. |
| Versioning | schema_version on every node and run record, with migration scripts. |
| Modularity | All service, agent, connector, skill/pipeline and frontend development uses explicit module ownership, public contracts and private implementations. Replaceable components have version/capability declarations, contract tests, dependency-boundary checks and state migration/rollback procedures. A compatible replacement does not require unrelated consumer changes. See the [modularity protocol](development/MODULARITY_PROTOCOL.md). |
| Agent-agnostic | No required use of tool-specific hooks, plugins or subagents in the core pipeline. |
## Success metrics
Metric
Target
Citation validity (quotes found at stated location)
100% of merged notes
Proposal acceptance rate after tuning
At least 70% for notes, tracked per skill and per agent
Retrieval quality on a per-project question set of 20-30 questions
Correct source in the top 5 for at least 80% of questions
Cross-agent convergence
Same 5 documents through two different agents give validator-clean, mostly overlapping notes
Freshness
No datapoint older than its stale_after served without a warning
Reuse
At least one project reuses shared nodes from another project in its first month
Time to answer
A person finds a cited answer to a typical question in under 2 minutes
| Metric | Target |
| --- | --- |
| Citation validity (quotes found at stated location in the cited revision) | 100% of accepted factual claims and datapoints; retained unverifiable drafts do not count as accepted knowledge |
| Claim support | Every accepted factual claim has a recorded support decision; the benchmark separately measures semantic support errors rather than inferring correctness from quote matches |
| Proposal acceptance rate after tuning | At least 70% for notes, tracked per skill and per agent |
| Retrieval quality on a per-project question set of 20-30 questions | Correct source in the top 5 for at least 80% of questions |
| Cross-agent convergence | Same 5 documents through two agents produce validator-clean proposals; compare coverage of human-labeled findings and unsupported-claim rates, not wording. Numeric coverage and error thresholds are fixed before M2 acceptance. |
| Freshness | No datapoint older than its stale_after served without a warning |
| Reuse | At least one project reuses shared nodes from another project in its first month |
| Time to answer | A person finds a cited answer to a typical question in under 2 minutes |
## Milestones
Milestone
Scope
Exit criteria
M0 Foundations
Node schema, edge vocabulary, project registry, validator, 20 hand-guided sources across two projects, starting with the deep-research report as the first ingest test (graded as a secondary, AI-synthesized source)
Validator catches seeded errors. Notes validate. Verify flags unsupported claims in the report.
M1 Service
Index, hybrid search, MCP and HTTP with project scoping, proposals to staging/
Agents can search and propose from all four tools.
M2 Ingest
capture, triage, digest, verify, link, run logs, task brief
Cross-agent convergence test passes.
M3 UI
Project switcher, search, node pages, review inbox, staleness
A person reviews and navigates without touching files.
M4 Synthesis
analyze, compile, brief, matrix, timeline, curator report
Briefs produced for each audience.
M5 Multi-project hardening
Promotion to shared, cross-project edges, export and import, acceptance receipts per agent
Three projects live on one base without cross-contamination.
Milestones describe delivery order. The owner confirmed a smaller pilot before full v1; all current P0 requirements remain the full v1 commitment. M4 and the P1 portions of M5 are optional for v1 unless explicitly selected. P0 multi-project scope, shared-policy enforcement, source retention, recovery and client compatibility cannot wait for those later milestones.
Pilot projects: Dome interactive content and an interactive video platform/service; initial team size: up to five people. Recommended pilot slice, pending exact client/format selection: one agent client and local connector, one location-preserving source format, two project scopes plus shared, source upload, same-agent recorded support, policy acceptance, cited retrieval and minimal read-only search/problem/source pages. Include viewer/editor/admin permissions, per-agent keys, invalid-evidence rejection, one retry/restart scenario and quality sampling. Demonstrate a shared source reused across both projects. Introduce this slice across M0–M3 before expanding client and format coverage. Keyword retrieval may be used during the pilot if explicitly selected; full v1 retains hybrid search. A pilot pass cannot be labeled full v1 acceptance.
Before implementing an affected boundary, M0 records a versioned decision for: (1) field/edge schemas and supported evidence locators, (2) project/shared policy ownership and support-assessor rules, (3) owner authorization and first-owner bootstrap, (4) proposal revisions, conflicts, bundle atomicity, replay and recovery, (5) accepted-revision reads during index lag, and (6) artifact limits and supported format/OS/client matrix. A lifecycle table must distinguish persisted states from retryable outcomes, and define correction, withdrawal and post-acceptance supersession. Open product decisions remain labeled pending; illustrative appendices are not executable contracts.
The full v1 release gate covers every P0 requirement plus backup/restore of canonical records and original artifacts, offline local operation, citation-safe token budgets, the declared OS/client matrix, and local-to-VPS authority handover. Each gate records its requirement, fixture, expected outcome, measured result and evidence link. NOT RUN or BLOCKED is not a pass. Fix benchmark hardware, workload, percentile, embedding-cache assumptions, semantic-error limits and recovery objectives before measuring against the success metrics; the current numeric targets are unverified targets.
| Milestone | Scope | Exit criteria |
| --- | --- | --- |
| M0 Foundations | Node schema, evidence/edge contracts, project registry, validator, proposal/review API and team capability contracts; 20 hand-guided sources across two projects, with the deep-research report as an ingest fixture once supplied (graded as a secondary, AI-synthesized source) | Validator catches seeded errors. Notes validate. Support-review fixtures distinguish quote presence from supported claims. Required pilot sources and expected answers are supplied and labeled. |
| M1 Service | Index, hybrid search, scoped MCP and read-only HTTP, authentication, durable proposals and automatic acceptance policy | Agents can search, transfer source artifacts and propose from all four harnesses. An eligible proposal is accepted without human action; web writes, unauthorized mutations, scope escape and duplicate acceptance fail. Index-lag recovery is demonstrated. |
| M2 Ingest | capture, triage, digest, verify, link, run logs, task brief | Cross-agent convergence test passes. |
| M3 UI | Read-only project switcher, search, node/source and problem/topic pages, evidence/history, related-node suggestions and staleness | With no agent running, a member opens a problem, explores multiple approaches and their conditions, and follows a citation to an archived source. Suggested matches remain distinguishable from accepted links. Web credentials cannot capture, edit or accept knowledge. |
| M4 Synthesis | analyze, compile, brief, matrix, timeline, curator report | Briefs produced for each audience. |
| M5 Multi-project hardening | Promotion to shared, cross-project edge hardening, export and import; acceptance receipts extended to portability workflows | Three projects live on one base without unintended scope mixing. P0 scope enforcement and acceptance receipts already pass at M1. |
## Risks and mitigations
Risk
Mitigation
Different agents extract inconsistent notes
Shared schema, validator gate, golden test documents, short example-driven skills
Hallucinated or misquoted claims
Quote-location validation, separate verify step, second agent for verification where possible
Low-value auto-captured notes
Lens-based triage, relevance thresholds, review-first autonomy
Projects pollute each other
Required project_id, scoped queries, per-project lens fit, explicit cross-project edges, promotion only through review
Duplicate sources and entities across projects
Global dedupe on hash, URL and entity resolution in the shared layer
Prompt injection from ingested sources
Treat source text as data, restrict ingest agent permissions, no direct writes
Market data goes stale
as_of and stale_after required for datapoints, curator reports, API warnings
Vendor or tool lock-in
Files plus MCP, no dependence on any one agent's hooks or plugins
Index drift
Index is derived and rebuilt from files, with a doctor command to check it
Over-building the stack (graph server, extra pipeline stages)
Start with files, SQLite and typed tools. Add a graph engine, clustering or heavier entity matching only when a revisit trigger in section 8 is hit.
| Risk | Mitigation |
| --- | --- |
| Different agents extract inconsistent notes | Shared schema, validator gate, golden test documents, short example-driven skills |
| Hallucinated or misquoted claims | Quote-location validation, separate verify step, second agent for verification where possible |
| Low-value auto-captured notes | Lens-based triage, evidence/support checks, constrained automatic acceptance and quality sampling |
| Projects pollute each other | Required project_id, scoped queries, per-project lens fit, explicit cross-project edges, promotion only through review |
| Duplicate sources and entities across projects | Dedupe identical captures by hash, use URLs to resolve source identities without dropping changed revisions, and review entity resolution in the shared layer |
| Prompt injection from ingested sources | Treat source text as data, restrict ingest agent permissions, no direct writes |
| Market data goes stale | as_of and stale_after required for datapoints, curator reports, API warnings |
| Vendor or tool lock-in | Files plus MCP, no dependence on any one agent's hooks or plugins |
| Index drift | Index is derived and rebuilt from files, with a doctor command to check it |
| Over-building the stack (graph server, extra pipeline stages) | Start with files, SQLite and typed tools. Revisit a graph engine, clustering or heavier entity matching against measured limits described in the architecture summary. |
## Open questions
Confirmed target: shared team plus local agents, all-team read access, local development then the owner’s VPS, read-only website, MCP-only knowledge contributions and policy-controlled automatic acceptance. Fine-grained project confidentiality remains P2. The following decisions are unresolved; recommendations in the review report are not approvals.
1. Should KB live in its own repo or inside one of the existing agent repos?
2. Embedding model: local or API, and how to handle re-embedding when the model changes?
3. UI stack and hosting: local web app only, or also hosted for a team?
4. Do projects ever need hard isolation (separate access rules), or is logical separation enough?
5. Should shared notes require two-step review (project owner plus a shared curator)?
3. What VPS capacity, backup responsibility and simultaneous user/agent/ingestion workload must v1 support? Local development followed by the owner’s VPS is confirmed.
4. Who owns each project and shared-library policy, and how is owner authorization for protected changes recorded through the local-agent/MCP workflow?
5. Which shared-library changes are eligible for automatic acceptance, and which require exception review?
6. How should NotebookLM exports be captured: manual export, or an automated step?
7. Which node subtypes does each of the three starting projects need beyond the core set?
7. Which representative sources/questions and subtypes are needed for the confirmed Dome interactive content and interactive video platform/service pilot? Suggested IDs are dome-performance and interactive-video; exact IDs remain to be finalized.
8. Finalize the automatic-acceptance eligibility proposed above, support-assessment requirements and exception handling. Human approval of every proposal is explicitly not required.
9. Which P1 features are release requirements? In particular, is a compiled brief required for the first useful team workflow, or can cited search/node retrieval satisfy it?
10. What are the private archive size/retention, backup/restore targets, benchmark hardware, concurrent workload and query-budget distribution?
11. Which source formats, initial client/OS pair and retrieval mode should the confirmed smaller pilot demonstrate? Full v1 retains the existing P0 commitments.
12. Who operates quality sampling, at what sample size/cadence and semantic-error threshold? Same-agent extraction and support assessment for routine factual notes are confirmed.
## Appendix A. Example project registry entry
Illustrative only: the automatic eligibility and support checks must be specified alongside these modes before implementation; the exact initial policy remains open question 8.
```yaml
---
project_id: interactive-video
title: Interactive video knowledge
status: active
description: Research supporting interactive video projects
owners: [example-owner]
north_star: <main goal, human-owned>
key_questions:
- How do others control branch explosion at feature-film scale?
- Who pays for interactive video, and how much?
audiences: [dev, product, pm, sales]
default_includes: [shared, agentic-design]
autonomy_policy: {source: auto-merge-safe, note: suggest, datapoint: suggest}
autonomy_policy: {source: auto-merge-safe, note: auto-merge-safe, datapoint: auto-merge-safe}
---
Other starting projects: dome-performance, agentic-design.
```
The confirmed pilot covers Dome interactive content and an interactive video platform/service. dome-performance and interactive-video are suggested IDs; agentic-design remains an example rather than a third pilot commitment.
## Appendix B. Example note
Illustrative draft, not a validator fixture: the source, source revision, quote, linked problem and run below must be replaced with actual records before acceptance.
```yaml
---
id: interactive-video:state-variables-vs-branching
project_id: interactive-video
@@ -437,25 +443,75 @@ summary: Store choices as flags or values and vary scenes by state so paths do n
audience: [dev, product]
domain: [tech, design]
confidence: medium
status: reviewed
review_state: draft
lifecycle: active
created: 2026-10-12
updated: 2026-10-12
tags: [state-tracking]
run_id: example-run
agent: example-agent
model: example-model
claim_support: pending
solves: [interactive-video:combinatorial-explosion]
lens_fit:
interactive-video: {score: 0.9, horizon: H3, key_question: branch explosion}
interactive-video: {score: 0.9, horizon: H3, key_question: branch explosion, reason: addresses the project question}
agentic-design: {score: 0.4, horizon: H2, reason: state tracking in agent workflows}
derived_from:
- {source: shared:src-example-talk, quote: "...", loc: "t=14:32"}
- {source: shared:src-example-talk, revision: example-revision, quote: "<exact transcript quote required>", loc: "t=14:32; span=<required>"}
schema_version: 1
---
```
## Appendix C. Agent tool signatures (illustrative)
search(query, project="interactive-video", scope="project+shared", filters={type, audience, domain, since}, limit=10)
get_node(id)
neighbors(id, edge_types=[], depth=2, scope="project+shared")
timeline(topic, project, from, to)
compare(ids)
brief(topic, project, audience, purpose, token_budget)
Content requests require scope_context = {project, includes?} or an explicitly selected projects/all scope. The server resolves and returns effective scope; the same scope rules apply to redirects and resources. Authenticated actor identity comes from credentials, not these arguments. Content responses use the budget contract in FR-A3; proposal/decision receipts have a separate documented size limit.
```text
search(query, scope_context, token_budget, filters={}, limit=10)
get_node(id, scope_context, token_budget)
neighbors(id, scope_context, token_budget, edge_types=[], depth=2)
timeline(topic, scope_context, from, to, token_budget) # P1
compare(ids, scope_context, token_budget) # P1
brief(topic, scope_context, audience, purpose, token_budget) # P1
list_projects()
propose_note(project, node_bundle, run_id)
flag_stale(id, reason)
propose_note(scope_context, node_bundle, run_id, proposal_id, base_revision)
flag_stale(id, scope_context, reason, proposal_id, base_revision) # stages a proposal
```
Resources: kb://schema, kb://projects/{project_id}, kb://nodes/{id}. Prompts: per-project roles, for example architecture_advisor(project_type, budget_tier) for interactive-video.
MCP additionally needs typed source-artifact transfer and proposal operations to list/get status, inspect validation, submit revisions/support assessments, withdraw a draft and request policy evaluation. Exact schemas are an M0 deliverable. The service performs acceptance under policy; agents cannot invoke an unconditional merge or impersonate owner authorization. Protected changes need attributable owner authorization through the MCP workflow. The website and generic HTTP/CLI interfaces provide no contribution or acceptance path.
## Revision notes (0.3)
- Confirmed shared-team and agent target, all-team read access, and P0 authentication/mutation permissions while preserving P2 project confidentiality.
- Defined scope propagation, source revision evidence, separate claim-support review, freshness dimensions, stable rename/promotion behavior, and the limits of local-file write isolation.
- Added concurrent proposal acceptance and recovery requirements; aligned P0/P1 tool exposure and corrected the storage rationale.
- Repaired illustrative examples and documented unresolved release, deployment, benchmark and autonomy decisions. These are requirements and proposals, not claims of implementation or passing tests.
## Revision notes (0.4)
- Applied owner clarification: local development then VPS deployment; local agents remain the writers through MCP; the website only searches and displays knowledge.
- Promoted automatic acceptance policy to P0, replaced browser review with MCP exception handling, and removed alternate HTTP/CLI/direct-file contribution paths.
- Defined source-artifact transfer to the VPS and local-to-VPS authority handover. Explained compiled briefs as optional agent-produced summaries with citations; their launch scope remains undecided.
## Revision notes (0.5)
- Confirmed no internal reasoning agent initially; external local agents supply semantic analysis while service functions validate, index and serve records.
- Specified source-file/URL intake, original artifact storage, citation revision/location navigation and a proposed local MCP transfer connector. Protocol support is distinguished from unimplemented KB upload tooling.
- Added problem/topic browsing, typed solution relationships with conditions, tag filtering and labeled similarity suggestions. Added P0 FR-U9; graph canvas and rich comparison matrices remain P1.
## Revision notes (0.6)
- Applied the implementation review of Jev and SCAR/Winnow, preserving the no-internal-agent and MCP-only contribution boundaries.
- Added durable external-run manifests/bounded resumption (FR-I11) and capability/version diagnostics (FR-A10), both P0.
- Clarified external skill contracts, explicit project intent, structured support assessments, source location maps, transport authorization, content-bound replay and durable acceptance receipts.
- Required per-client/deployment workflow evidence; source projects' existing code or documentation do not establish KB acceptance.
## Revision notes (0.7)
- Reviewed the current PRD against GOAL.md and recorded remaining decisions in [the readiness report](reviews/PRD_TARGET_READINESS.md).
- Clarified shared-policy authority, bundles spanning policy domains, support-assessor decisions and assertion-bound assessment validity.
- Clarified accepted-revision reads during index lag and P0 dependency warnings for displayed syntheses.
- Added M0 decision gates and a full v1 release gate; retained existing priorities and distinguished confirmed pilot domains from suggested registry IDs.
- Recorded owner decisions: smaller pilot, two named projects, up to five people, same-agent support with quality sampling, admin/editor/viewer roles and per-agent API keys/identifiers. Project-restricted access remains later.
- No implementation or runtime acceptance is claimed. Exact pilot client/formats, quality-sampling rules and operating targets remain open.
docs/PRD_REVIEW.md
+123
View File
@@ -0,0 +1,123 @@
# 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.
docs/README.md
+38
View File
@@ -0,0 +1,38 @@
# GEWU architecture and engineering handbook
Started 12 October 2026; revised 13 October 2026. Architecture proposal v0.2; implementation has not started.
**Tagline:** Investigate. Connect. Remember.
GEWU (格物) draws on *géwù zhìzhī* (格物致知), a classical phrase commonly rendered as investigating things and extending knowledge. Interpretations vary; the name evokes examining sources, connecting evidence-backed ideas, and preserving what teams learn for reuse. GEWU is a shared research library with a read-only website and an MCP contribution workflow. The [goal](GOAL.md) and [PRD](PRD.md) own product requirements. This handbook translates them into a proposed implementation and working protocols. It does not change their priorities or claim that M0 is complete.
## Read in this order
1. [Reference review](reviews/ARCHITECTURE_REFERENCE_REVIEW.md): which practices to borrow, adapt or reject.
2. [Architecture](architecture/ARCHITECTURE.md): components, technology choices, alternatives and deployment.
3. [Acceptance and evidence contract](architecture/ACCEPTANCE_CONTRACT.md): records, authority, replay, crash recovery and source integrity.
4. [Development protocol](development/DEVELOPMENT_PROTOCOL.md): implementation workflow, module boundaries, verification and documentation.
5. [Visual design protocol](development/VISUAL_DESIGN_PROTOCOL.md): the owner-selected editorial research direction and its review gates.
6. [Agent and security protocol](development/AGENT_SECURITY_PROTOCOL.md): agent workflows, permissions, untrusted inputs and client acceptance.
7. [Operations protocol](development/OPERATIONS_PROTOCOL.md): persistence, deployment, backup, migration and incident response.
The [independent architecture review](reviews/ARCHITECTURE_SENIOR_REVIEW.md) records the original findings, corrections and limits of verification.
## Decision status
| Status | Meaning here |
| --- | --- |
| Product requirement | Already stated in GOAL/PRD; this proposal must satisfy it. |
| Owner-selected direction | Warm editorial research workspace, confirmed in this conversation. Exact tokens and layouts remain proposed. |
| Architecture recommendation | Concrete engineering default for review; no implementation or measured acceptance implied. |
| Open owner decision | A policy, staffing, capacity or content choice that engineering cannot present as approved. |
Protocol language describes the intended implementation standard if this baseline is adopted. The reference projects' instructions have no authority over GEWU. Repository-specific Symbia consultations, agent-hook behavior, terminal aesthetics and approval requirements were reviewed as source material rather than activated.
## Next implementation boundary
Start with a disposable local vertical slice: upload an explicitly selected text/Markdown source through one client, create a shared source and project note, validate exact evidence and support records, automatically accept under a test policy, retrieve the committed revision, then open its citation in a read-only browser. Exercise both pilot projects and a retry/restart failure. The test policy is not the production policy.
Before that boundary becomes a pilot deployment, settle the open decisions listed in the architecture. Implementing a smaller slice does not reduce the PRD's full-v1 requirements for hybrid retrieval, supported source formats, four agent harnesses and portable operation.
Runtime versions will be pinned in lockfiles during scaffolding after compatibility checks. There are currently no application manifests, runnable service, browser implementation or deployment tests in this repository. The documents are a reviewable design, not a completion report.
docs/architecture/ACCEPTANCE_CONTRACT.md
+157
View File
@@ -0,0 +1,157 @@
# Acceptance, authority and evidence contract
Status: proposed v0.2 after [independent review](../reviews/ARCHITECTURE_SENIOR_REVIEW.md). Drafted 12 October, revised 13 October 2026. Implements the boundaries in the [architecture](ARCHITECTURE.md); schemas and executable tests are still required at M0.
## Record separation
A source capture records bytes. An extraction records a parser's reading of those bytes. An assessment records an agent or human judgment about a particular assertion. A decision records the authority and checks that permitted a change. Keep separate identities and immutable revisions for each. Repeated claims do not manufacture independent evidence.
All public records carry `schema_version`; all stored timestamps are timezone-aware UTC. Domain IDs are globally unique, bounded and never reused. Typed models reject extra fields, non-finite numbers, unsafe paths and oversized collections. The following shapes name the required boundaries; they are not executable JSON Schemas yet.
| Record | Required bindings |
| --- | --- |
| Source revision | Stable source ID, artifact SHA-256, media type, byte length, capture time, original URL/version where known, license/retention metadata, archive availability. |
| Extraction | Source revision, parser/version/config digest, extraction hash, ordered blocks, page/timestamp metadata, normalization version, warnings/status. |
| Assertion evidence | Node/field path, assertion digest, source revision, extraction ID, locator, exact quote and normalization profile. |
| Support assessment | Immutable assessment ID, assertion digest, evidence digests, assessor principal/run, method/rubric, supported/unsupported/unavailable, rationale. |
| Proposal revision | Proposal ID, monotonic revision, initiating project, payload digest, base commit, touched node revisions, affected policy domains, operations, evidence/assessment references, authenticated proposer and run. |
| Validation result | Proposal revision/digest, validator version, evaluated policy versions, dependency revisions, check results and actionable findings. |
| Owner decision | Decision/challenge IDs, proposal/revision/digest, human principal and owner-session ID, affected domains, policy and grant versions, decision, authorization/expiry times, decision digest. No secrets. Immutable decision snapshot; lifecycle tracked separately. |
| Acceptance manifest | Proposal/revision/digest, before-revision, changed paths/content hashes, accepted node revisions, actor/agent/key IDs, decision snapshot/ID/digest when required, policy/validator versions, decision time. |
| Receipt | Immutable proposal/revision/digest, outcome, commit ID when accepted, node revisions, acceptance-manifest path/hash and findings. Current index revision/status appears in the response envelope, separately from this immutable receipt. |
Proposer identity is derived from authentication. A self-reported model or harness label is useful provenance but grants no capability. Assessment authorship is likewise authenticated; the agent cannot submit a record pretending to be a human reviewer.
## Public transport contract
One versioned operation catalog owns request/response schemas and capabilities. Each content request includes `api_version`, `request_id`, explicit `scope`, and operation-specific fields; reads add `budget_tokens`, bounded `limit` and optional opaque `cursor` where applicable. A cursor binds the normalized query, scope and index revision; a mismatched or retired snapshot returns `CURSOR_EXPIRED`, never silently mixes pages.
Successful reads return `api_version`, `request_id`, `resolved_scope`, `data`, complete `citations`, `warnings`, `omissions`, `canonical_revision`, `index_revision`, `retrieval_mode`, `budget_profile`, `tokens_used` and `next_cursor` where applicable. Fields irrelevant to a direct canonical read are explicitly null with a reason. Error envelopes use `code`, safe `message`, `findings` and `retryable` plus request identity. HTTP status and MCP error representation map to the same domain result. Query `data` contains only accepted records; draft status belongs to proposal operations.
| Surface | Authentication | Allowed capabilities |
| --- | --- | --- |
| Read HTTP API | Read-only browser session or agent bearer key | Scoped search, node/source/neighbor/history reads; agent responses have the same budgets and citations as MCP. No proposals or owner decisions. |
| Agent MCP | Provisioned agent key through the controlled connector profile | Permitted reads, upload/staging/run operations and typed knowledge proposals; no human owner decision. |
| Owner MCP | Dedicated short-lived human owner session | Read the challenge/diff and authorize/reject that bound protected proposal within current owner grants. No unconditional merge. |
| Authentication/control plane | Human login or restricted operator channel | Session establishment and credential/grant management only; no knowledge-authoring bypass. |
Named initial operations are `search`, `get_node`, `neighbors`, `list_projects`, `source_upload_begin/chunk/finalize`, `proposal_submit/get/revise/withdraw/evaluate`, `run_get/checkpoint` and `flag_stale` (a proposal). Exact schema files and HTTP path mappings must be generated and tested at M0 before adapters are implemented. The content/authority semantics above are fixed design recommendations, not left for each adapter to invent.
## Scope and policy domains
Reads resolve requested projects plus their declared includes and shared. An `all` request is explicit. Direct IDs, redirects, source citations, graph neighbors and suggestions honor the resolved scope. When a target is outside scope, return an omission reason and a way to request wider scope. Never silently follow a link into another project.
Mutation authority follows every changed record. A project owner does not gain control of shared records or another project's records through a read include. Shared has an explicit owner grant and policy.
Proposed bundle rule: all-or-nothing acceptance in one Git commit under every affected policy. A source in shared and a project note may travel together only when both domains authorize their changes. Otherwise retain the entire bundle and return domain-specific findings. The agent may submit a shared-source proposal first, then a dependent project-note proposal; each receives its own receipt. Never report an incomplete bundle as accepted.
## Proposal lifecycle
| Persisted state | Entered by | Allowed next step |
| --- | --- | --- |
| `staged` | New proposal or corrected immutable revision | Evaluate; withdraw. |
| `validating` | Service records the evaluation attempt and input bindings | Accept, return to staged with findings, hold for review, or reject. A crashed attempt is recovered and revalidated. |
| `needs-review` | Missing protected decision, policy exception or unresolved ambiguity | Append assessment/decision and revalidate; submit corrected revision; reject or withdraw. |
| `accepted` | Canonical commit published and receipt reconciled | Terminal for this proposal. Corrections use a new linked proposal. |
| `rejected` | Authorized explicit rejection with rationale | Terminal. A new linked proposal may address the rejection. |
| `withdrawn` | Authenticated proposer/authorized owner withdraws before acceptance | Terminal. An accepted proposal cannot be withdrawn. |
`validation-failed`, `conflict`, `busy`, `dependency-unavailable` and `index-pending` are outcomes, not competing lifecycle states. Invalid or conflicting proposals return to `staged` with an immutable failed-attempt record. `index-pending` accompanies accepted state and does not request a second acceptance.
Correction appends a proposal revision and invalidates previous validation. Changed assertions or evidence invalidate their support assessments. An unchanged payload cannot inherit a validation result under a changed policy, schema or dependency revision. Withdrawal and acceptance serialize through the same writer; whichever completes first determines the permitted next action.
## Exact replay and conflict behavior
The client supplies `proposal_id`, revision and payload digest. The service recomputes the digest over canonical serialization. Exact retries return the original durable receipt, with current index status in a separate envelope. Reusing the same ID/revision with different content returns `IDEMPOTENCY_CONFLICT`; correction requires a new revision. Retrying an already accepted proposal never creates a second commit.
Proposal edits use expected revision checks. In the initial implementation, a changed canonical base commit returns a conflict, even if only an unrelated record changed. This conservative rule avoids implicit rebases. The client can fetch the new base and submit a new proposal revision, reusing only assessments whose assertion/evidence bindings remain identical. Record conflict frequency; move to dependency-level optimistic concurrency later if measurements justify it.
Authenticated status reads are allowed after key rotation through the same stable agent identity and current read capability. Revocation blocks further use of the old key; it does not erase its historical attribution.
## Publication and crash recovery
The acceptance commit itself contains the acceptance manifest at the deterministic path `acceptance/<proposal-storage-key>/<revision>.yaml`. It cannot contain its own Git commit ID. The external receipt resolves that ID from the committed manifest. The manifest path is unique and immutable; its first introducing commit on the authoritative ref's ancestry supplies the accepted commit ID. An orphan commit or another branch cannot establish acceptance.
Publication progress is a separate durable journal field, not a second proposal lifecycle: `evaluated`, `publishing` (expected head, manifest path/hash, prepared commit ID), `published-unreconciled` (published commit), then `reconciled` (receipt path/hash). The ref may advance before the journal records `published-unreconciled`; recovery always checks Git rather than trusting a stale journal field.
1. Persist the proposal revision and evaluation intent using temporary-file write, flush and atomic replace. Journal events are separate immutable files with a recoverable sequence; an interrupted tail is detectable.
2. Validate outside the writer's critical section where possible. Prepare safe content-addressed artifacts and bounded file changes. Quarantine uploads cannot become canonical references before integrity checks succeed.
3. Acquire exclusive writer access. Recheck current authentication/grants, policy versions, base commit, dependency hashes and protected decision bindings. Serialize credential/grant changes with the final authorization check and publication so revocation cannot race that check. Do no parsing, model inference or external network I/O while holding this boundary.
4. Build the exact Git tree using a private temporary index and argument-vector Git commands. Include only changed canonical records and the acceptance manifest. Generate the commit, then publish the canonical branch with `git update-ref <ref> <new> <expected-old>` while holding the process-lifetime writer lock. Only a successful ref update makes the change accepted; orphan commit objects do not.
5. Persist the immutable external receipt with the published commit ID; reconcile stage state and any consumed owner decision in the control store. If a required reconciliation write fails, freeze all new canonical publications and return an indeterminate/recovering result until reconciliation succeeds. Do not call the committed mutation rejected.
6. Schedule derived indexing from the published Git revision. The response envelope reports `index-pending`, `indexed` or `index-failed` alongside the receipt. Direct accepted-revision reads remain available.
Canonical readers use a committed tree, never partially modified worktree files. A service-owned checkout may be materialized for inspection after publication. Manual edits to that checkout are unsupported; detect drift and do not import it automatically.
| Failure point | Recovery requirement |
| --- | --- |
| Before proposal durable write | Return failure; retry can submit again. |
| Artifact stored, no accepted reference | Keep quarantined/unreferenced until retention cleanup; no accepted knowledge exists. |
| Prepared tree or orphan commit, ref unchanged | Ignore for acceptance; retry against current head. |
| Ref updated, receipt absent | Locate the committed manifest, verify digest/authority bindings, recreate receipt and reconcile stage state. Never reapply the bundle. |
| Receipt exists, index behind | Replay index updates or rebuild; status remains accepted. |
| Index generation corrupt | Serve explicit unavailable/degraded results or canonical ID reads; rebuild from authoritative records and artifact maps. |
| Unknown/manual canonical mutation | Hold writes for operator diagnosis. Do not manufacture a receipt or silently reset history. |
Startup reconciles manifests and workflow records before accepting new writes. Every proposal retry and status lookup also checks its deterministic manifest path against a captured authoritative ref when the receipt is absent or inconsistent. If present, verify proposal/digest bindings and the introducing commit, reconstruct the identical receipt and consume the bound decision idempotently under the global publication/recovery gate. If required persistence still fails, return `RECOVERY_REQUIRED` and keep new publications frozen. If absent and the writer has no active attempt, resume/revalidate staged work. This applies before restart as well as afterward, including requests from a different principal.
Fault injection must kill the process at each boundary, including filesystem write failures and receipt failures. Test live retries, unrelated queued proposals and challenge replay during the recovery window. Process-crash tests do not establish power-loss durability; storage flush behavior and backup recovery require separate acceptance on the intended filesystem. Network/shared filesystems and concurrent writers are outside this baseline.
## Human ownership without per-note approval
Routine auto-acceptance is controlled by explicit production policy. Proposed initial candidates are additive source captures and factual notes/datapoints with valid locations and supported assessments. Same-agent assessment is permitted for routine factual notes, as confirmed in the PRD. This candidate list is awaiting owner selection; a confidence threshold alone never authorizes acceptance.
Policy separately enumerates shared-source metadata, entities, typed links, interpretations and syntheses. Missing rules hold affected changes. Destructive merges, promotion, protected project intent and autonomy policy need attributable exceptional authority. Link correctness must not be inferred merely from both endpoint nodes existing.
Proposed protected-action flow:
1. An agent stages a proposal and receives a public challenge ID and exact digest. The challenge is not a bearer approval.
2. The human launches the owner client outside the agent's execution account. It obtains the dedicated session defined below, retrieves the diff directly from MCP, and displays affected projects, policy effects, hashes and expiration.
3. The human confirms there. The owner client submits a decision through MCP; the service checks project/shared ownership and records a single-use authorization bound to proposal revision, digest, policy versions and expiry.
4. The service revalidates and accepts when every affected domain permits it. Changed content, changed authority/policy, expiration or withdrawal invalidates the decision. The agent receives status only and never receives owner credentials.
An admin bootstraps accounts, key issuance and owner grants through a separate operator control plane. This authority alone cannot bypass a protected knowledge decision. Owner decisions and their audit references survive index deletion. The account/bootstrap commands are proposed tooling, not currently runnable commands.
Isolation is a deployment fact. If the agent can execute as the owner and read the owner's secrets, this mechanism cannot prove human-only authorization. Use a separate OS principal/device or a protected interactive authenticator before claiming that gate passed. Do not invent human approval from conversational text supplied by the agent.
### Proposed owner authentication profile
Use the controlled GEWU owner CLI over HTTPS to the same service's Streamable HTTP MCP endpoint. Before MCP initialization, the CLI calls a separate `POST /auth/owner-session` control endpoint with human account ID, password, TOTP and challenge ID. Password/TOTP are read directly from the human terminal without echo, never arguments/environment variables, and discarded after use. The server verifies a maintained Argon2id password hash and TOTP with a pinned library (proposed `argon2-cffi` and `pyotp`), rate limits failures and prevents reuse of an accepted TOTP timestep. Enrollment/reset requires restricted operator identity and records a security event. TOTP seeds are encrypted under a service key kept outside the database and ordinary data-backup set. Maintain that key in a separately protected, encrypted, access-controlled recovery backup. A restore verifies the key before enabling owner operations; if unavailable, owner login stays disabled until an attributable operator reset and human re-enrollment complete. Test both recovery paths before team release.
On success, generate a random 256-bit opaque token, store its hash in the private control database, and return it once with a five-minute expiry. Store the human principal, current grant version, service audience, allowed challenge ID and capabilities `owner:inspect`/`owner:decide`. The CLI keeps the token in memory and presents it as the MCP bearer credential; it is rejected by ordinary browser sessions and agent-key validation paths. The token cannot create arbitrary proposals or authorize another challenge. Reauthentication is required after expiry. Network operations verify TLS and the configured service identity. This custom profile is explicitly limited to GEWU's controlled clients and makes no general OAuth-interoperability claim.
MCP operations: `owner_challenge_get(challenge_id)` returns proposal revision/digest, affected domains/policy versions, expiry and status; `owner_diff_get(challenge_id)` returns the exact bounded diff and its digest; `owner_decide(challenge_id, expected_proposal_revision, expected_payload_digest, expected_diff_digest, decision, rationale)` accepts an attributable authorize/reject decision after rechecking current grants. Oversized diffs must be fully paginated and hash-bound before confirmation; they cannot be silently truncated.
Challenges live in the control database with states `issued`, `authorized`, `consumed`, `expired` or `invalidated`, plus immutable transition events. Only an unexpired `issued` challenge can acquire an immutable owner decision. Exact decision retries return the same decision; altered retries fail. Multiple owners can supply separate decisions for a bundle, each bound to its domains. An authorization is consumed by one acceptance manifest containing the full non-secret decision snapshot and digest. The global writer/recovery gate ensures the manifest is checked before any decision can be reused. A crash before the SQLite consumed flag is updated is recovered from that manifest; a missing flag cannot permit another acceptance. Rejection invalidates the challenge and records its decision without publishing the proposed knowledge.
Contract tests must cover owner session used as an agent token, browser/agent token used for owner operations, expired/wrong-audience token, revoked grant, TOTP reuse, altered diff, duplicate decision and crash-before-consumed-state. The profile remains proposed until implemented and reviewed on the actual client/service deployment.
Library basis checked 13 October 2026: [argon2-cffi password verification](https://argon2-cffi.readthedocs.io/en/stable/howto.html) and [PyOTP](https://pyauth.github.io/pyotp/). PyOTP documents replay rejection, secret protection and throttling as application responsibilities. Neither library establishes human/agent OS isolation or makes this profile phishing-resistant; a hardware-backed authenticator is a possible later replacement for the owner login adapter.
## Source transfer and evidence locations
The stdio connector reads only an explicitly selected path within configured roots. Reject devices, directories and reparse/symlink escapes; revalidate the opened handle/file identity to avoid path races. It transfers bytes to service MCP upload-session/chunk/finalize operations. Never echo source bytes or credentials into model-visible upload responses.
Proposed initial limits for probing: 50 MiB per artifact, 512 KiB binary chunks, two concurrent uploads per credential, ten-minute idle upload expiry, 100 operations per proposal and 1 MiB proposal JSON. The JSON wire limit accounts for base64 expansion. Advertise effective limits in diagnostics; tune only from measured fixtures and operational limits. These values do not constitute owner-approved archive capacity.
Chunk retries bind session/offset/content hash. A duplicate matching chunk succeeds idempotently; changed content at the same offset fails. Finalization verifies full length and SHA-256 before creating an immutable artifact. Upload completion is staging, not source acceptance. Resume reports verified offsets; expired sessions fail explicitly.
Locators use zero-based Unicode code-point offsets and half-open spans into a specified immutable extraction block. PDF page numbers are one-based. Text/HTML locators name a block ID; timestamped transcripts additionally name the time interval. A quote must match at that locator after the declared normalization profile. Normalization may standardize line endings and Unicode form, but cannot silently rewrite numbers, units or qualifiers. Record the normalized text alongside the original map.
The server derives or verifies extraction maps from captured bytes with its pinned parser. Agent-supplied extracted text cannot substitute for an archived PDF's location map. Encrypted, scanned, multi-column or mathematical sources may require a specialized parser/OCR adapter; return an explicit unsupported/unavailable extraction state until that path is verified. Preserve originals and every cited extraction version when parsers change.
### Immutable extraction format and rebuild procedure
Store one canonical UTF-8 JSON extraction artifact with `schema_version`, source artifact hash, parser name/version/config digest, normalization profile, extraction status/warnings, and ordered `blocks`. Each block has `block_id`, ordinal, original extracted text, normalized text, page number or time range, and a normalized-to-original code-point range map. This map relates text representations; it does not claim byte offsets into compressed PDF bytes. PDF page/block association is mandatory; geometry is optional and explicitly absent when unavailable.
Within one extraction artifact, derive `block_id` from the block ordinal and hash of original extracted text. IDs are stable only within that immutable extraction version. Hash canonical serialization of the complete artifact excluding its self-ID/hash field to obtain `extraction_id`; store under that hash. Record hashing/serialization version and test vectors. A citation resolves `(source_revision, extraction_id, block_id, start, end)` against these stored bytes. Normalization maps must resolve every quoted normalized span to original-text ranges. Parser upgrades create new artifacts and never reinterpret old locators.
A full rebuild captures a canonical Git head `H`, enumerates only its accepted record manifests and referenced source/extraction IDs, validates schemas and hashes, and builds an isolated index generation. Read exact stored extraction artifacts; never rerun a parser to resolve an existing citation. Record `H`, index schema, extraction profiles, embedding artifact/profile and corpus inventory hash as the generation watermark. Missing/corrupt authoritative artifacts fail the rebuild visibly rather than dropping affected nodes. After integrity/retrieval checks, publish the generation pointer under the service's index-publication gate, then apply complete commits after `H` in order. A newly published generation may report lag, but must never claim a later head before those commits are indexed. Crash recovery uses the generation watermark and replays unapplied commits; incomplete generations are never selected.
Reference-only sources remain discoverable with availability warnings. Their unsupported assertions stay outside the accepted evidence-backed corpus. A quote-location pass establishes occurrence; semantic support, source reliability, confidence and freshness remain separate fields.
## Contract errors and acceptance fixtures
Errors carry a stable code, safe message, request/proposal identity, field findings and retry guidance. Initial codes include `SCOPE_REQUIRED`, `OUT_OF_SCOPE`, `UNAUTHORIZED`, `OWNER_DECISION_REQUIRED`, `POLICY_MISSING`, `EVIDENCE_MISMATCH`, `SUPPORT_UNAVAILABLE`, `BASE_CONFLICT`, `IDEMPOTENCY_CONFLICT`, `BUDGET_TOO_SMALL`, `UPLOAD_EXPIRED`, `BUSY` and `RECOVERY_REQUIRED`. Internal paths, raw SQL and secrets remain in neither client errors nor routine logs.
M0 must implement adversarial fixtures for wrong-location matching quotes; wrong numeric units with valid quotes; changed assertions with old assessments; cross-policy bundles; stale owner approval; revoked key at publication; changed payload replay; scope escape through redirects; crash-after-ref-before-receipt; index lag; and whole-group token budgets. These fixtures are required work, not tests claimed to exist.
docs/architecture/ARCHITECTURE.md
+157
View File
@@ -0,0 +1,157 @@
# GEWU architecture
Status: proposed baseline v0.2 after [independent review](../reviews/ARCHITECTURE_SENIOR_REVIEW.md). Drafted 12 October, revised 13 October 2026. Product authority: [GOAL](../GOAL.md) and [PRD](../PRD.md). Related: [acceptance contract](ACCEPTANCE_CONTRACT.md).
## Decision
Build a modular Python service and a React reading application in the GEWU code repository. Deploy one authoritative knowledge repository per installation, shared across projects. The knowledge repository and private runtime data live outside the code checkout and outside agent-writable mounts.
Local agents reason about sources and submit proposals. The service validates their structure, source locations, permissions and policy eligibility, then records accepted changes. People can search and follow evidence without an agent running. The service contains no reasoning agent, autonomous research loop or general-purpose chat endpoint.
The starting deployment is one host, one service instance and one canonical writer. This fits the five-person pilot and makes the acceptance boundary inspectable. Capacity remains a measurement gate; five people does not specify simultaneous agent load.
## Technology choices and reasons
These are proposed baselines, not installed versions. Use Python 3.12 as the initial compatibility target, Pydantic 2, React 19 and TypeScript strict mode. Resolve supported releases of the other packages at scaffolding, pin exact versions in `uv.lock` and `package-lock.json`, and record Python, Node and SQLite runtime versions. Do not deploy floating `latest` dependencies. Any version conflict reopens the relevant choice before implementation.
| Boundary | Choice | Why for GEWU | Alternative and reconsideration trigger |
| --- | --- | --- | --- |
| Service | Python, FastAPI, Pydantic, Uvicorn; `uv` for environment/locking | Typed validation and the document-processing ecosystem; consistent with useful AAA/Jev patterns. | A TypeScript-only service saves a language but complicates Python parser integration. Revisit if parser requirements disappear. |
| Domain core | Plain typed Python modules, explicit dependency injection | The same scope, evidence and proposal rules serve MCP, reads and maintenance. | No generic pipeline/plugin framework until distinct implementations need one. |
| MCP | Official Python MCP SDK; local stdio connector, service Streamable HTTP | One contract across agent harnesses; connector can read selected local files and upload bytes. | Direct remote connections remain a tested option for clients that support the chosen auth profile; a remote path is never a file upload. |
| Canonical knowledge | UTF-8 Markdown with YAML frontmatter, YAML records, native Git CLI | Reviewable records, exact history, portable exports. | A database as canonical storage conflicts with the present PRD. |
| Private artifacts | Content-addressed filesystem by SHA-256 | Retain originals without growing Git with PDFs/media. Git records hashes and manifests. | Object storage only after one-host capacity/backup measurements justify it. |
| Search/graph | SQLite FTS5, ordinary edges tables, `sqlite-vec` behind a vector adapter | Rebuildable on one host; no graph/vector service to operate. | `sqlite-vec` is a gated candidate because its upstream describes pre-v1 compatibility risk. If portability/performance fails, revise the adapter choice; full v1 still needs hybrid search. |
| Embeddings | Local Sentence Transformers adapter; multilingual-e5-small is the first evaluation candidate | Offline execution and a multilingual path without hosting a reasoning agent. | Final model/artifact hash depends on the project's labeled language corpus, license and CPU/RAM measurements. API providers are optional and must be explicitly configured. |
| SQL access | Standard `sqlite3`, parameterized SQL, explicit repository methods | FTS/vector queries are easier to audit directly; the index is disposable. | SQLAlchemy/PostgreSQL become candidates only if operational state or deployment topology warrants the cost. |
| Web | React, TypeScript, Vite, React Router | Search, evidence drawers and linked reading views; static production assets require no Node server. | Next.js SSR adds a second server without a present SEO or server-rendering requirement. |
| Browser state | TanStack Query for server data; URL for scope/filters/selection; React local state for transient controls | Cache ownership and cancellation are explicit. | Do not copy AAA's bespoke telemetry stores into a reading application. Introduce another store only for demonstrated shared client state. |
| Visual implementation | CSS custom properties + CSS Modules; Radix primitives where needed; Lucide icons | Small, application-owned visual vocabulary with accessible interaction foundations. | Tailwind/shadcn is viable, but adds conventions without a present component system to reuse. No mixed styling systems by default. |
| Source/rendering adapters | `pypdf` for initial PDF extraction, `markdown-it-py` for Markdown structure, `trafilatura` for HTML text, `react-markdown` + GFM + sanitized math rendering in the UI | Keep parser-specific behavior behind versioned extraction contracts. | OCR and more complex parsers require a quality/cost probe. PDF extraction success is not locator or reading-order correctness. |
| Quality tools | pytest, Ruff, mypy; ESLint, TypeScript, Vitest/Testing Library, Playwright and axe | Cover contracts, recovery and actual browser reading workflows. | No arbitrary coverage percentage in place of behavioral acceptance. |
| Hosting | Linux VPS, Docker Compose, Caddy HTTPS; native local development | Repeatable single-host service and private volumes; Python serves built UI assets. | Kubernetes, Redis and distributed queues are deferred until measured need. |
The exact dependency inventory is a scaffolding deliverable. Model selection and native vector packaging are explicit prototype gates, not reasons to pretend the stack is already verified.
## Components and dependencies
```mermaid
flowchart LR
H[Human reader] --> W[React website]
W --> R[Read HTTP adapter]
A[Local agent harness] --> C[Local stdio MCP connector]
A --> R
C --> M[Service MCP adapter]
O[Human owner client] --> M
R --> Q[Scoped query services]
M --> Q
M --> P[Proposal and acceptance services]
P --> V[Schema, evidence and policy validators]
P --> G[Exclusive Git writer]
G --> K[Canonical knowledge repository]
P --> J[Durable staging and run records]
P --> B[Private source artifacts]
K --> I[Index worker]
I --> S[Derived SQLite index]
Q --> S
Q --> K
```
Imports point inward: transport -> application -> domain. Adapters implement storage, Git, clock, parser and embedding interfaces used by application services. Domain code imports neither FastAPI nor MCP nor React. A small lifespan-owned composition root creates services and closes resources. Each application service owns a complete use case; routes translate protocol messages and enforce transport admission.
Recommended code layout:
```text
src/skb/
domain/ # node, evidence, scope, policy, proposal contracts
application/ # intake, evaluate, accept, query, runs, maintenance
adapters/ # git, artifacts, records, sqlite, parsers, embeddings, auth
transports/ # MCP, read HTTP, operator/maintenance CLI
bootstrap/ # configuration and lifespan assembly
connector/ # local stdio client bridge; uses shared contract package
web/src/
app/ # routes, providers, shell
features/ # search, reading, sources, problems, history
components/ # shared accessible primitives
api/ # generated types, typed client, query keys
styles/ # semantic tokens and reading typography
schema/ # generated/versioned public schemas and fixtures
tests/ # unit, contract, integration, recovery, fixtures
docs/ # product, architecture, protocols, decisions, acceptance
```
Do not create empty layers or adapter classes for every file. A module must own a real responsibility. Share public schema definitions between service and connector; generate browser types from the read API. Type generation complements runtime validation.
## Persistence classes
| Store | Contents | Rebuildable? |
| --- | --- | --- |
| Private knowledge Git repository | Projects, nodes, source manifests, accepted evidence/assessments, policies, redirects, acceptance manifests | Authoritative; restore from backup. |
| Private artifact tree | Original bytes and immutable extraction/location maps, keyed by hashes | Required source evidence; restore from backup. A parser rerun does not replace a cited extraction version. |
| Durable staging/run tree | Proposal revisions, validation/decision events, uploads, external-run progress and receipts | Authoritative workflow history, written atomically; restore from backup. |
| Private control SQLite | Human accounts/password hashes, sessions, agent credential hashes, role/ownership grants, owner challenges and security audit | Operational authority; not the disposable search index. Backup with restricted access. |
| Derived SQLite index | Searchable nodes, FTS, edges, vectors, index metadata | Delete and rebuild without losing acceptance, evidence or identity. |
Distinguish the code repository from the knowledge repository. The PRD's single-repository rule means all knowledge projects share one canonical repository; it does not require committing private team sources into the application's code repository.
Git paths use safe storage keys rather than raw logical IDs. IDs such as `shared:paper-name` remain metadata, avoiding Windows filename restrictions. Use bounded safe YAML loading, reject duplicate keys and unknown fields, and emit stable ordering/UTF-8/LF. References use logical IDs and revisions, never caller-selected filesystem paths.
## Reads and retrieval
Every content query carries scope. Resolve registered projects and their explicit includes before search or ID resolution; return `resolved_scope`. All-team visibility does not authorize silently widening relevance scope. Redirects and graph traversal recheck destination scope.
Search runs scope-filtered FTS and vector candidates, merges them with reciprocal rank fusion, and performs bounded typed-edge expansion. Start with a maximum one-hop expansion and explicit candidate/edge caps in the public contract. Return ranking explanations separately from evidence status. Related suggestions never become accepted relationships by indexing.
Use normalized English token search plus language fixtures. `unicode61` alone is not a claim of Chinese word segmentation; test CJK queries and use a documented segmentation or trigram adapter when needed. Evaluate short queries separately. Search acceptance is the PRD's labeled per-project question set, not a synthetic speed result.
Index updates publish all node/edge/FTS/vector changes for a chosen Git revision in one SQLite transaction. Queries use a read transaction pinned to an index revision. A model change builds a separate index generation, with model ID, artifact hash, dimensions, normalization, chunking and parser versions. Publish the new generation only after integrity and retrieval gates pass. Avoid replacing an open database file on Windows: switch the service's generation pointer and retire old connections before cleanup. The acceptance contract specifies the immutable extraction artifact and rebuild watermark procedure.
`get_node` may read a requested accepted revision directly from Git before indexing. Search reports its indexed revision and lag. Embedding outages permit clearly labeled keyword-only reads; they do not relax acceptance rules or count as full-v1 hybrid acceptance.
Budget whole serialized result groups, including citations and warnings. Proposed counting profile: a pinned `tiktoken` package with the `o200k_base` encoding and hash-verified encoding assets, identified in each response and preinstalled for offline use. This is an API accounting convention, not a promise to equal every harness model's tokenizer. Define the error-envelope minimum separately. Never cut a quote or discard a stale warning to meet a budget.
## Process and concurrency model
Run one Uvicorn application worker initially. A process-lifetime OS lock excludes a second canonical writer on the same local filesystem; a repository head compare-and-swap check rejects stale publication. Do not deploy two writers with independent in-memory locks or accept shared NFS storage as equivalent.
Acceptance requests enter a bounded queue whose pending work is recoverable from staging records. Critical acceptance is not a fire-and-forget FastAPI background task. Blocking disk/Git calls cross one bounded worker boundary; extraction and model work execute in capped child processes with timeouts. Workers return artifacts with input hashes; only the service can publish canonical state. The [contract](ACCEPTANCE_CONTRACT.md) defines ordering and recovery.
A revoked credential, changed policy or changed dependency invalidates a prepared result before publication. Cancellation of a caller does not undo an already accepted proposal; status lookup resolves uncertainty.
## Authentication and deployment
Human browser sessions are expiring HttpOnly, Secure, SameSite cookies. The read API accepts those sessions with read capabilities only, including for an admin. It also accepts agent bearer keys for scoped, budgeted retrieval under the same read contracts used by MCP. Authentication endpoints may establish/end sessions but cannot author knowledge. Agent API keys are unique, revocable, server-bound to an agent and responsible human, stored as hashes at the service and outside Git at the connector.
For the initial controlled-team connector, document a GEWU provisioned-key authentication profile over TLS. Do not describe this as generic OAuth interoperability. HTTP MCP authorization has its own specification; supporting arbitrary remote OAuth clients requires a separately implemented and tested authorization-server/resource-server profile. The local stdio connector avoids assuming all four harnesses support the same remote authentication flow.
Protected changes use the human-authenticated owner MCP client and a digest-bound decision described in the contract. The proposed owner profile uses a short-lived opaque session obtained by password and TOTP reauthentication in a separate human terminal; it is an GEWU-controlled client profile, not a claim of generic OAuth support. Production separates the human owner credential from the agent's OS account/credential store. Owner-level unrestricted filesystem agents cannot be claimed to be isolated by prompt instructions.
Local operation uses the same core and directory layout as the VPS. Development may run on the user's account with disposable data; enforced pilot/team operation uses a separate service identity. VPS publication requires an independent restore test, HTTPS, private volumes and client workflow evidence. Moving authority to the VPS freezes local writes first; there is no independently writable local replica synchronization in v1.
## Delivery and open decisions
| Gate | Work | Observable exit |
| --- | --- | --- |
| M0 contract slice | Schemas, state machine, safe file records, scope/policy fixtures; pin dependencies | Seeded invalid evidence/authority rejected; public schemas generated; decisions below settled for affected boundary. |
| Pilot end-to-end | Proposed starting point: Windows/Codex, text/Markdown, two projects plus shared, lexical search first | Upload -> proposal -> automatic acceptance -> committed read -> citation; crash/replay tests; read-only browser. Client/format choice remains recommended. |
| Full P0 service | Hybrid index, all required input types, four harnesses, portability and protected decisions | Per-client transfer/rejection/acceptance/retry/retrieval receipts; no scope or authority bypass. |
| Team release | VPS migration, backup/restore, quality sampling, capacity/security acceptance | All selected PRD P0 gates plus measured retrieval, evidence and human reading tasks. |
| P1 follow-up | Rich comparisons, graph canvas, promotion/import/export and synthesis/curation | Explicitly selected requirements and their own acceptance evidence. |
Still needs owner input: first admin and project/shared owners; production auto-accept policy; sampling owner/cadence/error limits; representative sources and expected answers; supported initial client/format; VPS capacity, concurrent load, archive retention, recovery time and recovery-point targets. Production credentials and policies cannot use silently invented answers.
Technical probes needed: native vector package on Windows/macOS/Linux; parser locator fidelity including scanned/math PDFs; final embedding model and language set; cold rebuild under the PRD's ten-minute target. Measure cached-vector index rebuild and cold re-extraction/re-embedding separately; do not rename a warm rebuild to claim the full target passed.
## Research basis
Checked 12 October 2026. These sources establish available mechanisms, not GEWU performance or compatibility:
- [SQLite WAL](https://www.sqlite.org/wal.html): WAL allows reader/writer concurrency but retains one writer; motivates short index transactions and one-host operation.
- [SQLite FTS5](https://www.sqlite.org/fts5.html): tokenizers and substring search options; language quality needs our fixtures.
- [sqlite-vec upstream](https://github.com/asg017/sqlite-vec): embedded vector implementation and explicit pre-v1 warning; requires an isolated adapter and pinned packaging.
- [Official Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk), [versioned MCP transports](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports), and [HTTP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization): use negotiated compatible versions; do not implement draft changes by accident.
- [FastAPI process workers](https://fastapi.tiangolo.com/deployment/server-workers/): multiple workers are separate processes; an in-process lock cannot serialize their writes.
- [Pydantic strict validation](https://docs.pydantic.dev/latest/concepts/strict_mode/), [Vite](https://vite.dev/guide/), [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview): typed boundaries, static assets and server-state tooling supporting the choices above.
- [pypdf extraction limitations](https://pypdf.readthedocs.io/en/stable/user/extract-text.html): extraction and OCR are different capabilities; quality must be measured.
- [Sentence Transformers model loading](https://www.sbert.net/docs/package_reference/sentence_transformer/model.html) supports pinned revisions and local-only loading. The [multilingual-e5-small model card](https://huggingface.co/intfloat/multilingual-e5-small) was available in search results; direct retrieval failed, so its full configuration/license remains a mandatory probe rather than a verified selection.
- [tiktoken](https://github.com/openai/tiktoken) provides named encodings for a reproducible budget convention. [Git update-ref](https://git-scm.com/docs/git-update-ref.html) supports an expected-old object check for publication.
docs/architecture/LOCAL_AGENT.md
+77
View File
@@ -0,0 +1,77 @@
# GEWU local agent
13 October 2026. Owner requirement: a custom local agent built like the agents in the RESEARCH workspaces. Delivery form confirmed by inspecting Winnow in SCAR and Praxis in CV: a workspace profile, shared protocols, modular skills and coordinating pipeline instructions executed by an existing host application.
## Architecture decision
Ship a GEWU research-agent pack that runs inside a supported local agent host. The host supplies reasoning, model access and tool execution. GEWU supplies its role, task-specific skills, pipeline procedures and MCP connection contract. A new standalone agent runtime is outside this addition.
The pack is a first-class GEWU client and follows the same permissions as other clients. The knowledge service remains independent: it validates proposals, applies acceptance policy and stores records; the agent interprets sources and drafts knowledge. Reading and evidence navigation continue when no agent is running.
Local execution describes where the host and working files live. A configured cloud model may still receive content. Offline reasoning requires a host with a configured local model; neither the pack nor a local folder guarantees that data stays on the computer. Keep model/provider selection in the host configuration and record the actual model where available.
## Source and installation boundary
The source pack lives at [agents/gewu](../../agents/gewu/README.md) in this repository. Its own `AGENTS.md` defines the research role; it is not the development repository's global persona. This avoids turning every coding session into a research ingestion session.
The intended installed layout resembles the RESEARCH workspaces:
```text
<research-workspace>/
AGENTS.md # thin discovery pointer to canonical profile
.agents/
AGENTS.md # GEWU role and routing
manifest.json # pack/skill/pipeline versions and readiness
protocols/ # shared evidence, scope and proposal rules
skills/<name>/SKILL.md
pipelines/ # coordinating procedures and checkpoint fields
Inbox/ # explicitly selected local source inputs
Drafts/ # unaccepted draft artifacts
Runs/ # private local checkpoints/receipts
```
The checked-in source pack can be linked or installed into the canonical `.agents` directory. Host-specific configuration/pointers and a copy fallback must preserve other installed skills and agent profiles. A partial single-skill copy must also include its referenced protocols/pipelines. Do not overwrite an existing root persona or claim host discovery merely because files exist. No host configuration, symlink or user-global installation is performed by this change.
The live reference inspection found SCAR `.agents` points to `.opencode`; CV owns `.agents` directly. Both use workspace rules and reusable skills. GEWU adopts the organization, while changing their direct-file contribution behavior to its MCP proposal contract. Source reads were limited to profiles, skill templates and representative pipelines; their runtime behavior was not retested.
## Responsibilities and replaceable modules
| Part | Owns | Replacement boundary |
| --- | --- | --- |
| Agent profile | Role, routing, project context and collaboration behavior | Update profile version without copying workflow logic into it. |
| Protocols | Shared evidence, scope and contribution guidance | Referenced by concern; authoritative server validation still lives in service code. |
| Skills | Ingest, retrieve, curate or synthesize one coherent kind of task | Versioned inputs/outputs, tool needs and acceptance criteria. |
| Pipelines | Order skills/stages, identify checkpoints, route corrections and report coverage | Separate files reference skills; a changed coordinator need not rewrite every skill. |
| Host adapter | Discovery, permitted tools and model/runtime configuration | Preserve the same public skill and MCP contracts across hosts. |
| Local connector | Safe file transfer, MCP transport and diagnostics | Shared connector contract; contains no semantic decision authority. |
The [modularity protocol](../development/MODULARITY_PROTOCOL.md) applies to all these parts. Pipeline files are procedures interpreted by the host agent, not an executable scheduler or durable engine. MCP run records and receipts provide durable service-side progress. Local checkpoints support recovery but cannot prove acceptance.
## Initial workflows
| Skill | Pipeline | Output |
| --- | --- | --- |
| `kb-ingest` | Context -> source capture -> triage -> evidence-bound extraction -> support assessment -> proposal -> receipt | Accepted IDs/receipts, held drafts, coverage/skips and actionable findings. |
| `kb-query` | Scope -> retrieve -> inspect evidence -> bounded answer | Cited answer with scope, as-of dates, uncertainty and omissions; no writes. |
| `kb-curate` | Scoped audit -> inspect candidates -> propose corrections/relations -> receipts | Traceable changes or a report, preserving disagreements and old revisions. |
| `kb-synthesize` | Accepted inputs -> dependency inventory -> compare/compose -> evidence audit -> optional proposal | Labeled local synthesis draft, or accepted synthesis after a real receipt. |
The four skills are instruction artifacts in this change. Service schemas, executable tools and client acceptance remain unimplemented. The manifest declares no verified service compatibility yet. The pack can organize explicitly requested local drafts; it must report the missing service instead of fabricating tool calls, source revisions or accepted knowledge.
## Run and resume contract
At run start, record local run ID, authenticated service/agent identity when connected, explicit scope, task objective, pack/skill/pipeline versions and content hashes, host/model label, input hashes and budgets. Resolve tools and schemas from service diagnostics. Unsupported tools or schemas produce a clear blocked stage. Stage records name their inputs, outputs, disposition and last durable receipt.
For a connected run, service run identity, proposal revisions and acceptance receipts are authoritative. Resume queries them before retrying an uncertain upload/proposal result. Model output is not deterministic: preserve completed output artifacts and their hashes rather than asking the model to regenerate the same content and assuming identical IDs.
Pin the installed pack snapshot for an active run. If that version is unavailable after an upgrade, pause with a compatibility finding or explicitly start a successor run. Reuse previous outputs only when their hashes, evidence bindings and new stage contracts still hold; revalidate downstream stages after changes. Install/version manifests alone cannot enforce this in arbitrary hosts; native workflow tests must demonstrate it.
A pipeline has a bounded work/correction budget, explicit coverage and a resumable stop. Two unchanged validation failures are a default stop for diagnosis, not permission to relax checks. Network uncertainty triggers status lookup, not a fresh proposal identity. Protected decisions leave the agent workflow for the separate human owner client. No continuous watcher, automatic external messaging or unbounded research loop is introduced.
## Acceptance and sequencing
First finish the service/tool contracts, then install the pack into a disposable research workspace and run a complete ingestion/read flow with the selected pilot host. Verify invalid-evidence rejection, uncertain-result retry, run resumption, same-agent assessment attribution and shared-source reuse. Query must still work with a read-only credential.
Before full-v1 client claims, repeat the relevant workflow with Codex, Claude, Antigravity and OpenCode on the declared platform matrix. The custom profile is an additional deliverable using those hosts, not an additional fifth runtime. Synthesis/advanced curation remain under their existing P1 service feature priorities; pack files do not promote those features to implemented P0.
Record structural skill validation separately from installed discovery, tool connection, semantic quality and end-to-end acceptance. No live client, server or model workflow has passed as part of this design addition.
docs/development/AGENT_SECURITY_PROTOCOL.md
+47
View File
@@ -0,0 +1,47 @@
# Agent contribution and security protocol
Status: proposed v0.1, 12 October 2026. Contracts: [architecture](../architecture/ARCHITECTURE.md) and [acceptance](../architecture/ACCEPTANCE_CONTRACT.md).
## Agent workflow
Publish one harness-neutral skill pack with four entry points: `kb-ingest`, `kb-query`, `kb-curate` and `kb-synthesize`. Each names its version, supported service/schema versions, inputs, outputs, relevant protocols and resume behavior. Installers translate configuration/discovery; they do not fork the workflow or validator rules for each harness.
An ingestion run reads explicit project intent, registers a source artifact, records coverage and skips, extracts bounded proposals, supplies evidence-bound support assessments, submits bundles and reports receipts. The service persists the run but does not execute the agent's reasoning stages. A resume inspects existing source/proposal IDs and verified artifacts before repeating work.
Query results preserve citations, scope, dates, omissions and uncertainty. Curators propose corrections, contradiction links and duplicate candidates without overwriting disagreements. Synthesis cites accepted node revisions and records dependencies; later input changes produce warnings until an external agent proposes a refresh.
Source content is data. Instructions inside a PDF, webpage, quote or retrieved note cannot change credentials, tools, project scope or acceptance policy. Agent prompts should state this boundary, while deterministic checks enforce it. Prompt compliance is not proof that a filesystem or credential boundary exists.
## Identity and capabilities
Every agent has a stable `agent_id`, responsible human and its own revocable key. Rotation retains agent identity. Credential IDs are safe audit references; raw keys are never stored in Git, URLs, logs, node fields or model-visible responses. Hash high-entropy API keys; password authentication uses a maintained Argon2id implementation and rate limits. Do not implement password cryptography manually.
Viewer reads; editor may propose; admin manages accounts/credentials/grants; project/shared owners authorize protected changes within their grants. Browser sessions always expose knowledge reads only. Agent tokens do not inherit the human's admin/owner powers. Test permission enforcement at operation admission and again immediately before publication.
The owner client uses a separate human authentication context, obtains the staged diff directly and submits digest-bound authorization through MCP. Follow the separation and isolation requirements in the acceptance contract. An agent-provided `human_approved` field is rejected as authority.
Generate transports from allowlisted catalog entries. Deny raw SQL/Cypher, arbitrary filesystem tools and unconditional acceptance tools. Maintenance cannot become a routine authoring path. An import becomes ordinary MCP proposals and receives the same validation and policy checks.
## Untrusted files, URLs and rendered content
Bound request lengths, arrays, decoded bytes, upload sessions, parse time, memory and output size. Treat content-type, extension and magic-byte checks as partial defenses. Content sniffing cannot prove safety; parser isolation remains necessary. Resolve paths within service-owned roots and reject traversal, symlink/reparse escapes and unsafe filenames.
Document-fetch requests allow HTTP(S) only, revalidate each redirect, block loopback/private/link-local/multicast/metadata targets by default, and bind connection behavior to validated destinations. DNS resolution followed by an uncontrolled second resolution is insufficient against rebinding. Operator exceptions must name the allowed destination/network and purpose; they cannot arise from source instructions. Apply equivalent restrictions when a connector performs fetching.
Service parsing runs without network access or credentials, with a restricted temporary directory and resource limits. Parser child processes are a lifecycle boundary; OS/container sandboxing establishes the security boundary. Test that untrusted parsers cannot read service secrets or unrelated artifacts. Never claim isolation solely because a subprocess exists.
Store originals privately. Serve archived HTML as safe downloads or sanitized text; never render it under the application origin as executable content. Authenticate artifact access just like node access. Retention/rights metadata applies to originals and backups. The absence of project ACLs does not imply public archive access.
Validate MCP origins and hosts, bind local services to loopback, use TLS on hosted endpoints and limit cross-origin access. Keep stdio stdout protocol-only and send redacted diagnostics to stderr. Session IDs are not credentials. Pin and negotiate supported MCP versions; record the provisioned-key profile separately from any future OAuth implementation.
Security source checks: [MCP transport security requirements](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) and [HTTP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization), read 12 October 2026. These standards do not by themselves prove GEWU compliance.
## Portable client acceptance
The target harnesses remain Codex, Claude, Antigravity and OpenCode. Record actual application, connector, service and OS versions. Initial pilot coverage may be smaller only when named explicitly. Full v1 must exercise every supported harness and the declared Windows/macOS/Linux portability matrix; a single handshake cannot close those gates.
For each supported pair, verify configuration preserves other servers/skills, correct service/project identity, authenticated source-byte transfer, invalid-evidence rejection, eligible automatic acceptance, exact retry, interrupted-run resume and cited retrieval. Repeat the applicable remote transfer path against the VPS. A VPS cannot read a client-local path.
Use PASS, FAIL, BLOCKED, NOT RUN and UNSUPPORTED with evidence origin and blockers. Separate “configured,” “connected” and “workflow verified.” Symlinks are optional; test a configuration/copy fallback. Uninstall/rollback removes only owned entries and preserves unrelated user state.
No client compatibility or enforced credential isolation is claimed by this document. These are acceptance obligations for implementation.
docs/development/DEVELOPMENT_PROTOCOL.md
+73
View File
@@ -0,0 +1,73 @@
# Development protocol
Status: proposed v0.2, revised 13 October 2026. Applies to implementation of the [architecture](../architecture/ARCHITECTURE.md). Product requirements remain in the [PRD](../PRD.md). Owner-required modular development is specified in the [module design and replacement protocol](MODULARITY_PROTOCOL.md).
## Work from a bounded contract
Before editing, inspect applicable project instructions, current files and Git status. Preserve unrelated edits. Identify the user-visible result, affected requirement IDs, authority/data boundary, failure behavior and evidence needed to call the slice complete. Use a short task note for ordinary work; reserve an ADR for a durable architectural change. Do not require a new approval cycle for each reversible implementation step already authorized by the user.
Implement one vertical behavior at a time. For example: a source with a wrong-page quote is rejected with a locator finding; an exact retry returns the same outcome; a reader sees the accepted note only after valid submission. Avoid scaffolding the entire roadmap before the first complete flow exists.
Every implementation task names its owning module, public boundary and affected consumers. Design replacement paths as part of the module, including its state/schema compatibility. A folder split alone does not satisfy modularity. Consumers must depend on public contracts and remain independent of a module's storage layout, provider SDK or private helper functions.
## Code ownership rules
| Area | Required behavior |
| --- | --- |
| Domain | Own invariants and typed contracts; pure validation where practical. No transport, filesystem or model calls. |
| Application | Own use-case order, explicit scope, authorization checks, transaction/publication decisions and recovery. |
| Adapters | Own Git/files/SQLite/parsers/auth mechanics behind bounded interfaces. Never quietly decide policy. |
| HTTP/MCP | Validate inputs and map outputs/errors; expose only operations in the allowlisted catalog. No duplicate business rules. |
| Frontend | Read API data, route state and render evidence. No canonical mutation route or hidden browser proposal client. |
| Local skills | Reason and propose using public contracts. No direct canonical edits, SQL tools or assumed human authority. |
| Local agent runtime | Own bounded pipeline execution, model/tool dispatch and resumable client checkpoints. Use the service through public MCP contracts; never import its persistence or owner-credential internals. |
The operation catalog declares name/version, request/response schemas, handler, capabilities, permitted transports, idempotency semantics and limits. Test the generated route/tool surfaces, including forbidden exposure. An MCP `readOnlyHint` is documentation, not enforcement.
Use strict typing at new boundaries. Narrow exceptions to actionable domain errors; unexpected failures retain correlation IDs and private traces. Do not return success after a failed required write or check. Use parameterized SQL and subprocess argument arrays. Never interpolate source text, filenames or PR prose into shell commands.
Offload blocking work at one clear boundary. Bound queues and parser/model processes. Do not hold SQLite transactions or the Git writer while waiting for external calls. The durable publication sequence in the acceptance contract takes precedence over a convenient framework background-task helper.
## Frontend engineering
Keep scope, search query, filters and selected node/revision in the URL. Browser back/forward and shared links must restore the intended reading view. Query keys include resolved/requested scope, filters, node/revision and API version as appropriate. Clear private caches on logout or identity changes.
Cancel obsolete requests or ignore their results, including obsolete loading and error states. Query polling exists only for a visible need and cannot overlap indefinitely. Avoid a global real-time event system before the product requires it.
Fetch through the typed API layer. Components receive enough data to render complete states: loading, empty, unavailable, forbidden, stale, index-lagged and successful. A valid empty search is different from a failed request. Profile before adding broad memoization or custom comparison functions. Sanitize Markdown rendering and scope reading typography so source headings cannot restyle navigation.
## Verification proportional to the change
| Change | Minimum evidence |
| --- | --- |
| Documentation | Relative-link and consistency checks; no claim of runtime acceptance. |
| Pure domain rule | Focused tests with valid, invalid and boundary cases. |
| Scope/auth/catalog | Negative capability tests through actual HTTP and MCP adapters. |
| Files/Git/proposals | Isolated temporary repositories; replay, conflict and crash/restart tests. |
| Parsing | Labeled sources with exact location maps and failure states; successful conversion alone is insufficient. |
| Index/retrieval | Rebuild integrity, explicit scope, ranking/latency fixtures and model-change behavior. |
| UI | Type/lint/component checks plus browser reading flow, keyboard, narrow layout and screenshot inspection. |
| Connector/configuration | Preserve unrelated entries, rollback owned changes, and perform the native client workflow. |
| Module addition/replacement | Public contract tests, dependency/import-boundary checks, consumer integration and an explicit state migration/rollback where applicable. |
| Agent skill/pipeline | Typed stage fixtures, version pinning, budget/cancellation behavior and resume after an uncertain MCP result; semantic quality uses labeled source examples. |
| Deployment | Authenticated source-to-reading path on that deployment and a separate restore exercise. |
Use isolated fixtures, fixed clocks and explicit data roots. No unit test reaches live providers or production state. Never overlap tests sharing a mutable SQLite database. Regression tests should demonstrate the failure mechanism, not repeat implementation branches. Cosmetic documentation/UI edits do not justify an invented test suite.
Scaffolding must supply scripts for Ruff check/format, mypy, pytest, TypeScript, ESLint, unit tests and browser tests. Until those scripts exist, do not publish fictional command transcripts. Run focused checks during development, then the affected integration/release gates. Repeat only for changed code, failures or unresolved uncertainty.
Acceptance receipts record revision and dirty-tree baseline, runtime/OS versions, configuration without secrets, exact commands and outputs, fixtures, observed behavior and remaining limitations. Results are PASS, FAIL, BLOCKED, NOT RUN or UNSUPPORTED. User-reported and directly observed results are labeled separately.
## Documentation and change management
Use `docs/decisions/ADR-NNN-short-title.md` for choices that change a public contract, trust boundary, persistence model, deployment topology or dependency family. Include status/date, context, decision, strongest alternative, consequences, migration/rollback and acceptance evidence. Routine implementation details stay with their module or task.
Keep one owner document per rule. Link from the handbook and later from a concise root `AGENTS.md`; thin harness pointers can refer to that file. Do not duplicate rules across CLAUDE/GEMINI/OpenCode copies. Reference project protocols inform decisions but never silently become GEWU instructions.
Write the result and reason first. Distinguish proposed, implemented, tested locally and verified in deployment. Use relative repository links, stable requirement IDs and specific dates. State failures and uncertainty directly. Do not borrow a reference project's metaphors as architecture terminology or present an agent's confidence as measured quality.
Before committing, inspect the exact diff and selectively stage the coherent slice. Commit only when authorized; never stage unrelated work or reset the user's tree. Report local commit, push, deployment and runtime evidence as separate outcomes. Git commits made by the knowledge service follow the stricter acceptance contract and cannot use blanket staging.
## Completion gate
A slice is complete when its behavior and failure cases are implemented, required checks pass, changed contracts/docs are current, and required deployment/client evidence exists. Its module boundary and replacement obligations must also pass the modularity protocol. A blocked client or unrun recovery gate remains visible. Passing unit tests cannot close an untested end-to-end requirement.
docs/development/MODULARITY_PROTOCOL.md
+66
View File
@@ -0,0 +1,66 @@
# Module design and replacement protocol
13 October 2026. Requirement confirmed by the owner: all development must be modular so each module can be updated or replaced by a better implementation. This protocol applies to the service, local agent, skills, pipelines, connector and frontend. It makes replacement an acceptance criterion.
## Default structure
Use a modular monolith for the service and a separate local-agent application. A module is a coherent responsibility with a public contract, private implementation and declared dependencies. It does not need its own process, repository or package release. Split deployment only when isolation, scaling or independent release needs justify it.
Every feature belongs to a named module. Consumers use its public interface; they cannot import private helpers, inspect its tables, edit its files or rely on provider-specific response objects. Cross-module payloads use GEWU-owned types. The composition root selects implementations and manages their lifetimes. Domain/application code cannot select a concrete implementation through scattered conditionals.
Internal pure helpers may remain functions. Add an interface at a real replaceable boundary, not around every function. Keep stable interfaces small enough that a replacement does not have to emulate unrelated features.
## Required module description
Each replaceable module has a short description beside its implementation, plus a machine-readable descriptor when configuration selects it. The description declares responsibility, public input/output types, errors, owned state, side effects, dependencies, lifecycle and resource limits. The descriptor declares `module_id`, implementation version, provided contract/version, required capabilities, compatible state-schema versions and configuration schema. Resolve exact implementation versions and artifact hashes in the release/run manifest.
Compatibility is behavioral: valid inputs, errors, cancellation, ordering, idempotency and security limits all belong to the contract. Matching method names or a version range alone is insufficient. [Python Protocols](https://docs.python.org/3.12/library/typing.html#typing.Protocol) and TypeScript interfaces describe structure; runtime validators and contract tests enforce exchanged data and behavior.
## Initial replacement boundaries
| Module boundary | Public contract owns | Private implementation / replacement example |
| --- | --- | --- |
| Service application use cases | Scope, authorization order, proposal/read outcomes | Reorganize orchestration without changing HTTP/MCP behavior. |
| Acceptance validators and policy evaluator | Required checks, typed findings, policy/authority bindings | Improve implementation while retaining mandatory evidence and authority invariants. No configurable bypass of those checks. |
| Canonical repository and publication | Committed reads, expected-head publication, manifests, reconciliation | Git implementation may change behind the port; abandoning Git authority requires an explicit architecture/product change. |
| Artifact and workflow stores | Immutable hashes, atomic records, resumable upload/run operations | Local filesystem storage can later gain an object-storage adapter. |
| Source parsers | Immutable extraction artifact and supported locator profile | Replace a PDF parser; keep old extraction artifacts and citations resolvable. |
| Embedding provider | Normalized vectors plus model/profile metadata | Replace model/runtime; rebuild a separate vector generation. |
| Search and ranking | Scoped candidates, scores/explanations, revision and budget rules | Replace FTS/vector engine or ranking algorithm without modifying readers. |
| Identity and credentials | Authenticated principal, capabilities, grants and revocation | Replace login backend without changing proposal authorization semantics. |
| MCP and HTTP adapters | Versioned wire schemas and domain-error mapping | Update transport SDK without moving rules into routes. |
| Agent model provider | Typed requests/results, usage, timeouts and declared capabilities | Change local/hosted provider without exposing SDK types to skills. |
| Agent pipeline runner | Stage dispatch, bounded scheduling, checkpoints and outcomes | Replace orchestration library while preserving stage contracts and resume semantics. |
| Skills and stage handlers | Declared inputs/outputs, tools, prompt/content versions and budget | Replace an extraction or assessment skill without rewriting the pipeline. |
| Harness adapter | Profile/skill discovery and authenticated public tool access | Change a host's configuration format without duplicating the skill pack. |
| Frontend feature modules | Route/data contract, component props, events and accessibility behavior | Replace an evidence viewer or result list while preserving API and navigation. |
| Design system | Semantic tokens and shared interaction primitives | Revise typography/theme centrally without recoloring feature implementations. |
## Versioning and dependency rules
Public contracts, implementation versions, persisted schemas and model/prompt artifacts have distinct identifiers. Use [semantic versioning](https://semver.org/) for declared stable contracts: compatible additions are minor, fixes are patch, breaking behavior is major. Before 1.0, explicitly list supported contract versions; do not assume every `0.x` update is compatible. Published immutable artifacts are never changed in place.
Backend boundaries use typed ports with injected dependencies; the frontend imports feature public exports and shared primitives. Shared contract packages stay small and have no dependency on providers, storage engines or UI frameworks. Reject import cycles and cross-feature private imports in CI. The local agent cannot import service storage/auth internals; its GEWU access is through the public MCP client contract.
Configuration selects from installed, reviewed implementations by ID. Validate configuration and capability compatibility before activation. Do not discover executable modules from uploaded sources, skill text, arbitrary import strings or URL-supplied code. Python package entry points are a possible future distribution mechanism, not permission to auto-load third-party code; [the packaging guide](https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/) describes discovery mechanisms, not trust enforcement.
Existing deployments use lockfiles and a release manifest. Agent runs additionally pin pipeline, stage, skill, provider and model versions at start. No automatic hot swap in a running acceptance transaction or reasoning stage. A newly selected implementation applies at a controlled deployment/run boundary.
## Replacement workflow
1. Identify the public contract and current behavioral fixtures. Add missing fixtures for the changed boundary before declaring equivalence.
2. Implement the replacement behind the same port. Compare old/new behavior on representative data; compare retrieval quality, evidence fidelity or performance where the module affects them. A fake adapter proves dependency isolation only, not production equivalence.
3. Run shared contract tests, consumer integration tests and import-boundary checks. Test required failure states, cancellation and denied capabilities, not only successful outputs.
4. Migrate state explicitly or build a new derived generation. Record schema compatibility, migration checks and rollback path. Retain old source/extraction versions and accepted receipts.
5. Activate through the composition root/configuration in a test deployment, then complete the affected native client/browser/recovery gates. A compatible swap should require no changes to consumers' business logic.
6. Roll back by selecting the previous implementation only if it can read the resulting state. Otherwise use the tested state migration/restore procedure. Never claim that changing a version number reverses a destructive migration.
A breaking contract change needs an ADR, explicit consumer migration, version negotiation where relevant, and a declared deprecation window. Replaceability does not imply every future technology will fit today's contract; preserve the product invariants and document the actual compatibility cost.
## Required evidence
At scaffolding, add import/dependency checks and reusable contract test suites for the first real boundaries. Each new module must demonstrate isolated testing with collaborators substituted through public ports. Each replacement must demonstrate a swap without unrelated module edits, or declare the contract migration that makes those edits necessary.
Early acceptance examples: swap an embedding provider and rebuild without changing search consumers; substitute an extraction-stage implementation while preserving old citations; replace a frontend evidence panel without changing the read API; resume an agent run with its original pinned skill version after a newer version is installed. These are required design tests to implement, not existing passes.
Primary documentation above was checked on 13 October 2026. No module implementation or replacement test exists yet.
docs/development/OPERATIONS_PROTOCOL.md
+43
View File
@@ -0,0 +1,43 @@
# Operations and recovery protocol
Status: proposed v0.1, 12 October 2026. Applies to local and VPS installations of the [architecture](../architecture/ARCHITECTURE.md).
## Installation identity and health
Each installation has a stable service ID, environment label and one authoritative knowledge ref. Diagnostics report software/schema versions, canonical head, indexed revision, index lag, pending queue count/age, parser availability, model/index profile and configured limits. Return only the caller's permitted identity/capability details. Public liveness must not reveal private project names or configuration.
Readiness requires complete startup recovery and available canonical/control stores. An unavailable index may permit explicitly degraded reads but prevents reporting full retrieval readiness. A writer-lock conflict prevents a second instance from accepting writes. Deployment scripts must fail visibly rather than start a competing writer.
Use structured, bounded logs with request, run, proposal and safe credential identifiers. Redact before persistence. Never log source bodies, full tool payloads, passwords or authorization headers by default. Record safe error codes and private stack traces with retention limits. Durable acceptance/security audit records have separate retention and backup requirements from disposable diagnostics.
## Backups
Back up a consistent set: knowledge Git repository, artifact/extraction tree, staging/run/receipt tree, private control database, schema versions and required configuration. Keep recovery credentials/encryption keys in a separate protected recovery location. The derived index is optional backup material. A Git remote alone is not an artifact or account backup.
For the first implementation, use a short write-quiescence window: stop new acceptances/uploads/control mutations, drain active publications, checkpoint durable file state, take a supported SQLite backup of the control database, snapshot/copy the matching filesystem set, then resume writes. Record the authoritative Git head and inventory hashes. Do not copy a live SQLite main file while ignoring its WAL.
Encrypt off-host backups and restrict credentials. Proposed starting schedule is daily plus before migration, but owner-selected retention, recovery-point objective and recovery-time objective are prerequisites to team launch. Do not label these values agreed or declare recovery adequate without a measured restore.
Restore into a new isolated directory/host. Verify artifact/extraction hashes, canonical manifests, identity/grants and proposal states, reconcile receipts, rebuild the index and exercise cited reads and a disposable acceptance. Prevent the restored clone from writing as a second authority. After a real rollback, invalidate sessions and reissue/reconcile credentials and revocations before networking is enabled; restoring an older control database must not revive revoked access.
## Schema and model migrations
Version public contracts, canonical records and index schemas separately. A migration declares supported source/target versions, backup prerequisites, dry-run findings, transformed records and rollback limits. Use the same validators as ordinary writes. Canonical migrations create attributable service-maintenance commits; they cannot fabricate knowledge or bypass protected content decisions.
Test migration on a restored copy first. Old readers must reject unsupported schemas explicitly. Rebuild derived indexes into new generations. Keep the previous generation until the new one passes integrity/retrieval checks and old connections drain. An embedding model update cannot mix vector dimensions or silently erase citations to old source extractions.
Rollback of knowledge uses a corrective/superseding proposal or documented maintenance recovery, preserving history. Never solve an application bug by silently rewriting accepted Git history. Software rollback must remain compatible with the resulting schema, or restore the complete consistent snapshot under a stopped service.
## VPS transfer and release
Freeze local writes, record the final head, transfer and verify all authoritative stores, restore the service under a restricted account, then run its local health/recovery checks. Test HTTPS, cookie/key boundaries and MCP transfer from an actual client. Switch client endpoint configuration after the VPS is ready. The old local service stays read-only/offline until deliberately made authoritative again through a controlled handback.
The web and MCP routes share domain logic but retain different capabilities. Built UI assets may be served by the Python app behind Caddy. Private data mounts are never exposed as a static directory. Parser processes have restricted mounts; the public service runs without host-admin privileges. Record container/image digests and exact lockfiles used for the release.
Release evidence separates local checks, pushed revision, deployed revision, authenticated runtime behavior and restore verification. No deployment command or backup schedule has been executed as part of this design exercise.
## Capacity and incident handling
Before team release, name benchmark hardware, model, corpus, archive sizes, concurrent users/agents, queue limits and query budget distribution. Measure latency percentiles, top-five source recall, cold/warm index rebuild, parse time, memory and disk growth. PRD targets remain search under 300 ms at 10,000 project nodes, 100,000 total nodes and rebuild under ten minutes; define the measurement setup before running it. Saturation returns a retryable bounded outcome rather than unlimited queuing.
For an incident, inspect persisted production history and the actual affected endpoint/state before proposing causes. Separate observed facts from likely causes and untested hypotheses. Preserve the failed record, isolate a reproducer, repair the boundary and add a regression fixture when justified. Never infer deployed state from a local checkout or hide invalid evidence behind a successful request status.
docs/development/VISUAL_DESIGN_PROTOCOL.md
+84
View File
@@ -0,0 +1,84 @@
# Visual design protocol
Direction: editorial research workspace, selected by the owner on 12 October 2026. Status: proposed implementation specification v0.1. Exact colors, typefaces and geometry require a rendered review.
## Artistic and functional premise
The interface should feel like working with a well-edited research folio: a warm page, strong titles, legible annotations and precise references. Its central visual relationship is between an assertion and the evidence beside it. Project context stays visible while the reader moves between a problem, an approach and its source.
Use the editorial/technical typography contrast from Sonification, adapted for sustained reading. Large titles can carry character. Operational labels remain quiet and readable. Space and thin rules organize the page; dense technical metadata appears when it helps the reader assess origin, freshness or a relationship.
The website searches, navigates and displays knowledge. It has no capture, edit, approve, merge or generate controls. Account sign-in and view preferences do not change that knowledge boundary.
## Information architecture
Primary destinations are Search, Problems & topics, Sources and Stale knowledge, within an explicit project or all-projects scope. A project landing view shows its owner-defined purpose and key questions before recent records. Avoid a dashboard of counts without a reading task.
The core journey is: choose scope -> find a problem or note -> inspect applicable approaches and their conditions -> open the supporting quote -> inspect the source revision. History and typed neighbors are available without taking over the reading surface. Accepted relationships and similarity suggestions occupy separately labeled sections.
Desktop uses a modest navigation rail, a flexible reading/results area and an optional evidence panel. Target a 224 px rail and a 360–440 px evidence panel where space permits; the reading column has a maximum measure of about 68 characters. At insufficient width, evidence becomes a route or drawer and navigation collapses. Do not force three columns into a narrow viewport or hide primary reading content to preserve panel dimensions.
At 390 px, use one natural document flow. Search filters open on demand; citation links navigate to a focused evidence view with an obvious return path. At 200% zoom, preserve content and function. Long IDs/URLs wrap or offer a labeled copy action. Data tables may have a local horizontal scroll region with headers; the page itself must not overflow.
## Proposed visual tokens
Light theme is the initial acceptance target. A dark theme is a later token variant requiring its own contrast and screenshot checks, not a color inversion.
| Token | Proposed value | Role |
| --- | --- | --- |
| `surface.canvas` | `#F4F1EA` | Warm page background. |
| `surface.paper` | `#FFFDF8` | Reading/evidence surface. |
| `surface.subtle` | `#EAE5DA` | Quiet grouping and selected rows. |
| `text.primary` | `#242722` | Main reading text. |
| `text.secondary` | `#596057` | Secondary content, still readable. |
| `border.subtle` | `#D6D0C3` | Decorative separators only. |
| `border.control` | `#777C71` | Control boundaries where required for recognition. |
| `accent.link` | `#315D50` | Links, focus and active scope. |
| `status.caution` | `#85520B` | Stale or incomplete context, always labeled. |
| `status.error` | `#A1342B` | Failed/unavailable states, always labeled. |
These are candidate foreground/background pairs. Verify their actual rendered use; a palette list is not accessibility proof. Never lower text opacity to suggest age. Superseded content retains reading contrast and a clear status label.
Use semantic CSS properties once in the token layer; components cannot invent hex colors, spacing scales or animation durations. Spacing scale: 4, 8, 12, 16, 24, 32, 48 and 64 px. Typical radii: 2–6 px. Use shadows for overlays only. Thin rules and typography establish ordinary hierarchy.
Proposed fonts: Source Serif 4 for editorial titles and long-form reading; Source Sans 3 for navigation, search results and controls; JetBrains Mono for IDs, code and compact technical values. Self-host licensed assets with local fallbacks and `font-display: swap`. Verify Cyrillic and any required CJK fallback coverage with the actual source corpus. Font choice must not create a network dependency for local/offline reading.
Reading text begins at 17–18 px with roughly 1.6 line-height. Controls and result descriptions use 16 px; secondary metadata uses at least 14 px. Use sentence case. Small uppercase may identify a short section, but must never carry the main content or hide warnings. Dates/numeric tables use tabular figures.
## Component contracts
| Component | Must communicate | Interaction/state requirement |
| --- | --- | --- |
| Scope selector | Current project, included shared/cross-project scope | Changing scope updates URL and query; hidden exclusions are disclosed. |
| Search result | Title, concise assertion/summary, origin, relevant dates and evidence availability | Full title is a link; keyboard focus visible; stale warning survives truncation. |
| Reading header | Node type/title, project, lifecycle and dates | Keep revision/history discoverable without showing raw schema jargon by default. |
| Evidence block | Exact quote, source title, location, captured revision and availability | Opens the cited revision/location; explains when preview is unavailable; original/download remain permission-checked. |
| Support details | Location check, semantic assessment, source reliability and assessor | Separate labels; never collapse into a green “verified” badge. |
| Relationship row | Typed verb, target, conditions and support/rationale | Distinguish accepted link from related suggestion; omit out-of-scope target content with an explanation. |
| Freshness notice | As-of date and why stale/unknown | Text plus icon; no color-only indication. |
| History | Previous revision, actor category, date and reason | Reading old material visibly retains its revision context. |
| System state | Loading, empty, failed, forbidden, offline or index behind | Give the correct next action; do not label request failures as “No results.” |
Source quotations must look like quotations. Interpretation text must be labeled as interpretation and retain its supporting references. A model's confidence is not a truth probability; expose its meaning in details rather than presenting a spurious percentage meter.
Use a small application-owned component catalog: AppShell, ScopeSelector, SearchField, FilterBar, ResultRow, ReadingHeader, EvidenceBlock, SourceLocator, RelationshipRow, FreshnessNotice and StateMessage. Build each with fixtures for long titles, missing metadata and failure states before composing large pages.
## Motion, accessibility and content safety
Frequent search, selection and keyboard navigation should respond immediately. Optional disclosure transitions are brief, typically 120–180 ms, and respect reduced-motion preferences. No animated text entrance, CRT fringing, pulsing telemetry, scanlines or decorative graph animation in the reading surface.
Use semantic HTML, logical headings, landmarks and a skip link. All interactions work by keyboard. Dialogs trap focus and restore it on close; non-modal panels do not trap focus. Announce asynchronous result counts and errors without moving focus unexpectedly. Copy actions have visible success/failure feedback.
Target WCAG 2.2 AA: normal text contrast at least 4.5:1; large text and meaningful control graphics at least 3:1 where applicable. GEWU's preferred touch target is 44 x 44 CSS px, a product standard stricter than the AA minimum target-size criterion. Do not claim this preference is the universal WCAG minimum. See [W3C's criterion reference](https://www.w3.org/WAI/WCAG22/quickref/), checked 12 October 2026.
Render source Markdown as untrusted content. Disable raw HTML by default, sanitize any supported extensions, and do not execute source scripts or MDX. Source CSS cannot enter the application styles. Code and formulas have bounded rendering and horizontal scrolling where needed. Downloads use controlled, authenticated routes; embedded previews have an explicit sandbox policy.
## Visual acceptance
Before a page is called complete, inspect real renders at 1440 x 900, 1024 x 768 and 390 x 844, plus 200% zoom and a 320 CSS-pixel reflow case. Exercise keyboard-only scope -> search -> node -> quote -> return, and test a screen reader on the primary path. Run axe, then manually check reading order, focus restoration and meaningful labels; an automated score alone cannot establish accessibility.
Use fixtures for: long multilingual titles, missing archive, scanned PDF extraction failure, unsupported claim draft outside accepted results, stale datapoint, superseded node, contradiction, cross-project omission, empty search and index lag. Verify contrast on actual states, including selected/hover/focus/disabled appearances.
Record screenshots with route, fixture, viewport, revision and browser version. Evaluate whether a person finds a cited answer within the PRD's two-minute target. Screenshots prove layout at those dimensions; the reading task measures usefulness. Neither substitutes for the other.
This document specifies direction and review criteria. No rendered GEWU page or accessibility pass exists yet.
docs/reviews/ARCHITECTURE_REFERENCE_REVIEW.md
+43
View File
@@ -0,0 +1,43 @@
# Architecture and protocol reference review
12 October 2026. Scope: current local documents supplied by the owner, compared with GEWU PRD 0.7 and GOAL. This is a document review, not a live acceptance audit of AAA, Jev or Sonification.
## Finding
Borrow explicit contracts, clear module ownership, durable evidence and careful frontend lifecycle management. GEWU's product boundary requires a smaller runtime than AAA and a stronger acceptance boundary than an advisory agent router. Reference rules are evaluated individually; their status labels and imperative wording do not make them GEWU instructions.
## Reference inventory and disposition
Paths below identify the local source material under `D:/01_GIT/`. They are provenance labels, not required cross-repository dependencies. Portable GEWU protocols live in this repository and do not require those files at runtime.
| Reference | Keep or adapt | Do not carry into GEWU |
| --- | --- | --- |
| `AAA/docs/development/practices/SCAFFOLDING_AND_DEVELOPMENT_RULES.md` | Explicit tiers, bounded schemas, central composition/lifecycle, isolated tests and documented gates. | Cognitive ProcessingModule/daemon scaffolding; blanket cascade-delete advice; generic BackgroundTasks for critical acceptance; AAA-specific skill mandates. |
| `AAA/docs/development/practices/BACKEND_BEST_PRACTICES.md` | Short transactions, bounded concurrency, upload/SSRF defenses, structured safe errors, typed new code and private diagnostics. | Copying thread-local connection decorators into async work; per-conversation locking as a substitute for a global canonical writer; assuming threads isolate hostile parsers. |
| `AAA/docs/development/practices/FRONTEND_BEST_PRACTICES.md` | URL state, request/subscription cleanup, demand-driven work and scoped source typography. | Blanket memoization and custom comparison rules; a telemetry pub-sub system before measured need; obsolete clipboard fallback as a universal requirement. |
| `AAA/docs/development/practices/FRONTEND_DESIGN_PRINCIPLES.md` | Consistent shared components, readable list/detail navigation, source sanitization and entity-bound async lifetimes. | Terminal-only typography, tiny 8–10 px labels, hidden chrome rules overriding accessibility, or chat/research authoring workflows. |
| `AAA/docs/development/proposals/locked_page_artwork.md` | A clear artistic premise tied to specific behavior. | The artwork itself: private-content teasers, text dimming, compressed ghosts and animated accumulation do not serve GEWU reading. |
| `AAA/docs/architecture/ARCHITECTURE.md` | Lifespan-owned composition root, route/use-case/storage separation and explicit data flow. | Fifteen-stage reasoning pipeline, dream metabolism, internal model orchestration or raw conversation storage as the domain. |
| `AAA/docs/architecture/DATABASE_SCHEMA.md` | Explicit schema/migration descriptions and qualified verification status. | Its application tables as GEWU's model. Its dated local schema document is not evidence of current production state. |
| `AAA/docs/architecture/BELIEFS_V2_CONTRACT.md` | Separate encounter/assessment/decision records, digest bindings, explicit authority, immutable assessments and structured missing context. | Human adoption of every record. GEWU explicitly requires eligible automatic acceptance. |
| `AAA/docs/architecture/BELIEFS_V2_PLAN.md` | Preserve dissent, scope and revisions; similarity alone cannot establish equivalence or support. | Belief mass, participation/dream mechanics or a new internal reasoning layer. |
| `Jev/.agents/protocols/cross-platform-acceptance-protocol.md` | Per-OS/harness evidence, safe isolated fixtures, explicit result labels and configuration/connection/workflow distinctions. | Treating historical receipts or another client's pass as present compatibility. |
| `Jev/.agents/protocols/documentation-standard-protocol.md` | Progressive detail, one authoritative home per rule, a navigation hub and relative internal links. | Mandatory `cmd /c`/`%CD%` wrappers described as portable; mandatory metaphors, fixed RFC taxonomy or screenshot counts. Commands must name their shell and be tested. |
| `Jev/.agents/protocols/style-protocol.md` | Direct prose, concrete mechanisms, explicit limitations and respect for readers. | Mandatory author impersonation, philosophical slogans or rhetorical devices as engineering rules. |
| `Jev/.agents/protocols/anti-slop-protocol.md` | Remove hype, decorative prose and repetitive document structure while preserving exact constraints. | Word bans that erase useful technical distinctions or measurements. |
| `Jev/.agents/protocols/system-one-balance-protocol.md` | Context-aware follow-ups, proportionate process and avoiding repeated permission requests for authorized routine work. | Fail-open acceptance/security, model-confidence authority, routing thresholds or hook latency targets. Deterministic evidence and authority gates fail closed. |
| `SonificationV2/docs/UI_DESIGN_PROTOCOL.md` | Intentional editorial/technical type roles, curated tokens, coherent component grammar and explicit visual review. | CRT fringing/glow, uppercase operational text, tiny controls, DSP meters and instrumentation symbols unrelated to knowledge reading. |
## Contradictions resolved in the proposal
1. AAA's database is operationally central; GEWU requires Git-backed knowledge and a disposable search index. Durable proposals, receipts, artifacts and auth must therefore be explicitly outside the disposable index.
2. AAA's belief decisions begin with human adoption; GEWU permits routine same-agent support assessments and policy acceptance. Preserve attributable decisions without importing mandatory human review for every note.
3. Jev's workflow guidance favors routine speed and advisory fallback. In GEWU, search can degrade to keyword mode, but missing evidence or authority cannot degrade into successful acceptance.
4. The references optimize for agent telemetry and artistic instrumentation. The owner selected warm editorial reading for GEWU. Preserve rigor in evidence presentation while making content readable at ordinary sizes.
5. Local files support inspectability, but unrestricted agent access conflicts with enforced proposal-only writes. Separate service storage/identity from development and agent execution; report unenforced development mode honestly.
## Resulting documents
The [architecture](../architecture/ARCHITECTURE.md) chooses the proposed stack and runtime boundaries. The [acceptance contract](../architecture/ACCEPTANCE_CONTRACT.md) makes recovery, authority and evidence behavior reviewable. The [development](../development/DEVELOPMENT_PROTOCOL.md), [visual](../development/VISUAL_DESIGN_PROTOCOL.md), [agent/security](../development/AGENT_SECURITY_PROTOCOL.md) and [operations](../development/OPERATIONS_PROTOCOL.md) protocols adapt the useful practices to GEWU.
The existing [implementation-reference review](../LOCAL_AGENT_IMPLEMENTATION_REVIEW.md) remains relevant prior work for Jev/Winnow. Its probes were not rerun here. This review did not inspect or modify production databases or external repositories and does not claim their code implements every statement in their guides.
docs/reviews/ARCHITECTURE_SENIOR_REVIEW.md
+45
View File
@@ -0,0 +1,45 @@
# Architecture review and revision record
13 October 2026. Artifact: proposed GEWU architecture and engineering handbook, originally drafted under the SKB working name. Repository remains `D:/01_GIT/SKB`. This report covers document-level corrections, not implemented security or runtime acceptance.
## Frozen review inputs
An independent, read-only reviewer inspected the initial proposal, the actual docs-only repository, GOAL and PRD. The initial architecture and acceptance-contract digests were verified before review:
| Artifact | SHA-256 of v0.1 |
| --- | --- |
| `docs/architecture/ARCHITECTURE.md` | `353023F13730692C841C6541D4C64BFE6CD206F1D06A17C951638F20FD89083E` |
| `docs/architecture/ACCEPTANCE_CONTRACT.md` | `EA07DEFA57FCB8333CE46E663D13F24FBC636A46D7FA11E3DDA51CFA0EDF5021` |
The review classified the draft as mixed: product scope and most failure boundaries were concrete, but owner authentication, live receipt recovery, API parity and extraction persistence required further decisions. The findings below describe that frozen draft. Linked documents now contain the revised proposal.
## Findings and corrections
| ID / severity | Original gap | Correction in v0.2 |
| --- | --- | --- |
| B1 / blocker before protected-action implementation | Owner MCP authentication had no credential, transport or replay-state contract. Original architecture lines 122–126 and acceptance contract lines 86–95. | [Owner profile](../architecture/ACCEPTANCE_CONTRACT.md#proposed-owner-authentication-profile): controlled HTTPS CLI, separate human reauthentication, short-lived challenge-bound token, owner-only operations, durable decisions and single-use publication binding. This is a custom-client profile with explicit limits. |
| M1 / major | A committed proposal could have no receipt during a live retry; recovery blocked only the same identity. Original acceptance contract lines 47–78. | [Publication/recovery](../architecture/ACCEPTANCE_CONTRACT.md#publication-and-crash-recovery): deterministic committed manifest, publication journal, immutable receipt, separate dynamic index status, status/retry reconciliation before restart and global publication freeze while required reconciliation fails. |
| M2 / major | HTTP reads were drawn/described around browser sessions even though the PRD includes agent HTTP retrieval. Original architecture lines 40–56 and 122. | [Public transport contract](../architecture/ACCEPTANCE_CONTRACT.md#public-transport-contract): agent keys may authenticate read HTTP, which shares MCP scope, budgets, revision/error envelopes and cursor semantics. Proposals/owner decisions remain unavailable through the read API. |
| M3 / major | Extraction blocks/maps and a rebuild watermark were not specified sufficiently to preserve old citations. Original architecture lines 89–106 and acceptance contract lines 105–107. | [Extraction and rebuild](../architecture/ACCEPTANCE_CONTRACT.md#immutable-extraction-format-and-rebuild-procedure): immutable content-addressed block artifacts, code-point maps, exact cited extraction IDs, snapshot head, inventory/profile watermark and isolated generation publication. |
The review preserved the one-writer/CAS topology, manifest-in-commit recovery principle, atomic cross-policy bundles, source/assessment/decision separation, scope rechecks and the editorial visual direction. No evidence warranted adding a graph database, embedded reasoning agent or distributed service architecture.
A bounded independent recheck found B1 and M1–M3 substantively resolved at the design level. It identified one remaining recovery detail: the owner-login seed-encryption key needed its own protected recovery backup. The contract now specifies that backup, restore verification and a disabled-until-re-enrolled fallback when the key is unavailable. Runtime verification remains required.
Primary technical references checked during review: [MCP HTTP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) defines a standards-based OAuth profile; our custom controlled-client profile does not claim that interoperability. [Git update-ref](https://git-scm.com/docs/git-update-ref.html) supports publication conditioned on the expected previous object ID. These sources support mechanisms, not the correctness of an unimplemented service.
## Promoted baseline
The revised [architecture](../architecture/ARCHITECTURE.md) retains Python/FastAPI, React/TypeScript/Vite, private Git-backed canonical records, private source artifacts and derived SQLite retrieval. Engineering protocols remain in [development](../development/DEVELOPMENT_PROTOCOL.md), [visual design](../development/VISUAL_DESIGN_PROTOCOL.md), [agent/security](../development/AGENT_SECURITY_PROTOCOL.md) and [operations](../development/OPERATIONS_PROTOCOL.md).
The changes concentrate detail at four implementation boundaries. They do not settle production auto-acceptance policy, name owners, choose sampling thresholds, supply the evaluation corpus or invent hosting capacity. Those remain explicitly open in the architecture. Exact dependency locks, machine-readable schemas and executable acceptance cases are M0 work.
## Verification scope
Final documentation checks passed across nine files: 38 local links, including four heading anchors, resolved; fenced blocks were balanced and no trailing whitespace was found. `git diff --check` passed, with existing GOAL/PRD line-ending notices. A 76-pattern plain-language scan returned no matches. These are documentation checks, not runtime tests.
The proposed palette was checked numerically against canvas, paper and subtle backgrounds. Text colors had a minimum contrast of 5.17:1; the separate control-boundary color had a minimum of 3.41:1 and is not a text color. These calculations do not establish rendered accessibility, focus behavior or browser layout. No visual page has been implemented or rendered.
Manual prose review preserved technical lists and distinctions rather than removing necessary specification detail.
Existing GOAL/PRD and prior review edits were preserved. Concurrent GEWU naming/intro edits were retained. No commit, dependency installation, source-service implementation, deployment or live harness acceptance is part of this change.
docs/reviews/LOCAL_AGENT_PROBES.json
+58
View File
@@ -0,0 +1,58 @@
{
"date": "2026-10-12",
"scope": "Offline isolated probes; temporary state only; no provider calls, host installs or canonical source writes.",
"python": "3.10.9",
"jev_head": "bca82bb245389dc3ccdcef516878f33b11b71d47",
"jev_tree": "dirty implementation snapshot",
"winnow_head": "d67763617a5c9f16689332737878e4d81b9c9f99",
"checks": [
{
"check": "registry-handler coverage",
"observed": "All 8 declared Jev tools resolve to handlers; not an MCP handshake."
},
{
"check": "missing-reference verification",
"observed": {
"verified": true,
"support_level": "extrapolated"
}
},
{
"check": "knowledge write without evidence",
"observed": "Direct learn succeeded with empty details and no source/quote validation."
},
{
"check": "keyword-only knowledge retrieval",
"observed": {
"confidence": 0.69,
"context_items": 1,
"presentation": "may-apply hint; not ranked multi-result retrieval"
}
},
{
"check": "context budget boundary",
"observed": {
"unit": "characters",
"result": "ASSERTION [c",
"citation_preserved": false
}
},
{
"check": "replay binds operation digest",
"observed": {
"initial": "acquired",
"same_digest": "replay",
"changed_digest": "acquired",
"limit": "single-process SQLite probe, not concurrent git acceptance"
}
},
{
"check": "installer config merge",
"observed": "Unrelated MCP entry, theme and existing skill path preserved in an in-memory fixture; no client configuration changed."
},
{
"check": "PDF page-map preservation",
"observed": "Mocked two-page extractor output is concatenated without page markers or a location map; no real PDF extraction quality was tested."
}
]
}
docs/reviews/PRD_TARGET_READINESS.md
+67
View File
@@ -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.