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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: engineering-process
-Version: 2.4.0
+Version: 2.6.0
 Summary: A small agent-neutral engineering lifecycle with managed adoption
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/phuongnse/engineering-process
@@ -86,6 +86,32 @@ but cannot establish native conversation freshness or inspect removed history,
 other clones or other repositories. Keep native creation, non-inherited dispatch
 and effective settings evidence in the existing handoff.
 
+Verification keeps two caller intents explicit. `change verify --profile PROFILE`
+always refreshes the named profile. `change explain` is read-only; it shows the
+accepted required profiles, valid prior evidence, remaining work, inapplicable
+optional profiles, and blocked or unknown decisions. `change verify --remaining`
+executes only remaining work and reuses a complete profile report only when the
+candidate, contract/plan, project policy, process authority, runtime, and bounded
+child environment match. Legacy evidence without that identity reruns. This is
+whole-profile reuse: equal check IDs and ordered side effects are never merged, and
+the lifecycle receipt still records only actual executions.
+
+Reuse is stage-aware rather than a blanket cache: the contract and plan travel by
+digest; valid whole-profile verification can satisfy a continuation request; review
+and finish consume the same reports after rechecking the snapshot; and a new
+implementation cycle invalidates verification. Operation-local calculation reuse is
+allowed only before a mutation/concurrency boundary. Impact feedback and generated
+documents remain derived artifacts and never replace final required profiles or
+independent review.
+
+Consumers that can prove complete changed-path coverage may opt selected required
+profiles into final impact assurance with `impactProfiles.schemaVersion: 2` and
+`finalProfiles`. Each opted profile must declare an explicit global unit whose paths
+include the universal `**` pattern for cross-cutting reach. The lifecycle then
+records the selected units as final
+verification evidence; missing or unresolved coverage blocks rather than silently
+falling back. Existing version 1 policies remain feedback-only.
+
 `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,
@@ -156,6 +182,33 @@ Python 3.11 or newer and Git are required. A consumer owns .process/project.json
             "timeoutSeconds": 600
           }
         ]
+      },
+      "impactProfiles": {
+        "schemaVersion": 1,
+        "profiles": {
+          "development": [
+          {
+            "id": "unit-tests",
+            "run": ["python", "-m", "unittest", "tests.test_orders"],
+            "timeoutSeconds": 600,
+            "paths": ["src/orders/**", "tests/test_orders.py"]
+          },
+          {
+            "id": "cross-cutting",
+            "run": ["python", "-m", "unittest"],
+            "timeoutSeconds": 900,
+            "paths": ["**/process-policy.json"]
+          }
+          ],
+          "review": [
+          {
+            "id": "package",
+            "run": ["python", "-m", "build"],
+            "timeoutSeconds": 600,
+            "paths": ["src/**", "pyproject.toml"]
+          }
+          ]
+        }
       }
     }
 
@@ -502,6 +555,41 @@ Register implementation and run every required profile:
     processctl change verify --change-id change-123 --profile development
     processctl change verify --change-id change-123 --profile review
 
+When continuing an incomplete verification, inspect and execute the necessary set:
+
+    processctl change explain --change-id change-123
+    processctl change verify --change-id change-123 --remaining
+
+The explicit `--profile` form remains a refresh and is never silently converted to
+reuse.
+
+For fast feedback, consumers may declare a versioned `impactProfiles` policy in
+`.process/project.json` and run only units related to the candidate paths:
+
+    processctl change explain --change-id change-123 --impact
+    processctl change verify --change-id change-123 --affected --affected-profile development
+
+Each impact unit owns an exact command and path-pattern coverage. Matching is
+explicit and deterministic; overlapping units all run. A unit with
+`scope: "global"` may subsume narrower units only when its declared paths include
+the universal `**` pattern; a narrower pattern never covers unrelated paths. Every
+changed path must resolve for
+each requested profile. Missing policy, unsupported policy, or an unmapped path is
+`unresolved`/`unavailable`: the process launches nothing and returns the action
+`inspect-diff-and-update-impact-policy`. The agent must inspect the diff and
+dependency reach, update the consumer-owned mapping or obtain an owner decision,
+then repeat the explanation. It must not use a full profile as a fallback.
+
+Affected execution under a version 1 policy is feedback evidence only and never
+advances the lifecycle or satisfies a required profile. A consumer that can prove
+complete coverage may use schema version 2 with `finalProfiles`; `--remaining` then
+records the selected units as `impact-assurance` evidence. Each opted profile needs
+an explicit global unit with the universal `**` pattern for cross-cutting reach, and
+unresolved final coverage
+blocks rather than falling back silently. Explicit `--profile` remains the full
+refresh. Consumers that do not adopt the opt-in retain the existing final boundary;
+the affected command does not guess a policy for them.
+
 Assign an independent reviewer and submit its report:
 
     processctl change review start \
@@ -588,9 +676,11 @@ At any point:
 ## 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.
+the canonical manifest: one record per shipped feature/fix, its source issue, the
+problem and affected paths, the application action, compatibility impact, important
+notes, 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`.

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

@@ -62,6 +62,32 @@ but cannot establish native conversation freshness or inspect removed history,
 other clones or other repositories. Keep native creation, non-inherited dispatch
 and effective settings evidence in the existing handoff.
 
+Verification keeps two caller intents explicit. `change verify --profile PROFILE`
+always refreshes the named profile. `change explain` is read-only; it shows the
+accepted required profiles, valid prior evidence, remaining work, inapplicable
+optional profiles, and blocked or unknown decisions. `change verify --remaining`
+executes only remaining work and reuses a complete profile report only when the
+candidate, contract/plan, project policy, process authority, runtime, and bounded
+child environment match. Legacy evidence without that identity reruns. This is
+whole-profile reuse: equal check IDs and ordered side effects are never merged, and
+the lifecycle receipt still records only actual executions.
+
+Reuse is stage-aware rather than a blanket cache: the contract and plan travel by
+digest; valid whole-profile verification can satisfy a continuation request; review
+and finish consume the same reports after rechecking the snapshot; and a new
+implementation cycle invalidates verification. Operation-local calculation reuse is
+allowed only before a mutation/concurrency boundary. Impact feedback and generated
+documents remain derived artifacts and never replace final required profiles or
+independent review.
+
+Consumers that can prove complete changed-path coverage may opt selected required
+profiles into final impact assurance with `impactProfiles.schemaVersion: 2` and
+`finalProfiles`. Each opted profile must declare an explicit global unit whose paths
+include the universal `**` pattern for cross-cutting reach. The lifecycle then
+records the selected units as final
+verification evidence; missing or unresolved coverage blocks rather than silently
+falling back. Existing version 1 policies remain feedback-only.
+
 `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,
@@ -132,6 +158,33 @@ Python 3.11 or newer and Git are required. A consumer owns .process/project.json
             "timeoutSeconds": 600
           }
         ]
+      },
+      "impactProfiles": {
+        "schemaVersion": 1,
+        "profiles": {
+          "development": [
+          {
+            "id": "unit-tests",
+            "run": ["python", "-m", "unittest", "tests.test_orders"],
+            "timeoutSeconds": 600,
+            "paths": ["src/orders/**", "tests/test_orders.py"]
+          },
+          {
+            "id": "cross-cutting",
+            "run": ["python", "-m", "unittest"],
+            "timeoutSeconds": 900,
+            "paths": ["**/process-policy.json"]
+          }
+          ],
+          "review": [
+          {
+            "id": "package",
+            "run": ["python", "-m", "build"],
+            "timeoutSeconds": 600,
+            "paths": ["src/**", "pyproject.toml"]
+          }
+          ]
+        }
       }
     }
 
@@ -478,6 +531,41 @@ Register implementation and run every required profile:
     processctl change verify --change-id change-123 --profile development
     processctl change verify --change-id change-123 --profile review
 
+When continuing an incomplete verification, inspect and execute the necessary set:
+
+    processctl change explain --change-id change-123
+    processctl change verify --change-id change-123 --remaining
+
+The explicit `--profile` form remains a refresh and is never silently converted to
+reuse.
+
+For fast feedback, consumers may declare a versioned `impactProfiles` policy in
+`.process/project.json` and run only units related to the candidate paths:
+
+    processctl change explain --change-id change-123 --impact
+    processctl change verify --change-id change-123 --affected --affected-profile development
+
+Each impact unit owns an exact command and path-pattern coverage. Matching is
+explicit and deterministic; overlapping units all run. A unit with
+`scope: "global"` may subsume narrower units only when its declared paths include
+the universal `**` pattern; a narrower pattern never covers unrelated paths. Every
+changed path must resolve for
+each requested profile. Missing policy, unsupported policy, or an unmapped path is
+`unresolved`/`unavailable`: the process launches nothing and returns the action
+`inspect-diff-and-update-impact-policy`. The agent must inspect the diff and
+dependency reach, update the consumer-owned mapping or obtain an owner decision,
+then repeat the explanation. It must not use a full profile as a fallback.
+
+Affected execution under a version 1 policy is feedback evidence only and never
+advances the lifecycle or satisfies a required profile. A consumer that can prove
+complete coverage may use schema version 2 with `finalProfiles`; `--remaining` then
+records the selected units as `impact-assurance` evidence. Each opted profile needs
+an explicit global unit with the universal `**` pattern for cross-cutting reach, and
+unresolved final coverage
+blocks rather than falling back silently. Explicit `--profile` remains the full
+refresh. Consumers that do not adopt the opt-in retain the existing final boundary;
+the affected command does not guess a policy for them.
+
 Assign an independent reviewer and submit its report:
 
     processctl change review start \
@@ -564,9 +652,11 @@ At any point:
 ## 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.
+the canonical manifest: one record per shipped feature/fix, its source issue, the
+problem and affected paths, the application action, compatibility impact, important
+notes, 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`.

engineering_process-2.6.0/RELEASE_NOTES.md

@@ -0,0 +1,49 @@
+# Engineering Process v2.6.0
+
+Changes since v2.5.0.
+
+## Features
+
+- **Select and assure verification units from explicit change impact.** ([#205](https://github.com/phuongnse/engineering-process/issues/205))
+  - **Problem:** A consumer could only choose a whole profile or reuse a whole-profile result, so a small change lacked a standard way to run related verification units. When impact was unclear, an automatic full-suite fallback could hide that dependency reach had not been resolved, while explicit coverage could not yet satisfy a final required profile.
+  - **What changed:** Add versioned consumer-owned impactProfiles, deterministic changed-path resolution, change explain --impact, and change verify --affected. Every path must resolve to matching units or the command stops with an explicit re-analysis action; an explicit global pattern is the only broad selection rule. Add a schema-version 2 finalProfiles opt-in so complete explicit coverage can run selected units as final impact-assurance evidence. Policy or candidate changes, missing coverage and unresolved paths fail closed; schema-version 1 policies remain feedback-only.
+  - **Where:** `schemas/project.schema.json`, `schemas/verification-impact-selection.schema.json`, `schemas/verification-selection.schema.json`, `schemas/run.schema.json`, `schemas/receipt.schema.json`, `engineering_process/impact.py`, `engineering_process/repository.py`, `engineering_process/lifecycle.py`, `engineering_process/cli.py`, `engineering_process/project.py`, `process_assets/skills/change-verify/SKILL.md`, `process_assets/skills/change-plan/SKILL.md`, `SELF_HOSTING.md`, `README.md`, `tests/test_contracts.py`, `tests/test_impact.py`, `tests/test_lifecycle.py`, `tests/test_skills.py`
+  - **Apply:** Adopt the package release, add impactProfiles to the consumer project policy, map every changed path to one or more independently executable commands, and run change explain --impact before change verify --affected. Opt selected required profiles into schema version 2 finalProfiles only after reviewing complete path coverage and global cross-cutting units; then run change verify --remaining. Resolve every unresolved path by inspecting the diff/dependency reach and updating the consumer-owned mapping or recording an owner decision.
+  - **Compatibility:** Backward-compatible opt-in. Existing project files, explicit profile verification, whole-profile reuse, required lifecycle profiles, and final review/release evidence remain supported. Consumers without impactProfiles receive a clear unavailable result, and schema-version 1 policies remain feedback-only.
+  - **Notes:** Path patterns are a versioned consumer policy, not a process guess. Overlapping units all run; a global unit may subsume narrower units only when its declared paths include the explicit universal \*\* pattern, while narrower patterns never cover unrelated paths. Affected feedback does not advance the lifecycle or prove final assurance. Final assurance records execution mode and selection identity in the existing lifecycle evidence; it does not create a second lifecycle or infer coverage from filenames, labels, commands, or diagnostics.
+
+## Fixes
+
+- **Render release records as readable Markdown without gratuitous escapes.** ([#171](https://github.com/phuongnse/engineering-process/issues/171))
+  - **Problem:** Generated release notes escaped every punctuation mark and padded ordinary code references, making otherwise complete issue-level records difficult to read.
+  - **What changed:** Escape only Markdown and HTML-sensitive metadata syntax, keep ordinary punctuation readable, and render simple owned references as normal inline code while retaining safe fencing for embedded backticks.
+  - **Where:** `engineering_process/release_notes.py`, `tests/test_release.py`, `release-changes/README.md`, `RELEASING.md`, `ARTIFACT_STANDARDS.md`, `RELEASE_NOTES.md`
+  - **Apply:** Use the normal prepare-release workflow and review the generated RELEASE\_NOTES.md against release.json before publication.
+  - **Compatibility:** No breaking change. Schema-v5 manifests and legacy release-note data remain readable; the selected release-notes@1 structure and published v2.5.0 body are not rewritten.
+  - **Notes:** This correction applies to subsequently generated release bodies. Published release artifacts remain immutable and must be corrected only through the owner's release policy.
+- **Batch reusable verification evidence across lifecycle stages.** ([#198](https://github.com/phuongnse/engineering-process/issues/198))
+  - **Problem:** Continuation verification could make repeated reuse decisions and authority calculations one profile at a time even when several reports already covered the same unchanged candidate.
+  - **What changed:** Batch valid whole-profile reuse decisions into one canonical state write and reuse one process-authority digest across stable evidence comparisons. Preserve the selected runtime path spelling and virtual-environment symlinks across POSIX and Windows while retaining fresh candidate snapshots, runtime identity checks, explicit refresh semantics, and correction-cycle invalidation.
+  - **Where:** `engineering_process/evidence.py`, `engineering_process/lifecycle.py`, `engineering_process/pr_description.py`, `process_assets/skills/change-verify/SKILL.md`, `README.md`, `tests/test_lifecycle.py`, `tests/test_skills.py`
+  - **Apply:** Use change verify --remaining for continuation work. The process reuses only exact valid reports and records reuse without relaunching their child commands.
+  - **Compatibility:** No breaking change. Explicit profile verification remains an unconditional refresh; stale, legacy, or mismatched evidence reruns; final review and finish still require exact-snapshot evidence.
+  - **Notes:** The optimization is operation-scoped and does not add a persistent success cache or reuse evidence across a changed candidate, mutation boundary, or incompatible runtime. Runtime path normalization no longer dereferences the selected executable before constructing the bounded child PATH.
+- **Make the full verification suite deterministic and expose bounded timing diagnostics.** ([#201](https://github.com/phuongnse/engineering-process/issues/201))
+  - **Problem:** The repository-owned full verification suite took about six minutes on Windows and review-context tests incorrectly reported stale evidence when run after the complete suite, while local output did not identify the slowest tests.
+  - **What changed:** Give review-context tests an isolated fixture owner, seed their verified states once per test class, use the same bounded child environment as the verification boundary, and report aggregate, slow-test, fixture-setup, and profile timing without changing profile exit semantics or deleting behavioral coverage. Lifecycle fixtures clone an immutable Git snapshot instead of copying a live .git directory, avoiding races with Git maintenance locks.
+  - **Where:** `tests/test_review_contexts.py`, `tests/test_lifecycle.py`, `verification/run_test_suite.py`
+  - **Apply:** Run the normal development and review profiles; use the bounded suite timing and slow-test summary to diagnose future cost, and do not replace final verification with a focused subset.
+  - **Compatibility:** No breaking change. Existing profile commands, required checks, skip behavior, process/Git/filesystem boundaries, and stored evidence semantics remain supported.
+  - **Notes:** The reviewed change evidence records repeated comparable self-consumer measurements and the bounded improvement method; it does not establish a universal latency target. Shared mutable checkouts and blanket mocks remain out of scope.
+
+## 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.
+
+No breaking changes are included. Read each change's Apply, Compatibility and Notes entry before adopting.
+
+See [versioning and compatibility](https://github.com/phuongnse/engineering-process/blob/v2.6.0/VERSIONING.md) and [adoption guidance](https://github.com/phuongnse/engineering-process/blob/v2.6.0/SELF_HOSTING.md).
+
+[Full change comparison](https://github.com/phuongnse/engineering-process/compare/v2.5.0...v2.6.0)

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

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

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

@@ -38,10 +38,14 @@ from .lifecycle import (
     start_change,
     start_review,
     submit_review,
+    resolve_impact_work,
+    resolve_verification_work,
+    verify_affected,
+    verify_remaining,
     verify_change,
 )
 from .issue import render_issue
-from .project import load_project, readiness_summary
+from .project import impact_profiles, load_project, readiness_summary
 from .production_engineering import (
     validate_plan_assessments,
     validate_review_assessments,
@@ -53,7 +57,13 @@ from .publication_compat import (
     validate_range,
 )
 from .release import validate_release
-from .pr_description import body_issues, render_description, render_renovate_preset, render_template
+from .pr_description import (
+    body_issues,
+    build_pr_description_data,
+    render_description,
+    render_renovate_preset,
+    render_template,
+)
 from .release_notes import render_notes
 from .repository import repository_snapshot, same_checkpoint
 from .skills import validate_skills
@@ -87,9 +97,16 @@ def _result(command: str, status: str = "passed", **details: Any) -> dict[str, A
     return {"command": command, "status": status, **details}
 
 
-def _state_result(command: str, state: dict[str, Any], **details: Any) -> dict[str, Any]:
+def _state_result(
+    command: str,
+    state: dict[str, Any],
+    *,
+    status: str = "passed",
+    **details: Any,
+) -> dict[str, Any]:
     return _result(
         command,
+        status=status,
         changeId=state["changeId"],
         phase=state["phase"],
         cycle=state["cycle"],
@@ -120,6 +137,7 @@ def command_project_validate(args: argparse.Namespace) -> Result:
         "project validate",
         project=project["project"],
         profiles=sorted(project["profiles"]),
+        impactProfiles=sorted(impact_profiles(project)),
         requiredProfiles=project["lifecycle"]["requiredProfiles"],
         readiness=readiness_summary(project),
     ), 0
@@ -311,7 +329,84 @@ def command_change_implement(args: argparse.Namespace) -> Result:
 
 def command_change_verify(args: argparse.Namespace) -> Result:
     process_root = _process_root(args)
+    if getattr(args, "affected", False):
+        selected_profiles = tuple(getattr(args, "affected_profile", []) or []) or None
+        state, selection, executions = verify_affected(
+            args.project_root,
+            process_root,
+            {},
+            args.change_id,
+            profiles=selected_profiles,
+        )
+        execution_status = executions[0]["status"] if executions else None
+        status = (
+            "passed"
+            if selection["status"] == "ready" and execution_status == "passed"
+            else selection["status"]
+            if selection["status"] != "ready"
+            else "failed"
+        )
+        return _state_result(
+            "change verify",
+            state,
+            status=status,
+            selection=selection,
+            execution="affected",
+            evidence="feedback-only; does not satisfy a required full profile",
+            executions=executions,
+        ), (0 if status == "passed" else 1)
+    if getattr(args, "affected_profile", []):
+        raise ProcessError("--affected-profile requires --affected")
     project = load_project(args.project_root, process_root)
+    if args.remaining:
+        state, selection = verify_remaining(
+            args.project_root, process_root, project, args.change_id
+        )
+        executions = []
+        failures = []
+        for profile in selection["executeProfiles"]:
+            report = state["verification"].get(profile)
+            if report is None:
+                failures.append(profile)
+                continue
+            if report["status"] != "passed":
+                failures.append(profile)
+            check_duration = sum(check["durationMs"] for check in report["checks"])
+            executions.append(
+                {
+                    "profile": profile,
+                    "status": report["status"],
+                    "executionMode": report.get("executionMode", "full"),
+                    "launchCount": len(report["checks"]),
+                    "durationMs": report.get("durationMs", check_duration),
+                    "checkDurationMs": check_duration,
+                    "processOverheadMs": max(
+                        0, report.get("durationMs", check_duration) - check_duration
+                    ),
+                }
+            )
+        contract = state.get("contract", {})
+        required_profiles = (
+            contract.get("document", {}).get("requiredProfiles", [])
+            if isinstance(contract, dict)
+            else []
+        )
+        verification = state.get("verification", {})
+        required_profiles_passed = bool(required_profiles) and all(
+            isinstance(verification.get(profile), dict)
+            and verification[profile].get("status") == "passed"
+            for profile in required_profiles
+        )
+        complete = state["phase"] == "verified" and required_profiles_passed
+        return _state_result(
+            "change verify",
+            state,
+            status="passed" if complete and not failures else "failed",
+            selection=selection,
+            execution="remaining",
+            executions=executions,
+            failures=failures,
+        ), (0 if complete and not failures else 1)
     state, report = verify_change(
         args.project_root, process_root, project, args.change_id, args.profile
     )
@@ -321,6 +416,27 @@ def command_change_verify(args: argparse.Namespace) -> Result:
     ), code
 
 
+def command_change_explain(args: argparse.Namespace) -> Result:
+    process_root = _process_root(args)
+    if getattr(args, "impact", False):
+        profiles = (args.profile,) if args.profile else None
+        selection = resolve_impact_work(
+            args.project_root,
+            process_root,
+            {},
+            args.change_id,
+            profiles=profiles,
+        )
+        return _result("change explain", selection=selection), 0
+    if getattr(args, "profile", None):
+        raise ProcessError("--profile for change explain requires --impact")
+    project = load_project(args.project_root, process_root)
+    selection = resolve_verification_work(
+        args.project_root, process_root, project, args.change_id
+    )
+    return _result("change explain", selection=selection), 0
+
+
 def command_change_review_start(args: argparse.Namespace) -> Result:
     process_root = _process_root(args)
     state = start_review(
@@ -434,13 +550,37 @@ def command_artifact(args: argparse.Namespace) -> Result:
                 f"{standard.document['adapter']} state must be "
                 + " or ".join(sorted(allowed_states))
             )
-        data = load_and_validate(args.data_file, standard.document["adapter"] + "-data", schema_root=schemas_root(process_root)) if args.data_file is not None else None
+        if getattr(args, "change_id", None) is not None and standard.document["adapter"] == "pr-description":
+            overrides = (
+                load_and_validate(
+                    args.data_file,
+                    "pr-description-data",
+                    schema_root=schemas_root(process_root),
+                )
+                if args.data_file is not None
+                else None
+            )
+            data = build_pr_description_data(
+                args.project_root,
+                process_root,
+                args.change_id,
+                overrides=overrides,
+                standard=standard,
+            )
+        elif args.data_file is not None:
+            data = load_and_validate(
+                args.data_file,
+                standard.document["adapter"] + "-data",
+                schema_root=schemas_root(process_root),
+            )
+        else:
+            data = None
         if data is not None:
             renderer = {"pr-description": render_description, "release-notes": render_notes, "automation-name": render_name, "issue": render_issue}[standard.document["adapter"]]
             payload = renderer(standard, data, state=state, process_root=process_root).encode("utf-8")
             details["dataDigest"] = digest_json(data)
         elif operation == "render" or standard.document["adapter"] != "pr-description":
-            raise ProcessError("this artifact operation requires --data-file")
+            raise ProcessError("this artifact operation requires --data-file or --change-id")
         if operation == "validate":
             actual = read_document(args.body_file)
             if data is None:
@@ -460,6 +600,38 @@ def command_artifact(args: argparse.Namespace) -> Result:
     return _result(f"artifact {operation}", status, **details, issues=issues), (1 if issues else 0)
 
 
+def command_artifact_prepare_pr_data(args: argparse.Namespace) -> Result:
+    process_root = _process_root(args)
+    standard = resolve_standard(args.project_root, process_root, "pull-request")
+    overrides = (
+        load_and_validate(
+            args.data_file,
+            "pr-description-data",
+            schema_root=schemas_root(process_root),
+        )
+        if args.data_file is not None
+        else None
+    )
+    data = build_pr_description_data(
+        args.project_root,
+        process_root,
+        args.change_id,
+        overrides=overrides,
+        standard=standard,
+    )
+    payload = formatted_json_bytes(data)
+    details: dict[str, Any] = {
+        "changeId": args.change_id,
+        "dataDigest": digest_json(data),
+    }
+    if args.output is not None:
+        args.output.write_bytes(payload)
+        details["output"] = str(args.output)
+    else:
+        details["data"] = data
+    return _result("artifact prepare-pr-data", "passed", **details), 0
+
+
 def _add_common(parser: argparse.ArgumentParser, *, project: bool = True) -> None:
     if project:
         parser.add_argument("--project-root", type=_root, default=Path.cwd())
@@ -536,7 +708,21 @@ def build_parser() -> argparse.ArgumentParser:
     change_implement.add_argument("--change-id", required=True)
     change_verify = _leaf(change_commands, "verify", command_change_verify)
     change_verify.add_argument("--change-id", required=True)
-    change_verify.add_argument("--profile", required=True)
+    verify_scope = change_verify.add_mutually_exclusive_group(required=True)
+    verify_scope.add_argument("--profile")
+    verify_scope.add_argument("--remaining", action="store_true")
+    verify_scope.add_argument("--affected", action="store_true")
+    change_verify.add_argument(
+        "--affected-profile",
+        action="append",
+        default=[],
+        help="limit --affected to one or more accepted profiles",
+    )
+
+    change_explain = _leaf(change_commands, "explain", command_change_explain)
+    change_explain.add_argument("--change-id", required=True)
+    change_explain.add_argument("--impact", action="store_true")
+    change_explain.add_argument("--profile")
 
     review = change_commands.add_parser("review")
     review_commands = review.add_subparsers(dest="review_command", required=True)
@@ -564,12 +750,17 @@ def build_parser() -> argparse.ArgumentParser:
 
     artifact = commands.add_parser("artifact", help="Generate and verify consumer-selected artifact standards")
     artifact_commands = artifact.add_subparsers(dest="artifact_command", required=True)
+    prepare_pr_data = _leaf(artifact_commands, "prepare-pr-data", command_artifact_prepare_pr_data)
+    prepare_pr_data.add_argument("--change-id", required=True)
+    prepare_pr_data.add_argument("--data-file", type=Path)
+    prepare_pr_data.add_argument("--output", type=Path)
     for name in ("show", "template", "renovate-preset", "render", "validate"):
         leaf = _leaf(artifact_commands, name, command_artifact)
         leaf.add_argument("--artifact", required=True)
         if name in {"render", "validate"}:
             leaf.add_argument("--state", choices=("draft", "ready", "open", "closed"))
-            leaf.add_argument("--data-file", type=Path, required=name == "render")
+            leaf.add_argument("--change-id")
+            leaf.add_argument("--data-file", type=Path, required=False)
         if name == "validate":
             leaf.add_argument("--body-file", type=Path, required=True)
         else: