@danmoisan/drm-copilot-mcp 1.1.22 → 1.1.24

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

@@ -1,63 +1,46 @@
 ---
 name: discovery-runtime-characterization
-description: 'Produce runtime characterization scenarios and evidence references in the discovery workflow. Use when characterizing observed runtime behavior of the legacy application into scenarios with supporting evidence and routing analysis to the runtime role. Fourth stage, after coverage and before parity.'
+description: 'Dispatch runtime characterization to its canonical supplied-evidence workflow. Use when invoking the existing runtime-characterization alias.'
 ---
 
-# Discovery Runtime Characterization
-
-Runs the runtime characterization stage of the discovery and parity-definition
-workflow. It captures observed runtime behavior of the legacy application as
-characterization scenarios, each backed by evidence references, so that parity
-analysis can compare intended contracts against observed behavior. All domain
-specificity is read from the domain profile at runtime.
+# Discovery Runtime Characterization Alias
 
 ## When to Use This Skill
 
-- Feature contracts and the coverage ledger exist from the coverage stage.
-- You need documented runtime behavior scenarios before building the parity
-  matrix.
-
-## Prerequisites
-
-- `discovery-coverage-ledger` has completed.
-- The domain profile is loaded and valid.
-
-## Workflow
-
-1. **Produce characterization scenarios.** For each behavior requiring runtime
-   observation, produce a scenario conforming to the schema
-   `schemas/discovery/v1/runtime-characterization-scenario.schema.json`. Each
-   scenario records the observed runtime behavior in a domain-neutral form.
+Use this compatibility name only to dispatch to its canonical workflow.
 
-2. **Record evidence references.** Attach evidence to each scenario as
-   evidence-reference instances conforming to the schema
-   `schemas/discovery/v1/evidence-reference.schema.json`, so the provenance of
-   each observation is traceable.
+## Inputs
 
-3. **Route analysis.** Hand the scenarios to the runtime role for analysis (see
-   `## Worker Routing`).
+| Input | Required contract |
+| --- | --- |
+| inputs | Required inputs of the linked canonical workflow, forwarded unchanged. |
 
-## Worker Routing
+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`.
 
-- Worker: `runtime-characterization-analyst`
+## Dispatch
 
-The runtime role analyzes and confirms each characterization scenario and its
-evidence before the workflow proceeds to parity.
+| Selector | Canonical skill |
+| --- | --- |
+| fixed | characterize-runtime-behavior |
 
-## Validation
+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.
 
-- Validate scenarios with `dev.discovery.validate-runtime-scenario`.
-- Validate evidence references with `dev.discovery.validate-evidence-reference`.
-- An empty error list is a pass. On any error, follow the direction in
-  `discovery-validate-artifacts`.
+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.
 
-## Referenced Skills
+## Stop and result
 
-- `discovery-workflow` — stage order and the canonical Referenced Contracts
-  registry.
-- `discovery-validate-artifacts` — pass/fail semantics and error routing.
+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.
 
-## Notes
+## References
 
-- Scenarios and evidence references from this stage are consumed by
-  `discovery-parity-matrix`.
+- [characterize-runtime-behavior](../characterize-runtime-behavior/SKILL.md)

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

@@ -1,79 +1,46 @@
 ---
 name: discovery-validate-artifacts
-description: 'Canonical validation-gate mechanics for the discovery workflow. Use when running the per-artifact discovery validators after each stage and the completion gate at the end, interpreting the empty-error-list pass semantics, and routing any validator error back to the owning stage skill. Seventh and final stage.'
-allowed-tools: Bash Read
+description: 'Dispatch artifact validation to the canonical explicit-kind and mode workflow. Use when invoking the existing validate-artifacts alias.'
 ---
 
-# Discovery Validate Artifacts
-
-Owns the canonical validation-gate mechanics for the discovery and
-parity-definition workflow. Each discovery artifact is validated against its
-schema by a `dev.discovery.validate-*` console script after its owning stage,
-and `dev.discovery.validate-all` runs as the workflow completion gate. This skill
-is the single canonical location for the pass/fail semantics; stage skills defer
-to it by name.
+# Discovery Artifact Validation Alias
 
 ## When to Use This Skill
 
-- A stage has produced an artifact and you need to validate it before the next
-  stage proceeds.
-- You have completed all stages and need to run the workflow completion gate.
-- A validator reported errors and you need the routing rule back to the owning
-  stage skill.
-
-## Prerequisites
-
-- The relevant discovery artifacts exist under the profile's artifact root.
-- The validator console scripts are available (registry in `discovery-workflow`).
-
-## Pass/Fail Semantics
-
-Every `dev.discovery.validate-*` invocation yields a `list[str]` of error
-messages. An empty list is a pass; a non-empty list is a failure whose entries
-name the exact problems. The validators never mutate the artifacts they check.
+Use this compatibility name only to dispatch to its canonical workflow.
 
-## Per-Stage Validators
+## Inputs
 
-Run each validator after its owning stage produces its artifact. On a non-empty
-error list, return to the named owning stage skill, correct the artifact, and
-re-run the validator until the list is empty.
+| Input | Required contract |
+| --- | --- |
+| inputs | Required inputs of the linked canonical workflow, forwarded unchanged. |
 
-| Validator | Validates schema | Owning stage skill |
-|---|---|---|
-| `dev.discovery.validate-profile` | (domain profile) | `discovery-repo-inventory` |
-| `dev.discovery.validate-evidence-reference` | `schemas/discovery/v1/evidence-reference.schema.json` | `discovery-repo-inventory`, `discovery-runtime-characterization` |
-| `dev.discovery.validate-feature-contract` | `schemas/discovery/v1/feature-contract.schema.json` | `discovery-coverage-ledger` |
-| `dev.discovery.validate-coverage-ledger` | `schemas/discovery/v1/coverage-ledger.schema.json` | `discovery-coverage-ledger` |
-| `dev.discovery.validate-runtime-scenario` | `schemas/discovery/v1/runtime-characterization-scenario.schema.json` | `discovery-runtime-characterization` |
-| `dev.discovery.validate-parity-matrix` | `schemas/discovery/v1/parity-matrix.schema.json` | `discovery-parity-matrix` |
-| `dev.discovery.validate-unspecified-behavior` | `schemas/discovery/v1/unspecified-behavior-record.schema.json` | `discovery-behavior-reconciliation` |
-| `dev.discovery.validate-product-decision` | `schemas/discovery/v1/product-decision-record.schema.json` | `discovery-behavior-reconciliation` |
+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`.
 
-## Completion Gate
+## Dispatch
 
-After all stages pass their per-stage validators, run
-`dev.discovery.validate-all` as the workflow completion gate. It validates the
-full artifact set across all seven schemas under `schemas/discovery/v1/`:
+| Selector | Canonical skill |
+| --- | --- |
+| fixed | validate-discovery-artifacts |
 
-- `schemas/discovery/v1/feature-contract.schema.json`
-- `schemas/discovery/v1/coverage-ledger.schema.json`
-- `schemas/discovery/v1/runtime-characterization-scenario.schema.json`
-- `schemas/discovery/v1/parity-matrix.schema.json`
-- `schemas/discovery/v1/unspecified-behavior-record.schema.json`
-- `schemas/discovery/v1/product-decision-record.schema.json`
-- `schemas/discovery/v1/evidence-reference.schema.json`
+Dispatch directly to `validate-discovery-artifacts`. Forward its exact artifact kind/selection and explicit mode without type probing or substituting a different gate.
 
-An empty error list from `dev.discovery.validate-all` means the workflow is
-complete. A non-empty list names the exact artifact and problem; route each entry
-back to its owning stage skill using the per-stage table above, correct the
-artifact, and re-run the 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.
 
-## Referenced Skills
+## Stop and result
 
-- `discovery-workflow` — stage order and the canonical Referenced Contracts
-  registry (analyzer command, agent slugs, schema paths, validators).
+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.
 
-## Notes
+## References
 
-- This skill names no domain-specific identifier; artifact locations are read
-  from the domain profile at runtime.
+- [validate-discovery-artifacts](../validate-discovery-artifacts/SKILL.md)

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

@@ -1,146 +1,62 @@
 ---
 name: discovery-workflow
-description: 'Umbrella sequencing skill for the domain-neutral legacy discovery and parity-definition workflow. Use when onboarding or running the end-to-end discovery workflow across inventory, coverage, runtime characterization, parity, behavior reconciliation, and the validation gate, and when reconciling upstream analyzer and agent contract names. Holds the canonical Referenced Contracts registry.'
+description: 'Dispatch an explicit canonical discovery workflow without adding authority. Use when invoking the legacy discovery umbrella with a selected skill_id.'
 ---
 
-# Discovery Workflow
-
-Sequences the reusable, domain-neutral discovery and parity-definition workflow
-end to end. This skill is the entry point: it establishes the stage order,
-directs each stage to its owning skill, and holds the single canonical registry
-of upstream contract names (analyzer CLI commands, agent slugs, schema paths,
-and validators).
-
-All domain specificity is read at runtime from the consumer repository's domain
-profile (`discovery-profile.yaml`) via `dev.discovery.profile`. This skill names
-no concrete repository, path, or technology stack.
+# Discovery Workflow Alias
 
 ## When to Use This Skill
 
-- You are onboarding the discovery and parity-definition workflow in a consumer
-  repository and need the documented stage order.
-- You need the canonical list of upstream contract names to reconcile a renamed
-  analyzer command or agent slug at epic fan-in.
-- You need to know which stage skill owns which artifact and validator.
-
-## Prerequisites
-
-- A `discovery-profile.yaml` domain profile exists in the consumer repository and
-  loads cleanly via `dev.discovery.profile`.
-- The analyzer framework CLI and the four generic agent roles are available in
-  the consumer environment (referenced here by name only).
-
-## Stage Order
-
-Run the workflow in this fixed order. Each stage validates its artifacts before
-the next stage proceeds:
-
-1. **profile** — load and echo the domain profile via `dev.discovery.profile`.
-2. **inventory** — drive the language-neutral repository/project inventory
-   analyzer (`discovery-repo-inventory`).
-3. **coverage** — produce feature contracts and the coverage ledger
-   (`discovery-coverage-ledger`).
-4. **runtime** — produce runtime characterization scenarios and evidence
-   references (`discovery-runtime-characterization`).
-5. **parity** — produce or refresh the parity matrix (`discovery-parity-matrix`).
-6. **reconciliation** — capture unspecified or contradictory behavior and
-   reconcile it into product decisions (`discovery-behavior-reconciliation`).
-7. **validation gate** — run the per-stage validators and the completion gate
-   (`discovery-validate-artifacts`).
-
-Compact form: profile -> inventory -> coverage -> runtime -> parity ->
-reconciliation -> validation gate.
-
-## Worker Routing
-
-The four generic agent roles are routed by slug from their owning stage skills.
-The routing table below is the canonical mapping; each stage skill repeats only
-the single slug it routes to.
-
-| Stage skill | Agent slug |
-|---|---|
-| `discovery-coverage-ledger` | `migration-coverage-reviewer` |
-| `discovery-runtime-characterization` | `runtime-characterization-analyst` |
-| `discovery-parity-matrix` | `legacy-parity-analyst` |
-| `discovery-behavior-reconciliation` | `requirements-reconciler` |
-
-## Referenced Contracts
-
-This registry is the single canonical location for upstream contract names.
-Stage skills name only the specific contract(s) they use and defer to this
-registry for the full set. Indirect reference by skill name is not duplication.
-
-### Domain profile (config contract, issue #360 / epic #9001)
-
-- Config artifact: `discovery-profile.yaml`.
-- CLI: `dev.discovery.profile`.
-
-### Schemas (issue #359 / epic #9002)
-
-Seven schemas under `schemas/discovery/v1/`:
-
-- `schemas/discovery/v1/feature-contract.schema.json`
-- `schemas/discovery/v1/coverage-ledger.schema.json`
-- `schemas/discovery/v1/runtime-characterization-scenario.schema.json`
-- `schemas/discovery/v1/parity-matrix.schema.json`
-- `schemas/discovery/v1/unspecified-behavior-record.schema.json`
-- `schemas/discovery/v1/product-decision-record.schema.json`
-- `schemas/discovery/v1/evidence-reference.schema.json`
-
-### Validators (issue #361 / epic #9003)
-
-Nine `dev.discovery.validate-*` console scripts. Each yields a `list[str]` of
-errors; an empty list is a pass.
-
-- `dev.discovery.validate-profile`
-- `dev.discovery.validate-feature-contract`
-- `dev.discovery.validate-coverage-ledger`
-- `dev.discovery.validate-runtime-scenario`
-- `dev.discovery.validate-parity-matrix`
-- `dev.discovery.validate-unspecified-behavior`
-- `dev.discovery.validate-product-decision`
-- `dev.discovery.validate-evidence-reference`
-- `dev.discovery.validate-all`
-
-### Analyzer framework (epic #9006, in preparation)
-
-- Language-neutral repository/project inventory command: `dev.discovery.inventory`.
-
-  **Fan-in reconciliation assumption:** the inventory command name
-  `dev.discovery.inventory` is assumed. It is not fixed by the prepared upstream
-  summaries and is the epic #9006 owner's decision. This assumption is isolated
-  to this single registry line plus one fragment in `discovery-repo-inventory`.
-  If #9006 lands a different command name, update those two locations only.
-
-### Agent roles (epic #9007, in preparation)
-
-Four generic agent personas, referenced by slug in the Worker Routing table
-above:
-
-- `legacy-parity-analyst`
-- `runtime-characterization-analyst`
-- `requirements-reconciler`
-- `migration-coverage-reviewer`
-
-  **Fan-in reconciliation assumption:** the four agent slugs are assumed to be
-  the kebab-case of the persona titles. Final slugs are the epic #9007 owner's
-  decision. The assumption is isolated to this registry and the per-stage
-  `## Worker Routing` fragments; reconciling a renamed slug at fan-in is a
-  bounded edit.
-
-## Referenced Skills
-
-- `discovery-repo-inventory` — inventory stage mechanics.
-- `discovery-coverage-ledger` — coverage stage mechanics.
-- `discovery-runtime-characterization` — runtime stage mechanics.
-- `discovery-parity-matrix` — parity stage mechanics.
-- `discovery-behavior-reconciliation` — reconciliation stage mechanics.
-- `discovery-validate-artifacts` — canonical validation-gate mechanics.
-
-## Notes
-
-- No skill in this workflow asserts the existence of upstream analyzer or agent
-  files; upstream contracts are referenced by name only, so this workflow stays
-  correct regardless of upstream merge order.
-- Domain specificity (source and target roots, technology stack, artifact
-  conventions) is read from the domain profile at runtime, never hard-coded.
+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/claude-customizations/.claude/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.