@danmoisan/drm-copilot-mcp 1.1.23 → 1.1.25

package/resources/claude-customizations/.claude/hooks/enforce-python-batch-budget.ps1

@@ -7,14 +7,28 @@
     operation. When the target file is a Python file (.py), it decides whether the
     change may proceed in direct mode.
 
-    Direct mode counts distinct production Python paths per Claude Code session. The
-    running set is persisted under .claude/state/python-batch-budget.<session_id>.json,
-    and repeated edits to the same file are counted once. The 4th distinct production
-    path is denied with a PYTHON_LARGE_PATH_REQUIRED reason that instructs the caller
-    to route the change through /orchestrate.
-
-    The orchestrated large path is detected from
-    <root>/artifacts/orchestration/orchestrator-state.json. The selected route is the
+    Direct mode counts distinct production Python paths per Claude Code session and per
+    resolved target worktree, and repeated edits to the same file are counted once. The
+    4th distinct production path in one worktree is denied with a
+    PYTHON_LARGE_PATH_REQUIRED reason that instructs the caller to route the change
+    through /orchestrate.
+
+    The edited file is placed with Resolve-HookTargetWorktree from
+    .claude/lib/worktree-resolution/HookTargetWorktree.psm1. An absolute path resolves to
+    its nearest enclosing registered git worktree; a relative path, a path inside no
+    registered worktree, and an ambiguous result use the session root (the checkout that
+    holds this hook). The route is read from
+    artifacts/orchestration/orchestrator-state.json in the resolved target worktree.
+    The running set is kept under the session root, in
+    .claude/state/python-batch-budget.<session_id>.json when the resolved target worktree
+    is the session root and in
+    .claude/state/python-batch-budget.<session_id>.<worktree key>.json otherwise, where
+    the key comes from Get-HookTargetWorktreeKey; no state is written under another
+    worktree. A path under the root-level artifacts/ directory of the resolved target worktree
+    is gitignored scratch: it is allowed, consumes no slot, and writes no state. A
+    nested directory named artifacts elsewhere in the tree still counts.
+
+    The selected route is the
     route_id value when that key is present, otherwise the path_selected value, and it
     is usable only as a non-blank string. When the selected route is large,
     remediation, or preparation and the checkpoint is not terminal (next_step is not
@@ -38,9 +52,9 @@
     is composed into a file name, so a hostile id cannot escape the state
     directory. Resolving the id never creates the state directory.
 
-    Candidate paths are contained to the resolved root. A candidate that resolves
-    outside it is discarded: the decision is 'allow', no slot is consumed, and no
-    state is written. Persisted entries that fail the same containment test are
+    Candidate paths are contained to the resolved target worktree root. A candidate
+    that resolves outside it is discarded: the decision is 'allow', no slot is consumed,
+    and no state is written. Persisted entries that fail the same containment test are
     dropped when state is rehydrated, so a state file carried between worktrees
     cannot spend this worktree's budget.
 
@@ -48,9 +62,12 @@
     hookSpecificOutput.permissionDecision = 'deny' and exits 0. Files already counted
     are always allowed through.
 
-    Known limitation: a stale non-terminal large-path checkpoint left at the root
-    exempts a later direct-mode session at that root. Orchestrator checkpoint hygiene
-    (issue #673) moves foreign checkpoints aside before a new run.
+    Known limitations: an 8.3 short-name path, or a path reached through a junction,
+    that differs textually from the long path git reports matches no registered
+    worktree and falls back to the session root. A stale non-terminal large-path
+    checkpoint in a worktree exempts a later direct-mode session editing that worktree;
+    orchestrator checkpoint hygiene (issue #673) moves foreign checkpoints aside before
+    a new run.
 
 .NOTES
     Compatible with PowerShell 7+.
@@ -61,6 +78,7 @@ $script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot
 
 
 try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/HookTargetWorktree.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookTargetWorktree.psm1' -ErrorRecord $_ }
 $script:PythonBatchBudgetRouteImportFailure = $null; try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { $script:PythonBatchBudgetRouteImportFailure = 'enforce-batch-budget-route.ps1' }
 
 function Test-PythonBatchBudgetPathInRoot {
@@ -354,7 +372,8 @@ function Invoke-PythonBatchBudgetHook {
         [scriptblock] $WriteState = {
             param([string] $Path, [System.Collections.IDictionary] $State)
             $State | ConvertTo-Json -Depth 5 | Set-Content -Path $Path -Encoding UTF8
-        }
+        },
+        [scriptblock] $WorktreeListInvoker
     )
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
@@ -376,6 +395,25 @@ function Invoke-PythonBatchBudgetHook {
     }
     if ($script:PythonBatchBudgetRouteImportFailure) { return Get-PythonBatchBudgetBlockDecision -Reason "PYTHON_LARGE_PATH_REQUIRED: the route helper '$($script:PythonBatchBudgetRouteImportFailure)' failed to load, so the batch budget for '$normalized' cannot be evaluated; the gate fails closed." }
 
+    # The file is evaluated against the registered worktree that holds it. The session root
+    # stays the fallback for a relative path, a path in no registered worktree, and an
+    # ambiguous result, which keeps today's checkpoint, containment, and state-file name.
+    $resolverArguments = @{ SessionRoot = $Root; FilePath = @($filePath) }
+    if ($PSBoundParameters.ContainsKey('WorktreeListInvoker')) { $resolverArguments['WorktreeListInvoker'] = $WorktreeListInvoker }
+    $resolution = Resolve-HookTargetWorktree @resolverArguments
+    $targetRoot = $Root
+    $isSessionRoot = $true
+    if (-not $resolution.Ambiguous -and $null -ne $resolution.WorktreeRoot -and -not [string]::Equals($resolution.WorktreeRoot, (ConvertTo-HookTargetWorktreeNormalizedPath -Path $Root), [System.StringComparison]::OrdinalIgnoreCase)) {
+        $targetRoot = $resolution.WorktreeRoot
+        $isSessionRoot = $false
+    }
+
+    # The root-level artifacts/ directory is gitignored scratch, never a production file.
+    $relativePath = if ($normalized -match '^(/|[A-Za-z]:/)') { Get-HookTargetWorktreeRelativePath -Path $normalized -WorktreeRoot $targetRoot } else { $normalized }
+    if ($null -ne $relativePath -and $relativePath.StartsWith('artifacts/', [System.StringComparison]::OrdinalIgnoreCase)) {
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
+    }
+
     $stateDir = Join-Path -Path $Root -ChildPath '.claude/state'
 
     # Resolved before the directory is ensured, because reading the session-id
@@ -386,11 +424,12 @@ function Invoke-PythonBatchBudgetHook {
         -SessionIdFilePath (Join-Path -Path $stateDir -ChildPath 'current-session-id') `
         -ReadSessionIdFile $ReadSessionIdFile
 
-    $stateFile = Join-Path -Path $stateDir -ChildPath ("python-batch-budget.$resolvedSessionId.json")
+    $stateLeaf = if ($isSessionRoot) { "python-batch-budget.$resolvedSessionId.json" } else { "python-batch-budget.$resolvedSessionId.$(Get-HookTargetWorktreeKey -WorktreeRoot $targetRoot).json" }
+    $stateFile = Join-Path -Path $stateDir -ChildPath $stateLeaf
 
     # The checkpoint is read before any state operation, so the large path neither
     # creates the state directory nor reads or writes the state file.
-    $checkpointPath = Join-Path -Path $Root -ChildPath 'artifacts/orchestration/orchestrator-state.json'
+    $checkpointPath = Join-Path -Path $targetRoot -ChildPath 'artifacts/orchestration/orchestrator-state.json'
     $checkpointText = ''
     try {
         $checkpointText = [string](& $ReadCheckpoint $checkpointPath)
@@ -402,7 +441,7 @@ function Invoke-PythonBatchBudgetHook {
     $isLargePath = Test-BatchBudgetLargePathRoute -CheckpointText $checkpointText
     $observedRoute = Get-BatchBudgetSelectedRoute -CheckpointText $checkpointText
     if ($isLargePath) {
-        return Invoke-PythonBatchBudgetDecision -FilePath $filePath -State (Get-PythonBatchBudgetState -ProdCap $ProdCap) -StateFile $stateFile -Root $Root -LargePathRoute
+        return Invoke-PythonBatchBudgetDecision -FilePath $filePath -State (Get-PythonBatchBudgetState -ProdCap $ProdCap) -StateFile $stateFile -Root $targetRoot -LargePathRoute
     }
 
     if (-not (& $TestPathExists $stateDir)) {
@@ -414,13 +453,13 @@ function Invoke-PythonBatchBudgetHook {
     if (& $TestPathExists $stateFile) {
         try {
             $loaded = & $ReadState $stateFile | ConvertFrom-Json -ErrorAction Stop
-            $state = ConvertTo-PythonBatchBudgetState -InputObject $loaded -ProdCap $ProdCap -Root $Root
+            $state = ConvertTo-PythonBatchBudgetState -InputObject $loaded -ProdCap $ProdCap -Root $targetRoot
         } catch {
             Write-Verbose "Ignoring unreadable Python batch-budget state file '$stateFile': $($_.Exception.Message)"
         }
     }
 
-    $decision = Invoke-PythonBatchBudgetDecision -FilePath $filePath -State $state -StateFile $stateFile -Root $Root -ObservedRoute $observedRoute
+    $decision = Invoke-PythonBatchBudgetDecision -FilePath $filePath -State $state -StateFile $stateFile -Root $targetRoot -ObservedRoute $observedRoute
     if ($decision.shouldWriteState) {
         try {
             & $WriteState $stateFile $decision.state

package/resources/claude-customizations/.claude/hooks/record-discovery-agent-start.ps1

@@ -0,0 +1,132 @@
+<#
+.SYNOPSIS
+    Native SubagentStart attestation adapter for Claude Code discovery agents.
+
+.DESCRIPTION
+    Invoked by the Claude Code SubagentStart hook. The hook reads the start envelope,
+    derives the launch context from the payload alone (session, the host-assigned
+    agent_id and agent_type, and the literal parent root), and takes its decision
+    from the shared DiscoveryStart module. The start is observational: Claude Code
+    does not let a SubagentStart hook prevent the agent from running.
+
+    - a start whose agent type is not a discovery specialist is left to the
+      ordinary and epic attestation path and produces no output;
+    - a discovery specialist is attested when the protected store holds exactly one
+      prepared discovery-invocation bound to this host, session, parent and agent
+      type and the activation, deployment, agent profile hash and capability pins
+      agree; the start-attestation is recorded and the invocation moves to started;
+    - a start that cannot be attested writes the DISCOVERY_START_ATTESTATION_BLOCKED:
+      reason as the SubagentStart system message; the PreToolUse adapter then binds
+      the prepared invocation at the first controlled call or denies every grant.
+
+    No orchestrator checkpoint is read or written. An envelope the hook cannot read
+    and a dependency that fails to load write the reason to stderr at exit 2
+    (issue #980).
+
+.NOTES
+    Requires PowerShell 7+. Invokes NO external process and never reads a profile,
+    locator or payload field to decide identity or authority.
+#>
+[CmdletBinding()]
+param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
+
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryEncoding.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryEncoding.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryAuthority.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthority.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryPayload.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPayload.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryStartRecord.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStartRecord.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryStart.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStart.psm1' -ErrorRecord $_ }
+
+$script:DiscoveryStartReasonPrefix = 'DISCOVERY_START_ATTESTATION_BLOCKED:'
+$script:DiscoveryStartHandlerPath = $PSCommandPath
+
+function Get-DiscoveryStartHandlerSha256 {
+    <#
+    .SYNOPSIS
+        Returns the SHA-256 of this handler's own bytes for the attestation writer record.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory = $false)][AllowNull()][string]$HandlerPath = $script:DiscoveryStartHandlerPath)
+
+    if ([string]::IsNullOrEmpty($HandlerPath) -or -not (Test-Path -LiteralPath $HandlerPath -PathType Leaf)) {
+        return ('0' * 64)
+    }
+    return Get-DiscoveryBytesSha256Hex -Bytes ([System.IO.File]::ReadAllBytes($HandlerPath))
+}
+
+function Invoke-DiscoveryAgentStartDecision {
+    <#
+    .SYNOPSIS
+        Parses the SubagentStart envelope and returns the shared start outcome.
+    .DESCRIPTION
+        Returns the outcome object (Decision skip, observe or attest; Code; Reason;
+        Attestation; AttestationPath; Invocation). Every seam defaults to the real
+        host and is injectable so tests run over in-memory values. A recorded
+        dependency failure denies before the envelope is read.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$PayloadRaw,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$HostEnvironment = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$Store = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][nullable[datetime]]$Now = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][string]$Nonce = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][scriptblock]$ReadBytes = $null
+    )
+    if (Test-HookDependencyFailure) {
+        $reason = Get-HookDependencyFailureReason -ReasonPrefix $script:DiscoveryStartReasonPrefix
+        return [pscustomobject]@{ Decision = 'deny'; Code = 'DEPENDENCY'; Reason = $reason.Substring($script:DiscoveryStartReasonPrefix.Length).TrimStart(); Attestation = $null; AttestationPath = $null; Invocation = $null }
+    }
+
+    # Seams resolve only after the dependency check so a missing module denies
+    # instead of raising while a default is evaluated.
+    if ($null -eq $HostEnvironment) { $HostEnvironment = Get-DiscoveryTrustedHostEnvironment }
+    if ($null -eq $Store) { $Store = Get-DiscoveryStartStore }
+    if ($null -eq $Now) { $Now = [datetime]::UtcNow }
+    if ([string]::IsNullOrEmpty($Nonce)) { $Nonce = Get-DiscoveryAuthorizationNonceText }
+
+    $normalized = ConvertFrom-DiscoveryHostPayloadText -HostName 'claude-code' -Text $PayloadRaw
+    $parameters = @{
+        Normalized = $normalized; HostEnvironment = $HostEnvironment
+        HandlerSha256 = (Get-DiscoveryStartHandlerSha256); Store = $Store; Now = $Now; Nonce = $Nonce
+    }
+    if ($null -ne $ReadBytes) { $parameters['ReadBytes'] = $ReadBytes }
+    return Get-DiscoveryStartDecision @parameters
+}
+
+function Invoke-DiscoveryAgentStartEntryPoint {
+    <#
+    .SYNOPSIS
+        Reads one SubagentStart payload, writes the hook output and returns the process exit code.
+    .DESCRIPTION
+        An unreadable envelope or a dependency failure writes its reason to stderr
+        and returns 2. An observed (unattested) start writes the SubagentStart output
+        JSON to stdout and returns 0. A skipped or attested start writes nothing and returns 0.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$PayloadRaw)
+
+    $outcome = Invoke-DiscoveryAgentStartDecision -PayloadRaw $PayloadRaw
+    if ($outcome.Decision -notin @('deny', 'observe')) { return 0 }
+    if ($outcome.Code -in @('ENVELOPE', 'DEPENDENCY')) {
+        [Console]::Error.WriteLine("$($script:DiscoveryStartReasonPrefix) $($outcome.Reason)")
+        return 2
+    }
+    $output = ConvertTo-DiscoveryStartHookOutput -Outcome $outcome -ReasonPrefix $script:DiscoveryStartReasonPrefix
+    [Console]::Out.WriteLine(($output | ConvertTo-Json -Compress -Depth 5))
+    return 0
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('DISCOVERY_START_ATTESTATION_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'DISCOVERY_START_ATTESTATION_BLOCKED:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
+
+exit (Invoke-DiscoveryAgentStartEntryPoint -PayloadRaw (Read-ClaudeHookRawPayload))

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

@@ -1,244 +1,88 @@
 <#
 .SYNOPSIS
-    SubagentStop hook that validates discovery artifacts referenced in a
-    terminating subagent's final output.
+    SubagentStop hook that validates a discovery specialist's protected output authority.
 
 .DESCRIPTION
     Invoked by the Claude Code SubagentStop hook under the existing broad
-    generic-agent matcher group. The hook reads the SubagentStop envelope JSON
-    from stdin through the shared envelope helper (subagentstop-envelope.ps1),
-    takes its last_assistant_message field (the terminating subagent's last
-    assistant message), 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
-    via Invoke-DiscoveryValidatorExe.
-
-    Any referenced artifact that fails validation blocks the subagent's
-    termination: the hook writes the reason with a
-    DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix to stderr and exits 2 through the
-    shared envelope helper. An invalid envelope (empty, not valid JSON, not a
-    JSON object, or without a string last_assistant_message) also blocks, with
-    a "DISCOVERY_ARTIFACT_GATE_BLOCKED: payload anomaly" reason. The hook
-    allows termination when the last assistant message is blank, when it
-    references no discovery-artifact path, when the required-artifact
-    declaration is absent (fail-open), or when every referenced artifact
-    passes validation.
-
-    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.
+    generic-agent matcher group. The hook reads the SubagentStop envelope through
+    the shared envelope helper (subagentstop-envelope.ps1), derives the stopping
+    principal from the payload alone (session, the host-assigned agent_id and
+    agent_type, and the literal parent root), and takes its decision from the
+    shared DiscoveryStop module:
+
+    - a stop whose agent type is not a discovery specialist is allowed, so the
+      other SubagentStop validators keep their behavior;
+    - a discovery specialist may stop only when its protected invocation was
+      finalized through the gateway and the completion receipt is the gateway's
+      validation-receipt for this invocation, session, role and gate mode, bound to
+      the current activation and workspace, with every required output present,
+      every input unchanged since the receipt and output_valid true; the
+      migration-coverage-reviewer may stop on a valid failing report;
+    - filenames or success prose in the final message never admit a stop, and a
+      blank final message never skips the validation.
+
+    A stop that cannot be validated blocks: the reason is written with the
+    DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix to stderr and the hook exits 2 through
+    the shared envelope helper. An invalid envelope blocks with a "payload anomaly"
+    reason. An unhandled error during validation blocks with exit 2 and a reason
+    (issue #928). No orchestrator checkpoint is read or written.
 
 .NOTES
-    Requires PowerShell 7.4+ (the shared validation module uses
-    `Test-Json -SchemaFile` Draft 2020-12 support). Read-only validation gate that
-    invokes NO external process: validation runs in-process through
-    `.claude/lib/discovery-validation/DiscoveryValidation.psm1` (issue #475).
-    An unhandled error during validation blocks with exit 2 and a reason (issue #928).
+    Requires PowerShell 7+. Invokes NO external process and never reads a profile,
+    locator or final-message field to decide identity or authority (issue #980).
 #>
 [CmdletBinding()]
 param()
 $script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
-try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryValidation.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryValidation.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryEncoding.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryEncoding.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryAuthority.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthority.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryManifest.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryManifest.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryPayload.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPayload.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryStartRecord.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStartRecord.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryStop.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStop.psm1' -ErrorRecord $_ }
 
-function Invoke-DiscoveryValidatorExe {
-    <#
-    .SYNOPSIS
-        Wrapper around the discovery-artifact validator. Mockable seam.
-    .DESCRIPTION
-        Delegates to the portable PowerShell implementation in
-        `.claude/lib/discovery-validation/DiscoveryValidation.psm1`, keeping this
-        function's name, its `-ValidatorArgs <string[]>` parameter, and its
-        `@{ ExitCode; Output }` return shape unchanged so existing mocks and
-        `Should -Invoke` assertions continue to bind.
-
-        This no longer invokes a Python interpreter (issue #475). The `.claude/**`
-        payload ships to destinations with no guaranteed Python, Poetry, or
-        `scripts/dev_tools`, where the previous `python -m ...` call failed
-        obscurely or blocked every operation.
-
-        Success is SILENT by contract: a passing validation returns `ExitCode = 0`
-        with an EMPTY `Output`. The caller denies on a non-zero exit code OR on
-        non-empty output, so any success chatter here would deny a passing
-        validation (defect D-2).
-    #>
-    [CmdletBinding()]
-    [OutputType([hashtable])]
-    param(
-        [Parameter(Mandatory = $true)]
-        [string[]] $ValidatorArgs
-    )
-
-    $modulePath = Join-Path -Path $PSScriptRoot `
-        -ChildPath '../lib/discovery-validation/DiscoveryValidation.psm1'
-    if (-not (Test-Path -LiteralPath $modulePath -PathType Leaf)) {
-        return @{ ExitCode = 1; Output = "Discovery-validation module not found: $modulePath" }
-    }
-
-    Import-Module -Name $modulePath -Force -ErrorAction Stop
-    return Invoke-DiscoveryArtifactValidation -ValidatorArgs $ValidatorArgs
-}
-
-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 ($trimmed -and (Get-DiscoveryArtifactType -Path $trimmed)) {
-            if (-not $foundReferences.Contains($trimmed)) {
-                $foundReferences.Add($trimmed)
-            }
-        }
-    }
-
-    return [string[]]$foundReferences
-}
+$script:DiscoveryGateReasonPrefix = 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
 
 function Invoke-DiscoveryArtifactGateValidation {
     <#
     .SYNOPSIS
-        Reads the SubagentStop envelope and returns an Ok/Message validation
-        result for a discovery-artifact completion gate.
+        Reads the SubagentStop envelope and returns an Ok/Message validation result for a discovery stop.
+    .DESCRIPTION
+        Every seam defaults to the real host (platform state roots, protected
+        store, workspace bytes) and is injectable so tests run over in-memory
+        values. A recorded dependency failure blocks before the envelope is read.
+        The result also carries the shared outcome Code for diagnostics.
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
         [AllowNull()] [AllowEmptyString()] [string] $InputText,
-
-        [Parameter(Mandatory = $false)]
-        [scriptblock] $RequiredArtifactReader = { Get-RequiredDiscoveryArtifactDeclaration }
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$HostEnvironment = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$Store = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][scriptblock]$ReadBytes = $null
     )
-    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix $script:DiscoveryGateReasonPrefix
     if ($null -ne $dependencyDecision) { return $dependencyDecision }
     $envelope = if ($PSBoundParameters.ContainsKey('InputText')) { Read-SubagentStopEnvelope -InputText $InputText } else { Read-SubagentStopEnvelope }
-    if (-not $envelope.IsValid) { return @{ Ok = $false; Message = "DISCOVERY_ARTIFACT_GATE_BLOCKED: payload anomaly - $(Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)" } }
-    $assistantMessage = [string]$envelope.AssistantText
+    if (-not $envelope.IsValid) { return @{ Ok = $false; Message = "$($script:DiscoveryGateReasonPrefix) payload anomaly - $(Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)"; Code = 'ENVELOPE' } }
 
-    $references = Find-DiscoveryArtifactReference -OutputText $assistantMessage
-    if ($references.Count -eq 0) {
-        return @{ Ok = $true; Message = $null }
-    }
+    # Seams resolve only after the dependency check so a missing module blocks
+    # instead of raising while a default is evaluated.
+    if ($null -eq $HostEnvironment) { $HostEnvironment = Get-DiscoveryTrustedHostEnvironment }
+    if ($null -eq $Store) { $Store = Get-DiscoveryStartStore }
 
-    $requiredDeclaration = & $RequiredArtifactReader
-    if (-not $requiredDeclaration.Present) {
-        # Fail open: no domain profile / required-artifact declaration present.
-        return @{ Ok = $true; Message = $null }
+    $normalized = ConvertFrom-DiscoveryHostEnvelope -HostName 'claude-code' -Envelope $envelope.Envelope
+    $parameters = @{
+        Normalized = $normalized; HostEnvironment = $HostEnvironment
+        AssistantText = [string]$envelope.AssistantText; StopHookActive = [bool]$envelope.StopHookActive; Store = $Store
     }
-
-    foreach ($reference in $references) {
-        $artifactType = Get-DiscoveryArtifactType -Path $reference
-        $validatorResult = Invoke-DiscoveryValidatorExe -ValidatorArgs @($artifactType, $reference)
-        $hasErrorOutput = -not [string]::IsNullOrWhiteSpace($validatorResult['Output'])
-        if ($validatorResult['ExitCode'] -ne 0 -or $hasErrorOutput) {
-            return @{ Ok = $false; Message = "DISCOVERY_ARTIFACT_GATE_BLOCKED: $($validatorResult['Output'])" }
-        }
+    if ($null -ne $ReadBytes) { $parameters['ReadBytes'] = $ReadBytes }
+    $outcome = Get-DiscoveryStopDecision @parameters
+    if ($outcome.Decision -eq 'block') {
+        return @{ Ok = $false; Message = "$($script:DiscoveryGateReasonPrefix) $($outcome.Reason)"; Code = $outcome.Code }
     }
-
-    return @{ Ok = $true; Message = $null }
+    return @{ Ok = $true; Message = $null; Code = $outcome.Code }
 }
 
 # Guard allows dot-sourcing in tests without executing the entrypoint.