@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

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

@@ -21,6 +21,22 @@ Use this skill when:
 - Task IDs must match their phase and be sequential per phase.
 - Plans must pass the `mcp__drm-copilot__validate_orchestration_artifacts` MCP tool with `artifact_type: "plan"` and `artifact_path: <plan-path>` before they can be reported as approved.
 
+## Design-Level Plan Contract (Mandatory)
+
+A plan is a design-level document: it states what changes and how the change is proven, not a transcript of commands. Every task names the files it creates or edits, the symbols, headings, or tests it touches, the behavior the change produces, the tests that prove that behavior, and an acceptance condition stated as an observable outcome.
+
+Rules:
+
+- **Anchors are symbols, headings, or test names.** A plan never cites a line number, a `path:line` locator, a `#L` anchor, or a commit SHA, because each goes stale when `main` moves (validator rules G11 and G12). Scope comparisons name the merge-base derivation of `origin/main` and `HEAD`, not a commit.
+- **Literals only where they are the asserted value.** A plan quotes a literal when an acceptance condition asserts that exact value. It does not quote file contents, command output, or prose for context.
+- **Tool routes are not restated.** Tool routes, launchers, wrapper scripts, command-text restrictions, the batch budget, hook context, and CI shape are owned by the `execution-environment` skill. A plan references that skill instead of restating its content.
+- **Changed existing behavior names its asserting tests.** A task that changes the observable behavior of an existing function, script, fixture, or test stub (its signature, argv, output, exit status, or the files it writes) names every existing test that asserts that behavior and states each test's disposition: unchanged because it is unaffected, or updated, with the reason for the update. The tests are found by searching the test tree for the symbol, the file name, and the asserted output. A test that asserts the current behavior and is outside the task's file set fails once the change lands, and the plan's own acceptance condition then cannot be met. The planner's adversarial self-review includes this search for every task that changes existing behavior.
+- **Size guideline.** A plan stays within 40 canonical tasks and 400 physical lines. A plan that needs more carries a `## Size Justification` section with at least one line stating why the size is necessary (validator rule G13). Files produced by one generator run count as one generator task.
+- **Pre-Mortem.** Every plan carries 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 plan prevents that failure class, or states "not applicable" followed by the reason. The `Test isolation` bullet names the isolation runs the plan performs: a seeded shuffled Jest run with the seed recorded, a reversed-order run of the new or changed Python test modules, and a seeded shuffled file-order run of the touched Pester suites with at least three seeds, each seed recorded. The `Mirror parity` bullet also covers the execution-environment brief: a plan that alters a fact the brief states (for example, it adds or renames a CI job, changes a required status context, a tool route, or a batch-budget rule) includes a task that updates the brief in the same change, in all six byte-identical copies, and the bullet names that task. Without that task the brief states a superseded fact once the change lands, which breaks the brief's own maintenance rule. The planner SubagentStop hook blocks a plan without a complete section.
+- **Final-phase self-review.** The final phase of every plan contains a self-review task that walks the policy-audit, code-review, and feature-audit templates under `docs/features/templates/policy_audit/` against the branch diff from the merge base and writes `<FEATURE>/evidence/qa-gates/self-review.<timestamp>.md` with one PASS, FAIL, or N/A row per checklist item. A FAIL row is fixed and the QA loop is re-run before the self-review is rewritten; the plan does not complete with a FAIL row.
+
+This section takes precedence over the literal-quoting rules of `## Wrap-Tolerant Assertion Authoring (Mandatory)`: those rules govern the asserted value of an acceptance condition, not context.
+
 ## Short-Path Minimal Plan Contract
 
 When orchestration selects short path, a minimal plan is still mandatory and must include these blocks:
@@ -104,6 +120,10 @@ For short-path/minimal-audit plans, Phase 0 evidence is incomplete unless both a
 
 `Output Summary:` is mandatory for each command-step artifact and must concisely summarize the essential result signal (for example: pass/fail status, key counts, coverage headline, or primary diagnostic).
 
+## Evidence Filename Timestamps in Plans
+
+Plans name evidence artifacts `<name>.<timestamp>.md` and never fix a plan-time stamp in an evidence filename. An acceptance condition identifies a consumed evidence artifact by the derivation in `evidence-and-timestamp-conventions` (`### Evidence Filename Timestamp`): the lexicographically greatest file matching `<name>.*.md`, not a pre-stamped literal path. This section governs artifact paths only: asserted search tokens remain concrete.
+
 ## Coverage Evidence Contract (Mandatory when policy requires coverage)
 
 For any language in scope where repository policy requires coverage validation:
@@ -141,38 +161,52 @@ Any regression test task expected to fail must be tagged with `[expect-fail]` an
 
 ## Planner Adversarial Self-Review (Mandatory)
 
-Before any plan handoff, `atomic-planner` MUST complete one explicit adversarial self-review pass over every fact, assumption, and line or file citation the plan relies on. The pass is required on initial authoring and on every revision-delta round. A revision round is not exempt because it changed only part of the plan: the citations the revision touched describe the tree as it stands after the revision, and no earlier pass observed that state.
+Before any plan handoff, `atomic-planner` MUST complete one explicit adversarial self-review pass over every fact, assumption, and file, symbol, heading, or test citation the plan relies on. The pass is required on initial authoring and on every revision-delta round. A revision round is not exempt because it changed only part of the plan: the citations the revision touched describe the tree as it stands after the revision, and no earlier pass observed that state.
 
 Rules:
 
-- **Re-derive every citation in this pass.** Any line, file, test, or assertion that the planner's own edit touched, added, or removed in the current authoring or revision pass MUST be re-derived directly against current repository state in that same pass. The prohibited source is a citation carried forward from an earlier round, including one the planner itself verified in a prior round: that earlier verification observed the tree before the intervening edits, so it is evidence about a superseded state rather than about the state the plan now asserts.
-- **Re-check the sibling region.** The self-review MUST re-check the sibling lines, tests, and assertions that sit in the same file or region as any edited citation. The failure mechanism is sibling invalidation: a fix to one line can invalidate an assumption baked into a sibling line or test that a prior round's citation did not cover, so a pass that verifies only the edited line leaves the invalidated sibling unreported and it surfaces as a defect on a later round.
+- **Re-derive every citation in this pass.** Any file, symbol, heading, test, or assertion that the planner's own edit touched, added, or removed in the current authoring or revision pass MUST be re-derived directly against current repository state in that same pass. The prohibited source is a citation carried forward from an earlier round, including one the planner itself verified in a prior round: that earlier verification observed the tree before the intervening edits, so it is evidence about a superseded state rather than about the state the plan now asserts.
+- **Re-check the sibling region.** The self-review MUST re-check the sibling symbols, tests, and assertions that sit in the same file or section as any edited citation. The failure mechanism is sibling invalidation: a fix to one citation can invalidate an assumption baked into a sibling symbol or test that a prior round's citation did not cover, so a pass that verifies only the edited line leaves the invalidated sibling unreported and it surfaces as a defect on a later round.
 
 Declaration requirement. Every plan handoff MUST carry exactly one of these two signal lines, written in the directive-line form already used elsewhere in this contract:
 
-- `SELF-REVIEW: RE-DERIVED THIS PASS` — the adversarial self-review pass completed in this pass. This signal MUST be followed by an enumeration of the citations re-derived in that pass, one entry per citation, each naming the file and the line, test, or identifier that was re-derived. A signal carrying no enumeration is not a completed declaration.
+- `SELF-REVIEW: RE-DERIVED THIS PASS` — the adversarial self-review pass completed in this pass. This signal MUST be followed by an enumeration of the citations re-derived in that pass, one entry per citation, each naming the file and the symbol, heading, or test name that was re-derived. A signal carrying no enumeration is not a completed declaration.
 - `SELF-REVIEW: BLOCKED` — the pass could not be completed. This signal halts the handoff. It does not permit a self-approved plan: the planner reports the blocking reason and waits for the caller rather than proceeding to hand off an unverified plan.
 
 ## Preflight Validation (Planner ↔ Executor)
 
 ### Planner Internal Review Record
 
-Before executor preflight, the planner must emit exactly one bounded record between `PLANNER-INTERNAL-REVIEW: PASS` and the existing `PREFLIGHT:` signal. The record requires exactly one passing declaration each for `CITATION-TO-TREE`, `AC-TRACEABILITY`, and `SCOPE-BOUNDARY`; one or more `CITATION: <repository-relative path> | <nonblank locator>` entries; exactly one `AC-INVENTORY:` declaration containing unique nonblank IDs; one `AC-MAPPING: <ID> | IMPLEMENTATION: <nonblank> | TESTS: <nonblank> | EVIDENCE: <nonblank>` for every and only inventory ID; and exactly one `UNRESOLVED-GAPS: NONE`. Missing, blank, duplicate, non-passing, out-of-bounds, or inventory/mapping-disagreeing declarations block handoff. If review cannot pass, emit `SELF-REVIEW: BLOCKED` and do not hand the plan to preflight. `SELF-REVIEW: RE-DERIVED THIS PASS` remains distinct and does not replace executor clearance.
+Before executor preflight, the planner must emit exactly one bounded record between `PLANNER-INTERNAL-REVIEW: PASS` and the existing `PREFLIGHT:` signal. The record requires exactly one passing declaration each for `CITATION-TO-TREE`, `AC-TRACEABILITY`, and `SCOPE-BOUNDARY`; one or more `CITATION: <repository-relative path> | <symbol, heading, or test name>` entries, whose locator is never a line reference (bare digits, `L` plus digits, `line` plus digits, or a path followed by a colon and digits); exactly one `AC-INVENTORY:` declaration containing unique nonblank IDs; one `AC-MAPPING: <ID> | IMPLEMENTATION: <nonblank> | TESTS: <nonblank> | EVIDENCE: <nonblank>` for every and only inventory ID; and exactly one `UNRESOLVED-GAPS: NONE`. Missing, blank, duplicate, non-passing, out-of-bounds, or inventory/mapping-disagreeing declarations block handoff. If review cannot pass, emit `SELF-REVIEW: BLOCKED` and do not hand the plan to preflight. `SELF-REVIEW: RE-DERIVED THIS PASS` remains distinct and does not replace executor clearance.
 
 When validating or handing off plans for execution:
-- Use the directive line: `DIRECTIVE: PREFLIGHT VALIDATION ONLY`.
+- Put the directive line `DIRECTIVE: PREFLIGHT VALIDATION ONLY` in the delegation prompt. The preflight directive belongs in the delegation prompt, never in a plan file. A plan file that still carries the line from an earlier contract is harmless, because the executor SubagentStop hook classifies a run from the delegation prompt recorded in the subagent transcript.
 - Require one of the exact signals:
 	- `PREFLIGHT: ALL CLEAR`
 	- `PREFLIGHT: REVISIONS REQUIRED`
-- If revisions are required, provide a precise plan delta and repeat validation until all clear.
 - If the required planner ↔ executor handoff cannot be started or completed, stop and report blocked state; do not self-approve the plan.
 
-Review depth and reporting rules:
+### Single-Pass Preflight
+
+Preflight completes in one pass. The preflight executor fixes trivial defects in place and returns only substantive defects, and a plan returns to the planner at most once.
 
 - **Review the entire plan in one pass.** Under `DIRECTIVE: PREFLIGHT VALIDATION ONLY`, `atomic-executor` MUST continue checking every remaining phase, task, and prose region after finding an initial defect. Stopping at the first defect is prohibited: the unchecked remainder holds defects that the same pass could have reported, and each one that is left unreported becomes an additional round.
-- **Enumerate every defect found.** `PREFLIGHT: REVISIONS REQUIRED` output MUST list every defect found in that pass, not only the first. The failure mechanism is round inflation: a single-defect report causes the next round to rediscover a defect the same pass could have reported, so the round count rises without the review having covered more of the plan.
-- **Check the delta against its own rule.** Before returning either signal, `atomic-executor` MUST check its proposed fix or delta text against every rule the plan enforces, including that delta's own prose against the same violation class it is remediating. Worked example: the delta prose of a tonality-compliance fix must not itself contain the hyperbole or humor that `.claude/rules/tonality.md` prohibits, because a delta that violates the rule it is written to enforce reintroduces the finding it closes.
-- **Two-round target.** The quality bar is a target of at most two preflight rounds per plan. Exhaustive first-pass review is the mechanism that holds the round count to that target: a pass that reports every defect it can find leaves at most a revision round and a confirming round, whereas a pass that reports one defect at a time cannot reach the target however correct each individual report is.
+- **Classify every defect as trivial or substantive.**
+	- **Trivial defects** are a stale or misspelled anchor, symbol, heading, or path whose intent is unambiguous; a citation correction, including removal of a G11 line-number or G12 commit-SHA citation; a typo; a literal-formatting defect that does not change what is asserted (quoting, `-e` for a hyphen-leading search pattern, plain `grep` instead of `git grep` for a file the plan creates, a full repository-relative pathspec); an evidence filename spelling; and a validator-blind defect class listed in the `execution-environment` skill whose correction keeps the assertion's meaning.
+	- **Substantive defects** are a missing or extra task; a wrong file set or design; an acceptance criterion with no implementing task; an unsatisfiable acceptance condition whose correction changes what is asserted; a task-ordering error; and a scope-boundary violation.
+- **Fix trivial defects in place, in task text only.** The preflight executor edits task text and plan preamble in the same plan file. It never adds, removes, or reorders tasks, so the executor's anti-replanning rules are unchanged. Each fix is recorded in `<FEATURE>/evidence/other/preflight-fixes.<timestamp>.md`, which carries `Timestamp:`, `Plan:`, and one entry per fix.
+- **Return substantive defects only, all of them.** `PREFLIGHT: REVISIONS REQUIRED` is returned only when at least one substantive defect remains, and it lists every substantive defect found in the pass. `PREFLIGHT: ALL CLEAR` may follow in-place fixes.
+- **Check the fix against its own rule.** Before returning either signal, `atomic-executor` MUST check each in-place fix and each required change against every rule the plan enforces, including the fix's own prose against the same violation class it is remediating. Worked example: the prose of a tonality-compliance fix must not itself contain the hyperbole or humor that `.claude/rules/tonality.md` prohibits, because a fix that violates the rule it is written to enforce reintroduces the finding it closes.
+
+Output format. After the `PREFLIGHT:` signal and the `CONVERGENCE:` line, the preflight return carries one line per defect:
+
+- `PREFLIGHT-FIX: <task id or heading> | <defect class> | <change made>` for each trivial defect fixed in place.
+- `PREFLIGHT-DEFECT: <task id or heading> | <defect class> | <required change>` for each substantive defect returned.
+- `preflight-fix-record: <path>` when at least one fix was made, naming the record under `<FEATURE>/evidence/other/`.
+
+`PREFLIGHT: ALL CLEAR` carries no `PREFLIGHT-DEFECT:` line, and `PREFLIGHT: REVISIONS REQUIRED` carries at least one. The executor SubagentStop hook blocks, repairably, a preflight return with zero or several `PREFLIGHT:` signals, a signal that disagrees with its defect lines, or a `PREFLIGHT-FIX:` line without an existing `preflight-fix-record:` path under `docs/features/`.
+
+At most one return. A plan returns to the planner at most once. On `PREFLIGHT: REVISIONS REQUIRED`, the orchestrator delegates one planner revision carrying the full `PREFLIGHT-DEFECT:` list, then runs one more preflight. If that second preflight still reports a substantive defect, the orchestrator halts with `blocked_reason: "validator_failed"` during planning, or records `final_status: "blocked_preflight_iteration_limit"` in a remediation cycle. In a proportionate remediation cycle, where preflight and execution run in one executor delegation, a substantive defect stops the run with `BLOCKED at preflight (before [P0-T1])` before any task is checked.
 
 Convergence signal. Every preflight return, whether it carries `PREFLIGHT: ALL CLEAR` or `PREFLIGHT: REVISIONS REQUIRED`, MUST additionally carry exactly one of these two forward-looking lines:
 
@@ -189,14 +223,16 @@ Before a plan can be treated as approved:
 - reject the plan if that validator exits non-zero,
 - do not treat human-readable summaries as a substitute for validator success.
 
-The same validator call also applies the acceptance-gate rules G1 through G6 defined in `.claude/rules/plan-acceptance-gates.md`. Those rules report acceptance conditions that cannot fail — a coverage argument that collects no data, or a search for a literal that returns zero matches whatever the executor does. They run automatically on the existing `plan` route with no additional flag. Blocking findings appear in the validator's error output and fail the gate; Warnings are surfaced without failing it, prefixed with `PLAN GATE WARNING: ` on the CLI and carried on the optional `warnings` field of the MCP result. Read that rule file before authoring acceptance conditions.
+The same validator call also applies the acceptance-gate rules defined in `.claude/rules/plan-acceptance-gates.md`, starting with G1 through G6. Those rules report acceptance conditions that cannot fail — a coverage argument that collects no data, or a search for a literal that returns zero matches whatever the executor does. They run automatically on the existing `plan` route with no additional flag. Blocking findings appear in the validator's error output and fail the gate; Warnings are surfaced without failing it, prefixed with `PLAN GATE WARNING: ` on the CLI and carried on the optional `warnings` field of the MCP result. Read that rule file before authoring acceptance conditions.
 
-The same call additionally applies the rules G7, G8, G8b, and G9, which report a write-mode command observed only by its exit code, an unanchored `git diff`, a name-listing diff with no companion span, and a coverage command that prints no table. All four ship in the Warning channel, so they surface without failing the gate. The complete shipped set is therefore G1 through G9.
+The same call additionally applies the rules G7, G8, G8b, and G9, which report a write-mode command observed only by its exit code, an unanchored `git diff`, a name-listing diff with no companion span, and a coverage command that prints no table. All four ship in the Warning channel, so they surface without failing the gate. The same call also applies G10, a document-level rule that reports a SCRATCH definition not namespaced by issue number. G10 ships in the Blocking channel and reports each finding with a `Line N: ` prefix rather than a task identifier, because the definition sits outside any task window. The same call also applies the document-level rules G11, G12, and G13, which report a line-number citation, a commit-SHA citation, and a plan above 40 tasks or 400 lines without a non-empty `## Size Justification` section; all three ship in the Blocking channel with the `Line N: ` prefix. The complete shipped set is therefore G1 through G13. The installed MCP validator applies G11 through G13 only after the extension release that carries them is installed; until then, validate a plan with the repository's Python CLI `scripts/dev_tools/validate_orchestration_artifacts.py` and its `plan` subcommand, as the `execution-environment` skill states.
 
 ## Wrap-Tolerant Assertion Authoring (Mandatory)
 
 An acceptance condition must be able to fail. A condition whose command returns the same result whatever the executor does verifies nothing, however precise it reads. Author every acceptance condition in a wrap-tolerant form: one that survives line wrapping and shell quoting in the file it asserts against.
 
+These rules apply to the asserted value of an acceptance condition and are subordinate to `## Design-Level Plan Contract (Mandatory)`: they say how to quote a value that is asserted, not that a plan should quote file contents, command recipes, or tool routes. Where a rule below names a command shape, the shape is guidance for the executor's choice of command, which the `execution-environment` skill governs.
+
 Rules:
 
 - **Prefer a named test over a phrase search.** When a test can carry the assertion, name the test and its node ID and assert its pass count. A test node ID is stable under reformatting; a prose phrase is not. Reserve searches for cases where no test can express the condition.
@@ -212,7 +248,7 @@ Rules:
 - **Observe a command's success-case output before asserting over that output (mandatory).** Run the command, or read a recorded run of it, and confirm the value you intend to assert is actually printed on a *successful* run. Do not infer it from the tool's documentation, from the plan, or from what the tool prints on failure. This requirement exists because the class of defect it prevents is not detectable by reading: an assertion on a line the tool prints only when it changed something is unsatisfiable on a clean run; a demand for a zero-diagnostic count from a tool that returns only an ok flag names a value with no source; a demand for separate line and branch percentages from a coverage run that prints one combined column reads two numbers that are never printed. G7 and G9 cover two decidable slices of this class. The remainder is covered by this requirement and by nothing else, so a reviewer cannot rely on the gate to catch it.
 - **Fix the evidence in the plan; never leave the executor to select it.** An executor free to choose the evidence it is judged against cannot fail. Do not write an acceptance condition that asks the executor to identify "the known-genuine pair", to choose a survivor list, or to pick any suitable instance. Name the instances, or state the mechanical derivation that produces them, so a third party re-running it obtains the same set. This is authoring guidance and not a rule: a validator rule that scanned acceptance text for selection vocabulary was proposed and rejected, because that vocabulary is ordinary plan prose used in roles carrying no selection semantics and a keyword scan over prose is not statically decidable for the property it would claim to detect. The judgment is the author's, and it is not automated. `.claude/rules/plan-acceptance-gates.md` records the rejection and the reason for it.
 - **Check that the task-ordering does not make the condition unsatisfiable.** No rule covers this. A gate that runs a test path containing deliberately-failing cases added by an earlier task, before the later task that makes them pass, cannot exit 0. A baseline captured after a write-mode formatter has already repaired pre-existing drift becomes either a blanket waiver or makes a later gate unsatisfiable. Read each acceptance condition against the state the plan will actually be in when its task runs.
-- **Name the runner and job for a Pester acceptance criterion.** CI runs Pester in two jobs of `.github/workflows/_poshqc.yml`: `poshqc / PowerShell QC` runs every suite with coverage on `windows-latest`, and `poshqc / PowerShell hook suites (Linux)` runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest`, with coverage disabled. A Pester acceptance criterion may cite `ubuntu-latest` only for suites under `tests/scripts/claude-hooks` or `tests/scripts/codex-hooks`, never for coverage, and must name the job it relies on (`poshqc / PowerShell QC` or `poshqc / PowerShell hook suites (Linux)`).
+- **Name the runner and job for a Pester acceptance criterion.** In `.github/workflows/_poshqc.yml`, the Pester suites run with coverage on `windows-latest` in the shard jobs `poshqc / PowerShell QC shard 1`, `shard 2`, and `shard 3`; `poshqc / PowerShell QC` is the aggregating required check, which requires the static and shard jobs to succeed and merges shard coverage; and `poshqc / PowerShell hook suites (Linux)` runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest`, with coverage disabled. The execution-environment brief's `## CI Shape and Required Checks` section is the authoritative description of this shape. A Pester acceptance criterion may cite `ubuntu-latest` only for suites under `tests/scripts/claude-hooks` or `tests/scripts/codex-hooks`, never for coverage, and must name the job it relies on (`poshqc / PowerShell QC` or `poshqc / PowerShell hook suites (Linux)`).
 - **Do not assert a fixed-string search literal that contains a backslash.** Git for Windows grep 3.0 reads a doubled backslash in a `grep -F` pattern as one backslash, so the same check returns a different count locally than on a CI runner and cannot pass in both places. Assert a backslash-free substring of the literal, a named test, or a hash or byte-identity check instead.
 
 ## Plan-Path Continuity Contract (Mandatory)
@@ -220,10 +256,10 @@ Rules:
 When a caller provides an explicit target plan file path (for example `${plan-path}` or `${file}`):
 
 - Planner MUST update that exact file in place.
-- Planner MUST reuse the same file for all preflight revision iterations.
+- Planner MUST reuse the same file for the single permitted preflight revision.
 - Planner MUST NOT create additional timestamped sibling files (for example `plan.<timestamp>.md`) during the same planning cycle.
 
-If the provided path does not exist, it may be created once, then reused for all subsequent revisions in that cycle.
+If the provided path does not exist, it may be created once, then reused for the single permitted revision in that cycle.
 
 ## Mode source precedence (Mandatory)
 

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/SKILL.md

@@ -203,9 +203,13 @@ The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
    `.claude/settings.json`) carries no `gh` entry; and `.claude/hooks/enforce-epic-merge-gate.ps1`
    would deny the command with `EPIC_MERGE_GATE_BLOCKED` if it were attempted. At this
    boundary the agent reports the consolidation pull request's URL or number to the
-   operator and stops. The ruleset on `main` sets `strict_required_status_checks_policy`,
-   so the branch must be up to date with `main` before the merge becomes available to the
-   operator; the wait for the merge is unbounded within a session. After the consolidation
+   operator and stops. When `main` uses a merge queue (issue #952), the queue tests the merged
+   result of the pull request and the entries ahead of it against the latest `main`, so the
+   branch need not be up to date with `main`, and the operator adds it to the queue once its
+   checks pass. Without a merge queue, the ruleset on `main` sets
+   `strict_required_status_checks_policy`, so the branch must be up to date with `main` before
+   the merge becomes available to the operator. In either case the wait for the merge is
+   unbounded within a session. After the consolidation
    PR merges, verify it with `git fetch` followed by
    `git merge-base --is-ancestor documentationandmemories main`. Exit 0 confirms every
    consolidated commit is now reachable from `main`; that is the only state that unlocks

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_detached_lib.sh

@@ -43,7 +43,7 @@ is_detached_candidate() {
 	#
 	# The predicate is the porcelain FLAG, not the branch field: emit_record writes the
 	# literal DETACHED into the branch field whenever the branch accumulator is empty
-	# (.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_enumerate_lib.sh:115-116), which is also true of a
+	# (emit_record, nested in parse_worktree_list in cleanup_worktrees_enumerate_lib.sh), which is also true of a
 	# bare-repository stanza, and a local branch literally named DETACHED would produce
 	# the same branch field with no `detached` flag.
 	#

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_enumerate_lib.sh

@@ -348,6 +348,8 @@ cleanup_wt_derive_scan_roots() {
 		p=${paths[i]//\\//}
 		parent=${p%/*}
 		[[ -z $parent || $parent == "$p" ]] && continue
+		# A drive-relative parent (a registration directly under a drive root, such as D:/wt) is not an absolute root and is dropped.
+		cleanup_wt_is_absolute_path "$parent" || continue
 		n=$(normalize_wt_path "$parent")
 		[[ -z $n || -n ${seen[$n]:-} ]] && continue
 		[[ $n == "$main_norm" || $main_norm == "$n"/* ]] && continue

package/resources/claude-customizations/.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_scan_helper.sh

@@ -40,6 +40,8 @@
 # the SHELL_QC_<TOOL>_BIN seams substitute a checked-in stand-in for a real dependency.
 # An empty value is treated as missing and falls back to `.git`.
 set -euo pipefail
+# The library path is computed at runtime from BASH_SOURCE, so shellcheck (run without
+# -x) cannot follow it; SC1091 is the expected, benign result.
 # shellcheck source=.claude/skills/cleanup-merged-worktrees/scripts/cleanup_worktrees_enumerate_lib.sh
 # shellcheck disable=SC1091
 source "$(dirname -- "${BASH_SOURCE[0]}")/cleanup_worktrees_enumerate_lib.sh"

package/resources/claude-customizations/.claude/skills/csharp-change-budget-router/SKILL.md

@@ -28,7 +28,7 @@ When routed through `csharp-orchestrator`, small path still requires lifecycle s
 - promote potential item to GitHub issue with `--work-mode minor-audit`,
 - create active feature folder with `--work-mode minor-audit`,
 - delegate minimal-audit plan creation to `atomic_planner` with `DIRECTIVE: MINIMAL-AUDIT PLAN REQUIRED`,
-- require `atomic_executor` preflight until `PREFLIGHT: ALL CLEAR`,
+- require single-pass `atomic_executor` preflight ending in `PREFLIGHT: ALL CLEAR` (at most one return to the planner),
 - execute Phase 0 only via atomic_executor before branching,
 - run reduced small-audit after implementation and QC.
 
@@ -69,7 +69,7 @@ In all modes, per-batch budget remains: at most **3 production files** and **3 t
 When `csharp-typed-engineer` runs in orchestrator handoff mode, it must execute the following delegation chain and must not bypass it with direct implementation:
 
 1. Delegate to `atomic_planner` for an architecture plus testability plan only (no edits).
-2. Require planner output to include final `PREFLIGHT: ALL CLEAR` from the preflight validation loop.
+2. Require planner output to include final `PREFLIGHT: ALL CLEAR` from single-pass preflight (at most one return to the planner).
 3. Delegate plan execution to `atomic_executor`.
 4. Delegate the final QA gate to `atomic_executor` per `csharp-qa-gate`.
 5. Delegate post-implementation review to `feature-review` per `feature-review-workflow`.

package/resources/claude-customizations/.claude/skills/epic-orchestrate/SKILL.md

@@ -95,20 +95,45 @@ function of the DAG.
 2. Before starting each wave, `epic-orchestrator` runs
    `git fetch origin epic/<epic-slug>-integration` so the wave's child worktrees branch off the
    current remote tip, not a stale local ref.
-3. Each child feature's worktree/branch (created via
+3. Before each wave launches (wave 0 included), `epic-orchestrator` runs
+   `git fetch origin main` and then
+   `git rev-list --count origin/epic/<epic-slug>-integration..origin/main`. A zero count
+   proceeds directly to the wave. A non-zero count means `origin/main` has commits the
+   integration branch lacks, and the main-sync runs as a dedicated chore child item before the
+   wave launches, following the `epic-852-main-sync` / PR #882 pattern. Before delegating it,
+   `epic-orchestrator` writes the sync child's `features[]` row (with `depends_on: []`) and its
+   own `waves[]` entry to the epic checkpoint, because `enforce-epic-wave-barrier.ps1` denies a
+   delegation whose feature record is absent. The sync child must not reuse a manifest child's
+   issue number; it uses the epic issue number or a dedicated chore issue. Its branch is created
+   from the integration branch, merges `origin/main` with a merge commit
+   (`git merge --no-ff origin/main`; no rebase, no force-push), resolves any conflict inside its
+   own remediation loop, and opens a PR into the integration branch. The wave does not launch
+   until that PR has merged into the integration branch and the sync entry's `merge_status` is
+   `merged`. At most one main-sync child runs per wave: after it merges, `epic-orchestrator`
+   re-runs step 2 and launches the wave without repeating the count, and commits that reach
+   `origin/main` afterwards are picked up by the next wave's check or by the final integration
+   PR in step 6.
+4. Each child feature's worktree/branch (created via
    `Agent(orchestrator, isolation: "worktree", run_in_background: true)`) is branched from
    `origin/<integration_branch>`, not `origin/main`. The child's own `orchestrator` instance
    honors this via the epic-mode kickoff line below.
-4. Each child feature's PR base branch is the integration branch, not `main` — an explicit
+5. Each child feature's PR base branch is the integration branch, not `main` — an explicit
    epic-mode override recorded in the checkpoint, not a reliance on `pr-base-branch-merge-base`'s
    ancestry heuristic. Non-epic (standalone) orchestration is unchanged.
-5. At epic completion (every feature in the final wave has `merge_status: "merged"`),
+6. At epic completion (every feature in the final wave has `merge_status: "merged"`),
    `epic-orchestrator` drives a final PR merging `epic/<epic-slug>-integration` into `main`,
    delegating PR authoring to `Agent(pr-author)` and refreshing context via
    `mcp__drm-copilot__collect_pr_context`. `epic-orchestrator` runs the same S9 CI-green
    procedure (`pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-CiGateParser.ps1`) directly against this PR, records
    the result under the epic checkpoint's `epic_merge_pr` object, then executes
-   `gh pr merge --merge` once green, gated by `enforce-epic-merge-gate.ps1`.
+   `gh pr merge --merge` once green, gated by `enforce-epic-merge-gate.ps1`. Under a merge queue
+   on `main`, `gh pr merge` can return before the merge happens, so
+   `epic_merge_pr.merge_commit_sha` is recorded only after the merge is confirmed by polling and
+   ancestry check, using the confirmation procedure of step 3 of
+   `## Per-Item Merge to Main (Merge-on-Green)` in `.claude/skills/parallel-orchestrate/SKILL.md`
+   with `main` as the base branch; each pull-request snapshot is classified with
+   `pwsh -NoProfile -File .claude/lib/ci-gate/Invoke-MergeConfirmationParser.ps1 -PrJson <snapshot-json> -AsJson`
+   (issue #952).
 
 ## Merge-on-Green Kickoff Parameter
 
@@ -120,7 +145,9 @@ the literal epic-mode kickoff line:
 The child's own `orchestrator`, on reading this line, records `epic_mode: true` and
 `epic_context: { epic_feature_folder, integration_branch, epic_checkpoint_path }` at its first
 checkpoint write, and on CI-green (S9 step 6) merges its own PR into the integration branch,
-recording `epic_merge: { merge_commit_sha, target_branch, merged_at }`. Standalone (non-epic)
+recording `epic_merge: { merge_commit_sha, target_branch, merged_at }`. The child records
+`epic_merge` only after the merge is confirmed by polling and ancestry check against
+`origin/<integration_branch>` (S9 step 6). Standalone (non-epic)
 orchestration is unchanged: `epic_mode` absent or `false` makes S9 step 6 a no-op.
 
 The run gates `enforce-orchestration-preimplementation-gate.ps1` and `enforce-epic-wave-barrier.ps1` locate the epic checkpoint by the `integration_branch:` value of this line. They select the live worktree whose `artifacts/orchestration/epic-orchestrator-state.json` records `route_id` `epic` and that integration branch, prefer the worktree that has the branch checked out when more than one records it, and deny the delegation with `TARGET_WORKTREE_NOT_DERIVABLE` or `TARGET_WORKTREE_AMBIGUOUS` when none or more than one remains. A stale copy of the epic checkpoint is moved to `artifacts/orchestration/handoff/` rather than left at a worktree root. The child run's own delegations to implementation agents carry the canonical issue-number line and `branch:` label defined in `.claude/skills/orchestrate/SKILL.md` `## Issue Number Consistency`.
@@ -241,9 +268,15 @@ cross-call/conversation-state visibility.
   prompt text, reads `artifacts/orchestration/epic-orchestrator-state.json`, looks up that
   feature's `depends_on`, and denies with reason `EPIC_WAVE_BARRIER_BLOCKED` unless every
   dependency's `merge_status` is `merged` or `worktree_removed`.
-- **Layer 2 — retrospective backstop:** the wave-barrier ordering invariant inside
-  `validate_epic_orchestrator_state_text`, enforced at `epic-orchestrator` `SubagentStop` time via
-  the parameterized `validate-orchestrator-output.ps1` hook. It checks only a dependent feature
+- **Layer 2 — retrospective backstop:** the wave-barrier ordering invariant of
+  `validate_epic_orchestrator_state_text`, enforced at `epic-orchestrator` `SubagentStop` time by a
+  PowerShell port, `Get-OrchestratorStateEpicWaveBarrierError` in
+  `.claude/lib/orchestrator-state/OrchestratorStateEpicWaveBarrier.psm1`, which the parameterized
+  `validate-orchestrator-output.ps1` hook invokes for `epic-orchestrator-state` after resolving the
+  epic checkpoint through `WorktreeRunResolution.psm1`. The hook starts no Python process. Parity
+  with `validate_epic_orchestrator_state_text` is pinned by the shared fixtures under
+  `tests/fixtures/epic_wave_barrier/`, and the Python validator remains the authority used through
+  the `mcp__drm-copilot__validate_orchestration_artifacts` call. It checks only a dependent feature
   that is treated as started: one with a string `worktree_created_at`, or with a `merge_status`
   other than `not_started` (a missing or non-string `merge_status` counts as started). It appends
   exactly one error per violated dependency edge. When the dependency's `merge_status` is not
@@ -252,6 +285,9 @@ cross-call/conversation-state visibility.
   Otherwise, when the dependency's `merge_confirmed_at` is later than the dependent's
   `worktree_created_at`, the error is
   `EPIC_WAVE_BARRIER_VIOLATION: <f> worktree_created_at precedes dependency <d> merge_confirmed_at`.
+  A violation blocks with an instruction to report it to the operator and halt. The `SubagentStop`
+  transport and exit-code defect that this check previously depended on was resolved by epic #904
+  and issue #928: a violation blocks the stop with exit 2 and a stderr reason.
 
 Both layers are required; neither alone closes the gap. `epic-orchestrator` does not launch wave
 N+1 until every wave-N feature's dependency edges are durably confirmed merged, verified against
@@ -326,7 +362,7 @@ that same call at the completion gate. The validation is implemented in
 
 1. Every feature in the manifest has `merge_status` in `{merged, worktree_removed}`.
 2. The final integration-to-`main` PR has merged and `epic_merge_pr.merge_commit_sha` is
-   recorded.
+   recorded, and it is recorded only after the merge is confirmed by polling and ancestry check.
 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`.

package/resources/claude-customizations/.claude/skills/epic-plan/SKILL.md

@@ -118,8 +118,10 @@ A preparation-mode `orchestrator` run:
   `feature-promotion-lifecycle`, and `atomic-plan-contract`, and the promotion plus validator
   MCP tools.
 - Runs promotion via the MCP surface, research, feature documents, atomic planning, and the
-  atomic-executor preflight (precondition validation only, per the orchestrate skill's R2
-  semantics), iterating plan revisions until `PREFLIGHT: ALL CLEAR`.
+  atomic-executor preflight (precondition validation only), under the orchestrate skill's
+  single-pass preflight rule in `## Delegation Model`: trivial defects are fixed in place, a
+  plan returns to the planner at most once, and a second substantive result halts with
+  `blocked_reason: "validator_failed"`.
 - Terminates with `completed_steps` containing `S3_promotion` and `S4_atomic_planning`,
   `next_step: "S5_atomic_execution"`, out-of-scope step statuses `not-applicable`, and
   `blocked_reason: "none"`. The route's `requires_ci_gate: false` means the completion validator
@@ -211,7 +213,7 @@ With no ready feature checkpoint, the exemption admits two attribution-trailer f
 - The trailer option: `git commit -m 'docs: plan' --trailer 'Co-Authored-By: Name <email>' --trailer 'Claude-Session: <url>' -- <exempt paths>`. The separate-value form and the `--trailer=<value>` form are both admitted, any number of times, on `git commit` only; `git add --trailer` and a trailer option with no value are denied. Git writes every trailer value into one trailer block.
 - The one-paragraph multi-message form: the subject in the first `-m` and every trailer in one single-quoted second `-m` value, separated by a literal newline. Each `-m` value becomes its own paragraph and git parses only the last paragraph as the trailer block, so trailers split across separate `-m` values do not form one trailer block.
 
-Quoting rules: `$` and backtick are literal and admitted inside single quotes, and denied outside quotes and inside double quotes, where the shell expands them. `<` and `>` are admitted inside single or double quotes and denied outside quotes. An unquoted `#` is denied anywhere, because it starts a shell comment that the exemption does not model; a `#` inside quotes is admitted. A typographic quote character (U+2018 to U+201E) anywhere in the command line is denied, because a PowerShell host reads it as a quote.
+Quoting rules: `$` and backtick are literal and admitted inside single quotes, and denied outside quotes and inside double quotes, where the shell expands them. `<` and `>` are admitted inside single or double quotes and denied outside quotes. An unquoted `#` is denied anywhere, because it starts a shell comment that the exemption does not model; a `#` inside quotes is admitted. A typographic quote character (U+2018 to U+201E) anywhere in the command line is denied, because a PowerShell host reads it as a quote. Because the executing shell is undetermined (issue #735), a shape whose meaning differs between a POSIX shell and PowerShell is denied: a backslash anywhere in the command line is denied, and `{`, `}`, `,`, `(`, `)`, and `@` are denied outside quotes. Every staging operand must be a plain forward-slash repository-relative path that uses only the characters `A-Z a-z 0-9 . _ / -`.
 
 Not admitted: heredoc-fed messages, including `git commit -m "$(cat <<'EOF' ... EOF)"` and `git commit -F - <<'EOF'`, and message files supplied through `-F <file>` or `--file=<file>`. Use one of the two forms above instead.
 

package/resources/claude-customizations/.claude/skills/evidence-and-timestamp-conventions/SKILL.md

@@ -46,7 +46,16 @@ Use this skill when:
 Use `yyyy-MM-ddTHH-mm` for all audit, remediation, and evidence artifacts.
 Example: `2026-02-06T14-30`.
 
-The `Timestamp` value is local time read from the host system clock when the recorded command runs (for example `Get-Date -Format yyyy-MM-ddTHH-mm`); the agent never composes or estimates it.
+The `Timestamp` value is UTC read from the host system clock when the recorded command runs (for example `Get-Date -AsUTC -Format yyyy-MM-ddTHH-mm` in PowerShell 7, `(Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH-mm')` in Windows PowerShell 5.1, or `date -u +%Y-%m-%dT%H-%M` in a POSIX shell); the agent never composes or estimates it. The value is written without a zone suffix.
+
+### Evidence Filename Timestamp
+
+The stamp in the filename of every artifact under `<FEATURE>/evidence/<kind>/` is the UTC time at which that file is written, read from the host system clock immediately before the write, in the same `yyyy-MM-ddTHH-mm` shape with no zone suffix. It is never a plan-time stamp, a plan-cycle identifier, or any other value fixed before the write.
+
+- Plans name such an artifact `<name>.<timestamp>.md`, and the executor substitutes the write time. A later loop pass writes a new file with a new stamp.
+- A task that consumes an evidence artifact selects the lexicographically greatest file matching `<name>.*.md`. The fixed-width UTC shape sorts in chronological order, so that file is the most recently written one.
+- Plan files (`plan.<timestamp>.md`, stamped by the feature-folder tooling in America/New_York) and the review artifact set (`policy-audit`, `code-review`, `feature-audit`, `remediation-inputs`, which share one stamp) are outside this rule.
+- Existing evidence files whose names carry a plan-time stamp are not renamed.
 
 ## Canonical Evidence Locations
 

package/resources/claude-customizations/.claude/skills/execution-environment/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: execution-environment
+description: 'Execution-environment brief for research, planning, preflight, execution, and orchestration. Use before planning or delegating work so tool routes, command-text restrictions, the batch budget, hook context, CI shape, contract tests, evidence rules, coverage and file-size gates, and test-isolation checks are known and are not restated in plans.'
+---
+
+# Execution-Environment Brief
+
+## Purpose and Maintenance
+
+This brief states the environment facts that every researcher, planner, preflight executor, executor, and orchestrator needs before work starts. Plans reference this brief instead of restating its content; a plan that restates a tool route, a launcher, or a command-text restriction duplicates text that goes stale when this brief changes.
+
+Maintenance rule: this brief is updated in the same change that alters any fact it states. It carries no line numbers and no commit identifiers; it cites files, symbols, headings, job names, and test names. The same text is byte-identical in six locations: `.claude/skills/execution-environment/SKILL.md`, `.agents/skills/execution-environment/SKILL.md`, `.github/skills/execution-environment/SKILL.md`, and their bundled copies under `extensions/drm-copilot/resources/`. Where the Claude and Codex runtimes differ, both paths are named (`.claude/hooks/...` and `.codex/hooks/...`).
+
+## Tool Routes by Agent
+
+- `atomic-executor` has no PowerShell tool. Its `tools:` list is Read, Grep, Glob, Edit, Write, several `Bash(...)` entries, the four `mcp__drm-copilot__run_poshqc_*` tools, and `mcp__drm-copilot__validate_orchestration_artifacts`. A `(pattern)` suffix on a `tools:` entry admits the bare tool, so the executor has Bash, subject to the repository hooks and the runtime guard described under Command-Text Restrictions.
+- `atomic-planner` has no Bash. It has Read, Grep, Glob, Edit, Write, and `mcp__drm-copilot__validate_orchestration_artifacts`, so it can validate a plan with the installed validator before handoff but cannot run any toolchain command.
+- `task-researcher` has Read, Grep, Glob, WebFetch, and Write. It cannot run `git show` or `gh`; facts that need either are marked for the orchestrator to confirm.
+- `orchestrator` and the main session running the `orchestrate` skill have Bash, the PoshQC and validation MCP tools, and the `Agent` tool. Only they can delegate, so any step that needs a further agent run is orchestrator-owned.
+- PowerShell for the executor therefore runs through the `mcp__drm-copilot__run_poshqc_*` tools or through a `sh` launcher script stored under `SCRATCH` that invokes PowerShell 7 from inside the script file.
+
+## Command-Text Restrictions
+
+Two separate mechanisms restrict Bash command text. They are kept apart here because they have different causes and different fixes.
+
+- **Worktree isolation guard (Claude Code runtime behavior, not a repository hook).** Inside an agent-isolated worktree, the Claude Code runtime refuses Bash command text it cannot show stays inside the worktree. Observed refusals include text containing `pwsh`, `bash`, or `wsl`, heredocs, `printf --`, a `cd <path> &&` prefix before `git`, `git -C <other worktree>`, embedded `jq` filter strings, an unquoted shell variable in an option position, and loops or other compound constructs around `sh`. Text that passes includes `sh <file>.sh` with a literal path, `npx`, `poetry run python <script>`, `gh`, worktree-scoped `git`, and `git commit -F <file>`. No file under `.claude/hooks/` implements this guard, and no settings file registers it.
+- **Repository hooks.** `.claude/hooks/validate-bash.ps1` (`.codex/hooks/validate-bash.ps1` for Codex; functions `Get-BlockedBashPattern`, `Get-CdChainedReadCommandMatch`, `Get-BashBlockReason`) denies destructive patterns (`rm -rf`, forced pushes, `git reset --hard`, recursive forced removal) and a `cd` followed later in the same command by a file-reading command such as `grep`, `cat`, `head`, `tail`, `less`, `more`, `awk`, or `sed -n`. `.claude/hooks/enforce-parallel-worktree-removal-gate.ps1` denies the literal worktree-removal command anywhere in a command.
+- A multi-line `poetry run python -c` program exits 0 without running. Put Python helpers in a file under `SCRATCH` and run the file.
+
+## PowerShell Route and PoshQC MCP Limits
+
+- PoshQC MCP results carry no output. The summary string is composed from a fixed template before the child process runs (`runPoshQcWorkflow` in `extensions/drm-copilot/src/repo-automation-service.ts`), and `RepoAutomationExecutionResult` has no exit-code or output field. An `ok: true` result proves only that the tool was invoked.
+- Counts, percentages, and findings therefore come from files or direct runs: pass and fail counts from `artifacts/pester/pester-junit.xml`, line coverage from `artifacts/pester/powershell-coverage.xml`, and analyzer findings from a direct `Invoke-ScriptAnalyzer` run with `scripts/powershell/PoshQC/settings/pssa.settings.psd1`.
+- The MCP test tool reads the installed extension's settings. Branch-current Pester runs import `scripts/powershell/PoshQC/PoshQC.psd1` and call `Invoke-PoshQCTest` from a `sh`-launched PowerShell 7. The coverage population is derived by `Invoke-PoshQCTest` from `config/poshqc-coverage.json`; there is no hand-maintained coverage path list.
+- `Invoke-Pester` without `-EnableExit` (or `Run.Exit`) exits 0 when tests fail; read the JUnit file rather than the exit code of such a run.
+
+## Batch Budget
+
+- In direct mode the batch-budget hooks allow at most three distinct production files per kind in one session: the fourth distinct non-test PowerShell file is denied with `POWERSHELL_LARGE_PATH_REQUIRED` and the fourth distinct non-test Python file with `PYTHON_LARGE_PATH_REQUIRED` (`.claude/hooks/enforce-powershell-batch-budget.ps1` and `.claude/hooks/enforce-python-batch-budget.ps1`; Codex copies under `.codex/hooks/`). Test files never count.
+- Exemption: the cap does not apply when `artifacts/orchestration/orchestrator-state.json` in the worktree that holds the hook script selects the `large`, `remediation`, or `preparation` route and is not terminal (`Test-BatchBudgetLargePathRoute` in `.claude/hooks/enforce-batch-budget-route.ps1`). An isolated subagent worktree has no checkpoint, because `artifacts/` is gitignored, so direct mode applies there.
+- Bundle mirror copies under `extensions/drm-copilot/resources/` are production files and count against the cap.
+- A scratch `.ps1` file counts when it resolves inside the worktree root. Files under `SCRATCH`, which is outside the worktree root, are discarded without consuming a slot.
+- Only `Write` and `Edit` calls are seen (the hook matcher is `Write|Edit`). Files written by Bash, by a copy script, or by a generator are not seen.
+- Budget state is kept per session under `.claude/state/`; there is no automatic reset.
+
+## Hook Execution Context
+
+- Hooks for an isolated subagent run inside the subagent's worktree with that worktree's hook scripts, which are `main`'s copies. A hook change on a branch is not exercised by isolated subagents until it merges.
+- Hook behavior on a branch is therefore proven by Pester suites, not by a live subagent run. A live check of a branch hook needs a non-isolated delegation from the item worktree.
+- Enforcement hooks do not invoke Python; bash is preferred and PowerShell is acceptable (`tests/scripts/claude-runtime/enforcement-hooks-no-python-invocation.Tests.ps1`).
+
+## MCP Surfaces Run the Installed Extension
+
+- Every `mcp__drm-copilot__*` tool runs the installed extension, not the branch. `validate_orchestration_artifacts` applies the installed rule set, so validator rules added on a branch apply through MCP only after the extension release that carries them is installed.
+- Branch-current plan validation runs the repository's Python CLI `scripts/dev_tools/validate_orchestration_artifacts.py` with its `plan` subcommand, through Poetry in module form.
+- A push-down served by the MCP tools writes the installed extension's bundled payload; a repository-side edit under `extensions/drm-copilot/resources/` changes that payload only after a rebuild and reinstall.
+
+## CI Shape and Required Checks
+
+- `.github/workflows/ci.yml` triggers on `push` to `main` and `development`, on `pull_request` to `main`, `development`, and `epic/**`, on `workflow_dispatch`, and on `merge_group` (`types: [checks_requested]`, added by issue #952), with no path filters. When the merge queue on `main` is enabled, every required check is produced by a `merge_group` run of `ci.yml` as well as by the pull-request run; `.github/workflows/README.md` (`## Triggers`) records the trigger set.
+- Jobs in `ci.yml` and their check names: `Change scope` (job `changes`, the change-scope decision below); `CI full run` (job `full-run-marker`, which runs only on a full run, marks that run as a valid base for later decisions, and is not a required check); `quality-checks7 / Code Quality & Tests (<python-version>)` on Python 3.10, 3.11, 3.12, and 3.13 (`_quality-checks.yml`: Black check, Ruff, Pyright, the Codex generator `--check`, the tier classification, Pytest with line and branch coverage, and the coverage-threshold check on the JSON report totals); `security-scan / Security Scanning` (its `safety check` step carries `continue-on-error: true` and does not fail the check); `docs-validation / Documentation Validation`; `build-check / Build Package`; `shell-coverage / Shell Coverage (Bats + kcov)`; `drm-copilot-extension-tests / drm-copilot Extension Tests (<os>)` on `ubuntu-latest` and `windows-latest`; `root-typescript-tests / Root TypeScript Tests (<os>)` on `ubuntu-latest` and `windows-latest`; `NPM Audit Gate / npm audit (<manifest>)` (the calling job carries the name `NPM Audit Gate`); and the `poshqc` group below.
+- PowerShell CI (`_poshqc.yml`): `poshqc / PowerShell QC static` (format and analyze on `windows-latest`); the shard matrix `poshqc / PowerShell QC shard 1`, `shard 2`, and `shard 3` (`Invoke-PoshQCTest -ShardIndex -ShardCount` over the scan folders of `config/poshqc-scan.json`, with coverage, on `windows-latest`); the aggregator `poshqc / PowerShell QC`, which requires the static and shard jobs to succeed, verifies shard completeness against a Pester discovery count, and merges shard coverage; and `poshqc / PowerShell hook suites (Linux)`, which runs only `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on `ubuntu-latest` with coverage disabled. A new test file under a scanned folder is assigned to a shard automatically and is counted by the completeness check.
+- Change-scope decision (issue #962): the `Change scope` job runs `scripts/ci/Invoke-CiChangeScope.ps1` and publishes the job output `code`. The decision is `code=false` (docs-only) only on a `pull_request` event from this repository when every file changed since the newest successful `ci.yml` run on the pull-request branch whose `CI full run` job succeeded, and whose head commit is an ancestor of the current head, is on the allowlist `config/ci-docs-only-paths.json`. A path is allowlisted when it starts with `docs/features/active/`, `docs/features/completed/`, `docs/features/potential/`, or `docs/research/`, does not start with `docs/features/templates/` or `docs/features/potential/template.md`, and ends in `.md`, `.txt`, `.log`, `.json`, or `.xml`; the allowlist file itself is not allowlisted. Every other case is a full run (`code=true`): `push`, `merge_group`, and `workflow_dispatch` events, a fork pull request, unreadable run or job data, no earlier full green run, a missing or non-ancestor base, an empty diff, any path outside the allowlist, and any error. The decision step carries `continue-on-error: true` and the callers compare the output with `!= 'false'`, so a failed or missing decision also gives a full run.
+- Docs-only behavior (`code=false`): `ci.yml` passes `run-heavy: false` to `_quality-checks.yml`, `_security-scan.yml`, `_build-check.yml`, `_poshqc.yml`, `_shell-coverage.yml`, and `_drm-copilot-extension-tests.yml`. Each required job still starts under its full-run check name with every step skipped, so every required context reports `success` without running its suite. In `_poshqc.yml` the aggregator `poshqc / PowerShell QC` runs with every step gated, and `poshqc / PowerShell QC static`, the shard jobs, and `poshqc / PowerShell hook suites (Linux)` are skipped at job level. `docs-validation / Documentation Validation` runs in full. `root-typescript-tests`, `NPM Audit Gate`, and `CI full run` are skipped at job level. A `success` on a docs-only commit is therefore not evidence that the heavy suites pass for that commit; that evidence is the newest run whose `CI full run` job succeeded.
+- A commit that changes any path outside the allowlist (any code, workflow, configuration, script, test, or customization file) runs the full set of jobs, and its `CI full run` job marks it as a base for later docs-only decisions. A standalone `workflow_dispatch` of a reusable workflow, or a caller that omits `run-heavy`, also runs in full. `.github/workflows/README.md` (`## Change-Scope Decision (Issue #962)`) records the reason codes and the per-context behavior table.
+- Required contexts of ruleset 15241672, confirmed by the orchestrator through `gh api` on 2026-10-16: `drm-copilot-extension-tests / drm-copilot Extension Tests (ubuntu-latest)`, `drm-copilot-extension-tests / drm-copilot Extension Tests (windows-latest)`, `docs-validation / Documentation Validation`, `poshqc / PowerShell QC`, `shell-coverage / Shell Coverage (Bats + kcov)`, `security-scan / Security Scanning`, `quality-checks7 / Code Quality & Tests (3.10)`, `quality-checks7 / Code Quality & Tests (3.11)`, `quality-checks7 / Code Quality & Tests (3.12)`, `quality-checks7 / Code Quality & Tests (3.13)`, `build-check / Build Package`.
+- Refresh rule: a change that renames a job, adds or removes a matrix entry, or changes the ruleset refreshes this list in the same change, and the orchestrator re-confirms the contexts with a read-only `gh api repos/drmoisan/drm-copilot/rulesets/15241672` call before relying on them.
+- Skipped-check semantics: a job skipped by an `if:` condition reports success to a required check; a workflow that does not run at all reports nothing, which leaves the required check pending.
+- A pull request into a branch other than `main`, `development`, or `epic/**` gets no CI run; dispatch `ci.yml` manually for it.
+
+## CI-Only Failure Classes
+
+- A test that reads gitignored `artifacts/` state passes only on a worktree that holds that state; CI has none.
+- A fixture rooted at a drive letter or a `C:/workspace` path fails `path.isAbsolute` and path joins on Linux.
+- `_shell-coverage.yml` checks out at depth one, so `origin/main` does not exist in that job; no test may diff against it.
+- The Linux hook-suite job runs `tests/scripts/claude-hooks` and `tests/scripts/codex-hooks` on a case-sensitive file system: use `Join-Path`, forward-slash relative paths, exact file-name case, and no drive letters or backslash literals.
+- The `.gitattributes` rule `* text=auto eol=lf` normalizes line endings on checkout, so a CRLF fixture committed as text is not CRLF in CI.
+- Shard and single-process Pester runs expose module-scope import visibility and leaked state that per-suite local runs hide.
+
+## Contract Tests That Pin Mirrored Files
+
+Run these after editing any mirrored or bundled file; each is under `tests/scripts/dev_tools/` unless named otherwise.
+
+- `test_push_down_claude_resource_contracts.py` and `test_push_down_codex_and_agents_resource_contracts.py`: every distributable `.claude`, `.agents`, and `.codex` file exists in the bundle with equal text.
+- `test_push_down_claude_pack_manifest_completeness.py` and `test_push_down_codex_and_agents_pack_manifest_completeness.py`: every bundled file is listed in a pack manifest.
+- The Codex generator check: `scripts/dev_tools/generate_codex_agent_variants.py` run in module form with `--check` (base agents are hand-edited; variants, bundle copies, and the Codex `core.json` are generated).
+- `test_codex_agent_wrapper_contracts.py` and `test_codex_handoff_contract_parity.py`: pinned Codex agent fragments and handoff parity.
+- `test_claude_rules_frontmatter.py`: rule `paths:` scopes and that every preloaded skill exists.
+- `parallel_orchestrator_surface_expectations.py` (`PINNED_FROZEN_SURFACE_HASHES`): byte hashes of frozen orchestration surfaces, including `.claude/skills/epic-orchestrate/SKILL.md` and `.claude/agents/epic-orchestrator.md`.
+- `test_quality_checks_workflow_contracts.py`: workflow step conditions.
+- `test_push_down_issue_824_follow_ups.py`: pushed rules and skills name no consuming product.
+- `test_typescript_toolchain_instruction_contracts.py`: no reference to another test framework, and every backticked npm script token in the pinned mirrors exists in the root `package.json`.
+- `tests/scripts/claude-runtime/claude-architecture-doc.Tests.ps1` and `tests/scripts/claude-runtime/hook-dependency-guard-completeness.Tests.ps1`: agent tool names in the architecture document and the guarded dot-source pattern in hooks.
+
+## Preflight Defect Classes the Validator Cannot See
+
+These pass every validator rule and are found only by reading the plan against the tree:
+
+- `git grep` against a file the plan creates (untracked, so invisible to `git grep`); a search pattern beginning with `-` that is not passed through `-e`.
+- A checkbox diff-pair assertion against a file the plan adds, and a CRLF fixture under the `eol=lf` attribute rule.
+- A new TypeScript production file without its own `coverageThreshold` entry in `extensions/drm-copilot/jest.config.cjs`, whose threshold map has per-file entries only and no `global` key.
+- A per-file coverage floor asserted for code that the tests replace with blanket mocks.
+- Batch-budget exhaustion across a session, and an acceptance condition that depends on a branch hook being exercised by an isolated subagent.
+- `origin/main` advancing during planning: scope diffs anchor on the merge base of `origin/main` and `HEAD`, never on `origin/main` itself.
+- `Measure-Object -Line` counts non-empty lines only; physical line counts use `wc -l` or `@(Get-Content -LiteralPath <path>).Count`.
+- A coverage argument written as a filesystem path measures nothing; the dotted module form is required, and branch figures come from the JSON report, not the combined terminal column.
+- A task that changes the observable behavior of an existing function, script, fixture, or test stub (signature, argv, output, exit status, or written files) while the tests that assert that behavior are outside the task's file set: those tests fail once the change lands, and the plan's own acceptance cannot be met. Preflight searches the test tree for the changed symbol, the file name, and the asserted output, and confirms that the task names each matching test with its disposition (unchanged because unaffected, or updated with the reason).
+- A plan that alters a fact this brief states (it adds or renames a CI job, changes a required status context, a tool route, or a batch-budget rule) with no task that updates the brief in the same change, in all six byte-identical copies: the plan then breaks the maintenance rule in `## Purpose and Maintenance`. Preflight compares each task's changes against the facts this brief states and confirms that a brief-update task exists and that the plan's `Mirror parity` Pre-Mortem bullet names it.
+
+## Evidence and Documentation Rules
+
+- Evidence lives under `<FEATURE>/evidence/<kind>/` with kinds `baseline`, `regression-testing`, `qa-gates`, `other`, `issue-updates`, and `remediation-baseline` (`.claude/skills/evidence-and-timestamp-conventions/SKILL.md`; enforced by `.claude/hooks/enforce-evidence-locations.ps1`).
+- Evidence filenames carry the UTC time of the write, read from the clock, in the `yyyy-MM-ddTHH-mm` shape; a consumer selects the lexicographically greatest `<name>.*.md`. Plan files are stamped by the feature-folder tooling in America/New_York.
+- Every command-step artifact carries `Timestamp:`, `Command:`, `EXIT_CODE:`, and `Output Summary:`. No artifact records an absolute path, a host name, or a session scratchpad path; scratch locations are recorded as the token `SCRATCH`.
+- `SCRATCH` is `<session scratchpad>/issue-<issue-num>/`, and scratch file names start with `issue-<issue-num>-`.
+- `.github/workflows/_docs-validation.yml` checks only that `README.md` is present and non-empty and that `LICENSE` exists, and it warns when two instruction files are missing. There is no Markdown lint or link check in CI.
+
+## Coverage and File-Size Gates
+
+- Line coverage of at least 85% and branch coverage of at least 75% apply per changed production file in Python and TypeScript. PowerShell has a line threshold of 85% and no branch gate, because Pester does not measure branch coverage. No production file may be excluded from measurement.
+- Python: measure a module with `--cov=<dotted.module>`, `--cov-branch`, `--cov-report=term-missing`, and `--cov-report=json:<path>`; read branch figures from the JSON report.
+- TypeScript: a new production file needs its own entry in the `coverageThreshold` map of `extensions/drm-copilot/jest.config.cjs`; Jest runs through `node run-jest.cjs` in `extensions/drm-copilot/`.
+- PowerShell: per-file line coverage is read from `artifacts/pester/powershell-coverage.xml` written by the self-hosted PoshQC module.
+- No production, test, or reusable script file exceeds 500 physical lines; Markdown is exempt. Files at or near the limit are not extended; new logic goes into a new module and a new test file.
+
+## Test Isolation Checks
+
+- Tests create no temporary files; file and transcript reads go through injected seams with in-memory content.
+- Before review, run each isolation check and record it under `<FEATURE>/evidence/regression-testing/`:
+  - a seeded shuffled Jest run (`node run-jest.cjs --randomize --seed=<n>` in `extensions/drm-copilot/`) with the seed recorded;
+  - a reversed-order run of the new or changed Python test modules in one process;
+  - a seeded shuffled file-order run of the touched Pester suites in one process, with at least three seeds and each seed and its file order recorded;
+  - a fresh single-process Pester run over `tests/scripts`, which is the CI shape.
+- An order dependence found by any run is fixed on both sides: the suite that leaves state behind (globals, functions, environment variables, mocks, imported modules, script-scope state) and the suite that assumes prior state. Every seed is then re-run.

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

@@ -45,7 +45,7 @@ Note: VS Code command-palette commands may exist for interactive extension use,
 When the GitHub issue already exists (it was transferred, filed before orchestration, or created by epic decomposition), do not call `potential_to_issue`: that tool creates a new issue and would duplicate the existing one. Instead:
 
 1. Verify the issue read-only with `gh issue view`, a `gh api` GET request, or a GitHub MCP issue read, and use its number as `${issue-num}`.
-2. Record a top-level `issue_adoption` object in the orchestrator checkpoint (`issue_num`, `issue_url`, `origin`, `verified_via`, `verified_at`, `evidence`, `waived_tools`, and `potential_record` when a promotion-entry tool is waived). A valid record waives the `potential_to_issue` receipt requirement at completion.
+2. Record a top-level `issue_adoption` object in the orchestrator checkpoint (`issue_num`, `issue_url`, `origin`, `verified_via`, `verified_at`, `evidence`, `waived_tools`, and, when a promotion-entry tool is waived, `potential_record`). For that waiver `potential_record` is required when `origin` is `epic_decomposition`, optional when `origin` is `transferred` or `filed_before_orchestration`, and validated whenever it is present. A valid record waives the `potential_to_issue` receipt requirement at completion.
 3. `delegation_receipts.promotion.issue` may be omitted, because no promotion receipt exists for an adopted issue.
 
 The field rules, the closed set of waivable tools, and the fail-closed behavior are defined in `.claude/rules/orchestrator-state.md` under `## Invariants (issue_adoption object)`.