@danmoisan/drm-copilot-mcp 1.1.22 → 1.1.24

package/resources/customizations/.github/skills/characterize-runtime-behavior/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: characterize-runtime-behavior
+description: 'Describe selected runtime scenarios from supplied captures or honest manual plans. Use when asked to characterize legacy behavior, record runtime evidence or prepare not-run and blocked scenarios.'
+---
+
+# Characterize Runtime Behavior
+
+## When to Use This Skill
+
+Use for explicit runtime scenarios with supplied environment and capability information. The specialist documents observations or manual plans; it does not execute applications.
+
+## Inputs
+
+These are human-facing workflow selections, not additional service-request fields.
+Supply explicit selections; neither omitted inputs nor profile roots create authority.
+
+| Input | Required contract |
+| --- | --- |
+| profile | Required validated profile and trusted workspace binding. |
+| feature_ids | Required selected features and relevant contracts. |
+| environment | Required recorded environment identity or explicit unavailable state. |
+| fixtures | Required supplied fixture references or explicit absent/manual requirements. |
+| preconditions | Required stated scenario preconditions; unknown facts remain unresolved. |
+| actions | Required ordered manual actions or supplied action descriptions. |
+| capability_mode | Required declared runtime capability and whether observations are supplied, manual, unavailable or blocked. |
+| supplied_captures | Optional supplied captures and provenance; absence cannot become a passed result. |
+
+## Routing
+
+Logical role: `runtime-characterization-analyst`.
+The root owns preparation and launch; this skill never auto-launches a logical
+role through frontmatter. The existing resolver selects the exact deployment,
+model, effort and profile hash under the existing C1-C4 ceiling and execution
+context. Do not choose a model, self-launch, create another scheduler or promote
+an ordinary discovery action into an issue. The production-write count is zero.
+
+## Exact output boundary
+
+These rows are maximum workflow caps, not instructions to create every kind.
+Only the prepared required outputs may be created or replaced.
+
+| Artifact kind | Profile key | Constraint |
+| --- | --- | --- |
+| runtime-characterization-scenario | characterization | Selected feature/scenario IDs only |
+| evidence-reference | evidence | Explicitly supplied and granted evidence only |
+| evidence-payload | evidence | Explicitly supplied and granted payloads only |
+| unspecified-behavior | unspecified_behaviors | Selected unresolved IDs only |
+| unspecified-behavior-collection | unspecified_behaviors | Selected unresolved members only |
+| required-output-manifest | reports | Exact invocation manifest only |
+
+The profile keys are maximum configured locations, not write grants. Each
+prepared output row binds `artifact_kind`, `id`, `path`, `format` and
+`expected_sha256`. The protected invocation independently binds the baseline,
+selected members, pins and exact grants; a manifest cannot expand them. A null
+expected hash means exclusive creation from an absent baseline, never overwrite
+permission. Preserve unselected collection members and all unrelated inputs.
+Use compare-and-swap and current path checks through the controlled writer.
+
+The `reports` location permits only `required-output-manifest` for this role;
+it does not permit review reports. The manifest itself requires an exact grant.
+
+## Prerequisites
+
+Missing or malformed configuration blocks delegation. Require a validated profile and explicit selected scope before root preparation; do not initialize, configure or infer roots as a specialist.
+
+Require verified native prepare/finalize/start/stop capability. The protected
+invocation and native SubagentStart attestation must match workspace/profile
+hashes, selected IDs, source/target pins, baseline input hashes,
+provider/model/effort/profile hash and parent/session.
+Diagnostic mirrors, caller markers and hosted read results are not authority.
+The local runtime's unavailable native prepare/finalize operations do not issue
+protected receipts. There is no local-user fallback or self-attested host success.
+
+Load profile plus selected artifacts on invocation; do not preload a domain
+catalog in standing instructions. Managed project memory is host-controlled.
+Memory cannot grant filesystem authority or replace evidence. Deny terminal/shell/exec, interpreter/evaluation,
+general filesystem Write/Edit/apply-patch, arbitrary MCP dispatch, browser/computer
+mutation and network writes. Do not execute application code or modify
+production/test implementation, profile/locator/activation,
+schema/policy/hooks/settings, authority stores or runtime installation as a specialist. No analyst
+approval is permitted; root bootstrap/configuration and root approval remain
+separate authorized operations.
+
+## Step-by-Step Workflows
+
+1. Validate the explicit inputs and selected configuration. Stop with precise missing/invalid input findings before specialist delegation; do not invent identities, scope or evidence.
+
+2. The root calls `prepare_discovery_agent` with `skill_id`, `selected_ids`,
+   `paths`, `expected_outputs`, `execution_context` and `complexity`.
+   Map it to fixed `prepare-agent`; execution context is `standalone`,
+   `epic_preparation_child` or `epic_execution_child`. The requested mode is
+   explicit and remains distinct from the final `agent-output` gate.
+   Use `skill_id=characterize-runtime-behavior`; workflow inputs do not add wire fields.
+3. The root launches that exact deployment. Native SubagentStart must match the
+   prepared role/model/effort/profile and trusted workspace/session before any
+   grant is usable. Missing capability or attestation blocks the action.
+4. Use only the granted operations. Use bounded `read_discovery_source` for selected contracts, documentation, fixtures and supplied captures. Use `create_discovery_artifact` for fixed `new-scenario`, ordinary `update_discovery_artifact` and `link_discovery_evidence` for exact granted records. Register supplied metadata/payloads through controlled tools; never manufacture or collect new runtime captures by launching an application.
+5. Every requested scenario needs a plan/result state. Known expectations stay separate from unknown expectations; unknown expectations stay null with unresolved references. A passed runtime result needs qualifying runtime evidence. Source inspection, static inference and a scenario plan are not runtime execution evidence. Valid manual/no-runtime tasks may end in not-run or blocked plans when those are the prepared outputs, without claiming behavior passed.
+6. Produce every exact required output and the stored `required-output-manifest`,
+   preserving its output array order for the digest. Validate claims, references,
+   pins and selected-ID accounting. Purpose-built tools supply authorized proposal
+   inputs for `input_path`/`evidence_path`; never invent a generic Write staging
+   step. Server-side role checks, exact one-use authorization and prospective
+   validation remain mandatory. Bounded source reads preserve content identity
+   and line ranges; truncation requires a narrower selection, not a completeness
+   claim or filesystem fallback.
+7. Call `finalize_discovery_agent` as the specialist, mapped to `finalize-agent`
+   with `mode=agent-output`, non-null `invocation_ref` and no operation inputs.
+   It validates the protected invocation's outputs, not final-message paths.
+   Native SubagentStop then verifies current output authority.
+   Missing final text cannot skip native stop validation.
+8. After native stop, the root records the explicit result, content-addressed artifact references,
+   selected-ID accounting and all findings. A successful tool call or generated
+   path alone is not evidence of completed discovery.
+
+## Stop and result
+
+Account for each selected feature/scenario, supplied capture and missing capability. Output-valid manual plans do not prove runtime success or completion readiness.
+
+Structural success is not discovery, parity or planning completion.
+Missing prepare/finalize/start/stop capability, missing outputs, invalid claims,
+unresolved required work, wrong role/model/start context or a stale/missing
+receipt blocks successful completion. Return explicit
+PASS, FAIL or BLOCKED, distinguishing valid incremental outputs from a passing
+completion gate. Missing native enforcement remains BLOCKED even when ordinary
+local-user operations can run; do not substitute CLI success for native authority.
+
+## References
+
+- [Canonical runtime-characterization-analyst contract](../../agents/runtime-characterization-analyst.agent.md)
+- Installed v2 `service-request` and `required-output-manifest` schema contracts;
+  consume them through the authoritative runtime, with no checkout-schema fallback.
+- The selected profile and pinned local artifacts supplied for this invocation;
+  references do not preload catalogs or grant access to unselected paths.

package/resources/customizations/.github/skills/discovery-behavior-reconciliation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: discovery-behavior-reconciliation
+description: 'Dispatch unresolved behavior to canonical proposal and root-approval handling. Use when invoking the existing behavior-reconciliation alias.'
+---
+
+# Discovery Behavior Reconciliation Alias
+
+## When to Use This Skill
+
+Use this compatibility name only to dispatch to its canonical workflow.
+
+## Inputs
+
+| Input | Required contract |
+| --- | --- |
+| inputs | Required inputs of the linked canonical workflow, forwarded unchanged. |
+
+Forward all other supplied canonical inputs to the selected target. These
+alias selectors are not service-request fields. A fixed mapping requires no
+additional selector; it does not add fields to `prepare-agent`.
+
+## Dispatch
+
+| Selector | Canonical skill |
+| --- | --- |
+| fixed | adjudicate-unspecified-behavior |
+
+Dispatch directly to `adjudicate-unspecified-behavior`. The target separates specialist proposals from authorized root approval; this alias does not approve decisions.
+
+This alias has no independent output or write authority. Do not duplicate
+business validation, call tools independently, create a receipt, change a model
+or auto-launch a role. Use only the linked canonical workflow's lifecycle and
+exact grants; no alias chain or filesystem fallback is permitted.
+
+## Stop and result
+
+Return the selected canonical workflow's explicit result and references without
+changing failed, blocked, pending or incremental outcomes into completion.
+An unknown selector fails with no fallback. Missing configuration or native
+capability is handled by the canonical workflow, including initialization's
+explicit root bootstrap exception. The alias cannot bypass prepare/finalize or
+native start/stop requirements.
+
+## References
+
+- [adjudicate-unspecified-behavior](../adjudicate-unspecified-behavior/SKILL.md)

package/resources/customizations/.github/skills/discovery-coverage-ledger/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: discovery-coverage-ledger
+description: 'Dispatch explicit inventory, extraction or review without mixing coverage ownership. Use when invoking the existing coverage-ledger alias with action=inventory, extract or review.'
+---
+
+# Discovery Coverage Ledger Alias
+
+## When to Use This Skill
+
+Use this compatibility name only to dispatch to its canonical workflow.
+
+## Inputs
+
+| Input | Required contract |
+| --- | --- |
+| action | Required inventory, extract or review; reject missing, mixed or unknown actions with no fallback. |
+
+Forward all other supplied canonical inputs to the selected target. These
+alias selectors are not service-request fields. A fixed mapping requires no
+additional selector; it does not add fields to `prepare-agent`.
+
+## Dispatch
+
+| Selector | Canonical skill |
+| --- | --- |
+| inventory | inventory-legacy-system |
+| extract | extract-feature-contract |
+| review | review-discovery-coverage |
+
+`action=inventory|extract|review` selects the corresponding canonical workflow. Inventory and extraction use `legacy-parity-analyst`; review uses `migration-coverage-reviewer` with no reviewer ledger writes. These names describe the target's mapping and never authorize an unprepared logical-role launch.
+
+This alias has no independent output or write authority. Do not duplicate
+business validation, call tools independently, create a receipt, change a model
+or auto-launch a role. Use only the linked canonical workflow's lifecycle and
+exact grants; no alias chain or filesystem fallback is permitted.
+
+## Stop and result
+
+Return the selected canonical workflow's explicit result and references without
+changing failed, blocked, pending or incremental outcomes into completion.
+An unknown selector fails with no fallback. Missing configuration or native
+capability is handled by the canonical workflow, including initialization's
+explicit root bootstrap exception. The alias cannot bypass prepare/finalize or
+native start/stop requirements.
+
+## References
+
+- [inventory-legacy-system](../inventory-legacy-system/SKILL.md)
+- [extract-feature-contract](../extract-feature-contract/SKILL.md)
+- [review-discovery-coverage](../review-discovery-coverage/SKILL.md)

package/resources/customizations/.github/skills/discovery-parity-matrix/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: discovery-parity-matrix
+description: 'Dispatch parity reconciliation to the canonical Requirements Reconciler workflow. Use when invoking the existing discovery parity-matrix alias.'
+---
+
+# Discovery Parity Matrix Alias
+
+## When to Use This Skill
+
+Use this compatibility name only to dispatch to its canonical workflow.
+
+## Inputs
+
+| Input | Required contract |
+| --- | --- |
+| inputs | Required inputs of the linked canonical workflow, forwarded unchanged. |
+
+Forward all other supplied canonical inputs to the selected target. These
+alias selectors are not service-request fields. A fixed mapping requires no
+additional selector; it does not add fields to `prepare-agent`.
+
+## Dispatch
+
+| Selector | Canonical skill |
+| --- | --- |
+| fixed | reconcile-parity-matrix |
+
+Dispatch directly to `reconcile-parity-matrix`, whose logical role is `requirements-reconciler`. Do not route parity ownership to Legacy Parity Analyst or bypass the canonical root preparation.
+
+This alias has no independent output or write authority. Do not duplicate
+business validation, call tools independently, create a receipt, change a model
+or auto-launch a role. Use only the linked canonical workflow's lifecycle and
+exact grants; no alias chain or filesystem fallback is permitted.
+
+## Stop and result
+
+Return the selected canonical workflow's explicit result and references without
+changing failed, blocked, pending or incremental outcomes into completion.
+An unknown selector fails with no fallback. Missing configuration or native
+capability is handled by the canonical workflow, including initialization's
+explicit root bootstrap exception. The alias cannot bypass prepare/finalize or
+native start/stop requirements.
+
+## References
+
+- [reconcile-parity-matrix](../reconcile-parity-matrix/SKILL.md)

package/resources/customizations/.github/skills/discovery-repo-inventory/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: discovery-repo-inventory
+description: 'Dispatch repository inventory to the canonical legacy inventory workflow. Use when invoking the existing discovery repo-inventory alias.'
+---
+
+# Discovery Repository Inventory Alias
+
+## When to Use This Skill
+
+Use this compatibility name only to dispatch to its canonical workflow.
+
+## Inputs
+
+| Input | Required contract |
+| --- | --- |
+| inputs | Required inputs of the linked canonical workflow, forwarded unchanged. |
+
+Forward all other supplied canonical inputs to the selected target. These
+alias selectors are not service-request fields. A fixed mapping requires no
+additional selector; it does not add fields to `prepare-agent`.
+
+## Dispatch
+
+| Selector | Canonical skill |
+| --- | --- |
+| fixed | inventory-legacy-system |
+
+Dispatch directly to `inventory-legacy-system`. Its prepared Legacy Parity Analyst owns inventory and selected coverage dispositions; this alias grants no role or tool.
+
+This alias has no independent output or write authority. Do not duplicate
+business validation, call tools independently, create a receipt, change a model
+or auto-launch a role. Use only the linked canonical workflow's lifecycle and
+exact grants; no alias chain or filesystem fallback is permitted.
+
+## Stop and result
+
+Return the selected canonical workflow's explicit result and references without
+changing failed, blocked, pending or incremental outcomes into completion.
+An unknown selector fails with no fallback. Missing configuration or native
+capability is handled by the canonical workflow, including initialization's
+explicit root bootstrap exception. The alias cannot bypass prepare/finalize or
+native start/stop requirements.
+
+## References
+
+- [inventory-legacy-system](../inventory-legacy-system/SKILL.md)

package/resources/customizations/.github/skills/discovery-runtime-characterization/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: discovery-runtime-characterization
+description: 'Dispatch runtime characterization to its canonical supplied-evidence workflow. Use when invoking the existing runtime-characterization alias.'
+---
+
+# Discovery Runtime Characterization Alias
+
+## When to Use This Skill
+
+Use this compatibility name only to dispatch to its canonical workflow.
+
+## Inputs
+
+| Input | Required contract |
+| --- | --- |
+| inputs | Required inputs of the linked canonical workflow, forwarded unchanged. |
+
+Forward all other supplied canonical inputs to the selected target. These
+alias selectors are not service-request fields. A fixed mapping requires no
+additional selector; it does not add fields to `prepare-agent`.
+
+## Dispatch
+
+| Selector | Canonical skill |
+| --- | --- |
+| fixed | characterize-runtime-behavior |
+
+Dispatch directly to `characterize-runtime-behavior`. The canonical workflow preserves supplied evidence and honest manual, not-run or blocked states; the alias does not execute applications.
+
+This alias has no independent output or write authority. Do not duplicate
+business validation, call tools independently, create a receipt, change a model
+or auto-launch a role. Use only the linked canonical workflow's lifecycle and
+exact grants; no alias chain or filesystem fallback is permitted.
+
+## Stop and result
+
+Return the selected canonical workflow's explicit result and references without
+changing failed, blocked, pending or incremental outcomes into completion.
+An unknown selector fails with no fallback. Missing configuration or native
+capability is handled by the canonical workflow, including initialization's
+explicit root bootstrap exception. The alias cannot bypass prepare/finalize or
+native start/stop requirements.
+
+## References
+
+- [characterize-runtime-behavior](../characterize-runtime-behavior/SKILL.md)

package/resources/customizations/.github/skills/discovery-validate-artifacts/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: discovery-validate-artifacts
+description: 'Dispatch artifact validation to the canonical explicit-kind and mode workflow. Use when invoking the existing validate-artifacts alias.'
+---
+
+# Discovery Artifact Validation Alias
+
+## When to Use This Skill
+
+Use this compatibility name only to dispatch to its canonical workflow.
+
+## Inputs
+
+| Input | Required contract |
+| --- | --- |
+| inputs | Required inputs of the linked canonical workflow, forwarded unchanged. |
+
+Forward all other supplied canonical inputs to the selected target. These
+alias selectors are not service-request fields. A fixed mapping requires no
+additional selector; it does not add fields to `prepare-agent`.
+
+## Dispatch
+
+| Selector | Canonical skill |
+| --- | --- |
+| fixed | validate-discovery-artifacts |
+
+Dispatch directly to `validate-discovery-artifacts`. Forward its exact artifact kind/selection and explicit mode without type probing or substituting a different gate.
+
+This alias has no independent output or write authority. Do not duplicate
+business validation, call tools independently, create a receipt, change a model
+or auto-launch a role. Use only the linked canonical workflow's lifecycle and
+exact grants; no alias chain or filesystem fallback is permitted.
+
+## Stop and result
+
+Return the selected canonical workflow's explicit result and references without
+changing failed, blocked, pending or incremental outcomes into completion.
+An unknown selector fails with no fallback. Missing configuration or native
+capability is handled by the canonical workflow, including initialization's
+explicit root bootstrap exception. The alias cannot bypass prepare/finalize or
+native start/stop requirements.
+
+## References
+
+- [validate-discovery-artifacts](../validate-discovery-artifacts/SKILL.md)

package/resources/customizations/.github/skills/discovery-workflow/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: discovery-workflow
+description: 'Dispatch an explicit canonical discovery workflow without adding authority. Use when invoking the legacy discovery umbrella with a selected skill_id.'
+---
+
+# Discovery Workflow Alias
+
+## When to Use This Skill
+
+Use this compatibility name only to dispatch to its canonical workflow.
+
+## Inputs
+
+| Input | Required contract |
+| --- | --- |
+| skill_id | Required exact one of the nine canonical skill IDs listed below; unknown or missing values fail with no fallback. |
+
+Forward all other supplied canonical inputs to the selected target. These
+alias selectors are not service-request fields. A fixed mapping requires no
+additional selector; it does not add fields to `prepare-agent`.
+
+## Dispatch
+
+| Selector | Canonical skill |
+| --- | --- |
+| inventory-legacy-system | inventory-legacy-system |
+| extract-feature-contract | extract-feature-contract |
+| characterize-runtime-behavior | characterize-runtime-behavior |
+| reconcile-parity-matrix | reconcile-parity-matrix |
+| review-discovery-coverage | review-discovery-coverage |
+| adjudicate-unspecified-behavior | adjudicate-unspecified-behavior |
+| generate-acceptance-scenarios | generate-acceptance-scenarios |
+| initialize-discovery-workspace | initialize-discovery-workspace |
+| validate-discovery-artifacts | validate-discovery-artifacts |
+
+Select exactly one canonical workflow using `skill_id`. Forward its supplied inputs without inventing defaults or reinterpreting source identity. Each target owns its root prepare, exact launch, granted operations, finalize, native stop and root result; this umbrella adds no scheduler.
+
+This alias has no independent output or write authority. Do not duplicate
+business validation, call tools independently, create a receipt, change a model
+or auto-launch a role. Use only the linked canonical workflow's lifecycle and
+exact grants; no alias chain or filesystem fallback is permitted.
+
+## Stop and result
+
+Return the selected canonical workflow's explicit result and references without
+changing failed, blocked, pending or incremental outcomes into completion.
+An unknown selector fails with no fallback. Missing configuration or native
+capability is handled by the canonical workflow, including initialization's
+explicit root bootstrap exception. The alias cannot bypass prepare/finalize or
+native start/stop requirements.
+
+## References
+
+- [inventory-legacy-system](../inventory-legacy-system/SKILL.md)
+- [extract-feature-contract](../extract-feature-contract/SKILL.md)
+- [characterize-runtime-behavior](../characterize-runtime-behavior/SKILL.md)
+- [reconcile-parity-matrix](../reconcile-parity-matrix/SKILL.md)
+- [review-discovery-coverage](../review-discovery-coverage/SKILL.md)
+- [adjudicate-unspecified-behavior](../adjudicate-unspecified-behavior/SKILL.md)
+- [generate-acceptance-scenarios](../generate-acceptance-scenarios/SKILL.md)
+- [initialize-discovery-workspace](../initialize-discovery-workspace/SKILL.md)
+- [validate-discovery-artifacts](../validate-discovery-artifacts/SKILL.md)

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

@@ -1,6 +1,6 @@
 ---
 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.'
+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, test runtime, and test-isolation checks are known and are not restated in plans.'
 ---
 
 # Execution-Environment Brief
@@ -36,17 +36,20 @@ Two separate mechanisms restrict Bash command text. They are kept apart here bec
 
 ## 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.
+- 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. Files under `SCRATCH`, which is outside the worktree root, are discarded without consuming a slot.
+- 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 under `.claude/state/`; there is no automatic reset.
+- 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.
 - 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
@@ -58,12 +61,12 @@ Two separate mechanisms restrict Bash command text. They are kept apart here bec
 ## 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.
+- 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`); 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, 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 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`.
+- 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.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.
@@ -101,7 +104,7 @@ These pass every validator rule and are found only by reading the plan against t
 - 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.
+- Batch-budget exhaustion within one worktree over 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.
@@ -122,7 +125,18 @@ These pass every validator rule and are found only by reading the plan against t
 - 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.
+- File size follows three tiers for production, test, and reusable script files, counted in logical lines (a trailing terminator adds no line): at 500 lines look for a logical split (guidance); at 700 lines split more aggressively, and reviewers report a non-blocking Warning (advisory); above 800 lines a split is enforced regardless of logical separability (hard limit; exactly 800 passes). The hard limit is enforced by `tests/scripts/ci/FileSizePolicy.RepoGate.Tests.ps1` in the existing PowerShell shards against `config/file-size-baseline.json`, where legacy files above 800 may shrink (with the entry tightened) or stay equal but may not grow, and by the PreToolUse hook `.claude/hooks/enforce-file-size-limit.ps1` (`.codex/hooks/enforce-file-size-limit.ps1`). New logic in a file near a tier goes into a new module and a new test file. Markdown is exempt.
+
+## Test Runtime
+
+- A unit test runs in milliseconds. A full suite above about 15 minutes, or a single unit test above about 10 seconds, indicates repeated work in the code under test or its fixtures, not missing parallelism.
+- Diagnose before proposing sharding or parallel workers. First aggregate per-test and per-module time from the JUnit report that the full run already writes (`--junitxml`); a small fraction of tests usually holds most of the time. Then run the slowest test under a profiler (`python -m cProfile -o <file> -m pytest <node id>`) and read the profile with `pstats`.
+- Fix repeated production work first. An immutable structure, such as a schema registry that is rebuilt and re-verified on every call, is built once per owning instance. This speeds up the runtime as well as the tests.
+- Second, build an expensive immutable fixture once per session and hand each test its own copy wherever a test could mutate it, so test independence is unchanged.
+- Parallel workers reduce wall-clock time only: they are capped by the slowest test and leave the cost in the product.
+- pytest: pass `-n auto` (pytest-xdist) on the command line of the CI step `Run tests with Pytest` and of the parallel VS Code tasks, never in `addopts`, because the VS Code Test Explorer keys results to the wrong file when `addopts` carries it. `-n auto` counts physical cores, so a runner can start fewer workers than it has vCPUs; measure it against an explicit count such as `-n 4` before keeping it. pytest-cov combines the worker coverage into one report, and the serial `poetry run pytest` command remains the isolation reference.
+- Pester: Pester 5 has no in-process parallel mode, so parallel Pester runs are process-per-shard: `Invoke-PoshQCTest -ShardIndex -ShardCount` on the CI runners and `Invoke-PoshQCParallelTest` locally. Read the per-file `time` of the JUnit `testsuite` elements before changing the shard count or the weights in `config/poshqc-shard-weights.json`.
+- A candidate fix can be measured before the tree is edited by loading a pytest plugin module from `SCRATCH` with `-p <module>` and `PYTHONPATH`.
 
 ## Test Isolation Checks
 
@@ -131,5 +145,6 @@ These pass every validator rule and are found only by reading the plan against t
   - 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.
+  - a fresh single-process Pester run over `tests/scripts`, which is the CI shape;
+  - in addition to the serial runs, a concurrent-shard Pester run through `Invoke-PoshQCParallelTest` and a `pytest -n auto` run, both with zero failures.
 - 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.