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

{engineering_process-2.5.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.5.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
@@ -96,6 +96,22 @@ 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,
@@ -166,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"]
+          }
+          ]
+        }
       }
     }
 
@@ -520,6 +563,33 @@ When continuing an incomplete verification, inspect and execute the necessary se
 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 \
@@ -606,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.5.0 → engineering_process-2.6.0}/README.md

@@ -72,6 +72,22 @@ 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,
@@ -142,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"]
+          }
+          ]
+        }
       }
     }
 
@@ -496,6 +539,33 @@ When continuing an incomplete verification, inspect and execute the necessary se
 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 \
@@ -582,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.5.0 → engineering_process-2.6.0}/engineering_process/__init__.py

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

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

@@ -38,12 +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,
@@ -135,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
@@ -326,6 +329,34 @@ 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(
@@ -345,6 +376,7 @@ def command_change_verify(args: argparse.Namespace) -> Result:
                 {
                     "profile": profile,
                     "status": report["status"],
+                    "executionMode": report.get("executionMode", "full"),
                     "launchCount": len(report["checks"]),
                     "durationMs": report.get("durationMs", check_duration),
                     "checkDurationMs": check_duration,
@@ -386,6 +418,18 @@ def command_change_verify(args: argparse.Namespace) -> Result:
 
 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
@@ -667,9 +711,18 @@ def build_parser() -> argparse.ArgumentParser:
     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)

{engineering_process-2.5.0 → engineering_process-2.6.0}/engineering_process/contracts.py

@@ -36,6 +36,7 @@ CONTRACT_KINDS = (
     "renovate-preset",
     "review",
     "run",
+    "verification-impact-selection",
     "verification-selection",
 )
 

{engineering_process-2.5.0 → engineering_process-2.6.0}/engineering_process/evidence.py

@@ -110,6 +110,7 @@ def verification_input_digest(
     profile: str,
     *,
     runtime: dict[str, Any] | None = None,
+    authority_digest: str | None = None,
 ) -> str | None:
     """Bind reusable evidence to every input controlled by this process."""
     runtime = runtime if runtime is not None else execution_identity()
@@ -119,7 +120,11 @@ def verification_input_digest(
     return digest_json({
         "authority": {
             "version": VERSION,
-            "distribution": distribution_digest(process_root),
+            "distribution": (
+                authority_digest
+                if authority_digest is not None
+                else distribution_digest(process_root)
+            ),
         },
         "project": project,
         "contractDigest": state["contract"]["digest"],
@@ -145,6 +150,7 @@ def verification_report_matches_inputs(
     require_input: bool,
     require_explicit_scope: bool = False,
     runtime: dict[str, Any] | None = None,
+    authority_digest: str | None = None,
 ) -> bool:
     """Return whether one report is reusable for the supplied inputs."""
     scope = report.get("scope")
@@ -169,5 +175,6 @@ def verification_report_matches_inputs(
         state,
         profile,
         runtime=runtime,
+        authority_digest=authority_digest,
     )
     return current is not None and recorded == current

engineering_process-2.6.0/engineering_process/impact.py

@@ -0,0 +1,231 @@
+"""Strict, consumer-owned change-impact resolution for fast feedback."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Any, Iterable
+
+from .contracts import ProcessError, digest_json, validate_document
+from .distribution import schemas_root
+from .project import impact_assurance_profiles, impact_profiles
+from .repository import changed_paths
+
+
+def _matches(path: str, patterns: Iterable[str]) -> bool:
+    return any(fnmatchcase(path, pattern) for pattern in patterns)
+
+
+def resolve_impact_selection(
+    project_root: Path,
+    process_root: Path,
+    project: dict[str, Any],
+    state: dict[str, Any],
+    *,
+    profiles: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Resolve every changed path to explicit consumer verification units.
+
+    This function is intentionally fail-closed. It never converts an unknown
+    path into a full profile request.
+    """
+    required = tuple(state["contract"]["document"]["requiredProfiles"])
+    requested = tuple(required if profiles is None else profiles)
+    invalid = sorted(set(requested) - set(required))
+    if invalid:
+        raise ProcessError(
+            "impact selection may request only accepted required profiles: "
+            + ", ".join(invalid)
+        )
+
+    base = state.get("comparisonBaseCommit")
+    if not isinstance(base, str) or not base:
+        raise ProcessError("impact selection requires a pinned comparison base")
+    paths = changed_paths(project_root, base)
+    policy = impact_profiles(project)
+    assurance_profiles = tuple(impact_assurance_profiles(project))
+    policy_digest = digest_json(project.get("impactProfiles", {}))
+    selected: list[dict[str, Any]] = []
+    requirements: list[dict[str, Any]] = []
+    unresolved: list[dict[str, str]] = []
+
+    for profile in requested:
+        units = policy.get(profile) if isinstance(policy, dict) else None
+        if not isinstance(units, list) or not units:
+            requirements.append(
+                {
+                    "profile": profile,
+                    "status": "unavailable",
+                    "selectedUnits": [],
+                    "unresolvedPaths": [],
+                    "reason": "the consumer has not declared an impact policy for this profile",
+                }
+            )
+            unresolved.extend({"profile": profile, "path": path} for path in paths)
+            continue
+
+        matched: dict[str, set[str]] = {unit["id"]: set() for unit in units}
+        missing: list[str] = []
+        for path in paths:
+            matches = [unit for unit in units if _matches(path, unit["paths"])]
+            if not matches:
+                missing.append(path)
+                unresolved.append({"profile": profile, "path": path})
+                continue
+            for unit in matches:
+                matched[unit["id"]].add(path)
+
+        # Only an explicit universal pattern can subsume narrower units. A
+        # partial global pattern remains subject to the ordinary unresolved-
+        # path boundary.
+        global_ids = {
+            unit["id"]
+            for unit in units
+            if (
+                unit.get("scope", "matched") == "global"
+                and "**" in unit["paths"]
+                and matched[unit["id"]]
+            )
+        }
+
+        selected_for_profile = [
+            {
+                "profile": profile,
+                "id": unit["id"],
+                "matchedPaths": sorted(matched[unit["id"]]),
+            }
+            for unit in units
+            if matched[unit["id"]]
+            and (not global_ids or unit["id"] in global_ids)
+        ]
+        selected.extend(selected_for_profile)
+        requirements.append(
+            {
+                "profile": profile,
+                "status": "unresolved" if missing else "ready",
+                "selectedUnits": selected_for_profile,
+                "unresolvedPaths": sorted(missing),
+                **(
+                    {
+                        "reason": "one or more changed paths have no declared verification unit"
+                    }
+                    if missing
+                    else {}
+                ),
+            }
+        )
+
+    unresolved = sorted(
+        unresolved,
+        key=lambda item: (item["profile"], item["path"]),
+    )
+    status = "ready"
+    if unresolved or not paths:
+        status = "unresolved" if policy else "unavailable"
+    selection: dict[str, Any] = {
+        "schemaVersion": 2 if assurance_profiles else 1,
+        "changeId": state["changeId"],
+        "status": status,
+        "comparisonBaseCommit": base,
+        "policyDigest": policy_digest,
+        "assuranceProfiles": [
+            profile for profile in requested if profile in assurance_profiles
+        ],
+        "changedPaths": list(paths),
+        "requirements": requirements,
+        "selectedUnits": selected,
+        "unresolvedPaths": unresolved,
+    }
+    if status != "ready":
+        if not paths:
+            reason = "the candidate has no changed path from the pinned comparison base"
+        elif not policy:
+            reason = "the consumer has not declared a versioned impact policy"
+        else:
+            reason = "every requested profile must resolve every changed path before affected execution"
+        selection["resolution"] = {
+            "action": "inspect-diff-and-update-impact-policy",
+            "reason": reason,
+            "paths": list(paths),
+        }
+    return validate_document(
+        selection,
+        "verification-impact-selection",
+        schema_root=schemas_root(process_root),
+        source="verification impact selection",
+    )
+
+
+def unavailable_impact_selection(
+    project_root: Path,
+    process_root: Path,
+    state: dict[str, Any],
+    reason: str,
+    *,
+    profiles: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Build an actionable unavailable result when policy loading fails."""
+    required = tuple(state["contract"]["document"]["requiredProfiles"])
+    requested = tuple(required if profiles is None else profiles)
+    invalid = sorted(set(requested) - set(required))
+    if invalid:
+        raise ProcessError(
+            "impact selection may request only accepted required profiles: "
+            + ", ".join(invalid)
+        )
+    paths = changed_paths(project_root, state["comparisonBaseCommit"])
+    unresolved = [
+        {"profile": profile, "path": path}
+        for profile in requested
+        for path in paths
+    ]
+    selection = {
+        "schemaVersion": 1,
+        "changeId": state["changeId"],
+        "status": "unavailable",
+        "comparisonBaseCommit": state["comparisonBaseCommit"],
+        "changedPaths": list(paths),
+        "requirements": [
+            {
+                "profile": profile,
+                "status": "unavailable",
+                "selectedUnits": [],
+                "unresolvedPaths": list(paths),
+                "reason": "the consumer impact policy could not be loaded",
+            }
+            for profile in requested
+        ],
+        "selectedUnits": [],
+        "unresolvedPaths": unresolved,
+        "resolution": {
+            "action": "inspect-diff-and-update-impact-policy",
+            "reason": f"the consumer impact policy is invalid or unsupported: {reason}"[:2000],
+            "paths": list(paths),
+        },
+    }
+    return validate_document(
+        selection,
+        "verification-impact-selection",
+        schema_root=schemas_root(process_root),
+        source="verification impact selection",
+    )
+
+
+def impact_unit_lookup(
+    project: dict[str, Any], selection: dict[str, Any]
+) -> dict[tuple[str, str], dict[str, Any]]:
+    """Resolve selected output ids back to the consumer-owned command objects."""
+    policies = impact_profiles(project)
+    lookup: dict[tuple[str, str], dict[str, Any]] = {}
+    for profile, units in policies.items():
+        for unit in units:
+            lookup[(profile, unit["id"])] = unit
+    result: dict[tuple[str, str], dict[str, Any]] = {}
+    for selected in selection["selectedUnits"]:
+        key = (selected["profile"], selected["id"])
+        if key not in lookup:
+            raise ProcessError(
+                f"impact policy changed while resolving unit {key[0]}:{key[1]}"
+            )
+        result[key] = lookup[key]
+    return result