Finish repository foundation workplan

CLAUDE.md

@@ -13,8 +13,9 @@ At session start, orient from:
 2. `INTENT.md`
 3. `wiki/ProductRequirementsDocument.md`
 4. `wiki/FunctionalRequirementsSpecification.md`
-5. `docs/markitect-main-scope-assessment.md`
-6. Active files in `workplans/`
+5. `docs/stack-decision.md`
+6. `docs/markitect-main-scope-assessment.md`
+7. Active files in `workplans/`
 
 ## State Hub
 
@@ -73,6 +74,23 @@ Prefer clean reimplementation around the new PRD/FRS. Use `markitect-main` as
 reference material for behavior, tests, and domain vocabulary, not as an
 architecture to copy wholesale.
 
+## Stack And Commands
+
+- Python target: 3.12+
+- Distribution: `kontextual-engine`
+- Import package: `kontextual_engine`
+- Build backend: `setuptools`
+- Test runner: `pytest`
+- Source layout: `src/kontextual_engine`
+- Service framework: FastAPI as an optional boundary after the programmatic API
+  stabilizes
+
+Run tests:
+
+```bash
+python3 -m pytest
+```
+
 ## Workplans
 
 Workplans live in `workplans/` and follow the Custodian ADR-001 convention:
@@ -81,4 +99,3 @@ Workplans live in `workplans/` and follow the Custodian ADR-001 convention:
   kontextual-engine`, and `owner: codex`.
 - Tasks are embedded as headed sections with fenced `task` blocks.
 - State Hub may index these files, but the files remain authoritative.
-

README.md

@@ -9,5 +9,14 @@ Start here:
 - `wiki/ProductRequirementsDocument.md`
 - `wiki/FunctionalRequirementsSpecification.md`
 - `SCOPE.md`
+- `docs/stack-decision.md`
 - `docs/markitect-main-scope-assessment.md`
 - `workplans/`
+
+## Development
+
+This repo uses Python 3.12+, setuptools, a `src/` package layout, and pytest.
+
+```bash
+python3 -m pytest
+```

docs/stack-decision.md

@@ -0,0 +1,50 @@
+# Stack Decision
+
+Date: 2026-05-05
+
+## Decision
+
+`kontextual-engine` starts as a Python 3.12+ package with:
+
+- Distribution name: `kontextual-engine`
+- Import package: `kontextual_engine`
+- Build backend: `setuptools`
+- Test runner: `pytest`
+- Source layout: `src/kontextual_engine`
+- First service framework: FastAPI, added as an optional `service` extra
+
+The first implementation should stabilize the programmatic API before exposing
+HTTP endpoints. The service layer should wrap the same contracts rather than
+becoming the architecture driver.
+
+## Initial Dependencies
+
+Core dependencies:
+
+- `pydantic>=2.0` for explicit runtime models and validation.
+
+Optional extras:
+
+- `dev`: `pytest`
+- `service`: `fastapi`, `uvicorn`
+- `storage`: `sqlalchemy`
+- `markdown`: local `markitect-tool` adapter dependency
+- `llm`: local `llm-connect` adapter dependency
+
+## Rationale
+
+The PRD/FRS describe a headless runtime, not a CLI-first tool. Python keeps the
+repo aligned with `markitect-tool`, `llm-connect`, and State Hub while allowing
+the engine to expose both programmatic and service interfaces.
+
+FastAPI is appropriate for the service boundary because State Hub already uses
+that stack locally, but it remains optional until `KONT-WP-0003` defines stable
+artifact, collection, storage, query, workflow, and context contracts.
+
+## Deferred Decisions
+
+- Durable storage backend selection beyond initial repository interfaces.
+- HTTP endpoint shape and versioning.
+- Whether an administrative CLI is needed.
+- Lockfile/SBOM source, once dependencies are installed in this repo.
+

pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kontextual-engine"
+version = "0.1.0"
+description = "Headless knowledge runtime for persistent, operable structured knowledge"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+]
+service = [
+    "fastapi>=0.110",
+    "uvicorn>=0.27",
+]
+storage = [
+    "sqlalchemy>=2.0",
+]
+markdown = [
+    "markitect-tool @ file:///home/worsch/markitect-tool",
+]
+llm = [
+    "llm-connect @ file:///home/worsch/llm-connect",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+

src/kontextual_engine/__init__.py

@@ -0,0 +1,6 @@
+"""Headless knowledge runtime package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

tests/test_package_contract.py

@@ -0,0 +1,6 @@
+from kontextual_engine import __version__
+
+
+def test_package_exports_version() -> None:
+    assert __version__ == "0.1.0"
+

workplans/KONT-WP-0001-repo-foundation.md

@@ -4,11 +4,11 @@ type: workplan
 title: "Repository Foundation And State Hub Integration"
 domain: markitect
 repo: kontextual-engine
-status: active
+status: done
 owner: codex
 topic_slug: markitect
 created: "2026-05-03"
-updated: "2026-05-03"
+updated: "2026-05-05"
 state_hub_workstream_id: "52ff9c49-edcf-4150-8895-c6b31f5aa075"
 ---
 
@@ -77,10 +77,13 @@ workplan files.
 
 ```task
 id: KONT-WP-0001-T005
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "616e0476-7b65-4079-b545-13e0fc9436f7"
 ```
 
 Choose the first implementation stack, dependency manager, test command, and
 service framework. Record the decision before adding application code.
+
+Output: `docs/stack-decision.md`; executable scaffold added in `pyproject.toml`,
+`src/kontextual_engine/`, and `tests/`.