engineering-process 2.2.0__tar.gz → 2.3.1__tar.gz

{engineering_process-2.2.0/engineering_process.egg-info → engineering_process-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 2.2.0
+Version: 2.3.1
 Summary: A small agent-neutral engineering lifecycle with managed adoption
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process
@@ -64,19 +64,56 @@ under .process/receipts. Both paths are ignored by Git. Verification evidence is
 to HEAD plus a fingerprint of tracked and non-ignored untracked files. Any relevant
 mutation invalidates it.
 
-Independent review is one direct rule: neither the reviewer actor nor reviewer context
-may have implemented the current cycle. There is no attestation hierarchy,
+Neither the reviewer actor nor reviewer context may have implemented the current
+cycle. An agent reviewer context also cannot be recorded in another accepted change
+in this repository or its registered worktrees. There is no attestation hierarchy,
 recommendation chain, authority-transition protocol, remote-evidence federation, or
 second handwritten validator.
 
-The coordinator hands review to an actual reviewer. A new agent review starts in a
-fresh context with the accepted source artifacts and no suggested verdict; the same
-reviewer continues corrections. The reviewer inspects the change and authors its
+The coordinator hands each new change to a newly spawned reviewer, with the accepted
+source artifacts and no inherited implementation or other-change review conversation.
+The same reviewer continues only that change's corrections. The reviewer inspects the change and authors its
 own report. The runner's existing task/session interaction and returned result make
-that work inspectable. Sharing a model, provider, or account is allowed; this is a
+that work inspectable. Sharing a provider or account is allowed; this is a
 workflow for independent judgment, not authenticated identity or merge enforcement.
 See [change-review](process_assets/skills/change-review/SKILL.md) for the handoff.
 
+Start, submission and finish check schema-valid canonical run history with bounded
+worktree/file reads. A short OS lock in common Git metadata serializes canonical
+history writes and review checks; profiles run outside it and reload current state
+before recording results. The lock stores no identity registry. The check rejects known context reuse,
+but cannot establish native conversation freshness or inspect removed history,
+other clones or other repositories. Keep native creation, non-inherited dispatch
+and effective settings evidence in the existing handoff.
+
+`processctl change review replace-reused` repairs only an initial pending assignment
+proven to reuse another change's agent context, before a submitted review or normal
+report file exists. It validates a fresh replacement and current verification,
+preserves the prior assignment and conflict in canonical history, and leaves cycle
+and evidence unchanged. Valid assignments and reviewed correction cycles cannot use
+this operation. It does not provide an unrestricted reviewer reset.
+
+Every delegated agent and reviewer follows the active user-selected model and
+reasoning effort under [deliver-change's settings rule](process_assets/skills/deliver-change/SKILL.md#preserve-agent-execution-settings).
+It covers fresh agents and resumed sessions, requires native runtime confirmation,
+and permits no autonomous upgrade or downgrade. The portable guidance does not make
+processctl a provider runtime or a model-quality evaluator.
+
+Consumers using the packaged publication compatibility policy can enable
+`lifecycle.publication.required: true` in `.process/project.json` after adopting a
+version that supports it. Start then rejects an invalid branch before creating a
+run. Finish checks the current branch, head subject, and pinned comparison-base-to-head
+range, and writes publication metadata in a version 2 receipt. Version 1 receipts and
+consumers without the opt-in remain supported. Missing pinned bases and mutations
+during the check fail completion.
+
+PR readiness additionally requires the selected ready-state body/title and exact
+head/range checks. Follow the [completion preflight](process_assets/skills/change-complete/SKILL.md)
+and repeat those checks in required CI. This repository's existing
+`verification/verify_publication.py --pull-request` uses the actual PR metadata and
+selected consumer standard; local lifecycle completion alone does not establish
+external PR readiness. Integration-branch pushes remain consumer-owned operations.
+
 Runtime architecture is enforced by semantic fitness functions, not module or source-
 line quotas. Every module has an explicit dependency layer, imports point toward lower
 layers, the internal graph remains acyclic, and lifecycle.py alone owns state
@@ -122,6 +159,20 @@ Commands are argument arrays, never shell strings. Each command has a finite tim
 Output has a hard aggregate budget; evidence stores byte counts and hashes, never raw
 stdout or stderr that could contain secrets.
 
+For a fresh checkout of this repository, create a virtual environment with a supported
+Python and install `engineering_process/requirements-runtime.txt`,
+`engineering_process/requirements-dev.txt`, and
+`engineering_process/requirements-build.txt` through that interpreter. Use
+`.venv/Scripts/python.exe` on Windows or `.venv/bin/python` on POSIX to invoke the
+source CLI and verification scripts. Other consumers own their runtime paths and
+setup commands; installed consumers can use their environment's `processctl` entry
+point without a source checkout.
+
+The bounded runner prepends the invoking Python executable's directory to child
+`PATH`. Bare commands therefore search that environment before the inherited path,
+while declared argument arrays, explicit executable paths, secret filtering and
+remaining path entries are preserved. This alignment does not install dependencies.
+
 A failed profile also reports a safe `diagnostic` descriptor containing only its
 validated profile identifier, check identifier, canonical one-based profile position,
 and a fixed `processctl` argument array. The position remains unambiguous even when a
@@ -273,6 +324,8 @@ consumer-owned skills and instructions. Applying the same version twice is a no-
 Consumer-owned `.process/standards.json` selections and override definitions are also
 preserved; the managed PR template follows the effective supported standard. See
 [consumer document standards](ARTIFACT_STANDARDS.md).
+[Issue records](ARTIFACT_STANDARDS.md#issues) use the same default-and-override
+mechanism for open requests and closed evidence while tracker actions remain consumer-owned.
 [Automation naming](ARTIFACT_STANDARDS.md#automation-names) uses the same versioned
 selection and override mechanism; consumers apply it in their bootstrap and provider checks.
 The legacy managed runner can enter 1.0 directly, so consumers do not need a chain of
@@ -548,6 +601,16 @@ package rule keeps the adoption pull request in draft and runs exactly:
 
     python .process/adopt-process.py --project-root . --requirements-lock requirements/process.txt
 
+The bootstrap refreshes `engineering-process` index metadata using pip's
+`--refresh-package` option, with `--no-cache-dir` for older pip. Exact pins, hashes,
+isolated installation and bounded failures still apply. Consumer CI that installs
+the lock directly must also request fresh metadata: use
+`--refresh-package engineering-process` with pip 26.2 or newer, or the portable
+`--no-cache-dir` option. Keep this setting on the process installation command;
+other dependency caches do not need to be disabled. For non-isolated pip-compile,
+the equivalent `PIP_REFRESH_PACKAGE=engineering-process` environment setting keeps
+fresh release lookup compatible with older pip, which revalidated by default.
+
 postUpgradeTasks.fileFilters includes the managed paths, so Renovate commits the new
 hash lock and the fully materialized process in the same pull request. A self-hosted
 Renovate administrator must allow only this anchored command and must keep shell

{engineering_process-2.2.0 → engineering_process-2.3.1}/README.md

@@ -40,19 +40,56 @@ under .process/receipts. Both paths are ignored by Git. Verification evidence is
 to HEAD plus a fingerprint of tracked and non-ignored untracked files. Any relevant
 mutation invalidates it.
 
-Independent review is one direct rule: neither the reviewer actor nor reviewer context
-may have implemented the current cycle. There is no attestation hierarchy,
+Neither the reviewer actor nor reviewer context may have implemented the current
+cycle. An agent reviewer context also cannot be recorded in another accepted change
+in this repository or its registered worktrees. There is no attestation hierarchy,
 recommendation chain, authority-transition protocol, remote-evidence federation, or
 second handwritten validator.
 
-The coordinator hands review to an actual reviewer. A new agent review starts in a
-fresh context with the accepted source artifacts and no suggested verdict; the same
-reviewer continues corrections. The reviewer inspects the change and authors its
+The coordinator hands each new change to a newly spawned reviewer, with the accepted
+source artifacts and no inherited implementation or other-change review conversation.
+The same reviewer continues only that change's corrections. The reviewer inspects the change and authors its
 own report. The runner's existing task/session interaction and returned result make
-that work inspectable. Sharing a model, provider, or account is allowed; this is a
+that work inspectable. Sharing a provider or account is allowed; this is a
 workflow for independent judgment, not authenticated identity or merge enforcement.
 See [change-review](process_assets/skills/change-review/SKILL.md) for the handoff.
 
+Start, submission and finish check schema-valid canonical run history with bounded
+worktree/file reads. A short OS lock in common Git metadata serializes canonical
+history writes and review checks; profiles run outside it and reload current state
+before recording results. The lock stores no identity registry. The check rejects known context reuse,
+but cannot establish native conversation freshness or inspect removed history,
+other clones or other repositories. Keep native creation, non-inherited dispatch
+and effective settings evidence in the existing handoff.
+
+`processctl change review replace-reused` repairs only an initial pending assignment
+proven to reuse another change's agent context, before a submitted review or normal
+report file exists. It validates a fresh replacement and current verification,
+preserves the prior assignment and conflict in canonical history, and leaves cycle
+and evidence unchanged. Valid assignments and reviewed correction cycles cannot use
+this operation. It does not provide an unrestricted reviewer reset.
+
+Every delegated agent and reviewer follows the active user-selected model and
+reasoning effort under [deliver-change's settings rule](process_assets/skills/deliver-change/SKILL.md#preserve-agent-execution-settings).
+It covers fresh agents and resumed sessions, requires native runtime confirmation,
+and permits no autonomous upgrade or downgrade. The portable guidance does not make
+processctl a provider runtime or a model-quality evaluator.
+
+Consumers using the packaged publication compatibility policy can enable
+`lifecycle.publication.required: true` in `.process/project.json` after adopting a
+version that supports it. Start then rejects an invalid branch before creating a
+run. Finish checks the current branch, head subject, and pinned comparison-base-to-head
+range, and writes publication metadata in a version 2 receipt. Version 1 receipts and
+consumers without the opt-in remain supported. Missing pinned bases and mutations
+during the check fail completion.
+
+PR readiness additionally requires the selected ready-state body/title and exact
+head/range checks. Follow the [completion preflight](process_assets/skills/change-complete/SKILL.md)
+and repeat those checks in required CI. This repository's existing
+`verification/verify_publication.py --pull-request` uses the actual PR metadata and
+selected consumer standard; local lifecycle completion alone does not establish
+external PR readiness. Integration-branch pushes remain consumer-owned operations.
+
 Runtime architecture is enforced by semantic fitness functions, not module or source-
 line quotas. Every module has an explicit dependency layer, imports point toward lower
 layers, the internal graph remains acyclic, and lifecycle.py alone owns state
@@ -98,6 +135,20 @@ Commands are argument arrays, never shell strings. Each command has a finite tim
 Output has a hard aggregate budget; evidence stores byte counts and hashes, never raw
 stdout or stderr that could contain secrets.
 
+For a fresh checkout of this repository, create a virtual environment with a supported
+Python and install `engineering_process/requirements-runtime.txt`,
+`engineering_process/requirements-dev.txt`, and
+`engineering_process/requirements-build.txt` through that interpreter. Use
+`.venv/Scripts/python.exe` on Windows or `.venv/bin/python` on POSIX to invoke the
+source CLI and verification scripts. Other consumers own their runtime paths and
+setup commands; installed consumers can use their environment's `processctl` entry
+point without a source checkout.
+
+The bounded runner prepends the invoking Python executable's directory to child
+`PATH`. Bare commands therefore search that environment before the inherited path,
+while declared argument arrays, explicit executable paths, secret filtering and
+remaining path entries are preserved. This alignment does not install dependencies.
+
 A failed profile also reports a safe `diagnostic` descriptor containing only its
 validated profile identifier, check identifier, canonical one-based profile position,
 and a fixed `processctl` argument array. The position remains unambiguous even when a
@@ -249,6 +300,8 @@ consumer-owned skills and instructions. Applying the same version twice is a no-
 Consumer-owned `.process/standards.json` selections and override definitions are also
 preserved; the managed PR template follows the effective supported standard. See
 [consumer document standards](ARTIFACT_STANDARDS.md).
+[Issue records](ARTIFACT_STANDARDS.md#issues) use the same default-and-override
+mechanism for open requests and closed evidence while tracker actions remain consumer-owned.
 [Automation naming](ARTIFACT_STANDARDS.md#automation-names) uses the same versioned
 selection and override mechanism; consumers apply it in their bootstrap and provider checks.
 The legacy managed runner can enter 1.0 directly, so consumers do not need a chain of
@@ -524,6 +577,16 @@ package rule keeps the adoption pull request in draft and runs exactly:
 
     python .process/adopt-process.py --project-root . --requirements-lock requirements/process.txt
 
+The bootstrap refreshes `engineering-process` index metadata using pip's
+`--refresh-package` option, with `--no-cache-dir` for older pip. Exact pins, hashes,
+isolated installation and bounded failures still apply. Consumer CI that installs
+the lock directly must also request fresh metadata: use
+`--refresh-package engineering-process` with pip 26.2 or newer, or the portable
+`--no-cache-dir` option. Keep this setting on the process installation command;
+other dependency caches do not need to be disabled. For non-isolated pip-compile,
+the equivalent `PIP_REFRESH_PACKAGE=engineering-process` environment setting keeps
+fresh release lookup compatible with older pip, which revalidated by default.
+
 postUpgradeTasks.fileFilters includes the managed paths, so Renovate commits the new
 hash lock and the fully materialized process in the same pull request. A self-hosted
 Renovate administrator must allow only this anchored command and must keep shell

engineering_process-2.3.1/RELEASE_NOTES.md

@@ -0,0 +1,18 @@
+# Engineering Process v2.3.1
+
+Changes since v2.3.0.
+
+## Fixes
+
+- Refresh package metadata when installing the hash\-locked process so newly published releases remain visible through warm pip caches\; remove the publication\-time cache expiry wait\. Consumer CI using pip 26\.2 or newer should pass \-\-refresh\-package engineering\-process\, or use \-\-no\-cache\-dir with older pip\. ([#134](https://github.com/phuongnse/engineering-process/issues/134))
+- Reject recorded agent reviewer\-context reuse across changes in the same repository and its worktrees\. Preserve same\-change correction reviews\, and provide an audited replacement only for a reused initial assignment with no submitted review\. Native fresh\-session and unchanged model\/effort evidence remain required from the host\. ([#182](https://github.com/phuongnse/engineering-process/issues/182))
+
+## Upgrade and compatibility
+
+Merge the complete hash-locked package/adoption PR, update the local and CI environments to the selected version, and start a fresh agent session.
+
+Consumer CI, naming conventions and branch-protection settings remain consumer-owned; adoption does not configure them automatically.
+
+See [versioning and compatibility](https://github.com/phuongnse/engineering-process/blob/v2.3.1/VERSIONING.md) and [adoption guidance](https://github.com/phuongnse/engineering-process/blob/v2.3.1/SELF_HOSTING.md).
+
+[Full change comparison](https://github.com/phuongnse/engineering-process/compare/v2.3.0...v2.3.1)

{engineering_process-2.2.0 → engineering_process-2.3.1}/engineering_process/__init__.py

@@ -1,3 +1,3 @@
 """Agent-neutral engineering process."""
 
-VERSION = "2.2.0"
+VERSION = "2.3.1"

{engineering_process-2.2.0 → engineering_process-2.3.1}/engineering_process/_supervisor_posix.py

@@ -7,6 +7,7 @@ import ctypes
 import os
 from pathlib import Path
 import secrets
+import shutil
 import signal
 import subprocess
 import sys
@@ -35,9 +36,13 @@ def _enable_subreaper() -> None:
 
 
 def _ps_process_table() -> tuple[dict[int, int], str | None]:
+    # Supervision must not depend on the consumer's PATH.
+    application = shutil.which("ps", path=os.defpath)
+    if application is None:
+        return {}, "process table snapshot could not start"
     try:
         result = subprocess.run(
-            ["ps", "-axo", "pid=,ppid="],
+            [application, "-axo", "pid=,ppid="],
             stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
             timeout=PROCESS_TABLE_TIMEOUT_SECONDS, check=False, text=True,
         )
@@ -190,7 +195,7 @@ class PosixProcessSupervisor:
         if not command or "\x00" in command:
             raise OSError("command executable is invalid")
         supplied = Path(command)
-        if supplied.is_absolute() or supplied.parent != Path("."):
+        if supplied.is_absolute() or os.path.dirname(command):
             candidate = supplied if supplied.is_absolute() else working_directory / supplied
             try:
                 resolved = candidate.resolve(strict=True)
@@ -198,7 +203,8 @@ class PosixProcessSupervisor:
                 raise OSError(f"executable is unavailable: {command}") from error
             if not resolved.is_file() or not os.access(resolved, os.X_OK):
                 raise OSError(f"executable is unavailable: {command}")
-            return resolved
+            # The symlink path may select a virtual environment.
+            return candidate.absolute()
         for raw_directory in environment.get("PATH", "").split(os.pathsep):
             directory = Path(raw_directory or ".")
             if not directory.is_absolute():
@@ -209,7 +215,7 @@ class PosixProcessSupervisor:
             except OSError:
                 continue
             if resolved.is_file() and os.access(resolved, os.X_OK):
-                return resolved
+                return candidate.absolute()
         raise OSError(f"executable is unavailable: {command}")
 
     def spawn(

{engineering_process-2.2.0 → engineering_process-2.3.1}/engineering_process/_supervisor_windows.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import ntpath
 import os
 from pathlib import Path
 import subprocess
@@ -99,7 +100,7 @@ def resolve_windows_application(
         raise OSError("command executable is invalid")
     separator = os.pathsep if path_separator is None else path_separator
     supplied = Path(command)
-    explicit_path = supplied.is_absolute() or supplied.parent != Path(".")
+    explicit_path = supplied.is_absolute() or bool(ntpath.dirname(command))
     suffix = supplied.suffix.casefold()
     if suffix in _UNSUPPORTED_SHELL_SUFFIXES:
         raise OSError(

{engineering_process-2.2.0 → engineering_process-2.3.1}/engineering_process/artifact_standards.py

@@ -84,6 +84,14 @@ def _validate_relations(document: dict[str, Any]) -> None:
         _unique([group["type"] for group in rules["groups"]], "change types")
         _unique([section["id"] for section in rules["sections"]], "release section ids")
         _unique([item["heading"] for item in rules["groups"] + rules["sections"]], "release headings")
+    elif document["adapter"] == "issue":
+        for state, definition in rules["states"].items():
+            sections = definition["sections"]
+            _unique([section["heading"] for section in sections], f"{state} issue section headings")
+            for kind in ("fields", "checks"):
+                entries = [entry for section in sections for entry in section[kind]]
+                _unique([entry["id"] for entry in entries], f"{state} issue {kind} ids")
+                _unique([entry["label"] for entry in entries], f"{state} issue {kind} labels")
 
 
 def read_document(path: Path) -> bytes:

{engineering_process-2.2.0 → engineering_process-2.3.1}/engineering_process/cli.py

@@ -40,6 +40,7 @@ from .lifecycle import (
     submit_review,
     verify_change,
 )
+from .issue import render_issue
 from .project import load_project, readiness_summary
 from .production_engineering import (
     validate_plan_assessments,
@@ -329,9 +330,10 @@ def command_change_review_start(args: argparse.Namespace) -> Result:
         actor_id=args.actor,
         context_id=args.context,
         kind=args.actor_kind,
+        replace_reused=args.review_command == "replace-reused",
     )
     return _state_result(
-        "change review start",
+        f"change review {args.review_command}",
         state,
         assignment=state["reviewAssignment"],
         processSignals=process_improvement_signals(state),
@@ -420,17 +422,29 @@ def command_artifact(args: argparse.Namespace) -> Result:
     elif operation == "renovate-preset":
         payload = formatted_json_bytes(render_renovate_preset(standard, process_root=process_root))
     else:
+        state = args.state or ("open" if standard.document["adapter"] == "issue" else "ready")
+        allowed_states = {
+            "pr-description": {"draft", "ready"},
+            "release-notes": {"draft", "ready"},
+            "automation-name": {"draft", "ready"},
+            "issue": {"open", "closed"},
+        }[standard.document["adapter"]]
+        if state not in allowed_states:
+            raise ProcessError(
+                f"{standard.document['adapter']} state must be "
+                + " or ".join(sorted(allowed_states))
+            )
         data = load_and_validate(args.data_file, standard.document["adapter"] + "-data", schema_root=schemas_root(process_root)) if args.data_file is not None else None
         if data is not None:
-            renderer = {"pr-description": render_description, "release-notes": render_notes, "automation-name": render_name}[standard.document["adapter"]]
-            payload = renderer(standard, data, state=args.state, process_root=process_root).encode("utf-8")
+            renderer = {"pr-description": render_description, "release-notes": render_notes, "automation-name": render_name, "issue": render_issue}[standard.document["adapter"]]
+            payload = renderer(standard, data, state=state, process_root=process_root).encode("utf-8")
             details["dataDigest"] = digest_json(data)
         elif operation == "render" or standard.document["adapter"] != "pr-description":
             raise ProcessError("this artifact operation requires --data-file")
         if operation == "validate":
             actual = read_document(args.body_file)
             if data is None:
-                issues = body_issues(actual.decode("utf-8"), args.state, standard)
+                issues = body_issues(actual.decode("utf-8"), state, standard)
             elif actual != payload:
                 issues.append("artifact bytes differ from the selected standard and input data")
             payload = actual
@@ -529,6 +543,9 @@ def build_parser() -> argparse.ArgumentParser:
     review_start = _leaf(review_commands, "start", command_change_review_start)
     _add_actor(review_start)
     review_start.add_argument("--change-id", required=True)
+    review_replace = _leaf(review_commands, "replace-reused", command_change_review_start)
+    _add_actor(review_replace)
+    review_replace.add_argument("--change-id", required=True)
     review_submit = _leaf(review_commands, "submit", command_change_review_submit)
     review_submit.add_argument("--change-id", required=True)
     review_submit.add_argument("--review", type=Path, required=True)
@@ -551,7 +568,7 @@ def build_parser() -> argparse.ArgumentParser:
         leaf = _leaf(artifact_commands, name, command_artifact)
         leaf.add_argument("--artifact", required=True)
         if name in {"render", "validate"}:
-            leaf.add_argument("--state", choices=("draft", "ready"), default="ready")
+            leaf.add_argument("--state", choices=("draft", "ready", "open", "closed"))
             leaf.add_argument("--data-file", type=Path, required=name == "render")
         if name == "validate":
             leaf.add_argument("--body-file", type=Path, required=True)

{engineering_process-2.2.0 → engineering_process-2.3.1}/engineering_process/commands.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import hashlib
 import os
 from pathlib import Path
+import sys
 import threading
 import time
 from typing import Any, BinaryIO
@@ -28,6 +29,11 @@ def _child_environment() -> dict[str, str]:
         if any(marker in upper for marker in SECRET_MARKERS):
             continue
         environment[name] = value
+    runtime_directory = str(Path(sys.executable).absolute().parent)
+    inherited_path = environment.get("PATH", "")
+    environment["PATH"] = os.pathsep.join(
+        entry for entry in (runtime_directory, inherited_path) if entry
+    )
     environment["PYTHONUNBUFFERED"] = "1"
     return environment
 

{engineering_process-2.2.0 → engineering_process-2.3.1}/engineering_process/contracts.py

@@ -20,6 +20,7 @@ CONTRACT_KINDS = (
     "artifact-selection",
     "artifact-standard",
     "automation-name-data",
+    "issue-data",
     "change",
     "plan",
     "process-graph",
@@ -50,9 +51,20 @@ def read_json(path: Path, *, maximum_bytes: int = MAX_JSON_BYTES) -> Any:
     if size > maximum_bytes:
         raise ProcessError(f"{path} exceeds {maximum_bytes} bytes")
     try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as error:
-        raise ProcessError(f"{path} is not valid UTF-8 JSON: {error}") from error
+        with path.open("rb") as stream:
+            content = stream.read(maximum_bytes + 1)
+    except OSError as error:
+        raise ProcessError(f"cannot read {path}: {error}") from error
+    if len(content) > maximum_bytes:
+        raise ProcessError(f"{path} exceeds {maximum_bytes} bytes")
+    return parse_json_bytes(content, source=str(path))
+
+
+def parse_json_bytes(content: bytes, *, source: str) -> Any:
+    try:
+        return json.loads(content.decode("utf-8"))
+    except (UnicodeError, json.JSONDecodeError) as error:
+        raise ProcessError(f"{source} is not valid UTF-8 JSON: {error}") from error
 
 
 def canonical_bytes(value: Any) -> bytes:

engineering_process-2.3.1/engineering_process/issue.py

@@ -0,0 +1,112 @@
+"""Issue record generation from one consumer-selected standard."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+from .artifact_standards import ArtifactStandard, MAX_DOCUMENT_BYTES
+from .contracts import ProcessError, validate_document
+from .distribution import distribution_root, schemas_root
+
+
+_HTTPS_AUTHORITY = re.compile(
+    r"(?:\[[^\[\]]+\]|(?:[A-Za-z0-9._~!$&'()*+,;=-]|%[0-9A-Fa-f]{2})+)"
+    r"(?::[0-9]*)?"
+)
+
+
+def _record_url(value: str) -> bool:
+    if any(character.isspace() or ord(character) < 32 or 127 <= ord(character) <= 159
+           for character in value):
+        return False
+    try:
+        parsed = urlsplit(value)
+        # urlsplit defers port validation until this attribute is read.
+        parsed.port
+        return (
+            parsed.scheme == "https"
+            and parsed.hostname is not None
+            and parsed.username is None
+            and parsed.password is None
+            and _HTTPS_AUTHORITY.fullmatch(parsed.netloc) is not None
+        )
+    except ValueError:
+        return False
+
+
+def _validate_field(field: dict[str, Any], value: str) -> None:
+    format_name = field.get("format", "text")
+    if format_name == "record-url" and not _record_url(value):
+        raise ProcessError(f"issue field {field['label']} requires one durable HTTPS URL")
+    if format_name == "record-references":
+        references = value.split(", ")
+        if value.casefold() != "none" and (
+            not references or any(not _record_url(reference) for reference in references)
+        ):
+            raise ProcessError(
+                f"issue field {field['label']} requires none or comma-separated durable HTTPS URLs"
+            )
+
+
+def render_issue(
+    standard: ArtifactStandard,
+    data: dict[str, Any],
+    *,
+    state: str = "open",
+    process_root: Path | None = None,
+) -> str:
+    if standard.document["adapter"] != "issue":
+        raise ProcessError("selected standard requires a different issue adapter")
+    if state not in {"open", "closed"}:
+        raise ProcessError("issue state must be open or closed")
+    validate_document(
+        data,
+        "issue-data",
+        schema_root=schemas_root(distribution_root(process_root)),
+    )
+    title_rules = standard.rules["title"]
+    title = data["title"]
+    if len(title) > title_rules["maxLength"]:
+        raise ProcessError("issue title exceeds the selected length limit")
+    if prefix := title_rules.get("prefix"):
+        if not title.startswith(prefix):
+            raise ProcessError(f"issue title must start with {prefix}")
+    title_value = title[len(prefix):] if prefix else title
+    if not title_value.strip() or standard.unresolved(title_value):
+        raise ProcessError(f"{state} issue has unresolved title")
+
+    sections = standard.rules["states"][state]["sections"]
+    fields = [field for section in sections for field in section["fields"]]
+    checks = [check for section in sections for check in section["checks"]]
+    expected_fields = {field["id"] for field in fields}
+    expected_checks = {check["id"] for check in checks}
+    unknown_fields = sorted(data["fields"].keys() - expected_fields)
+    unknown_checks = sorted(data["checks"].keys() - expected_checks)
+    if unknown_fields:
+        raise ProcessError("issue data contains unknown fields: " + ", ".join(unknown_fields))
+    if unknown_checks:
+        raise ProcessError("issue data contains unknown checks: " + ", ".join(unknown_checks))
+
+    lines = [f"# {title}", ""]
+    for section in sections:
+        lines.extend([section["heading"], ""])
+        for field in section["fields"]:
+            value = data["fields"].get(field["id"], standard.document["pendingValues"][0])
+            if standard.unresolved(value):
+                raise ProcessError(f"{state} issue has unresolved value for {field['label']}")
+            _validate_field(field, value)
+            lines.extend([f"### {field['label']}", "", value, ""])
+        for check in section["checks"]:
+            completed = data["checks"].get(check["id"], False)
+            if state == "closed" and not completed:
+                raise ProcessError(f"closed issue has unchecked item: {check['label']}")
+            lines.append(f"- [{'x' if completed else ' '}] {check['label']}")
+        if section["checks"]:
+            lines.append("")
+    body = "\n".join(lines)
+    if len(body.encode("utf-8")) > MAX_DOCUMENT_BYTES:
+        raise ProcessError("issue record exceeds its size limit")
+    return body