@danmoisan/drm-copilot-mcp 1.1.22 → 1.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.1.22",
+  "version": "1.1.23",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

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

@@ -7,7 +7,7 @@ metadata:
 ---
 
 - [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.
+- [test-files-count-against-500-cap](feedback_test_files_count_against_500_cap.md) — the tiered file-size policy 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.

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

@@ -1,13 +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.
+description: The tiered file-size policy (hard limit above 800 lines) 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.
+The tiered file-size policy in `.claude/rules/general-code-change.md` (`## File Size Limit`) 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), assert each is at or below the hard limit, and report any file at or above the advisory tier.
 
-**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.
+**Why:** A plan that adds tests but only size-checks production files can create a remediation cycle when test files cross the hard limit — 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.
+**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 hard limit, split it into a sibling test module before reporting completion.

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

@@ -54,7 +54,7 @@ If the marker is missing or malformed, fail closed to `full-feature`.
 Stop implementation and return to the user when:
 
 - the scope estimate or an in-flight batch would exceed the 3-production-file cap in direct mode,
-- a file is near or would exceed the 500-line limit,
+- a file is above or would exceed the 800-line hard limit of the tiered file-size policy (split it before proceeding; at 500 lines look for a logical split, and at 700 lines split more aggressively),
 - any QA gate delta is non-zero after self-correction,
 - the toolchain cannot be executed in the current environment (mark the change **unverified**),
 - orchestrator handoff mode is requested but the required context package is incomplete,

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

@@ -143,6 +143,14 @@ For each language that has changed files in the feature branch:
 
 The agent does NOT rerun coverage generation. Evidence verification from existing artifacts is the required model.
 
+## File Size Advisory
+
+The tiered file-size policy (`## File Size Limit` in `.claude/rules/general-code-change.md`) sets a 500-line guidance tier, a 700-line advisory tier, and an 800-line hard limit. Measure the logical line count of every added or modified covered file in the branch diff. Covered files have one of the extensions `.py`, `.ps1`, `.psm1`, `.ts`, `.tsx`, `.js`, `.cjs`, `.mjs`, `.cs`, `.sh`, or `.bats` and are not under a build, cache, dependency, virtual-environment, or `docs` directory. A logical line count splits the content on line terminators, and a trailing terminator does not add a line; it equals `@(Get-Content -LiteralPath <path>).Count`. Do not use `wc -l` or `Measure-Object -Line`.
+
+- Report each covered file at or above 700 lines as a non-blocking `Warning` row in the Findings Table of `code-review.<timestamp>.md`, naming the file and its line count. Do not write the Warning to `remediation-inputs.<timestamp>.md`, and do not give it a remediation severity label.
+- Report a covered file above 800 lines that has no entry in `config/file-size-baseline.json`, and any added or increased entry in `config/file-size-baseline.json`, as a blocking policy finding.
+- Produce no finding for the 500-line guidance tier.
+
 ## Evidence Location Invariant
 
 All evidence artifacts this agent produces (baselines, QA gates, regression results, coverage) MUST be written to `<FEATURE>/evidence/<kind>/` as defined in `.claude/skills/evidence-and-timestamp-conventions/SKILL.md`.

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

@@ -91,7 +91,7 @@ For required delegated steps, delegation is mandatory. If a handoff cannot be st
 
 ## PR Creation Delegation
 
-PR creation and PR body edits must be delegated to `Agent(pr-author)`. The orchestrator must not call `gh pr create` or `gh pr edit --body*` directly from the main thread; those commands are blocked by the `enforce-pr-author-skill.ps1` PreToolUse hook unless the `--body-file` argument resolves to a canonical `artifacts/pr_body_<N>.md` path with a matching, verified `artifacts/pr_body_<N>.receipt.json`. The orchestrator first refreshes the PR-context artifact via `mcp__drm-copilot__collect_pr_context`, then runs the orchestrator-state validator against `artifacts/orchestration/orchestrator-state.json --require-pr-creation-ready` and records the result under `pr_author_preflight` (`{status, checked_at, checkpoint_path, validator_command, output_summary}`) before delegating to `Agent(pr-author)`. This is a local enforcement mechanism, not a CI check: `enforce-pr-author-skill.ps1` independently re-validates the same checkpoint inside the PreToolUse hook itself (via an injectable `$Invoker` subprocess seam) and blocks with `ORCHESTRATOR_STATE_PREFLIGHT_FAILED` when it is missing or invalid, closing the bypass path that a CI-only check could never close. `Agent(pr-author)` authors the PR body via the `pr-author` skill, writes `artifacts/pr_body_<N>.md` and the sibling receipt `artifacts/pr_body_<N>.receipt.json` (carrying the lowercase-hex SHA-256 of the body bytes), issues `gh pr create --body-file ...`, and reports the resulting PR URL or PR number. The authoritative handoff contract is `.claude/skills/orchestrate/SKILL.md` `## PR Authoring (pr-author Handoff)`; this section defers to it. The orchestrator records `pr_author_receipt` in the checkpoint.
+PR creation and PR body edits must be delegated to `Agent(pr-author)`. The orchestrator must not call `gh pr create` or `gh pr edit --body*` directly from the main thread; those commands are blocked by the `enforce-pr-author-skill.ps1` PreToolUse hook unless the `--body-file` argument resolves to a canonical `artifacts/pr_body_<N>.md` path with a matching, verified `artifacts/pr_body_<N>.receipt.json`. The orchestrator first refreshes the PR-context artifact via `mcp__drm-copilot__collect_pr_context`, then runs the orchestrator-state validator against `artifacts/orchestration/orchestrator-state.json --require-pr-creation-ready` and records the result under `pr_author_preflight` (`{status, checked_at, checkpoint_path, validator_command, output_summary}`) before delegating to `Agent(pr-author)`. This is a local enforcement mechanism, not a CI check: `enforce-pr-author-skill.ps1` independently re-validates the same checkpoint inside the PreToolUse hook itself (via an injectable `$Invoker` subprocess seam) and blocks with `ORCHESTRATOR_STATE_PREFLIGHT_FAILED` when it is missing or invalid, closing the bypass path that a CI-only check could never close. `Agent(pr-author)` authors the PR body via the `pr-author` skill, writes `artifacts/pr_body_<N>.md` and the sibling receipt `artifacts/pr_body_<N>.receipt.json` (carrying the lowercase-hex SHA-256 of the body bytes), issues `gh pr create --body-file ...`, and reports the resulting PR URL or PR number. The delegation prompt carries the line `Author-asserted autoclose issues: #<issue-num>` from the checkpoint `issue-num`, omitted only when the checkpoint has no `issue-num` or `epic_mode` is true; the skill section named in the next sentence states the rule and its hook enforcement. The authoritative handoff contract is `.claude/skills/orchestrate/SKILL.md` `## PR Authoring (pr-author Handoff)`; this section defers to it. The orchestrator records `pr_author_receipt` in the checkpoint.
 
 ### Remediation Loop Checkpoint Shape
 

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

@@ -1,9 +1,10 @@
 ---
 name: parallel-orchestrator
 model: opus
-description: Execution half of the parallel orchestration surface. Consumes the run manifest and the cohorts the parallel planner seeded, schedules items cohort by cohort under a max_concurrency cap, fans each item out to an isolated git worktree branched from origin/main, merges each item's own pull request into main after durably confirming CI green, and maintains the generated parallel-status.md projection. There is no integration branch and no final integration pull request. Authorized to delegate Agent(orchestrator).
+description: Execution half of the parallel orchestration surface. Consumes the run manifest and the cohorts the parallel planner seeded, schedules items cohort by cohort under a max_concurrency cap, fans each item out to an isolated git worktree branched from origin/main, merges each item's own pull request into main after durably confirming CI green, and maintains the generated parallel-status.md projection. There is no integration branch and no final integration pull request. Authorized to delegate Agent(orchestrator), and Agent(pr-author) for the Run Closing records pull request only.
 tools:
   - "Agent(orchestrator)"
+  - "Agent(pr-author)"
   - Read
   - Grep
   - Glob
@@ -19,6 +20,7 @@ tools:
   - "Bash(bash .claude/lib/bash/abandon-parallel-item.sh*)"
   - "Bash(bash .claude/lib/bash/remove-parallel-item.sh*)"
   - "Bash(bash .claude/lib/bash/mutate-parallel-run.sh*)"
+  - "Bash(bash .claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh*)"
   - "Bash(pwsh -NoProfile -File .claude/lib/project-file-merge/Resolve-MergeableConflict.ps1*)"
   - "Bash(pwsh -NoProfile -NonInteractive -File .claude/lib/parallel-drift/Invoke-ParallelDriftDetection.ps1*)"
   - "Bash(pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-CiGateParser.ps1*)"
@@ -173,7 +175,7 @@ Given a prepared run:
 
 ## Delegation Model
 
-You delegate through exactly one channel: `Agent(orchestrator)`, one delegation per item in the
+You delegate items through exactly one channel: `Agent(orchestrator)`, one delegation per item in the
 manifest, carrying the parallel-mode kickoff prompt defined in the `parallel-orchestrate` skill's
 `## Parallel-Mode Kickoff Parameter` section. Each delegation is spawned with all four of these
 parameters:
@@ -202,9 +204,10 @@ Each child `orchestrator` runs its own route inside that worktree, including its
 `atomic-planner`, `atomic-executor`, `feature-review`, and `pr-author`. You do not delegate to
 those agents directly.
 
-There is no `Agent(pr-author)` channel on this surface: each item's pull request is authored inside
-that item's own child run, and you merge the already-authored, already-green pull request with a
-`gh` command. There are also no upstream-context citation lines to emit: this surface carries no
+The `Agent(pr-author)` channel is used only for the Run Closing records pull request, which lands
+the run's generated documents after every item has merged. Each item's pull request is still
+authored inside that item's own child run, and you merge the already-authored, already-green item
+pull request with a `gh` command. There are also no upstream-context citation lines to emit: this surface carries no
 `depends_on` field, so no item cites another item's output. Ordering exists only as blast-radius
 overlap expressed by the cohort table.
 
@@ -303,10 +306,47 @@ In `closed` mode, do not report completion until:
    confirm that the `headRefOid` value equals that reported `ci_gate.head_sha` and that the item
    reported no pending CI-dependent criteria. You never commit acceptance-criteria check-offs from
    the coordinator root.
+5. `### Run Closing` below has run, and its records pull request is merged or reported as a
+   deferral.
 
 In `open` mode there is no automatic completion. The run is a standing queue and terminates only
 via `/parallel-close`, which is owned by F6 and is not specified here or shipped by this feature. Do
 not synthesize a completion condition for an `open`-mode run.
 
 No completion condition involves a run-level pull request. Each item merges its own pull request
-into `main`, so completion keys on the per-item terminal states above and on nothing else.
+into `main`, so completion keys on the per-item terminal states above and on nothing else. The Run
+Closing records pull request is a bookkeeping pull request for the run's generated documents; it
+is not a run-level integration pull request and merges no item work.
+
+### Run Closing
+
+Run Closing runs once per run, after every non-withdrawn item has `merge_status` of `merged` or
+`worktree_removed` and before you report completion (issue #995). It re-derives state from
+`git worktree list --porcelain`, `git`, and `gh` rather than from the checkpoint, so it is safe to
+repeat: a substep whose outcome already holds is skipped. The full procedure is in the
+`parallel-orchestrate` skill's `### Run Closing` section under `## Worktree Cleanup`; its five
+substeps, in order:
+
+1. **Item worktrees.** For each `merged` item, take the absolute path from
+   `git worktree list --porcelain`, never from the relative `items[].worktree_path`. Run
+   `git worktree unlock <path>` only when the lock reason names the item's own agent, then
+   `git worktree remove <path>` with no force flag. On success set `merge_status: worktree_removed`
+   and `worktree_removed_at`; on refusal leave `merged`, append a `completed_steps` deferral naming
+   the path and refusal reason, and continue.
+2. **Final status.** Regenerate `docs/features/parallel/<slug>/parallel-status.md`.
+3. **Run documents.** Stage the run folder and the promoted lifecycle files created for the run by
+   literal path, with every `git add` and `git commit` pathspec beginning `docs/features/`. The
+   `artifacts/` tree is gitignored, so Run Closing never stages it. Never use `git add -A` or
+   `git add .`, and never stage a
+   `docs/features/active/<item>/` folder. Require that `git diff --name-only origin/main...HEAD`
+   lists only `docs/` paths, otherwise stop and report without forcing or splitting the branch.
+   Push, delegate the pull request to `Agent(pr-author)` with a `branch:` label, merge it with
+   `gh pr merge <PR> --merge`, and confirm the merge by the skill's merge-confirmation procedure.
+4. **Scratch worktrees.** After the records merge is confirmed, run the `cleanup-merged-worktrees`
+   report with `bash .claude/skills/cleanup-merged-worktrees/scripts/cleanup-worktrees.sh`, and run
+   it with `--apply` only when every delete-eligible row is a worktree this run created; otherwise
+   apply nothing and report each scratch worktree as a deferral. Add no hook allow.
+5. **Report.** Report every deferral, with LV1 (removal refused after unlock), LV2 (records pull
+   request still open in the merge queue or `origin/main` absent at merge-gate time), and LV3
+   (records pull request needs manual authoring because `Agent(pr-author)` failed its routing
+   receipt check) as the named deferral cases.

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

@@ -65,7 +65,7 @@ If the marker is missing or malformed, fail closed to `full-feature`.
 Stop implementation and return to the user when:
 
 - the scope estimate exceeds the 3-production-file cap in direct mode,
-- a file is near or would exceed the 500-line limit,
+- a file is above or would exceed the 800-line hard limit of the tiered file-size policy (split it before proceeding; at 500 lines look for a logical split, and at 700 lines split more aggressively),
 - any QA gate delta is non-zero after self-correction,
 - the toolchain cannot be executed in the current environment (mark the change **unverified**),
 - orchestrator handoff mode is requested but the required context package is incomplete,

package/resources/claude-customizations/.claude/agents/pr-author.md

@@ -11,6 +11,7 @@ tools:
   - "Bash(git rev-parse *)"
   - "Bash(gh pr create *)"
   - "Bash(gh pr edit *)"
+  - "Bash(gh pr view *)"
   - "Bash(sha256sum *)"
   - "Bash(date *)"
   - "Write(/artifacts/**)"
@@ -78,9 +79,22 @@ the SHA-256 receipt.
 
 The `enforce-pr-author-command-allowlist.ps1` PreToolUse hook registered in this agent's frontmatter
 evaluates every Bash segment and denies anything outside the allowed forms (`git log`,
-`git rev-parse`, `gh pr create`, `gh pr edit`, and, each as a single command,
+`git rev-parse`, `gh pr create`, `gh pr edit`, exactly
+`gh pr view <N> --json closingIssuesReferences,body`, and, each as a single command,
 `sha256sum artifacts/pr_body_<N>.md` and `date -u +%Y-%m-%dT%H:%M:%SZ`) with
-`PR_AUTHOR_COMMAND_NOT_ALLOWED:`.
+`PR_AUTHOR_COMMAND_NOT_ALLOWED:`. The `Bash(gh pr view *)` tool entry grants the command class;
+the hook narrows it to that one read-only form.
+
+## Closing-Reference Verification
+
+Run `gh pr view <N> --json closingIssuesReferences,body` as a single command (no chaining, no
+extra flags) after every `gh pr create` or `gh pr edit` you issue, where `<N>` is the pull request
+number. Report the closing issue numbers that `closingIssuesReferences` lists, and report any
+mismatch with the author-asserted list: an author-asserted issue that GitHub does not list as
+closing, or a closing issue that no source named. An issue named on the delegation-prompt line
+`Author-asserted autoclose issues: #NNN` is a valid `- Closes #NNN` source even when the PR
+context lists no verified autoclose issues; the `pr-author` skill section
+`## Issue/PR Reference Rules` lists every source.
 
 ## Final Output Requirement
 
@@ -109,14 +123,25 @@ outside that enumeration. Do not invent issue or PR numbers.
 ## Required `--head` on `gh pr create` (issue #687)
 
 Every `gh pr create` command this agent issues MUST carry an explicit
-`--head <branch>` naming the branch the pull request is opened from.
+`--head <branch>` naming the branch the pull request is opened from, for example
+`gh pr create --head <branch> --body-file artifacts/pr_body_<N>.md`.
 
 This is what makes the call's target derivable. `enforce-pr-author-skill.ps1` resolves the
 worktree the call pertains to from the command text, and validates the orchestrator checkpoint
 belonging to that worktree. Without `--head`, `gh pr create` infers its head branch from the
-current checkout and the command carries no signal at all, so the gate denies with
-`TARGET_WORKTREE_NOT_DERIVABLE` rather than validating against whichever checkpoint occupies the
-session root, which in a parallel or epic topology belongs to a different item.
+current checkout and the command carries no signal at all, so the gate falls back to the branch
+checked out in its own working directory (issue #989) and denies with
+`TARGET_WORKTREE_NOT_DERIVABLE` when that checkout is detached or unreadable, rather than
+validating against whichever checkpoint occupies the session root, which in a parallel or epic
+topology belongs to a different item.
 
 Pass `--head` even when the branch is the current one: the gate resolves it to the session root
-and behaves exactly as before, and the command stays correct if it is ever replayed elsewhere.
+and behaves exactly as before, and the command stays correct if it is ever replayed elsewhere.
+
+`gh pr edit` takes no head-branch flag, and --head is not valid for gh pr edit. Name the target of
+an edit in one of two ways:
+
+- Run `gh pr edit <N> --body-file artifacts/pr_body_<N>.md` from the item worktree. The gate
+  derives the branch from that worktree's checkout.
+- When running outside the item worktree, append the shell comment `# branch: <branch>` to the
+  command, and pass the absolute canonical body path beneath the item worktree.

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

@@ -59,7 +59,7 @@ If the marker is missing or malformed, fail closed to `full-feature`.
 Stop implementation and return to the user when:
 
 - the scope estimate exceeds 3 production files in direct mode,
-- a file is near or would exceed the 500-line limit,
+- a file is above or would exceed the 800-line hard limit of the tiered file-size policy (split it before proceeding; at 500 lines look for a logical split, and at 700 lines split more aggressively),
 - any QA gate delta is non-zero after self-correction,
 - the toolchain cannot be executed in the current environment (mark the change **unverified**),
 - policy instructions conflict.

package/resources/claude-customizations/.claude/hooks/enforce-epic-merge-gate-green-ci.ps1

@@ -0,0 +1,325 @@
+<#
+.SYNOPSIS
+    Green-CI standalone merge branch of the merge gate (issue #997).
+
+.DESCRIPTION
+    Dot-sourced by enforce-epic-merge-gate.ps1. Invoke-EpicMergeGateDecision calls
+    Get-EpicMergeGateGreenCiDecision after the parallel allow-branch declines and before the
+    standalone authorization branch, so branches 1 to 3 keep their order and behavior. The
+    branch allows a standalone run (neither an epic child nor a parallel item) to merge its own
+    pull request once its per-feature checkpoint records a green S9 gate for that exact pull
+    request and the live pull-request head still equals the head that CI passed on.
+
+    Stages run cheapest first, and only stage D starts a process:
+      A. The item target resolved to one worktree and its per-feature checkpoint records a green
+         standalone S9 gate bound to the explicit PR number (Test-ChildCheckpointGreenCiRecorded).
+      B. No epic or parallel run checkpoint records the PR number (both run targets NoTarget),
+         and no parallel run checkpoint records the item worktree as a parallel item.
+      C. The command is one structural gh pr merge with no chain, wrapper, inline environment
+         prefix, -R or --repo, /pull/ URL selector, or --auto (Get-DocsOnlyMergeShapeViolation),
+         and carries no --admin flag (declined silently).
+      D. gh pr view <PR> --json headRefOid returns a well-formed head (one bounded call).
+      E. The live head equals ci_gate.head_sha, and --match-head-commit, when present, equals it.
+    Stages A to C decline silently, so every existing deny text is unchanged for a non-green
+    case. A stage D or E decline returns a suffix that the gate appends to its deny reason:
+    GREEN_CI_LIVE_HEAD_UNRESOLVED, GREEN_CI_HEAD_STALE, or GREEN_CI_MATCH_HEAD_MISMATCH.
+
+    Residual parallel-exclusion window: the Parallel mode: true marker lives in the Agent
+    delegation prompt and is not in a Bash PreToolUse payload, so this hook cannot see it. The
+    exclusion is layered and best-effort: a run target recording the PR number (layer 1a), a
+    parallel item recording the worktree path (layer 1b), and child-recorded parallel_mode or
+    parallel_slug keys (layer 2), with skill prose as layer 3. A parallel child whose parent has
+    recorded neither the PR number nor the worktree path, and which omits the layer 2 keys, is
+    not excluded mechanically. Like the standalone authorization record, this is a policy-level
+    control, not a cryptographic one. A push after the stage D lookup can also change the head
+    unless the command passes --match-head-commit; the hook does not require the flag.
+
+.NOTES
+    Compatible with PowerShell 7+. This file dot-sources nothing and imports no module. It
+    calls, at run time only, Invoke-DocsOnlyGhExe and Get-DocsOnlyMergeShapeViolation
+    (hook-docs-only-diff.ps1), Test-CommandLineFlag and Get-CommandLineFlagValue (the shared
+    command parser), and Resolve-WorktreeRunTargetByRecord (WorktreeRunResolution.psm1), all of
+    which the gate loads before it calls this file's functions.
+#>
+
+function Test-EpicMergeGateGreenCiObjectId {
+    <#
+    .SYNOPSIS
+        True when a value is a full lowercase hexadecimal object id of 40 or 64 characters.
+    .PARAMETER Value
+        The candidate value; any non-string value returns $false.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([AllowNull()] $Value)
+
+    return ($Value -is [string]) -and ($Value -cmatch '^[0-9a-f]{40}([0-9a-f]{24})?$')
+}
+
+function Test-EpicMergeGateGreenCiNotParallel {
+    <#
+    .SYNOPSIS
+        True when a parsed per-feature checkpoint carries no epic or parallel marker (pure).
+    .DESCRIPTION
+        epic_mode must be absent, JSON null, or JSON false; epic_mode true belongs to branch 1,
+        and any other value (for example the string "false") fails closed. parallel_mode must
+        be absent, JSON null, or JSON false, and parallel_slug must be absent or blank.
+    .PARAMETER Checkpoint
+        The parsed checkpoint object.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)] $Checkpoint)
+
+    $props = @($Checkpoint.PSObject.Properties.Name)
+    # Each marker key passes only when it is absent, JSON null, or the JSON boolean false.
+    foreach ($marker in @('epic_mode', 'parallel_mode')) {
+        if ($props -ccontains $marker -and $null -ne $Checkpoint.$marker -and
+            -not (($Checkpoint.$marker -is [bool]) -and -not $Checkpoint.$marker)) {
+            return $false
+        }
+    }
+    return -not ($props -ccontains 'parallel_slug' -and -not [string]::IsNullOrWhiteSpace([string]$Checkpoint.parallel_slug))
+}
+
+function Test-ChildCheckpointGreenCiRecorded {
+    <#
+    .SYNOPSIS
+        True when a per-feature checkpoint records a green standalone S9 gate for the PR (pure).
+    .DESCRIPTION
+        Every condition must hold: the command names a PR number above zero; the checkpoint
+        carries no epic or parallel marker (Test-EpicMergeGateGreenCiNotParallel);
+        step9_status is exactly "passed"; ci_gate is an object whose conclusion is exactly
+        "success"; pr_gate.pr_number is a JSON integer equal to the command number, with no
+        fallback to a standalone_merge_authorizations record; ci_gate.head_sha is a lowercase
+        40 or 64 character object id; and pr_gate.head_sha, when present and not null, equals
+        ci_gate.head_sha. Comparisons are ordinal, so a case variant fails closed.
+    .PARAMETER Checkpoint
+        Parsed per-feature checkpoint, or $null when absent or unreadable.
+    .PARAMETER CommandPrNumber
+        The explicit PR number the command names, or $null for a bare command.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $Checkpoint,
+        [AllowNull()][Nullable[int]] $CommandPrNumber
+    )
+
+    if ($null -eq $CommandPrNumber -or $CommandPrNumber -le 0) { return $false }
+    if ($Checkpoint -isnot [System.Management.Automation.PSCustomObject]) { return $false }
+    if (-not (Test-EpicMergeGateGreenCiNotParallel -Checkpoint $Checkpoint)) { return $false }
+    if (-not (($Checkpoint.step9_status -is [string]) -and ($Checkpoint.step9_status -ceq 'passed'))) { return $false }
+
+    $ciGate = $Checkpoint.ci_gate
+    if ($ciGate -isnot [System.Management.Automation.PSCustomObject]) { return $false }
+    if (-not (($ciGate.conclusion -is [string]) -and ($ciGate.conclusion -ceq 'success'))) { return $false }
+    if (-not (Test-EpicMergeGateGreenCiObjectId -Value $ciGate.head_sha)) { return $false }
+
+    # The PR binding comes from pr_gate alone; an authorization record must not stand in for a CI result.
+    $prGate = $Checkpoint.pr_gate
+    if ($prGate -isnot [System.Management.Automation.PSCustomObject]) { return $false }
+    $recordedNumber = $prGate.pr_number
+    if (-not (($recordedNumber -is [int]) -or ($recordedNumber -is [long])) -or [long]$recordedNumber -ne $CommandPrNumber) { return $false }
+
+    # A recorded PR head must agree with the head CI passed on; null or absent means not recorded.
+    if (@($prGate.PSObject.Properties.Name) -ccontains 'head_sha' -and $null -ne $prGate.head_sha) {
+        return [string]::Equals([string]$prGate.head_sha, [string]$ciGate.head_sha, [System.StringComparison]::Ordinal)
+    }
+    return $true
+}
+
+function Get-EpicMergeGateLivePrHeadSha {
+    <#
+    .SYNOPSIS
+        Return the live head commit of a pull request, or $null on any failure (the live-head seam).
+    .DESCRIPTION
+        Runs gh pr view <PR> --json headRefOid through Invoke-DocsOnlyGhExe, which bounds the
+        call at 7 seconds and never throws. Returns the head only for exit code 0, output that
+        parses to a JSON object, and a well-formed lowercase object id; a non-zero exit
+        (including 124 for a timeout and -1 for a missing root), unparseable output, and a
+        malformed head all return $null. Tests mock this function by name.
+    .PARAMETER PrNumber
+        The pull request number.
+    .PARAMETER WorktreeRoot
+        The directory gh runs in.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][int] $PrNumber,
+        [AllowNull()][AllowEmptyString()][string] $WorktreeRoot
+    )
+
+    $lookup = Invoke-DocsOnlyGhExe -WorkingRoot $WorktreeRoot -GhArgs @('pr', 'view', [string]$PrNumber, '--json', 'headRefOid')
+    if ($null -eq $lookup -or $lookup.ExitCode -ne 0) { return $null }
+    try {
+        $pr = ConvertFrom-Json -InputObject ([string]$lookup.Output) -ErrorAction Stop
+    }
+    catch {
+        # Unreadable gh output is a lookup failure; the gate fails closed on $null.
+        return $null
+    }
+    if ($pr -isnot [System.Management.Automation.PSCustomObject]) { return $null }
+    if (-not (Test-EpicMergeGateGreenCiObjectId -Value $pr.headRefOid)) { return $null }
+    return [string]$pr.headRefOid
+}
+
+function Test-EpicMergeGateGreenCiHeadAgreement {
+    <#
+    .SYNOPSIS
+        True when the live head equals ci_gate.head_sha and any pinned head equals the live head (pure).
+    .PARAMETER Checkpoint
+        Parsed per-feature checkpoint carrying ci_gate.head_sha.
+    .PARAMETER LiveHeadSha
+        The live pull-request head, or $null when unresolved.
+    .PARAMETER PinnedHeadSha
+        The --match-head-commit value, or $null when the flag is absent. An empty string means
+        the flag is present without a usable value and fails closed.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $Checkpoint,
+        [AllowNull()] $LiveHeadSha,
+        [AllowNull()] $PinnedHeadSha
+    )
+
+    if ($null -eq $Checkpoint -or $LiveHeadSha -isnot [string] -or $null -eq $Checkpoint.ci_gate) { return $false }
+    if (-not [string]::Equals($LiveHeadSha, [string]$Checkpoint.ci_gate.head_sha, [System.StringComparison]::Ordinal)) { return $false }
+    if ($null -ne $PinnedHeadSha -and -not [string]::Equals([string]$PinnedHeadSha, $LiveHeadSha, [System.StringComparison]::Ordinal)) { return $false }
+    return $true
+}
+
+function Resolve-EpicMergeGateParallelItemByWorktree {
+    <#
+    .SYNOPSIS
+        Resolve the parallel run whose items[] record a worktree path (layer 1b seam).
+    .DESCRIPTION
+        A one-call seam over Resolve-WorktreeRunTargetByRecord so tests can mock it. Status
+        NoTarget means no parallel checkpoint records the worktree as a parallel item.
+    .PARAMETER WorktreeRoot
+        The item worktree whose per-feature checkpoint was read.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject (the worktree-resolution target result).
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param([AllowNull()][AllowEmptyString()][string] $WorktreeRoot)
+
+    return Resolve-WorktreeRunTargetByRecord -Kind parallel -RecordField worktree_path -Value $WorktreeRoot -SessionRoot (Get-Location).Path
+}
+
+function Test-EpicMergeGateGreenCiNoRunRecord {
+    <#
+    .SYNOPSIS
+        True when no epic or parallel run checkpoint records the PR or the item worktree (stage B).
+    .DESCRIPTION
+        Both run targets must have status NoTarget; a resolved or Ambiguous target declines.
+        The worktree lookup declines on any status other than NoTarget, on $null, and on a
+        thrown error, because an unreadable parallel record cannot prove the item is standalone.
+    .PARAMETER EpicTarget
+        The epic run target resolved for the PR number.
+    .PARAMETER ParallelTarget
+        The parallel run target resolved for the PR number.
+    .PARAMETER WorktreeRoot
+        The item worktree root.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()] $EpicTarget,
+        [AllowNull()] $ParallelTarget,
+        [AllowNull()][AllowEmptyString()][string] $WorktreeRoot
+    )
+
+    foreach ($target in @($EpicTarget, $ParallelTarget)) {
+        if ($null -eq $target -or [string]$target.Status -cne 'NoTarget') { return $false }
+    }
+    try {
+        $byWorktree = Resolve-EpicMergeGateParallelItemByWorktree -WorktreeRoot $WorktreeRoot
+    }
+    catch {
+        # A failed lookup cannot show the worktree is not a parallel item, so the stage declines.
+        return $false
+    }
+    return ($null -ne $byWorktree -and [string]$byWorktree.Status -ceq 'NoTarget')
+}
+
+function Get-EpicMergeGateGreenCiDecision {
+    <#
+    .SYNOPSIS
+        Evaluate stages A to E of the green-CI branch and return Allowed and a deny suffix.
+        Stage C declines silently a command that carries --admin.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .PARAMETER CommandPrNumber
+        The explicit PR number, or $null for a bare command.
+    .PARAMETER ChildCheckpoint
+        The parsed per-feature checkpoint the gate read, or $null.
+    .PARAMETER ItemTarget
+        The item target, or $null for a bare command.
+    .PARAMETER EpicTarget
+        The epic run target, or $null for a bare command.
+    .PARAMETER ParallelTarget
+        The parallel run target, or $null for a bare command.
+    .PARAMETER SessionRoot
+        The session worktree root, where gh runs.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary with Allowed and Suffix.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $CommandText,
+        [AllowNull()][Nullable[int]] $CommandPrNumber,
+        [AllowNull()] $ChildCheckpoint,
+        [AllowNull()] $ItemTarget,
+        [AllowNull()] $EpicTarget,
+        [AllowNull()] $ParallelTarget,
+        [AllowNull()][AllowEmptyString()][string] $SessionRoot
+    )
+
+    $silent = [ordered]@{ Allowed = $false; Suffix = '' }
+    # Stage A: one resolved item worktree whose checkpoint records a green S9 gate for this PR.
+    if ($null -eq $ItemTarget -or @('SessionRoot', 'OtherWorktree') -cnotcontains [string]$ItemTarget.Status) { return $silent }
+    if (-not (Test-ChildCheckpointGreenCiRecorded -Checkpoint $ChildCheckpoint -CommandPrNumber $CommandPrNumber)) { return $silent }
+    # Stage B: no epic or parallel run records the PR or the item worktree.
+    if (-not (Test-EpicMergeGateGreenCiNoRunRecord -EpicTarget $EpicTarget -ParallelTarget $ParallelTarget -WorktreeRoot ([string]$ItemTarget.WorktreeRoot))) { return $silent }
+    # Stage C: a single structural gh pr merge naming the PR, with no repository or auto override.
+    if ($null -ne (Get-DocsOnlyMergeShapeViolation -CommandText $CommandText -PrNumber $CommandPrNumber)) { return $silent }
+    # --admin bypasses branch protection, so a green checkpoint must not authorize it.
+    if (Test-CommandLineFlag -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge') -FlagName '--admin') { return $silent }
+
+    # Stage D: the only process call, made after every pure stage passed.
+    $liveHead = Get-EpicMergeGateLivePrHeadSha -PrNumber $CommandPrNumber -WorktreeRoot $SessionRoot
+    if ($null -eq $liveHead) {
+        return [ordered]@{ Allowed = $false; Suffix = ' (green-CI merge not applied: GREEN_CI_LIVE_HEAD_UNRESOLVED)' }
+    }
+
+    # Stage E: a stale checkpoint head is reported before a mismatched --match-head-commit pin.
+    $subcommandPath = @('pr', 'merge')
+    $pinned = $null
+    if (Test-CommandLineFlag -CommandText $CommandText -CommandWord 'gh' -SubcommandPath $subcommandPath -FlagName '--match-head-commit') {
+        $pinned = [string](Get-CommandLineFlagValue -CommandText $CommandText -CommandWord 'gh' -SubcommandPath $subcommandPath -FlagName '--match-head-commit')
+    }
+    if (Test-EpicMergeGateGreenCiHeadAgreement -Checkpoint $ChildCheckpoint -LiveHeadSha $liveHead -PinnedHeadSha $pinned) {
+        return [ordered]@{ Allowed = $true; Suffix = '' }
+    }
+    if (-not (Test-EpicMergeGateGreenCiHeadAgreement -Checkpoint $ChildCheckpoint -LiveHeadSha $liveHead -PinnedHeadSha $null)) {
+        return [ordered]@{ Allowed = $false; Suffix = ' (green-CI merge not applied: GREEN_CI_HEAD_STALE)' }
+    }
+    return [ordered]@{ Allowed = $false; Suffix = ' (green-CI merge not applied: GREEN_CI_MATCH_HEAD_MISMATCH)' }
+}