# Execution Environment

> 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, test runtime, and test-isolation checks are known and are not restated in plans.

- Skill: `drmoisan/execution-environment-2` (Agent Skill)
- Install (CLI): `npx get-skill add drmoisan/execution-environment-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/drmoisan/execution-environment-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: drmoisan (https://skillmd.com/u/drmoisan)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/drmoisan/execution-environment-2

---


# 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/...`).

## Development Toolchain Baseline

The host manifest, both devcontainer Dockerfiles, and development CI select Python 3.13.18, Node.js 26.13.0/npm 11.20.0, PowerShell 7.6.9, and Poetry 2.5.1. Both images use `mcr.microsoft.com/devcontainers/python:3.3.2-3.13-bookworm`, require Git >=2.56.0, and install GitHub CLI 2.103.3, .NET SDK 10.0.403, uv 0.13.7, Claude Code 2.1.318, claude-swap 0.29.0, and Codex 0.166.0. Shell validation pins shfmt 3.14.1, ShellCheck 0.11.0, actionlint 1.7.12, and kcov v43. PowerShell selects Pester 6.2.0 and PSScriptAnalyzer 1.25.0. The images also retain Graphite 1.7.14, GitHub Copilot CLI 0.0.377, Bats, and bashdb. Host bootstrap treats manifest versions as minima and preserves equal/newer installations; the container verifier accepts later Python patches within 3.13 and later Git versions, and checks the other selected pins.

The pinned base supplies Python and Git; image-managed CLI installs take precedence on PATH. Full configuration builds include the selected devcontainer features. Local Docker retains the Docker outside-of-Docker feature; floating Git/GitHub CLI features do not replace image pins. Both configurations run the same shared post-create script and mandatory verifier. Local source is a live host bind mount with four `volume-nocopy` Linux dependency volumes for `.venv` and the root, extension, and MCP `node_modules`; setup prepares only their mount roots. A container-only Git environment override disables the host Windows fsmonitor without changing host configuration. The former workspace volume is retained for recovery. Runtime verification uses the Linux environment rather than host Windows dependencies. Codex includes its native optional package, disables the startup update prompt through root-owned system settings, and uses the file credential store; the image does not populate user authentication state. Python bytecode stays under `/tmp/pycache`.

Python 3.11/3.12 compatibility jobs, consumer package engines, and independent release-publishing runtime pins remain unchanged. The shared version predicate lives in `scripts/bash/container_versions.sh`; `.devcontainer/verify-container.sh` resolves it relative to its own repository location.

## 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.
- Nesting depth (#1138): the epic and parallel chains run the coordinator at depth 1, each per-feature `orchestrator` at depth 2, and its specialists at depth 3, so they need Claude Code 2.1.219 or later with `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` unset or at least 3, started from the main session. An agent that starts without the `Agent` tool records `blocked_reason: "spawn_agent_unavailable"` and returns a line beginning `AGENT_TOOL_UNAVAILABLE:`; `enforce-epic-invocation-origin.ps1` denies a chain delegation with `NESTING_DEPTH_INSUFFICIENT:` when the configured value is below 3, and the `## Nesting Depth` section of each coordinating skill states the main-session fallback.

## 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` (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`; an output filter such as `| tail -n 20` counts. Its cd-chained deny reason names the replacement form for the detected intent (`.claude/hooks/bash-command-shape-guidance.ps1`, #1165). The Codex copy `.codex/hooks/validate-bash.ps1` carries the destructive patterns and has no cd-chained leg. `.claude/hooks/enforce-parallel-worktree-removal-gate.ps1` denies the literal worktree-removal command anywhere in a command.
- **Preferred forms (#1165).** Never chain `cd` before a read command; name the directory on the tool instead. The same table is in `.claude/rules/bash-command-shape.md`, which loads at launch, and in its Codex skill and Copilot instruction. In an agent-isolated worktree the Bash working directory is already the worktree root and `git -C <other worktree>` is refused; a non-isolated agent working in a sibling worktree has its Bash working directory reset to the session root on each call, so a `cd` does not carry over. `<abs>` is the absolute path of the target directory.

| Intent | Agent-isolated worktree | Sibling worktree |
|---|---|---|
| Read a file | Read or Grep tool (absolute-path read) | Read or Grep tool (absolute-path read) |
| git | `git <subcommand>` with no `cd` | `git -C <abs> <subcommand>` |
| Poetry | `env -u VIRTUAL_ENV poetry <command>` with no `cd` | `env -u VIRTUAL_ENV poetry -C <abs> <command>` (long form `--directory <abs>`) |
| npm | `npm <command>` with no `cd` | `npm --prefix <abs> <command>` |
| npx | `npx <tool>` with no `cd` | `npm --prefix <abs> run <script>` when a package script exists, otherwise `sh <SCRATCH>/<file>.sh` |
| Multi-step | the steps with no `cd`, or `sh <SCRATCH>/<file>.sh` | `sh <SCRATCH>/<file>.sh` (the script may `cd` internally) |

- A multi-line `poetry run python -c` program exits 0 without running. Put Python helpers in a file under `SCRATCH` and run the file.
- Merge text under the concurrent-review key (#1097): when a checkpoint the merge gate reads records `review_mode: "concurrent"`, Bash text that could be a merge and cannot be bound to one pull request is denied with `REVIEW_GATE_HEAD_UNRESOLVED`. That includes prose holding `pr merge`, `pr (`, or `pr $`, and a merge followed by a line feed or `;`. Issue a merge as one plain `gh pr merge` of one number in its own Bash call, and pass commit messages through `git commit -F` with a 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-PoshQCParallelTest` from a `sh`-launched PowerShell 7. The coverage population is derived by `Invoke-PoshQCTest`, which each shard runs, from `config/poshqc-coverage.json`; there is no hand-maintained coverage path list.
- `Invoke-PoshQCParallelTest` returns an object whose `ExitCode` is read first, and the launcher exits with that value. Merged JUnit and coverage exist only after a fully green run, and a failed run can leave older merged files in place. Failure detail is under `artifacts/pester/parallel/shard-<i>/`.
- `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.
- No MCP tool exposes `Invoke-PoshQCLeakScan`. The executor reaches it through the `sh` launcher route, importing the branch-current `scripts/powershell/PoshQC/PoshQC.psd1` and calling `Invoke-PoshQCLeakScan -Root`; the scan throws on any failure, so the launcher exits non-zero.

## Batch Budget

- In direct mode the batch-budget hooks allow at most three distinct production files per kind in one session and one resolved worktree: 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 containing the edited file selects the `large`, `remediation`, or `preparation` route and is not terminal (`Test-BatchBudgetLargePathRoute` in `.claude/hooks/enforce-batch-budget-route.ps1`). That worktree is resolved by `Resolve-HookTargetWorktree` in `.claude/lib/worktree-resolution/HookTargetWorktree.psm1` (Codex twin `.codex/hooks/hook-target-worktree.ps1`): an absolute path resolves to its nearest enclosing registered git worktree, and a relative path, a path in no registered worktree, or an ambiguous result uses the session root. 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 and outside that root's `artifacts/` directory. Files under `SCRATCH`, which is outside the worktree root, are discarded without consuming a slot.
- Paths under the root-level `artifacts/` directory of the resolved worktree never count: they are allowed without consuming a slot and write no state. A nested directory named `artifacts` elsewhere in the tree still counts.
- Claude edits to a sibling registered worktree count against that worktree's own budget, because containment uses the resolved root; a path outside every registered worktree keeps the session root and is discarded by containment. Codex has no containment filter, so a Codex edit outside every registered worktree counts against the session root.
- 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 and per resolved worktree root under the session root's `.claude/state/` (Codex `.codex/state/`): the session root keeps `<kind>-batch-budget.<session id>.json`, and another worktree uses `<kind>-batch-budget.<session id>.<worktree key>.json` with the key from `Get-HookTargetWorktreeKey`. No state is written into another worktree, and 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.
- The batch-budget hooks evaluate the checkpoint of the target worktree that `Resolve-HookTargetWorktree` resolves for the edited file, so an edit made from a coordinating session into an item worktree is evaluated against the item worktree's checkpoint. The preimplementation gate (#1010) resolves the file path of a Write or Edit call and the `-C` values and absolute operands of `git add` and `git commit` through the same resolver, and denies when the worktree listing fails or names no worktree; its delegation checks still resolve by portable identity. The PR authoring gate (#1011) resolves the branch that a `gh pr create` or `gh pr edit` command names (`--head`, `--branch`, or a `branch:` label) through the same resolver when the command carries no canonical issue number line, and otherwise keeps its portable-identity and current-branch resolution. The other gates that read `artifacts/orchestration/orchestrator-state.json` are unchanged and still use the root that holds the hook script; the SubagentStop artifact hooks, the review coverage hook, and the orchestrator checkpoint stop hook described in the next item are not among them.
- SubagentStop artifact paths (#1105): the researcher (`research-path`), `prd-feature` (`spec-path`, `research-path`), required-artifact, planner (`plan-path`), and executor (`plan-path`, `preflight-fix-record`) hooks and the review coverage hook (`.claude/hooks/validate-feature-review-coverage.ps1`) resolve the item worktree through `Resolve-SubagentStopTargetWorktree` in `.claude/hooks/subagentstop-target-worktree.ps1`, which calls `Resolve-HookTargetWorktree` with an absolute advertised path or with the delegation prompt read from the subagent transcript (its `branch:` label and canonical issue line). They probe only the copy beneath the resolved item root and never fall back to the main checkout; an absolute path inside the item worktree is converted to repository-relative form before the unchanged shape rules run. Beneath an item root, the coverage hook reads the PR context summary, the root `CLAUDE.md`, and the coverage reports there, and blocks on an absent or stale report (`validate-feature-review-coverage-freshness.ps1`); a not-derivable or ambiguous resolution blocks the review. Without an absolute path or prompt identity, the session root applies and behavior is unchanged. The orchestrator checkpoint stop hook (#1145, `.claude/hooks/validate-orchestrator-output.ps1` through `validate-orchestrator-output-target.ps1`) resolves the `orchestrator-state` checkpoint the same way from the delegation prompt: a prompt identity that places the run in one worktree decides the root of the checkpoint and of the routing-contract, runbook, and feature-folder checks; an identity that names no registered worktree or more than one blocks once with `ORCHESTRATOR_CHECKPOINT_UNRESOLVED:` before any read; with no transcript, no identity, or a resolver failure, the session worktree is validated and the note `ORCHESTRATOR_CHECKPOINT_FALLBACK:` is appended to a block message or written to stderr on allow. The epic and parallel checkpoints are unchanged, and there is no Codex twin.
- Codex review coverage hook (#1114): `.codex/hooks/validate-feature-review-coverage.ps1` selects the policy audit named in the reviewer's `last_assistant_message`, with no recency fallback, through the functions of `.codex/hooks/feature-review-coverage-target.ps1`. An absolute audit path resolves the item root through `Resolve-HookTargetWorktree` in `.codex/hooks/hook-target-worktree.ps1`, and a relative path uses the session root. The hook reads the PR context summary, the root `CLAUDE.md`, and the coverage reports beneath that root, and when the item root differs from the session root it runs the freshness decision of `.codex/hooks/validate-feature-review-coverage-freshness.ps1`, a function-text twin of the Claude file. It blocks once when no audit is named, when audits of different items are named, or when the named audit is absent beneath the item root.
- Cleanup legs (#1026): a `cleanup-merged-worktrees` run writes no checkpoint, so the preimplementation gate (`.claude/hooks/enforce-orchestration-preimplementation-gate-cleanup.ps1` and its `.codex/hooks/` twin), the PR-authoring gate (`.claude/hooks/enforce-pr-author-skill.cleanup.ps1`), and the model-routing gate (`.claude/hooks/enforce-model-routing-receipt.ps1`) carry allow-side cleanup legs, evaluated only where each gate would otherwise deny, that share the pure predicates of `hook-cleanup-context.ps1`. The legs admit a Write of the session-root manifest `artifacts/orchestration/cleanup-worktrees-manifest.json` with valid content (an Edit stays denied), Write or Edit of paths under `docs/` or `.claude/agent-memory/` and of the pr-author receipt inside the consolidation worktree on branch `documentationandmemories`, `git -C <consolidation root> add` and `commit` of those paths, `Agent(pr-author)` with `branch: documentationandmemories`, and `gh pr create --head documentationandmemories --base main` while a fresh valid manifest exists at the session root and the pushed `refs/remotes/origin/documentationandmemories` resolves to the same commit as the consolidation worktree `HEAD`. A preimplementation-gate denial appends a cleanup sub-code (`Cleanup leg not applied`) only after a cleanup leg has identified the consolidation worktree as the target and a later condition fails; a call rejected by a prefilter keeps the unchanged deny text even when its target is the consolidation worktree, as does every other call.
- Scratch rule (#1026): the preimplementation gate allows a Write or Edit of an absolute local path that lies outside every registered worktree and the session root and under a temporary root, read through the seam `Get-OrchestrationGateTemporaryRoot` (the long-name `GetTempPath()` value and the `TEMP`, `TMP`, and `TMPDIR` values, which can carry the 8.3 short-name spelling). The rule fails closed when any registered worktree lies under a temporary root.
- Post-fan-in allowance (#1136): `Get-OrchestrationEpicScopeDecision` in each surface's `enforce-orchestration-preimplementation-gate-epic-scope.ps1` dot-sources (guarded) the byte-identical `hook-epic-fan-in.ps1` from `.claude/hooks/` and `.codex/hooks/`, and allows a call whose epic-scope readiness failure is exactly `merge-in-progress` when the fan-in predicate `Test-EpicFanInComplete` holds (`route_id` `epic`, `integration_branch` equal to the worktree HEAD, and a non-empty `features[]` whose every `merge_status` is `merged` or `worktree_removed`) and `Get-EpicFanInAllowance` admits the call. The allowlist is a Write or Edit of `artifacts/pr_body_<N>.md` or `artifacts/pr_body_<N>.receipt.json`, a `git add` of `docs/features/epics/<epic_feature_folder>/epic-status.md`, and a `git commit` carrying only `-m`, `--message`, `-F`, `--file`, or `--trailer` with either `-- <status doc>` or a staged index (read through `Get-OrchestrationGateStagedIndex`) that is exactly the status document. Every other deny and deny text is unchanged; it is a policy-level control, not a security control. Merged-feature follow-up allowance (#1141): for the same exact `merge-in-progress` failure, the same scope decision also allows a call that `Get-EpicMergedFeatureFollowUpAllowance` in `hook-epic-fan-in.ps1` admits, without requiring fan-in completeness. It requires `route_id` `epic` and `integration_branch` equal to the worktree HEAD, and derives allowed roots only from `features[]` entries of the epic checkpoint whose `merge_status` is `merged` or `worktree_removed`, whose `feature_folder` basename (after an optional `docs/features/active/` or `docs/features/completed/` prefix) is one plain segment, whose `merge_commit_sha` is 40 or 64 lowercase hex characters, and whose `pr_number` is an integer above 0: `docs/features/active/<basename>/`, `docs/features/completed/<basename>/`, and the status document. It admits a Write or Edit under those roots, a `git add [--] <paths>`, and a `git commit` with the same five options and either `-- <paths>` or a non-empty staged index, where every path lies under a root and carries no backslash, glob character, `.` or `..` segment, or leading `/`. No per-item checkpoint is read.
- Enforcement hooks do not invoke Python; bash is preferred and PowerShell is acceptable (`tests/scripts/claude-runtime/enforcement-hooks-no-python-invocation.Tests.ps1`).
- Merge guard (#1097): `.claude/hooks/enforce-epic-merge-gate-review.ps1`, byte-identical to its `.codex/hooks/` twin, is dot-sourced by both `enforce-epic-merge-gate.ps1` gates and is inert unless the checkpoint it reads records `review_mode: "concurrent"`. Under that key it denies with `REVIEW_GATE_NOT_PASSED`, `REVIEW_GATE_HEAD_STALE`, or `REVIEW_GATE_HEAD_UNRESOLVED`, each after the token `EPIC_MERGE_GATE_BLOCKED`. It reads the checkpoint of the item target that its gate resolves; on Claude, merge text that names no single pull request also reads the items of at most the first 4 numbers in the text (the shape rule). It is a policy-level control, not a security control (decision D10 in `.claude/rules/orchestrator-state.md`).
- Child-CI helper (#1130): `.claude/hooks/enforce-epic-merge-gate-child-ci.ps1`, byte-identical to its `.codex/hooks/` twin, is dot-sourced by both `enforce-epic-merge-gate.ps1` gates. Their epic-child branch allows a merge only when `Get-EpicMergeGateChildCiDecision` verifies, through one bounded `gh pr view` and one bounded `gh run list --commit` call, that `ci_gate.head_sha` equals the live PR head and that the newest run of the workflow named `CI` on that head is a completed, successful `pull_request` run or the `workflow_dispatch` run recorded in `ci_gate.dispatch_run_id`. Every other case denies with `EPIC_CHILD_CI_NOT_VERIFIED` after the token `EPIC_MERGE_GATE_BLOCKED`, without falling through to a later branch. The workflow name `CI` is an assumption, and a `push`-event run is not accepted.
- Owner-directive check (#1139): `.claude/hooks/validate-orchestrator-output.ps1` imports `.claude/lib/orchestrator-state/OrchestratorStateOwnerDirectives.psm1` with a guarded, fail-closed import and, for a checkpoint whose top-level property names include `owner_directives` or `owner_directive_records` (ordinal comparison), calls `Get-OrchestratorStateOwnerDirectiveError` after the routing dispatch and before the type-specific branches. Any error blocks the stop with `OWNER_DIRECTIVE_BLOCKED`, repairable; a checkpoint without either key is unaffected. The check is Claude only: there is no Codex twin, and the Python and TypeScript validators ignore both keys.

## Worktree Python Environment

- Poetry honors an inherited `VIRTUAL_ENV` over the in-project `poetry.toml` setting. When the session exported `VIRTUAL_ENV` for the main checkout, a mutating Poetry command run in an agent worktree writes into the main checkout's `.venv` and repoints its editable installs at the worktree.
- In an agent worktree, run `env -u VIRTUAL_ENV poetry install` once from the worktree root before any other Poetry command, then run every Poetry command as `env -u VIRTUAL_ENV poetry run ...`. A bare `poetry run` without that install creates a nearly empty `.venv` in the worktree. An agent whose Bash working directory is not the worktree root runs `env -u VIRTUAL_ENV poetry -C <worktree root> install` instead of changing directory first, and passes the same `-C <worktree root>` option to every later Poetry command.
- `.claude/hooks/enforce-worktree-poetry-venv.ps1` (Codex twin `.codex/hooks/enforce-worktree-poetry-venv.ps1`, helper `worktree-poetry-venv-policy.ps1` in each folder) denies `poetry install`, `sync`, `add`, `remove`, and `update` with `WORKTREE_VENV_BLOCKED:` when `VIRTUAL_ENV` lies outside the target project and the command does not unset it. The Claude hook fails open on an unparseable payload; the Codex twin follows the Codex exit-2 convention for empty or unparseable stdin. It is a guard against a known foot-gun, not a security control.
- The worktree's own `.venv` points editable installs at the worktree, so coverage measures the worktree's files and no `PYTHONPATH` override is needed.
- Destination repositories receive the hook, the helper, the registrations, and this section through a push-down refresh after the extension release that carries them.

## 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.
- Concurrent checkpoints (#1097): until the extension release that carries the concurrent-review rule is installed, installed MCP accepts a `review_mode: "concurrent"` checkpoint that the PowerShell stop hook and the Python CLI reject, so such a checkpoint is checked with `scripts/dev_tools/validate_orchestration_artifacts.py` in its `orchestrator-state` subcommand with `--require-complete`.
- Light remediation checkpoints (#1097): installed MCP applies invariant 8 only after the extension release that carries it is installed. Until then a Claude run validates a light checkpoint through `scripts/dev_tools/validate_orchestration_artifacts.py` in its `orchestrator-state` subcommand, and on Codex, whose orchestrator requires the installed MCP validator with no fallback, the light path is unavailable.
- The docs tools (`run_docs_check`, `run_docs_inventory`, `run_docs_coverage`, `update_docs_ledger`, `generate_docs_reference`, `validate_docs_artifacts`) run the workspace's `.claude/lib/docs/Invoke-DocsCommand.ps1` with `pwsh`, so a branch edit to the docs lib applies through MCP immediately, while the TypeScript wrapper is the installed extension.

## 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.11, 3.12, and 3.13 (`_quality-checks.yml`: Black check, Ruff, Pyright, the Codex generator `--check`, the tier classification, and Pytest on every version; Pytest with line and branch coverage and the coverage-threshold check on the JSON report totals run on 3.13 only); `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`); the `poshqc` group below; and `CI Required Gate` (job `ci-required-gate`, issue #1074), which needs every other `ci.yml` job, runs under `if: always()` on `ubuntu-latest`, and passes `toJSON(needs)` to `scripts/ci/Invoke-CiRequiredGate.ps1`. The gate is green on a full run only when every needed job is `success`, and on a docs-only run only when `CI full run`, `root-typescript-tests`, and `NPM Audit Gate` are `success` or `skipped` and every other needed job is `success`; a `failure`, `cancelled`, or unknown result, a `Change scope` result other than `success`, and unreadable input are red. `tests/scripts/workflows/CiRequiredGateWorkflow.Tests.ps1` pins its `needs:` set against the other job ids of `ci.yml`.
- PowerShell CI (`_poshqc.yml`): `poshqc / PowerShell QC static` (format, analyze, and the `Invoke-PoshQCLeakScan` leak scan 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, through one of two comparisons. Green-run base: 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 present and an ancestor of the current head, is on the allowlist `config/ci-docs-only-paths.json`; the reason is `DOCS_ONLY_SINCE_<green head sha>`. Merge-base fallback (issue #973): when the green-run step ends with no earlier full green run (`NO_FULL_GREEN_RUN`), a missing base (`BASE_NOT_PRESENT`), or a non-ancestor base (`BASE_NOT_ANCESTOR`), and the pull request's base ref is exactly `main`, the script computes `git merge-base` of the payload base SHA (`BASE_SHA`, from `github.event.pull_request.base.sha`; the base ref arrives as `BASE_REF`) and the head, lists the files changed since that merge base with the same diff arguments, and decides `DOCS_ONLY_SINCE_MERGE_BASE_<merge base sha>` when every changed file is allowlisted. Both comparisons run the diff with rename detection off, so both the old and the new path of a rename are classified. A path is allowlisted when it starts with `docs/features/active/`, `docs/features/archive/`, `docs/features/completed/`, `docs/features/epics/`, `docs/features/parallel/`, `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 or a missing or non-ancestor base when the base ref is not `main`, a merge base that cannot be resolved (`MERGE_BASE_UNRESOLVED`, for example a blank base SHA or a base commit missing from the checkout), a failed ancestry check, 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 job that runs with its steps gated still starts under its full-run check name with every step skipped, so it 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. Eight currently required contexts therefore never report on a docs-only run: `poshqc / PowerShell QC shard 1`, `poshqc / PowerShell QC shard 2`, `poshqc / PowerShell QC shard 3`, `root-typescript-tests / Root TypeScript Tests (ubuntu-latest)`, `root-typescript-tests / Root TypeScript Tests (windows-latest)`, `NPM Audit Gate / npm audit (.)`, `NPM Audit Gate / npm audit (extensions/drm-copilot)`, and `NPM Audit Gate / npm audit (packages/mcp-server)`, so a docs-only head stays blocked under the 20-context ruleset. `CI Required Gate` passes on a docs-only run, because it accepts `skipped` for exactly those skipped callers. 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, read through a read-only `gh api` call on 2026-11-04 (20 contexts, each with `integration_id` 15368): `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.11)`, `quality-checks7 / Code Quality & Tests (3.12)`, `quality-checks7 / Code Quality & Tests (3.13)`, `build-check / Build Package`, `NPM Audit Gate / npm audit (extensions/drm-copilot)`, `NPM Audit Gate / npm audit (.)`, `NPM Audit Gate / npm audit (packages/mcp-server)`, `root-typescript-tests / Root TypeScript Tests (ubuntu-latest)`, `root-typescript-tests / Root TypeScript Tests (windows-latest)`, `poshqc / PowerShell QC shard 1`, `poshqc / PowerShell QC shard 2`, `poshqc / PowerShell QC shard 3`, `poshqc / PowerShell QC static`, `poshqc / PowerShell hook suites (Linux)`. After the owner's post-merge ruleset edit (issue #1074 runbook), the single required context is `CI Required Gate` (`integration_id` 15368), and the individual job contexts remain visible but are no longer required.
- Refresh rule: a change that renames a job, adds or removes a `ci.yml` job or 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. A new `ci.yml` job must also be added to the `needs:` list of `ci-required-gate`; `tests/scripts/workflows/CiRequiredGateWorkflow.Tests.ps1` fails until it is.
- 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 matrix job skipped at job level reports no expanded context (its matrix name is never expanded), and a reusable-workflow caller skipped in `ci.yml` reports no nested contexts, so each such required context stays pending.
- A pull request into a branch other than `main`, `development`, or `epic/**` gets no CI run; dispatch `ci.yml` manually for it.
- Epic-child dispatch (#1130): when an epic child's head has no `CI` check, for example in a destination whose `CI` workflow does not list `epic/**` in its `pull_request` branches, S9 dispatches `CI` once with `gh workflow run CI --ref <child branch>` and records the run's `databaseId` as `ci_gate.dispatch_run_id`; the merge gate accepts that run and no other `workflow_dispatch` run.
- Concurrent-review join (#1097): under `review_mode: "concurrent"` a green `CI Required Gate` alone does not permit a merge. The join in `## Concurrent Review and CI (review_mode)` of `.claude/skills/orchestrate/SKILL.md` also needs the last `review_outcomes[]` entry to be `PASS` at a current head, and a `CI full run` check with conclusion `success` at the reviewed head or at an ancestor of it whose diff to the reviewed head lists only `feature-folder` paths. The parallel parent withholds `merge_status: ci_green` and the merge until then.

## 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.
- Files in one shard share a process, so a leak surfaces when shard contents change.
- `Invoke-PoshQCLeakScan` is the check for such leaks. It runs in `poshqc / PowerShell QC static`, and a stale entry in `config/poshqc-leak-allowlist.json`, one that matches no finding, fails that job, so a fixed finding requires removing its entry.

## Contract Tests That Pin Mirrored Files

Run these after editing any mirrored or bundled file; each is under `tests/scripts/dev_tool

…(truncated)
