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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 2.3.0
+Version: 2.4.0
 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,
@@ -86,10 +102,14 @@ 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.
+run. Before final profiles run and before review assignment, the lifecycle checks
+the current branch, head subject, and nonempty pinned comparison-base-to-head range,
+and requires all candidate changes to be committed. Commit before `change verify`;
+a later commit changes the checkpoint even when its source content is identical.
+Local lifecycle run/receipt files and Git-ignored files are excluded. Finish repeats
+the same checks 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 without advancing the lifecycle.
 
 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)
@@ -585,6 +605,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.4.0}/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,
@@ -62,10 +78,14 @@ 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.
+run. Before final profiles run and before review assignment, the lifecycle checks
+the current branch, head subject, and nonempty pinned comparison-base-to-head range,
+and requires all candidate changes to be committed. Commit before `change verify`;
+a later commit changes the checkpoint even when its source content is identical.
+Local lifecycle run/receipt files and Git-ignored files are excluded. Finish repeats
+the same checks 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 without advancing the lifecycle.
 
 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)
@@ -561,6 +581,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.4.0/RELEASE_NOTES.md

@@ -0,0 +1,22 @@
+# Engineering Process v2.4.0
+
+Changes since v2.3.1.
+
+## Features
+
+- Lifecycle guidance helps consumers find authoritative current project knowledge\, maintain only information affected by accepted work or necessary gaps\, and review explanations and useful connections in context\. Existing consumer organization remains valid\; no documentation taxonomy or migration is required\. ([#192](https://github.com/phuongnse/engineering-process/issues/192))
+- Planning\, implementation and review connect tests and other evidence to accepted behavior and concrete risks\, including regression sensitivity and fitting evidence boundaries\. Consumer\-required profiles and testing policies remain authoritative\; no universal test\-first ritual or new test per change is imposed\. ([#193](https://github.com/phuongnse/engineering-process/issues/193))
+
+## Fixes
+
+- Publication\-required changes must commit the complete candidate and pass the existing branch\, subject and nonempty pinned\-range checks before final verification and review\. This avoids a late commit forcing a repeated verification\/review cycle\; exact\-snapshot and finish checks remain enforced\. ([#191](https://github.com/phuongnse/engineering-process/issues/191))
+
+## 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.4.0/VERSIONING.md) and [adoption guidance](https://github.com/phuongnse/engineering-process/blob/v2.4.0/SELF_HOSTING.md).
+
+[Full change comparison](https://github.com/phuongnse/engineering-process/compare/v2.3.1...v2.4.0)

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

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

{engineering_process-2.3.0 → engineering_process-2.4.0}/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.4.0}/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.4.0}/engineering_process/lifecycle.py

@@ -36,7 +36,14 @@ from .production_engineering import (
     validate_review_assessments,
 )
 from .source_publication import branch_issues, current_branch, validate_current_source
-from .repository import repository_snapshot, resolve_commit, same_checkpoint
+from .repository import (
+    repository_snapshot, require_committed_candidate, resolve_commit, same_checkpoint,
+)
+from .review_contexts import (
+    recorded_context_conflict,
+    require_unreused_context,
+    history_transaction,
+)
 
 
 NEXT_COMMAND = {
@@ -134,6 +141,7 @@ def _require_phase(state: dict[str, Any], *phases: str) -> None:
         )
 
 
+@history_transaction
 def start_change(
     project_root: Path,
     process_root: Path,
@@ -215,6 +223,7 @@ def start_change(
     return state
 
 
+@history_transaction
 def register_plan(
     project_root: Path,
     process_root: Path,
@@ -251,6 +260,7 @@ def register_plan(
     return state
 
 
+@history_transaction
 def begin_implementation(
     project_root: Path,
     process_root: Path,
@@ -309,6 +319,33 @@ def begin_implementation(
     return state
 
 
+def _publication_preflight(
+    project_root: Path,
+    project: dict[str, Any],
+    state: dict[str, Any],
+    checkpoint: dict[str, Any],
+) -> dict[str, Any] | None:
+    if not publication_required(project):
+        return None
+    if not (comparison_base := state.get("comparisonBaseCommit")):
+        raise ProcessError("publication requires a pinned comparison base")
+    publication = validate_current_source(project_root, comparison_base)
+    if publication["range"] != f"{comparison_base}..{checkpoint['head']}":
+        raise ProcessError("publication validation does not match the candidate HEAD")
+    if publication["issues"]:
+        raise ProcessError(
+            "publication compatibility checks failed: "
+            + "; ".join(publication["issues"])
+            + "; commit the candidate on a valid publication branch before change verify"
+        )
+    require_committed_candidate(project_root, checkpoint["head"])
+    after = repository_snapshot(project_root)
+    if (not same_checkpoint(checkpoint, after)
+            or current_branch(project_root) != publication["branch"]):
+        raise ProcessError("repository changed while publication validation was running")
+    return publication
+
+
 def verify_change(
     project_root: Path,
     process_root: Path,
@@ -322,13 +359,35 @@ def verify_change(
         raise ProcessError(f"profile {profile} is not required by change {change_id}")
 
     before = repository_snapshot(project_root)
+    _publication_preflight(project_root, project, state, before)
+    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 +415,7 @@ def verify_change(
     return state, report
 
 
+@history_transaction
 def start_review(
     project_root: Path,
     process_root: Path,
@@ -364,9 +424,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 +463,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 +474,13 @@ 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")
+    _publication_preflight(
+        project_root, load_project(project_root, process_root), state, checkpoint
+    )
     state["reviewAssignment"] = {
         "reviewer": reviewer,
         "checkpoint": checkpoint,
@@ -403,11 +491,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 +526,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 +634,7 @@ def submit_review(
     return state
 
 
+@history_transaction
 def finish_change(
     project_root: Path,
     process_root: Path,
@@ -546,28 +646,13 @@ 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)
-    publication = None
-    if publication_required(project):
-        if not (comparison_base := state.get("comparisonBaseCommit")):
-            raise ProcessError("publication completion requires a pinned comparison base")
-        publication = validate_current_source(
-            project_root, comparison_base
-        )
-        if publication["range"] != f"{comparison_base}..{checkpoint['head']}":
-            raise ProcessError("publication validation does not match the reviewed HEAD")
-        after_publication = repository_snapshot(project_root)
-        if (not same_checkpoint(checkpoint, after_publication)
-                or current_branch(project_root) != publication["branch"]):
-            raise ProcessError("repository changed while publication validation was running")
-        if publication["issues"]:
-            raise ProcessError(
-                "publication compatibility checks failed: "
-                + "; ".join(publication["issues"])
-            )
-        checkpoint = after_publication
+    publication = _publication_preflight(project_root, project, state, checkpoint)
     if not same_checkpoint(checkpoint, state["reviewAssignment"]["checkpoint"]):
         raise ProcessError("repository changed after approval")
 

{engineering_process-2.3.0 → engineering_process-2.4.0}/engineering_process/repository.py

@@ -7,6 +7,7 @@ import os
 from pathlib import Path
 import stat
 import subprocess
+import tempfile
 from typing import Any
 
 from .contracts import ProcessError
@@ -18,11 +19,15 @@ MAX_TOTAL_BYTES = 1_000_000_000
 STATE_PREFIXES = (b".process/runs/", b".process/receipts/")
 
 
-def _git(root: Path, arguments: list[str], *, check: bool = True) -> bytes:
+def _git(
+    root: Path, arguments: list[str], *, check: bool = True,
+    env: dict[str, str] | None = None,
+) -> bytes:
     try:
         result = subprocess.run(
             ["git", "-c", "core.quotepath=false", *arguments],
             cwd=root,
+            env=env,
             stdin=subprocess.DEVNULL,
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
@@ -56,6 +61,49 @@ def resolve_commit(root: Path, reference: str) -> str:
     ).decode("ascii").strip()
 
 
+def require_committed_candidate(root: Path, head: str = "HEAD") -> None:
+    root = root.resolve()
+    head = resolve_commit(root, head)
+    environment = dict(os.environ, GIT_OPTIONAL_LOCKS="0")
+    paths = _git(root, [
+        "diff", "--cached", "--name-only", "-z", "--no-ext-diff",
+        "--ignore-submodules=none", head,
+    ], env=environment).split(b"\0")
+    # Git's skip-worktree contract permits absence, not changed materialized content.
+    omitted = {
+        record[2:]
+        for record in _git(root, ["ls-files", "-t", "-z"], env=environment).split(b"\0")
+        if record.startswith(b"S ") and not os.path.lexists(root / os.fsdecode(record[2:]))
+    }
+    # A fresh HEAD index cannot hide worktree changes behind visibility flags or
+    # cached stat data. Keep the consumer's real index and its flags untouched.
+    # Git metadata stays outside snapshots even when TMPDIR is inside the checkout.
+    git_directory = os.fsdecode(_git(root, ["rev-parse", "--absolute-git-dir"]).rstrip(b"\r\n"))
+    with tempfile.TemporaryDirectory(prefix="process-candidate-", dir=git_directory) as directory:
+        environment["GIT_INDEX_FILE"] = str(Path(directory) / "index")
+        inspection = [
+            "-c", "core.fsmonitor=false", "-c", "core.ignoreStat=false",
+            "-c", "core.sparseCheckout=false", "-c", "core.splitIndex=false",
+        ]
+        _git(root, [*inspection, "read-tree", head], env=environment)
+        records = _git(root, [
+            *inspection, "status", "--porcelain=v1", "-z", "--untracked-files=all",
+            "--no-renames", "--ignore-submodules=none",
+        ], env=environment).split(b"\0")
+        for record in records:
+            if not record:
+                continue
+            path = record[3:]
+            if record.startswith(b" D ") and path in omitted:
+                continue
+            paths.append(path)
+    if any(path and not path.startswith(STATE_PREFIXES) for path in paths):
+        raise ProcessError(
+            "publication requires committed candidate changes; commit or remove "
+            "uncommitted changes before change verify"
+        )
+
+
 def repository_snapshot(root: Path) -> dict[str, Any]:
     root = root.resolve()
     if not (root / ".git").exists():