@danmoisan/drm-copilot-mcp 1.1.19 → 1.1.20

package/out/mcp-server.js

@@ -22913,7 +22913,7 @@ var BASE_REWRITE_RULES = [
   },
   {
     pattern: /Return the finalized plan for validation-only preflight through `atomic-executor` and preserve the same target file path across revision loops\. Do not claim nested worker delegation from within planner execution\./g,
-    replacement: 'Before reporting completion, explicitly spawn the `atomic-executor` subagent for validation-only preflight. The delegated prompt MUST include the exact directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY`.\n\n- `atomic-executor` MUST return exactly one of:\n  - `PREFLIGHT: ALL CLEAR`\n  - `PREFLIGHT: REVISIONS REQUIRED`\n- Treat executor preflight findings as binding plan defects.\n- If preflight returns `PREFLIGHT: REVISIONS REQUIRED`, revise the same target plan file using the executor\'s precise plan delta and re-run preflight.\n- Reuse the same target plan file for every preflight revision iteration in the same planning cycle.\n- If the required `atomic-executor` handoff cannot be started or completed, stop and report blocked state; do not self-approve the plan.\n- Before reporting completion, the target plan MUST pass the `validate_orchestration_artifacts` MCP tool with `artifact_type: "plan"` and `artifact_path: <plan-path>`.\n\nDo not claim nested worker delegation from within planner execution.',
+    replacement: 'Before reporting completion, explicitly spawn the `atomic-executor` subagent for validation-only preflight. The delegated prompt MUST include the exact directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY`.\n\n- `atomic-executor` MUST return exactly one of:\n  - `PREFLIGHT: ALL CLEAR`\n  - `PREFLIGHT: REVISIONS REQUIRED`\n- Treat executor preflight findings as binding plan defects.\n- If preflight returns `PREFLIGHT: REVISIONS REQUIRED`, revise the same target plan file once using the executor\'s precise plan delta and its full `PREFLIGHT-DEFECT:` list, and run one confirming preflight. Preflight is single-pass: trivial defects are fixed in place by the executor, and a plan returns to the planner at most once; a second substantive result halts with `blocked_reason: "validator_failed"`.\n- Reuse the same target plan file for the single permitted preflight revision in the same planning cycle.\n- If the required `atomic-executor` handoff cannot be started or completed, stop and report blocked state; do not self-approve the plan.\n- Before reporting completion, the target plan MUST pass the `validate_orchestration_artifacts` MCP tool with `artifact_type: "plan"` and `artifact_path: <plan-path>`.\n\nDo not claim nested worker delegation from within planner execution.',
     description: "Expand the Claude atomic-planner preflight shorthand into the strict Codex atomic-executor handoff contract."
   },
   {
@@ -28957,6 +28957,166 @@ function extractPlanCommands(text2) {
   return commands;
 }
 
+// ../../extensions/drm-copilot/src/lib/validate/plan-gate-document.ts
+var G11_SEVERITY = "blocking";
+var G12_SEVERITY = "blocking";
+var G13_SEVERITY = "blocking";
+var PLAN_TASK_GUIDELINE = 40;
+var PLAN_LINE_GUIDELINE = 400;
+var G11_PROSE_PATTERN = String.raw`\b[Ll]ines?[ \t]+[0-9]+`;
+var G11_PATH_PATTERN = String.raw`[A-Za-z0-9_./-]+\.[A-Za-z][A-Za-z0-9]{0,5}:[0-9]+`;
+var G11_ANCHOR_PATTERN = String.raw`#L[0-9]+`;
+var G12_SHA_PATTERN = String.raw`\b[0-9a-f]{7,40}\b`;
+var G13_TASK_PATTERN = String.raw`^- \[[ xX]\] \[P[0-9]+-T[0-9]+\] `;
+var INLINE_CODE_PATTERN = "`[^`]*`";
+var FENCE_RE2 = /^\s*```/;
+var PROSE_RE = new RegExp(G11_PROSE_PATTERN, "g");
+var PATH_RE = new RegExp(G11_PATH_PATTERN, "g");
+var ANCHOR_RE = new RegExp(G11_ANCHOR_PATTERN, "g");
+var SHA_RE = new RegExp(G12_SHA_PATTERN, "g");
+var TASK_RE = new RegExp(G13_TASK_PATTERN);
+var INLINE_CODE_RE = new RegExp(INLINE_CODE_PATTERN, "g");
+var WHITESPACE_RE = new RegExp(`^${PLAN_WHITESPACE_CLASS}$`);
+var JUSTIFICATION_HEADING_RE = /^##[ \t]+Size Justification[ \t]*$/;
+var SECTION_END_RE = /^#{1,2}(?:[ \t]|$)/;
+var HEADING_RE = /^#{1,6}(?:[ \t]|$)/;
+var DIGITS = "0123456789";
+var HEX_LETTERS = "abcdef";
+var SHA_BEFORE_REJECT = "-_.";
+var SHA_AFTER_REJECT = "-_";
+function unfencedLines(text2) {
+  const result = [];
+  let inFence = false;
+  for (const [index, line] of splitPlanLines(text2).entries()) {
+    if (FENCE_RE2.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (!inFence) {
+      result.push([index + 1, line]);
+    }
+  }
+  return result;
+}
+function maskInlineCode(line) {
+  return line.replace(INLINE_CODE_RE, (span) => " ".repeat(span.length));
+}
+function isWhitespace(character) {
+  return character !== void 0 && WHITESPACE_RE.test(character);
+}
+function enclosingToken(line, start, end) {
+  let left = start;
+  while (left > 0 && !isWhitespace(line[left - 1])) {
+    left -= 1;
+  }
+  let right = end;
+  while (right < line.length && !isWhitespace(line[right])) {
+    right += 1;
+  }
+  return line.slice(left, right);
+}
+function lineCitations(text2) {
+  const findings = [];
+  for (const [lineNumber, line] of unfencedLines(text2)) {
+    for (const match of maskInlineCode(line).matchAll(PROSE_RE)) {
+      findings.push([lineNumber, match[0]]);
+    }
+    for (const match of line.matchAll(PATH_RE)) {
+      const token = enclosingToken(
+        line,
+        match.index,
+        match.index + match[0].length
+      );
+      if (!token.includes("://")) {
+        findings.push([lineNumber, match[0]]);
+      }
+    }
+    for (const match of line.matchAll(ANCHOR_RE)) {
+      findings.push([lineNumber, match[0]]);
+    }
+  }
+  return findings;
+}
+function isShaCandidate(line, start, end) {
+  const token = line.slice(start, end);
+  if (![...token].some((character) => DIGITS.includes(character))) {
+    return false;
+  }
+  if (![...token].some((character) => HEX_LETTERS.includes(character))) {
+    return false;
+  }
+  const before = start > 0 ? line.charAt(start - 1) : "";
+  if (before !== "" && SHA_BEFORE_REJECT.includes(before)) {
+    return false;
+  }
+  const after = end < line.length ? line.charAt(end) : "";
+  return !(after !== "" && SHA_AFTER_REJECT.includes(after));
+}
+function shaCitations(text2) {
+  const findings = [];
+  for (const [lineNumber, line] of unfencedLines(text2)) {
+    for (const match of line.matchAll(SHA_RE)) {
+      if (isShaCandidate(line, match.index, match.index + match[0].length)) {
+        findings.push([lineNumber, match[0]]);
+      }
+    }
+  }
+  return findings;
+}
+function hasSizeJustification(text2) {
+  let inSection = false;
+  for (const [, line] of unfencedLines(text2)) {
+    if (JUSTIFICATION_HEADING_RE.test(line)) {
+      inSection = true;
+      continue;
+    }
+    if (!inSection) {
+      continue;
+    }
+    if (SECTION_END_RE.test(line)) {
+      inSection = false;
+      continue;
+    }
+    if (normalizePlanWhitespace(line) !== "" && !HEADING_RE.test(line)) {
+      return true;
+    }
+  }
+  return false;
+}
+function planSize(text2) {
+  const tasks = unfencedLines(text2).filter(
+    ([, line]) => TASK_RE.test(line)
+  ).length;
+  return [tasks, splitPlanLines(text2).length];
+}
+function lineCitationMessage(lineNumber, value) {
+  return `Line ${String(lineNumber)}: line-number citation \`${value}\` anchors on a position that moves when main moves; cite the symbol, heading, or test name instead.`;
+}
+function shaCitationMessage(lineNumber, value) {
+  return `Line ${String(lineNumber)}: commit-SHA citation \`${value}\` names a commit that goes stale when main moves; cite the branch, ref name, or merge base derivation instead.`;
+}
+function planSizeMessage(tasks, lines) {
+  return `Line 1: plan size \`${String(tasks)} tasks, ${String(lines)} lines\` exceeds the guideline of ${String(PLAN_TASK_GUIDELINE)} tasks or ${String(PLAN_LINE_GUIDELINE)} lines and carries no \`## Size Justification\` section; split the item or state why the size is necessary.`;
+}
+function channelFor(report, severity) {
+  return severity === "blocking" ? report.blocking : report.warnings;
+}
+function evaluateDocumentGates(report, text2) {
+  const g11 = channelFor(report, G11_SEVERITY);
+  for (const [lineNumber, value] of lineCitations(text2)) {
+    g11.push(lineCitationMessage(lineNumber, value));
+  }
+  const g12 = channelFor(report, G12_SEVERITY);
+  for (const [lineNumber, value] of shaCitations(text2)) {
+    g12.push(shaCitationMessage(lineNumber, value));
+  }
+  const [tasks, lines] = planSize(text2);
+  const overGuideline = tasks > PLAN_TASK_GUIDELINE || lines > PLAN_LINE_GUIDELINE;
+  if (overGuideline && !hasSizeJustification(text2)) {
+    channelFor(report, G13_SEVERITY).push(planSizeMessage(tasks, lines));
+  }
+}
+
 // ../../extensions/drm-copilot/src/lib/validate/plan-gate-rules.ts
 function emptyPlanGateReport() {
   return { blocking: [], warnings: [] };
@@ -29344,7 +29504,7 @@ var G10_SEVERITY = "blocking";
 var BACKTICK = "`";
 var SCRATCH_DEFINITION_PATTERN = String.raw`(?:^|[^A-Za-z0-9_<>$/.-])${BACKTICK}?SCRATCH${BACKTICK}?(?:\*\*)?[ \t]*(?:means\b|:=|=|:|is (?:the|a|an)\b|resolves to\b|abbreviates\b|denotes\b|refers to\b|stands for\b)`;
 var SCRATCH_NAMESPACE_PATTERN = String.raw`issue-(?:<issue-num>|[0-9]+)`;
-var FENCE_RE2 = /^\s*```/;
+var FENCE_RE3 = /^\s*```/;
 var DEFINITION_RE = new RegExp(SCRATCH_DEFINITION_PATTERN);
 var NAMESPACE_RE = new RegExp(SCRATCH_NAMESPACE_PATTERN);
 var LEADING_WHITESPACE_RE = new RegExp(`^${PLAN_WHITESPACE_CLASS}`);
@@ -29352,7 +29512,7 @@ function continuesLogicalLine(line) {
   if (normalizePlanWhitespace(line) === "" || !LEADING_WHITESPACE_RE.test(line)) {
     return false;
   }
-  return !FENCE_RE2.test(line);
+  return !FENCE_RE3.test(line);
 }
 function isBareDefinition(logical) {
   const match = DEFINITION_RE.exec(logical);
@@ -29380,7 +29540,7 @@ function bareScratchDefinitions(text2) {
       recordIfBare(findings, pending);
       pending = null;
     }
-    if (FENCE_RE2.test(line)) {
+    if (FENCE_RE3.test(line)) {
       inFence = !inFence;
       continue;
     }
@@ -29504,6 +29664,7 @@ function evaluatePlanGates(text2, context) {
     evaluateLiteralRules(report, text2, commands, context);
   }
   evaluateScratchGate(report, text2);
+  evaluateDocumentGates(report, text2);
   return report;
 }
 

package/package.json

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

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

@@ -22,11 +22,13 @@ tools:
   - "mcp__drm-copilot__run_poshqc_analyze"
   - "mcp__drm-copilot__run_poshqc_test"
   - "mcp__drm-copilot__run_poshqc_analyze_autofix"
+  - "mcp__drm-copilot__validate_orchestration_artifacts"
 skills:
   - policy-compliance-order
   - atomic-plan-contract
   - evidence-and-timestamp-conventions
   - acceptance-criteria-tracking
+  - execution-environment
 memory: project
 hooks:
   SubagentStop:
@@ -95,19 +97,28 @@ Concurrent child runs in one session share one session scratchpad, so every scra
 
 ## Preflight Validation
 
-When receiving a plan with directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY`, perform only format and structure validation. Return exactly one of:
+A run is a preflight run when its delegation prompt carries the directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY`. The preflight directive belongs in the delegation prompt, never in a plan file. A directive line left in a plan file does not make an execution run a preflight run. Preflight follows `### Single-Pass Preflight` in the `atomic-plan-contract` skill:
 
-- `PREFLIGHT: ALL CLEAR`
-- `PREFLIGHT: REVISIONS REQUIRED` (with precise plan delta)
+- **Review the entire plan in one pass.** Check every phase, task, and prose region; do not stop at the first defect.
+- **Classify every defect.** Trivial defects (stale or misspelled anchors, citation corrections including G11 and G12 findings, typos, literal formatting that does not change what is asserted, evidence filename spelling) are fixed in place. Substantive defects (missing or extra tasks, wrong file set or design, an acceptance criterion without a task, an assertion change, ordering, scope) are returned.
+- **Fix in task text only.** Edit task text and plan preamble in the same plan file. Never add, remove, or reorder tasks. Record every fix in `<FEATURE>/evidence/other/preflight-fixes.<timestamp>.md`.
+- **Return exactly one signal**, `PREFLIGHT: ALL CLEAR` or `PREFLIGHT: REVISIONS REQUIRED`, followed by one `CONVERGENCE:` line and then one line per defect:
+  - `PREFLIGHT-FIX: <task id or heading> | <defect class> | <change made>`
+  - `PREFLIGHT-DEFECT: <task id or heading> | <defect class> | <required change>`
+  - `preflight-fix-record: <path>` when at least one fix was made.
+- `PREFLIGHT: ALL CLEAR` carries no `PREFLIGHT-DEFECT:` line; `PREFLIGHT: REVISIONS REQUIRED` carries at least one and lists every substantive defect found. A plan returns to the planner at most once; do not request or expect a further round.
+- Validate the plan with `mcp__drm-copilot__validate_orchestration_artifacts` (`artifact_type: "plan"`), or with `poetry run python -m scripts.dev_tools.validate_orchestration_artifacts plan <path>` when branch-current rules are required (see the `execution-environment` skill).
 
 ## Blocking Protocol
 
-Blocking is permitted only during preflight validation (before `[P0-T1]`). When preflight-blocked:
+Blocking is permitted only during preflight validation (before `[P0-T1]`). This includes a combined preflight-and-execute run of a proportionate remediation cycle: the run first performs single-pass preflight, fixes trivial defects in place, and stops before `[P0-T1]` only when a substantive defect remains. When preflight-blocked:
 
 1. State: `BLOCKED at preflight (before [P0-T1])`.
 2. Provide a short, concrete explanation of why.
-3. Provide a plan delta (exact new or modified task text) that `atomic-planner` can apply, preserving the plan's `[P#-T#]` ID conventions.
-4. Request that `atomic-planner` produce the corrected plan or that the user explicitly approve the delta.
+3. Provide a plan delta (exact new or modified task text) that `atomic-planner` can apply, preserving the plan's `[P#-T#]` ID conventions, with one `PREFLIGHT-DEFECT:` line per substantive defect.
+4. Request that `atomic-planner` produce the corrected plan or that the user explicitly approve the delta. Leave every task unchecked.
+
+Report the blocked state with the uppercase `BLOCKED` token: the SubagentStop hook matches only that token, so lowercase or title-case "blocked" prose is not read as a blocked claim.
 
 After execution begins, do not block. Continue to completion using allowed micro-actions within the current task.
 

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

@@ -10,10 +10,12 @@ tools:
   - "Edit(artifacts/**)"
   - "Write(docs/**)"
   - "Write(artifacts/**)"
+  - "mcp__drm-copilot__validate_orchestration_artifacts"
 skills:
   - policy-compliance-order
   - atomic-plan-contract
   - evidence-and-timestamp-conventions
+  - execution-environment
 memory: project
 hooks:
   SubagentStop:
@@ -45,7 +47,9 @@ Generate plans using the atomic plan contract defined in the `atomic-plan-contra
 - Task IDs: `- [ ] [P#-T#] <description>`
 - Sequential task numbering within each phase
 - Phase 0: baseline capture (repo-policy reading tasks + language-specific toolchain baselines)
-- Final phase: full QA loop for each applicable language
+- Final phase: full QA loop for each applicable language, ending with the self-review task that writes `<FEATURE>/evidence/qa-gates/self-review.<timestamp>.md`
+
+Every plan is design-level per `## Design-Level Plan Contract (Mandatory)` in the `atomic-plan-contract` skill: tasks name files, symbols, behavior, tests, and acceptance; anchors are symbols, headings, or test names, never line numbers or commit SHAs; literals appear only where they are the asserted value; tool routes and launchers are not restated because the `execution-environment` skill owns them; and a plan above 40 tasks or 400 lines carries a `## Size Justification` section. Every plan carries a `## Pre-Mortem` section with one bullet for each of `Review checklists`, `Coverage`, `Mirror parity`, `File size`, `Test isolation`, `CI-only behavior`, and `Evidence`; the planner SubagentStop hook blocks a plan without it.
 
 ## Requirements
 
@@ -67,10 +71,14 @@ Concurrent child runs in one session share one session scratchpad, so every plan
 
 ## Preflight Validation
 
-Before handing the plan to executor preflight, return the exact bounded line record defined in `atomic-plan-contract`, starting with `PLANNER-INTERNAL-REVIEW: PASS` and ending with the required `PREFLIGHT:` signal. The bounded record must include exactly one passing `CITATION-TO-TREE`, `AC-TRACEABILITY`, and `SCOPE-BOUNDARY` declaration; one or more current-tree `CITATION: <repository-relative path> | <locator>` records; one complete unique `AC-INVENTORY:`; one complete `AC-MAPPING: <ID> | IMPLEMENTATION: <identifier> | TESTS: <identifier> | EVIDENCE: <identifier>` for every and only inventory ID; and exactly one `UNRESOLVED-GAPS: NONE`. A missing, duplicate, malformed, failed, blocked, or out-of-bounds record declaration requires `SELF-REVIEW: BLOCKED` and stops handoff.
+Before handing the plan to executor preflight, return the exact bounded line record defined in `atomic-plan-contract`, starting with `PLANNER-INTERNAL-REVIEW: PASS` and ending with the required `PREFLIGHT:` signal. The bounded record must include exactly one passing `CITATION-TO-TREE`, `AC-TRACEABILITY`, and `SCOPE-BOUNDARY` declaration; one or more current-tree `CITATION: <repository-relative path> | <symbol, heading, or test name>` records, none of which uses a line-reference locator; one complete unique `AC-INVENTORY:`; one complete `AC-MAPPING: <ID> | IMPLEMENTATION: <identifier> | TESTS: <identifier> | EVIDENCE: <identifier>` for every and only inventory ID; and exactly one `UNRESOLVED-GAPS: NONE`. A missing, duplicate, malformed, failed, blocked, or out-of-bounds record declaration requires `SELF-REVIEW: BLOCKED` and stops handoff.
+
+Before handoff, validate the plan with `mcp__drm-copilot__validate_orchestration_artifacts` (`artifact_type: "plan"`) and correct every finding the validator reports. The installed validator applies only the rules of the installed extension release, as the `execution-environment` skill states.
 
 Return the finalized plan for validation-only preflight through `atomic-executor` and preserve the same target file path across revision loops. Do not claim nested worker delegation from within planner execution.
 
+Preflight is single-pass (`### Single-Pass Preflight` in `atomic-plan-contract`): the preflight executor applies the rule "Review the entire plan in one pass", fixes trivial defects in place, and returns substantive defects, and a plan returns to the planner at most once. Trivial defects are stale anchors, citation corrections, typos, and formatting that does not change an assertion; Substantive defects are missing or extra tasks, a wrong file set or design, an uncovered acceptance criterion, an assertion change, ordering, and scope. The preflight directive belongs in the delegation prompt, never in a plan file. The preflight return carries `PREFLIGHT-FIX: <task id or heading> | <defect class> | <change made>` lines for fixes, `PREFLIGHT-DEFECT: <task id or heading> | <defect class> | <required change>` lines for returned defects, and `preflight-fix-record: <path>` when a fix was made. When it returns, it carries the full `PREFLIGHT-DEFECT:` list; apply every listed change in one revision of the same file. If the preflight that follows still reports a substantive defect, the orchestrator halts with `blocked_reason: "validator_failed"` rather than requesting another revision.
+
 ## Output
 
 Write the finalized plan to the target path provided by the calling agent. Return the plan path and final preflight signal.

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

@@ -14,6 +14,8 @@ tools:
   - "Edit(artifacts/orchestration/**)"
   - "Bash(git *)"
   - "Bash(gh *)"
+  - "Bash(pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-CiGateParser.ps1*)"
+  - "Bash(pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1*)"
   - "mcp__drm-copilot__collect_pr_context"
   - "mcp__drm-copilot__validate_orchestration_artifacts"
 skills:
@@ -161,6 +163,9 @@ Do not report completion until:
 
 1. Every feature in the manifest has `merge_status: "merged"` or `"worktree_removed"`.
 2. The final integration-to-`main` PR has merged (`epic_merge_pr.merge_commit_sha` recorded).
+   `epic_merge_pr.merge_commit_sha` is recorded only after the merge is confirmed by polling and
+   ancestry check, because under a merge queue on `main` `gh pr merge` can return before the
+   merge happens (issue #952).
 3. `docs/features/epics/<epic-slug>/epic-status.md` reflects the completed state.
 4. The epic checkpoint passes `validate_epic_orchestrator_state_text` with
    `require_complete=True` (no wave-barrier violations, all features merged/removed).

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

@@ -33,6 +33,7 @@ skills:
   - atomic-plan-contract
   - acceptance-criteria-tracking
   - evidence-and-timestamp-conventions
+  - execution-environment
 memory: project
 hooks:
   SubagentStop:
@@ -126,6 +127,8 @@ Malformed-cycle rules:
 - R10: each well-formed outcome's `verdict` must equal the verdict derived from its findings' classes.
 - R11: `opened_by_review`, when present, must be a non-negative integer that indexes an object entry of `review_outcomes` whose `verdict` is `REMEDIATION_REQUIRED`.
 
+Remediation mode lives in the inputs file, not in the checkpoint: each `remediation-inputs.<entry-ts>.md` carries exactly one line `Remediation-Mode: proportionate` or `Remediation-Mode: design`, so no checkpoint field is added. A cycle is proportionate when every `autonomous` finding can be fixed without changing a spec acceptance criterion, a public interface, or the item's file inventory beyond the files already in the branch diff plus their tests and mirrors; CI-failure findings are normally proportionate. A proportionate cycle runs one `atomic-planner` delegation and one `atomic-executor` delegation that performs single-pass preflight with in-place trivial fixes and then executes; the orchestrator records `preflight: {iterations: 1, final_status: "clear"}` before `execution_status`, which satisfies the malformed-cycle rule above. When that preflight finds a substantive defect, the executor stops with `BLOCKED at preflight (before [P0-T1])` and no checked task, and the cycle converts to design mode for one planner revision.
+
 Cycle-aware `next_step` uses the form `remediation.cycle_N.{plan,preflight,execute,reaudit,exit_check}`, where `N` is `completed_attempts + 1` (the active cycle number) and the sub-step names the current position in the loop; `current_cycle` remains a record position in `cycles[]`.
 
 ### CI Monitoring and Post-PR Remediation
@@ -154,7 +157,7 @@ Each cycle produces exactly five artifacts:
 
 ### Preflight Sub-State Semantics
 
-`preflight.final_status` is one of `{clear, changes_requested, pending}`. A `changes_requested` status routes back to `atomic-planner` for plan revision. An `execution_status` in `{in_progress, complete, failed}` recorded while `final_status != clear` is malformed. `preflight.iterations` counts the number of preflight passes performed in the cycle.
+`preflight.final_status` is one of `{clear, changes_requested, pending}`, extended by `blocked_preflight_iteration_limit` as defined in the remediation-handoff skill. A `changes_requested` status routes back to `atomic-planner` for plan revision at most once per cycle, carrying the full `PREFLIGHT-DEFECT:` list; when the confirming preflight still reports a substantive defect, the orchestrator records `blocked_preflight_iteration_limit` and halts the cycle. An `execution_status` in `{in_progress, complete, failed}` recorded while `final_status != clear` is malformed. `preflight.iterations` counts the number of preflight passes performed in the cycle; trivial defects fixed in place by the preflight executor do not add a pass.
 
 ### Scope-change Rule
 

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

@@ -22,6 +22,7 @@ tools:
   - "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*)"
+  - "Bash(pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1*)"
   - "Bash(dotnet tool restore*)"
   - "Bash(dotnet csharpier check *)"
   - "Bash(dotnet build *)"
@@ -287,6 +288,9 @@ In `closed` mode, do not report completion until:
 
 1. Every non-withdrawn item has `merge_status` of `merged` or `worktree_removed`, each durably
    confirmed by `git` and `gh` rather than by an in-memory notification.
+   A `merged` value is recorded only after the merge is confirmed by polling and ancestry check
+   (step 3 of the `parallel-orchestrate` skill's `## Per-Item Merge to Main (Merge-on-Green)`),
+   because under a merge queue `gh pr merge` exits 0 before the merge happens.
 2. `docs/features/parallel/<slug>/parallel-status.md` has been regenerated a final time and
    reflects the completed state.
 3. The parallel checkpoint passes validation with `require_complete` (the F3 completion gate for

package/resources/claude-customizations/.claude/agents/task-researcher.md

@@ -9,7 +9,9 @@ tools:
   - WebFetch
   - "Write(/docs/features/**/research/**)"
   - "Write(/docs/research/**)"
+skills:
   - evidence-and-timestamp-conventions
+  - execution-environment
 memory: project
 hooks:
   SubagentStop:
@@ -71,6 +73,12 @@ The orchestrator resolves which root to use from whether an active feature folde
 
 - Propose a test strategy consistent with repository policy without writing test code.
 
+### 6. Pre-Mortem
+
+- Feature-associated research (a research path under `docs/features/`) MUST carry a `## Pre-Mortem` section with one bullet beginning with each of the seven labels `Review checklists`, `Coverage`, `Mirror parity`, `File size`, `Test isolation`, `CI-only behavior`, and `Evidence`. Each bullet states how the next review or CI run could fail on that dimension and the mitigation the plan must carry; a label that does not apply is written as "not applicable" followed by the reason.
+- One-off research under `docs/research/` is exempt.
+- `.claude/hooks/validate-task-researcher-output.ps1` blocks feature research without a complete section. The `execution-environment` skill states the CI shape, contract tests, and isolation checks the section accounts for.
+
 ## Constraints
 
 - Write only to the orchestrator-supplied research path under `docs/features/<feature>/research/` (feature-associated) or `docs/research/` (one-off). Do not modify source code or configurations.

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

@@ -0,0 +1,190 @@
+<#
+.SYNOPSIS
+    Scope predicate and pull-request selector reader for the epic merge gate (issue #952).
+.DESCRIPTION
+    Dot-sourced by enforce-epic-merge-gate.ps1 on both runtimes; this file is byte-identical in
+    .claude/hooks and .codex/hooks. Under a merge queue every gh pr merge spelling (--merge, -m,
+    --squash, -s, --rebase, -r, --auto, --admin, or no method flag) adds the pull request to the
+    queue, and the gh api mutations enqueuePullRequest, enablePullRequestAutoMerge, and
+    mergePullRequest and the REST pulls/<n>/merge endpoint also reach the base branch. All of
+    them are in scope. A gh pr merge whose only action flag is --disable-auto is out of scope.
+
+    Pure string logic only: no disk, process, network, clock, or environment access. The file
+    dot-sources and imports nothing; it consumes Get-CommandLineInvocation and
+    Get-CommandLineStructuralMatch, which the gate loads from hook-command-invocation.ps1 first.
+
+    Known limitation (issue #952 code review CR-5): the gh api scope reads the command text
+    only. A GraphQL mutation supplied from a file (gh api graphql -F query=@mutation.graphql,
+    or gh api --input payload.json) is not visible to this text-based scope and is not gated.
+#>
+
+# gh pr merge flags that perform or schedule a merge. Any of them keeps a command in scope even
+# when it also carries --disable-auto.
+$script:EpicMergeGateActionFlags = @('--merge', '-m', '--squash', '-s', '--rebase', '-r', '--auto', '--admin')
+
+# gh pr merge flags, including the inherited --repo, that consume the following token as a value.
+$script:EpicMergeGateValueFlags = @('-b', '--body', '-F', '--body-file', '-t', '--subject', '-A', '--author-email', '--match-head-commit', '-R', '--repo')
+
+# GraphQL mutations that merge, enqueue, or schedule the merge of a pull request.
+$script:EpicMergeGateMutationNames = @('enqueuePullRequest', 'enablePullRequestAutoMerge', 'mergePullRequest')
+
+# The REST merge endpoint path; group 1 is the pull-request number.
+$script:EpicMergeGateRestMergePattern = '(?:^|/)pulls/(\d+)/merge(?:$|[^\w-])'
+
+function Get-EpicMergeGateFlagName {
+    <#
+    .SYNOPSIS
+        Return the flag name of a dash-led token without any '=value' suffix.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Token)
+
+    $split = $Token.IndexOf('=')
+    if ($split -gt 0) { return $Token.Substring(0, $split) }
+    return $Token
+}
+
+function ConvertFrom-EpicMergeGateSelector {
+    <#
+    .SYNOPSIS
+        Convert a gh pr merge selector to a pull-request number, or $null.
+    .DESCRIPTION
+        Accepts an all-digit selector or a URL whose path ends in /pull/<n>. A branch-name
+        selector carries no number and yields $null.
+    .OUTPUTS
+        System.Nullable[int]
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Selector)
+
+    $digits = $null
+    if ($Selector -match '^\d+$') {
+        $digits = $Selector
+    } elseif ($Selector -match '/pull/(\d+)/?(?:[?#].*)?$') {
+        $digits = $Matches[1]
+    }
+    $number = 0
+    if ($null -ne $digits -and [int]::TryParse($digits, [ref] $number)) { return $number }
+    return $null
+}
+
+function Test-EpicMergeGateDisableAutoOnly {
+    <#
+    .SYNOPSIS
+        Report whether a Structural gh pr merge match carries --disable-auto and no action flag.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][pscustomobject] $Match)
+
+    $tokens = [string[]]@($Match.Segment.Tokens)
+    $hasDisableAuto = $false
+    for ($index = $Match.OperandIndex; $index -lt $tokens.Count; $index++) {
+        $name = Get-EpicMergeGateFlagName -Token $tokens[$index]
+        if ($script:EpicMergeGateActionFlags -ccontains $name) { return $false }
+        if ($name -ceq '--disable-auto') { $hasDisableAuto = $true }
+    }
+    return $hasDisableAuto
+}
+
+function Test-EpicMergeGateApiMutationText {
+    <#
+    .SYNOPSIS
+        Report whether gh api text names a merge or enqueue mutation or the REST merge endpoint.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $Text)
+
+    if ([string]::IsNullOrEmpty($Text)) { return $false }
+    foreach ($name in $script:EpicMergeGateMutationNames) {
+        if ($Text.IndexOf($name, [System.StringComparison]::OrdinalIgnoreCase) -ge 0) { return $true }
+    }
+    return [regex]::IsMatch($Text, $script:EpicMergeGateRestMergePattern)
+}
+
+function Test-EpicMergeGateCommandInScope {
+    <#
+    .SYNOPSIS
+        Report whether a command line is a gated merge or enqueue action (issue #952).
+    .DESCRIPTION
+        True for any gh pr merge match, Structural or Indeterminate, unless the match is Structural
+        and its only action flag is --disable-auto; true for any gh api match whose tokens name a
+        merge or enqueue mutation or a pulls/<n>/merge path. Text that only mentions these words
+        produces no match and stays out of scope. An Indeterminate gh pr merge match stays in scope
+        (fail closed).
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $CommandText)
+
+    foreach ($match in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge'))) {
+        if ($match.Status -ne 'Structural' -or -not (Test-EpicMergeGateDisableAutoOnly -Match $match)) { return $true }
+    }
+    foreach ($match in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('api'))) {
+        if (Test-EpicMergeGateApiMutationText -Text (@($match.Segment.Tokens) -join ' ')) { return $true }
+    }
+    return $false
+}
+
+function Get-EpicMergeGateSelectorPrNumber {
+    <#
+    .SYNOPSIS
+        Resolve the pull-request number of a gated merge or enqueue command, or $null.
+    .DESCRIPTION
+        For gh pr merge, only the first Structural match is read. Value flags are skipped with
+        their values, other flags are skipped, an equals-joined --merge=<digits> yields its
+        digits (an equals-joined value that is not a number is skipped like any other flag),
+        and the first non-flag token (or the token after a bare '--') is the selector.
+        For gh api, the number comes from a pulls/<n>/merge token. Any other command yields
+        $null, which the gate handles through its no-number branches.
+    .OUTPUTS
+        System.Nullable[int]
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory)][AllowEmptyString()][AllowNull()][string] $CommandText)
+
+    $match = Get-CommandLineStructuralMatch -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('pr', 'merge')
+    if ($null -ne $match) {
+        $tokens = [string[]]@($match.Segment.Tokens)
+        $index = $match.OperandIndex
+        while ($index -lt $tokens.Count) {
+            $token = $tokens[$index]
+            if ($token -ceq '--') {
+                if ($index + 1 -lt $tokens.Count) { return ConvertFrom-EpicMergeGateSelector -Selector $tokens[$index + 1] }
+                return $null
+            }
+            if ($token.StartsWith('-') -and $token.Length -gt 1) {
+                $name = Get-EpicMergeGateFlagName -Token $token
+                if ($name -ceq '--merge' -and $token.Length -gt $name.Length) {
+                    $equalsNumber = ConvertFrom-EpicMergeGateSelector -Selector $token.Substring($name.Length + 1)
+                    if ($null -ne $equalsNumber) { return $equalsNumber }
+                }
+                $index += if ($script:EpicMergeGateValueFlags -ccontains $token) { 2 } else { 1 }
+                continue
+            }
+            return ConvertFrom-EpicMergeGateSelector -Selector $token
+        }
+        return $null
+    }
+
+    foreach ($apiMatch in @(Get-CommandLineInvocation -CommandText $CommandText -CommandWord 'gh' -SubcommandPath @('api'))) {
+        foreach ($token in @($apiMatch.Segment.Tokens)) {
+            $rest = [regex]::Match([string]$token, $script:EpicMergeGateRestMergePattern)
+            $number = 0
+            if ($rest.Success -and [int]::TryParse($rest.Groups[1].Value, [ref] $number)) { return $number }
+        }
+    }
+    return $null
+}