engineering-process 2.0.2__tar.gz → 2.1.0__tar.gz

{engineering_process-2.0.2 → engineering_process-2.1.0}/MANIFEST.in

@@ -1,4 +1,5 @@
 include process-graph.json
+include RELEASE_NOTES.md
 recursive-include process_assets/skills SKILL.md *.json
 recursive-include schemas *.json
 recursive-include templates *.md *.py *.json

{engineering_process-2.0.2/engineering_process.egg-info → engineering_process-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 2.0.2
+Version: 2.1.0
 Summary: A small agent-neutral engineering lifecycle with managed adoption
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process
@@ -69,6 +69,14 @@ may have implemented the current cycle. 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
+own report. The runner's existing task/session interaction and returned result make
+that work inspectable. Sharing a model, provider, or account is allowed; this is a
+workflow for independent judgment, not authenticated identity or merge enforcement.
+See [change-review](process_assets/skills/change-review/SKILL.md) for the handoff.
+
 Runtime architecture is enforced by semantic fitness functions, not module or source-
 line quotas. Every module has an explicit dependency layer, imports point toward lower
 layers, the internal graph remains acyclic, and lifecycle.py alone owns state
@@ -174,6 +182,25 @@ runtime/license delivery, Linux advisory resolution, real-host workspace securit
 updater, incident recovery, and independent security review remain planned.
 Consumers without readiness remain compatible during that evidence-backed rollout.
 
+### Design quality
+
+Changes that materially alter logic, state, or collaboration boundaries carry
+consumer design standards in their existing acceptance criteria. The shared
+[design quality guidance](process_assets/skills/production-engineering/SKILL.md#design-quality)
+requires understandable responsibilities, data and state, ownership, and contracts.
+Agents actively introduce or refine cohesive abstractions when current requirements
+justify them, weighing comprehension and change locality against indirection.
+Consumer architecture and language choices remain authoritative.
+
+Start defines scoped design outcomes; the plan explains material choices in its
+existing approach and work items; implementation revisits the affected flow before
+verification. Independent review traces behavior and a concrete maintenance scenario
+against the actual code. Demonstrated violations of accepted criteria can block
+completion despite passing tests. Routine edits stay proportional, and a clear
+direct implementation remains valid. The existing lifecycle enforces criterion-bound
+findings and evidence freshness; contextual design quality remains the reviewer's
+judgment, without another gate, artifact, or canonical invariant.
+
 ### Production engineering invariants
 
 Every new plan and independent review applies one small, versioned invariant floor:
@@ -440,6 +467,19 @@ approved can finish only while the repository still matches the reviewed snapsho
       --actor coordinator \
       --context finish-123
 
+New runs preserve the accepted `comparisonBase` ref and contract digest, and record
+its resolved commit separately as `comparisonBaseCommit`. Start rejects missing or
+non-commit refs before writing the run. Lifecycle output supplies the recorded commit
+for review even after commits or branch movement. Older runs without this field stay
+readable; their original review boundary must be established from available history,
+not retrospectively claimed as pinned. If that boundary cannot be established, use
+an owner-selected replacement contract.
+
+Correction reports must retain every previously open blocker until its unchanged
+identity receives an explicit `resolved` disposition. Omitting it or changing it to
+`accepted-risk` or `tracked-follow-up` cannot retire the blocker. This applies to all
+supported review schemas; ordinary legacy non-blocking observations remain readable.
+
 ### Public pull-request evidence
 
 The managed pull-request template keeps public assurance separate from local
@@ -465,12 +505,26 @@ and authors plus independent review keep it out of free-form values. The validat
 a positive grammar for public fields; it deliberately does not guess identities from
 an open-ended vocabulary of names or labels.
 
+This producer's local `review` profile runs `verification/verify_publication.py`
+against the actual Git branch. `main` is the consumer's integration branch, not a
+proposal; detached local checkouts require explicit PR context instead of a guessed
+branch name. In CI, the `Adopted public process` job supplies actual PR metadata and
+the base/head commit range to the installed publication adapters. Metadata edits and
+draft-state changes rerun CI. Maintainers must keep this existing job in `main`'s
+required status checks alongside the other required checks. These publication choices
+belong to this consumer; the shared lifecycle does not impose a naming policy.
+
 At any point:
 
     processctl change status --change-id change-123 --json
 
 ## Release to consumer PR
 
+Each release includes [reviewed release contents](RELEASE_NOTES.md) generated from
+the canonical manifest: shipped features/fixes, their source issues or changes, and
+upgrade guidance. The release PR reviews this file; the GitHub Release publishes the
+same contents. See [the release procedure](RELEASING.md) for authoring and checks.
+
 This producer's release identity inputs and text assets declared by
 `tool.setuptools.data-files` use UTF-8 without BOM and LF, matching `.gitattributes`.
 Writers select that representation explicitly; JSON writers use

{engineering_process-2.0.2 → engineering_process-2.1.0}/README.md

@@ -45,6 +45,14 @@ may have implemented the current cycle. 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
+own report. The runner's existing task/session interaction and returned result make
+that work inspectable. Sharing a model, provider, or account is allowed; this is a
+workflow for independent judgment, not authenticated identity or merge enforcement.
+See [change-review](process_assets/skills/change-review/SKILL.md) for the handoff.
+
 Runtime architecture is enforced by semantic fitness functions, not module or source-
 line quotas. Every module has an explicit dependency layer, imports point toward lower
 layers, the internal graph remains acyclic, and lifecycle.py alone owns state
@@ -150,6 +158,25 @@ runtime/license delivery, Linux advisory resolution, real-host workspace securit
 updater, incident recovery, and independent security review remain planned.
 Consumers without readiness remain compatible during that evidence-backed rollout.
 
+### Design quality
+
+Changes that materially alter logic, state, or collaboration boundaries carry
+consumer design standards in their existing acceptance criteria. The shared
+[design quality guidance](process_assets/skills/production-engineering/SKILL.md#design-quality)
+requires understandable responsibilities, data and state, ownership, and contracts.
+Agents actively introduce or refine cohesive abstractions when current requirements
+justify them, weighing comprehension and change locality against indirection.
+Consumer architecture and language choices remain authoritative.
+
+Start defines scoped design outcomes; the plan explains material choices in its
+existing approach and work items; implementation revisits the affected flow before
+verification. Independent review traces behavior and a concrete maintenance scenario
+against the actual code. Demonstrated violations of accepted criteria can block
+completion despite passing tests. Routine edits stay proportional, and a clear
+direct implementation remains valid. The existing lifecycle enforces criterion-bound
+findings and evidence freshness; contextual design quality remains the reviewer's
+judgment, without another gate, artifact, or canonical invariant.
+
 ### Production engineering invariants
 
 Every new plan and independent review applies one small, versioned invariant floor:
@@ -416,6 +443,19 @@ approved can finish only while the repository still matches the reviewed snapsho
       --actor coordinator \
       --context finish-123
 
+New runs preserve the accepted `comparisonBase` ref and contract digest, and record
+its resolved commit separately as `comparisonBaseCommit`. Start rejects missing or
+non-commit refs before writing the run. Lifecycle output supplies the recorded commit
+for review even after commits or branch movement. Older runs without this field stay
+readable; their original review boundary must be established from available history,
+not retrospectively claimed as pinned. If that boundary cannot be established, use
+an owner-selected replacement contract.
+
+Correction reports must retain every previously open blocker until its unchanged
+identity receives an explicit `resolved` disposition. Omitting it or changing it to
+`accepted-risk` or `tracked-follow-up` cannot retire the blocker. This applies to all
+supported review schemas; ordinary legacy non-blocking observations remain readable.
+
 ### Public pull-request evidence
 
 The managed pull-request template keeps public assurance separate from local
@@ -441,12 +481,26 @@ and authors plus independent review keep it out of free-form values. The validat
 a positive grammar for public fields; it deliberately does not guess identities from
 an open-ended vocabulary of names or labels.
 
+This producer's local `review` profile runs `verification/verify_publication.py`
+against the actual Git branch. `main` is the consumer's integration branch, not a
+proposal; detached local checkouts require explicit PR context instead of a guessed
+branch name. In CI, the `Adopted public process` job supplies actual PR metadata and
+the base/head commit range to the installed publication adapters. Metadata edits and
+draft-state changes rerun CI. Maintainers must keep this existing job in `main`'s
+required status checks alongside the other required checks. These publication choices
+belong to this consumer; the shared lifecycle does not impose a naming policy.
+
 At any point:
 
     processctl change status --change-id change-123 --json
 
 ## Release to consumer PR
 
+Each release includes [reviewed release contents](RELEASE_NOTES.md) generated from
+the canonical manifest: shipped features/fixes, their source issues or changes, and
+upgrade guidance. The release PR reviews this file; the GitHub Release publishes the
+same contents. See [the release procedure](RELEASING.md) for authoring and checks.
+
 This producer's release identity inputs and text assets declared by
 `tool.setuptools.data-files` use UTF-8 without BOM and LF, matching `.gitattributes`.
 Writers select that representation explicitly; JSON writers use

engineering_process-2.1.0/RELEASE_NOTES.md

@@ -0,0 +1,23 @@
+# Engineering Process v2.1.0
+
+Changes since v2.0.2.
+
+## Features
+
+- Pin comparison refs in new lifecycle runs\, require explicit blocker closure\, and wire the producer\'s actual publication metadata into required verification while retaining older run readers\. ([#169](https://github.com/phuongnse/engineering-process/issues/169))
+
+## Fixes
+
+- Carry consumer design quality through accepted criteria\, planning\, implementation\, and independent review\, with proactive cohesive abstractions and evidence\-based maintenance judgment\. ([#119](https://github.com/phuongnse/engineering-process/issues/119))
+- Clarify real independent reviewer dispatch\, neutral context and reviewer\-owned report handoff using the existing runner\. ([#166](https://github.com/phuongnse/engineering-process/issues/166))
+- Publish reviewed release contents with grouped changes\, source issues and upgrade guidance generated from the canonical release manifest\. ([#171](https://github.com/phuongnse/engineering-process/issues/171))
+
+## 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.1.0/VERSIONING.md) and [adoption guidance](https://github.com/phuongnse/engineering-process/blob/v2.1.0/SELF_HOSTING.md).
+
+[Full change comparison](https://github.com/phuongnse/engineering-process/compare/v2.0.2...v2.1.0)

{engineering_process-2.0.2 → engineering_process-2.1.0}/engineering_process/__init__.py

@@ -1,3 +1,3 @@
 """Agent-neutral engineering process."""
 
-VERSION = "2.0.2"
+VERSION = "2.1.0"

{engineering_process-2.0.2 → engineering_process-2.1.0}/engineering_process/cli.py

@@ -85,6 +85,7 @@ def _state_result(command: str, state: dict[str, Any], **details: Any) -> dict[s
         changeId=state["changeId"],
         phase=state["phase"],
         cycle=state["cycle"],
+        **({"comparisonBaseCommit": state["comparisonBaseCommit"]} if "comparisonBaseCommit" in state else {}),
         **details,
     )
 

{engineering_process-2.0.2 → engineering_process-2.1.0}/engineering_process/lifecycle.py

@@ -33,7 +33,7 @@ from .production_engineering import (
     validate_plan_assessments,
     validate_review_assessments,
 )
-from .repository import repository_snapshot, same_checkpoint
+from .repository import repository_snapshot, resolve_commit, same_checkpoint
 
 
 NEXT_COMMAND = {
@@ -182,12 +182,14 @@ def start_change(
         raise ProcessError("change affectedProjects must include the current project")
 
     actor = _actor(actor_id, context_id, kind)
+    comparison_base = resolve_commit(project_root, contract["comparisonBase"])
     state: dict[str, Any] = {
         "schemaVersion": 1,
         "changeId": change_id,
         "phase": "specified",
         "cycle": 0,
         "contract": {"digest": digest_json(contract), "document": contract},
+        "comparisonBaseCommit": comparison_base,
         "plan": None,
         "implementations": [],
         "currentImplementation": None,
@@ -481,6 +483,19 @@ def submit_review(
             ):
                 raise ProcessError("critical-late blockers must be P0 or P1")
 
+    current_findings = {finding["id"]: finding for finding in review["findings"]}
+    for finding_id, prior in prior_findings.items():
+        if prior["severity"] != "blocking":
+            continue
+        current_finding = current_findings.get(finding_id)
+        if current_finding is None:
+            raise ProcessError(f"prior blocking finding must not be omitted: {finding_id}")
+        if (
+            current_finding["severity"] != "blocking"
+            and current_finding.get("disposition", {}).get("status") != "resolved"
+        ):
+            raise ProcessError(f"prior blocking finding must remain blocking or be resolved: {finding_id}")
+
     state["review"] = {"digest": digest_json(review), "document": review}
     state["reviewHistory"].append(
         {

{engineering_process-2.0.2 → engineering_process-2.1.0}/engineering_process/repository.py

@@ -50,6 +50,12 @@ def _head(root: Path) -> str | None:
     return decoded
 
 
+def resolve_commit(root: Path, reference: str) -> str:
+    return _git(
+        root, ["rev-parse", "--verify", "--end-of-options", f"{reference}^{{commit}}"]
+    ).decode("ascii").strip()
+
+
 def repository_snapshot(root: Path) -> dict[str, Any]:
     root = root.resolve()
     if not (root / ".git").exists():

{engineering_process-2.0.2 → engineering_process-2.1.0/engineering_process.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 2.0.2
+Version: 2.1.0
 Summary: A small agent-neutral engineering lifecycle with managed adoption
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process
@@ -69,6 +69,14 @@ may have implemented the current cycle. 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
+own report. The runner's existing task/session interaction and returned result make
+that work inspectable. Sharing a model, provider, or account is allowed; this is a
+workflow for independent judgment, not authenticated identity or merge enforcement.
+See [change-review](process_assets/skills/change-review/SKILL.md) for the handoff.
+
 Runtime architecture is enforced by semantic fitness functions, not module or source-
 line quotas. Every module has an explicit dependency layer, imports point toward lower
 layers, the internal graph remains acyclic, and lifecycle.py alone owns state
@@ -174,6 +182,25 @@ runtime/license delivery, Linux advisory resolution, real-host workspace securit
 updater, incident recovery, and independent security review remain planned.
 Consumers without readiness remain compatible during that evidence-backed rollout.
 
+### Design quality
+
+Changes that materially alter logic, state, or collaboration boundaries carry
+consumer design standards in their existing acceptance criteria. The shared
+[design quality guidance](process_assets/skills/production-engineering/SKILL.md#design-quality)
+requires understandable responsibilities, data and state, ownership, and contracts.
+Agents actively introduce or refine cohesive abstractions when current requirements
+justify them, weighing comprehension and change locality against indirection.
+Consumer architecture and language choices remain authoritative.
+
+Start defines scoped design outcomes; the plan explains material choices in its
+existing approach and work items; implementation revisits the affected flow before
+verification. Independent review traces behavior and a concrete maintenance scenario
+against the actual code. Demonstrated violations of accepted criteria can block
+completion despite passing tests. Routine edits stay proportional, and a clear
+direct implementation remains valid. The existing lifecycle enforces criterion-bound
+findings and evidence freshness; contextual design quality remains the reviewer's
+judgment, without another gate, artifact, or canonical invariant.
+
 ### Production engineering invariants
 
 Every new plan and independent review applies one small, versioned invariant floor:
@@ -440,6 +467,19 @@ approved can finish only while the repository still matches the reviewed snapsho
       --actor coordinator \
       --context finish-123
 
+New runs preserve the accepted `comparisonBase` ref and contract digest, and record
+its resolved commit separately as `comparisonBaseCommit`. Start rejects missing or
+non-commit refs before writing the run. Lifecycle output supplies the recorded commit
+for review even after commits or branch movement. Older runs without this field stay
+readable; their original review boundary must be established from available history,
+not retrospectively claimed as pinned. If that boundary cannot be established, use
+an owner-selected replacement contract.
+
+Correction reports must retain every previously open blocker until its unchanged
+identity receives an explicit `resolved` disposition. Omitting it or changing it to
+`accepted-risk` or `tracked-follow-up` cannot retire the blocker. This applies to all
+supported review schemas; ordinary legacy non-blocking observations remain readable.
+
 ### Public pull-request evidence
 
 The managed pull-request template keeps public assurance separate from local
@@ -465,12 +505,26 @@ and authors plus independent review keep it out of free-form values. The validat
 a positive grammar for public fields; it deliberately does not guess identities from
 an open-ended vocabulary of names or labels.
 
+This producer's local `review` profile runs `verification/verify_publication.py`
+against the actual Git branch. `main` is the consumer's integration branch, not a
+proposal; detached local checkouts require explicit PR context instead of a guessed
+branch name. In CI, the `Adopted public process` job supplies actual PR metadata and
+the base/head commit range to the installed publication adapters. Metadata edits and
+draft-state changes rerun CI. Maintainers must keep this existing job in `main`'s
+required status checks alongside the other required checks. These publication choices
+belong to this consumer; the shared lifecycle does not impose a naming policy.
+
 At any point:
 
     processctl change status --change-id change-123 --json
 
 ## Release to consumer PR
 
+Each release includes [reviewed release contents](RELEASE_NOTES.md) generated from
+the canonical manifest: shipped features/fixes, their source issues or changes, and
+upgrade guidance. The release PR reviews this file; the GitHub Release publishes the
+same contents. See [the release procedure](RELEASING.md) for authoring and checks.
+
 This producer's release identity inputs and text assets declared by
 `tool.setuptools.data-files` use UTF-8 without BOM and LF, matching `.gitattributes`.
 Writers select that representation explicitly; JSON writers use

{engineering_process-2.0.2 → engineering_process-2.1.0}/engineering_process.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE
 MANIFEST.in
 README.md
+RELEASE_NOTES.md
 process-graph.json
 pyproject.toml
 engineering_process/__init__.py
@@ -68,6 +69,7 @@ tests/test_distribution.py
 tests/test_lifecycle.py
 tests/test_production_engineering.py
 tests/test_publication_compat.py
+tests/test_publication_workflow.py
 tests/test_pypi_cache_horizon.py
 tests/test_release.py
 tests/test_repository.py

{engineering_process-2.0.2 → engineering_process-2.1.0}/process_assets/skills/change-complete/SKILL.md

@@ -7,7 +7,11 @@ description: Complete an approved change when routed by deliver-change, only whi
 
 Confirm the lifecycle is approved, every required profile passed, every blocking
 finding is closed, every non-blocking finding has its required disposition, and the
-repository still matches the reviewed snapshot. Then run:
+repository still matches the reviewed snapshot.
+Every previously open blocker must have remained visible until the reviewer recorded
+its explicit resolution; an omitted finding is not a closed finding.
+
+Run:
 
     processctl change finish --change-id ID --actor ACTOR --context CONTEXT
 
@@ -16,6 +20,12 @@ marks the run completed.
 Completion does not itself grant merge, deployment, or release authority; those
 remain project-owned operations. Never report completion from prose alone.
 
+When the accepted work includes a release, make its contents reviewable: what ships,
+user impact, source issues or changes, and required upgrade/compatibility actions.
+Use the consumer's reviewed release records as the authority. The consumer owns
+format, tooling and publication decisions; a list of internal execution events or
+version-bump PR titles does not explain shipped behavior.
+
 Use a normal trailing `Refs ISSUE.` line for producer and intermediate pull requests.
 Only a contract-identified final consumer adoption that has verified the released
 behavior may use `Closes ISSUE, closes ISSUE.` after the completed public checklist.

{engineering_process-2.0.2 → engineering_process-2.1.0}/process_assets/skills/change-implement/SKILL.md

@@ -21,6 +21,13 @@ items produce the planned objective evidence. If implementation proves an
 applicability decision wrong, preserve the accepted contract and implement the
 required structure; the independent review records the corrected semantic result.
 
+Complete the accepted design work before final verification. Re-read the affected
+end-to-end flow and its callers using **production-engineering** design guidance;
+refactor within scope when the implemented structure obscures responsibility,
+weakens contracts, or adds unnecessary coupling or indirection. Preserve behavior
+and protective checks during refactoring. Working code and passing tests do not
+replace meeting accepted design criteria.
+
 Do not weaken an affected enforced readiness capability or silently change its pack,
 version, profile mapping, state, or gap. A planned-to-enforced transition must be an
 explicit implementation diff backed by the planned checks. Never auto-promote a

{engineering_process-2.0.2 → engineering_process-2.1.0}/process_assets/skills/change-plan/SKILL.md

@@ -10,6 +10,14 @@ approach, bounded work items with owned paths, and concrete risks with mitigatio
 The plan must bind the exact contract digest and must not add behavior that the
 contract did not accept.
 
+Use the existing `approach` to explain material design decisions against the accepted
+criteria and inspected consumer code: responsibility and state ownership,
+collaboration contracts, reusable structures, and actual sources of variation.
+Explain how the chosen structure helps trace the behavior and contains a concrete
+maintenance change, accounting for indirection and coupling. Bind needed design work
+to existing work-item outcomes. Keep reasoning proportional; retaining a clear
+existing structure is a valid choice.
+
 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.0.2 → engineering_process-2.1.0}/process_assets/skills/change-review/SKILL.md

@@ -6,7 +6,29 @@ description: Review the exact verified snapshot from an independent actor and co
 # Review a change
 
 The reviewer must not share either actor identity or execution context with an
-implementer in the current cycle. Read `processctl change status --change-id ID`.
+implementer in the current cycle. An implementer must hand off this phase to an
+actual reviewer, not perform it under another identity.
+
+For a new agent review, spawn a fresh agent/session without the implementation
+conversation. Supply the accepted contract and plan, recorded `comparisonBaseCommit`, candidate
+path/checkpoint, and verification evidence. Request an independent assessment of
+the complete diff and relevant code/tests without suggesting a verdict. The same
+model, provider, or account may be used. If the environment cannot run or reach an
+independent reviewer, leave the change awaiting review and report that missing
+handoff.
+
+Use `comparisonBaseCommit` from lifecycle output or the run state; never re-resolve
+the original moving ref after implementation. Older runs may lack this field. Keep
+their accepted comparison boundary explicit and establish the complete diff from
+available history; if it cannot be established, request an owner-selected replacement
+contract rather than claiming the base was pinned at start.
+
+Use the runner's returned reviewer handle to continue the real reviewer. Record its
+actor/context in the existing assignment and retain the native task/session
+interaction and returned result for inspection. Distinct identity strings alone do
+not demonstrate that a review ran.
+
+Read `processctl change status --change-id ID`.
 When the phase is `verified`, start the assignment:
 
     processctl change review start --change-id ID --actor REVIEWER --context REVIEW_CONTEXT
@@ -28,6 +50,22 @@ the contract are proposals, not blocking findings. approved may contain non-bloc
 observations but no blocking finding; changes-requested requires at least one blocking
 finding.
 
+Carry every previously open blocking finding into the next report with its identity
+unchanged. It must remain blocking or have a `resolved` disposition with the reason
+the reviewed snapshot closes it. Omission, `accepted-risk`, and `tracked-follow-up`
+cannot retire a blocker. This also applies to older report versions; their ordinary
+non-blocking observations keep the existing compatibility rules.
+
+Assess accepted design criteria separately from passing checks. Use
+**production-engineering** design guidance to trace a significant behavior and a
+concrete maintenance scenario grounded in current requirements through the affected
+code, callers, and dependencies. Evaluate both the effort to understand the flow and
+the reach of a change. A design finding must identify the violated criterion, source
+location, and concrete correctness, comprehension, or maintenance consequence.
+Apply the existing blocking rules to demonstrated violations even when tests pass;
+preference for a pattern, shorter code, or a different valid structure is insufficient.
+Do not retrofit new design criteria into the frozen contract.
+
 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
@@ -60,7 +98,10 @@ For a planned-to-enforced transition, require the explicit readiness diff and cu
 consumer-owned evidence; reject promotion by prose, stale evidence, or renamed gap.
 Do not block the change merely because unrelated planned capabilities still exist.
 
-Validate and submit the report:
+The reviewer authors the verdict, findings, and assessments, then validates and
+submits its report. If only the coordinator can submit, it transports the reviewer's
+returned report unchanged. Report errors go back to the assigned reviewer for
+correction; the coordinator must not fill in or rewrite the review content.
 
     processctl contract validate --kind review REPORT_PATH
     processctl change review submit --change-id ID --review REPORT_PATH

{engineering_process-2.0.2 → engineering_process-2.1.0}/process_assets/skills/change-start/SKILL.md

@@ -10,6 +10,17 @@ 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.
 
+Choose the consumer's comparison ref deliberately. Start resolves it once to an
+existing commit and returns `comparisonBaseCommit`; use that recorded commit for
+later diff/review work. The accepted contract and its digest retain the original ref.
+
+When the accepted change adds or materially changes logic, state, or collaboration
+boundaries, read the design quality guidance in **production-engineering**. Express
+applicable consumer design standards as observable outcomes in the existing
+acceptance criteria: identify the responsibility or contract that must be clear and
+the supported behavior it must make understandable. Keep those outcomes within the
+accepted behavior and affected code; routine edits need no separate design exercise.
+
 Read the readiness result from `processctl project validate --json`. Use the accepted
 request, consumer rules, and inspected behavior to identify only capabilities this
 change affects or explicitly advances. State that relationship in the summary and

{engineering_process-2.0.2 → engineering_process-2.1.0}/process_assets/skills/deliver-change/SKILL.md

@@ -18,9 +18,10 @@ change status when a change already exists, then route exactly one current phase
 2. specified: use **change-plan**.
 3. planned or changes-requested: use **change-implement**.
 4. implementing: use **change-verify**.
-5. verified or review-pending: use **change-review**, resuming the existing assignment
-   when review is pending; if the repository changed after evidence was recorded,
-   use **change-implement** to open a new cycle.
+5. verified or review-pending: hand off to an actual independent reviewer through
+   **change-review**, resuming the existing assignment when review is pending; if the
+   repository changed after evidence was recorded, use **change-implement** to open a
+   new cycle.
 6. approved: use **change-complete**; a later repository change also reopens through
    **change-implement**.
 7. blocked: stop. The current contract cannot merge; the owner may narrow or
@@ -30,10 +31,10 @@ When changing this process itself, first use **process-improve** to prove the re
 came from a real consumer incident or need; the change still follows the same six
 phases afterward.
 
-From planning through independent review, use **production-engineering** as the
-shared correctness floor. Its canonical definitions drive the plan and review
-contracts; do not replace their contextual assessment with keyword or naming
-heuristics.
+Use **production-engineering** design guidance when defining acceptance criteria for
+material changes. From planning through independent review, also apply its shared
+correctness floor. Its canonical definitions drive the invariant assessments; do not
+replace contextual judgment with keyword or naming heuristics.
 
 The project's nearest AGENTS.md owns product decisions and .process/project.json owns
 exact argument-array commands. Skills guide the work; only processctl advances

{engineering_process-2.0.2 → engineering_process-2.1.0}/process_assets/skills/production-engineering/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: production-engineering
-description: Apply the small production-engineering invariant floor during planning, implementation, verification, and independent review without replacing semantic judgment with keyword checks.
+description: Apply intentional design guidance and the small production-engineering invariant floor without replacing contextual judgment with keyword checks.
 ---
 
-# Production engineering invariants
+# Production engineering
 
 Assess the [canonical invariant definitions](invariants.json) for every new plan. They
 are a small correctness floor, not a design-pattern catalog and not a claim that one
@@ -13,6 +13,33 @@ Keep the core floor at no more than seven invariants. Adding one requires eviden
 from a real consumer; first prefer clarifying or consolidating an existing invariant.
 This is a design budget, not an assessment or a substitute for evidence.
 
+## Design quality
+
+Use the consumer's architecture, domain model, and accepted design criteria to judge
+the affected code. Responsibilities, valid data and state, ownership of rules and
+side effects, and contracts between collaborators must be understandable from the
+source. A reader should be able to trace a supported behavior and locate its rules
+without reconstructing the implementation conversation.
+
+Actively introduce or refine cohesive abstractions when current requirements expose
+a hidden responsibility, duplicated policy, or coordination and consistency
+obligations leaking into callers. Use consumer-native constructs and reuse sound
+existing boundaries. An abstraction earns its place by clarifying behavior or
+containing a real change, with its indirection and coupling costs accounted for.
+A small caller count does not disqualify an abstraction that clarifies responsibility
+or protects a contract.
+
+Preserve clear direct implementations where further separation adds no present
+benefit. Judge both the effort to follow a behavior and the reach of a change;
+shorter code, more layers, and named patterns do not establish design quality.
+Keep refactoring within the accepted scope and avoid unused flexibility. Record
+material rationale near the owned code when the structure cannot express it.
+
+Assess these outcomes through the existing accepted criteria. They do not add entries
+to the canonical invariant assessments or expand an in-flight contract.
+
+## Invariant assessments
+
 At plan time, assess every invariant as `applicable` or `not-applicable`. Explain the
 decision from the invariant's trigger. Every applicable assessment names the work
 items that will establish its required structure and evidence. `not-applicable` is a

{engineering_process-2.0.2 → engineering_process-2.1.0}/pyproject.toml

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

{engineering_process-2.0.2 → engineering_process-2.1.0}/schemas/run.schema.json

@@ -11,6 +11,7 @@
     "phase": {"enum": ["specified", "planned", "implementing", "verified", "review-pending", "approved", "changes-requested", "completed", "blocked"]},
     "cycle": {"type": "integer", "minimum": 0},
     "contract": {"$ref": "#/$defs/boundDocument"},
+    "comparisonBaseCommit": {"type": "string", "pattern": "^[0-9a-f]{40}(?:[0-9a-f]{24})?$"},
     "plan": {"oneOf": [{"$ref": "#/$defs/boundDocument"}, {"type": "null"}]},
     "implementations": {
       "type": "array",