@danmoisan/drm-copilot-mcp 1.0.16 → 1.0.18

package/resources/claude-customizations/.claude/hooks/validate-discovery-artifact-gate.ps1

@@ -0,0 +1,237 @@
+<#
+.SYNOPSIS
+    SubagentStop hook that validates discovery artifacts referenced in a
+    terminating subagent's final output.
+
+.DESCRIPTION
+    Invoked by the Claude Code SubagentStop hook under the existing broad
+    generic-agent matcher group. The hook reads $env:CLAUDE_HOOK_INPUT JSON
+    containing .output (the terminating subagent's final text), scans that
+    text for discovery-artifact path references via Get-DiscoveryArtifactType,
+    and for each recognized reference (when a required-artifact declaration is
+    present) invokes the discovery validator CLI via
+    Invoke-DiscoveryValidatorExe.
+
+    Any referenced artifact that fails validation blocks the subagent's
+    termination: the hook writes an error with a
+    DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix and exits with a non-zero code.
+    When no reference fails validation, or when no discovery-artifact path is
+    referenced, or when the required-artifact declaration is absent
+    (fail-open), the hook allows termination.
+
+    This hook provides the authoritative, defense-in-depth check of final
+    workspace state, regardless of which tool produced the artifact,
+    complementing the PreToolUse gate in
+    enforce-discovery-artifact-gate.ps1. Neither hook implements or
+    reimplements discovery-validator logic; both only route to the validator
+    CLI delivered by a separate feature and interpret its exit code and
+    captured output.
+
+.NOTES
+    Compatible with PowerShell 7+. Read-only validation gate; the validator
+    subprocess is the only external process invoked.
+#>
+[CmdletBinding()]
+param()
+
+function Invoke-DiscoveryValidatorExe {
+    <#
+    .SYNOPSIS
+        Wrapper around the discovery-artifact validator CLI. Mockable seam.
+    .DESCRIPTION
+        Invokes `python -m scripts.dev_tools.validate_discovery_artifacts` with
+        the supplied arguments and captures both stdout and stderr. Tests mock
+        this function directly; production code must never mock `python`.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string[]] $ValidatorArgs
+    )
+
+    $output = & python -m scripts.dev_tools.validate_discovery_artifacts @ValidatorArgs 2>&1
+    return @{ ExitCode = $LASTEXITCODE; Output = ($output | Out-String).Trim() }
+}
+
+function Get-DiscoveryArtifactType {
+    <#
+    .SYNOPSIS
+        Maps a normalized file path to a discovery-artifact-type token.
+    .DESCRIPTION
+        Returns one of the eight validator subcommand tokens (profile,
+        feature-contract, coverage-ledger, runtime-scenario, parity-matrix,
+        unspecified-behavior, product-decision, evidence-reference), or $null
+        when the path does not resolve to a recognized discovery-artifact
+        type.
+
+        # TODO(#9002): this is a narrow, replaceable directory/filename lookup.
+        The schema-versioned directory/filename convention this mapping
+        depends on is owned by #9002 and is not finalized in this branch.
+        Replace this lookup once #9002 ships its versioning convention.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path
+    )
+
+    $normalized = $Path -replace '\\', '/'
+
+    $typeMap = [ordered]@{
+        'discovery/profile'              = 'profile'
+        'discovery/feature-contract'     = 'feature-contract'
+        'discovery/coverage-ledger'      = 'coverage-ledger'
+        'discovery/runtime-scenario'     = 'runtime-scenario'
+        'discovery/parity-matrix'        = 'parity-matrix'
+        'discovery/unspecified-behavior' = 'unspecified-behavior'
+        'discovery/product-decision'     = 'product-decision'
+        'discovery/evidence-reference'   = 'evidence-reference'
+    }
+
+    foreach ($prefix in $typeMap.Keys) {
+        if ($normalized -match "(^|/)$([regex]::Escape($prefix))") {
+            return $typeMap[$prefix]
+        }
+    }
+
+    return $null
+}
+
+function Get-RequiredDiscoveryArtifactDeclaration {
+    <#
+    .SYNOPSIS
+        Reads the domain-profile required-artifact declaration, if present.
+    .DESCRIPTION
+        # TODO(#9001): this is a narrow, injectable RequiredArtifactPathsReader
+        seam. The discovery-workspace root and which of the eight artifact
+        types are "required" for a given gate are domain-profile runtime
+        configuration owned by #9001, which has no shipped parser/schema in
+        this branch.
+
+        Default behavior on absence is documented inline as fail-open
+        (allow/exit 0): when no domain profile is present, this function
+        returns an object with Present = $false, and callers must treat that
+        as "always allow, never invoke the validator" rather than as an error.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $ProfileReader = { $null }
+    )
+
+    $declaration = & $ProfileReader
+    if ($null -eq $declaration) {
+        # Fail open: no domain profile / required-artifact declaration present.
+        return @{ Present = $false }
+    }
+
+    return @{ Present = $true; Declaration = $declaration }
+}
+
+function Find-DiscoveryArtifactReference {
+    <#
+    .SYNOPSIS
+        Extracts candidate discovery-artifact path references from subagent
+        output text.
+    .DESCRIPTION
+        Splits the output text into whitespace-delimited tokens and returns
+        the distinct set of tokens that resolve to a recognized
+        discovery-artifact type via Get-DiscoveryArtifactType. This is a
+        lightweight text scan, not a JSON/markdown parser, matching the
+        precision needed for a defense-in-depth completion gate.
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $OutputText
+    )
+
+    if ([string]::IsNullOrWhiteSpace($OutputText)) {
+        return [string[]]@()
+    }
+
+    $tokens = $OutputText -split '\s+' | Where-Object { $_ }
+    $foundReferences = New-Object System.Collections.Generic.List[string]
+    foreach ($token in $tokens) {
+        $trimmed = $token.Trim('`', '"', "'", ',', ';', '(', ')', '[', ']')
+        if (Get-DiscoveryArtifactType -Path $trimmed) {
+            if (-not $foundReferences.Contains($trimmed)) {
+                $foundReferences.Add($trimmed)
+            }
+        }
+    }
+
+    return [string[]]$foundReferences
+}
+
+function Invoke-DiscoveryArtifactGateValidation {
+    <#
+    .SYNOPSIS
+        Parses CLAUDE_HOOK_INPUT and returns an Ok/Message validation result
+        for a discovery-artifact completion gate.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [string] $RawPayload,
+
+        [Parameter(Mandatory = $false)]
+        [scriptblock] $RequiredArtifactReader = { Get-RequiredDiscoveryArtifactDeclaration }
+    )
+
+    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
+        return @{ Ok = $false; Message = 'discovery artifact gate hook: CLAUDE_HOOK_INPUT is empty' }
+    }
+
+    try {
+        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        return @{ Ok = $false; Message = "discovery artifact gate hook: CLAUDE_HOOK_INPUT is not valid JSON: $_" }
+    }
+
+    $outputText = ''
+    if ($null -ne $payload -and ($payload.PSObject.Properties.Name -contains 'output')) {
+        $outputText = [string]$payload.output
+    }
+
+    $references = Find-DiscoveryArtifactReference -OutputText $outputText
+    if ($references.Count -eq 0) {
+        return @{ Ok = $true; Message = $null }
+    }
+
+    $requiredDeclaration = & $RequiredArtifactReader
+    if (-not $requiredDeclaration.Present) {
+        # Fail open: no domain profile / required-artifact declaration present.
+        return @{ Ok = $true; Message = $null }
+    }
+
+    foreach ($reference in $references) {
+        $artifactType = Get-DiscoveryArtifactType -Path $reference
+        $result = Invoke-DiscoveryValidatorExe -ValidatorArgs @($artifactType, $reference)
+        $hasErrorOutput = -not [string]::IsNullOrWhiteSpace($result.Output)
+        if ($result.ExitCode -ne 0 -or $hasErrorOutput) {
+            return @{ Ok = $false; Message = "DISCOVERY_ARTIFACT_GATE_BLOCKED: $($result.Output)" }
+        }
+    }
+
+    return @{ Ok = $true; Message = $null }
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+$result = Invoke-DiscoveryArtifactGateValidation -RawPayload $env:CLAUDE_HOOK_INPUT
+if (-not $result.Ok) {
+    Write-Error $result.Message
+    exit 1
+}
+
+exit 0

package/resources/claude-customizations/.claude/hooks/validate-planner-output.ps1

@@ -1,4 +1,4 @@
-<#
+<#
 .SYNOPSIS
     SubagentStop hook for the atomic-planner subagent.
 
@@ -14,7 +14,7 @@
       - output contains `PREFLIGHT: ALL CLEAR` or
         `PREFLIGHT: REVISIONS REQUIRED`,
       - the advertised plan exists on disk,
-      - the plan contains canonical `### Phase N - <Title>` headings,
+      - the plan contains canonical `### Phase N — <Title>` headings,
       - Phase 0 exists and includes policy-read and baseline tasks,
       - each task uses `- [ ] [P#-T#]` (or checked equivalent),
       - task numbering is sequential within each phase,
@@ -118,7 +118,7 @@ function Get-PlanStructureValidationReport {
         [string[]] $Lines
     )
 
-    $phasePattern = '^### Phase (?<Phase>\d+)\s+-\s+(?<Title>.+)$'
+    $phasePattern = '^### Phase (?<Phase>\d+)\s+—\s+(?<Title>.+)$'
     $taskPattern = '^- \[(?<State>[ xX])\] \[P(?<Phase>\d+)-T(?<Task>\d+)\] (?<Text>.+)$'
     $errors = [System.Collections.Generic.List[string]]::new()
     $tasksByPhase = @{}
@@ -134,7 +134,7 @@ function Get-PlanStructureValidationReport {
         if ($line -match '^### Phase ') {
             $phaseMatch = [regex]::Match($line, $phasePattern)
             if (-not $phaseMatch.Success) {
-                $errors.Add("Line ${lineNumber}: phase heading must match `### Phase N - <Title>`.")
+                $errors.Add("Line ${lineNumber}: phase heading must match `### Phase N — <Title>`.")
                 $currentPhase = $null
                 continue
             }
@@ -245,7 +245,7 @@ function Invoke-PlannerOutputValidation {
     }
 
     $agentOutput = $null
-    if ($payload.PSObject.Properties.Name -contains 'output') {
+    if ($null -ne $payload.PSObject.Properties['output']) {
         $agentOutput = $payload.output
     }
     if ([string]::IsNullOrWhiteSpace($agentOutput)) {

package/resources/claude-customizations/.claude/rules/shell.md

@@ -0,0 +1,88 @@
+---
+paths:
+  - "**/*.sh"
+  - "**/*.bats"
+  - "scripts/bash/**"
+  - "tests/shell/**"
+description: Shell (bash) toolchain and coding standards.
+---
+
+# Shell (Bash) Code Standards
+
+This rule file summarizes the shell-specific policies for this repository. The shell
+quality-control toolchain is native bash and has no Python or Poetry dependency.
+
+## Toolchain
+
+Run the toolchain in this order and restart from step 1 if any step fails or rewrites files:
+
+1. **Formatting — shfmt**: Format all shell scripts with shfmt (write mode). Command:
+   `bash scripts/bash/shell-qc.sh format`. The `check` command runs shfmt in diff mode
+   (`shfmt -d`) as its first stage.
+2. **Linting — shellcheck**: Lint all shell scripts with shellcheck. Command:
+   `bash scripts/bash/shell-qc.sh check`. `check` runs `shfmt -d` once over the full file
+   list and then `shellcheck` once per file, returning the maximum exit code.
+3. **Type checking — not applicable**: Bash has no separate type-check stage. An optional
+   syntax check is available via `bash -n`; the VS Code task "Shell QC: 3 bash: type-check"
+   provides it. Skip to testing.
+4. **Testing — bats**: Run bats tests with `bash scripts/bash/shell-qc.sh test`. Line coverage
+   via kcov with `bash scripts/bash/shell-qc.sh test --coverage`.
+
+Do not stop the loop until formatting, linting, and testing complete without errors in a
+single pass. Do not substitute the VS Code task wrappers for the native command in automation.
+
+## Native Invocation and Environment
+
+- The toolchain is native bash: the wrapper `scripts/bash/shell-qc.sh` and its library
+  `scripts/bash/shell_qc_lib.sh` invoke `shfmt`, `shellcheck`, `bats`, and `kcov` directly.
+  No Python interpreter, no Poetry, and no `poetry run` are involved.
+- On Windows, run the toolchain under WSL.
+- In CI, the toolchain runs on `ubuntu-latest` (`.github/workflows/_shell-coverage.yml` for
+  coverage; `.github/workflows/_build-check.yml` runs `--help` as an installability smoke).
+- Per-tool path overrides are available for testing via `SHELL_QC_<TOOL>_BIN` (for `shfmt`,
+  `shellcheck`, `bats`, `kcov`); an empty or nonexistent value is treated as missing. The
+  coverage output directory is `SHELL_QC_KCOV_OUT_DIR` (default `artifacts/pester/kcov`).
+
+## Discovery Contract
+
+- Search roots: `tools/` and `scripts/`, relative to the current working directory; a missing
+  root is silently skipped.
+- A file is a shell script when its suffix (lowercased) is `.sh` or its first line is a
+  shebang whose resolved interpreter is `bash` or `sh` (including `env` and `env -S`/`-flag`
+  forms; the shebang is lowercased before parsing, so `#!/usr/bin/env BASH` qualifies).
+- Excluded directories (pruned at any depth): `.venv`, `.git`, `node_modules`, `dist`,
+  `build`.
+- The discovered set is de-duplicated and sorted with `LC_ALL=C` for deterministic ordering.
+- bats test directories: `tests/shell` and `tests/bash`, whichever exist, in that order.
+
+## Coverage Expectations
+
+- Coverage is measured with kcov, which emits a single merged Cobertura report `cov.xml` under
+  `artifacts/pester/kcov` (or `SHELL_QC_KCOV_OUT_DIR`). The run prints
+  `Bash coverage (lines): NN.N%`.
+- kcov reports **line coverage only**. The uniform line-coverage threshold (>= 85% per
+  `.claude/rules/quality-tiers.md`) applies. Branch coverage is not measurable by kcov for
+  bash; there is no bash branch-coverage gate.
+
+## CI-vs-Local Version Drift
+
+- CI pins shfmt 3.8.0 (installed as a binary), uses apt-packaged shellcheck and bats, and
+  builds kcov v43 from source. Local WSL installs (winget or apt) may drift from these
+  versions.
+- CI versions are canonical. When local and CI results disagree, defer to CI.
+
+## Coding Standards
+
+- Begin executable scripts with `set -euo pipefail`. Tools that legitimately return non-zero
+  (shfmt diff mode, shellcheck, bats, kcov) must be captured with `|| rc=$?` so an intended
+  non-zero exit does not abort under `set -e`.
+- Keep scripts shellcheck-clean. Suppressions are permitted only when justified inline with a
+  `# shellcheck disable=SCxxxx` comment stating the reason.
+- Use shfmt default formatting (tab indentation, as in `scripts/bash/coverage_lib.sh`).
+- Quote all expansions; resolve tools with `command -v` (honoring the `SHELL_QC_<TOOL>_BIN`
+  override seam).
+- No production, test, or reusable shell file may exceed 500 lines.
+- Tests live in `tests/shell/*.bats` and mirror `scripts/bash/`. Tests must not create
+  temporary files; use checked-in fixtures under `tests/fixtures/` and checked-in stub
+  binaries under `tests/fixtures/shell_qc/stub-bin/` wired through the `SHELL_QC_<TOOL>_BIN`
+  seam.

package/resources/claude-customizations/.claude/settings.json

@@ -155,6 +155,10 @@
           {
             "type": "command",
             "command": "pwsh -NoProfile -File .claude/hooks/enforce-completion-consistency.ps1"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/enforce-discovery-artifact-gate.ps1"
           }
         ]
       },
@@ -191,6 +195,10 @@
           {
             "type": "command",
             "command": "pwsh -NoProfile -Command \"$input = $env:CLAUDE_HOOK_INPUT | ConvertFrom-Json; $output = $input.output; if (-not ($output -match '(plan-path|research-path|review-artifact|PREFLIGHT|evidence/)')) { Write-Error 'Subagent stopped without required completion artifact path'; exit 1 }; exit 0\""
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/validate-discovery-artifact-gate.ps1"
           }
         ]
       },

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

@@ -0,0 +1,132 @@
+---
+name: cleanup-merged-worktrees
+description: 'Detect, consolidate, and delete git worktrees/branches that are fully merged into main; use after an epic or feature''s PRs have merged and stale drm-copilot-wt-* branches/worktrees remain, driving the detect -> report -> consolidate -> pr-author handoff -> post-merge deletion workflow.'
+allowed-tools:
+  - Read
+  - "Bash(bash scripts/bash/cleanup-worktrees.sh *)"
+  - "Bash(git fetch *)"
+  - "Bash(git merge-base *)"
+  - "Bash(git push *)"
+  - "Bash(git rev-parse *)"
+---
+
+# Cleanup Merged Worktrees
+
+Drive the end-to-end cleanup of stale git worktrees and branches after their work has
+merged into `main`. The deterministic classification, consolidation staging, and
+deletion mechanics live in `scripts/bash/cleanup-worktrees.sh` (wrapping
+`scripts/bash/cleanup_worktrees_lib.sh` and
+`scripts/bash/cleanup_worktrees_actions_lib.sh`). This skill owns the editorial and
+orchestration layer: deciding whether flagged unique content is genuinely
+documentation/memory material, driving consolidation onto a single
+`documentationandmemories` branch, delegating PR creation to `Agent(pr-author)`, and
+running the destructive apply pass only after the consolidation PR has merged.
+
+The script is deterministic and owns the safe/unsafe decision; the LLM/editorial
+judgment (which flagged commits are documentation/memory content) is this skill's job
+and is out of the script's scope.
+
+## When to Use This Skill
+
+- After an epic or feature's PRs have all merged and two to five stale
+  `drm-copilot-wt-*` branches or worktrees remain.
+- When you need a trustworthy, machine-parseable report of which branches/worktrees are
+  safe to delete (`MERGED_CLEAN`, `MERGED_CONTENT_NEUTRAL`, `MERGED_EQUIVALENT`) versus
+  which carry unmerged or unique work (`NOT_MERGED`, `HAS_UNIQUE_RESIDUALS`).
+- When stranded documentation/agent-memory commits were appended to a worktree branch
+  after its feature content already merged and must be preserved before deletion.
+- Do not use this skill to manage remote branches; its scope is local branches and
+  local worktree registrations only.
+
+## Report Line Contract
+
+The script emits pipe-delimited, `LC_ALL=C`-ordered records, one per line:
+
+- `BRANCH|<name>|<state>` — `state` in `NOT_MERGED | MERGED_CLEAN |
+  MERGED_CONTENT_NEUTRAL | MERGED_EQUIVALENT | HAS_UNIQUE_RESIDUALS | PROTECTED_CURRENT`.
+- `COMMIT|<branch>|<sha>|<state>|<paths-csv>|<author>|<author-date>` — per-commit state
+  in `EQUIVALENT | CONTENT_ON_MAIN | EMPTY | UNIQUE | CONFLICT`. A `UNIQUE` COMMIT record
+  is a cherry-pick candidate for editorial triage.
+- `WORKTREE|<path>|<branch-or-DETACHED>|<flags>` — worktree registrations.
+- `WARN|main-divergence|<local-sha>|<origin-sha>` — local `main` differs from
+  `origin/main` (advisory; classification still runs).
+- `DIRTY|<worktree-path>|<status-porcelain-line>` — a dirty worktree that blocked
+  removal.
+- `ACTION|<verb>|<target>|<result>` — apply-mode action results.
+
+## End-to-End Workflow
+
+1. **Detect and report (dry run).** Run `bash scripts/bash/cleanup-worktrees.sh`
+   (report mode is the default and mutates nothing). It verifies local `main` against
+   `origin/main` (emitting `WARN|main-divergence` on drift), enumerates branches and
+   worktrees, and prints one `BRANCH|` line per branch plus `COMMIT|...|UNIQUE|...`
+   records for each unique residual commit.
+
+2. **Editorial triage of the cherry-pick candidates.** Review each
+   `COMMIT|...|UNIQUE|...` record — this is the LLM-judgment boundary. Confirm
+   editorially that the unique commits are genuinely documentation/agent-memory
+   content (for example paths under `docs/**`, `.claude/agent-memory/**`, or `**/*.md`).
+   The script only reports the deterministic facts (SHA, paths, author, date); deciding
+   what counts as documentation is this skill's responsibility.
+
+3. **Consolidate onto `documentationandmemories`.** When the candidate list is
+   non-empty, the script creates the `documentationandmemories` branch off `main` in a
+   dedicated worktree (never the caller's worktree) and cherry-picks the flagged commits
+   oldest-first per source branch, branches in `LC_ALL=C` order, with `-x` provenance. A
+   pre-existing `documentationandmemories` branch stops the run with a report — never
+   reuse it silently. Conflicts are aborted and surfaced as `CONFLICT` for editorial
+   resolution, never auto-resolved.
+
+4. **Push and hand off PR creation to `Agent(pr-author)`.** Push the consolidation
+   branch (`git push`). Refresh the PR-context bundle with
+   `mcp__drm-copilot__collect_pr_context` using base branch `main` (producing
+   `artifacts/pr_context.summary.txt` and `artifacts/pr_context.appendix.txt`).
+   Validate the orchestrator-state checkpoint
+   (`artifacts/orchestration/orchestrator-state.json`) with `--require-pr-creation-ready`
+   and record the `pr_author_preflight` result; delegation is prohibited when that
+   validation fails. Then delegate PR creation to `Agent(pr-author)` per
+   `.claude/skills/pr-author/SKILL.md`, using `<N> = 396` for the body-file and receipt
+   contract. This skill never authors or creates the PR itself.
+
+5. **Wait for merge and verify git-natively.** After the consolidation PR merges,
+   verify it with `git fetch` followed by
+   `git merge-base --is-ancestor documentationandmemories main`. Exit 0 confirms every
+   consolidated commit is now reachable from `main`; that is the only state that unlocks
+   deletion of branches whose unique content was consolidated.
+
+6. **Run the apply-mode deletion.** Run `bash scripts/bash/cleanup-worktrees.sh --apply`.
+   It re-verifies each candidate's ancestry/equivalence in-process, removes worktrees
+   (without force; a dirty worktree is reported via `DIRTY|` lines and skipped), then
+   deletes branches with `git branch -D`. The now-merged `documentationandmemories`
+   branch and its worktree become `MERGED_CLEAN` instances and are cleaned up by the same
+   mechanics.
+
+## Nothing to Consolidate (Short Path)
+
+When report mode classifies every candidate as `MERGED_CLEAN` or `MERGED_EQUIVALENT`
+with an empty cherry-pick-candidate list, skip steps 3-5 entirely: proceed directly from
+the report to `bash scripts/bash/cleanup-worktrees.sh --apply`. Cleanup completes in a
+single session with no PR.
+
+## Prohibited Shortcuts
+
+- Never invoke `gh pr create` or `gh pr edit --body*` from this skill or the scripts. PR
+  authoring is `Agent(pr-author)`'s exclusive responsibility and is enforced by the
+  `enforce-pr-author-skill.ps1` PreToolUse hook.
+- Never pass a force flag to `git worktree remove`. A dirty worktree blocks deletion and
+  is reported for manual handling; it is never force-removed.
+- Never execute `git worktree prune`. Prunable registrations are report-only.
+- Never act on `NOT_MERGED`, `HAS_UNIQUE_RESIDUALS`, or `PROTECTED_CURRENT` candidates;
+  the caller's worktree and branch, and the main worktree, are never mutated.
+- Never use commit-message text matching as a classification input, and never
+  auto-resolve cherry-pick conflicts.
+
+## Cross-References
+
+- `.claude/skills/pr-author/SKILL.md` — the PR body/receipt contract and the delegation
+  target for step 4.
+- `.claude/skills/pr-context-artifacts/SKILL.md` — how the PR-context bundle is collected
+  and the base-branch resolution rules.
+- `.claude/rules/shell.md` — the bash toolchain (shfmt/shellcheck/bats/kcov), the
+  500-line cap, the no-temp-files test policy, and the `CLEANUP_WT_GIT_BIN` seam
+  convention.

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

@@ -0,0 +1,65 @@
+---
+name: discovery-behavior-reconciliation
+description: 'Capture unspecified or contradictory behavior and reconcile it into product decisions in the discovery workflow. Use when recording unspecified-behavior findings from the parity matrix and reconciling them into product-decision records via the reconciler role. Sixth stage, after parity and before the validation gate.'
+---
+
+# Discovery Behavior Reconciliation
+
+Runs the reconciliation stage of the discovery and parity-definition workflow.
+It captures behavior that is unspecified or contradictory across the legacy
+source, the runtime observations, and the parity matrix, then reconciles each
+finding into a product decision. All domain specificity is read from the domain
+profile at runtime.
+
+## When to Use This Skill
+
+- The parity matrix has flagged gaps or contradictions that need a documented
+  resolution.
+- You need product-decision records before the final validation gate.
+
+## Prerequisites
+
+- `discovery-parity-matrix` has completed.
+- The domain profile is loaded and valid.
+
+## Workflow
+
+1. **Capture unspecified behavior.** Record each unspecified or contradictory
+   behavior as a record conforming to the schema
+   `schemas/discovery/v1/unspecified-behavior-record.schema.json`, citing the
+   parity-matrix entry and evidence that surfaced it.
+
+2. **Reconcile into product decisions.** For each captured record, produce a
+   product-decision record conforming to the schema
+   `schemas/discovery/v1/product-decision-record.schema.json`, stating the
+   decision and its rationale.
+
+3. **Route reconciliation.** Hand the records to the reconciler role for the
+   reconciliation decision (see `## Worker Routing`).
+
+## Worker Routing
+
+- Worker: `requirements-reconciler`
+
+The reconciler role decides how each unspecified or contradictory behavior is
+resolved and records the outcome as a product decision.
+
+## Validation
+
+- Validate unspecified-behavior records with
+  `dev.discovery.validate-unspecified-behavior`.
+- Validate product-decision records with
+  `dev.discovery.validate-product-decision`.
+- An empty error list is a pass. On any error, follow the direction in
+  `discovery-validate-artifacts`.
+
+## Referenced Skills
+
+- `discovery-workflow` — stage order and the canonical Referenced Contracts
+  registry.
+- `discovery-validate-artifacts` — pass/fail semantics and error routing.
+
+## Notes
+
+- Product-decision records complete the artifact set consumed by the final
+  validation gate in `discovery-validate-artifacts`.

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

@@ -0,0 +1,66 @@
+---
+name: discovery-coverage-ledger
+description: 'Produce feature contracts and the coverage ledger from inventory output in the discovery workflow. Use when deriving the feature contract set and the migration coverage ledger from the repository inventory and routing coverage review to the coverage role. Third stage, after inventory and before runtime characterization.'
+---
+
+# Discovery Coverage Ledger
+
+Runs the coverage stage of the discovery and parity-definition workflow. It
+derives feature contracts and the coverage ledger from the inventory output, so
+that every inventoried unit of behavior has a contract and a tracked coverage
+state. All domain specificity is read from the domain profile at runtime.
+
+## When to Use This Skill
+
+- The inventory stage has produced analyzer outputs under the profile's artifact
+  root.
+- You need the feature contract set and the coverage ledger before runtime
+  characterization and parity analysis.
+
+## Prerequisites
+
+- `discovery-repo-inventory` has completed and recorded its outputs.
+- The domain profile is loaded and valid.
+
+## Workflow
+
+1. **Derive feature contracts.** From the inventory output, produce one feature
+   contract per inventoried unit of behavior, conforming to the schema
+   `schemas/discovery/v1/feature-contract.schema.json`.
+
+2. **Build the coverage ledger.** Aggregate the feature contracts into the
+   coverage ledger, conforming to the schema
+   `schemas/discovery/v1/coverage-ledger.schema.json`. The ledger records the
+   coverage state of each contract so later stages can measure parity progress.
+
+3. **Route coverage review.** Hand the ledger to the coverage role for review
+   (see `## Worker Routing`).
+
+## Worker Routing
+
+- Worker: `migration-coverage-reviewer`
+
+The coverage role reviews the derived feature contracts and the coverage ledger
+for completeness and correctness before the workflow proceeds to runtime
+characterization.
+
+## Validation
+
+- Validate feature contracts with `dev.discovery.validate-feature-contract`.
+- Validate the coverage ledger with `dev.discovery.validate-coverage-ledger`.
+- An empty error list is a pass. On any error, follow the direction in
+  `discovery-validate-artifacts`.
+
+## Referenced Skills
+
+- `discovery-workflow` — stage order and the canonical Referenced Contracts
+  registry.
+- `discovery-validate-artifacts` — pass/fail semantics and error routing.
+
+## Notes
+
+- Feature contracts and the coverage ledger are jointly derived from the
+  inventory, so contract authorship is assigned to this stage and reviewed by
+  the coverage role.
+- Outputs from this stage feed `discovery-runtime-characterization` and
+  `discovery-parity-matrix`.