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-executorhas no PowerShell tool. Itstools:list is Read, Grep, Glob, Edit, Write, severalBash(...)entries, the fourmcp__drm-copilot__run_poshqc_*tools, andmcp__drm-copilot__validate_orchestration_artifacts. A(pattern)suffix on atools: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-plannerhas no Bash. It has Read, Grep, Glob, Edit, Write, andmcp__drm-copilot__validate_orchestration_artifacts, so it can validate a plan with the installed validator before handoff but cannot run any toolchain command.task-researcherhas Read, Grep, Glob, WebFetch, and Write. It cannot rungit showorgh; facts that need either are marked for the orchestrator to confirm.orchestratorand the main session running theorchestrateskill have Bash, the PoshQC and validation MCP tools, and theAgenttool. 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 ashlauncher script stored underSCRATCHthat 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
orchestratorat depth 2, and its specialists at depth 3, so they need Claude Code 2.1.219 or later withCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHunset or at least 3, started from the main session. An agent that starts without theAgenttool recordsblocked_reason: "spawn_agent_unavailable"and returns a line beginningAGENT_TOOL_UNAVAILABLE:;enforce-epic-invocation-origin.ps1denies a chain delegation withNESTING_DEPTH_INSUFFICIENT:when the configured value is below 3, and the## Nesting Depthsection 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, orwsl, heredocs,printf --, acd <path> &&prefix beforegit,git -C <other worktree>, embeddedjqfilter strings, an unquoted shell variable in an option position, and loops or other compound constructs aroundsh. Text that passes includessh <file>.shwith a literal path,npx,poetry run python <script>,gh, worktree-scopedgit, andgit commit -F <file>. No file under.claude/hooks/implements this guard, and no settings file registers it. - Repository hooks.
.claude/hooks/validate-bash.ps1(functionsGet-BlockedBashPattern,Get-CdChainedReadCommandMatch,Get-BashBlockReason) denies destructive patterns (rm -rf, forced pushes,git reset --hard, recursive forced removal) and acdfollowed later in the same command by a file-reading command such asgrep,cat,head,tail,less,more,awk, orsed -n; an output filter such as| tail -n 20counts. 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.ps1carries the destructive patterns and has no cd-chained leg..claude/hooks/enforce-parallel-worktree-removal-gate.ps1denies the literal worktree-removal command anywhere in a command. - Preferred forms (#1165). Never chain
cdbefore 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 andgit -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 acddoes 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 -cprogram exits 0 without running. Put Python helpers in a file underSCRATCHand 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 withREVIEW_GATE_HEAD_UNRESOLVED. That includes prose holdingpr merge,pr (, orpr $, and a merge followed by a line feed or;. Issue a merge as one plaingh pr mergeof one number in its own Bash call, and pass commit messages throughgit commit -Fwith 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 (
runPoshQcWorkflowinextensions/drm-copilot/src/repo-automation-service.ts), andRepoAutomationExecutionResulthas no exit-code or output field. Anok: trueresult 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 fromartifacts/pester/powershell-coverage.xml, and analyzer findings from a directInvoke-ScriptAnalyzerrun withscripts/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.psd1and callInvoke-PoshQCParallelTestfrom ash-launched PowerShell 7. The coverage population is derived byInvoke-PoshQCTest, which each shard runs, fromconfig/poshqc-coverage.json; there is no hand-maintained coverage path list. Invoke-PoshQCParallelTestreturns an object whoseExitCodeis 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 underartifacts/pester/parallel/shard-<i>/.Invoke-Pesterwithout-EnableExit(orRun.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 theshlauncher route, importing the branch-currentscripts/powershell/PoshQC/PoshQC.psd1and callingInvoke-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_REQUIREDand the fourth distinct non-test Python file withPYTHON_LARGE_PATH_REQUIRED(.claude/hooks/enforce-powershell-batch-budget.ps1and.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.jsonin the worktree containing the edited file selects thelarge,remediation, orpreparationroute and is not terminal (Test-BatchBudgetLargePathRoutein.claude/hooks/enforce-batch-budget-route.ps1). That worktree is resolved byResolve-HookTargetWorktreein.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, becauseartifacts/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
.ps1file counts when it resolves inside the worktree root and outside that root'sartifacts/directory. Files underSCRATCH, 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 namedartifactselsewhere 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
WriteandEditcalls are seen (the hook matcher isWrite|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>.jsonwith the key fromGet-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-HookTargetWorktreeresolves 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-Cvalues and absolute operands ofgit addandgit committhrough 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 agh pr createorgh pr editcommand names (--head,--branch, or abranch: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 readartifacts/orchestration/orchestrator-state.jsonare 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 throughResolve-SubagentStopTargetWorktreein.claude/hooks/subagentstop-target-worktree.ps1, which callsResolve-HookTargetWorktreewith an absolute advertised path or with the delegation prompt read from the subagent transcript (itsbranch: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 rootCLAUDE.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.ps1throughvalidate-orchestrator-output-target.ps1) resolves theorchestrator-statecheckpoint 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 withORCHESTRATOR_CHECKPOINT_UNRESOLVED:before any read; with no transcript, no identity, or a resolver failure, the session worktree is validated and the noteORCHESTRATOR_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.ps1selects the policy audit named in the reviewer'slast_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 throughResolve-HookTargetWorktreein.codex/hooks/hook-target-worktree.ps1, and a relative path uses the session root. The hook reads the PR context summary, the rootCLAUDE.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-worktreesrun writes no checkpoint, so the preimplementation gate (.claude/hooks/enforce-orchestration-preimplementation-gate-cleanup.ps1and 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 ofhook-cleanup-context.ps1. The legs admit a Write of the session-root manifestartifacts/orchestration/cleanup-worktrees-manifest.jsonwith valid content (an Edit stays denied), Write or Edit of paths underdocs/or.claude/agent-memory/and of the pr-author receipt inside the consolidation worktree on branchdocumentationandmemories,git -C <consolidation root> addandcommitof those paths,Agent(pr-author)withbranch: documentationandmemories, andgh pr create --head documentationandmemories --base mainwhile a fresh valid manifest exists at the session root and the pushedrefs/remotes/origin/documentationandmemoriesresolves to the same commit as the consolidation worktreeHEAD. 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-nameGetTempPath()value and theTEMP,TMP, andTMPDIRvalues, 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-OrchestrationEpicScopeDecisionin each surface'senforce-orchestration-preimplementation-gate-epic-scope.ps1dot-sources (guarded) the byte-identicalhook-epic-fan-in.ps1from.claude/hooks/and.codex/hooks/, and allows a call whose epic-scope readiness failure is exactlymerge-in-progresswhen the fan-in predicateTest-EpicFanInCompleteholds (route_idepic,integration_branchequal to the worktree HEAD, and a non-emptyfeatures[]whose everymerge_statusismergedorworktree_removed) andGet-EpicFanInAllowanceadmits the call. The allowlist is a Write or Edit ofartifacts/pr_body_<N>.mdorartifacts/pr_body_<N>.receipt.json, agit addofdocs/features/epics/<epic_feature_folder>/epic-status.md, and agit commitcarrying only-m,--message,-F,--file, or--trailerwith either-- <status doc>or a staged index (read throughGet-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 exactmerge-in-progressfailure, the same scope decision also allows a call thatGet-EpicMergedFeatureFollowUpAllowanceinhook-epic-fan-in.ps1admits, without requiring fan-in completeness. It requiresroute_idepicandintegration_branchequal to the worktree HEAD, and derives allowed roots only fromfeatures[]entries of the epic checkpoint whosemerge_statusismergedorworktree_removed, whosefeature_folderbasename (after an optionaldocs/features/active/ordocs/features/completed/prefix) is one plain segment, whosemerge_commit_shais 40 or 64 lowercase hex characters, and whosepr_numberis 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, agit add [--] <paths>, and agit commitwith 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 bothenforce-epic-merge-gate.ps1gates and is inert unless the checkpoint it reads recordsreview_mode: "concurrent". Under that key it denies withREVIEW_GATE_NOT_PASSED,REVIEW_GATE_HEAD_STALE, orREVIEW_GATE_HEAD_UNRESOLVED, each after the tokenEPIC_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 bothenforce-epic-merge-gate.ps1gates. Their epic-child branch allows a merge only whenGet-EpicMergeGateChildCiDecisionverifies, through one boundedgh pr viewand one boundedgh run list --commitcall, thatci_gate.head_shaequals the live PR head and that the newest run of the workflow namedCIon that head is a completed, successfulpull_requestrun or theworkflow_dispatchrun recorded inci_gate.dispatch_run_id. Every other case denies withEPIC_CHILD_CI_NOT_VERIFIEDafter the tokenEPIC_MERGE_GATE_BLOCKED, without falling through to a later branch. The workflow nameCIis an assumption, and apush-event run is not accepted. - Owner-directive check (#1139):
.claude/hooks/validate-orchestrator-output.ps1imports.claude/lib/orchestrator-state/OrchestratorStateOwnerDirectives.psm1with a guarded, fail-closed import and, for a checkpoint whose top-level property names includeowner_directivesorowner_directive_records(ordinal comparison), callsGet-OrchestratorStateOwnerDirectiveErrorafter the routing dispatch and before the type-specific branches. Any error blocks the stop withOWNER_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_ENVover the in-projectpoetry.tomlsetting. When the session exportedVIRTUAL_ENVfor the main checkout, a mutating Poetry command run in an agent worktree writes into the main checkout's.venvand repoints its editable installs at the worktree. - In an agent worktree, run
env -u VIRTUAL_ENV poetry installonce from the worktree root before any other Poetry command, then run every Poetry command asenv -u VIRTUAL_ENV poetry run .... A barepoetry runwithout that install creates a nearly empty.venvin the worktree. An agent whose Bash working directory is not the worktree root runsenv -u VIRTUAL_ENV poetry -C <worktree root> installinstead 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, helperworktree-poetry-venv-policy.ps1in each folder) deniespoetry install,sync,add,remove, andupdatewithWORKTREE_VENV_BLOCKED:whenVIRTUAL_ENVlies 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
.venvpoints editable installs at the worktree, so coverage measures the worktree's files and noPYTHONPATHoverride 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_artifactsapplies 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.pywith itsplansubcommand, 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 withscripts/dev_tools/validate_orchestration_artifacts.pyin itsorchestrator-statesubcommand 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.pyin itsorchestrator-statesubcommand, 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.ps1withpwsh, 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.ymltriggers onpushtomainanddevelopment, onpull_requesttomain,development, andepic/**, onworkflow_dispatch, and onmerge_group(types: [checks_requested], added by issue #952), with no path filters. When the merge queue onmainis enabled, every required check is produced by amerge_grouprun ofci.ymlas well as by the pull-request run;.github/workflows/README.md(## Triggers) records the trigger set.- Jobs in
ci.ymland their check names:Change scope(jobchanges, the change-scope decision below);CI full run(jobfull-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(itssafety checkstep carriescontinue-on-error: trueand 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>)onubuntu-latestandwindows-latest;root-typescript-tests / Root TypeScript Tests (<os>)onubuntu-latestandwindows-latest;NPM Audit Gate / npm audit (<manifest>)(the calling job carries the nameNPM Audit Gate); theposhqcgroup below; andCI Required Gate(jobci-required-gate, issue #1074), which needs every otherci.ymljob, runs underif: always()onubuntu-latest, and passestoJSON(needs)toscripts/ci/Invoke-CiRequiredGate.ps1. The gate is green on a full run only when every needed job issuccess, and on a docs-only run only whenCI full run,root-typescript-tests, andNPM Audit Gatearesuccessorskippedand every other needed job issuccess; afailure,cancelled, or unknown result, aChange scoperesult other thansuccess, and unreadable input are red.tests/scripts/workflows/CiRequiredGateWorkflow.Tests.ps1pins itsneeds:set against the other job ids ofci.yml. - PowerShell CI (
_poshqc.yml):poshqc / PowerShell QC static(format, analyze, and theInvoke-PoshQCLeakScanleak scan onwindows-latest); the shard matrixposhqc / PowerShell QC shard 1,shard 2, andshard 3(Invoke-PoshQCTest -ShardIndex -ShardCountover the scan folders ofconfig/poshqc-scan.json, with coverage, onwindows-latest); the aggregatorposhqc / PowerShell QC, which requires the static and shard jobs to succeed, verifies shard completeness against a Pester discovery count, and merges shard coverage; andposhqc / PowerShell hook suites (Linux), which runs onlytests/scripts/claude-hooksandtests/scripts/codex-hooksonubuntu-latestwith 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 scopejob runsscripts/ci/Invoke-CiChangeScope.ps1and publishes the job outputcode. The decision iscode=false(docs-only) only on apull_requestevent from this repository, through one of two comparisons. Green-run base: every file changed since the newest successfulci.ymlrun on the pull-request branch whoseCI full runjob succeeded, and whose head commit is present and an ancestor of the current head, is on the allowlistconfig/ci-docs-only-paths.json; the reason isDOCS_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 exactlymain, the script computesgit merge-baseof the payload base SHA (BASE_SHA, fromgithub.event.pull_request.base.sha; the base ref arrives asBASE_REF) and the head, lists the files changed since that merge base with the same diff arguments, and decidesDOCS_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 withdocs/features/active/,docs/features/archive/,docs/features/completed/,docs/features/epics/,docs/features/parallel/,docs/features/potential/, ordocs/research/, does not start withdocs/features/templates/ordocs/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, andworkflow_dispatchevents, 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 notmain, 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 carriescontinue-on-error: trueand the callers compare the output with!= 'false', so a failed or missing decision also gives a full run. - Docs-only behavior (
code=false):ci.ymlpassesrun-heavy: falseto_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 reportssuccesswithout running its suite. In_poshqc.ymlthe aggregatorposhqc / PowerShell QCruns with every step gated, andposhqc / PowerShell QC static, the shard jobs, andposhqc / PowerShell hook suites (Linux)are skipped at job level.docs-validation / Documentation Validationruns in full.root-typescript-tests,NPM Audit Gate, andCI full runare 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), andNPM Audit Gate / npm audit (packages/mcp-server), so a docs-only head stays blocked under the 20-context ruleset.CI Required Gatepasses on a docs-only run, because it acceptsskippedfor exactly those skipped callers. Asuccesson a docs-only commit is therefore not evidence that the heavy suites pass for that commit; that evidence is the newest run whoseCI full runjob 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 runjob marks it as a base for later docs-only decisions. A standaloneworkflow_dispatchof a reusable workflow, or a caller that omitsrun-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 apicall on 2026-11-04 (20 contexts, each withintegration_id15368):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 isCI Required Gate(integration_id15368), 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.ymljob 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-onlygh api repos/drmoisan/drm-copilot/rulesets/15241672call before relying on them. A newci.ymljob must also be added to theneeds:list ofci-required-gate;tests/scripts/workflows/CiRequiredGateWorkflow.Tests.ps1fails 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 inci.ymlreports no nested contexts, so each such required context stays pending. - A pull request into a branch other than
main,development, orepic/**gets no CI run; dispatchci.ymlmanually for it. - Epic-child dispatch (#1130): when an epic child's head has no
CIcheck, for example in a destination whoseCIworkflow does not listepic/**in itspull_requestbranches, S9 dispatchesCIonce withgh workflow run CI --ref <child branch>and records the run'sdatabaseIdasci_gate.dispatch_run_id; the merge gate accepts that run and no otherworkflow_dispatchrun. - Concurrent-review join (#1097): under
review_mode: "concurrent"a greenCI Required Gatealone does not permit a merge. The join in## Concurrent Review and CI (review_mode)of.claude/skills/orchestrate/SKILL.mdalso needs the lastreview_outcomes[]entry to bePASSat a current head, and aCI full runcheck with conclusionsuccessat the reviewed head or at an ancestor of it whose diff to the reviewed head lists onlyfeature-folderpaths. The parallel parent withholdsmerge_status: ci_greenand 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:/workspacepath failspath.isAbsoluteand path joins on Linux. _shell-coverage.ymlchecks out at depth one, soorigin/maindoes not exist in that job; no test may diff against it.- The Linux hook-suite job runs
tests/scripts/claude-hooksandtests/scripts/codex-hookson a case-sensitive file system: useJoin-Path, forward-slash relative paths, exact file-name case, and no drive letters or backslash literals. - The
.gitattributesrule* text=auto eol=lfnormalizes 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-PoshQCLeakScanis the check for such leaks. It runs inposhqc / PowerShell QC static, and a stale entry inconfig/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)