adamshen1007 · adamshen1007 · Jul 28, 2026 · Jul 28, 2026
diff --git a/ARCHITECTURE_DECISIONS.md b/ARCHITECTURE_DECISIONS.md
@@ -74,6 +74,14 @@ This ledger records repository-level decisions. Feature-level decisions should m
 - **Decision:** Define strict query and result contracts in `@founderos/knowledge-schema` and execute them as a pure operation in `@founderos/knowledge-engine` over a caller-supplied candidate set. Apply exact-match filters and declarative context constraints by intersection, reject invalid or duplicate candidates, sort returned objects by ID, and copy source metadata into each result's provenance record.
 - **Consequences:** Query behavior is auditable, deterministic, and independently testable against the Priority 1 corpus. Callers remain responsible for supplying candidates, context constraints do not confer authorization, project matching is limited to documented object fields, and semantic relevance or ranking requires a future architecture decision.
 
+## ADR-0010: Separate candidate provision from deterministic knowledge access
+
+- **Status:** Accepted
+- **Date:** 2026-07-28
+- **Context:** Milestone 05 requires callers to assemble candidate arrays directly. Future filesystems, databases, and external providers need a stable access boundary, but Milestone 06 excludes durable persistence, external integrations, and retrieval intelligence.
+- **Decision:** Define versioned candidate-source batches and asynchronous repository interfaces in `@founderos/knowledge-schema`. Implement a validated in-memory candidate source and immutable repository snapshot in `@founderos/knowledge-engine`. Candidate sources provide objects and source provenance; repositories revalidate, reject duplicate identities, sort observable results, and supply candidates to the existing query filter through a repository-backed application service.
+- **Consequences:** Query execution no longer needs to know how candidates were obtained, and future providers can implement the same asynchronous contract. The in-memory repository is rebuilt from its sources, carries no durability or update semantics, and deliberately performs no ranking, semantic selection, or authorization.
+
 ## ADR template
 
 ```markdown

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,3 +20,5 @@ All notable changes to FounderOS will be documented here.
 - Path-contained migration CLI and deterministic `migration-report.json` generation.
 - Strict KnowledgeOS query and result contracts with consumer context, exact filters, and source provenance.
 - Deterministic in-memory query execution and Priority 1 corpus evaluation fixtures.
+- Versioned candidate-source and Knowledge Repository contracts.
+- Validated in-memory candidate provider, deterministic repository access, and repository-backed query execution.
diff --git a/DOCUMENTATION_INDEX.md b/DOCUMENTATION_INDEX.md
@@ -72,6 +72,16 @@ The documents below are the official FounderOS v1.0 bootstrap specification, org
 - [Milestone 05 Acceptance Criteria v1.0](./docs/milestones/milestone-05/FounderOS_Milestone_05_Acceptance_Criteria_v1.0.md)
 - [Milestone 05 Codex Execution Prompt v1.0](./docs/milestones/milestone-05/FounderOS_Milestone_05_Codex_Execution_Prompt_v1.0.md)
 
+### Milestone 06 — Knowledge Repository and Candidate Source Foundation
+
+- [Knowledge Repository and Candidate Source Foundation Specification v1.0](./docs/milestones/milestone-06/FounderOS_Milestone_06_Knowledge_Repository_and_Candidate_Source_Foundation_Specification_v1.0.md)
+- [Knowledge Repository Contract v1.0](./docs/milestones/milestone-06/FounderOS_Knowledge_Repository_Contract_v1.0.md)
+- [Candidate Source Contract v1.0](./docs/milestones/milestone-06/FounderOS_Candidate_Source_Contract_v1.0.md)
+- [Knowledge Repository Architecture v1.0](./docs/milestones/milestone-06/FounderOS_Knowledge_Repository_Architecture_v1.0.md)
+- [Milestone 06 Acceptance Criteria v1.0](./docs/milestones/milestone-06/FounderOS_Milestone_06_Acceptance_Criteria_v1.0.md)
+- [Milestone 06 Verification Checklist v1.0](./docs/milestones/milestone-06/FounderOS_Milestone_06_Verification_Checklist_v1.0.md)
+- [Milestone 06 Codex Execution Prompt v1.0](./docs/milestones/milestone-06/FounderOS_Milestone_06_Codex_Execution_Prompt_v1.0.md)
+
 ## Repository governance
 
 - [Architecture decisions](./ARCHITECTURE_DECISIONS.md)

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 FounderOS is an AI-native operating system for founder decision-making, organizational memory, and governed AI-assisted execution. This repository is a documentation-first TypeScript monorepo.
 
-The repository currently provides the governed KnowledgeOS schema, ingestion, migration, and deterministic query foundations. It does **not** implement persistence, semantic retrieval, Hermes, an agent runtime, MCP connectors, or a user interface.
+The repository currently provides the governed KnowledgeOS schema, ingestion, migration, repository access, and deterministic query foundations. It does **not** implement persistence, semantic retrieval, Hermes, an agent runtime, MCP connectors, or a user interface.
 
 ## Architecture at a glance
 
@@ -20,12 +20,12 @@ The official specifications are indexed in [DOCUMENTATION_INDEX.md](./DOCUMENTAT
 
 ## Implemented foundations
 
-- [`@founderos/knowledge-schema`](./packages/knowledge-schema/README.md) provides strict runtime schemas and inferred TypeScript contracts for KnowledgeOS metadata, relationships, the seven official knowledge object categories, queries, and query results.
-- [`@founderos/knowledge-engine`](./services/knowledge-engine/README.md) provides read-only ingestion, manifest-controlled Priority 1 corpus migration, and deterministic in-memory filtering with preserved source provenance.
+- [`@founderos/knowledge-schema`](./packages/knowledge-schema/README.md) provides strict runtime schemas and inferred TypeScript contracts for KnowledgeOS metadata, objects, migration, queries, candidate sources, repositories, and results.
+- [`@founderos/knowledge-engine`](./services/knowledge-engine/README.md) provides read-only ingestion, manifest-controlled Priority 1 corpus migration, validated in-memory repository access, and deterministic filtering with preserved source provenance.
 - [`specs/knowledge-templates`](./specs/knowledge-templates) provides valid Markdown templates for all seven KnowledgeOS object types.
 - [`knowledge/migration-manifest.yaml`](./knowledge/migration-manifest.yaml) binds the eight canonical FounderOS Priority 1 documents to reviewed object identities, logical destinations, metadata, and source hashes.
 
-Vault watching, persistence, semantic retrieval, embeddings, ranking, graph storage, agent behavior, connectors, and interfaces remain unimplemented.
+Vault watching, durable persistence, semantic retrieval, embeddings, ranking, graph storage, agent behavior, connectors, and interfaces remain unimplemented.
 
 ## Repository layout
 

diff --git a/docs/milestones/milestone-06/FounderOS_Candidate_Source_Contract_v1.0.md b/docs/milestones/milestone-06/FounderOS_Candidate_Source_Contract_v1.0.md
@@ -0,0 +1,32 @@
+# FounderOS Candidate Source Contract v1.0
+
+## Purpose
+
+Define how knowledge sources provide candidates to KnowledgeOS.
+
+## Future Sources
+
+-   File system
+-   Database
+-   External APIs
+-   MCP connectors
+
+## Contract
+
+A candidate source provides:
+
+-   Source identity
+-   Available objects
+-   Provenance metadata
+
+## Rules
+
+Candidate sources must not:
+
+-   Modify knowledge objects
+-   Bypass validation
+-   Remove provenance
+
+## Principle
+
+Sources provide candidates; repositories manage access.
diff --git a/docs/milestones/milestone-06/FounderOS_Knowledge_Repository_Architecture_v1.0.md b/docs/milestones/milestone-06/FounderOS_Knowledge_Repository_Architecture_v1.0.md
@@ -0,0 +1,29 @@
+# FounderOS Knowledge Repository Architecture v1.0
+
+## Architecture
+
+    Candidate Sources
+
+    ↓
+
+    Repository Layer
+
+    ↓
+
+    Query Engine
+
+    ↓
+
+    Knowledge Results
+
+## Responsibilities
+
+Candidate Source: Provides validated candidates.
+
+Repository: Provides access abstraction and lookup.
+
+Query Engine: Provides filtering and result generation.
+
+## Principle
+
+Separate knowledge access from knowledge intelligence.
diff --git a/docs/milestones/milestone-06/FounderOS_Knowledge_Repository_Contract_v1.0.md b/docs/milestones/milestone-06/FounderOS_Knowledge_Repository_Contract_v1.0.md
@@ -0,0 +1,38 @@
+# FounderOS Knowledge Repository Contract v1.0
+
+## Purpose
+
+Define the abstraction for accessing Knowledge Objects.
+
+## Responsibilities
+
+The repository provides:
+
+-   Knowledge object retrieval
+-   Object lookup
+-   Candidate discovery
+-   Deterministic access
+
+## Contract
+
+Example:
+
+``` typescript
+interface KnowledgeRepository {
+  find(query): KnowledgeObject[];
+  getById(id): KnowledgeObject | null;
+}
+```
+
+## Requirements
+
+Repository implementations must:
+
+-   Preserve identity
+-   Preserve provenance
+-   Return validated objects
+-   Maintain deterministic behavior
+
+## Principle
+
+Repository provides access, not intelligence.
diff --git a/docs/milestones/milestone-06/FounderOS_Milestone_06_Acceptance_Criteria_v1.0.md b/docs/milestones/milestone-06/FounderOS_Milestone_06_Acceptance_Criteria_v1.0.md
@@ -0,0 +1,31 @@
+# FounderOS Milestone 06 Acceptance Criteria v1.0
+
+## Functional Criteria
+
+-   [ ] Repository contract implemented.
+-   [ ] Candidate source contract implemented.
+-   [ ] Query engine consumes repository candidates.
+-   [ ] Provenance preserved.
+-   [ ] Deterministic behavior maintained.
+
+## Quality Criteria
+
+-   [ ] Milestone 05 tests remain passing.
+-   [ ] Repository tests added.
+-   [ ] Package boundaries preserved.
+
+## Non Goals
+
+Not included:
+
+-   Database
+-   Embeddings
+-   Vector search
+-   Ranking
+-   Agents
+-   MCP
+
+## Definition of Done
+
+KnowledgeOS has a stable access boundary between sources and query
+execution.
diff --git a/docs/milestones/milestone-06/FounderOS_Milestone_06_Codex_Execution_Prompt_v1.0.md b/docs/milestones/milestone-06/FounderOS_Milestone_06_Codex_Execution_Prompt_v1.0.md
@@ -0,0 +1,72 @@
+You are the lead engineer implementing FounderOS Milestone 06 ---
+Knowledge Repository and Candidate Source Foundation.
+
+Before making changes, read:
+
+-   README.md
+-   AGENTS.md
+-   CONTRIBUTING.md
+-   ARCHITECTURE_DECISIONS.md
+-   Repository audit
+-   Milestone 04 documents
+-   Milestone 05 documents
+-   Milestone 06 documents
+
+Review:
+
+-   packages/knowledge-schema/
+-   services/knowledge-engine/
+
+Understand existing contracts, query flow, tests, and package
+boundaries.
+
+Objective:
+
+Move KnowledgeOS from caller-supplied candidates to repository-supplied
+candidates.
+
+Implement:
+
+1.  Knowledge Repository Contract
+2.  Candidate Source Contract
+3.  Repository-backed query flow
+4.  Tests for retrieval, provenance, determinism, and regression
+
+Do not implement:
+
+-   Database persistence
+-   Vector database
+-   Embeddings
+-   Semantic search
+-   Ranking
+-   Knowledge graph
+-   Agents
+-   Hermes
+-   MCP
+-   UI
+
+Follow:
+
+-   Documentation first
+-   Architecture before code
+-   Preserve package boundaries
+-   Add tests
+-   Avoid unnecessary dependencies
+
+Run:
+
+pnpm format:check pnpm lint pnpm build pnpm typecheck pnpm test
+
+Final report:
+
+1.  Status GO or NOT READY
+2.  Summary
+3.  Changed files
+4.  Tests
+5.  Verification
+6.  Architecture impact
+7.  Limitations
+8.  Next milestone recommendation
+
+Build a stable knowledge access foundation before adding intelligence
+layers.
diff --git a/...e_06_Knowledge_Repository_and_Candidate_Source_Foundation_Specification_v1.0.md b/...e_06_Knowledge_Repository_and_Candidate_Source_Foundation_Specification_v1.0.md
@@ -0,0 +1,44 @@
+# FounderOS Milestone 06 Knowledge Repository and Candidate Source Foundation Specification v1.0
+
+## Purpose
+
+Define the repository abstraction layer that provides KnowledgeOS query
+capabilities with managed knowledge sources.
+
+## Objective
+
+Move from Milestone 05 caller-supplied candidates to a controlled
+Knowledge Repository foundation.
+
+Current:
+
+Caller -\> Query Engine -\> Knowledge Objects
+
+Target:
+
+Knowledge Repository -\> Candidate Source -\> Query Engine -\> Knowledge
+Results
+
+## Scope
+
+Included:
+
+-   Knowledge repository contract
+-   Candidate source contract
+-   Repository query integration
+-   Deterministic evaluation
+
+Excluded:
+
+-   Database persistence
+-   Vector databases
+-   Embeddings
+-   Semantic search
+-   Ranking systems
+-   Knowledge graph
+-   Agents
+-   MCP integrations
+
+## Principle
+
+Separate knowledge access from knowledge intelligence.
diff --git a/docs/milestones/milestone-06/FounderOS_Milestone_06_Verification_Checklist_v1.0.md b/docs/milestones/milestone-06/FounderOS_Milestone_06_Verification_Checklist_v1.0.md
@@ -0,0 +1,29 @@
+# FounderOS Milestone 06 Verification Checklist v1.0
+
+## Architecture
+
+-   [ ] Repository boundary exists.
+-   [ ] Query engine remains storage-independent.
+-   [ ] Candidate sources are replaceable.
+
+## Functional
+
+-   [ ] Objects retrieved through repository.
+-   [ ] Query filtering works.
+-   [ ] Provenance preserved.
+
+## Regression
+
+-   [ ] Migration tests pass.
+-   [ ] Query tests pass.
+-   [ ] Repository tests pass.
+
+## Commands
+
+``` bash
+pnpm format:check
+pnpm lint
+pnpm build
+pnpm typecheck
+pnpm test
+```
diff --git a/packages/knowledge-schema/README.md b/packages/knowledge-schema/README.md
@@ -24,6 +24,8 @@ Milestone 04 adds strict migration-manifest contracts for object identity, objec
 
 Milestone 05 adds strict, versioned query and result contracts. Queries carry identity, consumer context, optional context constraints, and exact-match filters for object type, project, lifecycle status, tags, source, domain, and category. Results carry validated objects, matching source provenance, candidate and match counts, and the sorted set of applied constraints. The schema package defines these boundaries but does not execute queries.
 
+Milestone 06 adds candidate-source and repository access contracts. A candidate batch binds a validated source descriptor and its provenance to schema-valid Knowledge Objects. The repository interface supports deterministic candidate listing, identity lookup, multi-identity finding, and source inspection. Provider execution and storage behavior remain outside this package.
+
 ## Usage
 
 ```typescript
@@ -46,4 +48,14 @@ const query = KnowledgeQuerySchema.parse(queryInput);
 const result = KnowledgeQueryResultSchema.parse(resultInput);
 ```
 
+```typescript
+import {
+  KnowledgeCandidateBatchSchema,
+  type KnowledgeCandidateSource,
+  type KnowledgeRepository,
+} from "@founderos/knowledge-schema";
+
+const batch = KnowledgeCandidateBatchSchema.parse(candidateBatchInput);
+```
+
 All schemas reject unknown fields so contract changes remain explicit and versioned.
diff --git a/packages/knowledge-schema/package.json b/packages/knowledge-schema/package.json
@@ -2,7 +2,7 @@
   "name": "@founderos/knowledge-schema",
   "version": "0.1.0",
   "private": true,
-  "description": "KnowledgeOS object, migration, and query contracts",
+  "description": "KnowledgeOS object, migration, query, and repository contracts",
   "type": "module",
   "files": [
     "dist"

diff --git a/packages/knowledge-schema/src/index.ts b/packages/knowledge-schema/src/index.ts
@@ -6,3 +6,4 @@ export * from "./parse.js";
 export * from "./primitives.js";
 export * from "./query.js";
 export * from "./query-result.js";
+export * from "./repository.js";