Install a pinned native SpecGraph runtime for product workspaces

.github/workflows/native-runtime.yml

@@ -0,0 +1,40 @@
+name: Native SpecGraph runtime
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  native-install:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install test prerequisites
+        run: python -m pip install -e '.[dev]'
+      - name: Verify installed runtime in separate workspaces
+        run: >-
+          python tests/native_runtime_smoke.py
+          --repo "$GITHUB_WORKSPACE"
+          --revision "$GITHUB_SHA"
+          --root "$RUNNER_TEMP/native-runtime-smoke"
+          --output "$RUNNER_TEMP/native-runtime-observation.json"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: native-runtime-observation-${{ matrix.python-version }}
+          path: ${{ runner.temp }}/native-runtime-observation.json

CONTRIBUTING.md

@@ -6,6 +6,15 @@ Use [AGENTS.md](AGENTS.md) for executable agent rules. Use this file for the hum
 
 ## Distribution verification
 
+Proposal 0231 installs a full pinned source snapshot alongside a separate Python
+environment. Exercise the installed launcher against distinct external workspace
+roots; source-only tests cannot prove policy resources or tool paths are usable.
+Record the selected commit and distinguish deterministic probes from real
+executor runs and canonical approval.
+Resolve user-supplied local Git sources against the caller's directory before
+changing the Git subprocess directory. Exercise a relative source in the actual
+installation smoke, and preserve Git URL and SSH remote syntax.
+
 Distribution changes must exercise the built artifact, not just imports from
 the source checkout. For portable SpecDraft (proposal 0230), build a wheel through
 its source distribution, install it into a separate pipx environment, then run

README.md

@@ -14,6 +14,31 @@ It turns product intent into a structured, governed, and execution-ready graph t
 
 SpecGraph makes it possible to move from intent to implementation through specifications that remain understandable to humans, verifiable by machines, and traceable across the full software lifecycle.
 
+## Native SpecGraph runtime
+
+Proposal 0231 adds a separately installed snapshot of the full tracked SpecGraph
+source and a Python environment. It uses a full Git SHA and a new destination:
+
+```sh
+# Select a trusted full commit SHA that includes tools/native_runtime.py.
+REVISION=<full-commit-sha>
+curl -fsSL "https://raw.githubusercontent.com/0al-spec/SpecGraph/$REVISION/tools/native_runtime.py" \
+  -o /tmp/specgraph-native-install.py
+python3 /tmp/specgraph-native-install.py install \
+  --source https://github.com/0al-spec/SpecGraph.git \
+  --revision "$REVISION" --destination <new-runtime-directory>
+<new-runtime-directory>/specgraph-runtime --workspace <project-workspace> \
+  init -- --project-id <project-id>
+<new-runtime-directory>/specgraph-runtime --workspace <project-workspace> \
+  supervisor -- --target-spec <spec-id> --dry-run
+```
+
+The selected revision must include the installer. Python 3.10+, Git and network
+access for Python dependencies are required. Existing project history, agent
+executor setup and workspace initialization are separate from installation.
+See [proposal 0231](docs/proposals/0231_native_specgraph_runtime.md) for
+supported operations and limitations.
+
 ## Installed SpecDraft
 
 Proposal 0230 provides a separate Python runtime for notes and local preview.

Sources/SpecGraph/Documentation.docc/NativeRuntime.md

@@ -0,0 +1,33 @@
+# Native SpecGraph runtime
+
+Proposal 0231 describes a pinned source snapshot for an agent running SpecGraph
+from independent product workspaces. The installer ships tracked tools and
+policy resources without the engine Git history; it creates a separate Python
+environment and a launcher. Python 3.10+, Git and access to dependencies are
+prerequisites. The local source commit is recorded in `runtime.json`.
+
+`tools/native_runtime.py install` takes an explicit Git source, full revision
+and new destination. It never overwrites an existing destination. Failure leaves
+an incomplete installation without the `runtime.json` ready marker.
+To bootstrap without a developer checkout, download that script from the same
+trusted full commit on `raw.githubusercontent.com` before invoking it; the
+repository README gives the command. The chosen revision must contain the script.
+Local Git source paths are resolved against the caller's directory before Git
+enters its temporary repository; Git URL and SSH remote syntax stays unchanged.
+The installed-runtime smoke uses a relative source to preserve this behavior.
+
+The launcher accepts `--workspace` and `init`, `next-move`, `supervisor` or
+`draft`. `init` runs the existing initializer from the installed source root;
+other operations run in the selected product workspace. Project-owned Git,
+notes, specs and runs are not installed data. Each workspace must be explicitly
+selected, and an existing workspace or Git history is not overwritten by setup.
+
+Current supervisor refinement requires its configured Codex executor. ASP is
+future work, and the invoking agent is not automatically the child executor.
+The existing initializer's `specs/nodes` and `.worktrees` limitations persist.
+Unix platforms are the target; relocation, offline installation, Docker and a
+full cross-repository evidence binding are not claimed by this slice.
+
+Focused tests cover snapshot safety and installer refusal. An installed-runtime
+probe exercises a real snapshot and separate project roots; no canonical
+acceptance or live provider inference follows from that observation.

Sources/SpecGraph/Documentation.docc/SpecGraph.md

@@ -110,6 +110,7 @@ The canonical source files remain in the repository:
 - <doc:ConversationNotes>
 - <doc:SpecDraft>
 - <doc:SpecDraftDistribution>
+- <doc:NativeRuntime>
 
 ### Proposed composition comparison
 

docs/archive/proposal_sources/0231_native_specgraph_runtime.md

@@ -0,0 +1,17 @@
+# Source: native SpecGraph runtime
+
+The operator described the intended product explicitly:
+
+> Для executor у меня есть ASP - agent surface protocol, но он ещё в разработке. Поэтому меня бы устроил такой вариант, где каким-то образом (скриптом?) создается копия стабильного SpecGraph со всеми инструмениами, разворачивается окружение Python/git/etc и далее агент-разработчик работает с супервизором и тп над конкретным проектом…
+
+The operator subsequently requested: «Да, начинай по канону правок».
+The SpecDraft note `specgraph_native_runtime` retains this quote at revision
+`1b44588d2b6640de86bd56f219fd4735`; the original message ID and timestamp were
+not independently attested. The supervisor intake helper created a pre-canonical
+captured intent and an under-review proposal-lane link. This is not approval of
+canonical graph publication or a claim of an executor/model run.
+
+Proposal 0227 describes the product workspace boundary; 0230 packages SpecDraft.
+This proposal packages a pinned checkout snapshot of the existing engine and
+does not introduce ASP or change either proposal's authority. Git, an appropriate
+Python interpreter, and the executor remain externally selected prerequisites.

docs/proposals/0231_native_specgraph_runtime.intent.yaml

@@ -0,0 +1,18 @@
+id: SG-RFC-0231
+kind: proposal
+status: draft
+proposal_ref: docs/proposals/0231_native_specgraph_runtime.md
+provenance:
+  authored_by: agent
+  authority: proposal_draft
+  source_ref: docs/archive/proposal_sources/0231_native_specgraph_runtime.md
+atoms:
+  intents:
+  - id: SG-NATIVE-SNAPSHOT
+    statement: An installation retains a full tracked SpecGraph snapshot identified by the exact source commit without retaining its Git history.
+  - id: SG-NATIVE-ENVIRONMENT
+    statement: A separately created Python environment installs the snapshot dependencies and a launcher without overwriting an existing installation.
+  - id: SG-NATIVE-WORKSPACES
+    statement: One installed runtime runs existing product commands against explicitly selected independent workspace roots.
+  - id: SG-NATIVE-AUTHORITY
+    statement: The installed supervisor retains existing executor and review authority without pretending to implement ASP or canonical acceptance.

docs/proposals/0231_native_specgraph_runtime.md

@@ -0,0 +1,66 @@
+# Native SpecGraph runtime
+
+## Status and source
+
+Synchronous runtime slice for review. The [source](../archive/proposal_sources/0231_native_specgraph_runtime.md), [attributed note](../reviews/0231_native_runtime/source-notes.json), [intake](../reviews/0231_native_runtime/intake.json) and [draft obligations](0231_native_specgraph_runtime.intent.yaml) precede canonical acceptance.
+
+See the [installed-runtime observation](../reviews/0231_native_runtime/verification.json)
+and [pipeline observation](../reviews/0231_native_runtime/pipeline.json).
+
+An agent needs a stable installed snapshot while the SpecGraph developer
+checkout evolves independently. The existing Product Workspace model remains
+the project boundary; source snapshots and Python environments are versioned
+separately from project-owned graphs, runs and Git history.
+
+## Bounded contract
+
+`tools/native_runtime.py install --source <git-repository> --revision <full-sha>
+--destination <new-directory>` fetches that exact commit into temporary bare Git,
+archives tracked files without history, creates a separate Python environment,
+installs dependencies, and produces a launcher and a completed receipt. It fails
+if the destination exists, preserves incomplete installations on error, and
+never adds projects or their data to the installed runtime. Python >=3.10, Git,
+network access to dependencies and Unix venv layout are prerequisites.
+The bootstrap script can be downloaded from the same chosen Git commit; the
+consumer does not need an existing developer checkout.
+Relative Git source paths are resolved from the caller's directory before
+entering the temporary Git repository; URL and SSH remote forms are preserved.
+
+The installed `specgraph-runtime --workspace <workspace> init -- --project-id <id>`
+invokes the existing product initializer from the installed engine root.
+`next-move`, `supervisor` and `draft` forward arguments with the selected
+workspace as current directory. This retains existing CLI output and authority
+semantics. Existing source facades remain available. A workspace with existing
+Git history keeps it; the installer does not create or overwrite project Git.
+
+The installed snapshot contains tracked source files, not `.git`, uncommitted
+changes, credentials, existing worktrees, local notes or generated artifacts.
+The launcher is colocated with its Python environment and is not relocatable;
+reinstall at a new path. One installation can serve separate workspace roots.
+Current supervisor refinement launches a configured `codex exec` child; ASP is
+a future integration. An agent invoking the launcher is not itself the child
+executor. No package-index release, native Windows support, offline installation,
+automatic upgrades, broad integration bundle or Docker image is claimed.
+
+## Verification and limits
+
+Focused tests verify conflict preservation, unsafe archive rejection, full SHA
+and incomplete installation rejection. A real isolated install and product
+workspace probe must bind to the installed commit and report exactly what ran.
+The existing initializer does not create `specs/nodes`, and after supervisor
+creates `.worktrees` a repeated initializer may report it as unexpected; these
+pre-existing limitations are not silently altered by this distribution slice.
+Real provider calls, canonical publication, cross-repository code trace and
+hosted evidence admission are outside the technical smoke's claims.
+The actual repeat-init probe failed on `.worktrees` after the synthetic
+refinement, as expected from proposal 0227; this is an open usability defect.
+
+## Pipeline
+
+Captured user intent → proposal lane → draft obligations → implementation →
+tests/observations. SG-SPEC-0007 constrains the attribution boundary; references
+are governance context, not a canonical Requirement binding. The named
+`RUNTIME_READY_SPEC` checks that a versioned receipt records a completed install
+and identifies a full source commit. It does not verify the current bytes of the
+installed tree. CLI forwarding, archive copying and environment creation are I/O
+mechanics and do not expand supervisor authority.

docs/reviews/0231_native_runtime/intake.json

@@ -0,0 +1,9 @@
+{
+  "artifact_kind": "native_runtime_intake",
+  "schema_version": 1,
+  "source_notes_revision": "1b44588d2b6640de86bd56f219fd4735",
+  "source_node": "specgraph_native_runtime",
+  "source_notes_ref": "docs/reviews/0231_native_runtime/source-notes.json",
+  "user_instruction": "Да, начинай по канону правок",
+  "canonical": false
+}

docs/reviews/0231_native_runtime/pipeline.json

@@ -0,0 +1,12 @@
+{
+  "artifact_kind": "native_runtime_pipeline_observation",
+  "canonical_publication": "not_performed",
+  "canonical_requirement_binding": "not_created",
+  "intent_handle": "user_intent::specgraph-native-runtime-20261027",
+  "intent_status": "captured",
+  "model_execution": "not_performed",
+  "proposal_handle": "proposal::0231",
+  "proposal_status": "under_review",
+  "schema_version": 1,
+  "source_notes_revision": "1b44588d2b6640de86bd56f219fd4735"
+}

docs/reviews/0231_native_runtime/relative-source-verification.json

@@ -0,0 +1,33 @@
+{
+  "artifact_kind": "native_runtime_observation",
+  "canonical_publication": "not_evaluated",
+  "checks": [
+    "exact_snapshot_without_git",
+    "isolated_venv",
+    "path_with_spaces",
+    "init",
+    "product_advisor",
+    "targeted_supervisor_dry_run",
+    "specdraft_read"
+  ],
+  "executor": "deterministic_fixture_not_a_real_agent",
+  "installer_sha256": "3024b78faab17f4b920e02b1a3dff30961fae9ab4d48139b3f381aa6bd6aa8c0",
+  "python_version": "3.12.11",
+  "refinement": {
+    "gate_state": "review_pending",
+    "isolation_mode": "git_worktree",
+    "outcome": "done"
+  },
+  "review_thread": "https://github.com/0al-spec/SpecGraph/pull/813#discussion_r4393159271",
+  "schema_version": 1,
+  "source_argument": ".",
+  "source_commit": "df773af49d92121b9261dd5369fe0868086e5569",
+  "source_files_sha256": {
+    "tests/native_runtime_smoke.py": "744eff5a57fabeafc7f4926d0a5c7791a73d9a42d8dccab5ef984c982fba1bb3",
+    "tests/test_native_runtime.py": "1e76f5f3dfd5ae94df860ee873c8a0063fd5a201121cd9956e38d3c2a7cc7596",
+    "tools/native_runtime.py": "3024b78faab17f4b920e02b1a3dff30961fae9ab4d48139b3f381aa6bd6aa8c0"
+  },
+  "source_resolution": "relative to the caller checkout before temporary git -C",
+  "status": "passed",
+  "synthetic_workspaces": 2
+}

docs/reviews/0231_native_runtime/source-notes.json

@@ -0,0 +1,37 @@
+{
+  "artifact_kind": "conversation_notes",
+  "schema_version": 1,
+  "revision": "1b44588d2b6640de86bd56f219fd4735",
+  "canonical": false,
+  "nodes": [
+    {
+      "id": "specgraph_native_runtime",
+      "label": "Стабильный установленный SpecGraph",
+      "detail": "Снимок движка и отдельное Python-окружение; агент использует supervisor в workspace проекта. ASP — будущий executor.",
+      "parent_id": "specdraft_portable_runtime",
+      "sources": [
+        {
+          "ref": "conversation:2026-10-27/native-runtime-request",
+          "quote": "Для executor у меня есть ASP - agent surface protocol, но он ещё в разработке. Поэтому меня бы устроил такой вариант, где каким-то образом (скриптом?) создается копия стабильного SpecGraph со всеми инструмениами, разворачивается окружение Python/git/etc и далее агент-разработчик работает с супервизором и тп над конкретным проектом…",
+          "speaker": "human"
+        }
+      ]
+    }
+  ],
+  "links": [],
+  "reviews": [],
+  "omitted_nodes": 31,
+  "history": [
+    {
+      "revision": "1b44588d2b6640de86bd56f219fd4735",
+      "parent_revision": "2bf2408ebe0148f6a5c6a548f305e67a",
+      "captured_at": "2026-10-27T18:45:26.818269+00:00",
+      "source": {
+        "ref": "conversation:2026-10-27/native-runtime-request",
+        "quote": "Для executor у меня есть ASP - agent surface protocol, но он ещё в разработке. Поэтому меня бы устроил такой вариант, где каким-то образом (скриптом?) создается копия стабильного SpecGraph со всеми инструмениами, разворачивается окружение Python/git/etc и далее агент-разработчик работает с супервизором и тп над конкретным проектом…",
+        "speaker": "human"
+      }
+    }
+  ],
+  "snapshot_path": "conversation_memory/sketches/hypercode-conversation-poc/revisions/1b44588d2b6640de86bd56f219fd4735"
+}

docs/reviews/0231_native_runtime/specdraft.md

@@ -0,0 +1,13 @@
+# Draft: native SpecGraph runtime
+
+Review address `req.specgraph.native-runtime`; `review_pending`, `canonical: false`.
+Source: [proposal 0231](../../proposals/0231_native_specgraph_runtime.md),
+[intake](intake.json) and [source notes](source-notes.json).
+
+The four draft obligations map to `tools/native_runtime.py::install`,
+`extract_snapshot`, and `run`; `tests/test_native_runtime.py` checks the
+destructive/error boundaries. The installed-runtime smoke must additionally
+exercise two independent workspaces, existing supervisor behavior and receipt
+provenance. This draft is not a canonical Requirement or an admission decision.
+`RUNTIME_READY_SPEC` in `tools/native_runtime_ready_spec.py` expresses the
+versioned installation readiness decision using `RuntimeReadyFacts`.