feat: materialize FounderOS core knowledge vault

.gitignore

@@ -7,3 +7,4 @@ coverage/
 dist/
 node_modules/
 *.log
+migration-report.json

AGENTS.md

@@ -0,0 +1,83 @@
+# FounderOS AGENTS.md
+
+## Role
+
+You are an AI engineering agent working inside the FounderOS repository.
+
+Your responsibility is to implement approved specifications while
+preserving architecture integrity, documentation consistency, and
+engineering quality.
+
+## Before Coding
+
+Always read and understand:
+
+- README.md
+- Relevant architecture documentation
+- Relevant milestone specifications
+- Existing implementation patterns
+- Current tests
+
+Do not start implementation without understanding repository context.
+
+## Engineering Principles
+
+Follow:
+
+- Documentation first
+- Architecture before code
+- Small verified changes
+- Preserve existing boundaries
+- Prefer simple maintainable solutions
+- Add tests for behavior changes
+
+## Implementation Rules
+
+You should:
+
+- Follow existing package boundaries
+- Maintain TypeScript standards
+- Reuse existing patterns
+- Update documentation when required
+
+You should not:
+
+- Redesign architecture without approval
+- Introduce unnecessary dependencies
+- Modify unrelated modules
+- Ignore specifications
+
+## Verification Requirements
+
+Before completion run:
+
+```bash
+pnpm format:check
+pnpm lint
+pnpm build
+pnpm test
+```
+
+If verification fails:
+
+- Investigate
+- Report clearly
+- Do not claim completion
+
+## Completion Report
+
+Every completed task must include:
+
+1.  Summary
+2.  Changed files
+3.  Tests executed
+4.  Verification results
+5.  Risks or limitations
+6.  Recommended next steps
+
+## Principle
+
+Operate as a senior engineer inside an AI-native engineering
+organization.
+
+Preserve system integrity over short-term implementation speed.

ARCHITECTURE_DECISIONS.md

@@ -58,6 +58,14 @@ This ledger records repository-level decisions. Feature-level decisions should m
 - **Decision:** Recursively ingest regular Markdown files from one explicit directory in stable relative-path order, never follow symbolic links, and return a deterministic aggregate report. Reject every member of duplicate object-ID or source-hash sets so accepted objects have unique identity and source content.
 - **Consequences:** Migration reports are reproducible and safe to review before persistence. Directory ingestion remains an explicit, read-only operation rather than a vault crawler, watcher, scheduler, or storage system.
 
+## ADR-0008: Materialize the core corpus through a reviewed manifest
+
+- **Status:** Accepted
+- **Date:** 2026-07-28
+- **Context:** Milestone 03 proved deterministic directory ingestion with derived fixtures, but the complete Priority 1 corpus needs a controlled contract that detects source drift and preserves human review without modifying or duplicating canonical specifications.
+- **Decision:** Use a strict, versioned YAML manifest to bind each knowledge object ID and type to one canonical source path, logical `knowledge/` destination, expected SHA-256 digest, schema metadata, migration status, and review status. Execute the manifest within one physical repository root, reject traversal and symbolic links, and materialize validated objects only in a deterministic report artifact.
+- **Consequences:** The eight Priority 1 documents become reproducibly auditable without adding persistence or changing canonical Markdown. Manifest hashes must be deliberately updated when approved source documents change, and report content is a normalized schema representation rather than a byte-for-byte source replica.
+
 ## ADR template
 
 ```markdown

CHANGELOG.md

@@ -15,3 +15,6 @@ All notable changes to FounderOS will be documented here.
 - File-level acceptance and rejection reports with deterministic source evidence.
 - Deterministic directory-ingestion reports with duplicate identity and source detection.
 - Canonical templates for all seven knowledge object types and a five-document FounderOS Core migration pilot.
+- Strict migration-manifest schemas with identity, path, hash, metadata, lifecycle, and review validation.
+- Manifest-controlled migration of all eight FounderOS Priority 1 canonical documents.
+- Path-contained migration CLI and deterministic `migration-report.json` generation.

DOCUMENTATION_INDEX.md

@@ -53,8 +53,19 @@ The documents below are the official FounderOS v1.0 bootstrap specification, org
 - [Milestone 02 Vault Ingestion Foundation Specification v1.0](./docs/migration/FounderOS_Milestone_02_Vault_Ingestion_Foundation_Specification_v1.0.md)
 - [Milestone 03 Core Migration Dry Run Specification v1.0](./docs/migration/FounderOS_Milestone_03_Core_Migration_Dry_Run_Specification_v1.0.md)
 
+### Milestone 04 — Core Vault Materialization
+
+- [Core Vault Materialization Specification v1.0](./docs/milestones/milestone-04/FounderOS_Milestone_04_Core_Vault_Materialization_Specification_v1.0.md)
+- [Knowledge Migration Manifest Specification v1.0](./docs/milestones/milestone-04/FounderOS_Knowledge_Migration_Manifest_Specification_v1.0.md)
+- [Knowledge Corpus Structure v1.0](./docs/milestones/milestone-04/FounderOS_Knowledge_Corpus_Structure_v1.0.md)
+- [Knowledge Object Lifecycle Specification v1.0](./docs/milestones/milestone-04/FounderOS_Knowledge_Object_Lifecycle_Specification_v1.0.md)
+- [Milestone 04 Acceptance Criteria v1.0](./docs/milestones/milestone-04/FounderOS_Milestone_04_Acceptance_Criteria_v1.0.md)
+- [Milestone 04 Verification Checklist v1.0](./docs/milestones/milestone-04/FounderOS_Milestone_04_Verification_Checklist_v1.0.md)
+- [Milestone 04 Codex Execution Prompt v1.0](./docs/milestones/milestone-04/FounderOS_Milestone_04_Codex_Execution_Prompt_v1.0.md)
+
 ## Repository governance
 
 - [Architecture decisions](./ARCHITECTURE_DECISIONS.md)
 - [Contribution guide](./CONTRIBUTING.md)
 - [Changelog](./CHANGELOG.md)
+- [Repository Audit v1.0](./docs/reviews/REPOSITORY_AUDIT_v1.0.md)

README.md

@@ -21,8 +21,9 @@ 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, and the seven official knowledge object categories.
-- [`@founderos/knowledge-engine`](./services/knowledge-engine/README.md) provides read-only file and directory ingestion, deterministic migration reports, conflict detection, and source evidence.
+- [`@founderos/knowledge-engine`](./services/knowledge-engine/README.md) provides read-only file and directory ingestion, manifest-controlled Priority 1 corpus migration, deterministic reports, path containment, conflict detection, and source evidence.
 - [`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, retrieval, embeddings, graph storage, agent behavior, connectors, and interfaces remain unimplemented.
 
@@ -55,6 +56,9 @@ pnpm lint
 pnpm typecheck
 pnpm test
 pnpm build
+pnpm knowledge:migrate
 ```
 
+`pnpm knowledge:migrate` validates the approved manifest and writes the deterministic, Git-ignored `migration-report.json` artifact without modifying canonical documents.
+
 See [CONTRIBUTING.md](./CONTRIBUTING.md) before making changes.

docs/milestones/milestone-04/FounderOS_Knowledge_Corpus_Structure_v1.0.md

@@ -0,0 +1,21 @@
+# FounderOS Knowledge Corpus Structure v1.0
+
+## Purpose
+
+Define the long-term KnowledgeOS organization structure.
+
+## Structure
+
+    knowledge/
+
+    ├── governance/
+    ├── architecture/
+    ├── decisions/
+    ├── projects/
+    ├── research/
+    ├── experiments/
+    └── principles/
+
+## Principle
+
+Knowledge organization should reflect organizational intelligence.

docs/milestones/milestone-04/FounderOS_Knowledge_Migration_Manifest_Specification_v1.0.md

@@ -0,0 +1,40 @@
+# FounderOS Knowledge Migration Manifest Specification v1.0
+
+## Purpose
+
+Define the manifest used to control and audit KnowledgeOS migrations.
+
+## Manifest Fields
+
+Each entry should contain:
+
+-   Object ID
+-   Object type
+-   Source path
+-   Destination path
+-   Source hash
+-   Review status
+
+## Example
+
+``` yaml
+documents:
+  - id: founderos-constitution
+    type: principle
+    source: docs/governance/FounderOS_Constitution_v1.0.md
+    status: approved
+```
+
+## Validation Rules
+
+Migration fails when:
+
+-   Source file is missing
+-   IDs conflict
+-   Hash validation fails
+-   Metadata is invalid
+
+## Principle
+
+The migration manifest is the audit contract between human knowledge and
+machine processing.

docs/milestones/milestone-04/FounderOS_Knowledge_Object_Lifecycle_Specification_v1.0.md

@@ -0,0 +1,34 @@
+# FounderOS Knowledge Object Lifecycle Specification v1.0
+
+## Lifecycle
+
+    Draft
+     |
+     v
+    Validated
+     |
+     v
+    Approved
+     |
+     v
+    Indexed
+     |
+     v
+    Retrieved
+     |
+     v
+    Archived
+
+## Rules
+
+Validated objects require:
+
+-   Schema validation
+-   Metadata validation
+-   Provenance checks
+
+Approved objects require human review.
+
+## Principle
+
+Knowledge quality improves through controlled lifecycle management.

docs/milestones/milestone-04/FounderOS_Milestone_04_Acceptance_Criteria_v1.0.md

@@ -0,0 +1,70 @@
+# FounderOS Milestone 04 Acceptance Criteria v1.0
+
+## Purpose
+
+Define the completion criteria for FounderOS Milestone 04 --- Core Vault
+Materialization.
+
+## Functional Acceptance Criteria
+
+The milestone is complete when:
+
+-   [ ] Migration manifest format is implemented.
+-   [ ] Manifest validation is implemented.
+-   [ ] FounderOS Priority 1 knowledge corpus can be migrated.
+-   [ ] Migration workflow produces deterministic reports.
+-   [ ] Migration execution does not modify source documents.
+
+## Migration Criteria
+
+The migration system must verify:
+
+-   [ ] Every document has a unique knowledge object ID.
+-   [ ] Every source document exists.
+-   [ ] Every document type is supported.
+-   [ ] Source hashes can be verified.
+-   [ ] Provenance information is preserved.
+
+## Error Handling Criteria
+
+The system must fail clearly when:
+
+-   [ ] Duplicate object IDs are detected.
+-   [ ] Source documents are missing.
+-   [ ] Metadata validation fails.
+-   [ ] Manifest entries are invalid.
+-   [ ] Source content has changed unexpectedly.
+
+## Engineering Acceptance Criteria
+
+Required:
+
+-   [ ] TypeScript implementation follows existing conventions.
+-   [ ] Existing package boundaries are preserved.
+-   [ ] Tests are added for new behavior.
+-   [ ] Documentation is updated where necessary.
+
+## Verification Requirements
+
+The following commands must pass:
+
+``` bash
+pnpm format:check
+pnpm lint
+pnpm build
+pnpm test
+```
+
+## Definition of Done
+
+Milestone 04 is complete when the KnowledgeOS migration process is:
+
+-   Repeatable
+-   Auditable
+-   Deterministic
+-   Safe for future corpus expansion
+
+## Principle
+
+A knowledge foundation must be trustworthy before it becomes
+intelligent.

docs/milestones/milestone-04/FounderOS_Milestone_04_Codex_Execution_Prompt_v1.0.md

@@ -0,0 +1,66 @@
+# FounderOS Milestone 04 Codex Execution Prompt v1.0
+
+## Role
+
+You are the lead engineer implementing FounderOS Milestone 04.
+
+## Context
+
+FounderOS has completed:
+
+-   Repository foundation
+-   Knowledge schema foundation
+-   Markdown ingestion
+-   Core migration dry run
+
+## Objective
+
+Implement:
+
+-   Migration manifest
+-   Full corpus migration workflow
+-   Deterministic reports
+-   CLI migration interface
+-   Acceptance tests
+
+## Constraints
+
+Do not implement:
+
+-   Database persistence
+-   Embeddings
+-   Retrieval ranking
+-   Knowledge graph
+-   Agents
+-   MCP integrations
+
+## Read First
+
+-   README.md
+-   AGENTS.md
+-   Repository audit
+-   Architecture documentation
+-   Existing knowledge-engine code
+
+## Verification
+
+Run:
+
+-   pnpm format:check
+-   pnpm lint
+-   pnpm build
+-   pnpm test
+
+## Completion Report
+
+Return:
+
+1.  Summary
+2.  Changed files
+3.  Tests executed
+4.  Risks
+5.  Next milestone recommendation
+
+## Principle
+
+Build a reliable knowledge foundation before adding intelligence layers.