applied-epistemic-engineering 1.0.0__tar.gz

applied_epistemic_engineering-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+site/
+.aee/
+

applied_epistemic_engineering-1.0.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+

applied_epistemic_engineering-1.0.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-09-04
+
+### Added
+
+- Independent Applied Epistemic Engineering domain model.
+- Claim decomposition, evidence/provenance representation, and explicit uncertainty.
+- Deterministic stress testing, contradiction discovery, dependency analysis, and recovery.
+- Evidence-quality scoring with weakest-link propagation.
+- Tamper-evident SHA-256 JSONL ledger with complete-chain verification.
+- Adapter for ElectroHire's Spec Kit Evaluator Contract v1.0.
+- Dependency-free CLI and Python API.
+- Strict Read the Docs/MkDocs documentation and multi-platform CI.
+
+[1.0.0]: https://github.com/electrohire/applied-epistemic-engineering/releases/tag/v1.0.0
+

applied_epistemic_engineering-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ElectroHire Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

applied_epistemic_engineering-1.0.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: applied-epistemic-engineering
+Version: 1.0.0
+Summary: Evidence-centered claim evaluation, adversarial challenge, recovery, and tamper-evident epistemic records.
+Project-URL: Homepage, https://github.com/electrohire/applied-epistemic-engineering
+Project-URL: Documentation, https://applied-epistemic-engineering.readthedocs.io
+Project-URL: Repository, https://github.com/electrohire/applied-epistemic-engineering
+Project-URL: Changelog, https://github.com/electrohire/applied-epistemic-engineering/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/electrohire/applied-epistemic-engineering/issues
+Author: ElectroHire Inc.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aee,ai-governance,applied-epistemic-engineering,evidence,provenance,spec-driven-development,uncertainty
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Applied Epistemic Engineering for Python
+
+[![CI](https://github.com/electrohire/applied-epistemic-engineering/actions/workflows/ci.yml/badge.svg)](https://github.com/electrohire/applied-epistemic-engineering/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/applied-epistemic-engineering/badge/?version=latest)](https://applied-epistemic-engineering.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An evidence-centered Python toolkit for turning important claims into inspectable engineering
+artifacts. It makes boundaries, evidence, provenance, uncertainty, contradictions,
+falsification tests, recovery work, and decision history explicit.
+
+This is an original, ground-up ElectroHire implementation. It carries forward the useful AEE
+concepts previously embedded in SpecSmith while removing SpecSmith runtime coupling and aligning
+the result model directly with ElectroHire's Spec Kit Evaluator Contract.
+
+## Why it exists
+
+Ordinary validation asks whether an artifact is formatted correctly. AEE asks harder questions:
+
+- What exactly is being claimed?
+- Under what conditions does it hold?
+- What was observed, inferred, or merely asserted?
+- What evidence would prove the claim wrong?
+- Which claims depend on uncertain foundations?
+- What contradicts the current conclusion?
+- What bounded work would improve the decision?
+
+The library does not call a confidence number “truth.” Every score is a transparent decision aid
+derived from recorded evidence and explicit rules.
+
+## Installation
+
+```bash
+pip install applied-epistemic-engineering
+```
+
+For development:
+
+```bash
+pip install -e ".[dev,docs]"
+```
+
+## Five-minute example
+
+```python
+from aee import (
+    AEESession,
+    ClaimKind,
+    ClaimStatus,
+    Evidence,
+    EvidenceKind,
+    SourceQuality,
+)
+
+session = AEESession(
+    "checkout-service",
+    phase="after_plan",
+    ledger_file=".aee/epistemic-ledger.jsonl",
+)
+
+claim = session.add_claim(
+    "REQ-PERF-001",
+    "Checkout p95 latency remains below 300 ms",
+    kind=ClaimKind.REQUIREMENT,
+    boundary=["production", "nominal load", "30-minute observation window"],
+    source_ref="spec.md#REQ-PERF-001",
+)
+claim.status = ClaimStatus.SUPPORTED
+claim.falsification_tests.append("Observe p95 latency at or above 300 ms")
+
+session.add_evidence(
+    claim.id,
+    Evidence(
+        ref="reports/load-test-2026-09-04.json",
+        kind=EvidenceKind.OBSERVED,
+        source_quality=SourceQuality.TEST,
+        source_id="load-test-2026-09-04",
+        description="Observed p95 latency was 241 ms",
+    ),
+)
+
+assessment = session.assess()
+print(assessment.outcome, assessment.summary)
+```
+
+## CLI
+
+```bash
+aee assess --input claims.json --phase after_plan --output assessment.json \
+  --evaluator-output evaluator-result.json --ledger .aee/epistemic-ledger.jsonl
+
+aee verify-ledger --ledger .aee/epistemic-ledger.jsonl
+aee graph --input claims.json --output claim-graph.mmd
+aee gate --input assessment.json
+```
+
+Exit codes are CI-friendly: `0` for pass/warn, `1` for iteration/clarification/evidence
+collection, and `2` for a hard block or invalid ledger.
+
+## Architecture
+
+| Layer | Responsibility |
+|---|---|
+| `aee` Python package | Claims, evidence, scoring, challenge, recovery, graph, ledger |
+| [`spec-kit-aee`](https://github.com/electrohire/spec-kit-aee) | Spec Kit commands, hooks, and artifact discovery |
+| [`spec-kit-evaluator`](https://github.com/electrohire/spec-kit-evaluator) | Shared result envelope, composition, reports, and model routing |
+
+## Core principles
+
+1. Assertions never become observations because a model repeats them.
+2. Counterevidence and contradictions remain visible.
+3. Unsupported claims remain explicitly unsupported.
+4. Confidence propagates through dependencies by the weakest-link rule.
+5. Every failure produces a bounded recovery proposal with a verification condition.
+6. Deterministic checks run before probabilistic review.
+7. Hash chains establish tamper evidence—not truth, identity, or trusted time.
+
+## Documentation
+
+Full documentation is configured for Read the Docs at
+[applied-epistemic-engineering.readthedocs.io](https://applied-epistemic-engineering.readthedocs.io).
+Existing SpecSmith AEE users can follow the [migration guide](docs/migration.md).
+
+## Ownership and license
+
+Designed and implemented by **ElectroHire Inc.** Copyright © 2026 ElectroHire Inc.
+Released under the [MIT License](LICENSE).

applied_epistemic_engineering-1.0.0/README.md

@@ -0,0 +1,126 @@
+# Applied Epistemic Engineering for Python
+
+[![CI](https://github.com/electrohire/applied-epistemic-engineering/actions/workflows/ci.yml/badge.svg)](https://github.com/electrohire/applied-epistemic-engineering/actions/workflows/ci.yml)
+[![Documentation](https://readthedocs.org/projects/applied-epistemic-engineering/badge/?version=latest)](https://applied-epistemic-engineering.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An evidence-centered Python toolkit for turning important claims into inspectable engineering
+artifacts. It makes boundaries, evidence, provenance, uncertainty, contradictions,
+falsification tests, recovery work, and decision history explicit.
+
+This is an original, ground-up ElectroHire implementation. It carries forward the useful AEE
+concepts previously embedded in SpecSmith while removing SpecSmith runtime coupling and aligning
+the result model directly with ElectroHire's Spec Kit Evaluator Contract.
+
+## Why it exists
+
+Ordinary validation asks whether an artifact is formatted correctly. AEE asks harder questions:
+
+- What exactly is being claimed?
+- Under what conditions does it hold?
+- What was observed, inferred, or merely asserted?
+- What evidence would prove the claim wrong?
+- Which claims depend on uncertain foundations?
+- What contradicts the current conclusion?
+- What bounded work would improve the decision?
+
+The library does not call a confidence number “truth.” Every score is a transparent decision aid
+derived from recorded evidence and explicit rules.
+
+## Installation
+
+```bash
+pip install applied-epistemic-engineering
+```
+
+For development:
+
+```bash
+pip install -e ".[dev,docs]"
+```
+
+## Five-minute example
+
+```python
+from aee import (
+    AEESession,
+    ClaimKind,
+    ClaimStatus,
+    Evidence,
+    EvidenceKind,
+    SourceQuality,
+)
+
+session = AEESession(
+    "checkout-service",
+    phase="after_plan",
+    ledger_file=".aee/epistemic-ledger.jsonl",
+)
+
+claim = session.add_claim(
+    "REQ-PERF-001",
+    "Checkout p95 latency remains below 300 ms",
+    kind=ClaimKind.REQUIREMENT,
+    boundary=["production", "nominal load", "30-minute observation window"],
+    source_ref="spec.md#REQ-PERF-001",
+)
+claim.status = ClaimStatus.SUPPORTED
+claim.falsification_tests.append("Observe p95 latency at or above 300 ms")
+
+session.add_evidence(
+    claim.id,
+    Evidence(
+        ref="reports/load-test-2026-09-04.json",
+        kind=EvidenceKind.OBSERVED,
+        source_quality=SourceQuality.TEST,
+        source_id="load-test-2026-09-04",
+        description="Observed p95 latency was 241 ms",
+    ),
+)
+
+assessment = session.assess()
+print(assessment.outcome, assessment.summary)
+```
+
+## CLI
+
+```bash
+aee assess --input claims.json --phase after_plan --output assessment.json \
+  --evaluator-output evaluator-result.json --ledger .aee/epistemic-ledger.jsonl
+
+aee verify-ledger --ledger .aee/epistemic-ledger.jsonl
+aee graph --input claims.json --output claim-graph.mmd
+aee gate --input assessment.json
+```
+
+Exit codes are CI-friendly: `0` for pass/warn, `1` for iteration/clarification/evidence
+collection, and `2` for a hard block or invalid ledger.
+
+## Architecture
+
+| Layer | Responsibility |
+|---|---|
+| `aee` Python package | Claims, evidence, scoring, challenge, recovery, graph, ledger |
+| [`spec-kit-aee`](https://github.com/electrohire/spec-kit-aee) | Spec Kit commands, hooks, and artifact discovery |
+| [`spec-kit-evaluator`](https://github.com/electrohire/spec-kit-evaluator) | Shared result envelope, composition, reports, and model routing |
+
+## Core principles
+
+1. Assertions never become observations because a model repeats them.
+2. Counterevidence and contradictions remain visible.
+3. Unsupported claims remain explicitly unsupported.
+4. Confidence propagates through dependencies by the weakest-link rule.
+5. Every failure produces a bounded recovery proposal with a verification condition.
+6. Deterministic checks run before probabilistic review.
+7. Hash chains establish tamper evidence—not truth, identity, or trusted time.
+
+## Documentation
+
+Full documentation is configured for Read the Docs at
+[applied-epistemic-engineering.readthedocs.io](https://applied-epistemic-engineering.readthedocs.io).
+Existing SpecSmith AEE users can follow the [migration guide](docs/migration.md).
+
+## Ownership and license
+
+Designed and implemented by **ElectroHire Inc.** Copyright © 2026 ElectroHire Inc.
+Released under the [MIT License](LICENSE).

applied_epistemic_engineering-1.0.0/docs/api.md

@@ -0,0 +1,36 @@
+# Python API
+
+## Session
+
+::: aee.session.AEESession
+
+## Engine
+
+::: aee.engine.AEEEngine
+
+::: aee.engine.Assessment
+
+## Model
+
+::: aee.model.Claim
+
+::: aee.model.Evidence
+
+::: aee.model.FailureMode
+
+## Analysis
+
+::: aee.challenge.StressTester
+
+::: aee.scoring.ScoringEngine
+
+::: aee.graph.ClaimGraph
+
+::: aee.recovery.RecoveryOperator
+
+## Ledger and adapter
+
+::: aee.ledger.HashChainLedger
+
+::: aee.adapters.evaluator.EvaluatorAdapter
+

applied_epistemic_engineering-1.0.0/docs/concepts.md

@@ -0,0 +1,36 @@
+# Foundations
+
+AEE follows four operational stages:
+
+1. **Frame** — identify the decision, claim boundaries, actors, and risk.
+2. **Disassemble** — split conclusions into atomic claims and dependencies.
+3. **Stress-test** — seek ambiguity, hidden assumptions, counterexamples, contradictions,
+   missing evidence, circular inference, and unfalsifiable claims.
+4. **Reconstruct** — narrow, clarify, gather evidence, resolve contradictions, or supersede.
+
+## Claim model
+
+A claim separates:
+
+- its proposition from its source;
+- its applicable boundary from universal language;
+- observed evidence from inference and assertion;
+- supporting evidence from counterevidence;
+- direct confidence from dependency-propagated confidence; and
+- current status from historical ledger events.
+
+## Epistemic invariants
+
+- A model's statement about its own work is `asserted`, not `observed`.
+- A supported claim requires inspectable evidence.
+- Contradictions are records to resolve, not noise to average away.
+- An accepted claim needs a falsification condition.
+- A dependent claim cannot be more certain than its weakest required premise.
+- The absence of evidence is represented as insufficient evidence, not a fabricated answer.
+
+## Deterministic and probabilistic work
+
+The Python engine performs transparent deterministic checks. A model-backed reviewer may enrich
+claims, propose alternatives, or locate counterevidence, but its output enters the same model and
+remains labeled according to how it was obtained.
+

applied_epistemic_engineering-1.0.0/docs/index.md

@@ -0,0 +1,21 @@
+# Applied Epistemic Engineering
+
+Applied Epistemic Engineering (AEE) treats consequential claims as engineering artifacts:
+identifiable, bounded, challengeable, evidence-linked, recoverable, and auditable.
+
+The ElectroHire Python package provides:
+
+- a typed claim and evidence model;
+- deterministic stress tests;
+- explicit contradictions and dependency graphs;
+- transparent evidence-quality scoring;
+- bounded recovery proposals;
+- a tamper-evident decision ledger; and
+- native conversion to the Spec Kit Evaluator Contract.
+
+!!! important
+    AEE does not certify truth, compliance, safety, or correctness. It records what is known,
+    why it is believed, what remains uncertain, and what evidence would change the decision.
+
+Start with the [quickstart](quickstart.md), then read the [foundations](concepts.md).
+

applied_epistemic_engineering-1.0.0/docs/ledger.md

@@ -0,0 +1,24 @@
+# Tamper-evident ledger
+
+`HashChainLedger` writes canonical JSON Lines. Each entry includes the hash of the previous entry
+and its own canonical SHA-256 digest.
+
+```python
+from aee import HashChainLedger
+
+ledger = HashChainLedger(".aee/epistemic-ledger.jsonl")
+ledger.append("decision", {"claim_id": "DEC-001", "choice": "Option A"})
+assert ledger.verify().valid
+```
+
+The chain detects modification, reordering, insertion, and deletion from the middle of the local
+history. It does **not** independently prove:
+
+- who wrote an entry;
+- when the event occurred;
+- that the payload is true; or
+- that the ledger head was not replaced wholesale.
+
+For stronger guarantees, anchor head hashes externally and add actor signatures, trusted
+timestamps, protected storage, and independent evidence retention.
+

applied_epistemic_engineering-1.0.0/docs/migration.md

@@ -0,0 +1,54 @@
+# Migrating from SpecSmith AEE
+
+This package is a ground-up ElectroHire implementation, not a drop-in copy of SpecSmith's
+`epistemic` package. The concepts remain recognizable, while the types, serialization format,
+scoring model, CLI, and Spec Kit boundary are intentionally explicit and independently versioned.
+
+## Concept mapping
+
+| SpecSmith concept | ElectroHire AEE equivalent | Important change |
+| --- | --- | --- |
+| Belief/claim | `aee.Claim` | Stable IDs, sources, boundaries, dependencies, conflicts, and falsifiers are first-class |
+| Evidence refs | `aee.Evidence` | Kind, direction, source quality, independence, observation time, and content hash are separate |
+| Stress tester | `aee.StressTester` | Checks are deterministic and every breakpoint has a stable failure ID |
+| Failure graph | `aee.ClaimGraph` | Missing dependencies, cycles, conflicts, order, and Mermaid rendering share one graph |
+| Certainty engine | `aee.ScoringEngine` | Published weights replace opaque confidence; dependencies use weakest-link propagation |
+| Recovery operator | `aee.RecoveryOperator` | Every recovery includes a verification condition and deterministic priority |
+| AEE session | `aee.AEESession` | Library-first orchestration with an optional append-only ledger |
+| Trace vault | `aee.HashChainLedger` | Canonical JSONL SHA-256 chain establishes continuity, not truth or identity |
+| Result | `aee.Assessment` | Rich output converts to Evaluator Contract 1.0 through `EvaluatorAdapter` |
+
+## Minimal migration
+
+Instead of importing `epistemic`, install the new distribution and import `aee`:
+
+```bash
+pip install applied-epistemic-engineering
+```
+
+```python
+from aee import AEESession, ClaimKind
+
+session = AEESession("my-system", phase="after_plan")
+session.add_claim(
+    "ASM-IDENTITY-001",
+    "The upstream identity is verified",
+    kind=ClaimKind.ASSUMPTION,
+    boundary=["production OAuth callback"],
+    source_ref="plan.md#ASM-IDENTITY-001",
+)
+assessment = session.assess()
+```
+
+The initial outcome remains evidence-seeking until independently inspectable evidence and a
+falsification test are attached. That is deliberate.
+
+## Deliberate exclusions
+
+- No SpecSmith runtime dependency or private backend coupling.
+- No ChronoMemory code or commercial storage integration.
+- No model-generated confidence masquerading as observed evidence.
+- No compatibility aliases that obscure which implementation produced a record.
+
+For Spec Kit projects, install `spec-kit-evaluator` and `spec-kit-aee`; keep domain logic in this
+package and lifecycle orchestration in the extension.

applied_epistemic_engineering-1.0.0/docs/quickstart.md

@@ -0,0 +1,67 @@
+# Quickstart
+
+## Install
+
+```bash
+python -m pip install applied-epistemic-engineering
+```
+
+## Assess structured claims
+
+Create `claims.json`:
+
+```json
+{
+  "claims": [
+    {
+      "id": "REQ-API-001",
+      "text": "The API returns within 100 ms",
+      "kind": "requirement",
+      "status": "supported",
+      "boundary": ["p95", "nominal load", "production"],
+      "falsification_tests": ["Observe p95 at or above 100 ms"],
+      "uncertainty": "low",
+      "evidence": [
+        {
+          "ref": "reports/load-test.json",
+          "kind": "observed",
+          "direction": "supports",
+          "source_quality": "test",
+          "source_id": "load-test-001"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Run the assessment:
+
+```bash
+aee assess \
+  --input claims.json \
+  --phase after_plan \
+  --output assessment.json \
+  --evaluator-output evaluator-result.json \
+  --ledger .aee/epistemic-ledger.jsonl
+```
+
+The assessment retains the rich AEE model. `evaluator-result.json` conforms to the shared
+Evaluator Contract used by Spec Kit.
+
+## Extract identified claims from Markdown
+
+The parser intentionally extracts only claims with stable identifiers:
+
+```markdown
+## REQ-API-001 — The API returns within 100 ms
+- **Boundary:** p95 under nominal production load
+- **Test:** Observe p95 at or above 100 ms
+```
+
+```bash
+aee assess --input spec.md --phase after_specify
+```
+
+Unidentified prose is not silently promoted into claims.
+

applied_epistemic_engineering-1.0.0/docs/scoring.md

@@ -0,0 +1,25 @@
+# Transparent scoring
+
+The default direct confidence score is:
+
+```text
+0.55 × evidence quality
++ 0.20 × source independence
++ 0.15 × falsifiability
++ 0.10 × explicit boundary
+- contradiction penalty
+- freshness penalty
+```
+
+Evidence quality combines evidence kind and source quality. Multiple supporting sources use a
+bounded cumulative calculation; repeated weak assertions cannot inflate confidence without limit.
+
+After direct scoring, required dependencies apply the weakest-link rule:
+
+```text
+propagated(claim) = min(direct(claim), propagated(each required dependency))
+```
+
+Scores communicate the state of the recorded evidence. They do not measure metaphysical truth,
+legal sufficiency, or safety certification.
+

applied_epistemic_engineering-1.0.0/docs/security.md

@@ -0,0 +1,25 @@
+# Security and trust boundaries
+
+## Data handling
+
+The core library is offline and has no network dependencies. It only reads files explicitly
+provided by the caller and writes to explicitly configured output paths.
+
+Do not place secrets, export-controlled material, personal data, or privileged evidence in a
+public repository. AEE records may reveal architecture, risks, and unresolved weaknesses.
+
+## Model-backed enrichment
+
+The core library does not contact a model. Host applications that add model-backed review must:
+
+- classify model output as asserted or inferred;
+- avoid sending protected data to an unauthorized provider;
+- retain the model and policy identity in metadata;
+- require independent evidence for high-impact gates; and
+- preserve counterevidence and human overrides.
+
+## Cryptographic scope
+
+SHA-256 chaining detects local history mutation. It is not a digital signature, trusted timestamp,
+identity proof, or truth oracle. See the [ledger guide](ledger.md).
+

applied_epistemic_engineering-1.0.0/docs/spec-kit.md

@@ -0,0 +1,23 @@
+# Spec Kit integration
+
+The Python package owns epistemic analysis. The
+[`spec-kit-aee`](https://github.com/electrohire/spec-kit-aee) extension owns Spec Kit artifact
+discovery, lifecycle hooks, and command UX. The
+[`spec-kit-evaluator`](https://github.com/electrohire/spec-kit-evaluator) extension owns the shared
+result envelope, composition, reports, and routing.
+
+```mermaid
+flowchart TD
+    SK["Spec Kit artifacts"] --> AEE["spec-kit-aee"]
+    AEE --> PY["AEE Python engine"]
+    PY --> ER["Evaluator result"]
+    ER --> EC["Compose, report, route"]
+```
+
+An AEE assessment is converted with `EvaluatorAdapter`. Rich claim and score data are preserved
+inside the evaluator contract's opaque `state.aee` field, while actionable failures become normal
+Evaluator Contract findings.
+
+This keeps AEE opinionated and independently versioned without forking or weakening the neutral
+Evaluator Contract.
+