Document portable setup and review receipts

2026-07-31 03:05:21 +00:00 · 2026-05-11 23:01:51 -05:00 · 2026-05-11 23:01:51 -05:00 · f53c0aeb04
commit f53c0aeb04
parent 110280dfd9
5 changed files with 402 additions and 2 deletions
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@ -1,6 +1,5 @@
 {
-    "cmake.sourceDirectory": "/home/allaun/Documents/Research Stack/2-Search-Space/simulations/heat-2D",
-    "python.defaultInterpreterPath": "/home/allaun/.local/share/uv/python/cpython-3.11-linux-x86_64-gnu/bin/python3.11",
+    "cmake.sourceDirectory": "${workspaceFolder}/2-Search-Space/simulations/heat-2D",
    "files.watcherExclude": {
        "**/.git/objects/**": true,
        "**/.git/subtree-cache/**": true,
--- a/6-Documentation/wiki/Build-System.md
+++ b/6-Documentation/wiki/Build-System.md
@ -0,0 +1,133 @@
+# Build System
+
+> **Source:** [[Home|Wiki Home]] · [[../GETTING_STARTED.md|Getting Started]] · [[../CONTRIBUTING.md|Contributing]]
+
+This page documents the build-system surfaces of the Sovereign Research Stack
+that supplement the Lean toolchain described in `GETTING_STARTED.md`. Content
+here is the wiki-level companion to the top-level setup docs and to the
+VSCode tasks and npm scripts committed under the repository root.
+
+---
+
+## Python Environment Management
+
+The repository pins a single Python version for all Python-based harnesses
+(swarm scripts, CAD tooling, DeepSeek review adapters, etc.) so that
+deterministic re-runs and AI-assisted review receipts remain reproducible.
+
+| Surface | Value | Source |
+|---|---|---|
+| Python version | `3.11.15` | `.python-version` |
+| Installer | `uv` (Astral) | VSCode task `Install Python 3.11.15`, npm script `install-python` |
+| Interpreter path | Platform-local uv path printed by `uv python find 3.11.15` | User-level VSCode setting or selected interpreter |
+
+The repository intentionally does not commit `python.defaultInterpreterPath`.
+That VSCode setting is absolute-path based and is therefore not portable across
+Linux, macOS, Windows, or users with a non-default `XDG_DATA_HOME`. If you want
+VSCode to pin an interpreter, set it in your user-level settings after running
+`uv python find 3.11.15`. The per-OS uv install roots are typically:
+
+| Platform | uv-managed CPython 3.11.15 path (example) |
+|---|---|
+| Linux | `/home/<user>/.local/share/uv/python/cpython-3.11-linux-x86_64-gnu/bin/python3.11` |
+| macOS | `/Users/<user>/.local/share/uv/python/cpython-3.11-macos-aarch64-none/bin/python3.11` |
+| Windows | `C:\\Users\\<user>\\AppData\\Roaming\\uv\\python\\cpython-3.11-windows-x86_64-none\\python.exe` |
+
+Run `uv python find 3.11.15` after installing the interpreter to print the
+exact path for your platform.
+
+### Why a pinned `.python-version`
+
+- `build123d` and `OCP` (the CAD stack used by `5-Applications/text-to-cad/`)
+  publish wheels for CPython 3.11 only.
+- DeepSeek review receipts (see [[DeepSeek-Review-Process]]) record SHA-256
+  hashes of prompts and answers; differing Python runtimes can change tokenizer
+  output and break receipt reproducibility for downstream review continuation.
+- The Lean toolchain is independent of Python, but every Python harness must
+  agree on a single interpreter so that artifacts produced by one stage
+  (e.g. equation-forest extraction) can be re-validated by another stage
+  (e.g. metaprobe replay) without environment drift.
+
+### UV integration
+
+`uv` is used as the installer for the pinned interpreter. The repository does
+not bundle a `pyproject.toml` at the root — `uv` is invoked only to install
+the interpreter itself, and per-application virtual environments are created
+from that interpreter.
+
+```bash
+# Install the pinned interpreter (idempotent)
+uv python install 3.11.15
+
+# Equivalent npm shortcut from the repo root
+npm run install-python
+```
+
+### VSCode integration
+
+`.vscode/settings.json` avoids committing a workspace-level
+`python.defaultInterpreterPath`. Open the repository in VSCode after the
+interpreter is installed, then select the interpreter reported by
+`uv python find 3.11.15` if the Python extension does not discover it
+automatically. The portable source of truth is `.python-version` plus the
+root install task/script, not an absolute path from one machine.
+
+### Installation flow
+
+```bash
+# 1. Install uv itself (one-time, see https://docs.astral.sh/uv/)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 2. Install the pinned interpreter
+uv python install 3.11.15      # or: npm run install-python
+
+# 3. (CAD only) Create the text-to-cad venv
+npm run setup-cad-env          # see [[Text-to-CAD-Environment]]
+
+# 4. (CAD only) Verify the CAD venv resolves build123d and OCP
+npm run verify-cad
+```
+
+---
+
+## NPM Script Surface (repo root `package.json`)
+
+The repository root `package.json` exposes a small set of orchestration scripts
+that wrap the VSCode tasks so that they are available outside the editor (CI,
+remote shells, headless installs).
+
+| Script | Wraps | Purpose |
+|---|---|---|
+| `npm run install-python` | `uv python install 3.11.15` | Install the pinned interpreter via uv |
+| `npm run setup-cad-env` | `python3.11 -m venv` + `pip install -r requirements-cad.txt` in `5-Applications/text-to-cad/` | Create the text-to-cad virtual environment |
+| `npm run verify-cad` | `import build123d; import OCP` in the text-to-cad venv | Validate that the CAD dependencies are importable |
+
+See [[Text-to-CAD-Environment]] for the CAD-specific workflow these scripts
+support.
+
+---
+
+## VSCode Tasks (`.vscode/tasks.json`)
+
+The same three operations are exposed as VSCode tasks so they can be invoked
+from the command palette (`Tasks: Run Task`) without leaving the editor.
+
+| Task label | Equivalent npm script | Notes |
+|---|---|---|
+| `Install Python 3.11.15` | `npm run install-python` | Runs `uv python install 3.11.15` from the workspace root |
+| `Setup CAD Environment` | `npm run setup-cad-env` | Creates `5-Applications/text-to-cad/.venv` and installs `requirements-cad.txt` |
+| `Verify CAD Dependencies` | `npm run verify-cad` | Runs `./.venv/bin/python -c "import build123d; import OCP; print('CAD dependencies OK')"` from the text-to-cad directory |
+
+Tasks present output in a shared panel so the install logs are persisted across
+re-runs.
+
+---
+
+## Related
+
+- [[Text-to-CAD-Environment]] — CAD-specific environment, requirements, and
+  the agent contract that consumes `5-Applications/text-to-cad/.venv`.
+- [[DeepSeek-Review-Process]] — receipt schema and review workflow that
+  depends on the pinned Python interpreter for prompt-hash reproducibility.
+- `GETTING_STARTED.md` — Lean toolchain installation and end-to-end build
+  walkthrough for the Lean core.
--- a/6-Documentation/wiki/DeepSeek-Review-Process.md
+++ b/6-Documentation/wiki/DeepSeek-Review-Process.md
@ -0,0 +1,189 @@
+# DeepSeek Review Process
+
+> **Source:** [[Home|Wiki Home]] · `5-Applications/tools-scripts/llm/deepseek_review_adapter.py` · `shared-data/artifacts/deepseek_review/`
+
+The Research Stack incorporates DeepSeek AI models for formal mathematical
+review and validation of canonical specifications, Lean kernels, and
+statistical-interpretation receipts. This page documents the wiki-level view
+of the review pipeline, the receipt schema, and the canonical example
+(prime-gap entropy collapse) shipped under
+`shared-data/artifacts/deepseek_review/`.
+
+---
+
+## AI-Assisted Mathematical Review
+
+DeepSeek review receipts provide reproducibility and integrity tracking for
+AI-assisted mathematical validation. Each review run emits a paired
+`.md` answer file and a `.receipt.json` sidecar that records the exact model,
+endpoint, token usage, and SHA-256 hashes needed to re-validate the review
+without re-running the model.
+
+### Review Artifacts
+
+| Path | Purpose |
+|---|---|
+| `shared-data/artifacts/deepseek_review/` | Root for all review answers and receipt sidecars |
+| `*_deepseek-v3.2_*.md` | Primary review answer (markdown, model-authored) |
+| `*_deepseek-v3.2_*.receipt.json` | Receipt for the primary review (schema `ollama_deepseek_review_receipt_v1`) |
+| `*_deepseek-v4-flash_continuation_*.md` | Continuation answer when the primary review was truncated |
+| `*_deepseek-v4-flash_continuation_*.receipt.json` | Receipt for the continuation (schema `ollama_deepseek_review_continuation_receipt_v1`) |
+
+Receipt filenames are aligned with their answer files by sharing the same
+`<topic>_<model>_<ISO-timestamp>` stem.
+
+### Receipt Schema
+
+Both receipt schemas are versioned JSON records that track every field needed
+to re-derive the review independently of the model server.
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema` | string | `ollama_deepseek_review_receipt_v1` (primary) or `ollama_deepseek_review_continuation_receipt_v1` (continuation) |
+| `created_at` | ISO-8601 timestamp | UTC time at which the review was produced |
+| `model` | string | Model identifier (e.g. `deepseek-v3.2`, `deepseek-v4-flash`) |
+| `endpoint` | URL | API endpoint that served the review (e.g. `https://ollama.com/v1/chat/completions`) |
+| `prompt_sha256` | `sha256:<hex>` | SHA-256 of the exact serialized prompt body sent to the endpoint |
+| `answer_sha256` | `sha256:<hex>` | SHA-256 of the answer payload written to `answer_path` |
+| `usage.prompt_tokens` | int | Tokens consumed by the prompt as reported by the endpoint |
+| `usage.completion_tokens` | int | Tokens produced by the model |
+| `usage.total_tokens` | int | Sum of the two above (recorded for cross-checks) |
+| `context_files` | string[] | Repo-relative paths to every file that participated in the review prompt context (primary receipt only; continuation consumers reconstruct this through `previous_answer_path` and the primary receipt) |
+| `answer_path` | string | Repo-relative path to the answer markdown |
+| `previous_answer_path` | string | Repo-relative path to the answer being continued (continuation receipt only) |
+| `message_keys` | string[] | Field names returned alongside `content` by the continuation endpoint (e.g. `role`, `content`, `reasoning`) (continuation receipt only) |
+
+Receipts are committed alongside the answers so that any future agent can:
+
+1. Verify integrity by recomputing the SHA-256 of `answer_path` and comparing
+   to `answer_sha256`.
+2. Reconstruct the prompt by joining the listed `context_files` against the
+   commit at which the receipt was authored.
+3. Audit token usage and cost without re-querying the endpoint.
+
+### Reconstructing context for continuations
+
+Continuation receipts intentionally omit `context_files` — a continuation
+inherits the prompt context of the primary review it extends. Consumers should
+not treat the missing field as lost context; they reconstruct it through the
+previous answer and primary receipt. To reconstruct the full context for a
+continuation answer:
+
+1. Read `previous_answer_path` from the continuation receipt.
+2. Locate the sibling primary receipt by replacing the `.md` suffix on
+   `previous_answer_path` with `.receipt.json` (the primary receipt and its
+   answer share a stem).
+3. Read `context_files` from that primary receipt and treat it as the
+   continuation's effective context bundle.
+4. The continuation prompt body itself is the primary answer at
+   `previous_answer_path` plus any continuation directive recorded in the
+   continuation answer's preamble; `prompt_sha256` on the continuation
+   receipt covers that combined body.
+
+### Review Process
+
+Reviews are executed as a two-stage pipeline:
+
+1. **Primary analysis** with `deepseek-v3.2` against a curated prompt that
+   bundles the canonical spec, statistical receipts, and Lean kernels for the
+   topic under review.
+2. **Continuation** with `deepseek-v4-flash` when the primary review is
+   truncated by the per-completion token cap. The continuation receipt
+   references the primary answer via `previous_answer_path` and inherits the
+   review topic via filename stem.
+
+Every review answer is structured to include:
+
+- A **YES/NO verdict table** answering the specific review questions posed
+  in the prompt.
+- An **arithmetic recheck** that recomputes every numeric claim in the
+  reviewed material against the canonical specification.
+- A **statistical interpretation** section that classifies thresholds as
+  `CANONICAL`, `HEURISTIC`, or `DETERMINISTIC WINDOW FEATURE`, and flags
+  null-model mismatches.
+- A **failure mode analysis** that enumerates the conditions under which the
+  reviewed method would emit false positives or false negatives.
+- A **canonical spec patches** block of explicit warnings to copy verbatim
+  into the reviewed specification.
+
+### Example Review: Prime Gap Entropy Collapse
+
+The canonical example shipped with the initial DeepSeek review tracking is
+the prime-gap entropy-collapse analysis:
+
+| Artifact | Path |
+|---|---|
+| Primary answer | `shared-data/artifacts/deepseek_review/prime_gap_entropy_collapse_deepseek_deepseek-v3.2_20260512T033551Z.md` |
+| Primary receipt | `shared-data/artifacts/deepseek_review/prime_gap_entropy_collapse_deepseek_deepseek-v3.2_20260512T033551Z.receipt.json` |
+| Continuation answer | `shared-data/artifacts/deepseek_review/prime_gap_entropy_collapse_deepseek_deepseek-v4-flash_continuation_20260512T033849Z.md` |
+| Continuation receipt | `shared-data/artifacts/deepseek_review/prime_gap_entropy_collapse_deepseek_deepseek-v4-flash_continuation_20260512T033849Z.receipt.json` |
+
+Context files cited by the primary receipt:
+
+- `6-Documentation/docs/distilled/ArithmeticSpec_Corrected_2026-05-11.md`
+- `shared-data/data/stack_solidification/prime_gap_k21_rerun_receipt_2026-05-11.md`
+- `0-Core-Formalism/lean/Semantics/Semantics/HCMMR/Kernels/EntropyCollapseDetector.lean`
+
+The review covers:
+
+- **Arithmetic verification** of the canonical spec (crossing counts, `D₂`,
+  `σ_q`, Kendall SD, and exact tail probabilities at `W=8`).
+- **Statistical interpretation** of threshold selection — confirming `K=7`
+  as non-selective (94.57% FPR under random-permutation null) and `K=21` as a
+  heuristic ~5% FPR calibration (strict `>21`: 3.05%, inclusive `>=21`: 5.43%).
+- **Failure mode analysis** for the random-permutation null model when
+  applied to prime gaps (ties, non-uniform marginal distribution, local
+  dependence make the FPR estimates unreliable).
+- **Canonical spec patches** that add HEURISTIC warnings, clarify that
+  window-level `σ_q` and `D₂` are deterministic features rather than
+  estimators, document the null-model mismatch for prime gaps, and address
+  multiple-testing and edge-effect considerations.
+- **Continuation** (deepseek-v4-flash) extending the canonical spec patches
+  with predictive-versus-contemporaneous fusion semantics, ground-truth
+  caveats, parameter-sensitivity reporting requirements, edge-effect handling,
+  reproducibility requirements, and an interpretation caveat for the final
+  verdict surface.
+
+---
+
+## Adding a New Review
+
+When emitting new review artifacts:
+
+1. Write the answer to
+   `shared-data/artifacts/deepseek_review/<topic>_deepseek_<model>_<ISO-Z>.md`.
+   The literal `_deepseek_` segment is the **provider tag** and is held
+   constant across all DeepSeek-family reviews; `<model>` is the specific
+   model identifier (e.g. `deepseek-v3.2`, `deepseek-v4-flash`). The two
+   segments are kept separate so future provider-level tooling (rate caps,
+   budget accounting, fleet-wide audits) can filter on the provider tag
+   without parsing the `<model>` slug. This is why the canonical example
+   filenames contain `_deepseek_deepseek-v3.2_` — the doubled `deepseek` is
+   intentional and reflects `<provider>_<model>`.
+2. Write the matching receipt alongside it with the same stem and
+   `.receipt.json` suffix, using `ollama_deepseek_review_receipt_v1` for the
+   primary review and `ollama_deepseek_review_continuation_receipt_v1` for any
+   continuation.
+3. Populate `context_files` with repo-relative paths to every file consumed
+   by the prompt so future agents can reproduce the prompt body. Continuation
+   receipts omit `context_files` and `message_keys` records the alternate
+   shape of the continuation response; consumers reconstruct continuation
+   context via the primary receipt indexed by `previous_answer_path` (see
+   [[#Reconstructing context for continuations]] above).
+4. Record `prompt_sha256` and `answer_sha256` for integrity verification.
+5. Commit the answer and receipt together — the receipt is meaningless
+   without the answer it indexes, and the answer is unverifiable without the
+   receipt.
+
+---
+
+## Related
+
+- [[Build-System]] — pinned Python interpreter that drives the review adapter
+  and ensures prompt-hash reproducibility across runs.
+- `5-Applications/tools-scripts/llm/deepseek_review_adapter.py` — adapter that
+  emits the receipt + answer pair.
+- `6-Documentation/docs/distilled/` — canonical specs that reviews validate
+  against (e.g. `ArithmeticSpec_Corrected_2026-05-11.md`).
+- `0-Core-Formalism/lean/Semantics/Semantics/HCMMR/Kernels/` — Lean kernels
+  cross-referenced as review context.
--- a/6-Documentation/wiki/Home.md
+++ b/6-Documentation/wiki/Home.md
@ -9,6 +9,9 @@
 | `docs/GLOSSARY.md` | Project-wide glossary — all terms across all domains |
 | `wiki/Concept-Archive.md` | Concept archive — canonical, speculative, held, lossy, retired, and abandoned terms |
 | `docs/BEGINNERS_MAP.md` | Narrative onboarding — what this stack is and why it exists |
+| `wiki/Build-System.md` | Build system — pinned Python (`3.11.15`), uv integration, VSCode tasks, npm scripts |
+| `wiki/Text-to-CAD-Environment.md` | Text-to-CAD environment — CAD-specific venv sequencing, `build123d` / `OCP` verification, agent contract |
+| `wiki/DeepSeek-Review-Process.md` | AI-assisted mathematical review — receipt schema, two-stage pipeline, prime-gap example |
 | `docs/VISION_NORTH_STAR.md` | Long-term vision — where the stack converges |
 | `docs/PHI_CENTER_REVAMP.md` | Phi-centered cockpit architecture — cost/efficiency comparison root |
 | `docs/BRAIN_AS_MANIFOLD.md` | Biological manifold theory — hyperbolic geometry, intelligence ladder, Physarum |
@ -63,3 +66,19 @@
 | `CITATION.cff` | Terminology neutrality map — technical terms vs cultural aliases |
 | `PROJECT_MAP.md` | Repository-wide directory structure and module map |
 | `MATH_MODEL_MAP.tsv` | Full equation registry indexed by phinary ID |
+
+## Build System & Environments
+
+| Document | Summary |
+|---|---|
+| `wiki/Build-System.md` | Python `3.11.15` pin via `.python-version`, uv install path, VSCode interpreter, npm script surface |
+| `wiki/Text-to-CAD-Environment.md` | CAD-specific sequencing that consumes the canonical setup commands in `wiki/Build-System.md` |
+| `GETTING_STARTED.md` | Lean toolchain installation and end-to-end Lean build walkthrough |
+
+## AI-Assisted Review
+
+| Document | Summary |
+|---|---|
+| `wiki/DeepSeek-Review-Process.md` | Receipt schema (`ollama_deepseek_review_receipt_v1`), two-stage pipeline (`deepseek-v3.2` + `deepseek-v4-flash` continuation), prime-gap entropy-collapse example |
+| `shared-data/artifacts/deepseek_review/` | Paired answer + receipt artifacts for each review run |
+| `5-Applications/tools-scripts/llm/deepseek_review_adapter.py` | Adapter that emits the answer / receipt pair |
--- a/6-Documentation/wiki/Text-to-CAD-Environment.md
+++ b/6-Documentation/wiki/Text-to-CAD-Environment.md
@ -0,0 +1,60 @@
+# Text-to-CAD Environment
+
+> **Source:** [[Home|Wiki Home]] · [[Build-System]] · `5-Applications/text-to-cad/README.md` · `5-Applications/text-to-cad/AGENTS.md`
+
+The Text-to-CAD harness (`5-Applications/text-to-cad/`) drives agentic 3D
+modeling by exposing `build123d` and `OCP` (OpenCascade) bindings to coding
+agents like Codex and Claude Code. The canonical VSCode task and npm script
+matrix lives in [[Build-System]]. This page stays focused on the CAD-specific
+environment shape, sequencing, and agent constraints.
+
+For the agent contract (file-targeted skills, viewer handoff rules, prompt-ref
+grammar), see `5-Applications/text-to-cad/AGENTS.md`.
+
+---
+
+## CAD Environment Setup
+
+The Text-to-CAD harness uses a repo-local virtual environment at
+`5-Applications/text-to-cad/.venv` that is created from the pinned Python
+interpreter described in [[Build-System#Python Environment Management]].
+
+### Bootstrap order
+
+```bash
+# 1. From the repository root
+npm run install-python       # uv python install 3.11.15
+npm run setup-cad-env        # creates 5-Applications/text-to-cad/.venv
+npm run verify-cad           # prints "CAD dependencies OK" on success
+```
+
+The `Setup CAD Environment` task is idempotent — re-running it against an
+existing `.venv` will reuse it and only update pinned packages. To force a
+clean rebuild, remove `5-Applications/text-to-cad/.venv` first.
+
+For the exact VSCode task labels, npm script definitions, and command bodies,
+use [[Build-System]]. Do not duplicate that matrix here; when a task or script
+changes, update [[Build-System]] and keep this page limited to the CAD workflow
+that consumes those commands.
+
+### Agent contract
+
+The harness's `AGENTS.md` requires all CAD tooling to be invoked through
+`./.venv/bin/python` from `5-Applications/text-to-cad/`. The `Verify CAD
+Dependencies` task is the canonical preflight check before running any of the
+skill scripts (`gen_step_part`, `gen_step_assembly`, `gen_urdf`, `cadref`,
+`snapshot`). If the verification fails, agents are expected to re-run the
+`Setup CAD Environment` task before attempting CAD generation.
+
+---
+
+## Related
+
+- [[Build-System]] — Python version pinning, uv integration, VSCode interpreter
+  configuration that this environment builds on.
+- `5-Applications/text-to-cad/README.md` — user-facing quick start, feature
+  list, and bundled skill catalog.
+- `5-Applications/text-to-cad/AGENTS.md` — agent contract, viewer handoff
+  rules, and common harness commands.
+- `5-Applications/text-to-cad/requirements-cad.txt` — pinned CAD dependency
+  set installed into `.venv`.