adamshen1007 · adamshen1007 · Jul 30, 2026 · Jul 30, 2026
diff --git a/ARCHITECTURE_DECISIONS.md b/ARCHITECTURE_DECISIONS.md
@@ -131,6 +131,14 @@ This ledger records repository-level decisions. Feature-level decisions should m
 - **Decision:** Define strict, versioned, storage-independent Delivery Ledger records in `@founderos/knowledge-schema`, and keep verification, orchestration, canonical fingerprinting, replay, recovery, integrity checking, index rebuilding, and physical persistence in `@founderos/knowledge-engine`. Persist each original Delivery as one complete immutable committed transaction containing the exact verified Milestone 11 Request, Envelope, Acknowledgment, and Receipt plus permanent idempotency ownership. Persist every later Replay Attempt as a separate append-only audit event that references, but never rewrites, the original result. Chain authoritative events by explicit sequence and previous fingerprint. The local adapter stages and flushes a complete event, installs it atomically, then atomically advances a separately fingerprinted commit-head marker; only the marker-bounded prefix is committed. Derived lookups are non-authoritative, bounded, fingerprinted, and deterministically rebuildable. Expired idempotency keys remain permanently reserved in version `1.0`; expiration never erases authoritative evidence.
 - **Consequences:** Exact original results, single-delivery rules, idempotency ownership, replay history, and current validation evidence are recoverable and independently verifiable after restart. A crash before commit-head replacement leaves an ignored staging or uncommitted event; a crash after replacement requires the complete referenced event. The initial adapter assumes a cooperative local administrator, one explicit writer, atomic same-filesystem rename, and file flush support; it does not claim distributed writer safety, hostile privileged-filesystem resistance, network-filesystem consensus, coordinated rollback protection, or multi-region durability. Archival, destructive compaction, databases, distributed persistence, provider execution, authentication, authorization, agents, Hermes, and MCP remain deferred.
 
+## ADR-0017: Invoke reasoning only from an exact durable Delivery transaction
+
+- **Status:** Accepted
+- **Date:** 2026-07-29
+- **Context:** Milestones 10–12 create, deliver, and durably preserve governed Context Packages, but a reasoning executor must not turn those artifacts into an ungoverned provider call or lose the exact Delivery, Receipt, Consumer, Policy, Active Snapshot, and Registry bindings that made the context authoritative.
+- **Decision:** Define strict, versioned, storage-independent Reasoning Invocation, provider-neutral Input and Capability Descriptor, Execution Policy, Attempt, Outcome, Result, Usage, Cost, Failure, Timeout, Cancellation, Consumption, and execution-ledger contracts in `@founderos/knowledge-schema`. `@founderos/knowledge-engine` exposes `invokeGovernedReasoning` as the public execution facade. It accepts only an exact Milestone 12 transaction identity and governed ledgers; recovers and independently verifies the durable Delivery transaction and all governed bindings before matching the verified Invocation against the fixed deterministic fake-provider Capability Descriptor. Provider-neutral character, attempt, and timeout budgets in the verified Execution Policy are authoritative. Invocation idempotency permanently owns one canonical request; retries produce sequential immutable Attempts and Outcomes, while explicit deadline and cancellation evidence control terminal classification. One independently verified Result and finalized Consumption Evidence are atomically committed as append-only execution evidence. No public path accepts raw knowledge, Query Results, unverified Delivery artifacts, hidden context, provider injection, or low-level execution-ledger writes.
+- **Consequences:** Every finalized result has an independently verifiable chain from a committed Delivery through its exact Invocation, selected Capability, complete Attempt history, terminal evidence, Result, and finalized Consumption Evidence; identical finalized invocation replay returns that original result, while conflicting reuse or finalization fails. Milestone 13 instantiates only the deterministic fake provider: it makes no network or credential access and is not a real-provider integration. The local execution-evidence adapter is Git-ignored, cooperative, single-process, and same-filesystem only; its lock can require operator cleanup after a failed process and it provides neither distributed coordination nor hostile privileged-filesystem or coordinated-rollback protection. Automatic abandoned-invocation resume, real providers or provider selection, streaming, tools, Agents, Hermes, MCP, authentication, authorization, semantic retrieval, embeddings, ranking, knowledge graphs, databases, remote persistence, and UI remain deferred.
+
 ## ADR template
 
 ```markdown

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -40,3 +40,9 @@ All notable changes to FounderOS will be documented here.
 - Forty executable deterministic Milestone 11 evaluations plus contract, exact request/policy binding, trusted historical-prefix verification, authoritative artifact verification, freshness, capability, tamper, path and credential privacy, replay-attempt evidence, receipt, immutability, accessor-safety, and bypass tests.
 - Strict storage-independent Durable Context Delivery Ledger, immutable Request registration, permanent idempotency ownership, exact Delivery artifact wrapper, atomic transaction, Replay Attempt, expiration, recovery, integrity, and derived-index contracts.
 - A governed local file-backed Delivery Ledger with a fingerprinted commit-head commit point, single-writer protection, compare-and-swap head and ownership checks, restart recovery, exact original-result replay, current Policy and Freshness evidence, tamper-evident audit chaining, deterministic index rebuilding, crash-fault evaluation, and recursive filesystem-safety enforcement.
+- Milestone 13 provider-neutral Reasoning Invocation contracts for governed Inputs, Capability Descriptors and compatibility, authoritative Execution Policies and character/attempt/timeout budgets, immutable Attempts and Outcomes, Result Envelopes, Usage/Cost/Failure/Timeout/Cancellation Evidence, finalized Consumption Evidence, permanent Invocation ownership, atomic finalization, and storage-independent append-only execution-evidence ledgers.
+- A single governed invocation workflow that verifies one exact durable Milestone 12 Delivery transaction and its Context, Consumer, Policy, Freshness, Active Snapshot, and Registry bindings before deterministic capability matching, fake-provider execution, append-only Attempt evidence, independently verifiable Result construction, and Consumption finalization.
+- The fixed deterministic fake provider, with explicit success, failure, retry, timeout, cancellation, overflow, malformed, contradictory, path-bearing, and credential-bearing evaluation modes; it has no production provider, network, credential, implicit-clock, randomness, Repository, tool, Agent, Hermes, or MCP dependency.
+- A governed local file-backed execution-evidence adapter with expected-head checks, cooperative single-writer locking, fingerprinted atomic commit markers, restart recovery, fail-closed authoritative integrity verification, and non-authoritative rebuildable derived indexes.
+- Sixty-three executable deterministic Milestone 13 evaluation definitions and focused no-provider-bypass, tamper, replay, recovery, capability, lifecycle, and adapter-safety tests. The full verification suite passes 719 tests in 37 files.
+- Milestone 13 explicitly excludes real providers and provider selection, credentials, streaming, tools, Agents, Hermes, MCP, authentication, authorization, semantic retrieval, embeddings, ranking, knowledge graphs, databases, distributed or remote persistence, automatic abandoned-invocation resume, and UI.
diff --git a/DOCUMENTATION_INDEX.md b/DOCUMENTATION_INDEX.md
@@ -168,6 +168,29 @@ The documents below are the official FounderOS v1.0 bootstrap specification, org
 - [Milestone 12 Verification Checklist v1.0](./docs/milestones/milestone-12/FounderOS_Milestone_12_Verification_Checklist_v1.0.md)
 - [Milestone 12 Codex Execution Prompt v1.0](./docs/milestones/milestone-12/FounderOS_Milestone_12_Codex_Execution_Prompt_v1.0.md)
 
+### Milestone 13 — Provider-Neutral Reasoning Invocation and Result Evidence Foundation
+
+Milestone 13 is implemented by storage-independent contracts in [`@founderos/knowledge-schema`](./packages/knowledge-schema/README.md) and the governed invocation facade, deterministic fake provider, and local append-only execution-evidence adapter in [`@founderos/knowledge-engine`](./services/knowledge-engine/README.md). It consumes an exact committed Milestone 12 Delivery transaction; it does not implement a production provider or a general reasoning runtime.
+
+- [Milestone 13 Package README v1.0](./docs/milestones/milestone-13/FounderOS_Milestone_13_Package_README_v1.0.md)
+- [Provider-Neutral Reasoning Invocation and Result Evidence Foundation Specification v1.0](./docs/milestones/milestone-13/FounderOS_Milestone_13_Provider_Neutral_Reasoning_Invocation_and_Result_Evidence_Foundation_Specification_v1.0.md)
+- [Reasoning Invocation Request Contract v1.0](./docs/milestones/milestone-13/FounderOS_Reasoning_Invocation_Request_Contract_v1.0.md)
+- [Provider-Neutral Reasoning Input Contract v1.0](./docs/milestones/milestone-13/FounderOS_Provider_Neutral_Reasoning_Input_Contract_v1.0.md)
+- [Reasoning Provider Capability Descriptor Contract v1.0](./docs/milestones/milestone-13/FounderOS_Reasoning_Provider_Capability_Descriptor_Contract_v1.0.md)
+- [Reasoning Execution Policy and Budget Contract v1.0](./docs/milestones/milestone-13/FounderOS_Reasoning_Execution_Policy_and_Budget_Contract_v1.0.md)
+- [Provider-Neutral Reasoning Execution Port v1.0](./docs/milestones/milestone-13/FounderOS_Provider_Neutral_Reasoning_Execution_Port_v1.0.md)
+- [Deterministic Fake Reasoning Provider Adapter Specification v1.0](./docs/milestones/milestone-13/FounderOS_Deterministic_Fake_Reasoning_Provider_Adapter_Specification_v1.0.md)
+- [Reasoning Invocation Idempotency, Retry, Timeout, and Cancellation Specification v1.0](./docs/milestones/milestone-13/FounderOS_Reasoning_Invocation_Idempotency_Retry_Timeout_and_Cancellation_Specification_v1.0.md)
+- [Reasoning Execution Receipt, Usage, Cost, Failure, and Cancellation Evidence Contract v1.0](./docs/milestones/milestone-13/FounderOS_Reasoning_Execution_Receipt_Usage_Cost_Failure_and_Cancellation_Evidence_Contract_v1.0.md)
+- [Reasoning Result Envelope Contract v1.0](./docs/milestones/milestone-13/FounderOS_Reasoning_Result_Envelope_Contract_v1.0.md)
+- [Consumption Evidence Finalization Specification v1.0](./docs/milestones/milestone-13/FounderOS_Consumption_Evidence_Finalization_Specification_v1.0.md)
+- [Durable Reasoning Execution Evidence Ledger Contract v1.0](./docs/milestones/milestone-13/FounderOS_Durable_Reasoning_Execution_Evidence_Ledger_Contract_v1.0.md)
+- [No-Provider-Bypass and Reasoning Result Integrity Enforcement Policy v1.0](./docs/milestones/milestone-13/FounderOS_No_Provider_Bypass_and_Reasoning_Result_Integrity_Enforcement_Policy_v1.0.md)
+- [Provider-Neutral Reasoning Evaluation Framework v1.0](./docs/milestones/milestone-13/FounderOS_Provider_Neutral_Reasoning_Evaluation_Framework_v1.0.md)
+- [Milestone 13 Acceptance Criteria v1.0](./docs/milestones/milestone-13/FounderOS_Milestone_13_Acceptance_Criteria_v1.0.md)
+- [Milestone 13 Verification Checklist v1.0](./docs/milestones/milestone-13/FounderOS_Milestone_13_Verification_Checklist_v1.0.md)
+- [Milestone 13 Codex Execution Prompt v1.0](./docs/milestones/milestone-13/FounderOS_Milestone_13_Codex_Execution_Prompt_v1.0.md)
+
 ## Repository governance
 
 - [Architecture decisions](./ARCHITECTURE_DECISIONS.md)

diff --git a/README.md b/README.md
@@ -2,12 +2,14 @@
 
 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, corpus-backed repository snapshots, deterministic comparison and governed change sets, human-controlled snapshot review, a local durable snapshot registry and activation audit trail, deterministic queries, governed context assembly, a provider-neutral governed Context Consumer delivery boundary, and a restart-safe local Context Delivery Ledger with durable idempotency and Replay Attempt evidence. It does **not** implement a general-purpose application database, distributed or remote persistence, automatic activation or synchronization, semantic retrieval, LLM execution, Hermes, an agent runtime, MCP connectors, or a user interface.
+The repository currently provides the governed KnowledgeOS schema, ingestion, migration, corpus-backed repository snapshots, deterministic comparison and governed change sets, human-controlled snapshot review, a local durable snapshot registry and activation audit trail, deterministic queries, governed context assembly, a provider-neutral governed Context Consumer delivery boundary, and a restart-safe local Context Delivery Ledger with durable idempotency and Replay Attempt evidence. It does **not** implement a general-purpose application database, distributed or remote persistence, automatic activation or synchronization, semantic retrieval, real-provider or production-model execution, Hermes, an agent runtime, MCP connectors, or a user interface.
 
 ## Architecture at a glance
 
 FounderOS separates human interaction, intelligence, orchestration, knowledge and memory, integrations, and infrastructure. Knowledge is retrieved before important actions; reasoning is separate from execution; human approval remains authoritative for strategic, external, irreversible, and high-risk actions.
 
+Milestone 13 also provides a governed provider-neutral reasoning boundary backed only by a deterministic fake provider and append-only execution evidence. It does not connect to or emulate a production model provider.
+
 Repository dependencies must flow in one direction:
 
 ```text
@@ -20,12 +22,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, repositories, lifecycle and durable registry evidence, governed context packages, Consumer delivery, and storage-independent durable Delivery Ledger records 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 queries, governed lifecycle and durable activation, deterministic budget-bounded context assembly, fail-closed provider-neutral delivery, and a governed append-only Delivery Ledger with restart recovery, audit verification, and rebuildable derived indexes.
+- [`@founderos/knowledge-schema`](./packages/knowledge-schema/README.md) provides strict runtime schemas and inferred TypeScript contracts for KnowledgeOS metadata, objects, migration, queries, repositories, lifecycle and durable registry evidence, governed context packages, Consumer delivery, and storage-independent durable Delivery and Reasoning Execution Ledger contracts 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 queries, governed lifecycle and durable activation, deterministic budget-bounded context assembly, fail-closed provider-neutral delivery, governed append-only Delivery and Reasoning Execution ledgers, and deterministic fake-provider reasoning with independently verifiable result 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.
 
-Automatic corpus refresh, vault watching, background synchronization or activation, database and distributed adapters, remote coordination and replication, semantic retrieval, embeddings, ranking, graph storage, LLM or agent execution, connectors, and interfaces remain unimplemented. Milestone 09 and 12 persistence is deliberately limited to explicit, Git-ignored, cooperative single-writer local runtimes; see the [knowledge-engine durability documentation](./services/knowledge-engine/README.md#milestone-12-durable-context-delivery-ledger) before operating them.
+Automatic corpus refresh, vault watching, background synchronization or activation, database and distributed adapters, remote coordination and replication, semantic retrieval, embeddings, ranking, graph storage, real-provider or agent execution, connectors, and interfaces remain unimplemented. Milestone 09, 12, and 13 persistence is deliberately limited to explicit, Git-ignored, cooperative single-writer local runtimes; see the [Milestone 12](./services/knowledge-engine/README.md#milestone-12-durable-context-delivery-ledger) and [Milestone 13](./services/knowledge-engine/README.md#milestone-13-governed-reasoning-invocation) durability documentation before operating them.
 
 ## Repository layout
 

diff --git a/.../milestone-13/FounderOS_Consumption_Evidence_Finalization_Specification_v1.0.md b/.../milestone-13/FounderOS_Consumption_Evidence_Finalization_Specification_v1.0.md
@@ -0,0 +1,46 @@
+# FounderOS Consumption Evidence Finalization Specification v1.0
+
+## Purpose
+
+Define how Milestone 11 Consumption Evidence becomes complete after a governed Reasoning Invocation finishes.
+
+## Finalized Consumption Evidence
+
+The final record should bind:
+
+- Contract version
+- Consumption ID
+- Delivery Receipt ID and fingerprint
+- Invocation Request ID and fingerprint
+- Invocation idempotency key
+- Provider Capability ID and fingerprint
+- Final Result Envelope ID and fingerprint
+- Final outcome
+- Attempt history summary
+- Started-at evidence
+- Completed-at evidence
+- Usage Evidence fingerprint
+- Cost Evidence fingerprint
+- Failure, Timeout, or Cancellation Evidence fingerprint when applicable
+- Durable ledger transaction reference
+- Canonical Consumption Evidence fingerprint
+
+## Finalization Rules
+
+- Consumption cannot finalize before a terminal Result Envelope exists.
+- Exactly one final Consumption Evidence record exists per finalized Invocation.
+- Identical finalization replay is idempotent.
+- Conflicting finalization fails.
+- Finalization never modifies the Delivery Envelope or Receipt.
+- Attempt history remains separately auditable.
+- Finalized evidence must be append-only when persisted.
+
+## Durable Binding
+
+Milestone 13 should extend the existing durable governance boundary using a storage-independent execution-evidence port or a compatible versioned extension to the Milestone 12 ledger.
+
+Do not expose arbitrary low-level record insertion.
+
+## Principle
+
+Consumption Evidence closes the governed chain from knowledge delivery to reasoning outcome.