Version semantic diff and impact JSON contracts

.github/workflows/ci.yml

@@ -101,12 +101,18 @@ jobs:
           cd /tmp
           printf '%s\n' 'Create and approve a customer request, then replicate it to the target system.' > process-description.txt
           /tmp/pac-wheel/bin/process-code schema -o process.schema.json
+          /tmp/pac-wheel/bin/process-code output-schema semantic-diff -o semantic-diff.schema.json
+          /tmp/pac-wheel/bin/process-code output-schema impact -o impact.schema.json
           /tmp/pac-wheel/bin/process-code draft-context process-description.txt --json -o draft-context.json
           /tmp/pac-wheel/bin/python - <<'PY'
           import json
           schema = json.load(open('/tmp/process.schema.json', encoding='utf-8'))
+          diff_schema = json.load(open('/tmp/semantic-diff.schema.json', encoding='utf-8'))
+          impact_schema = json.load(open('/tmp/impact.schema.json', encoding='utf-8'))
           draft = json.load(open('/tmp/draft-context.json', encoding='utf-8'))
           assert schema['title'] == 'Process as Code contract v0.2'
+          assert diff_schema['properties']['output']['properties']['format']['const'] == 'process-as-code.semantic-diff'
+          assert impact_schema['properties']['output']['properties']['format']['const'] == 'process-as-code.impact'
           assert draft['schema']['title'] == schema['title']
           assert draft['schema_source'].startswith('package:')
           PY

.github/workflows/pages.yml

@@ -35,6 +35,8 @@ jobs:
           cp docs/product.html _site/index.html
           cp docs/agent-manifest.json _site/agent-manifest.json
           cp -R web/playground _site/playground
+          mkdir -p _site/schemas/outputs
+          cp schemas/outputs/*.json _site/schemas/outputs/
           touch _site/.nojekyll
       - name: Detect Pages availability
         id: pages

CHANGELOG.md

@@ -9,6 +9,7 @@
 - BPMN supported-subset import and richer export with lanes and parallel gateways.
 - Process governance policy gates.
 - GitHub Action PR validation, semantic impact and marker-based PR comment reporting, including shallow-checkout support and deleted-contract status.
+- Versioned machine-readable contracts and bundled JSON Schemas for semantic diff and impact output.
 - Portable/transitive external artifact resolver with GitHub and JSON Pointer support.
 - External artifact security hardening: local-reference sandboxing against traversal/symlink escapes, validated GitHub URI components and bounded network payloads.
 - MCP v2 process-context server.

README.md

@@ -141,6 +141,7 @@ The source-tree schema is [`schemas/process.schema.json`](schemas/process.schema
 | Capability | Command |
 | --- | --- |
 | Bundled JSON Schema | `process-code schema` |
+| Versioned machine-output schemas | `process-code output-schema` |
 | Contract validation | `process-code validate` |
 | v0.1 -> v0.2 migration | `process-code migrate` |
 | Mermaid | `process-code mermaid` |
@@ -321,7 +322,7 @@ The deterministic graph keeps stable links across process, steps, systems, inter
 
 ## Status
 
-`0.2.0` alpha reference implementation. The specification is intentionally explicit but not frozen until 1.0. See [`PRODUCT_BACKLOG.md`](PRODUCT_BACKLOG.md), [`ROADMAP.md`](ROADMAP.md), the [problem-oriented guides](docs/guides/README.md), and the public conformance suite.
+`0.2.0` alpha reference implementation. The specification is intentionally explicit but not frozen until 1.0. See [`PRODUCT_BACKLOG.md`](PRODUCT_BACKLOG.md), [`ROADMAP.md`](ROADMAP.md), the [machine-readable output contracts](docs/machine-output-contracts.md), the [problem-oriented guides](docs/guides/README.md), and the public conformance suite.
 
 MIT License.
 

ROADMAP.md

@@ -43,6 +43,7 @@ For product strategy and acceptance criteria, see [PRODUCT_BACKLOG.md](PRODUCT_B
 - [x] zero-backend browser playground
 - [x] adapter framework + BPMN/CSV reference adapters
 - [x] provider-neutral AI-assisted drafting bundle
+- [x] versioned JSON output contracts for semantic diff and impact
 
 ## 1.0 — stable contract
 

docs/agent-manifest.json

@@ -5,15 +5,20 @@
   "human_url": "https://dkharlanau.github.io/process-as-code/",
   "repository": "https://github.com/dkharlanau/process-as-code",
   "boundaries": ["not a workflow engine", "not a replacement for full BPMN modeling suites", "do not invent process semantics or ownership", "validate contracts before diff/impact/policy"],
-  "capabilities": ["validate process contracts", "semantic and visual diff", "change impact analysis", "policy gates", "Mermaid/BPMN/RACI/docs generation", "test-scope generation", "searchable catalog", "external-reference resolution", "MCP process context", "JSON-LD export"],
+  "capabilities": ["validate process contracts", "semantic and visual diff", "change impact analysis", "policy gates", "Mermaid/BPMN/RACI/docs generation", "test-scope generation", "searchable catalog", "external-reference resolution", "MCP process context", "JSON-LD export", "versioned diff/impact JSON contracts"],
   "entrypoints": [
     {"type":"cli","command":"process-code validate <process.yaml> --strict"},
     {"type":"cli","command":"process-code diff <before.yaml> <after.yaml>"},
     {"type":"cli","command":"process-code impact <before.yaml> <after.yaml>"},
+    {"type":"cli","command":"process-code output-schema impact"},
     {"type":"cli","command":"process-code policy <process.yaml> --policy <policy.yaml>"},
     {"type":"cli","command":"process-code mcp"}
   ],
   "safe_agent_loop": ["read process contract and manifest", "validate", "inspect semantic diff for changes", "calculate impact/policy before proposing edits", "respect step-level agent.exposable/executable/allowed_actions", "return generated evidence and affected scope"],
+  "machine_outputs": {
+    "semantic_diff": {"format":"process-as-code.semantic-diff","version":"1.0","schema":"https://dkharlanau.github.io/process-as-code/schemas/outputs/semantic-diff-v1.schema.json"},
+    "impact": {"format":"process-as-code.impact","version":"1.0","schema":"https://dkharlanau.github.io/process-as-code/schemas/outputs/impact-v1.schema.json"}
+  },
   "related": [
     {"product":"interface-as-code","relationship":"operational contracts referenced by process steps through sandboxed artifact resolution"},
     {"product":"mapping-as-code","relationship":"mapping artifacts resolved for traceability without transform evaluation"},

docs/architecture.md

@@ -24,6 +24,8 @@ YAML/JSON contract
 
 The v0.2 JSON Schema describes syntax; Python validation enforces graph and cross-reference invariants. Stable IDs are the semantic backbone for diff, impact, tests, external links and knowledge-graph export.
 
+Semantic diff and impact also expose versioned machine-output contracts. Their JSON payloads carry explicit format/version/schema metadata while preserving the existing top-level data fields. This separates external automation compatibility from internal Python implementation changes.
+
 Graph validation deliberately separates **reachability** from **liveness**. Forward traversal identifies what execution can enter. Reachable edge-less steps define the terminal set. A reverse traversal then determines which reachable steps can eventually reach a terminal. Strongly connected components identify trapped retry/rework cycles that have no terminating path without treating every intentional loop as an error.
 
 The validator remains a static contract analyzer: a liveness-clean graph means the declared model contains a terminating path from every reachable branch, not that external workers or systems are guaranteed to complete it.

docs/cli.md

@@ -10,6 +10,7 @@ Core authoring and review:
 - `docs FILE`
 - `raci FILE`
 - `diff OLD NEW [--json]`
+- `output-schema {semantic-diff,impact} [-o FILE]`
 - `diff-visual OLD NEW`
 - `impact OLD NEW [--resolve-external]`
 - `policy FILE --policy POLICY [--old OLD]`
@@ -32,4 +33,6 @@ Adoption and AI tooling:
 - `adapter-import ADAPTER SOURCE`
 - `mcp --root ROOT`
 
+`diff --json` and `impact --json` use versioned machine-output contracts with bundled JSON Schemas. See [Machine-readable output contracts](machine-output-contracts.md).
+
 Commands that support `--json` emit deterministic machine-readable output suitable for CI/agents. The CLI returns non-zero for validation, policy, test or import validation failures.

docs/machine-output-contracts.md

@@ -0,0 +1,82 @@
+# Machine-readable output contracts
+
+Process as Code exposes deterministic JSON for automation. The first versioned output contracts cover:
+
+- `process-code diff OLD NEW --json`
+- `process-code impact OLD NEW --json`
+
+These JSON documents are used by CI pipelines, repository tooling, agent integrations and other as-code tools. Their structure therefore needs an explicit compatibility boundary.
+
+## Output metadata
+
+Each versioned JSON document contains an `output` object:
+
+```json
+{
+  "output": {
+    "format": "process-as-code.semantic-diff",
+    "version": "1.0",
+    "schema": "https://dkharlanau.github.io/process-as-code/schemas/outputs/semantic-diff-v1.schema.json"
+  },
+  "process": {},
+  "sections": {},
+  "analysis": {}
+}
+```
+
+The impact report uses `process-as-code.impact` and its own schema URI. Its nested `semantic_diff` object keeps the semantic-diff metadata as well.
+
+The output contract version is independent from:
+
+- the Process Contract version such as `0.2`;
+- the Python package version such as `0.2.0`.
+
+## Compatibility rule
+
+Version `1.0` follows these rules:
+
+1. Existing documented fields keep their meaning and type.
+2. New optional fields may be added.
+3. Consumers should ignore fields they do not understand.
+4. Removing, renaming or changing the type of an existing documented field requires a new major output contract.
+5. Machine output stays deterministic. It does not include timestamps, random IDs or environment-specific values unless a command explicitly models them as business data.
+
+This policy lets a CI consumer depend on fields such as `sections.steps.changed` or `affected.interfaces` without depending on the internal Python implementation.
+
+## JSON Schemas
+
+The schemas are stored in:
+
+- `schemas/outputs/semantic-diff-v1.schema.json`
+- `schemas/outputs/impact-v1.schema.json`
+
+They are bundled in the Python package and published with the project site.
+
+Retrieve the bundled copies without network access:
+
+```bash
+process-code output-schema semantic-diff -o semantic-diff.schema.json
+process-code output-schema impact -o impact.schema.json
+```
+
+## Consumer pattern
+
+A consumer should check the metadata before reading the payload:
+
+```python
+result = json.loads(payload)
+
+output = result["output"]
+if output["format"] != "process-as-code.impact":
+    raise ValueError("unexpected Process as Code output")
+if output["version"] != "1.0":
+    raise ValueError("unsupported impact contract version")
+
+interfaces = result["affected"]["interfaces"]
+```
+
+For validation, use the schema from `output.schema` or a bundled copy retrieved with `process-code output-schema`.
+
+## Scope
+
+The first contract boundary is intentionally focused on semantic change control: diff and impact. Other JSON-producing commands can adopt the same pattern when their payloads become integration surfaces with external consumers.

docs/product.html

@@ -10,5 +10,5 @@
 process-code policy examples/customer-creation.process.yaml \
   --policy examples/policy.yaml</pre></div><div><h3>Designed for coexistence</h3><p>Process as Code complements BPMN editors, modeling suites, and process-mining tools. It adds a Git-native contract and review layer around the process instead of trying to become another authoring suite.</p><div class="boundary">Not a workflow engine and not a replacement for full BPMN modeling. Use it where process intent has to participate in version control, CI, impact analysis, and agent context.</div></div></div></div></section>
 <section class="section ecosystem"><div class="wrap"><div class="section-head"><h2>Where it connects</h2><p>A process can resolve specialist contracts rather than duplicating them. Resolution preserves traceability; each specialist tool still validates its own semantics.</p></div><div class="links"><a class="link-card" href="https://dkharlanau.github.io/interface-as-code/"><b>Interface as Code →</b><span>Reference the operational integration invoked by a process step.</span></a><a class="link-card" href="https://dkharlanau.github.io/reconciliation-as-code/"><b>Reconciliation as Code →</b><span>Link process or cutover gates to executable assurance controls and evidence.</span></a><a class="link-card" href="https://dkharlanau.github.io/decision-tables-as-code/"><b>Decision Tables as Code →</b><span>Reference the governed rule semantics behind a decision step.</span></a></div></div></section>
-<section class="section agent"><div class="wrap"><div class="product-mark">Agent entry point</div><div class="section-head"><h2>Governed process context for agents.</h2><p>The process contract can expose selected steps and allowed actions. MCP and drafting-context commands make the same reviewed process available to agents without turning documentation into an unrestricted tool surface.</p></div><div class="cards"><div class="card"><span class="n">DISCOVER</span><h3>Manifest + schema</h3><p><a href="agent-manifest.json">agent-manifest.json</a> describes the product surface; the bundled schema defines the process contract.</p></div><div class="card"><span class="n">INSPECT</span><h3>Diff before acting</h3><p>Agents can explain current flow and change impact before proposing modifications.</p></div><div class="card"><span class="n">BOUND</span><h3>Expose allowed actions</h3><p>Step-level agent metadata distinguishes explainable context from executable capability.</p></div></div></div></section>
+<section class="section agent"><div class="wrap"><div class="product-mark">Agent entry point</div><div class="section-head"><h2>Governed process context for agents.</h2><p>The process contract can expose selected steps and allowed actions. MCP and drafting-context commands make the same reviewed process available to agents without turning documentation into an unrestricted tool surface.</p></div><div class="cards"><div class="card"><span class="n">DISCOVER</span><h3>Manifest + schemas</h3><p><a href="agent-manifest.json">agent-manifest.json</a> describes the product surface. The process schema defines input, while <a href="schemas/outputs/impact-v1.schema.json">versioned output schemas</a> define diff and impact JSON for automation.</p></div><div class="card"><span class="n">INSPECT</span><h3>Diff before acting</h3><p>Agents can explain current flow and change impact before proposing modifications.</p></div><div class="card"><span class="n">BOUND</span><h3>Expose allowed actions</h3><p>Step-level agent metadata distinguishes explainable context from executable capability.</p></div></div></div></section>
 <section class="final"><div class="wrap"><h2>Put process change where teams can review it.</h2><p>Start with one process that changes often, version the intent, and let the catalog and impact views come from that source.</p><div class="actions"><a class="btn primary" href="catalog/">Open catalog</a><a class="btn" href="https://github.com/dkharlanau/process-as-code">Open repository</a><a class="btn" href="https://dkharlanau.github.io/products/">Full toolkit</a></div></div></section></main><footer><div class="wrap">Process as Code · part of the Enterprise Transformation Toolkit by Dzmitryi Kharlanau.</div></footer></body></html>

pyproject.toml

@@ -29,7 +29,7 @@ Repository = "https://github.com/dkharlanau/process-as-code"
 Issues = "https://github.com/dkharlanau/process-as-code/issues"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0"]
+dev = ["pytest>=8.0", "jsonschema>=4.23"]
 mcp = ["mcp>=2,<3"]
 
 [project.scripts]
@@ -43,4 +43,4 @@ package-dir = {"" = "src"}
 where = ["src"]
 
 [tool.setuptools.package-data]
-process_as_code = ["resources/*.json"]
+process_as_code = ["resources/*.json", "resources/output-schemas/*.json"]

schemas/outputs/impact-v1.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dkharlanau.github.io/process-as-code/schemas/outputs/impact-v1.schema.json",
+  "title": "Process as Code change impact output v1",
+  "type": "object",
+  "required": [
+    "output",
+    "changed_steps",
+    "analysis_changes",
+    "analysis_affected_steps",
+    "affected",
+    "risk_flags",
+    "recommended_tests",
+    "resolved_artifacts",
+    "semantic_diff"
+  ],
+  "properties": {
+    "output": {
+      "type": "object",
+      "required": ["format", "version", "schema"],
+      "properties": {
+        "format": {"const": "process-as-code.impact"},
+        "version": {"const": "1.0"},
+        "schema": {"const": "https://dkharlanau.github.io/process-as-code/schemas/outputs/impact-v1.schema.json"}
+      },
+      "additionalProperties": true
+    },
+    "changed_steps": {"type": "array", "items": {"type": "string"}},
+    "analysis_changes": {
+      "type": "object",
+      "required": ["variants", "pain_points", "data_flows"],
+      "properties": {
+        "variants": {"type": "array", "items": {"type": "string"}},
+        "pain_points": {"type": "array", "items": {"type": "string"}},
+        "data_flows": {"type": "array", "items": {"type": "string"}}
+      },
+      "additionalProperties": true
+    },
+    "analysis_affected_steps": {"type": "array", "items": {"type": "string"}},
+    "affected": {
+      "type": "object",
+      "required": ["roles", "systems", "objects", "interfaces", "controls", "risks", "evidence", "artifacts", "subprocesses"],
+      "additionalProperties": {
+        "type": "array",
+        "items": {"type": "string"}
+      }
+    },
+    "risk_flags": {"type": "array", "items": {"type": "string"}},
+    "recommended_tests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "step", "type", "scenario"],
+        "properties": {
+          "id": {"type": "string"},
+          "step": {"type": "string"},
+          "type": {"type": "string"},
+          "scenario": {"type": "string"}
+        },
+        "additionalProperties": true
+      }
+    },
+    "resolved_artifacts": {
+      "type": "array",
+      "items": {"type": "object"}
+    },
+    "semantic_diff": {
+      "type": "object",
+      "required": ["output", "process", "sections", "analysis"],
+      "properties": {
+        "output": {
+          "type": "object",
+          "required": ["format", "version", "schema"],
+          "properties": {
+            "format": {"const": "process-as-code.semantic-diff"},
+            "version": {"const": "1.0"},
+            "schema": {"const": "https://dkharlanau.github.io/process-as-code/schemas/outputs/semantic-diff-v1.schema.json"}
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}