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

{engineering_process-2.3.1/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.1
+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
@@ -102,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)

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

@@ -78,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)

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.1 → engineering_process-2.4.0}/engineering_process/__init__.py

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

{engineering_process-2.3.1 → engineering_process-2.4.0}/engineering_process/lifecycle.py

@@ -36,7 +36,9 @@ 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,
@@ -317,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,
@@ -330,6 +359,7 @@ 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
@@ -448,6 +478,9 @@ def start_review(
         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,
@@ -619,25 +652,7 @@ def finish_change(
     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.1 → 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():

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 2.3.1
+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
@@ -102,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)

{engineering_process-2.3.1 → engineering_process-2.4.0}/process_assets/skills/change-implement/SKILL.md

@@ -13,8 +13,24 @@ Every delegated actor/context that may mutate the candidate must run the same co
 before its first edit. During an active cycle the command appends that participant
 without starting another cycle; review checks all registered participants.
 
-Implement only the current plan. Add focused regression coverage for deterministic
-defects and keep consumer-owned policy in the consumer. If review requested changes,
+Implement only the current plan and keep consumer-owned policy in the consumer.
+For a deterministic defect, add focused regression evidence that distinguishes the
+reported faulty behavior from the correction. When a known-faulty state is safely
+available, demonstrate that distinction; no proof of test-authoring or execution
+order is required. Each added or materially changed test or check must protect accepted
+behavior, a contract boundary, or a concrete risk, rather than merely execute changed
+code or mirror its structure. Retain consumer-mandated checks; do not manufacture a
+new automated test when existing evidence suffices or other evidence better fits the
+change. Focused checks support diagnosis and implementation; required full profiles
+still run on the final unchanged candidate.
+
+Update, supplement, or create only the project information needed for the planned
+knowledge repairs, using inspected behavior, accepted requirements, and recorded
+decisions. Replaced material is updated, removed, or visibly marked historical or
+superseded when retaining it is useful. Explain enough for the intended reader and
+accepted work, in a logical order, with references that clarify relevant relationships.
+
+If review requested changes,
 resolve every blocking finding in the next cycle without renaming or dropping it.
 Follow every applicable **production-engineering** assessment and make its named work
 items produce the planned objective evidence. If implementation proves an

{engineering_process-2.3.1 → engineering_process-2.4.0}/process_assets/skills/change-plan/SKILL.md

@@ -18,6 +18,21 @@ maintenance change, accounting for indirection and coupling. Bind needed design
 to existing work-item outcomes. Keep reasoning proportional; retaining a clear
 existing structure is a valid choice.
 
+Identify project knowledge this change would make misleading, incomplete, or obsolete,
+and concrete information gaps obstructing the accepted work. Plan only the necessary
+updates or additions in consumer-owned sources. Any proposed cleanup names the
+obstacle, smallest useful repair, and expected benefit; unrelated gaps remain
+non-blocking proposals.
+
+Explain a material or non-obvious evidence strategy in the existing `approach`, tied
+to accepted behavior, contract boundaries, and concrete risks. Derive expectations
+for new deterministic behavior from acceptance criteria and important cases; preserve
+behavioral evidence for refactors, and select an integration boundary capable of
+observing the relevant contract or failure. Documentation, configuration, visual, or
+exploratory work may use suitable checks or contextual review. These are defaults;
+preserve consumer-mandated testing policies. An obvious existing verification path
+needs no repeated rationale or additional record.
+
 Read **production-engineering** and add one `productionEngineering` assessment for
 each canonical invariant in its defined order. Decide applicability from the stated
 trigger, give a concrete rationale, and bind every applicable invariant to the work

{engineering_process-2.3.1 → engineering_process-2.4.0}/process_assets/skills/change-review/SKILL.md

@@ -102,6 +102,24 @@ Apply the existing blocking rules to demonstrated violations even when tests pas
 preference for a pattern, shorter code, or a different valid structure is insufficient.
 Do not retrofit new design criteria into the frozen contract.
 
+Assess relevant project knowledge against implementation and accepted requirements:
+can the intended reader find the authoritative current source, understand sufficient
+explanations in a logical order, and use meaningful connections where helpful? A
+finding names a concrete error, necessary missing explanation, confusing organization,
+or missing/misleading connection and its consequence for the work. A different folder,
+heading, or style preference is insufficient. Consumer checks can prove properties
+such as valid links, runnable examples, parseable structure, or rendering; presence,
+length, formatting, and resolving links do not establish semantic usefulness or truth.
+
+Assess whether material test expectations follow the accepted contract, important
+claimed risks are actually exercised, and the execution boundary could detect the
+claimed failure. Reject assertions overfitted to implementation details when they do
+not protect observable behavior. Findings identify an accepted behavior or applicable
+contract and a concrete consequence; tests must not introduce new product behavior.
+Test counts, coverage percentages, or green profiles alone do not establish adequacy.
+No newly added test is required when existing evidence protects the behavior or an
+automated behavioral check is not meaningful; preserve consumer-mandated policies.
+
 Read **production-engineering** and independently reassess every canonical invariant.
 Use the report's `productionEngineering` entries to record `satisfied`,
 `not-applicable`, or `violated`; cite concrete snapshot evidence for each satisfied

{engineering_process-2.3.1 → engineering_process-2.4.0}/process_assets/skills/change-start/SKILL.md

@@ -10,6 +10,13 @@ behavior. Write a change contract containing the source request, comparison base
 risk, affected projects, observable acceptance criteria, and required verification
 profiles. Do not decide unresolved product behavior silently.
 
+Use a clear consumer-owned reading entry point to locate the project knowledge needed
+for this work. Reuse coherent existing sources; consumers choose their organization
+and document types, without placeholders for irrelevant material. Where sources could
+conflict, establish which is authoritative and which is current or superseded. A
+missing entry point or necessary explanation calls for a focused repair, not a broad
+documentation migration.
+
 When the work produces an issue record, PR description, release notes or an automation name, inspect the consumer's
 selected artifact standard and existing publication checks. The consumer may override
 the packaged defaults. Keep document-format choices separate from lifecycle approval.

{engineering_process-2.3.1 → engineering_process-2.4.0}/process_assets/skills/change-verify/SKILL.md

@@ -5,8 +5,14 @@ description: Run the project-owned verification profiles on one unchanged reposi
 
 # Verify a change
 
-Read the registered acceptance criteria and .process/project.json. Run every required
-profile through the lifecycle:
+Read the registered acceptance criteria and .process/project.json. When publication
+is required, commit the complete candidate on a valid publication branch before final
+verification. The lifecycle rejects uncommitted candidate changes or an invalid or
+empty pinned-base-to-HEAD range before running a profile, and rechecks before review.
+Lifecycle run/receipt files remain local. A later commit, even with identical source
+content, changes the checkpoint and requires fresh verification and review.
+
+Run every required profile through the lifecycle:
 
     processctl change verify --change-id ID --profile PROFILE
 

{engineering_process-2.3.1 → engineering_process-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "engineering-process"
-version = "2.3.1"
+version = "2.4.0"
 description = "A small agent-neutral engineering lifecycle with managed adoption"
 readme = "README.md"
 license = "MIT"

{engineering_process-2.3.1 → engineering_process-2.4.0}/tests/test_lifecycle.py

@@ -9,6 +9,7 @@ import tempfile
 import unittest
 from unittest.mock import patch
 
+from engineering_process.commands import run_profile
 from engineering_process.contracts import ProcessError, digest_json
 from engineering_process.artifact_standards import resolve_standard
 from engineering_process.lifecycle import (
@@ -365,6 +366,122 @@ class LifecycleTests(unittest.TestCase):
             (self.root / ".process" / "receipts" / "sample-change.json").exists()
         )
 
+    def test_publication_rejects_empty_range_before_profiles_then_committed_candidate_finishes(self) -> None:
+        self.prepare_publication_candidate()
+        self.contract["comparisonBase"] = "HEAD"
+        self.plan["contractDigest"] = digest_json(self.contract)
+        write_json(self.contract_path, self.contract)
+        write_json(self.plan_path, self.plan)
+        git(self.root, "add", ".")
+        git(self.root, "commit", "-qm", "fix: select initial boundary")
+        self.begin()
+        (self.root / "product.txt").write_text("corrected\n", encoding="utf-8")
+        state_path = self.root / ".process/runs/sample-change/run.json"
+        before = state_path.read_bytes()
+        with patch("engineering_process.lifecycle.run_profile", wraps=run_profile) as runner:
+            with self.assertRaisesRegex(ProcessError, "at least one commit.*before change verify"):
+                verify_change(self.root, PROCESS_ROOT, self.project, "sample-change", "development")
+            runner.assert_not_called()
+        self.assertEqual(before, state_path.read_bytes())
+
+        git(self.root, "add", "product.txt")
+        git(self.root, "commit", "-qm", "fix: commit corrected candidate")
+        self.verify_all()
+        start_review(self.root, PROCESS_ROOT, "sample-change",
+                     actor_id="reviewer", context_id="review-context", kind="agent")
+        review_path = self.root / ".process/runs/review-input.json"
+        write_json(review_path, self.review_document("approved"))
+        submit_review(self.root, PROCESS_ROOT, "sample-change", review_path)
+        state, receipt = finish_change(self.root, PROCESS_ROOT, "sample-change",
+                                      actor_id="coordinator", context_id="finish-context", kind="agent")
+        self.assertEqual(1, state["cycle"])
+        self.assertEqual("completed", state["phase"])
+        self.assertEqual("fix: commit corrected candidate", receipt["publication"]["subject"])
+
+    def test_publication_verify_rejects_dirty_candidate_before_profiles(self) -> None:
+        self.prepare_publication_candidate()
+        self.begin()
+        (self.root / "product.txt").write_text("not committed\n", encoding="utf-8")
+        state_path = self.root / ".process/runs/sample-change/run.json"
+        before = state_path.read_bytes()
+        with patch("engineering_process.lifecycle.run_profile", wraps=run_profile) as runner:
+            with self.assertRaisesRegex(ProcessError, "committed candidate changes"):
+                verify_change(self.root, PROCESS_ROOT, self.project, "sample-change", "development")
+            runner.assert_not_called()
+        self.assertEqual(before, state_path.read_bytes())
+
+    def test_publication_review_rechecks_branch_without_assigning_reviewer(self) -> None:
+        self.prepare_publication_candidate()
+        self.begin()
+        self.verify_all()
+        state_path = self.root / ".process/runs/sample-change/run.json"
+        before = state_path.read_bytes()
+        git(self.root, "branch", "-M", "codex/invalid")
+        with self.assertRaisesRegex(ProcessError, "publication compatibility checks failed"):
+            start_review(self.root, PROCESS_ROOT, "sample-change",
+                         actor_id="reviewer", context_id="review-context", kind="agent")
+        self.assertEqual(before, state_path.read_bytes())
+
+    def test_publication_verify_rejects_changes_hidden_by_index_flags(self) -> None:
+        self.prepare_publication_candidate()
+        self.begin()
+        state_path = self.root / ".process/runs/sample-change/run.json"
+        before = state_path.read_bytes()
+        for flag in ("--assume-unchanged", "--skip-worktree"):
+            with self.subTest(flag=flag):
+                git(self.root, "update-index", flag, "product.txt")
+                (self.root / "product.txt").write_text("hidden change\n", encoding="utf-8")
+                with patch("engineering_process.lifecycle.run_profile", wraps=run_profile) as runner:
+                    with self.assertRaisesRegex(ProcessError, "committed candidate changes"):
+                        verify_change(self.root, PROCESS_ROOT, self.project, "sample-change", "development")
+                    runner.assert_not_called()
+                self.assertEqual(before, state_path.read_bytes())
+                git(self.root, "update-index", "--no-assume-unchanged", "product.txt")
+                git(self.root, "update-index", "--no-skip-worktree", "product.txt")
+
+    def test_publication_verify_rejects_head_mutation_during_preflight(self) -> None:
+        self.prepare_publication_candidate()
+        self.begin()
+        state_path = self.root / ".process/runs/sample-change/run.json"
+        before = state_path.read_bytes()
+
+        def change_head(root: Path, base: str) -> dict:
+            result = validate_current_source(root, base)
+            git(root, "commit", "--allow-empty", "-qm", "fix: concurrent commit")
+            return result
+
+        with patch("engineering_process.lifecycle.validate_current_source", side_effect=change_head):
+            with patch("engineering_process.lifecycle.run_profile", wraps=run_profile) as runner:
+                with self.assertRaisesRegex(ProcessError, "repository changed while publication"):
+                    verify_change(self.root, PROCESS_ROOT, self.project, "sample-change", "development")
+                runner.assert_not_called()
+        self.assertEqual(before, state_path.read_bytes())
+
+    def test_publication_review_rejects_legacy_dirty_verification(self) -> None:
+        self.prepare_publication_candidate()
+        self.begin()
+        (self.root / "product.txt").write_text("legacy uncommitted candidate\n", encoding="utf-8")
+        # Reproduce evidence recorded by a process without the early preflight.
+        with patch("engineering_process.lifecycle._publication_preflight"):
+            self.verify_all()
+        state_path = self.root / ".process/runs/sample-change/run.json"
+        before = state_path.read_bytes()
+        with self.assertRaisesRegex(ProcessError, "committed candidate changes"):
+            start_review(self.root, PROCESS_ROOT, "sample-change",
+                         actor_id="reviewer", context_id="review-context", kind="agent")
+        self.assertEqual(before, state_path.read_bytes())
+
+    def test_metadata_only_commit_still_invalidates_verification(self) -> None:
+        self.prepare_publication_candidate()
+        self.begin()
+        self.verify_all()
+        before = repository_snapshot(self.root)
+        git(self.root, "commit", "--allow-empty", "-qm", "fix: metadata-only change")
+        self.assertEqual(before["fingerprint"], repository_snapshot(self.root)["fingerprint"])
+        with self.assertRaisesRegex(ProcessError, "verification evidence is stale or incomplete"):
+            start_review(self.root, PROCESS_ROOT, "sample-change",
+                         actor_id="reviewer", context_id="review-context", kind="agent")
+
     def test_publication_finish_records_validated_source_metadata(self) -> None:
         base = self.approve_publication_candidate(moving_base=True)
         head = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=self.root, text=True, timeout=30).strip()
@@ -432,7 +549,7 @@ class LifecycleTests(unittest.TestCase):
                 git(root, "update-ref", "HEAD", original)
 
         with patch("engineering_process.lifecycle.validate_current_source", side_effect=validate_other_head):
-            with self.assertRaisesRegex(ProcessError, "does not match the reviewed HEAD"):
+            with self.assertRaisesRegex(ProcessError, "does not match the candidate HEAD"):
                 finish_change(self.root, PROCESS_ROOT, "sample-change",
                               actor_id="coordinator", context_id="finish-context", kind="agent")
         self.assertEqual(original, repository_snapshot(self.root)["head"])

engineering_process-2.4.0/tests/test_repository.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from engineering_process.contracts import ProcessError
+from engineering_process import repository
+from engineering_process.repository import (
+    repository_snapshot, require_committed_candidate, resolve_commit, same_checkpoint,
+)
+
+
+def git(root: Path, *arguments: str) -> None:
+    subprocess.run(["git", *arguments], cwd=root, check=True, capture_output=True)
+
+
+class RepositorySnapshotTests(unittest.TestCase):
+    def make_repository(self, root: Path) -> None:
+        git(root, "init", "-q")
+        git(root, "config", "user.email", "tests@example.invalid")
+        git(root, "config", "user.name", "Tests")
+        (root / ".gitignore").write_text("/.process/runs/\n/.process/receipts/\n", encoding="utf-8")
+        (root / "tracked.txt").write_text("one\n", encoding="utf-8")
+        git(root, "add", ".")
+        git(root, "commit", "-qm", "initial")
+
+    def test_tracked_and_untracked_content_change_fingerprint(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.make_repository(root)
+            initial = repository_snapshot(root)
+            (root / "tracked.txt").write_text("two\n", encoding="utf-8")
+            tracked = repository_snapshot(root)
+            self.assertFalse(same_checkpoint(initial, tracked))
+            (root / "new.txt").write_text("new\n", encoding="utf-8")
+            untracked = repository_snapshot(root)
+            self.assertFalse(same_checkpoint(tracked, untracked))
+
+    def test_resolve_commit_accepts_branches_and_peels_annotated_tags(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.make_repository(root)
+            git(root, "branch", "review-base")
+            git(root, "tag", "-a", "review-tag", "-m", "Review boundary")
+            expected = repository_snapshot(root)["head"]
+            for reference in ("HEAD", "review-base", "review-tag"):
+                with self.subTest(reference=reference):
+                    self.assertEqual(expected, resolve_commit(root, reference))
+
+    def test_lifecycle_state_does_not_invalidate_its_own_checkpoint(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.make_repository(root)
+            initial = repository_snapshot(root)
+            state = root / ".process" / "runs" / "change" / "run.json"
+            state.parent.mkdir(parents=True)
+            state.write_text("{}\n", encoding="utf-8")
+            receipt = root / ".process" / "receipts" / "change.json"
+            receipt.parent.mkdir(parents=True)
+            receipt.write_text("{}\n", encoding="utf-8")
+            self.assertTrue(same_checkpoint(initial, repository_snapshot(root)))
+
+    def test_committed_candidate_ignores_only_lifecycle_state_and_ignored_files(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.make_repository(root)
+            # State remains excluded even in consumers without matching ignore rules.
+            (root / ".gitignore").write_text("ignored.txt\n", encoding="utf-8")
+            git(root, "add", ".gitignore")
+            git(root, "commit", "-qm", "fix: consumer ignore rules")
+            for relative in (".process/runs/sample/run.json", ".process/receipts/sample.json", "ignored.txt"):
+                path = root / relative
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text("local\n", encoding="utf-8")
+            require_committed_candidate(root)
+            (root / ".process/project.json").write_text("{}\n", encoding="utf-8")
+            with self.assertRaisesRegex(ProcessError, "committed candidate changes"):
+                require_committed_candidate(root)
+
+    def test_committed_candidate_rejects_worktree_index_and_untracked_changes(self) -> None:
+        for change in ("unstaged", "staged", "index-only", "untracked", "deleted", "renamed"):
+            with self.subTest(change=change), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                self.make_repository(root)
+                tracked = root / "tracked.txt"
+                if change == "untracked":
+                    (root / "new name-é.txt").write_text("new\n", encoding="utf-8")
+                elif change == "deleted":
+                    tracked.unlink()
+                elif change == "renamed":
+                    git(root, "mv", "tracked.txt", "renamed.txt")
+                else:
+                    tracked.write_text("two\n", encoding="utf-8")
+                    if change in ("staged", "index-only"):
+                        git(root, "add", "tracked.txt")
+                    if change == "index-only":
+                        tracked.write_text("one\n", encoding="utf-8")
+                with self.assertRaisesRegex(ProcessError, "committed candidate changes.*before change verify"):
+                    require_committed_candidate(root)
+
+    def test_committed_candidate_inspects_hidden_files_without_changing_index_flags(self) -> None:
+        for flag in ("--assume-unchanged", "--skip-worktree"):
+            with self.subTest(flag=flag), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                self.make_repository(root)
+                git(root, "update-index", flag, "tracked.txt")
+                index = root / ".git/index"
+                before = index.read_bytes()
+                require_committed_candidate(root)
+                self.assertEqual(before, index.read_bytes())
+                (root / "tracked.txt").write_text("two\n", encoding="utf-8")
+                with self.assertRaisesRegex(ProcessError, "committed candidate changes"):
+                    require_committed_candidate(root)
+                self.assertEqual(before, index.read_bytes())
+
+    def test_committed_candidate_does_not_follow_a_transient_head(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.make_repository(root)
+            original = resolve_commit(root, "HEAD")
+            (root / "tracked.txt").write_text("two\n", encoding="utf-8")
+            git(root, "add", "tracked.txt")
+            git(root, "commit", "-qm", "fix: alternate content")
+            transient = resolve_commit(root, "HEAD")
+            git(root, "reset", "--mixed", original)
+            before = repository_snapshot(root)
+            inspect = repository._git
+
+            def change_head(path: Path, arguments: list[str], **options) -> bytes:
+                if "read-tree" in arguments:
+                    git(root, "update-ref", "HEAD", transient)
+                try:
+                    return inspect(path, arguments, **options)
+                finally:
+                    if "status" in arguments:
+                        git(root, "update-ref", "HEAD", original)
+
+            try:
+                with patch("engineering_process.repository._git", side_effect=change_head):
+                    with self.assertRaisesRegex(ProcessError, "committed candidate changes"):
+                        require_committed_candidate(root)
+            finally:
+                git(root, "update-ref", "HEAD", original)
+            self.assertTrue(same_checkpoint(before, repository_snapshot(root)))
+
+    def test_committed_candidate_preserves_sparse_omissions_but_inspects_present_files(self) -> None:
+        for mode in ("--no-sparse-index", "--sparse-index"):
+            with self.subTest(mode=mode), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                self.make_repository(root)
+                for relative in ("selected/kept.txt", "omitted/absent.txt"):
+                    path = root / relative
+                    path.parent.mkdir(parents=True)
+                    path.write_text("committed\n", encoding="utf-8")
+                git(root, "add", ".")
+                git(root, "commit", "-qm", "fix: sparse fixture")
+                git(root, "sparse-checkout", "init", "--cone", mode)
+                git(root, "sparse-checkout", "set", "selected")
+                absent = root / "omitted/absent.txt"
+                self.assertFalse(absent.exists())
+                index = root / ".git/index"
+                before = index.read_bytes()
+                require_committed_candidate(root)
+                self.assertEqual(before, index.read_bytes())
+                absent.parent.mkdir(exist_ok=True)
+                absent.write_text("uncommitted\n", encoding="utf-8")
+                with self.assertRaisesRegex(ProcessError, "committed candidate changes"):
+                    require_committed_candidate(root)
+                self.assertEqual(before, index.read_bytes())
+
+    def test_repository_local_temporary_root_does_not_join_the_candidate(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            self.make_repository(root)
+            before = repository_snapshot(root)
+            index = (root / ".git/index").read_bytes()
+            with patch("engineering_process.repository.tempfile.tempdir", str(root)):
+                require_committed_candidate(root)
+            self.assertTrue(same_checkpoint(before, repository_snapshot(root)))
+            self.assertEqual(index, (root / ".git/index").read_bytes())
+            self.assertEqual([], list((root / ".git").glob("process-candidate-*")))
+
+    def test_committed_candidate_supports_linked_worktrees(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory) / "source"
+            root.mkdir()
+            self.make_repository(root)
+            linked = Path(directory) / "linked"
+            git(root, "worktree", "add", "--detach", str(linked), "HEAD")
+            before = repository_snapshot(linked)
+            with patch("engineering_process.repository.tempfile.tempdir", str(linked)):
+                require_committed_candidate(linked)
+            self.assertTrue(same_checkpoint(before, repository_snapshot(linked)))
+            (linked / "tracked.txt").write_text("uncommitted\n", encoding="utf-8")
+            with self.assertRaisesRegex(ProcessError, "committed candidate changes"):
+                require_committed_candidate(linked)
+
+
+if __name__ == "__main__":
+    unittest.main()

engineering_process-2.3.1/RELEASE_NOTES.md

@@ -1,18 +0,0 @@
-# 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.1/tests/test_repository.py

@@ -1,63 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-import subprocess
-import tempfile
-import unittest
-
-from engineering_process.repository import repository_snapshot, resolve_commit, same_checkpoint
-
-
-def git(root: Path, *arguments: str) -> None:
-    subprocess.run(["git", *arguments], cwd=root, check=True, capture_output=True)
-
-
-class RepositorySnapshotTests(unittest.TestCase):
-    def make_repository(self, root: Path) -> None:
-        git(root, "init", "-q")
-        git(root, "config", "user.email", "tests@example.invalid")
-        git(root, "config", "user.name", "Tests")
-        (root / ".gitignore").write_text("/.process/runs/\n/.process/receipts/\n", encoding="utf-8")
-        (root / "tracked.txt").write_text("one\n", encoding="utf-8")
-        git(root, "add", ".")
-        git(root, "commit", "-qm", "initial")
-
-    def test_tracked_and_untracked_content_change_fingerprint(self) -> None:
-        with tempfile.TemporaryDirectory() as directory:
-            root = Path(directory)
-            self.make_repository(root)
-            initial = repository_snapshot(root)
-            (root / "tracked.txt").write_text("two\n", encoding="utf-8")
-            tracked = repository_snapshot(root)
-            self.assertFalse(same_checkpoint(initial, tracked))
-            (root / "new.txt").write_text("new\n", encoding="utf-8")
-            untracked = repository_snapshot(root)
-            self.assertFalse(same_checkpoint(tracked, untracked))
-
-    def test_resolve_commit_accepts_branches_and_peels_annotated_tags(self) -> None:
-        with tempfile.TemporaryDirectory() as directory:
-            root = Path(directory)
-            self.make_repository(root)
-            git(root, "branch", "review-base")
-            git(root, "tag", "-a", "review-tag", "-m", "Review boundary")
-            expected = repository_snapshot(root)["head"]
-            for reference in ("HEAD", "review-base", "review-tag"):
-                with self.subTest(reference=reference):
-                    self.assertEqual(expected, resolve_commit(root, reference))
-
-    def test_lifecycle_state_does_not_invalidate_its_own_checkpoint(self) -> None:
-        with tempfile.TemporaryDirectory() as directory:
-            root = Path(directory)
-            self.make_repository(root)
-            initial = repository_snapshot(root)
-            state = root / ".process" / "runs" / "change" / "run.json"
-            state.parent.mkdir(parents=True)
-            state.write_text("{}\n", encoding="utf-8")
-            receipt = root / ".process" / "receipts" / "change.json"
-            receipt.parent.mkdir(parents=True)
-            receipt.write_text("{}\n", encoding="utf-8")
-            self.assertTrue(same_checkpoint(initial, repository_snapshot(root)))
-
-
-if __name__ == "__main__":
-    unittest.main()