engineering-process 2.4.0__tar.gz → 2.5.0__tar.gz

{engineering_process-2.4.0/engineering_process.egg-info → engineering_process-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 2.4.0
+Version: 2.5.0
 Summary: A small agent-neutral engineering lifecycle with managed adoption
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process
@@ -86,6 +86,16 @@ 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.
 
+Verification keeps two caller intents explicit. `change verify --profile PROFILE`
+always refreshes the named profile. `change explain` is read-only; it shows the
+accepted required profiles, valid prior evidence, remaining work, inapplicable
+optional profiles, and blocked or unknown decisions. `change verify --remaining`
+executes only remaining work and reuses a complete profile report only when the
+candidate, contract/plan, project policy, process authority, runtime, and bounded
+child environment match. Legacy evidence without that identity reruns. This is
+whole-profile reuse: equal check IDs and ordered side effects are never merged, and
+the lifecycle receipt still records only actual executions.
+
 `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,
@@ -502,6 +512,14 @@ Register implementation and run every required profile:
     processctl change verify --change-id change-123 --profile development
     processctl change verify --change-id change-123 --profile review
 
+When continuing an incomplete verification, inspect and execute the necessary set:
+
+    processctl change explain --change-id change-123
+    processctl change verify --change-id change-123 --remaining
+
+The explicit `--profile` form remains a refresh and is never silently converted to
+reuse.
+
 Assign an independent reviewer and submit its report:
 
     processctl change review start \

{engineering_process-2.4.0 → engineering_process-2.5.0}/README.md

@@ -62,6 +62,16 @@ 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.
 
+Verification keeps two caller intents explicit. `change verify --profile PROFILE`
+always refreshes the named profile. `change explain` is read-only; it shows the
+accepted required profiles, valid prior evidence, remaining work, inapplicable
+optional profiles, and blocked or unknown decisions. `change verify --remaining`
+executes only remaining work and reuses a complete profile report only when the
+candidate, contract/plan, project policy, process authority, runtime, and bounded
+child environment match. Legacy evidence without that identity reruns. This is
+whole-profile reuse: equal check IDs and ordered side effects are never merged, and
+the lifecycle receipt still records only actual executions.
+
 `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,
@@ -478,6 +488,14 @@ Register implementation and run every required profile:
     processctl change verify --change-id change-123 --profile development
     processctl change verify --change-id change-123 --profile review
 
+When continuing an incomplete verification, inspect and execute the necessary set:
+
+    processctl change explain --change-id change-123
+    processctl change verify --change-id change-123 --remaining
+
+The explicit `--profile` form remains a refresh and is never silently converted to
+reuse.
+
 Assign an independent reviewer and submit its report:
 
     processctl change review start \

engineering_process-2.5.0/RELEASE_NOTES.md

@@ -0,0 +1,17 @@
+# Engineering Process v2.5.0
+
+Changes since v2.4.0.
+
+## Features
+
+- Resolve process issues \#197\-\#205\: durable feedback and review recovery\, snapshot and test cost\, guidance authority\, PR evidence\, adoption scope\, CI repetition\, and necessary verification\. ([#205](https://github.com/phuongnse/engineering-process/issues/205))
+
+## 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.5.0/VERSIONING.md) and [adoption guidance](https://github.com/phuongnse/engineering-process/blob/v2.5.0/SELF_HOSTING.md).
+
+[Full change comparison](https://github.com/phuongnse/engineering-process/compare/v2.4.0...v2.5.0)

{engineering_process-2.4.0 → engineering_process-2.5.0}/engineering_process/__init__.py

@@ -1,3 +1,3 @@
 """Agent-neutral engineering process."""
 
-VERSION = "2.4.0"
+VERSION = "2.5.0"

{engineering_process-2.4.0 → engineering_process-2.5.0}/engineering_process/cli.py

@@ -38,6 +38,8 @@ from .lifecycle import (
     start_change,
     start_review,
     submit_review,
+    resolve_verification_work,
+    verify_remaining,
     verify_change,
 )
 from .issue import render_issue
@@ -53,7 +55,13 @@ from .publication_compat import (
     validate_range,
 )
 from .release import validate_release
-from .pr_description import body_issues, render_description, render_renovate_preset, render_template
+from .pr_description import (
+    body_issues,
+    build_pr_description_data,
+    render_description,
+    render_renovate_preset,
+    render_template,
+)
 from .release_notes import render_notes
 from .repository import repository_snapshot, same_checkpoint
 from .skills import validate_skills
@@ -87,9 +95,16 @@ def _result(command: str, status: str = "passed", **details: Any) -> dict[str, A
     return {"command": command, "status": status, **details}
 
 
-def _state_result(command: str, state: dict[str, Any], **details: Any) -> dict[str, Any]:
+def _state_result(
+    command: str,
+    state: dict[str, Any],
+    *,
+    status: str = "passed",
+    **details: Any,
+) -> dict[str, Any]:
     return _result(
         command,
+        status=status,
         changeId=state["changeId"],
         phase=state["phase"],
         cycle=state["cycle"],
@@ -312,6 +327,54 @@ def command_change_implement(args: argparse.Namespace) -> Result:
 def command_change_verify(args: argparse.Namespace) -> Result:
     process_root = _process_root(args)
     project = load_project(args.project_root, process_root)
+    if args.remaining:
+        state, selection = verify_remaining(
+            args.project_root, process_root, project, args.change_id
+        )
+        executions = []
+        failures = []
+        for profile in selection["executeProfiles"]:
+            report = state["verification"].get(profile)
+            if report is None:
+                failures.append(profile)
+                continue
+            if report["status"] != "passed":
+                failures.append(profile)
+            check_duration = sum(check["durationMs"] for check in report["checks"])
+            executions.append(
+                {
+                    "profile": profile,
+                    "status": report["status"],
+                    "launchCount": len(report["checks"]),
+                    "durationMs": report.get("durationMs", check_duration),
+                    "checkDurationMs": check_duration,
+                    "processOverheadMs": max(
+                        0, report.get("durationMs", check_duration) - check_duration
+                    ),
+                }
+            )
+        contract = state.get("contract", {})
+        required_profiles = (
+            contract.get("document", {}).get("requiredProfiles", [])
+            if isinstance(contract, dict)
+            else []
+        )
+        verification = state.get("verification", {})
+        required_profiles_passed = bool(required_profiles) and all(
+            isinstance(verification.get(profile), dict)
+            and verification[profile].get("status") == "passed"
+            for profile in required_profiles
+        )
+        complete = state["phase"] == "verified" and required_profiles_passed
+        return _state_result(
+            "change verify",
+            state,
+            status="passed" if complete and not failures else "failed",
+            selection=selection,
+            execution="remaining",
+            executions=executions,
+            failures=failures,
+        ), (0 if complete and not failures else 1)
     state, report = verify_change(
         args.project_root, process_root, project, args.change_id, args.profile
     )
@@ -321,6 +384,15 @@ def command_change_verify(args: argparse.Namespace) -> Result:
     ), code
 
 
+def command_change_explain(args: argparse.Namespace) -> Result:
+    process_root = _process_root(args)
+    project = load_project(args.project_root, process_root)
+    selection = resolve_verification_work(
+        args.project_root, process_root, project, args.change_id
+    )
+    return _result("change explain", selection=selection), 0
+
+
 def command_change_review_start(args: argparse.Namespace) -> Result:
     process_root = _process_root(args)
     state = start_review(
@@ -434,13 +506,37 @@ def command_artifact(args: argparse.Namespace) -> Result:
                 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 getattr(args, "change_id", None) is not None and standard.document["adapter"] == "pr-description":
+            overrides = (
+                load_and_validate(
+                    args.data_file,
+                    "pr-description-data",
+                    schema_root=schemas_root(process_root),
+                )
+                if args.data_file is not None
+                else None
+            )
+            data = build_pr_description_data(
+                args.project_root,
+                process_root,
+                args.change_id,
+                overrides=overrides,
+                standard=standard,
+            )
+        elif args.data_file is not None:
+            data = load_and_validate(
+                args.data_file,
+                standard.document["adapter"] + "-data",
+                schema_root=schemas_root(process_root),
+            )
+        else:
+            data = None
         if data is not None:
             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")
+            raise ProcessError("this artifact operation requires --data-file or --change-id")
         if operation == "validate":
             actual = read_document(args.body_file)
             if data is None:
@@ -460,6 +556,38 @@ def command_artifact(args: argparse.Namespace) -> Result:
     return _result(f"artifact {operation}", status, **details, issues=issues), (1 if issues else 0)
 
 
+def command_artifact_prepare_pr_data(args: argparse.Namespace) -> Result:
+    process_root = _process_root(args)
+    standard = resolve_standard(args.project_root, process_root, "pull-request")
+    overrides = (
+        load_and_validate(
+            args.data_file,
+            "pr-description-data",
+            schema_root=schemas_root(process_root),
+        )
+        if args.data_file is not None
+        else None
+    )
+    data = build_pr_description_data(
+        args.project_root,
+        process_root,
+        args.change_id,
+        overrides=overrides,
+        standard=standard,
+    )
+    payload = formatted_json_bytes(data)
+    details: dict[str, Any] = {
+        "changeId": args.change_id,
+        "dataDigest": digest_json(data),
+    }
+    if args.output is not None:
+        args.output.write_bytes(payload)
+        details["output"] = str(args.output)
+    else:
+        details["data"] = data
+    return _result("artifact prepare-pr-data", "passed", **details), 0
+
+
 def _add_common(parser: argparse.ArgumentParser, *, project: bool = True) -> None:
     if project:
         parser.add_argument("--project-root", type=_root, default=Path.cwd())
@@ -536,7 +664,12 @@ def build_parser() -> argparse.ArgumentParser:
     change_implement.add_argument("--change-id", required=True)
     change_verify = _leaf(change_commands, "verify", command_change_verify)
     change_verify.add_argument("--change-id", required=True)
-    change_verify.add_argument("--profile", required=True)
+    verify_scope = change_verify.add_mutually_exclusive_group(required=True)
+    verify_scope.add_argument("--profile")
+    verify_scope.add_argument("--remaining", action="store_true")
+
+    change_explain = _leaf(change_commands, "explain", command_change_explain)
+    change_explain.add_argument("--change-id", required=True)
 
     review = change_commands.add_parser("review")
     review_commands = review.add_subparsers(dest="review_command", required=True)
@@ -564,12 +697,17 @@ def build_parser() -> argparse.ArgumentParser:
 
     artifact = commands.add_parser("artifact", help="Generate and verify consumer-selected artifact standards")
     artifact_commands = artifact.add_subparsers(dest="artifact_command", required=True)
+    prepare_pr_data = _leaf(artifact_commands, "prepare-pr-data", command_artifact_prepare_pr_data)
+    prepare_pr_data.add_argument("--change-id", required=True)
+    prepare_pr_data.add_argument("--data-file", type=Path)
+    prepare_pr_data.add_argument("--output", type=Path)
     for name in ("show", "template", "renovate-preset", "render", "validate"):
         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", "open", "closed"))
-            leaf.add_argument("--data-file", type=Path, required=name == "render")
+            leaf.add_argument("--change-id")
+            leaf.add_argument("--data-file", type=Path, required=False)
         if name == "validate":
             leaf.add_argument("--body-file", type=Path, required=True)
         else:

{engineering_process-2.4.0 → engineering_process-2.5.0}/engineering_process/commands.py

@@ -3,39 +3,113 @@
 from __future__ import annotations
 
 import hashlib
+from contextlib import contextmanager
 import os
 from pathlib import Path
 import sys
 import threading
 import time
-from typing import Any, BinaryIO
+from typing import Any, BinaryIO, Iterator
 
 from .contracts import ProcessError
+from .evidence import child_environment, execution_identity as _execution_identity
 from .supervision import process_supervisor
 
 
 DEFAULT_OUTPUT_BYTES = 1_000_000
 TERMINATION_SECONDS = 2
-SECRET_MARKERS = ("TOKEN", "SECRET", "PASSWORD", "PASSWD", "API_KEY", "PRIVATE_KEY")
 _EXECUTION_LOCK = threading.Lock()
 
 
 def _child_environment() -> dict[str, str]:
-    environment: dict[str, str] = {}
-    for name, value in os.environ.items():
-        upper = name.upper()
-        if name in {"PYTHONHOME", "PYTHONPATH"}:
-            continue
-        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
+    return child_environment(executable=sys.executable)
+
+
+def execution_identity() -> dict[str, Any]:
+    """Return the bounded runtime inputs used to launch consumer checks."""
+    return _execution_identity(executable=sys.executable)
+
+
+_LOCK_OWNERS = threading.local()
+
+
+@contextmanager
+def verification_lock(path: Path) -> Iterator[None]:
+    """Prevent concurrent lifecycle requests from dispatching verification twice."""
+    lock_path = (
+        path.parent / ".verification.lock"
+        if os.name == "nt"
+        else path.parent
     )
-    environment["PYTHONUNBUFFERED"] = "1"
-    return environment
+    resolved = lock_path.resolve()
+    holders = getattr(_LOCK_OWNERS, "holders", None)
+    if holders is None:
+        holders = _LOCK_OWNERS.holders = {}
+
+    if resolved in holders:
+        holders[resolved] += 1
+        try:
+            yield
+        finally:
+            holders[resolved] -= 1
+            if holders[resolved] == 0:
+                del holders[resolved]
+        return
+
+    if os.name == "nt":
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0)
+        flags |= getattr(os, "O_NOFOLLOW", 0)
+    else:
+        # Lock the run directory itself so replacing a profile lock entry cannot
+        # create a second lock inode while this operation is active.
+        flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        descriptor = os.open(lock_path, flags, 0o600)
+    except OSError as error:
+        raise ProcessError(f"cannot open verification lock: {error}") from error
+    locked = False
+    try:
+        if os.name == "nt":
+            opened = os.fstat(descriptor)
+            current = os.stat(lock_path)
+            if (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino):
+                raise ProcessError("verification lock was replaced while opening")
+            import msvcrt
+            if os.fstat(descriptor).st_size == 0:
+                os.write(descriptor, b"0")
+            os.lseek(descriptor, 0, os.SEEK_SET)
+            msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
+        else:
+            import fcntl
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        locked = True
+        if os.name == "nt":
+            current = os.stat(lock_path)
+            if (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino):
+                raise ProcessError("verification lock was replaced while acquiring")
+    except OSError as error:
+        os.close(descriptor)
+        raise ProcessError("verification for this profile is already running") from error
+    except ProcessError:
+        os.close(descriptor)
+        raise
+    holders[resolved] = 1
+    try:
+        yield
+    finally:
+        del holders[resolved]
+        if locked:
+            try:
+                if os.name == "nt":
+                    import msvcrt
+                    os.lseek(descriptor, 0, os.SEEK_SET)
+                    msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)
+                else:
+                    import fcntl
+                    fcntl.flock(descriptor, fcntl.LOCK_UN)
+            finally:
+                os.close(descriptor)
 
 
 class _OutputBudget:
@@ -221,6 +295,7 @@ def run_profile(
             )
         checks = [configured_checks[check_position - 1]]
         positions = [check_position]
+    started = time.monotonic()
     reports: list[dict[str, Any]] = []
     failed_position: int | None = None
     for position, check in zip(positions, checks, strict=True):
@@ -234,6 +309,7 @@ def run_profile(
         "status": "passed" if len(reports) == len(checks) and all(
             report["status"] == "passed" for report in reports
         ) else "failed",
+        "durationMs": 0,
         "scope": (
             {"kind": "profile"}
             if check_position is None
@@ -245,6 +321,7 @@ def run_profile(
         ),
         "checks": reports,
     }
+    result["durationMs"] = int((time.monotonic() - started) * 1000)
     failed = next((report for report in reports if report["status"] == "failed"), None)
     if failed is not None:
         assert failed_position is not None

{engineering_process-2.4.0 → engineering_process-2.5.0}/engineering_process/contracts.py

@@ -36,6 +36,7 @@ CONTRACT_KINDS = (
     "renovate-preset",
     "review",
     "run",
+    "verification-selection",
 )
 
 

engineering_process-2.5.0/engineering_process/evidence.py

@@ -0,0 +1,173 @@
+"""Shared runtime and lifecycle evidence identity helpers."""
+
+from __future__ import annotations
+
+from importlib import metadata
+import hashlib
+import os
+import platform
+from pathlib import Path
+import sys
+from typing import Any, Mapping
+
+from . import VERSION
+from .contracts import digest_json
+from .distribution import distribution_digest
+from .repository import same_checkpoint
+
+
+SECRET_MARKERS = ("TOKEN", "SECRET", "PASSWORD", "PASSWD", "API_KEY", "PRIVATE_KEY")
+
+
+def child_environment(
+    *,
+    executable: str | Path | None = None,
+    source: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Project the exact sanitized environment used by consumer checks."""
+    environment: dict[str, str] = {}
+    for name, value in (os.environ if source is None else source).items():
+        upper = name.upper()
+        if name in {"PYTHONHOME", "PYTHONPATH"}:
+            continue
+        if any(marker in upper for marker in SECRET_MARKERS):
+            continue
+        # Empty bindings remain meaningful inputs to a consumer command.
+        environment[name] = value
+    runtime_executable = Path(
+        sys.executable if executable is None else executable
+    ).absolute()
+    runtime_directory = str(runtime_executable.parent)
+    inherited_path = environment.get("PATH", "")
+    path_entries = [entry for entry in inherited_path.split(os.pathsep) if entry]
+    runtime_is_first = bool(path_entries) and (
+        os.path.normcase(os.path.normpath(path_entries[0]))
+        == os.path.normcase(os.path.normpath(runtime_directory))
+    )
+    if not runtime_is_first:
+        path_entries.insert(0, runtime_directory)
+    environment["PATH"] = os.pathsep.join(path_entries)
+    environment["PYTHONUNBUFFERED"] = "1"
+    return environment
+
+
+def execution_identity(
+    *,
+    executable: str | Path | None = None,
+    source: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Return the runtime inputs used to launch consumer checks."""
+    try:
+        # Keep duplicate distribution records: multiplicity is part of the
+        # environment identity, even when records have the same display name.
+        dependencies = sorted(
+            f"{distribution.name}=={distribution.version}@"
+            f"{Path(distribution.locate_file('')).resolve()}"
+            for distribution in metadata.distributions(path=_metadata_search_path())
+        )
+    except Exception:
+        dependency_identity: dict[str, Any] = {"known": False}
+    else:
+        dependency_identity = {
+            "known": True,
+            "count": len(dependencies),
+            "digest": "sha256:" + hashlib.sha256(
+                "\n".join(dependencies).encode("utf-8")
+            ).hexdigest(),
+        }
+    runtime_executable = Path(
+        sys.executable if executable is None else executable
+    ).absolute()
+    return {
+        "executable": str(runtime_executable),
+        "python": sys.version,
+        "platform": platform.platform(),
+        "environment": child_environment(
+            executable=runtime_executable, source=source
+        ),
+        "dependencies": dependency_identity,
+    }
+
+
+def _metadata_search_path() -> list[str]:
+    paths: list[str] = []
+    seen: set[str] = set()
+    for entry in sys.path:
+        value = os.fspath(entry) if entry else os.curdir
+        key = os.path.normcase(str(Path(value).resolve()))
+        if key in seen:
+            continue
+        seen.add(key)
+        paths.append(value)
+    return paths
+
+
+def verification_input_digest(
+    project_root: Path,
+    process_root: Path,
+    project: dict[str, Any],
+    state: dict[str, Any],
+    profile: str,
+    *,
+    runtime: dict[str, Any] | None = None,
+) -> str | None:
+    """Bind reusable evidence to every input controlled by this process."""
+    runtime = runtime if runtime is not None else execution_identity()
+    dependencies = runtime.get("dependencies")
+    if not isinstance(dependencies, Mapping) or dependencies.get("known") is not True:
+        return None
+    return digest_json({
+        "authority": {
+            "version": VERSION,
+            "distribution": distribution_digest(process_root),
+        },
+        "project": project,
+        "contractDigest": state["contract"]["digest"],
+        "planDigest": state["plan"]["digest"] if state.get("plan") else None,
+        "comparisonBaseCommit": state.get("comparisonBaseCommit"),
+        "profile": profile,
+        "projectRoot": str(project_root.resolve()),
+        "runtime": runtime,
+        "host": platform.node(),
+        "pythonImplementation": sys.implementation.name,
+    })
+
+
+def verification_report_matches_inputs(
+    project_root: Path,
+    process_root: Path,
+    project: dict[str, Any],
+    state: dict[str, Any],
+    profile: str,
+    report: dict[str, Any],
+    checkpoint: dict[str, Any],
+    *,
+    require_input: bool,
+    require_explicit_scope: bool = False,
+    runtime: dict[str, Any] | None = None,
+) -> bool:
+    """Return whether one report is reusable for the supplied inputs."""
+    scope = report.get("scope")
+    if scope is None:
+        if require_explicit_scope:
+            return False
+        scope = {"kind": "profile"}
+    if (
+        report.get("profile") != profile
+        or report.get("status") != "passed"
+        or scope != {"kind": "profile"}
+        or not same_checkpoint(report.get("checkpoint", {}), checkpoint)
+    ):
+        return False
+    recorded = report.get("inputDigest")
+    if recorded is None:
+        return not require_input
+    current = verification_input_digest(
+        project_root,
+        process_root,
+        project,
+        state,
+        profile,
+        runtime=runtime,
+    )
+    return current is not None and recorded == current