@danmoisan/drm-copilot-mcp 0.0.1 → 0.0.5

package/resources/customizations/.github/agents/python-orchestrator.agent.md

@@ -109,6 +109,10 @@ Use these reusable skills to avoid duplicating shared operations:
   - `${feature-folder}`: created active feature folder path
   - `${plan-path}`: workspace-relative path to the single plan file that must be updated in-place across all planning/preflight iterations
 
+5) **No manual steps by default**
+- Do not introduce manual bootstrap, human-operator validation, user-performed repro steps, or any other manual handoff unless the initial user request explicitly asked for manual orchestration from the beginning.
+- If a delegated plan, review, or remediation flow proposes a new manual step without that explicit initial opt-in, reject it, request a revision, or record blocked automated state instead of asking the user to perform the step.
+
 # Workflow router
 
 ## Phase 0 — Intake and budget estimate (mandatory)
@@ -196,11 +200,11 @@ Hard enforcement for S4:
 
 ### Step S5 — Branch by bootstrap mode
 
-S5.1 If request is `manual bootstrap`:
+S5.1 Only if the initial user request explicitly requested `manual bootstrap` from the beginning:
 - Save checkpoint with `next_step` at Phase 1 resume point.
 - Stop execution and return resume instructions.
 
-S5.2 If request is small development (not manual bootstrap):
+S5.2 Otherwise continue automated small development:
 - Continue to Step S6.
 
 ### Step S6 — Delegate constrained small-path development

package/resources/customizations/.github/agents/staged-review.agent.md

@@ -48,7 +48,7 @@ You MUST read and follow, in priority order:
 
 Policy Audit templates:
 - If and only if the user asked for a Policy Audit (this agent invocation counts), you MUST also follow:
-   - MCP server `drmCopilotExtension` tool `resolve_policy_audit_template_asset` with the selector appropriate to the needed artifact:
+   - MCP server `drm-copilot` tool `resolve_policy_audit_template_asset` with the selector appropriate to the needed artifact:
       - `asset: template` for `policy-audit.yyyy-MM-ddTHH-mm.md`
       - `asset: code-review-template` for `code-review.yyyy-MM-ddTHH-mm.md`
       - `asset: feature-audit-template` for `feature-audit.yyyy-MM-ddTHH-mm.md`

package/resources/customizations/.github/instructions/powershell-code-change.instructions.md

@@ -21,20 +21,20 @@ If you encounter any conflicting instructions, **halt and notify the user.**
 
 **Agent execution requirement (explicit):**
 
-- Agents must use the MCP server functions: `mcp__drmCopilotExtension__run_poshqc_format`, `mcp__drmCopilotExtension__run_poshqc_analyze`, `mcp_drmcopilotext_run_poshqc_test`, and `mcp__drmCopilotExtension__run_poshqc_analyze_autofix`.
+- Agents must use the MCP server functions: `mcp__drm-copilot__run_poshqc_format`, `mcp__drm-copilot__run_poshqc_analyze`, `mcp_drmcopilotext_run_poshqc_test`, and `mcp__drm-copilot__run_poshqc_analyze_autofix`.
 - Agents must **not** use VS Code task wrappers as a substitute.
 
 1) **Formatting - Invoke-Formatter**
 
 - Format all PowerShell files using the PoshQC formatter (Invoke-Formatter).
-- **Agent execution:** `mcp__drmCopilotExtension__run_poshqc_format`
+- **Agent execution:** `mcp__drm-copilot__run_poshqc_format`
 - Do not hand-format; re-run the formatter whenever PSScriptAnalyzer would change whitespace/indentation.
 
 2) **Linting - PSScriptAnalyzer**
 
 - Run the PoshQC analyzer (PSScriptAnalyzer) with repo settings.
-- **Agent execution:** `mcp__drmCopilotExtension__run_poshqc_analyze`
-- Optional autofix: `mcp__drmCopilotExtension__run_poshqc_analyze_autofix`; review diffs after running.
+- **Agent execution:** `mcp__drm-copilot__run_poshqc_analyze`
+- Optional autofix: `mcp__drm-copilot__run_poshqc_analyze_autofix`; review diffs after running.
 - Fix **all** findings (Error/Warning/Information). No rule suppressions unless strictly necessary and localized with a comment.
 
 3) **Compatibility**
@@ -69,8 +69,8 @@ If you encounter any conflicting instructions, **halt and notify the user.**
 
 When PowerShell code changes, your toolchain loop must include:
 
-1. Format: `mcp__drmCopilotExtension__run_poshqc_format`
-2. Analyze: `mcp__drmCopilotExtension__run_poshqc_analyze`
+1. Format: `mcp__drm-copilot__run_poshqc_format`
+2. Analyze: `mcp__drm-copilot__run_poshqc_analyze`
 3. (Type checking is not applicable for PowerShell; skip to testing.)
 4. Test: `mcp_drmcopilotext_run_poshqc_test`
 

package/resources/customizations/.github/prompts/generate-commit-message-repo.prompt.md

@@ -5,7 +5,7 @@ description: 'Standard loading prompt for completing partially filled user-story
 
 You are an expert Git commit message author operating in a professional, policy-driven repository.
 
-Your task is to generate **high-signal, conventional commit messages** based strictly on the supplied context file located at `/workspaces/transcript-etl-pipeline/artifacts/commit_context.txt`.
+Your task is to generate **high-signal, conventional commit messages** based strictly on the supplied commit-context artifact path or pasted commit-context content provided by the caller.
 Assume no prior conversation history beyond what is explicitly provided.
 
 ---

package/resources/customizations/.github/prompts/orchestrate-csharp-work.prompt.md

@@ -17,6 +17,7 @@ Coordinate the user request from intake to completion using the correct path bas
 - **Likely affected files (optional):** any known production/test files
 - **Initial classification hint (optional):** `feature` or `bug`
 - **Constraints (optional):** APIs/paths/behavior that must remain unchanged
+- **Manual orchestration opt-in (optional):** allowed only when the initial user request explicitly asked from the beginning for a manual bootstrap pause
 
 ## Required orchestration behavior
 
@@ -29,8 +30,8 @@ Coordinate the user request from intake to completion using the correct path bas
      4) Require `atomic_executor` preflight until `PREFLIGHT: ALL CLEAR`
      5) Delegate to `atomic_executor` to execute **Phase 0 only**
      6) Branch behavior:
-        - manual bootstrap: save state and stop for manual resume
-        - non-bootstrap small development: delegate constrained implementation to `csharp-typed-engineer`
+        - explicit initial manual bootstrap opt-in: save state and stop for manual resume
+        - otherwise continue automated small development and delegate constrained implementation to `csharp-typed-engineer`
    7) Delegate post-delivery validation to `atomic_executor` for validation against issue.md, using only the explicit `## Acceptance Criteria` section for minor-audit acceptance validation, and persist checklist/doc updates
      8) Run reduced small-path audit and remediation loop until ready-to-merge
 3. If budget is **>3 production C# files** or **>3 test C# files**:
@@ -48,6 +49,7 @@ Coordinate the user request from intake to completion using the correct path bas
 - Maintain orchestration state in `artifacts/orchestration/csharp-orchestrator-state.json`.
 - Resume from the next incomplete step if interrupted.
 - Do not end early while required downstream steps remain.
+- Do not introduce manual validation or other human-operator steps later in the workflow unless the initial user request explicitly opted in from the beginning.
 
 ## Output expectations
 
@@ -62,5 +64,5 @@ On completion, report:
 For small path also report:
 - approved `plan-path`
 - preflight result (`PREFLIGHT: ALL CLEAR`)
-- whether `manual bootstrap` branch was taken
+- whether an explicit initial manual-bootstrap opt-in was present and used
 - Phase 0 execution evidence and stored `next_step` for resume

package/resources/customizations/.github/prompts/orchestrate-work.prompt.md

@@ -17,6 +17,7 @@ Coordinate the user request from intake to completion using the correct path bas
 - **Likely affected files (optional):** any known production/test files
 - **Initial classification hint (optional):** `feature` or `bug`
 - **Constraints (optional):** APIs/paths/behavior that must remain unchanged
+- **Manual orchestration opt-in (optional):** allowed only when the initial user request explicitly asked from the beginning for a manual bootstrap pause
 
 ## Required orchestration behavior
 
@@ -29,8 +30,8 @@ Coordinate the user request from intake to completion using the correct path bas
      4) Require `atomic_executor` preflight until `PREFLIGHT: ALL CLEAR`
      5) Delegate to `atomic_executor` to execute **Phase 0 only**
      6) Branch behavior:
-        - manual bootstrap: save state and stop for manual resume
-        - non-bootstrap small development: delegate constrained implementation to the small-path engineer
+        - explicit initial manual bootstrap opt-in: save state and stop for manual resume
+        - otherwise continue automated small development and delegate constrained implementation to the small-path engineer
    7) Delegate post-delivery validation to `atomic_executor` against `issue.md`, using only the explicit `## Acceptance Criteria` section for minor-audit acceptance validation, and persist checklist/doc updates
      8) Run reduced small-path audit and remediation loop until ready-to-merge
 3. If budget is **>3 production files** or **>3 test files**:
@@ -48,6 +49,7 @@ Coordinate the user request from intake to completion using the correct path bas
 - Maintain orchestration state in `artifacts/orchestration/orchestrator-state.json`.
 - Resume from the next incomplete step if interrupted.
 - Do not end early while required downstream steps remain.
+- Do not introduce manual validation or other human-operator steps later in the workflow unless the initial user request explicitly opted in from the beginning.
 
 ## Output expectations
 
@@ -62,5 +64,5 @@ On completion, report:
 For small path also report:
 - approved `plan-path`
 - preflight result (`PREFLIGHT: ALL CLEAR`)
-- whether `manual bootstrap` branch was taken
+- whether an explicit initial manual-bootstrap opt-in was present and used
 - Phase 0 execution evidence and stored `next_step` for resume

package/resources/customizations/.github/skills/atomic-plan-contract/SKILL.md

@@ -73,9 +73,22 @@ After preflight all-clear on the minimal-audit plan:
 - orchestrator MUST checkpoint Phase 0 evidence before branching.
 
 Branching after Phase 0:
-- `manual bootstrap` → save state and stop for manual resume,
+- `manual bootstrap` → save state and stop for manual resume ONLY when the initial user request explicitly opted into manual orchestration from the beginning,
 - otherwise continue with constrained small-path development, then executor validation, then reduced audit/remediation loop.
 
+## No-Manual-Step Contract (Mandatory)
+
+Unless the user's initial request explicitly opts into manual orchestration from the beginning, approved plans and remediation plans MUST remain fully automated.
+
+This prohibition includes:
+
+- manual bootstrap pauses,
+- human-operator validation tasks,
+- user-performed repro or QA steps,
+- requests for screenshots, notes, or runtime evidence that the agent cannot collect itself.
+
+When a fully automated equivalent is unavailable, the plan MUST fail closed by recording blocked or remediation-required automated state. It MUST NOT introduce a new manual step later in the workflow.
+
 ## Phase 0 Requirements
 
 Phase 0 must include tasks to read policy files in the order defined in `policy-compliance-order`.

package/resources/customizations/.github/skills/feature-promotion-lifecycle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-promotion-lifecycle
-description: Deterministic promotion workflow from potential feature/bug entry to issue, branch, active feature folder, and downstream spec/research handoffs. Prefer MCP server (drmCopilotExtension) tool invocations when the MCP server is reachable; use underlying scripts only as fallback.
+description: Deterministic promotion workflow from potential feature/bug entry to issue, branch, active feature folder, and downstream spec/research handoffs. Prefer MCP server (drm-copilot) tool invocations when the MCP server is reachable; use underlying scripts only as fallback.
 ---
 
 # Feature Promotion Lifecycle
@@ -17,13 +17,13 @@ Use this skill when:
 
 ## MCP-First Execution Rule
 
-When the MCP server (`drmCopilotExtension`) is reachable, execute the lifecycle through the MCP tool surface first.
+When the MCP server (`drm-copilot`) is reachable, execute the lifecycle through the MCP tool surface first.
 
 Canonical MCP tool invocations:
-- feature potential entry: `mcp__drmCopilotExtension__new_potential_entry` with `{"short_name": "${short-name}"}`
-- bug potential entry: `mcp__drmCopilotExtension__new_potential_bug_entry` with `{"short_name": "${short-name}"}`
-- potential-to-issue promotion: `mcp__drmCopilotExtension__potential_to_issue` with `{"potential_path": "${relativeFile}", "promotion_type": "${promotion-type}", "work_mode": "${work-mode}"}`
-- active feature folder creation: `mcp__drmCopilotExtension__new_active_feature_folder` with `{"feature_name": "${long-name}", "type": "${promotion-type}", "issue_number": "${issue-num}", "work_mode": "${work-mode}"}`
+- feature potential entry: `mcp__drm-copilot__new_potential_entry` with `{"short_name": "${short-name}"}`
+- bug potential entry: `mcp__drm-copilot__new_potential_bug_entry` with `{"short_name": "${short-name}"}`
+- potential-to-issue promotion: `mcp__drm-copilot__potential_to_issue` with `{"potential_path": "${relativeFile}", "promotion_type": "${promotion-type}", "work_mode": "${work-mode}"}`
+- active feature folder creation: `mcp__drm-copilot__new_active_feature_folder` with `{"feature_name": "${long-name}", "type": "${promotion-type}", "issue_number": "${issue-num}", "work_mode": "${work-mode}"}`
 
 Documented alternatives:
 - VS Code extension commands (via `vscode/runCommand`): use when MCP server is unreachable but the VS Code extension command surface is available.
@@ -90,9 +90,13 @@ When orchestrator routing selects short path, promotion/folder initialization st
 6) Execute plan Phase 0 only via executor and checkpoint evidence.
 
 7) Branch:
-- manual bootstrap: save state and stop,
+- manual bootstrap: save state and stop ONLY when the initial user request explicitly opted into manual orchestration from the beginning,
 - non-bootstrap: continue with constrained small-path development.
 
+Automation rule:
+- do not introduce manual bootstrap, human-operator validation, or any other manual handoff later in orchestration unless that initial explicit opt-in exists
+- if automation cannot proceed, record blocked automated state instead of asking for manual intervention
+
 8) Validate delivery via executor against `issue.md`, then run reduced audit/remediation loop until ready-to-merge.
 
 ## Required Outputs for Downstream Handoffs

package/resources/customizations/.github/skills/feature-review-workflow/SKILL.md

@@ -132,6 +132,14 @@ Always apply:
 9. **Finalize the review**
    - Verify every reported artifact exists on disk before reporting completion.
    - Report artifact paths and a concise go/no-go recommendation for PR readiness.
+   - End the final report with these exact single-line fields:
+     - `REVIEW_STATUS: PASS` or `REVIEW_STATUS: REMEDIATION_REQUIRED`
+     - `FEATURE_FOLDER: <path>`
+     - `POLICY_AUDIT: <path>`
+     - `CODE_REVIEW: <path>`
+     - `FEATURE_AUDIT: <path>`
+     - `REMEDIATION_INPUTS: <path-or-NONE>`
+     - `REMEDIATION_PLAN: <path-or-NONE>`
 
 ## Required Artifact Shapes
 
@@ -150,4 +158,5 @@ Always apply:
 
 - Prefer check-only commands.
 - Do not claim completion until every required artifact exists and its validator passes.
-- Use shared skills as the source of truth for policy order, base-branch resolution, PR-context handling, acceptance-criteria tracking, template usage, and remediation handoff.
+- Use shared skills as the source of truth for policy order, base-branch resolution, PR-context handling, acceptance-criteria tracking, template usage, and remediation handoff.
+- Do not omit any required final result field from the review report.

package/resources/customizations/.github/skills/pr-base-branch-merge-base/SKILL.md

@@ -10,7 +10,7 @@ Deterministic branch-selection rules for PR context collection.
 ## When to Use This Skill
 
 Use this skill when:
-- running via MCP server `drmCopilotExtension` tool `collect_pr_context`,
+- running via MCP server `drm-copilot` tool `collect_pr_context`,
 - delegating post-implementation review that depends on `PRBaseBranch`,
 - constructing PR context artifacts where the base must not be hard-coded.
 
@@ -44,7 +44,7 @@ Definition of correct base:
 
 When invoking PR context collection, pass the resolved base explicitly:
 
-- per `pr-context-artifacts` via MCP server `drmCopilotExtension` tool `collect_pr_context` with `base: ${resolved-PRBaseBranch}`
+- per `pr-context-artifacts` via MCP server `drm-copilot` tool `collect_pr_context` with `base: ${resolved-PRBaseBranch}`
 
 ## Evidence Recommendation
 

package/resources/customizations/.github/skills/remediation-handoff-atomic-planner/SKILL.md

@@ -33,6 +33,11 @@ Create `remediation-inputs.<timestamp>.md` with:
    - `${spec}` pointing to remediation inputs (authoritative)
    - `${file}` pointing to the remediation plan target file
 3) Require `atomic_planner` to output a deterministic, atomic plan with phases and `[P#-T#]` IDs.
+4) Require the same `${file}` path to be updated in place across all remediation-plan revisions in the same remediation loop.
+5) The caller owns the downstream clearance loop:
+   - hand the resulting remediation plan to `atomic_executor` in preflight-validation mode,
+   - if preflight returns `PREFLIGHT: REVISIONS REQUIRED`, re-delegate to `atomic_planner` against the same `${file}` path,
+   - execute the remediation plan only after `PREFLIGHT: ALL CLEAR`.
 
 ## Context Package (When Required)
 

package/resources/powershell/PoshQC/settings/pester.runsettings.psd1

@@ -26,6 +26,13 @@
             '.claude/hooks/check-powershell-test-purity.ps1'
             '.claude/hooks/enforce-python-batch-budget.ps1'
             '.claude/hooks/enforce-powershell-batch-budget.ps1'
+            # Issue #214 added/changed these four release scripts and provided dedicated
+            # Pester suites; they are measured here to produce real per-file changed-line
+            # coverage rather than relying on behavioral-only evidence.
+            'scripts/powershell/Publish-DrmCopilotExtension.ps1'
+            'scripts/dev-tools/Invoke-FullRelease.ps1'
+            'scripts/dev-tools/Invoke-MarketplacePublish.ps1'
+            'scripts/dev-tools/Invoke-ReleaseTagPush.ps1'
         )
         ExcludedPath          = @(
             '.claude/hooks/validate-feature-review-coverage.ps1' # Feature-review wrapper around repository evidence; not deterministic in normal unit-test execution.

package/resources/scripts/dev_tools/_orchestrator_state_human_interaction.py

@@ -0,0 +1,127 @@
+"""Human-interaction invariants for orchestrator-state checkpoints.
+
+Purpose:
+    Hold the optional ``human_interaction`` block constants and the
+    ``_validate_human_interaction`` helper so the primary validator module
+    (`scripts.dev_tools.validate_orchestrator_state`) can stay within the
+    repository's 500-line file limit while preserving the existing validator
+    contract.
+
+Usage:
+    Import ``HUMAN_INTERACTION_KEY`` and ``_validate_human_interaction`` from
+    this module. The primary validator re-exports both symbols so existing
+    callers and tests continue to resolve them from
+    ``scripts.dev_tools.validate_orchestrator_state`` unchanged.
+
+Invariants / Constraints:
+    - The three permitted ``response`` values are ``scope_change``,
+      ``exception``, and ``halt``.
+    - An ``exception`` response requires a non-empty ``runbook_path`` string.
+    - The validator never imports ``schemas/orchestrator-state.schema.json``;
+      the invariants are expressed directly here per
+      `.claude/rules/orchestrator-state.md`.
+
+Side Effects:
+    None.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+# Declare the module's intended exported surface. Listing ``_validate_human_
+# interaction`` here marks it as a deliberate re-export consumed by
+# ``validate_orchestrator_state``, so static analysis does not flag the helper
+# as unused locally or as private-usage when imported across the module boundary.
+__all__ = [
+    "HUMAN_INTERACTION_KEY",
+    "HUMAN_INTERACTION_REQUIREMENTS_KEY",
+    "HUMAN_INTERACTION_RESPONSE_ENUM",
+    "HUMAN_INTERACTION_EXCEPTION_RESPONSE",
+    "_validate_human_interaction",
+]
+
+HUMAN_INTERACTION_KEY = "human_interaction"
+HUMAN_INTERACTION_REQUIREMENTS_KEY = "requirements"
+# The three permitted responses for an unautomatable requirement under the
+# autonomous-execution mandate (see `.claude/skills/orchestrate/SKILL.md`).
+HUMAN_INTERACTION_RESPONSE_ENUM = {"scope_change", "exception", "halt"}
+HUMAN_INTERACTION_EXCEPTION_RESPONSE = "exception"
+
+
+def _validate_human_interaction(human_interaction: object) -> list[str]:
+    """Validate the optional ``human_interaction`` block invariants.
+
+    Purpose:
+        Apply the autonomous-execution mandate invariants to the checkpoint's
+        optional top-level ``human_interaction`` object, mirroring the schema
+        invariants documented in `.claude/rules/orchestrator-state.md`. The
+        validator never imports `schemas/orchestrator-state.schema.json`; the
+        invariants are expressed directly here in the existing helper-plus-
+        error-list style.
+
+    Args:
+        human_interaction (object): The raw value of the checkpoint's top-level
+            ``human_interaction`` key. Callers invoke this helper only when the
+            key is present, so a non-object value is itself a malformed block.
+
+    Returns:
+        list[str]: One error string per violated invariant; an empty list when
+        the block is well-formed. The three invariants are: ``requirements`` is
+        present and is a list; each requirement is an object whose ``response``
+        is within the permitted enum; a requirement whose ``response`` is
+        ``exception`` carries a non-empty ``runbook_path`` string.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+
+    errors: list[str] = []
+
+    # A non-object human_interaction cannot carry a requirements list; the key
+    # was present, so this is a malformed block rather than an absent one.
+    if not isinstance(human_interaction, dict):
+        errors.append("Checkpoint human_interaction must be an object when present.")
+        return errors
+    human_interaction_map = cast("dict[str, Any]", human_interaction)
+
+    # Invariant 1: requirements must be present and a list.
+    requirements = human_interaction_map.get(HUMAN_INTERACTION_REQUIREMENTS_KEY)
+    if not isinstance(requirements, list):
+        errors.append("Checkpoint human_interaction.requirements must be a list.")
+        return errors
+    requirement_list = cast("list[object]", requirements)
+
+    # Validate each requirement independently so callers receive a complete
+    # error list instead of stopping at the first malformed requirement.
+    for index, requirement in enumerate(requirement_list):
+        if not isinstance(requirement, dict):
+            errors.append(
+                f"Checkpoint human_interaction.requirements #{index} must be an "
+                "object."
+            )
+            continue
+        requirement_map = cast("dict[str, Any]", requirement)
+
+        # Invariant 2: response must be within the permitted enum.
+        response = requirement_map.get("response")
+        if response not in HUMAN_INTERACTION_RESPONSE_ENUM:
+            errors.append(
+                f"Checkpoint human_interaction.requirements #{index} response "
+                f"must be one of scope_change, exception, halt; got: {response}"
+            )
+            continue
+
+        # Invariant 3: an exception response requires a non-empty runbook_path.
+        if response == HUMAN_INTERACTION_EXCEPTION_RESPONSE:
+            runbook_path = requirement_map.get("runbook_path")
+            if not isinstance(runbook_path, str) or not runbook_path.strip():
+                errors.append(
+                    f"Checkpoint human_interaction.requirements #{index} "
+                    "response is exception but runbook_path is missing or empty."
+                )
+
+    return errors

package/resources/scripts/dev_tools/_orchestrator_state_routing.py

@@ -0,0 +1,216 @@
+"""Routing and mandatory handoff invariants for orchestrator checkpoints."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, cast
+
+ROUTING_MATRIX_PATH = (
+    Path(__file__).resolve().parents[2] / "config" / "orchestration-routing.json"
+)
+
+
+def load_routing_matrix(path: Path = ROUTING_MATRIX_PATH) -> dict[str, Any]:
+    """Load the repository routing matrix from disk."""
+
+    loaded: object = json.loads(path.read_text(encoding="utf-8"))
+    return cast("dict[str, Any]", loaded)
+
+
+def _string_list(value: object) -> list[str] | None:
+    """Return a list of strings only when the value has that exact shape."""
+
+    if not isinstance(value, list):
+        return None
+    values = cast("list[object]", value)
+    if not all(isinstance(item, str) and item.strip() for item in values):
+        return None
+    return cast("list[str]", values)
+
+
+def _route_list(route: dict[str, Any], key: str) -> list[str]:
+    """Read a required string-list field from one route entry."""
+
+    value = _string_list(route.get(key))
+    return [] if value is None else value
+
+
+def _state_list(
+    state: dict[str, Any], key: str, route_id: str, expected: list[str]
+) -> list[str] | None:
+    """Validate a state list against the routing matrix list."""
+
+    value = _string_list(state.get(key))
+    if value is None:
+        return None
+    if value != expected:
+        return None
+    return value
+
+
+def _list_receipts(receipts: object) -> list[dict[str, Any]]:
+    """Return legacy list delegation receipts as typed dictionaries."""
+
+    if not isinstance(receipts, list):
+        return []
+    receipt_list = cast("list[object]", receipts)
+    return [
+        cast("dict[str, Any]", item) for item in receipt_list if isinstance(item, dict)
+    ]
+
+
+def _receipt_agents(state: dict[str, Any]) -> set[str]:
+    """Collect agent names from delegation receipts."""
+
+    agents: set[str] = set()
+    for receipt in _list_receipts(state.get("delegation_receipts")):
+        agent_name = receipt.get("agent_name")
+        if isinstance(agent_name, str) and agent_name.strip():
+            agents.add(agent_name)
+    return agents
+
+
+def _receipt_skills(state: dict[str, Any]) -> set[str]:
+    """Collect acknowledged skill names from skill receipts."""
+
+    skills: set[str] = set()
+    receipts = state.get("skill_receipts")
+    if not isinstance(receipts, list):
+        return skills
+    for receipt in cast("list[object]", receipts):
+        if not isinstance(receipt, dict):
+            continue
+        receipt_map = cast("dict[str, object]", receipt)
+        skill = receipt_map.get("skill")
+        required = receipt_map.get("required")
+        evidence = receipt_map.get("evidence")
+        if (
+            isinstance(skill, str)
+            and skill.strip()
+            and required is True
+            and isinstance(evidence, str)
+            and evidence.strip()
+        ):
+            skills.add(skill)
+    return skills
+
+
+def _mcp_tools(state: dict[str, Any]) -> set[str]:
+    """Collect successful MCP tool receipts from checkpoint state."""
+
+    tools: set[str] = set()
+    receipts = state.get("mcp_call_receipts")
+    if not isinstance(receipts, list):
+        return tools
+    for receipt in cast("list[object]", receipts):
+        if not isinstance(receipt, dict):
+            continue
+        receipt_map = cast("dict[str, object]", receipt)
+        tool = receipt_map.get("tool")
+        ok = receipt_map.get("ok")
+        evidence = receipt_map.get("evidence")
+        if (
+            isinstance(tool, str)
+            and tool.strip()
+            and ok is True
+            and isinstance(evidence, str)
+            and evidence.strip()
+        ):
+            tools.add(tool)
+    return tools
+
+
+def _validate_empty_list_field(state: dict[str, Any], key: str) -> list[str]:
+    """Require a checkpoint field to exist as an empty list."""
+
+    value = state.get(key)
+    if not isinstance(value, list):
+        return [f"Checkpoint {key} must be an empty list at completion."]
+    if value:
+        return [f"Checkpoint {key} must be empty at completion."]
+    return []
+
+
+def _validate_lifecycle_operations(state: dict[str, Any]) -> list[str]:
+    """Reject lifecycle-operation records that did not use MCP."""
+
+    operations = state.get("lifecycle_operations")
+    if operations is None:
+        return []
+    if not isinstance(operations, list):
+        return ["Checkpoint lifecycle_operations must be a list when present."]
+    errors: list[str] = []
+    for index, operation in enumerate(cast("list[object]", operations)):
+        if not isinstance(operation, dict):
+            errors.append(
+                f"Checkpoint lifecycle_operations #{index} must be an object."
+            )
+            continue
+        operation_map = cast("dict[str, object]", operation)
+        if operation_map.get("surface") != "mcp":
+            errors.append(
+                f"Checkpoint lifecycle_operations #{index} did not use MCP surface."
+            )
+    return errors
+
+
+def validate_routing_contract(
+    state: dict[str, Any], *, routing_matrix: dict[str, Any] | None = None
+) -> list[str]:
+    """Validate mandatory route, handoff, skill, and MCP completion evidence."""
+
+    matrix = routing_matrix if routing_matrix is not None else load_routing_matrix()
+    raw_routes = matrix.get("routes")
+    if not isinstance(raw_routes, dict):
+        return ["Routing matrix missing routes object."]
+    routes = cast("dict[str, object]", raw_routes)
+
+    route_id = state.get("route_id", state.get("path_selected"))
+    if not isinstance(route_id, str) or not route_id.strip():
+        return ["Checkpoint route_id or path_selected must select a route."]
+    raw_route = routes.get(route_id)
+    if not isinstance(raw_route, dict):
+        return [f"Checkpoint selected route has no routing-matrix entry: {route_id}."]
+    route_map = cast("dict[str, Any]", raw_route)
+
+    errors: list[str] = []
+    required_agents = _route_list(route_map, "required_agents")
+    required_skills = _route_list(route_map, "required_skills")
+    required_mcp_tools = _route_list(route_map, "required_mcp_tools")
+
+    if _state_list(state, "required_agents", route_id, required_agents) is None:
+        errors.append(
+            "Checkpoint required_agents must match routing matrix for route "
+            f"{route_id}."
+        )
+    if _state_list(state, "required_skills", route_id, required_skills) is None:
+        errors.append(
+            "Checkpoint required_skills must match routing matrix for route "
+            f"{route_id}."
+        )
+    if _state_list(state, "required_mcp_tools", route_id, required_mcp_tools) is None:
+        errors.append(
+            "Checkpoint required_mcp_tools must match routing matrix for route "
+            f"{route_id}."
+        )
+
+    actual_agents = _receipt_agents(state)
+    for agent in required_agents:
+        if agent not in actual_agents:
+            errors.append(f"Checkpoint missing required agent receipt: {agent}.")
+
+    actual_skills = _receipt_skills(state)
+    for skill in required_skills:
+        if skill not in actual_skills:
+            errors.append(f"Checkpoint missing required skill receipt: {skill}.")
+
+    actual_tools = _mcp_tools(state)
+    for tool in required_mcp_tools:
+        if tool not in actual_tools:
+            errors.append(f"Checkpoint missing successful MCP receipt: {tool}.")
+
+    errors.extend(_validate_empty_list_field(state, "local_execution_overrides"))
+    errors.extend(_validate_empty_list_field(state, "delegation_bypasses"))
+    errors.extend(_validate_lifecycle_operations(state))
+    return errors