@danmoisan/drm-copilot-mcp 1.0.1 → 1.0.8

package/resources/codex-and-agents-customizations/.agents/skills/orchestrate/SKILL.md

@@ -109,6 +109,24 @@ staging, commits, or implementation delegation. This gate covers edits, formatte
 If any required item is missing, implementation is blocked until the checkpoint
 and lifecycle state are corrected.
 
+## Plan-Path Resolution Gate
+
+After active feature folder creation and before any planning delegation, the
+main session must resolve `${plan-path}` from the active feature folder:
+
+1. Enumerate existing `${feature-folder}/plan*.md` files in deterministic
+   filename order.
+2. If one or more files exist, persist `${plan-path}` as the first existing
+   file and require every planner and executor handoff to use that exact path.
+3. If no `plan*.md` file exists, create exactly one canonical target path using
+   the repository's feature-folder plan naming convention, persist that path,
+   and reuse it for all revisions.
+4. Do not default to `${feature-folder}/plan.md` when a timestamped scaffolded
+   plan already exists.
+5. If checkpoint state names a different plan path than the resolved existing
+   plan file, correct the checkpoint before planner delegation. Do not create a
+   second plan artifact to satisfy an incorrect checkpoint value.
+
 ## Pre-Implementation Violation Handling
 
 If an implementation action is attempted before a required orchestration gate
@@ -141,9 +159,12 @@ There is no fallback. If the MCP server or validation tool is unavailable, or
 if validation fails, the orchestrator must update blocked state and stop rather
 than reporting completion.
 
-The repository CI gate `Orchestrator State Gate` runs the same validator when a
-checkpoint is present. Branch protection should require this check for branches
-that use orchestrated completion.
+No CI workflow performs this validation. The `artifacts/` directory is gitignored,
+so the orchestrator-state checkpoint is never present in a CI checkout; a prior
+CI gate (`validate-orchestrator-state.yml`) that attempted this check was a
+structural no-op for that reason and has been removed. The MCP-server-based
+validation described above is this ecosystem's enforcement mechanism for the
+orchestrator-state checkpoint.
 
 Completion validation requires the checkpoint to prove mandatory handoffs and
 skill use. The checkpoint must include:

package/resources/codex-and-agents-customizations/.agents/skills/orchestrator-workflow/SKILL.md

@@ -101,6 +101,16 @@ Persist and reuse these fields exactly:
 - `lifecycle_operations`
 - `pre-implementation-violation`
 
+Plan-path invariant:
+- `${plan-path}` is resolved only after `${feature-folder}` exists.
+- The orchestrator MUST enumerate existing `${feature-folder}/plan*.md` files
+  in deterministic filename order before planner delegation.
+- If any existing plan file is present, `${plan-path}` MUST be that first
+  existing file. Do not persist or delegate against `${feature-folder}/plan.md`
+  when a timestamped scaffolded plan already exists.
+- If checkpoint state conflicts with the resolved existing plan file, correct
+  checkpoint state before delegation and do not create a duplicate plan.
+
 For small-path runs, also persist:
 - `bootstrap_mode`
 - `phase0_execution_summary`
@@ -310,6 +320,9 @@ Required behavior:
 7. When those specialists are not yet migrated, perform the authoring steps directly without changing template headings.
 8. Spawn `atomic-planner` to finalize `${plan-path}` and require `PREFLIGHT: ALL CLEAR`.
     Hard enforcement for Step 7:
+    - Before spawning `atomic-planner`, resolve `${plan-path}` by enumerating
+      existing `${feature-folder}/plan*.md` files. Reuse the first existing file
+      in deterministic filename order, including timestamped scaffolded plans.
     - The planning route MUST be `atomic-planner -> atomic-executor` for preflight validation.
     - The planner MUST update `${plan-path}` in place and MUST NOT create additional `plan.*.md` files for revisions.
     - The approved plan MUST include explicit Phase 0 baseline evidence tasks and explicit final-QA evidence or coverage tasks for each language in scope where policy requires them.

package/resources/codex-and-agents-customizations/.agents/skills/remediation-handoff-atomic-planner/SKILL.md

@@ -22,7 +22,7 @@ Trigger remediation when any of these are true:
 
 ## Required Remediation Inputs
 
-Create `remediation-inputs.<timestamp>.md` with:
+Create `remediation/<timestamp>/remediation-inputs.md` (one timestamped `remediation/` folder per cycle; reaudit artifacts from a triggering or exit review live under the sibling `audit/<timestamp>/` folder, per the canonical pattern documented in the Claude-side `remediation-handoff-atomic-planner` skill) with:
 - Enumerated fix list with file paths, expected behavior, and verification commands.
 - A “do not do” list (no scope creep, no policy weakening, no silent skips).
 

package/resources/codex-and-agents-customizations/.agents-variants/csharp-legacy/skills/csharp/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: csharp
+paths:
+  - "**/*.cs"
+  - "**/*.csproj"
+description: C#-specific toolchain and coding standards.
+---
+
+# C# Code Standards
+
+Legacy C# variant resource for Codex push-down.
+
+This rule file summarizes the C#-specific policies for this repository.
+
+## Toolchain
+
+1. **Formatting — CSharpier**: All C# source files must be formatted with CSharpier. Do not use `dotnet format`. Command: `dotnet tool run csharpier .` or `csharpier .`
+2. **Linting — .NET Analyzers**: C# code must pass Roslyn/.NET analyzer diagnostics. Command: `msbuild TaskMaster.sln /t:Build /p:Configuration=Debug /p:Platform="Any CPU" /p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true`
+3. **Type Checking — Nullable Analysis**: Enable nullable reference types and fail on warnings. Command: `msbuild TaskMaster.sln /t:Build /p:Configuration=Debug /p:Platform="Any CPU" /p:Nullable=enable /p:TreatWarningsAsErrors=true`
+4. **Testing — MSTest + Moq + FluentAssertions**: Run tests with: `vstest.console.exe <test-assembly-paths> /EnableCodeCoverage`
+
+Run the toolchain in order: format → lint → type-check → test. Restart from step 1 if any step fails or changes files.
+
+## Coding Standards
+
+- **Naming**: `PascalCase` for types and public members. `camelCase` for locals and private fields/parameters.
+- **Null safety**: Keep nullable reference types enabled. Model optional values with nullable annotations and guard clauses.
+- **Composition over inheritance**: Keep classes cohesive and scoped to one responsibility. Favor composition unless polymorphism is a clear requirement.
+- **Async/await**: Use `async`/`await` for I/O-bound operations. Prefer `using`/`await using` for disposable resources.
+- **Exceptions**: Fail fast with explicit exceptions. Avoid broad `catch (Exception)` unless at a defined boundary with added context.
+- **Public surface**: Keep public API surface intentional and minimal. Prefer `internal` for non-public APIs.
+- **XML docs**: Public APIs should include XML documentation comments when behavior or contract is non-obvious.
+
+## Testing Standards
+
+- Use **MSTest** (`Microsoft.VisualStudio.TestTools.UnitTesting`) as the test framework.
+- Use **Moq** for mocking.
+- Prefer **FluentAssertions** for assertions; use MSTest `Assert` only when FluentAssertions is not practical.
+- Use `[TestClass]` and `[TestMethod]` attributes.
+- Follow Arrange–Act–Assert structure.
+- No external dependencies in unit tests.
+- Repository-wide line coverage must remain >= 80%.
+- Any new module, class, or method must reach >= 90% coverage.
+- Coverage regression on changed lines is a blocking finding.
+
+## Deterministic Test Rules
+
+Unit tests must not depend on network, mutable machine PATH or profile state, implicit working-directory assumptions, or external services. Use seam-based mocking for all external boundaries (processes, HTTP, filesystem, clocks). Tests must produce identical results in the IDE test runner and in CLI runs so local and CI behavior agree.
+
+## DI Seams
+
+Introduce the smallest seam that enables reliable unit testing. Apply in this order of preference:
+
+1. **Interface seam (preferred)** — extract boundary calls into narrow purpose-specific interfaces (for example, `IProcessRunner`, `IFileSystem`, `IClock`). Keep interfaces minimal.
+2. **Injectable delegate seam** — use a narrow `Func<>`/`Action<>` delegate for a single call path when a full interface is excessive. Default behavior must remain safe and deterministic.
+3. **Adapter seam for static or third-party APIs** — wrap the static or third-party call behind a small adapter so tests can mock the adapter with Moq.
+
+## Prohibited Behaviors
+
+- Broad refactors across unrelated projects or files.
+- Introducing heavy generic abstraction frameworks without need.
+- Creating analyzer debt and deferring cleanup.
+- Weakening assertions or relaxing test expectations to make tests pass.
+- Adding sleeps, retries, or timing hacks to mask flaky behavior.
+- Reporting success without running the required toolchain.

package/resources/codex-and-agents-customizations/.agents-variants/csharp-legacy/skills/csharp-qa-gate/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: csharp-qa-gate
+description: Final QA gate for C# changes. Executes the full CSharpier -> .NET Analyzers -> Nullable Analysis -> MSTest toolchain, compares against a captured baseline, enforces zero-regression deltas, and produces the required reporting block before the agent declares the change complete.
+---
+
+# C# QA Gate
+
+Legacy C# variant resource for Codex push-down.
+
+Canonical procedure for the Phase D final quality gate that every C# change must pass before completion is reported.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- `csharp-typed-engineer` is about to declare a change complete.
+- An executor has finished applying a planned batch and must verify zero regressions against the baseline captured in Phase A.
+- A reviewer needs to confirm the toolchain was actually run and produced a clean pass.
+
+## Required Inputs
+
+Before invoking this gate, the agent must have:
+
+- a baseline record produced in Phase A, containing analyzer findings, compiler/nullable diagnostics, MSTest pass/fail status, and per-file coverage status for the in-scope files,
+- the exact list of touched production and test files,
+- a clean working tree (all planned edits committed to the working copy).
+
+## Toolchain Execution Sequence
+
+Run the full toolchain in this exact order. If any step fails or modifies files, fix the issue and restart from step 1. Do not stop the loop until all four steps complete without errors in a single pass.
+
+1. `dotnet tool run csharpier .`
+2. `msbuild TaskMaster.sln /t:Build /p:Configuration=Debug /p:Platform="Any CPU" /p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true`
+3. `msbuild TaskMaster.sln /t:Build /p:Configuration=Debug /p:Platform="Any CPU" /p:Nullable=enable /p:TreatWarningsAsErrors=true`
+4. `vstest.console.exe <test-assembly-paths> /EnableCodeCoverage`
+
+If the environment prevents running any tool, stop and report the change as **unverified**. Do not declare completion.
+
+## Delta Requirements (Zero-Regression Hard Gate)
+
+Compare the final results to the Phase A baseline. All of the following must hold:
+
+- **Analyzer delta**: 0 new findings across the repository.
+- **Compiler / nullable delta**: 0 new diagnostics across the repository.
+- **MSTest delta**: 0 new failing tests.
+- **Per-file coverage delta**: coverage for every touched file is greater than or equal to the baseline for that file.
+- **Overall coverage delta** (when the repo enforces it): overall coverage is greater than or equal to the baseline.
+- **New modules, classes, or methods**: coverage >= 90% for each new unit introduced in the batch.
+
+If any delta check fails, the agent must revert or fix immediately and rerun the full toolchain. Do not proceed to reporting until all deltas are clean.
+
+## Required Reporting Block
+
+Every completion response must include the following sections:
+
+1. **Scope** — exact file list touched in this change.
+2. **Baseline** — analyzer, compiler/nullable, MSTest, and coverage status recorded in Phase A.
+3. **Plan** — design and test-strategy summary, referencing the approved plan.
+4. **Diffs** — patch-style or full-file replacements for scoped files only.
+5. **QA Gate Results** — analyzer, compiler/nullable, MSTest, and coverage deltas. If any step could not be run, mark the corresponding line **unverified** and state why.
+
+## Evidence Storage
+
+Persist toolchain output according to `evidence-and-timestamp-conventions`:
+
+- store baseline outputs under `<FEATURE>/evidence/baseline/<timestamp>/`,
+- store post-change outputs under `<FEATURE>/evidence/qa-gates/<timestamp>/`,
+- use ISO-8601 UTC timestamps in folder names.
+
+This location is canonical per evidence-and-timestamp-conventions and is not overridable.
+See `.agents/skills/evidence-and-timestamp-conventions/SKILL.md` for the canonical evidence path authority.
+
+The evidence paths must be referenced in the agent's completion message to satisfy the `SubagentStop` completion-artifact gate.
+
+## Prohibited Shortcuts
+
+- Do not disable, skip, or narrow any step of the toolchain to reach a clean result.
+- Do not add analyzer suppressions, `#pragma warning disable`, `#nullable disable`, or test `[Ignore]` attributes to suppress new findings introduced by the change.
+- Do not report success based on partial or targeted runs alone. Targeted runs are allowed mid-batch, but the final gate requires a full-solution pass.

package/resources/codex-and-agents-customizations/.agents-variants/csharp-legacy/skills/invoke-csharp-engineer/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: invoke-csharp-engineer
+description: Invoke the csharp-typed-engineer worker to design, implement, and verify C# changes within typed repository boundaries. Applies CSharpier -> .NET Analyzers -> Nullable Analysis -> MSTest toolchain, the 1-3 production-file small-path budget, and zero-regression quality gates.
+---
+
+# Implement C# Skill
+
+Legacy C# variant resource for Codex push-down.
+
+This direct-use wrapper delegates C# implementation work to the `csharp-typed-engineer` worker. Use this entry point when a prompt needs a scoped C# change that must stay inside the typed engineer's guardrails.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- The user requests a C# code change, bug fix, refactor, or test addition.
+- Estimated scope fits the small path (1-3 production files plus corresponding tests).
+- The toolchain (CSharpier, .NET Analyzers, Nullable Analysis, MSTest) can be run in the current environment, or the user has explicitly authorized an unverified plan-only response.
+
+If the estimated scope exceeds the small-path budget, this skill defers to the orchestrated flow via `csharp-change-budget-router` instead of proceeding directly.
+
+## Inputs
+
+- Objective statement (what the change must accomplish).
+- Files or entrypoints in scope.
+- Constraints, including public APIs that must be preserved.
+- Optional approved plan. If none is supplied, the worker delegates plan authoring to `atomic_planner` before any edits.
+- Optional budget override in the form `budget: prod=<N>, test=<M>` subject to repo policy compliance.
+
+## Output Paths
+
+- C# source and test files within the approved scope.
+- Baseline evidence under `<FEATURE>/evidence/baseline/<timestamp>/` and post-change evidence under `<FEATURE>/evidence/qa-gates/<timestamp>/` per `evidence-and-timestamp-conventions`.
+- This location is canonical per evidence-and-timestamp-conventions and is not overridable. See `.agents/skills/evidence-and-timestamp-conventions/SKILL.md` for the canonical evidence path authority.
+- Plan artifacts under the active feature folder when the task is feature-scoped.
+
+## Required Reporting Block
+
+The worker must return the following reporting block:
+
+1. Scope (exact file list).
+2. Baseline (CSharpier, .NET Analyzers, Nullable Analysis, MSTest, coverage status).
+3. Plan (design and test strategy).
+4. Diffs (patch-style or full-file replacements).
+5. QA Gate Results (CSharpier, .NET Analyzers, Nullable Analysis, MSTest, and coverage deltas, or clearly marked **unverified**).
+
+## Worker Routing
+
+- Worker: `csharp-typed-engineer`
+
+## Preloaded Contracts
+
+The worker operates under the following preloaded skills and rules:
+
+- `policy-compliance-order`
+- `csharp-change-budget-router`
+- `atomic-plan-contract`
+- `csharp-qa-gate`
+- `acceptance-criteria-tracking`
+- `feature-promotion-lifecycle`
+- `remediation-handoff-atomic-planner`
+- `evidence-and-timestamp-conventions`
+- `.agents/skills/csharp/SKILL.md` (path-scoped for `**/*.cs` and `**/*.csproj`)
+- `AGENTS.md`
+- `AGENTS.md`
+- `AGENTS.md`

package/resources/codex-and-agents-customizations/.codex/agents/orchestrator.toml

@@ -76,6 +76,8 @@ Every agent named above must exist as a native Codex agent under `.codex/agents/
 - Do not rename, back up, or create sidecar checkpoint files.
 - Do not create or edit `${feature-folder}/issue.md`, `${feature-folder}/spec.md`, `${feature-folder}/user-story.md`, or `plan*.md` until lifecycle setup succeeds.
 - Do not persist placeholder lifecycle values such as `NONE`, `TBD`, or empty strings once lifecycle setup begins.
+- After active folder creation and before planner delegation, resolve `${plan-path}` by enumerating existing `${feature-folder}/plan*.md` files in deterministic filename order. If a scaffolded timestamped plan exists, persist and delegate against that exact file. Do not default to `${feature-folder}/plan.md` and do not create a second plan artifact when a plan already exists.
+- For issue #306, the canonical existing plan path is `docs/features/active/2026-07-04-codex-agent-role-config-306/plan.2026-07-04T13-47.md`; reuse that exact file and do not create `docs/features/active/2026-07-04-codex-agent-role-config-306/plan.md`.
 
 ## Checkpoint Persistence
 
@@ -133,17 +135,16 @@ The MCP validator and required CI checks are the hard completion boundary. There
 Do not claim mission completion unless all required delegations completed with receipts and the required orchestration artifacts exist on disk.
 '''
 
-[mcp_servers.drm-copilot]
-enabled = true
-
-[skills.config]
-policy-compliance-order = true
-orchestrate = true
-orchestrator-workflow = true
-feature-promotion-lifecycle = true
-repo-automation-adapter = true
-atomic-plan-contract = true
-acceptance-criteria-tracking = true
-evidence-and-timestamp-conventions = true
-pr-context-artifacts = true
-pr-base-branch-merge-base = true
+[skills]
+config = [
+    { name = "policy-compliance-order", enabled = true },
+    { name = "orchestrate", enabled = true },
+    { name = "orchestrator-workflow", enabled = true },
+    { name = "feature-promotion-lifecycle", enabled = true },
+    { name = "repo-automation-adapter", enabled = true },
+    { name = "atomic-plan-contract", enabled = true },
+    { name = "acceptance-criteria-tracking", enabled = true },
+    { name = "evidence-and-timestamp-conventions", enabled = true },
+    { name = "pr-context-artifacts", enabled = true },
+    { name = "pr-base-branch-merge-base", enabled = true },
+]

package/resources/codex-and-agents-customizations/.codex/config.toml

@@ -84,28 +84,4 @@ command = "pwsh -NoProfile -File .codex/hooks/enforce-orchestration-preimplement
 
 [[hooks.SubagentStop]]
 matcher = "feature-review|feature-reviewer"
-command = "pwsh -NoProfile -File .codex/hooks/validate-feature-review-coverage.ps1"
-
-[permissions.orchestrator-workspace]
-description = "Workspace editing for deterministic orchestration with secret-path deny rules."
-extends = ":workspace"
-
-[permissions.orchestrator-workspace.filesystem]
-glob_scan_max_depth = 4
-
-[permissions.orchestrator-workspace.filesystem.":workspace_roots"]
-"**/.env" = "deny"
-"**/.env.*" = "deny"
-"secrets" = "deny"
-"secrets/**" = "deny"
-
-[permissions.orchestrator-workspace.network]
-enabled = true
-
-[permissions.orchestrator-workspace.network.domains]
-"github.com" = "allow"
-"api.github.com" = "allow"
-"objects.githubusercontent.com" = "allow"
-"registry.npmjs.org" = "allow"
-"pypi.org" = "allow"
-"files.pythonhosted.org" = "allow"
+command = "pwsh -NoProfile -File .codex/hooks/validate-feature-review-coverage.ps1"

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-completion-consistency.ps1

@@ -23,9 +23,11 @@
         variables.feature-folder);
       - a ci_gate object with conclusion == "success" and a non-empty head_sha.
 
-    The block reason names the specific missing evidence so the caller can
-    remediate. When completion is not asserted, the write is allowed
-    (backward compatibility).
+    When completion evidence is missing the hook emits a PreToolUse JSON
+    response with hookSpecificOutput.permissionDecision='deny' and a reason that
+    names the specific missing evidence so the caller can remediate. When
+    completion is not asserted, the write is allowed via
+    hookSpecificOutput.permissionDecision='allow' (backward compatibility).
 
     Edit tool calls supply only old_string/new_string (a partial patch) and
     cannot be reliably validated without the full target file content, so they
@@ -39,6 +41,11 @@
 [CmdletBinding()]
 param()
 
+# Dot-source the shared validation helpers. Guarded so a missing file produces a
+# clear error and so dot-sourcing this hook in tests loads the helpers too.
+$script:CompletionHelpersPath = Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1'
+. $script:CompletionHelpersPath
+
 function ConvertFrom-CheckpointJson {
     <#
     .SYNOPSIS
@@ -53,6 +60,29 @@ function ConvertFrom-CheckpointJson {
     return $Json | ConvertFrom-Json -ErrorAction Stop
 }
 
+function Get-CheckpointFileContent {
+    <#
+    .SYNOPSIS
+        Reads the on-disk checkpoint content for the read-then-validate Edit path.
+    .DESCRIPTION
+        Returns the full file text when the path resolves to a file on disk, or
+        $null when the file does not exist. Tests inject a CheckpointReader
+        scriptblock instead of mocking this function so no temporary files are
+        required.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Path
+    )
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return $null
+    }
+    return Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+}
+
 function Test-IsCheckpointPath {
     [CmdletBinding()]
     [OutputType([bool])]
@@ -149,7 +179,13 @@ function Get-MissingCompletionEvidence {
     param(
         [Parameter(Mandatory)]
         [AllowNull()]
-        $Payload
+        $Payload,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader
     )
 
     $missing = @()
@@ -158,16 +194,17 @@ function Get-MissingCompletionEvidence {
     if (-not $issueNum -and $null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'variables')) {
         $issueNum = Get-CheckpointStringValue -Payload $Payload.variables -Name 'issue-num'
     }
-    if (-not $issueNum) {
-        $missing += 'issue-num'
+    if (-not (Test-IsValidIssueNum -Value $issueNum)) {
+        # Name the offending value so sentinel/placeholder inputs are explicit.
+        $missing += "issue-num value '$issueNum' is not a valid issue number (must be digits-only)"
     }
 
     $featureFolder = Get-CheckpointStringValue -Payload $Payload -Name 'feature-folder'
     if (-not $featureFolder -and $null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'variables')) {
         $featureFolder = Get-CheckpointStringValue -Payload $Payload.variables -Name 'feature-folder'
     }
-    if (-not $featureFolder) {
-        $missing += 'feature-folder'
+    if (-not (Test-IsValidFeatureFolder -Value $featureFolder -FolderExistsCheck $FolderExistsCheck)) {
+        $missing += "feature-folder value '$featureFolder' is not a valid feature folder (must be under docs/features/active/ and exist)"
     }
 
     $ciGate = $null
@@ -188,7 +225,14 @@ function Get-MissingCompletionEvidence {
         }
     }
 
-    if ($issueNum -eq '232') {
+    # PR-gate evidence is required only when the checkpoint's selected route
+    # opts into it via requires_pr_gate in the routing matrix. This replaces the
+    # former issue-number special-casing with route-driven enforcement.
+    $prGateArgs = @{ Payload = $Payload }
+    if ($PSBoundParameters.ContainsKey('RoutingMatrixReader') -and $null -ne $RoutingMatrixReader) {
+        $prGateArgs['RoutingMatrixReader'] = $RoutingMatrixReader
+    }
+    if (Test-RouteRequiresPrGate @prGateArgs) {
         $prGate = $null
         if ($null -ne $Payload -and ($Payload.PSObject.Properties.Name -contains 'pr_gate')) {
             $prGate = $Payload.pr_gate
@@ -213,6 +257,60 @@ function Get-MissingCompletionEvidence {
     return [string[]]$missing
 }
 
+function Resolve-EditedCheckpointContent {
+    <#
+    .SYNOPSIS
+        Returns the patched checkpoint content for an Edit-tool call, or $null
+        when the patch cannot be applied against the on-disk checkpoint.
+    .DESCRIPTION
+        Implements the read-then-validate Edit path. When the tool input carries
+        an old_string (an Edit patch), the on-disk checkpoint is read through the
+        injectable CheckpointReader seam and the old_string -> new_string
+        replacement is applied in memory (no on-disk mutation). Returns $null
+        when there is no old_string, the on-disk file does not exist, or the
+        old_string is not present in the on-disk content, signalling the caller
+        to allow (defer).
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $ToolInput,
+
+        [Parameter(Mandatory)]
+        [scriptblock] $CheckpointReader
+    )
+
+    $oldString = $null
+    if ($null -ne $ToolInput -and ($ToolInput.PSObject.Properties.Name -contains 'old_string')) {
+        $oldString = [string]$ToolInput.old_string
+    }
+    if ([string]::IsNullOrEmpty($oldString)) {
+        return $null
+    }
+
+    $newString = ''
+    if ($ToolInput.PSObject.Properties.Name -contains 'new_string') {
+        $newString = [string]$ToolInput.new_string
+    }
+
+    $onDisk = & $CheckpointReader 'artifacts/orchestration/orchestrator-state.json'
+    if ([string]::IsNullOrEmpty([string]$onDisk)) {
+        # The on-disk checkpoint does not exist (or is empty); cannot patch.
+        return $null
+    }
+
+    $onDiskText = [string]$onDisk
+    if (-not $onDiskText.Contains($oldString)) {
+        # The old_string is not present, so the patch does not apply here.
+        return $null
+    }
+
+    # Apply the patch in memory using a literal (non-regex) replacement.
+    return $onDiskText.Replace($oldString, $newString)
+}
+
 function Invoke-CompletionConsistencyDecision {
     <#
     .SYNOPSIS
@@ -222,11 +320,20 @@ function Invoke-CompletionConsistencyDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
-        [string] $ToolInputRaw
+        [string] $ToolInputRaw,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $FolderExistsCheck = { param($p) Test-Path -LiteralPath $p -PathType Container },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $CheckpointReader = { param($Path) Get-CheckpointFileContent -Path $Path },
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RoutingMatrixReader
     )
 
     if (-not $ToolInputRaw) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     try {
@@ -238,19 +345,25 @@ function Invoke-CompletionConsistencyDecision {
 
     $filePath = $toolInput.file_path
     if (-not $filePath) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     $normalized = $filePath -replace '\\', '/'
     if (-not (Test-IsCheckpointPath -NormalizedPath $normalized)) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    # Write tool: validate the content payload. Edit tool: partial new_string is
-    # not reliable without the full target file content, so allow.
+    # Write tool: validate the content payload directly. Edit tool: no content is
+    # supplied, so read the on-disk checkpoint through the injectable seam and
+    # apply the old_string -> new_string patch in memory (read-then-validate).
     $content = $toolInput.content
     if (-not $content) {
-        return [ordered]@{ decision = 'allow' }
+        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader
+        if (-not $content) {
+            # No content, and the Edit could not be resolved against on-disk
+            # state (missing file or non-matching patch): defer and allow.
+            return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
+        }
     }
 
     try {
@@ -259,26 +372,29 @@ function Invoke-CompletionConsistencyDecision {
     catch {
         # The content itself is not valid JSON. Let downstream tools surface the
         # error rather than blocking with a misleading reason here.
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
     if (-not (Test-CompletionAsserted -Payload $payload)) {
-        return [ordered]@{ decision = 'allow' }
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    $missing = Get-MissingCompletionEvidence -Payload $payload
-    if ($missing.Count -eq 0) {
-        return [ordered]@{ decision = 'allow' }
+    $missingArgs = @{ Payload = $payload; FolderExistsCheck = $FolderExistsCheck }
+    if ($PSBoundParameters.ContainsKey('RoutingMatrixReader') -and $null -ne $RoutingMatrixReader) {
+        $missingArgs['RoutingMatrixReader'] = $RoutingMatrixReader
     }
-
-    $issueContext = ''
-    if ((Get-CheckpointStringValue -Payload $payload -Name 'issue-num') -eq '232') {
-        $issueContext = ' Issue #232 requires pr_gate evidence and current-head ci_gate evidence.'
+    $missing = Get-MissingCompletionEvidence @missingArgs
+    if ($missing.Count -eq 0) {
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
+    $reason = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', '). A completion-asserting checkpoint must include a non-empty issue-num, a non-empty feature-folder, and a ci_gate object with conclusion == 'success' and a non-empty head_sha; routes whose requires_pr_gate is true must also include pr_gate evidence with a matching head_sha. Supply the missing evidence or remove the completion assertion."
     return [ordered]@{
-        decision = 'block'
-        reason   = "COMPLETION_CONSISTENCY_BLOCKED: the checkpoint asserts completion but is missing required completion evidence: $($missing -join ', ').$issueContext A completion-asserting checkpoint must include a non-empty issue-num, a non-empty feature-folder, and a ci_gate object with conclusion == 'success' and a non-empty head_sha. Supply the missing evidence or remove the completion assertion."
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $reason
+        }
     }
 }
 
@@ -295,6 +411,6 @@ catch {
     exit 1
 }
 
-$decision | ConvertTo-Json -Compress | Write-Output
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 
 exit 0