@danmoisan/drm-copilot-mcp 0.0.1 → 0.0.5

package/out/mcp-server.js

@@ -7,7 +7,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "0.0.1",
+  "version": "0.0.5",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",
   "bin": {
-    "drm-copilot-mcp": "./out/mcp-server.js"
+    "drm-copilot-mcp": "out/mcp-server.js"
   },
   "files": [
     "out/mcp-server.js",
@@ -16,17 +16,33 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/drmoisan/drm-copilot.git",
+    "url": "git+https://github.com/drmoisan/drm-copilot.git",
     "directory": "packages/mcp-server"
   },
-  "bugs": { "url": "https://github.com/drmoisan/drm-copilot/issues" },
+  "bugs": {
+    "url": "https://github.com/drmoisan/drm-copilot/issues"
+  },
   "homepage": "https://github.com/drmoisan/drm-copilot#readme",
-  "keywords": ["mcp", "copilot", "claude", "codex", "automation", "workflow", "stdio"],
+  "keywords": [
+    "mcp",
+    "copilot",
+    "claude",
+    "codex",
+    "automation",
+    "workflow",
+    "stdio"
+  ],
   "author": "Dan Moisan",
   "scripts": {
     "build": "node esbuild-mcp-server.cjs",
     "prepack": "node -e \"const{cpSync}=require('fs');cpSync('../../extensions/drm-copilot/resources','./resources',{recursive:true,force:true})\""
   },
+  "overrides": {
+    "fast-uri": "^3.1.2",
+    "hono": "^4.12.25",
+    "ip-address": "^10.2.0",
+    "qs": "^6.15.2"
+  },
   "devDependencies": {
     "esbuild": "^0.28.0"
   },

package/resources/claude-customizations/.claude/agent-memory/orchestrator/MEMORY.md

@@ -1,3 +1,15 @@
-- [VS Code extension location](project_extension_location.md) — the extension lives at `extensions/drm-copilot/`, not at the repo root.
-- [Verify package.json before vsce work](feedback_vsce_verify_package_location.md) — in multi-package repos, never assume the repo root is the publishable extension; locate it first.
-- [Repo root is source of truth for codex bundle](feedback_repo_root_is_source_of_truth.md) — when repo `.codex/`, `.agents/`, `AGENTS.md` differ from bundled copies, update the bundle to match.
+---
+name: orchestrator-memory-index
+description: Index of orchestrator agent memories.
+metadata:
+  type: index
+  scope: repo
+---
+
+- [Policy requirements are not optional gaps](feedback_policy_compliance_not_optional.md) — never frame skipped policy requirements as "known gaps" or defer them; comply before reporting completion.
+- [test-files-count-against-500-cap](feedback_test_files_count_against_500_cap.md) — the 500-line file cap applies to test files too; QA must scan changed/created production AND test files.
+- [every-change-through-lifecycle](feedback_every_change_through_lifecycle.md) — every change, including small tooling changes, goes through issue promotion, an active feature folder, and feature-review before commit.
+- [remediation-plan-em-dash-required](feedback_remediation_plan_em_dash_required.md) — the plan validator rejects any token between "Phase N" and the em-dash; only `### Phase N — <Title>` passes.
+- [branch-base-check-unmerged-pr-deps](feedback_branch_base_check_unmerged_pr_deps.md) — verify required symbols/files exist on the chosen branch base; if they only exist in an open PR, stack or merge first.
+- [potential-to-issue-creates-github-issue](feedback_potential_to_issue_creates_github_issue.md) — potential-to-issue creates the GitHub issue as a side effect; do not also run gh issue create.
+- [small-bug-uses-minor-audit](feedback_small_bug_uses_minor_audit.md) — a ~1-3 production-file bug fix uses the small path with Work Mode minor-audit, not full-bug.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_branch_base_check_unmerged_pr_deps.md

@@ -0,0 +1,16 @@
+---
+name: branch-base-check-unmerged-pr-deps
+description: Before choosing a branch base, verify the plan's required symbols and files exist on that base; if they only exist in an open PR, stack on it or merge it first.
+metadata:
+  type: feedback
+  scope: general
+---
+
+Before choosing a branch base for a new feature, verify that the symbols and files the plan relies on exist on that base. If they only exist in an open PR, either (a) base on that PR's branch (stack), or (b) recommend merging it first.
+
+Check existence with: `git cat-file -e origin/main:<file>`
+Check file overlap with: `git diff --name-only origin/main...<branch>`
+
+**Why:** Branching off the default branch when a required symbol only exists in an unmerged PR forces the implementation to use a fallback or stub, which the reviewer will catch.
+
+**How to apply:** At orchestration start-up, when the plan references files or modules that appear to be part of a separate ongoing feature, run the cat-file check before setting the branch base in the orchestrator state.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_every_change_through_lifecycle.md

@@ -0,0 +1,15 @@
+---
+name: every-change-through-lifecycle
+description: Every change, including small tooling changes, goes through issue promotion, an active feature folder, and feature-review before commit; evidence lives only under the active feature folder.
+metadata:
+  type: feedback
+  scope: general
+---
+
+Every change — including small tooling changes to hooks, skills, rules, or scripts — must go through the full orchestration lifecycle: open an issue (via MCP promotion), create the active feature folder, and pass feature-review before committing. "It's just a small change" is not an exemption.
+
+Evidence may be written ONLY under the active feature folder at `docs/features/active/<date>-<short>-<issue>/evidence/<kind>/`. Any other location (including paths that are not in the forbidden list) is not approved.
+
+**Why:** Bypassing the lifecycle produces changes with no feature folder, which causes engineers to place evidence in unapproved locations and creates review failures requiring full remediation.
+
+**How to apply:** Before any implementation delegation, run promotion (new potential entry -> potential-to-issue -> new active feature folder). Pass the resulting feature folder's `evidence/<kind>/` path as the only permitted evidence sink.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_policy_compliance_not_optional.md

@@ -0,0 +1,18 @@
+---
+name: Policy requirements are not optional gaps
+description: Never frame skipped policy requirements as "known gaps" or defer them to user opt-in; comply before reporting completion.
+type: feedback
+metadata:
+  type: feedback
+  scope: general
+---
+
+When repository policy (`.claude/rules/*.md`, `.github/instructions/*.md`) requires something — tests, coverage, toolchain steps, file-size limits — completing the change without satisfying that requirement is a policy violation, not a "known gap" or "follow-up."
+
+**Why:** The user explicitly rejected framing a missing Pester test as a "known gap" after a new PowerShell script was added. Per `.claude/rules/powershell.md` and `.claude/rules/general-unit-test.md`, new scripts require Pester tests and >=90% coverage. Treating that as optional or deferrable misrepresents the state of the work and pushes compliance burden onto the user.
+
+**How to apply:**
+- Before reporting any code change complete, verify every applicable policy requirement (toolchain steps, tests, coverage, file size, etc.) is satisfied in this same change set.
+- Do not use phrases like "known gap," "follow-up," "if you want I can add tests," or "out of scope" to defer a policy requirement. Either complete the requirement, or stop and report the work as blocked with the specific policy citation.
+- For PowerShell: new `.ps1` files require Pester tests covering positive, negative, and edge paths, with mocks at the wrapper-seam boundary; run format → analyze → Pester and confirm all pass before reporting completion.
+- Asking the user whether to add required tests is not an acceptable substitute for adding them.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_potential_to_issue_creates_github_issue.md

@@ -0,0 +1,13 @@
+---
+name: potential-to-issue-creates-github-issue
+description: The potential-to-issue MCP tool creates the GitHub issue as a side effect; do not also run gh issue create, which produces a duplicate.
+metadata:
+  type: feedback
+  scope: general
+---
+
+The `potential_to_issue` MCP tool creates the GitHub issue as a side effect and returns a summary. The generated `issue.md` already carries the correct `Issue: #N` and `Issue URL` lines. Do NOT run `gh issue create` after `potential_to_issue` — it creates a duplicate issue.
+
+**Why:** Running `gh issue create` after the MCP promotion step produces two issues for the same work item.
+
+**How to apply:** After `potential_to_issue`, read the generated `issue.md` to get the assigned number. Pass that same number to the new-active-feature-folder step via the issue number. If the folder number and the tooling-created GitHub issue number disagree, align to the GitHub number.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_remediation_plan_em_dash_required.md

@@ -0,0 +1,13 @@
+---
+name: remediation-plan-em-dash-required
+description: The plan validator rejects any token between "Phase N" and the em-dash; only the canonical `### Phase N — <Title>` heading passes.
+metadata:
+  type: feedback
+  scope: general
+---
+
+The plan validator (`validate_orchestration_artifacts` with `artifact_type: "plan"`) rejects any phase heading with tokens between "Phase N" and the em-dash. Only the canonical form `### Phase N — <Title>` passes. Parenthetical qualifiers like `(continued)` or `(part 2)` cause the validator to error with "phase heading must match ### Phase N — <Title>" followed by "task appears before a canonical phase heading".
+
+**Why:** Encountered when a planner introduced `### Phase 1 (continued) — <Title>` to group tasks.
+
+**How to apply:** Instruct the planner to use only canonical `### Phase N — <Title>` headings with no parenthetical qualifiers. Either fold task groups under a single phase title or use separate phase numbers. After the planner returns, always run the validator before delegating to executor preflight.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_small_bug_uses_minor_audit.md

@@ -0,0 +1,13 @@
+---
+name: small-bug-uses-minor-audit
+description: A bug fix of roughly 1-3 production files uses the small path with Work Mode minor-audit, not full-bug; requirements and acceptance criteria live in issue.md.
+metadata:
+  type: feedback
+  scope: general
+---
+
+A bug fix whose scope is roughly 1-3 production files must be delivered on the small path with Work Mode `minor-audit`, not `full-bug`. On the small path there is no `spec.md`; requirements (summary, repro, scope, test strategy, and acceptance criteria) live in `issue.md`. The feature-review agent in minor-audit mode reads the `## Acceptance Criteria` section of `issue.md` as the AC source.
+
+**Why:** Using the full-bug path for a small change requires `spec.md`, adds unnecessary overhead, and risks marking a change done without on-disk audit artifacts.
+
+**How to apply:** At change-budget routing, if a bug impacts only 1-3 production files, select small path + minor-audit. Confirm `issue.md` carries an explicit `## Acceptance Criteria` section before delegating to feature-review. Do not create `spec.md` for small-path bugs.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_test_files_count_against_500_cap.md

@@ -0,0 +1,13 @@
+---
+name: test-files-count-against-500-cap
+description: The 500-line file cap applies to test files as well as production files; QA phases must scan all changed/created production AND test files.
+metadata:
+  type: feedback
+  scope: general
+---
+
+The `.claude/rules/general-code-change.md` 500-line file cap applies to test files as well as production files. Only throwaway scripts, raw text fixtures, and Markdown are exempt. When a plan adds substantial tests, Phase 0 baseline and final QA tasks must scan ALL changed/created test files (not only production files) and assert each is <= 500 lines.
+
+**Why:** A plan that adds tests but only size-checks production files can create a remediation cycle when test files cross the cap — the only finding raised during feature-review.
+
+**How to apply:** When briefing the planner for any change that adds tests, require the QA phase to include a line-count assertion across all changed/created production AND test files. If a test file would exceed the cap, split it into a sibling test module before reporting completion.

package/resources/claude-customizations/.claude/agents/atomic-executor.md

@@ -14,13 +14,13 @@ tools:
   - "Bash(npx prettier *)"
   - "Bash(npx eslint *)"
   - "Bash(npx tsc *)"
-  - "Bash(npx jest *)"
+  - "Bash(npx vitest *)"
   - "Bash(pwsh *)"
   - "Bash(git *)"
-  - "mcp__drmCopilotExtension__run_poshqc_format"
-  - "mcp__drmCopilotExtension__run_poshqc_analyze"
-  - "mcp__drmCopilotExtension__run_poshqc_test"
-  - "mcp__drmCopilotExtension__run_poshqc_analyze_autofix"
+  - "mcp__drm-copilot__run_poshqc_format"
+  - "mcp__drm-copilot__run_poshqc_analyze"
+  - "mcp__drm-copilot__run_poshqc_test"
+  - "mcp__drm-copilot__run_poshqc_analyze_autofix"
 skills:
   - policy-compliance-order
   - atomic-plan-contract
@@ -75,8 +75,8 @@ For each task:
 Use the scoped tool patterns for quality gates:
 
 - **Python**: `poetry run black`, `poetry run ruff`, `poetry run pyright`, `poetry run pytest`
-- **TypeScript**: `npx prettier`, `npx eslint`, `npx tsc`, `npx jest`
-- **PowerShell**: MCP server functions (`mcp__drmCopilotExtension__run_poshqc_format`, `mcp__drmCopilotExtension__run_poshqc_analyze`, `mcp__drmCopilotExtension__run_poshqc_test`, `mcp__drmCopilotExtension__run_poshqc_analyze_autofix`)
+- **TypeScript**: `npx prettier`, `npx eslint`, `npx tsc`, `npx vitest`
+- **PowerShell**: MCP server functions (`mcp__drm-copilot__run_poshqc_format`, `mcp__drm-copilot__run_poshqc_analyze`, `mcp__drm-copilot__run_poshqc_test`, `mcp__drm-copilot__run_poshqc_analyze_autofix`)
 - **Git**: `git diff`, `git status`, `git log`
 
 Run toolchain in order: format, lint, type-check, test. Restart from step 1 if any step fails or changes files.

package/resources/claude-customizations/.claude/agents/csharp-typed-engineer.md

@@ -1,11 +1,10 @@
 ---
 name: csharp-typed-engineer
-description: Project-scoped worker that implements and verifies C# changes within typed repository boundaries. Applies the CSharpier -> .NET Analyzers -> Nullable Analysis -> MSTest toolchain, the 1-3 production-file small-path budget, and zero-regression quality gates.
+description: Project-scoped worker that implements and verifies C# changes within typed repository boundaries. Applies the CSharpier -> .NET Analyzers -> Nullable Analysis -> xUnit toolchain, the 1-3 production-file small-path budget, and zero-regression quality gates.
 tools:
   - Read
   - Grep
   - Glob
-  - "Bash(msbuild *)"
   - "Bash(dotnet *)"
 skills:
   - policy-compliance-order
@@ -21,7 +20,7 @@ memory: project
 
 # CSharp Typed Engineer Agent
 
-Senior C# engineer specialized in small cohesive classes and modules, strong typing under nullable reference types, minimal DI seams, and deterministic MSTest coverage. Implement C# changes within the approved scope, preserve typed boundaries, and verify results with the repository C# toolchain.
+Senior C# engineer specialized in small cohesive classes and modules, strong typing under nullable reference types, minimal DI seams, and deterministic xUnit coverage. Implement C# changes within the approved scope, preserve typed boundaries, and verify results with the repository C# toolchain (`dotnet build`, `dotnet test`).
 
 ## Standing Rules
 
@@ -33,8 +32,8 @@ Follow the phased workflow defined by the preloaded skills:
 
 1. **Policy compliance** — apply `policy-compliance-order` to load mandatory repo policies before any change.
 2. **Routing and scope** — apply `csharp-change-budget-router` to estimate scope, select direct vs orchestrator handoff mode, and enforce the 3 production + 3 test per-batch cap.
-3. **Plan and baseline** — apply `atomic-plan-contract` for Phase 0 baseline capture and atomic plan structure. Delegate plan authoring to `atomic_planner` when no plan is supplied. Plans must include the proposed class and module structure, minimal DI seams, MSTest scenario-level test strategy, and Moq mock strategy.
-4. **Implement in batches** — apply the approved plan. After each batch, run targeted analyzer and nullable builds on touched projects plus targeted MSTest, and confirm per-file coverage.
+3. **Plan and baseline** — apply `atomic-plan-contract` for Phase 0 baseline capture and atomic plan structure. Delegate plan authoring to `atomic_planner` when no plan is supplied. Plans must include the proposed class and module structure, minimal DI seams, xUnit scenario-level test strategy, and NSubstitute mock strategy.
+4. **Implement in batches** — apply the approved plan. After each batch, run targeted `dotnet build` analyzer and nullable checks on touched projects plus targeted xUnit tests, and confirm per-file coverage.
 5. **Final QA gate** — apply `csharp-qa-gate` to run the full toolchain, enforce zero-regression deltas against the baseline, and produce the required reporting block before declaring completion.
 6. **Evidence and handoff** — store baseline and post-change evidence per `evidence-and-timestamp-conventions`. Trigger remediation via `remediation-handoff-atomic-planner` when deltas fail.
 

package/resources/claude-customizations/.claude/agents/feature-review.md

@@ -106,9 +106,13 @@ Coverage metrics are mandatory for every language that has changed files in the
 
 ### Coverage Thresholds
 
-- **New code files** (files added in this feature, not previously existing): line coverage must be >= 90%.
-- **Modified files** (files that existed before and were changed): line coverage must show no regression relative to the baseline and must remain >= 80%.
-- **Repo-wide**: line coverage must remain >= 80% for each language.
+Coverage thresholds follow the uniform tier rule (Authoritative Decision #2) defined in `.claude/rules/quality-tiers.md`:
+
+- **New code files** (files added in this feature, not previously existing): line coverage >= 85%, branch coverage >= 75%.
+- **Modified files** (files that existed before and were changed): line coverage >= 85%, branch coverage >= 75%, and no regression on changed lines relative to baseline.
+- **Repo-wide per language**: line coverage >= 85%, branch coverage >= 75%.
+
+Tier-specific lower thresholds are not used.
 
 ### Verification Procedure
 

package/resources/claude-customizations/.claude/agents/orchestrator.md

@@ -6,11 +6,26 @@ tools:
   - Read
   - Grep
   - Glob
+  - Write
+  - Edit
   - "Bash(git *)"
   - "Bash(poetry run *)"
   - "Bash(npx *)"
   - "Bash(pwsh *)"
-  - "mcp__drmCopilotExtension__.*"
+  - "Bash(gh *)"
+  - "mcp__drm-copilot__run_poshqc_format"
+  - "mcp__drm-copilot__run_poshqc_analyze"
+  - "mcp__drm-copilot__run_poshqc_analyze_autofix"
+  - "mcp__drm-copilot__run_poshqc_test"
+  - "mcp__drm-copilot__resolve_execute_hard_lock_prompt"
+  - "mcp__drm-copilot__resolve_atomic_plan_prompt"
+  - "mcp__drm-copilot__collect_pr_context"
+  - "mcp__drm-copilot__new_potential_entry"
+  - "mcp__drm-copilot__new_potential_bug_entry"
+  - "mcp__drm-copilot__potential_to_issue"
+  - "mcp__drm-copilot__new_active_feature_folder"
+  - "mcp__drm-copilot__validate_orchestration_artifacts"
+  - "mcp__drm-copilot__.*"
 skills:
   - policy-compliance-order
   - feature-promotion-lifecycle

package/resources/claude-customizations/.claude/agents/powershell-typed-engineer.md

@@ -6,7 +6,7 @@ tools:
   - Grep
   - Glob
   - "Bash(pwsh *)"
-  - mcp__drmCopilotExtension__.*
+  - mcp__drm-copilot__.*
   - Write
   - Edit
 skills:

package/resources/claude-customizations/.claude/hooks/enforce-checkpoint-monotonic.ps1

@@ -0,0 +1,245 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks Write operations on the orchestrator checkpoint
+    file when completed_steps appear out of declared canonical order.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on Write or Edit operations. The
+    hook activates only when the target file_path is
+    artifacts/orchestration/orchestrator-state.json.
+
+    For Write tool calls, the content field is parsed as JSON and its
+    completed_steps array is validated against the canonical orchestrator
+    workflow step prefixes:
+
+      S0_startup_checks
+      S1_change_budget_estimation
+      S2_research
+      S3_promotion
+      S4_atomic_planning
+      S5_atomic_execution
+      S6_pre_review_commit
+      S7_feature_review
+      S8_create_pr
+      S9_remediation_loop
+      S10_post_pr
+      S12_complete
+
+    Entries that do not match any canonical prefix are treated as informational
+    and ignored. If any pair (i, j) with i < j has a higher canonical index at
+    position i than at position j, the script blocks with a reason listing the
+    offending pair. A non-empty rollback_history array suppresses this check
+    because rollbacks legitimately reorder steps.
+
+    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
+    are allowed by this hook. The next Write call will catch a regression.
+
+.NOTES
+    Compatible with PowerShell 7+. Read-only validation gate.
+#>
+[CmdletBinding()]
+param()
+
+$script:CanonicalStepPrefixes = @(
+    'S0_startup_checks',
+    'S1_change_budget_estimation',
+    'S2_research',
+    'S3_promotion',
+    'S4_atomic_planning',
+    'S5_atomic_execution',
+    'S6_pre_review_commit',
+    'S7_feature_review',
+    'S8_create_pr',
+    'S9_remediation_loop',
+    'S10_post_pr',
+    'S12_complete'
+)
+
+function ConvertFrom-CheckpointJson {
+    <#
+    .SYNOPSIS
+        Wrapper around ConvertFrom-Json for the checkpoint content. Mockable.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Json
+    )
+
+    return $Json | ConvertFrom-Json -ErrorAction Stop
+}
+
+function Get-CanonicalStepIndex {
+    <#
+    .SYNOPSIS
+        Returns the canonical index for a completed_steps entry, or -1 when the
+        entry does not match any canonical prefix.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $StepEntry
+    )
+
+    for ($i = 0; $i -lt $script:CanonicalStepPrefixes.Count; $i++) {
+        $prefix = $script:CanonicalStepPrefixes[$i]
+        if ($StepEntry -eq $prefix -or $StepEntry.StartsWith("$prefix" + '_') -or $StepEntry.StartsWith("$prefix.") -or $StepEntry.StartsWith("$prefix-")) {
+            return $i
+        }
+        # The S3_promotion family of variants (S3_promotion_potential, S3_promotion_issue,
+        # S3_promotion_folder, etc.) is matched by the StartsWith branches above.
+    }
+
+    return -1
+}
+
+function Get-OutOfOrderPair {
+    <#
+    .SYNOPSIS
+        Returns the first pair (entry-at-i, entry-at-j, indices) where i<j but the
+        canonical index at i is greater than the canonical index at j. Non-canonical
+        entries (index -1) are skipped. Returns $null when in order.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyCollection()]
+        [string[]] $CompletedSteps
+    )
+
+    $indexed = @()
+    for ($i = 0; $i -lt $CompletedSteps.Count; $i++) {
+        $idx = Get-CanonicalStepIndex -StepEntry $CompletedSteps[$i]
+        if ($idx -ge 0) {
+            $indexed += [pscustomobject]@{ Position = $i; CanonicalIndex = $idx; Entry = $CompletedSteps[$i] }
+        }
+    }
+
+    for ($a = 0; $a -lt $indexed.Count; $a++) {
+        for ($b = $a + 1; $b -lt $indexed.Count; $b++) {
+            if ($indexed[$a].CanonicalIndex -gt $indexed[$b].CanonicalIndex) {
+                return [pscustomobject]@{
+                    EarlierEntry = $indexed[$a].Entry
+                    EarlierPos   = $indexed[$a].Position
+                    LaterEntry   = $indexed[$b].Entry
+                    LaterPos     = $indexed[$b].Position
+                }
+            }
+        }
+    }
+
+    return $null
+}
+
+function Test-IsCheckpointPath {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $NormalizedPath
+    )
+
+    return $NormalizedPath -match '(^|/)artifacts/orchestration/orchestrator-state\.json$'
+}
+
+function Invoke-CheckpointMonotonicDecision {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        throw "enforce-checkpoint-monotonic hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $filePath = $toolInput.file_path
+    if (-not $filePath) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $normalized = $filePath -replace '\\', '/'
+    if (-not (Test-IsCheckpointPath -NormalizedPath $normalized)) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    # Write tool: validate the content payload. Edit tool: partial new_string is
+    # not reliable without the full target file content, so allow.
+    $content = $toolInput.content
+    if (-not $content) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $payload = ConvertFrom-CheckpointJson -Json $content
+    }
+    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' }
+    }
+
+    if (-not $payload.PSObject.Properties.Name -contains 'completed_steps') {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $steps = @()
+    if ($payload.completed_steps) {
+        foreach ($s in $payload.completed_steps) {
+            $steps += [string]$s
+        }
+    }
+
+    if ($steps.Count -lt 2) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $rollbackHistory = $null
+    if ($payload.PSObject.Properties.Name -contains 'rollback_history') {
+        $rollbackHistory = $payload.rollback_history
+    }
+    if ($rollbackHistory -and @($rollbackHistory).Count -gt 0) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $pair = Get-OutOfOrderPair -CompletedSteps $steps
+    if ($null -eq $pair) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    return [ordered]@{
+        decision = 'block'
+        reason   = "CHECKPOINT_ORDER_BLOCKED: completed_steps lists '$($pair.EarlierEntry)' at position $($pair.EarlierPos) before '$($pair.LaterEntry)' at position $($pair.LaterPos), but the canonical orchestrator workflow requires the later step to follow the earlier one. Reorder completed_steps or, if a rollback occurred, record it in rollback_history."
+    }
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-CheckpointMonotonicDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+}
+catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress | Write-Output
+
+exit 0