specromancy-engine 0.1.3__tar.gz

specromancy_engine-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pavel Golitsyn
+
+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.

specromancy_engine-0.1.3/MANIFEST.in

@@ -0,0 +1,21 @@
+# Start from an allowlist, including when setuptools has a cached SOURCES.txt.
+global-exclude *
+include pyproject.toml MANIFEST.in README.md LICENSE setup.py build_readme.py
+recursive-include src/specromancy_engine *.py
+include src/specromancy_engine/schemas/*.json
+include src/specromancy_engine.egg-info/PKG-INFO
+include src/specromancy_engine.egg-info/SOURCES.txt
+include src/specromancy_engine.egg-info/dependency_links.txt
+include src/specromancy_engine.egg-info/entry_points.txt
+include src/specromancy_engine.egg-info/top_level.txt
+include examples/release-documentation/README.md
+include examples/release-documentation/AGENTS.md
+include examples/release-documentation/.gitignore
+include examples/release-documentation/sample-changes.md
+recursive-include examples/release-documentation/workflow *.toml *.md
+include examples/release-documentation/.agents/skills/pipeline/SKILL.md
+include examples/release-documentation/.agents/skills/draft-release-notes/SKILL.md
+include examples/release-documentation/.agents/skills/review-release-notes/SKILL.md
+include docs/README.md
+recursive-include docs/guides *.md
+recursive-include docs/reference *.md

specromancy_engine-0.1.3/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: specromancy-engine
+Version: 0.1.3
+Summary: Harness-agnostic agentic pipeline framework
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PavelGolitsyn/specromancy-engine
+Project-URL: Documentation, https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/README.md
+Project-URL: Issues, https://github.com/PavelGolitsyn/specromancy-engine/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license-file
+Dynamic: project-url
+
+# Specromancy Engine
+
+Specromancy Engine is a dependency-free Python 3.11+ framework for portable,
+artifact-based agent workflows. A declarative pipeline and canonical skills
+define the work; a small CLI validates transitions and persists recoverable run
+state independently of any harness conversation.
+
+Specromancy Engine targets Linux and macOS. The release verification matrix covers
+Ubuntu 24.04 and macOS 15 with Python 3.11.15 and 3.14.4. Windows is unverified
+and is not claimed as supported in this release.
+
+## Use the engine in another project
+
+Install from PyPI into your project's Python environment:
+
+```sh
+python -m pip install specromancy-engine
+specromancy --help
+```
+
+Follow the [installation guide][installation] to create an isolated
+environment, add the engine to an existing Python project's dependencies, or
+install a local wheel. The
+[release-documentation consumer][consumer-example]
+provides an executable two-phase example.
+
+Your project explicitly supplies its registry, graphs, templates, instructions,
+and skills. The engine emits actions and verifies agent output; it does not
+launch an LLM, provide credentials, generate prose, or publish results.
+
+## Contributor quickstart
+
+From a Git checkout, create a dedicated development environment and install
+the package in editable mode:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+bin/specromancy init "describe the requested change" --pipeline implementation
+bin/specromancy status RUN_ID
+bin/specromancy resume RUN_ID
+python -m unittest discover
+bin/specromancy adapters generate --check
+```
+
+`init` returns the run ID and next action. Follow the emitted action packet and
+use its exact output path, skill, mutation policy, and final validation command.
+Runtime data is written only under ignored `.specromancy/runs/` storage.
+
+The `specromancy-engine` package provides the `specromancy` console
+command and `python -m specromancy_engine`. The checkout wrappers
+`bin/specromancy` and `adapters/generate.py` also work without installation as
+producer-checkout conveniences. Consumers install the dependency; they do not
+copy engine source or launchers into their projects.
+Python consumers import `specromancy_engine`. Run and event formats use schema
+version 1. See the [public contracts][contracts] for supported
+interfaces, persistence, and ownership rules.
+
+## Customize the workflow
+
+Register pipelines in `workflow/pipelines.toml` and keep their graphs under
+`workflow/pipelines/`. Every new run requires `--pipeline ID`; there is no default.
+Adapters generate a `specromancy-<id>` launch skill for each registration.
+The editable graphs and shared artifact templates live in [`workflow/`][workflow-directory].
+These top-level resources configure this repository's own development workflow;
+they are not automatically installed consumer defaults.
+Phase procedures live in [`.agents/skills/`][skills-directory] for native harness
+discovery, and repository-wide agent constraints live in [`AGENTS.md`][agent-instructions].
+The Python package under `src/specromancy_engine/` is the generic engine, not a workflow
+customization surface. Start with the
+[`workflow/README.md`][workflow-guide] customization map.
+
+## Documentation
+
+- [Documentation and repository map][documentation]
+- [Consumer installation][installation]
+- [Distribution verification and CI][distribution-verification]
+- [Publishing a release][releasing]
+- [Architecture][architecture]
+- [CLI reference][cli]
+- [Pipeline authoring][pipeline-authoring]
+- [Harness usage][harnesses]
+- [Public contracts][contracts]
+- [Historical plans and refactoring records][history]
+
+The engine intentionally does not launch harnesses, migrate active runs between
+pipeline versions, provide remote storage or distributed locking, authenticate
+approvers, or implement parallel graph joins. See the architecture document for
+the complete limitations and safety boundary.
+
+[installation]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/guides/installation.md
+[consumer-example]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/examples/release-documentation/README.md
+[contracts]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/reference/contracts.md
+[workflow-directory]: https://github.com/PavelGolitsyn/specromancy-engine/tree/v0.1.3/workflow
+[skills-directory]: https://github.com/PavelGolitsyn/specromancy-engine/tree/v0.1.3/.agents/skills
+[agent-instructions]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/AGENTS.md
+[workflow-guide]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/workflow/README.md
+[documentation]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/README.md
+[distribution-verification]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/guides/distribution-verification.md
+[releasing]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/guides/releasing.md
+[architecture]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/reference/architecture.md
+[cli]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/reference/cli.md
+[pipeline-authoring]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/guides/authoring-pipelines.md
+[harnesses]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/guides/harnesses.md
+[history]: https://github.com/PavelGolitsyn/specromancy-engine/blob/v0.1.3/docs/implementation-history/README.md

specromancy_engine-0.1.3/README.md

@@ -0,0 +1,106 @@
+# Specromancy Engine
+
+Specromancy Engine is a dependency-free Python 3.11+ framework for portable,
+artifact-based agent workflows. A declarative pipeline and canonical skills
+define the work; a small CLI validates transitions and persists recoverable run
+state independently of any harness conversation.
+
+Specromancy Engine targets Linux and macOS. The release verification matrix covers
+Ubuntu 24.04 and macOS 15 with Python 3.11.15 and 3.14.4. Windows is unverified
+and is not claimed as supported in this release.
+
+## Use the engine in another project
+
+Install from PyPI into your project's Python environment:
+
+```sh
+python -m pip install specromancy-engine
+specromancy --help
+```
+
+Follow the [installation guide][installation] to create an isolated
+environment, add the engine to an existing Python project's dependencies, or
+install a local wheel. The
+[release-documentation consumer][consumer-example]
+provides an executable two-phase example.
+
+Your project explicitly supplies its registry, graphs, templates, instructions,
+and skills. The engine emits actions and verifies agent output; it does not
+launch an LLM, provide credentials, generate prose, or publish results.
+
+## Contributor quickstart
+
+From a Git checkout, create a dedicated development environment and install
+the package in editable mode:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+bin/specromancy init "describe the requested change" --pipeline implementation
+bin/specromancy status RUN_ID
+bin/specromancy resume RUN_ID
+python -m unittest discover
+bin/specromancy adapters generate --check
+```
+
+`init` returns the run ID and next action. Follow the emitted action packet and
+use its exact output path, skill, mutation policy, and final validation command.
+Runtime data is written only under ignored `.specromancy/runs/` storage.
+
+The `specromancy-engine` package provides the `specromancy` console
+command and `python -m specromancy_engine`. The checkout wrappers
+`bin/specromancy` and `adapters/generate.py` also work without installation as
+producer-checkout conveniences. Consumers install the dependency; they do not
+copy engine source or launchers into their projects.
+Python consumers import `specromancy_engine`. Run and event formats use schema
+version 1. See the [public contracts][contracts] for supported
+interfaces, persistence, and ownership rules.
+
+## Customize the workflow
+
+Register pipelines in `workflow/pipelines.toml` and keep their graphs under
+`workflow/pipelines/`. Every new run requires `--pipeline ID`; there is no default.
+Adapters generate a `specromancy-<id>` launch skill for each registration.
+The editable graphs and shared artifact templates live in [`workflow/`][workflow-directory].
+These top-level resources configure this repository's own development workflow;
+they are not automatically installed consumer defaults.
+Phase procedures live in [`.agents/skills/`][skills-directory] for native harness
+discovery, and repository-wide agent constraints live in [`AGENTS.md`][agent-instructions].
+The Python package under `src/specromancy_engine/` is the generic engine, not a workflow
+customization surface. Start with the
+[`workflow/README.md`][workflow-guide] customization map.
+
+## Documentation
+
+- [Documentation and repository map][documentation]
+- [Consumer installation][installation]
+- [Distribution verification and CI][distribution-verification]
+- [Publishing a release][releasing]
+- [Architecture][architecture]
+- [CLI reference][cli]
+- [Pipeline authoring][pipeline-authoring]
+- [Harness usage][harnesses]
+- [Public contracts][contracts]
+- [Historical plans and refactoring records][history]
+
+The engine intentionally does not launch harnesses, migrate active runs between
+pipeline versions, provide remote storage or distributed locking, authenticate
+approvers, or implement parallel graph joins. See the architecture document for
+the complete limitations and safety boundary.
+
+[installation]: docs/guides/installation.md
+[consumer-example]: examples/release-documentation/README.md
+[contracts]: docs/reference/contracts.md
+[workflow-directory]: workflow/
+[skills-directory]: .agents/skills/
+[agent-instructions]: AGENTS.md
+[workflow-guide]: workflow/README.md
+[documentation]: docs/README.md
+[distribution-verification]: docs/guides/distribution-verification.md
+[releasing]: docs/guides/releasing.md
+[architecture]: docs/reference/architecture.md
+[cli]: docs/reference/cli.md
+[pipeline-authoring]: docs/guides/authoring-pipelines.md
+[harnesses]: docs/guides/harnesses.md
+[history]: docs/implementation-history/README.md

specromancy_engine-0.1.3/build_readme.py

@@ -0,0 +1,87 @@
+"""Build-only README metadata, independent of Git and the engine runtime.
+
+Local README destinations use single-line Markdown reference definitions.
+Directory destinations end in '/'; image references use labels beginning with
+'image-'. These explicit conventions also work in an sdist that omits the
+linked repository files. Inline links should use absolute URLs.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+import posixpath
+import re
+import tomllib
+from urllib.parse import quote, urlsplit, urlunsplit
+
+
+REFERENCE = re.compile(r"^( {0,3}\[([^\]\n]+)\]:[ \t]*)(<[^>\n]+>|\S+)(.*)$")
+FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
+
+
+def absolute_url(destination: str, repository: str, version: str, *, image: bool = False) -> str:
+    """Resolve a repository-root destination without inspecting the filesystem."""
+    parts = urlsplit(destination)
+    if parts.scheme or parts.netloc:
+        return destination
+    path = posixpath.normpath(parts.path.lstrip("/") or "README.md")
+    if path == ".." or path.startswith("../") or "\\" in path:
+        raise ValueError(f"README link escapes the repository: {destination}")
+    tag = quote(f"v{version}", safe="")
+    kind = "tree" if parts.path.endswith("/") else "blob"
+    if image:
+        # GitHub's raw endpoint serves image bytes instead of an HTML file view.
+        kind = "raw"
+    path = quote(path, safe="/%:@!$&'()*+,;=-._~")
+    base = f"{repository.rstrip('/')}/{kind}/{tag}/{path}"
+    return urlunsplit((*urlsplit(base)[:3], parts.query, parts.fragment))
+
+
+def render_readme(source: str, repository: str, version: str) -> str:
+    """Rewrite reference destinations, preserving prose, titles, and code blocks."""
+    result = []
+    fence = ""
+    for line in source.splitlines(keepends=True):
+        marker = FENCE.match(line)
+        if fence:
+            if marker and marker[1][0] == fence[0] and len(marker[1]) >= len(fence) and not marker[2].strip():
+                fence = ""
+            result.append(line)
+            continue
+        if marker:
+            fence = marker[1]
+            result.append(line)
+            continue
+        match = REFERENCE.match(line)
+        if match:
+            target = match[3]
+            angled = target.startswith("<")
+            url = absolute_url(target[1:-1] if angled else target, repository, version,
+                               image=match[2].lower().startswith("image-"))
+            if angled:
+                url = f"<{url}>"
+            line = line[:match.start(3)] + url + line[match.end(3):]
+        elif not line.startswith(("    ", "\t")):
+            prose = re.sub(r"(`+).*?\1", "", line)
+            for inline in re.finditer(r"\]\(<?([^\s)>]+)", prose):
+                parts = urlsplit(inline[1])
+                if not parts.scheme and not parts.netloc:
+                    raise ValueError("Use a Markdown reference definition for local README links: "
+                                     + inline[1])
+        result.append(line)
+    return "".join(result)
+
+
+def build_metadata(root: Path) -> dict:
+    config = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+    version = config["project"]["version"]
+    repository = config["tool"]["specromancy-engine-build"]["repository"]
+    return {
+        "long_description": render_readme((root / "README.md").read_text(encoding="utf-8"),
+                                          repository, version),
+        "long_description_content_type": "text/markdown",
+        "project_urls": {
+            "Homepage": repository,
+            "Documentation": absolute_url("docs/README.md", repository, version),
+            "Issues": f"{repository}/issues",
+        },
+    }

specromancy_engine-0.1.3/docs/README.md

@@ -0,0 +1,55 @@
+# Documentation
+
+Current documentation is organized by purpose:
+
+- [Installation](guides/installation.md): CLI-only and Python dependency consumer routes.
+- [Publishing a release](guides/releasing.md): manual GitHub Actions release, registry setup, and recovery.
+- [Release-documentation example](../examples/release-documentation/README.md): wheel-only lifecycle walkthrough.
+- [Architecture](reference/architecture.md): runtime responsibilities and dependencies.
+- [Public contracts](reference/contracts.md): stable imports, CLI behavior, and persisted data.
+- [CLI reference](reference/cli.md): commands, responses, and exit codes.
+- [Harness compatibility](reference/harness-compatibility.md): supported discovery surfaces.
+- [Pipeline authoring](guides/authoring-pipelines.md): configure graphs and validators.
+- [Harness usage](guides/harnesses.md): run workflows from supported agent harnesses.
+- [Workflow customization](../workflow/README.md): editable sources and pipeline registration.
+
+[Historical plans and refactoring records](implementation-history/README.md) document prior work;
+use the references and guides above for current behavior.
+
+## Repository map
+
+| Location | Purpose |
+| --- | --- |
+| `pyproject.toml` | Build metadata, package discovery, schema data, and installed CLI |
+| `src/specromancy_engine/` | Public Python entry points and shared runtime utilities |
+| `src/specromancy_engine/_config/` | Private configuration parsing, models, and serialization |
+| `src/specromancy_engine/_runs/` | Private run records, persistence, and visit preparation/decisions |
+| `src/specromancy_engine/_engine/` | Private approval, validation, provenance, and response orchestration |
+| `src/specromancy_engine/_adapters/` | Private adapter source capture, rendering, and ownership |
+| `src/specromancy_engine/_cli/` | Private command metadata and pipeline selection |
+| `src/specromancy_engine/schemas/` | Published JSON schemas |
+| `bin/` | Executable launcher |
+| `workflow/` | This repository's configured development registry, graphs, and templates |
+| `.agents/skills/` | This repository's canonical procedures and manifest-owned launch skills |
+| `adapters/` | Generation entry point and generated-file ownership manifest |
+| `.claude/`, `.github/`, `.opencode/` | Harness discovery files owned by the adapter manifest |
+| `tests/engine/` | Engine unit/contract tests, evaluations, and test-owned fixtures |
+| `tests/shipped_configuration/` | Validation of the shipped workflow and generated adapters |
+| `tests/packaging/` | Installed consumer contracts and executable documentation checks |
+| `examples/release-documentation/` | Consumer-owned registry, graph, skills, templates, and sample request; outside the wheel |
+| `docs/reference/`, `docs/guides/` | Current documentation |
+| `docs/implementation-history/` | Implementation records |
+| `.specromancy/runs/` | Ignored local run state and immutable visit artifacts |
+
+The underscore-prefixed Python packages are internal implementation details.
+Public imports use `specromancy_engine`, including its `config`, `engine`,
+`run_store`, `registry`, `adapters`, and `cli` facades. See the
+[public contracts](reference/contracts.md). Internal package initializers do not import
+public facades or eagerly load sibling components.
+
+See the [test guide](../tests/README.md) for discovery commands and compatibility
+coverage. Generated adapters remain in harness-required locations; edit their
+canonical sources and regenerate them through the CLI.
+
+The [distribution verification guide](guides/distribution-verification.md) covers
+the offline installed-artifact gates, sdist contents, pinned tooling, and CI.

specromancy_engine-0.1.3/docs/guides/authoring-pipelines.md

@@ -0,0 +1,222 @@
+# Authoring pipelines
+
+Start with the [release-documentation consumer](../../examples/release-documentation/README.md)
+and [installation guide](installation.md). The example supplies a registry,
+two read-only phases, canonical skills, templates, and a complete walkthrough.
+The producer's implementation pipeline provides richer approval and repair
+examples. Test-owned replacement fixtures independently verify replaceability;
+they are not the consumer onboarding template.
+
+Register each graph in mandatory `workflow/pipelines.toml`, with a unique ID
+and a path under `workflow/pipelines/`. There is no default; use
+`specromancy init DESCRIPTION --pipeline ID`. See
+[Workflow customization](../../workflow/README.md) for add/edit/remove steps.
+
+With the package installed in your environment, use `specromancy init DESCRIPTION
+--pipeline ID` from the consumer root or a nested directory. Discovery recognizes
+both `.git` directories and worktree marker files. From an unrelated directory,
+use `specromancy --root /absolute/path/to/consumer init DESCRIPTION --pipeline ID`.
+A non-Git consumer needs both `--root` and `allow_non_git = true` in its graph.
+Installation supplies the engine and its four published schemas; author the
+registry, graph, skills, templates, and validator schemas in the consumer project.
+Nothing is implicitly loaded from the engine's source checkout or home directory.
+
+Adapter generation also requires the project-owned generic
+`.agents/skills/pipeline/SKILL.md`. Explicitly copy the
+[reusable procedure](../../.agents/skills/pipeline/SKILL.md) to that path in the
+consumer; review existing content before replacing it. Installation does not
+create it. The procedure resolves phases from persisted CLI packets and needs
+no example phase names. See [Harness usage](harnesses.md) for command environment
+setup, including GUI harnesses.
+
+Pipeline files use TOML so Python 3.11 can load them without a dependency. A
+pipeline declares schema version, identity, start phase, terminal outcomes,
+artifact naming, Git policy, and an ordered `[[phases]]` array. Every phase
+names a canonical skill, inputs, output, mutation policy, validator, gates, and
+transitions.
+
+## Add, delete, reorder, or replace phases
+
+To add a phase:
+
+1. add `.agents/skills/<name>/SKILL.md` with portable frontmatter;
+2. add any output template under the pipeline's directory;
+3. add `[[phases]]` with a unique lowercase identifier;
+4. route an existing transition to it and give it at least one transition;
+5. make every symbolic input available on every incoming route;
+6. regenerate adapters and run tests.
+
+Delete a phase by removing all inbound transitions first, then its phase table,
+skill, and unused template. Reordering table text alone does not change graph
+behavior: change transition targets and, when necessary, `start`. The loader
+rejects unreachable phases and unknown targets.
+
+Replacing the whole workflow follows the same rules. The replacement fixture's
+unrelated names and order are the contract test for this operation.
+
+## Branches and bounded loops
+
+Add one transition table per allowed outcome:
+
+```toml
+[[phases.transitions]]
+outcome = "accepted"
+
+[[phases.transitions]]
+outcome = "rejected"
+target = "transform"
+max_traversals = 2
+```
+
+A transition without `target` must be listed in `terminal_outcomes`. A cycle
+must be bounded by a positive `max_traversals` on the cyclic edge or a positive
+`max_visits` on a phase that bounds the cycle. Limits count persisted visits or
+edge traversals and block before creating an excess visit.
+
+Set `pause = true` on a nonterminal transition to create a durable checkpoint:
+
+```toml
+[[phases.transitions]]
+outcome = "validated"
+target = "implement"
+pause = true
+```
+
+The source visit completes and the target visit is prepared atomically, but the
+run remains `paused` until `specromancy resume RUN_ID` releases it. Pauses are
+independent from approvals and are rejected on terminal transitions. Omitting
+`pause`, or setting it to `false`, preserves ordinary transition behavior and
+the canonical hash of an otherwise unchanged version-1 pipeline.
+
+## Skills and templates
+
+`skill = "inspect"` resolves to `.agents/skills/inspect/SKILL.md` at the
+repository root. Canonical skill frontmatter is limited to portable Agent
+Skills fields (`name`, `description`, `license`, `compatibility`, and optional
+`metadata`). Keep vendor models, tool allowlists, and slash-command syntax in
+generated harness surfaces, never canonical skills.
+
+`output_template` is relative to the pipeline file. `../templates/result.md`
+can reference shared `workflow/templates/`; multiple graphs may use the same
+canonical skill or template. The resolved file must remain inside the repository.
+The `.agents/skills/specromancy-*` namespace holds generated launch skills and
+is not a phase-procedure customization surface. A Markdown validator can
+declare `required_headings` and `heading_occurrence`; a JSON validator may use
+the documented project-owned schema subset. Templates should contain every
+required heading exactly once and meaningful placeholder content that a valid
+artifact must replace.
+
+JSON validator `path` (or `schema`) resolves relative to the pipeline file and
+must stay inside the consumer root, including after symlink resolution. The
+`load_json_schema(path)` API still reads these project-owned files and rejects
+unsupported keywords. The four published engine schemas are a separate package
+resource contract, not artifact validators for that subset; see
+[installed resources](../reference/contracts.md#installed-resources-and-consumer-roots).
+
+## Embed the installed engine
+
+Use an explicit absolute consumer root so the caller's working directory does
+not select the project. Given a registered `shared` pipeline, this initializes a
+run and reads its durable status through the public facades:
+
+```python
+from pathlib import Path
+from specromancy_engine import Engine, RunStore, load_registry
+
+root = Path("/absolute/path/to/consumer").resolve()
+pipeline = load_registry(root).load("shared")
+store = RunStore(root)
+engine = Engine(pipeline, store)
+response = engine.initialize("Record the consumer result.")
+run_id = response["action"]["run_id"]
+status = engine.status(run_id)
+manifest = store.load(run_id)
+```
+
+`Engine(pipeline)` also constructs a store at `pipeline.repository_root` when
+one is not supplied. For an existing run, load its recorded graph rather than
+selecting today's registration, which might point somewhere else:
+
+```python
+from specromancy_engine import load_pipeline
+
+saved = store.load(run_id, verify_artifacts=False)["pipeline"]
+pipeline = load_pipeline(root / saved["path"], repository_root=root)
+engine = Engine(pipeline, store)
+status = engine.status(run_id)
+```
+
+The low-level `load_pipeline(path, repository_root=...)` API does not require a
+registry. CLI commands continue to require one. Neither API executes a phase's
+agent procedure: call `start_phase(run_id, phase_id)`, use its action packet to
+produce the artifact, then call `validate(run_id, phase_id)`. Construct a
+separate pipeline and store for each consumer; no new builder API is required.
+
+## Approvals and stops
+
+Declare stable kebab-case reason codes:
+
+```toml
+approval_conditions = ["external-side-effect", "material-scope-change"]
+stop_conditions = ["insufficient-information"]
+```
+
+The phase skill explains when each code applies. It must call
+`request-approval` or `block` rather than merely mentioning a concern in prose.
+Changing or adding a reason changes the pipeline hash.
+
+## Mutation policies
+
+- `read-only` rejects every repository path change during the visit, including
+  a second edit to a file that was dirty at visit start.
+- `repository-write` records all changes but permits them.
+- `allowlist` permits only paths matched by the phase's `allowlist` globs and
+  rejects the rest.
+
+CLI-owned `.specromancy/` files are outside repository mutation comparison.
+Read-only phases may write their designated visit output there. Completed
+outputs are immutable. In the release-documentation example the reviewed notes
+stay in run storage; explicitly copying them into release docs is a user action
+outside that lifecycle.
+None of these policies grants permission to delete, reset, stage, or commit
+work; repository instructions still apply.
+
+## Validation commands
+
+Commands are arrays, never shell strings:
+
+```toml
+[[phases.commands]]
+argv = ["python", "-m", "unittest", "discover"]
+timeout_seconds = 300
+required = true
+```
+
+They run in order from the repository root. A required failure prevents phase
+completion. Use explicit executables and arguments; shell operators, pipes, and
+redirections are not interpreted.
+
+## Regeneration and active runs
+
+After changing `AGENTS.md`, a canonical skill, the registry, a pipeline or its
+referenced templates/schemas, or CLI help
+metadata, run:
+
+```bash
+specromancy adapters generate
+specromancy adapters generate --check
+python -m unittest discover
+```
+
+A run stores its pipeline hash. Any pipeline change causes `resume`, `phase`,
+and transition commands to reject that run with `pipeline-hash-mismatch`.
+Approval records also become stale. The engine deliberately has no active-run
+migration: finish the old run before editing its pipeline, restore the exact
+old configuration to resume it, or initialize a new run under the new hash.
+Never edit `run.json` to force compatibility.
+
+Removing a registration disables new runs and removes unchanged generated
+launch skills on regeneration. Keep original graph, skill, and template files
+for active runs, which continue to resolve their persisted provenance. Removing
+the files or moving the graph prevents continuation. Registry order and edits
+to another graph do not change the selected run.