feat(knowledge-corpus): implement Milestone 07 repository adapter

.gitignore

@@ -6,5 +6,6 @@
 coverage/
 dist/
 node_modules/
+.pnpm-store/
 *.log
 migration-report.json

ARCHITECTURE_DECISIONS.md

@@ -82,6 +82,14 @@ This ledger records repository-level decisions. Feature-level decisions should m
 - **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-0011: Materialize approved corpus access as immutable content-addressed snapshots
+
+- **Status:** Accepted
+- **Date:** 2026-07-28
+- **Context:** Milestone 06 proves repository-backed querying with manually supplied candidates, but future context assembly needs to identify exactly which approved corpus state supplied a result without coupling queries to files or introducing persistence.
+- **Decision:** Implement an engine-owned corpus candidate source that delegates canonical reads, approval gates, path safety, source hashes, and object validation to the Milestone 04 migration workflow. Materialize its accepted objects through the existing in-memory repository and create a schema-validated, deeply immutable snapshot whose identity is derived from corpus version, manifest reference, and deterministic per-object fingerprints. Compare snapshots through a pure, sorted change-set contract.
+- **Consequences:** The Priority 1 corpus can be queried through the existing repository abstraction with traceable, reproducible knowledge-state identity. Creation metadata does not alter content identity. Change detection is observable but inert: durable storage, automatic refresh, watchers, synchronization, retrieval intelligence, and agent integration remain future decisions.
+
 ## ADR template
 
 ```markdown

CHANGELOG.md

@@ -22,3 +22,4 @@ All notable changes to FounderOS will be documented here.
 - 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.
+- Approved-corpus candidate source, immutable repository snapshots, corpus-backed repository initialization, and deterministic change detection.

DOCUMENTATION_INDEX.md

@@ -82,6 +82,16 @@ The documents below are the official FounderOS v1.0 bootstrap specification, org
 - [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)
 
+### Milestone 07 — Knowledge Corpus Repository Adapter
+
+- [Knowledge Corpus Repository Adapter Specification v1.0](./docs/milestones/milestone-07/FounderOS_Milestone_07_Knowledge_Corpus_Repository_Adapter_Specification_v1.0.md)
+- [Knowledge Corpus Candidate Source Contract v1.0](./docs/milestones/milestone-07/FounderOS_Knowledge_Corpus_Candidate_Source_Contract_v1.0.md)
+- [Knowledge Repository Snapshot Specification v1.0](./docs/milestones/milestone-07/FounderOS_Knowledge_Repository_Snapshot_Specification_v1.0.md)
+- [Knowledge Corpus Refresh and Change Detection Specification v1.0](./docs/milestones/milestone-07/FounderOS_Knowledge_Corpus_Refresh_and_Change_Detection_Specification_v1.0.md)
+- [Milestone 07 Acceptance Criteria v1.0](./docs/milestones/milestone-07/FounderOS_Milestone_07_Acceptance_Criteria_v1.0.md)
+- [Milestone 07 Verification Checklist v1.0](./docs/milestones/milestone-07/FounderOS_Milestone_07_Verification_Checklist_v1.0.md)
+- [Milestone 07 Codex Execution Prompt v1.0](./docs/milestones/milestone-07/FounderOS_Milestone_07_Codex_Execution_Prompt_v1.0.md)
+
 ## Repository governance
 
 - [Architecture decisions](./ARCHITECTURE_DECISIONS.md)

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, repository access, 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, corpus-backed repository snapshots, change detection, 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, 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.
+- [`@founderos/knowledge-schema`](./packages/knowledge-schema/README.md) provides strict runtime schemas and inferred TypeScript contracts for KnowledgeOS metadata, objects, migration, queries, candidate sources, repository snapshots, change sets, and results.
+- [`@founderos/knowledge-engine`](./services/knowledge-engine/README.md) provides read-only ingestion, manifest-controlled Priority 1 corpus migration, corpus-backed repository initialization, deterministic snapshots and change comparison, and exact 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, durable persistence, semantic retrieval, embeddings, ranking, graph storage, agent behavior, connectors, and interfaces remain unimplemented.
+Corpus refresh execution, vault watching, durable persistence, semantic retrieval, embeddings, ranking, graph storage, agent behavior, connectors, and interfaces remain unimplemented.
 
 ## Repository layout
 

docs/milestones/milestone-07/FounderOS_Knowledge_Corpus_Candidate_Source_Contract_v1.0.md

@@ -0,0 +1,27 @@
+# FounderOS Knowledge Corpus Candidate Source Contract v1.0
+
+## Purpose
+
+Define the contract for a corpus-backed candidate source.
+
+## Responsibilities
+
+The source provides:
+
+- Knowledge object discovery
+- Corpus metadata
+- Snapshot identity
+- Provenance information
+
+## Requirements
+
+The source must:
+
+- Load approved corpus content
+- Preserve object identity
+- Preserve provenance
+- Maintain deterministic ordering
+
+## Principle
+
+A candidate source provides trusted knowledge candidates, not intelligence.

docs/milestones/milestone-07/FounderOS_Knowledge_Corpus_Refresh_and_Change_Detection_Specification_v1.0.md

@@ -0,0 +1,28 @@
+# FounderOS Knowledge Corpus Refresh and Change Detection Specification v1.0
+
+## Purpose
+
+Define the foundation for detecting controlled knowledge corpus changes.
+
+## Detection Inputs
+
+Compare:
+
+- Source hashes
+- Object identities
+- Metadata changes
+- Corpus version
+
+## Scope
+
+This milestone defines contracts only.
+
+Deferred:
+
+- Automatic synchronization
+- Background refresh
+- Event streaming
+
+## Principle
+
+Knowledge changes must be observable before they become operational.

docs/milestones/milestone-07/FounderOS_Knowledge_Repository_Snapshot_Specification_v1.0.md

@@ -0,0 +1,26 @@
+# FounderOS Knowledge Repository Snapshot Specification v1.0
+
+## Purpose
+
+Define versioned KnowledgeOS repository snapshots.
+
+## Snapshot Contains
+
+- Snapshot ID
+- Corpus version
+- Source manifest
+- Content fingerprint
+- Object count
+- Creation metadata
+
+## Requirements
+
+Snapshots must be:
+
+- Immutable
+- Traceable
+- Deterministic
+
+## Principle
+
+Versioned knowledge enables reliable future AI context.

docs/milestones/milestone-07/FounderOS_Milestone_07_Acceptance_Criteria_v1.0.md

@@ -0,0 +1,29 @@
+# FounderOS Milestone 07 Acceptance Criteria v1.0
+
+## Functional Criteria
+
+- [ ] Corpus candidate source implemented.
+- [ ] Repository initializes from approved corpus.
+- [ ] Snapshot identity generated.
+- [ ] Provenance preserved.
+- [ ] Query behavior remains deterministic.
+
+## Quality Criteria
+
+- [ ] Previous milestone tests remain passing.
+- [ ] Adapter tests added.
+- [ ] Package boundaries preserved.
+
+## Non Goals
+
+Not included:
+
+- Database
+- Embeddings
+- Semantic retrieval
+- Agents
+- MCP
+
+## Definition of Done
+
+KnowledgeOS operates on a controlled corpus-backed repository snapshot.

docs/milestones/milestone-07/FounderOS_Milestone_07_Codex_Execution_Prompt_v1.0.md

@@ -0,0 +1,87 @@
+You are the lead engineer responsible for implementing FounderOS
+Milestone 07 --- Knowledge Corpus Repository Adapter.
+
+Before making changes, read:
+
+-   README.md
+-   AGENTS.md
+-   CONTRIBUTING.md
+-   ARCHITECTURE_DECISIONS.md
+-   Repository audit
+-   Milestone 04 documents
+-   Milestone 05 documents
+-   Milestone 06 documents
+-   Milestone 07 documents
+
+Review:
+
+-   packages/knowledge-schema/
+-   services/knowledge-engine/
+
+Understand:
+
+-   Knowledge Object contracts
+-   Query contracts
+-   Repository contracts
+-   Candidate source boundaries
+
+Objective:
+
+Implement a corpus-backed KnowledgeOS repository adapter.
+
+Move from:
+
+In-memory repository
+
+to:
+
+Approved knowledge corpus source
+
+without introducing persistence or retrieval intelligence.
+
+Implement:
+
+1.  Knowledge Corpus Candidate Source
+2.  Repository snapshot model
+3.  Snapshot identity
+4.  Corpus loading workflow
+5.  Change detection foundation
+6.  Tests
+
+Do not implement:
+
+-   Database
+-   Embeddings
+-   Vector search
+-   Semantic ranking
+-   Knowledge graph
+-   Agents
+-   Hermes
+-   MCP
+-   UI
+
+Follow:
+
+-   Documentation first
+-   Architecture before code
+-   Preserve package boundaries
+-   Add tests
+-   Avoid unnecessary dependencies
+
+Verification:
+
+pnpm format:check pnpm lint pnpm build pnpm typecheck pnpm test
+
+Completion report:
+
+1.  Status GO or NOT READY
+2.  Summary
+3.  Changed files
+4.  Tests
+5.  Verification results
+6.  Architecture impact
+7.  Limitations
+8.  Next milestone recommendation
+
+Build a trusted corpus access layer before adding context assembly and
+agents.

docs/milestones/milestone-07/FounderOS_Milestone_07_Knowledge_Corpus_Repository_Adapter_Specification_v1.0.md

@@ -0,0 +1,53 @@
+# FounderOS Milestone 07 Knowledge Corpus Repository Adapter Specification v1.0
+
+## Purpose
+
+Define the first KnowledgeOS repository adapter connecting the approved FounderOS knowledge corpus to the repository abstraction created in Milestone 06.
+
+## Objective
+
+Move from:
+
+    In-memory Repository
+            |
+            v
+    Query Engine
+
+to:
+
+    Canonical Knowledge Corpus
+            |
+            v
+    Corpus Candidate Source Adapter
+            |
+            v
+    Knowledge Repository
+            |
+            v
+    Query Engine
+
+## Scope
+
+Included:
+
+- Knowledge corpus loading
+- Corpus candidate source adapter
+- Versioned repository snapshot
+- Snapshot identity
+- Refresh detection foundation
+
+Excluded:
+
+- Database persistence
+- Embeddings
+- Vector search
+- Semantic retrieval
+- Ranking
+- Knowledge graph
+- Agents
+- MCP
+- UI
+
+## Principle
+
+The knowledge corpus should become a controlled source of truth before intelligence layers are added.

docs/milestones/milestone-07/FounderOS_Milestone_07_Verification_Checklist_v1.0.md

@@ -0,0 +1,31 @@
+# FounderOS Milestone 07 Verification Checklist v1.0
+
+## Architecture Verification
+
+- [ ] Corpus source uses repository boundary.
+- [ ] Query engine remains storage independent.
+- [ ] Snapshot model is immutable.
+
+## Functional Verification
+
+- [ ] Corpus loads successfully.
+- [ ] Provenance is preserved.
+- [ ] Results remain deterministic.
+
+## Change Detection Verification
+
+- [ ] Snapshot identity is stable.
+- [ ] Source changes are detectable.
+- [ ] Invalid corpus states fail safely.
+
+## Engineering Verification
+
+Run:
+
+```bash
+pnpm format:check
+pnpm lint
+pnpm build
+pnpm typecheck
+pnpm test
+```

packages/knowledge-schema/README.md

@@ -26,6 +26,8 @@ Milestone 05 adds strict, versioned query and result contracts. Queries carry id
 
 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.
 
+Milestone 07 adds strict corpus-source, repository-snapshot, and corpus-change contracts. Snapshots bind a corpus version and manifest reference to deterministic object, metadata, source-hash, and content fingerprints. Change sets report version, identity, source, metadata, and object changes without defining refresh execution or persistence behavior.
+
 ## Usage
 
 ```typescript