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

{engineering_process-2.3.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.3.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,35 @@ 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 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,
@@ -585,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.3.0 → engineering_process-2.3.1}/README.md

@@ -40,19 +40,35 @@ 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 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,
@@ -561,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.3.0 → engineering_process-2.3.1}/engineering_process/__init__.py

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

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

@@ -330,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),
@@ -542,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)

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

@@ -51,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.0 → engineering_process-2.3.1}/engineering_process/lifecycle.py

@@ -37,6 +37,11 @@ from .production_engineering import (
 )
 from .source_publication import branch_issues, current_branch, validate_current_source
 from .repository import repository_snapshot, resolve_commit, same_checkpoint
+from .review_contexts import (
+    recorded_context_conflict,
+    require_unreused_context,
+    history_transaction,
+)
 
 
 NEXT_COMMAND = {
@@ -134,6 +139,7 @@ def _require_phase(state: dict[str, Any], *phases: str) -> None:
         )
 
 
+@history_transaction
 def start_change(
     project_root: Path,
     process_root: Path,
@@ -215,6 +221,7 @@ def start_change(
     return state
 
 
+@history_transaction
 def register_plan(
     project_root: Path,
     process_root: Path,
@@ -251,6 +258,7 @@ def register_plan(
     return state
 
 
+@history_transaction
 def begin_implementation(
     project_root: Path,
     process_root: Path,
@@ -322,13 +330,34 @@ def verify_change(
         raise ProcessError(f"profile {profile} is not required by change {change_id}")
 
     before = repository_snapshot(project_root)
+    report = run_profile(project_root, project, profile)
+    return _record_verification(
+        project_root, process_root, change_id, state["cycle"], before, report
+    )
+
+
+@history_transaction
+def _record_verification(
+    project_root: Path,
+    process_root: Path,
+    change_id: str,
+    cycle: int,
+    before: dict[str, Any],
+    report: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    # Profiles run outside the lock. Reload so their publication cannot erase
+    # participants or evidence recorded by another command while they ran.
+    state = _load_state(project_root, process_root, change_id)
+    _require_phase(state, "implementing")
+    if state["cycle"] != cycle:
+        raise ProcessError("implementation cycle changed while verification was running")
     state["verification"] = {
         name: report
         for name, report in state["verification"].items()
         if same_checkpoint(report["checkpoint"], before)
     }
-    report = run_profile(project_root, project, profile)
     after = repository_snapshot(project_root)
+    profile = report["profile"]
     report["checkpoint"] = after
     report["recordedAt"] = _now()
     if not same_checkpoint(before, after):
@@ -356,6 +385,7 @@ def verify_change(
     return state, report
 
 
+@history_transaction
 def start_review(
     project_root: Path,
     process_root: Path,
@@ -364,9 +394,29 @@ def start_review(
     actor_id: str,
     context_id: str,
     kind: str,
+    replace_reused: bool = False,
 ) -> dict[str, Any]:
     state = _load_state(project_root, process_root, change_id)
-    _require_phase(state, "verified")
+    previous_assignment = conflict = None
+    if replace_reused:
+        _require_phase(state, "review-pending")
+        if (state["reviewAssignment"] is None or state["review"] is not None
+                or state["reviewHistory"]
+                or any(event["event"] == "review-submitted" for event in state["history"])):
+            raise ProcessError("only an unsubmitted initial review assignment can be replaced")
+        previous_assignment = deepcopy(state["reviewAssignment"])
+        if previous_assignment["reviewer"]["kind"] != "agent":
+            raise ProcessError("replace-reused requires a recorded reused agent context")
+        report_path = _run_path(project_root, change_id).with_name(f"review-{state['cycle']}.json")
+        if report_path.exists() or report_path.is_symlink():
+            raise ProcessError("a review report already exists; assignment replacement would discard it")
+        conflict = recorded_context_conflict(
+            project_root, process_root, state, previous_assignment["reviewer"]["contextId"]
+        )
+        if conflict is None:
+            raise ProcessError("the pending reviewer context has no recorded cross-change reuse")
+    else:
+        _require_phase(state, "verified")
     reviewer = _actor(actor_id, context_id, kind)
     if state["reviewHistory"]:
         original_reviewer = state["reviewHistory"][0]["document"]["reviewer"]
@@ -383,6 +433,7 @@ def start_review(
         raise ProcessError("reviewer actor must be independent from implementation")
     if any(item["contextId"] == reviewer["contextId"] for item in implementers):
         raise ProcessError("reviewer context must be independent from implementation")
+    require_unreused_context(project_root, process_root, state, reviewer)
 
     checkpoint = repository_snapshot(project_root)
     required = state["contract"]["document"]["requiredProfiles"]
@@ -393,6 +444,10 @@ def start_review(
         for name in required
     ):
         raise ProcessError("verification evidence is stale or incomplete")
+    if previous_assignment is not None and not same_checkpoint(
+        previous_assignment["checkpoint"], checkpoint
+    ):
+        raise ProcessError("repository changed after the reused review assignment")
     state["reviewAssignment"] = {
         "reviewer": reviewer,
         "checkpoint": checkpoint,
@@ -403,11 +458,21 @@ def start_review(
         ),
     }
     state["phase"] = "review-pending"
-    _event(state, "review-started", reviewer)
+    if previous_assignment is None:
+        _event(state, "review-started", reviewer)
+    else:
+        _event(
+            state, "review-assignment-replaced", reviewer,
+            reason="cross-change-context-reuse",
+            previousAssignment=previous_assignment,
+            replacementAssignment=deepcopy(state["reviewAssignment"]),
+            conflict=conflict,
+        )
     _save_state(project_root, process_root, state)
     return state
 
 
+@history_transaction
 def submit_review(
     project_root: Path,
     process_root: Path,
@@ -428,6 +493,7 @@ def submit_review(
         raise ProcessError("review changeId does not match lifecycle state")
     if review["reviewer"] != assignment["reviewer"]:
         raise ProcessError("reviewer does not match the assigned independent identity")
+    require_unreused_context(project_root, process_root, state, assignment["reviewer"])
     if not same_checkpoint(review["checkpoint"], assignment["checkpoint"]):
         raise ProcessError("review checkpoint does not match the assignment")
     current = repository_snapshot(project_root)
@@ -535,6 +601,7 @@ def submit_review(
     return state
 
 
+@history_transaction
 def finish_change(
     project_root: Path,
     process_root: Path,
@@ -546,6 +613,9 @@ def finish_change(
 ) -> tuple[dict[str, Any], dict[str, Any]]:
     state = _load_state(project_root, process_root, change_id)
     _require_phase(state, "approved")
+    require_unreused_context(
+        project_root, process_root, state, state["reviewAssignment"]["reviewer"]
+    )
     actor = _actor(actor_id, context_id, kind)
     project = load_project(project_root, process_root)
     checkpoint = repository_snapshot(project_root)

engineering_process-2.3.1/engineering_process/review_contexts.py

@@ -0,0 +1,291 @@
+"""Recorded reviewer-context ownership within one Git repository."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from functools import wraps
+import os
+from pathlib import Path
+import stat
+import subprocess
+import tempfile
+import time
+from typing import Any, Callable, Iterator
+
+from .contracts import (
+    MAX_JSON_BYTES,
+    ProcessError,
+    digest_json,
+    parse_json_bytes,
+    validate_document,
+)
+from .distribution import schemas_root
+
+
+MAX_WORKTREES = 64
+MAX_RUN_ENTRIES = 512
+MAX_TOTAL_BYTES = 64_000_000
+MAX_GIT_BYTES = 256_000
+GIT_TIMEOUT_SECONDS = 10
+SCAN_TIMEOUT_SECONDS = 30
+LOCK_TIMEOUT_SECONDS = 10
+
+
+def _check_deadline(deadline: float) -> None:
+    if time.monotonic() >= deadline:
+        raise ProcessError("review history exceeds its time limit")
+
+
+def _git(root: Path, arguments: list[str], *, deadline: float | None = None) -> bytes:
+    # These fixed metadata commands cannot invoke a pager or consumer shell command.
+    command_deadline = time.monotonic() + GIT_TIMEOUT_SECONDS
+    if deadline is not None:
+        _check_deadline(deadline)
+        command_deadline = min(command_deadline, deadline)
+    with tempfile.TemporaryFile() as output:
+        try:
+            process = subprocess.Popen(
+                ["git", "--no-pager", *arguments], cwd=root,
+                stdin=subprocess.DEVNULL, stdout=output, stderr=subprocess.STDOUT,
+            )
+        except OSError as error:
+            raise ProcessError(f"cannot inspect review worktrees: {error}") from error
+        try:
+            while process.poll() is None:
+                if os.fstat(output.fileno()).st_size > MAX_GIT_BYTES:
+                    raise ProcessError("review worktree Git output exceeded its byte limit")
+                if time.monotonic() >= command_deadline:
+                    raise ProcessError("review worktree Git command timed out")
+                time.sleep(0.01)
+            output.seek(0)
+            content = output.read(MAX_GIT_BYTES + 1)
+            if len(content) > MAX_GIT_BYTES:
+                raise ProcessError("review worktree Git output exceeded its byte limit")
+            if process.returncode:
+                detail = content[:2000].decode("utf-8", errors="replace").strip()
+                raise ProcessError(f"cannot inspect review worktrees: {detail}")
+            if deadline is not None:
+                _check_deadline(deadline)
+            return content
+        finally:
+            if process.poll() is None:
+                process.kill()
+            process.wait(timeout=5)
+
+
+def _safe_info(path: Path, *, directory: bool) -> os.stat_result:
+    info = path.lstat()
+    reparse = getattr(info, "st_file_attributes", 0) & getattr(
+        stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0
+    )
+    if stat.S_ISLNK(info.st_mode) or reparse:
+        raise ProcessError(f"review history must not traverse a link or reparse point: {path}")
+    expected = stat.S_ISDIR if directory else stat.S_ISREG
+    if not expected(info.st_mode):
+        raise ProcessError(f"review history has an unsupported file type: {path}")
+    return info
+
+
+def _identity(info: os.stat_result) -> tuple[int, ...]:
+    return (info.st_dev, info.st_ino, info.st_mode, info.st_size, info.st_mtime_ns)
+
+
+def _directory_identity(path: Path) -> tuple[int, ...]:
+    info = _safe_info(path, directory=True)
+    return (info.st_dev, info.st_ino, info.st_mode)
+
+
+def _common_directory(root: Path, *, deadline: float | None = None) -> Path:
+    result = _git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"],
+                  deadline=deadline)
+    path = Path(os.fsdecode(result.removesuffix(b"\n")))
+    if not path.is_absolute():
+        raise ProcessError("Git common directory must be absolute")
+    _safe_info(path, directory=True)
+    return path.resolve()
+
+
+@contextmanager
+def _review_lock(root: Path) -> Iterator[None]:
+    common = _common_directory(root)
+    path = common / "engineering-process-review.lock"
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0)
+    descriptor = os.open(path, flags, 0o600)
+    try:
+        opened = os.fstat(descriptor)
+        current = _safe_info(path, directory=False)
+        if (current.st_dev, current.st_ino, current.st_mode) != (
+            opened.st_dev, opened.st_ino, opened.st_mode
+        ):
+            raise ProcessError("review transaction lock changed while opening")
+        deadline = time.monotonic() + LOCK_TIMEOUT_SECONDS
+        while True:
+            try:
+                if os.name == "nt":
+                    import msvcrt
+                    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)
+                break
+            except OSError as error:
+                if time.monotonic() >= deadline:
+                    raise ProcessError("review transaction lock timed out") from error
+                time.sleep(0.02)
+        try:
+            current = _safe_info(path, directory=False)
+            if (current.st_dev, current.st_ino) != (opened.st_dev, opened.st_ino):
+                raise ProcessError("review transaction lock was replaced")
+            yield
+        finally:
+            if os.name == "nt":
+                os.lseek(descriptor, 0, os.SEEK_SET)
+                msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)
+            else:
+                fcntl.flock(descriptor, fcntl.LOCK_UN)
+    finally:
+        os.close(descriptor)
+
+
+def history_transaction(function: Callable[..., Any]) -> Callable[..., Any]:
+    @wraps(function)
+    def locked(project_root: Path, *args: Any, **kwargs: Any) -> Any:
+        try:
+            with _review_lock(project_root):
+                return function(project_root, *args, **kwargs)
+        except OSError as error:
+            raise ProcessError(f"cannot inspect or lock lifecycle history: {error}") from error
+    return locked
+
+
+def _worktrees(root: Path, *, deadline: float) -> list[Path]:
+    raw = _git(root, ["worktree", "list", "--porcelain", "-z"], deadline=deadline)
+    roots = []
+    for record in raw.split(b"\0\0"):
+        _check_deadline(deadline)
+        if not record:
+            continue
+        fields = record.split(b"\0")
+        if not fields[0].startswith(b"worktree "):
+            raise ProcessError("Git returned an invalid review worktree record")
+        if b"bare" in fields:
+            continue
+        path = Path(os.fsdecode(fields[0][len(b"worktree "):]))
+        if not path.is_absolute():
+            raise ProcessError("review worktree paths must be absolute")
+        _safe_info(path, directory=True)
+        roots.append(path.resolve())
+        if len(roots) > MAX_WORKTREES:
+            raise ProcessError("review history exceeds its worktree limit")
+    if root.resolve() not in roots or len(roots) != len(set(roots)):
+        raise ProcessError("Git returned an incomplete or duplicate review worktree inventory")
+    return sorted(roots)
+
+
+def _read_run(path: Path, parents: list[Path], process_root: Path) -> tuple[dict[str, Any], int]:
+    before = [_directory_identity(parent) for parent in parents]
+    info = _safe_info(path, directory=False)
+    if info.st_size > MAX_JSON_BYTES:
+        raise ProcessError(f"{path} exceeds {MAX_JSON_BYTES} bytes")
+    descriptor = os.open(
+        path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+        | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0),
+    )
+    with os.fdopen(descriptor, "rb") as stream:
+        if _identity(os.fstat(stream.fileno())) != _identity(info):
+            raise ProcessError(f"review history changed while opening: {path}")
+        if before != [_directory_identity(parent) for parent in parents]:
+            raise ProcessError(f"review history path changed while opening: {path}")
+        content = stream.read(MAX_JSON_BYTES + 1)
+        after = _safe_info(path, directory=False)
+        if _identity(after) != _identity(info) or len(content) != info.st_size:
+            raise ProcessError(f"review history changed while reading: {path}")
+    if before != [_directory_identity(parent) for parent in parents]:
+        raise ProcessError(f"review history path changed while reading: {path}")
+    state = validate_document(
+        parse_json_bytes(content, source=str(path)), "run",
+        schema_root=schemas_root(process_root), source=str(path),
+    )
+    if state["changeId"] != path.parent.name:
+        raise ProcessError(f"{path}: change identity mismatch")
+    return state, len(content)
+
+
+def recorded_context_conflict(
+    project_root: Path, process_root: Path, current: dict[str, Any], context_id: str,
+) -> dict[str, str] | None:
+    """Return one recorded foreign use; absence only covers the inspected history."""
+    deadline = time.monotonic() + SCAN_TIMEOUT_SECONDS
+    common = _common_directory(project_root, deadline=deadline)
+    roots = _worktrees(project_root, deadline=deadline)
+    accepted = (current["changeId"], current["contract"]["digest"])
+    total = entries = 0
+    for root in roots:
+        _check_deadline(deadline)
+        if _common_directory(root, deadline=deadline) != common:
+            raise ProcessError(f"registered review worktree changed repository: {root}")
+        process = root / ".process"
+        runs = process / "runs"
+        try:
+            _safe_info(process, directory=True)
+            _safe_info(runs, directory=True)
+        except FileNotFoundError:
+            _check_deadline(deadline)
+            continue
+        directories = []
+        with os.scandir(runs) as children:
+            for child in children:
+                entries += 1
+                if entries > MAX_RUN_ENTRIES or time.monotonic() >= deadline:
+                    raise ProcessError("review history exceeds its entry or time limit")
+                directories.append(Path(child.path))
+        for directory in sorted(directories):
+            _check_deadline(deadline)
+            info = directory.lstat()
+            if stat.S_ISREG(info.st_mode):
+                continue
+            _safe_info(directory, directory=True)
+            path = directory / "run.json"
+            try:
+                path.lstat()
+            except FileNotFoundError:
+                continue
+            state, size = _read_run(path, [root, process, runs, directory], process_root)
+            _check_deadline(deadline)
+            total += size
+            if total > MAX_TOTAL_BYTES:
+                raise ProcessError("review history exceeds its aggregate byte limit")
+            if (state["changeId"], state["contract"]["digest"]) == accepted:
+                continue
+            actors = [event["actor"] for event in state["history"]]
+            actors.extend(item["actor"] for item in state["implementations"])
+            if state["reviewAssignment"] is not None:
+                actors.append(state["reviewAssignment"]["reviewer"])
+            for event in state["history"]:
+                if event["event"] == "review-assignment-replaced":
+                    actors.append(event["details"]["previousAssignment"]["reviewer"])
+            if any(actor["contextId"] == context_id for actor in actors):
+                return {
+                    "changeId": state["changeId"],
+                    "contractDigest": state["contract"]["digest"],
+                    "runPath": str(path),
+                    "runDigest": digest_json(state),
+                }
+    if _worktrees(project_root, deadline=deadline) != roots:
+        raise ProcessError("review worktree inventory changed during inspection")
+    _check_deadline(deadline)
+    return None
+
+
+def require_unreused_context(
+    project_root: Path, process_root: Path, state: dict[str, Any], reviewer: dict[str, str],
+) -> None:
+    if reviewer["kind"] != "agent":
+        return
+    conflict = recorded_context_conflict(project_root, process_root, state, reviewer["contextId"])
+    if conflict is not None:
+        raise ProcessError(
+            f"reviewer context was used by another change: {conflict['changeId']} "
+            f"({conflict['runPath']}); spawn a fresh reviewer for this change"
+        )