@danmoisan/drm-copilot-mcp 1.1.23 → 1.1.25

package/resources/lib/discovery-validation/DiscoveryStartRecord.psm1

@@ -0,0 +1,296 @@
+<#
+.SYNOPSIS
+    Agent-profile, record and store primitives for native discovery start attestation.
+
+.DESCRIPTION
+    The SubagentStart adapters of Claude Code, Codex and GitHub Copilot share these
+    primitives: the per-host agent profile location and its Markdown front-matter
+    reader, UTC instant coercion for record timestamps, the started transition of
+    a protected invocation record (System.Text.Json preserves every untouched
+    value verbatim), the `start-attestation` record and the real filesystem store
+    seams. The discovery agent-type grammar lives in DiscoveryPayload.psm1
+    (`Get-DiscoveryAgentRole`). Nothing here reads an environment value or
+    decides; the decision lives in DiscoveryStart.psm1.
+
+.NOTES
+    Issue #980. Compatible with PowerShell 7+. Depends only on the sibling
+    DiscoveryEncoding module.
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+Import-Module (Join-Path $PSScriptRoot 'DiscoveryEncoding.psm1') -ErrorAction Stop
+
+$script:StartAttestationSchema = 'urn:drm-copilot:discovery:2.0.0:start-attestation'
+$script:StartAttestationFile = 'start-attestation.json'
+# Where each host keeps the generated specialist profile the root launches.
+$script:AgentProfileLayout = @{
+    'claude-code'    = @{ Directory = '.claude/agents'; Suffix = '.md' }
+    'codex'          = @{ Directory = '.codex/agents'; Suffix = '.toml' }
+    'github-copilot' = @{ Directory = '.github/agents'; Suffix = '.agent.md' }
+}
+
+function Get-DiscoveryAgentProfilePath {
+    <#
+    .SYNOPSIS
+        Returns the workspace-relative profile path of a native discovery agent on HostName.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)][ValidateSet('claude-code', 'codex', 'github-copilot')][string]$HostName,
+        [Parameter(Mandatory = $true)][string]$AgentType
+    )
+
+    if ($AgentType -notmatch '^[A-Za-z0-9][A-Za-z0-9._-]*$') {
+        throw "AGENT_PROFILE_INVALID: '$AgentType' is not a valid agent profile name."
+    }
+    $layout = $script:AgentProfileLayout[$HostName]
+    return "$($layout.Directory)/$AgentType$($layout.Suffix)"
+}
+
+function ConvertFrom-DiscoveryMarkdownProfile {
+    <#
+    .SYNOPSIS
+        Reads name, model and effort from the YAML front matter of a Markdown agent profile.
+    .DESCRIPTION
+        Only scalar `key: value` lines of the first front-matter block are read; a
+        missing block or a missing `name` is a typed failure. Model and effort are
+        $null when the host profile does not declare them.
+    .OUTPUTS
+        [pscustomobject] ProfilePath, ProfileSha256, ProfileName, ProfileModel, ProfileReasoningEffort.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)][AllowEmptyString()][string]$Text,
+        [Parameter(Mandatory = $true)][string]$RelativePath,
+        [Parameter(Mandatory = $true)][string]$Sha256
+    )
+
+    $lines = $Text -split "`r?`n"
+    if ($lines.Count -lt 2 -or $lines[0].Trim() -ne '---') {
+        throw "AGENT_PROFILE_INVALID: '$RelativePath' has no YAML front matter."
+    }
+    $values = @{}
+    $closed = $false
+    foreach ($line in $lines[1..($lines.Count - 1)]) {
+        if ($line.Trim() -eq '---') { $closed = $true; break }
+        if ($line -match '^(?<key>[A-Za-z_][A-Za-z0-9_-]*):\s*(?<value>[^#]*?)\s*(?:#.*)?$' -and -not [string]::IsNullOrWhiteSpace($Matches['value'])) {
+            $values[$Matches['key']] = $Matches['value'].Trim().Trim('"', "'")
+        }
+    }
+    if (-not $closed) { throw "AGENT_PROFILE_INVALID: '$RelativePath' has an unterminated front-matter block." }
+    if (-not $values.ContainsKey('name')) { throw "AGENT_PROFILE_INVALID: '$RelativePath' declares no name." }
+    return [pscustomobject]@{
+        ProfilePath            = $RelativePath
+        ProfileSha256          = $Sha256
+        ProfileName            = [string]$values['name']
+        ProfileModel           = $(if ($values.ContainsKey('model')) { [string]$values['model'] } else { $null })
+        ProfileReasoningEffort = $(if ($values.ContainsKey('effort')) { [string]$values['effort'] } elseif ($values.ContainsKey('reasoning_effort')) { [string]$values['reasoning_effort'] } else { $null })
+    }
+}
+
+function Read-DiscoveryAgentProfile {
+    <#
+    .SYNOPSIS
+        Reads and hashes the Markdown agent profile of AgentType under WorkspaceRoot.
+    .DESCRIPTION
+        Claude Code and GitHub Copilot profiles are Markdown with front matter; the
+        Codex adapter reads its TOML profiles through its own parser and converts the
+        result, so this reader refuses the codex host. ReadBytes is the filesystem seam.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)][ValidateSet('claude-code', 'github-copilot')][string]$HostName,
+        [Parameter(Mandatory = $true)][string]$AgentType,
+        [Parameter(Mandatory = $true)][string]$WorkspaceRoot,
+        [Parameter(Mandatory = $false)][scriptblock]$ReadBytes = {
+            param([string]$Path)
+            if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return $null }
+            return [System.IO.File]::ReadAllBytes($Path)
+        }
+    )
+
+    $relativePath = Get-DiscoveryAgentProfilePath -HostName $HostName -AgentType $AgentType
+    $bytes = & $ReadBytes "$($WorkspaceRoot.TrimEnd('/', '\'))/$relativePath"
+    if ($null -eq $bytes) { throw "AGENT_PROFILE_INVALID: '$relativePath' does not exist." }
+    $bytes = [byte[]]$bytes
+    try {
+        $text = [System.Text.UTF8Encoding]::new($false, $true).GetString($bytes)
+    } catch {
+        throw "AGENT_PROFILE_INVALID: '$relativePath' is not valid UTF-8."
+    }
+    return ConvertFrom-DiscoveryMarkdownProfile -Text $text -RelativePath $relativePath -Sha256 (Get-DiscoveryBytesSha256Hex -Bytes $bytes)
+}
+
+function ConvertTo-DiscoveryUtcInstant {
+    <#
+    .SYNOPSIS
+        Coerces a decoded JSON timestamp (string or DateTime) to a UTC DateTime, or $null.
+    #>
+    [CmdletBinding()]
+    [OutputType([nullable[datetime]])]
+    param([Parameter(Mandatory = $false)][AllowNull()][object]$Value)
+
+    if ($Value -is [datetime]) { return $Value.ToUniversalTime() }
+    if ($Value -is [datetimeoffset]) { return $Value.UtcDateTime }
+    $parsed = [datetimeoffset]::MinValue
+    $styles = [System.Globalization.DateTimeStyles]::AssumeUniversal -bor [System.Globalization.DateTimeStyles]::AdjustToUniversal
+    if ($Value -is [string] -and [datetimeoffset]::TryParse($Value, [cultureinfo]::InvariantCulture, $styles, [ref]$parsed)) { return $parsed.UtcDateTime }
+    return $null
+}
+
+function ConvertTo-DiscoveryStartedInvocationText {
+    <#
+    .SYNOPSIS
+        Rewrites a prepared invocation record text to the started state.
+    .DESCRIPTION
+        Only `state`, `agent_id` and `start_attestation_ref` change; every other value,
+        including timestamps, keeps its original spelling because the document is
+        edited as a JSON node tree rather than re-serialized from PowerShell objects.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)][string]$Text,
+        [Parameter(Mandatory = $true)][string]$AgentId,
+        [Parameter(Mandatory = $true)][string]$StartAttestationRef
+    )
+
+    $node = [System.Text.Json.Nodes.JsonNode]::Parse($Text)
+    if ($node -isnot [System.Text.Json.Nodes.JsonObject]) { throw 'INVOCATION_RECORD_INVALID: the invocation record is not a JSON object.' }
+    $node['state'] = [System.Text.Json.Nodes.JsonValue]::Create('started')
+    $node['agent_id'] = [System.Text.Json.Nodes.JsonValue]::Create($AgentId)
+    $node['start_attestation_ref'] = [System.Text.Json.Nodes.JsonValue]::Create($StartAttestationRef)
+    $options = [System.Text.Json.JsonSerializerOptions]::new()
+    $options.WriteIndented = $true
+    $options.Encoder = [System.Text.Encodings.Web.JavaScriptEncoder]::UnsafeRelaxedJsonEscaping
+    return $node.ToJsonString($options) + "`n"
+}
+
+function ConvertTo-DiscoveryStartAttestationRecord {
+    <#
+    .SYNOPSIS
+        Builds the `start-attestation` record binding the trusted principal to one prepared invocation.
+    .DESCRIPTION
+        Every identity value comes from the principal, the protected record and the
+        host's profile read; the SubagentStart payload contributes only the agent
+        identifier the host assigned. ActualModel and ActualReasoningEffort are $null
+        when the host does not expose them in its start event.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory = $true)][pscustomobject]$Principal,
+        [Parameter(Mandatory = $true)][string]$AgentId,
+        [Parameter(Mandatory = $true)][string]$AgentType,
+        [Parameter(Mandatory = $true)][pscustomobject]$Record,
+        [Parameter(Mandatory = $true)][pscustomobject]$AgentProfile,
+        [Parameter(Mandatory = $false)][AllowNull()][string]$ActualModel,
+        [Parameter(Mandatory = $false)][AllowNull()][string]$ActualReasoningEffort,
+        [Parameter(Mandatory = $true)][string]$HandlerSha256,
+        [Parameter(Mandatory = $true)][datetime]$Now,
+        [Parameter(Mandatory = $true)][string]$Nonce
+    )
+
+    return [ordered]@{
+        '$schema'             = $script:StartAttestationSchema
+        schema_version        = '2.0.0'
+        artifact_kind         = 'start-attestation'
+        id                    = "start-$Nonce"
+        start_attestation_ref = "start-$Nonce"
+        invocation_ref        = [string]$Record.invocation_id
+        workspace             = [ordered]@{
+            workspace_root   = [string]$Record.workspace.workspace_root
+            workspace_sha256 = [string]$Record.workspace.workspace_sha256
+            profile_path     = [string]$Record.workspace.profile_path
+            profile_sha256   = [string]$Record.workspace.profile_sha256
+        }
+        host                  = $Principal.HostName
+        session_id            = $Principal.SessionId
+        parent_agent_id       = $Principal.ParentAgentId
+        agent_id              = $AgentId
+        agent_type            = $AgentType
+        role                  = [string]$Record.role
+        deployment            = [ordered]@{
+            agent_name       = [string]$Record.deployment.agent_name
+            model            = [string]$Record.deployment.model
+            reasoning_effort = [string]$Record.deployment.reasoning_effort
+            actual_model     = $(if ([string]::IsNullOrEmpty($ActualModel)) { $null } else { $ActualModel })
+            actual_effort    = $(if ([string]::IsNullOrEmpty($ActualReasoningEffort)) { $null } else { $ActualReasoningEffort })
+        }
+        agent_profile         = [ordered]@{
+            path   = $AgentProfile.ProfilePath
+            sha256 = $AgentProfile.ProfileSha256
+            name   = $AgentProfile.ProfileName
+        }
+        capability_ref        = [string]$Record.capability_ref
+        runtime               = $Record.runtime
+        attested_at           = $Now.ToUniversalTime().ToString("yyyy-MM-dd'T'HH:mm:ss'Z'")
+        writer                = [ordered]@{ host = $Principal.HostName; event = 'SubagentStart'; handler_sha256 = $HandlerSha256 }
+    }
+}
+
+function Get-DiscoveryStartStore {
+    <#
+    .SYNOPSIS
+        Returns the real-filesystem store seams (ReadText, ListEntries, WriteText, ReplaceText).
+    .DESCRIPTION
+        WriteText creates the attestation exclusively, so a second start for the same
+        invocation fails; ReplaceText rewrites the invocation record in place.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param()
+
+    return @{
+        ReadText    = {
+            param([string]$Path)
+            if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return $null }
+            return [System.IO.File]::ReadAllText($Path, [System.Text.Encoding]::UTF8)
+        }
+        ListEntries = {
+            param([string]$Directory)
+            if (-not (Test-Path -LiteralPath $Directory -PathType Container)) { return @() }
+            return @(Get-ChildItem -LiteralPath $Directory -Force | Sort-Object -Property Name | ForEach-Object { $_.Name })
+        }
+        WriteText   = {
+            param([string]$Path, [string]$Text)
+            $stream = [System.IO.File]::Open($Path, [System.IO.FileMode]::CreateNew, [System.IO.FileAccess]::Write, [System.IO.FileShare]::None)
+            try {
+                $bytes = [System.Text.Encoding]::UTF8.GetBytes($Text)
+                $stream.Write($bytes, 0, $bytes.Length)
+            } finally { $stream.Dispose() }
+        }
+        ReplaceText = {
+            param([string]$Path, [string]$Text)
+            [System.IO.File]::WriteAllText($Path, $Text, [System.Text.UTF8Encoding]::new($false))
+        }
+    }
+}
+
+function Get-DiscoveryStartAttestationFileName {
+    <#
+    .SYNOPSIS
+        Returns the file name of the start attestation inside an invocation directory.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    return $script:StartAttestationFile
+}
+
+Export-ModuleMember -Function `
+    Get-DiscoveryAgentProfilePath, `
+    ConvertFrom-DiscoveryMarkdownProfile, `
+    Read-DiscoveryAgentProfile, `
+    ConvertTo-DiscoveryUtcInstant, `
+    ConvertTo-DiscoveryStartedInvocationText, `
+    ConvertTo-DiscoveryStartAttestationRecord, `
+    Get-DiscoveryStartStore, `
+    Get-DiscoveryStartAttestationFileName

package/resources/lib/discovery-validation/DiscoveryStop.psm1

@@ -0,0 +1,336 @@
+<#
+.SYNOPSIS
+    Native SubagentStop validation of a discovery specialist's protected output authority.
+
+.DESCRIPTION
+    Every native discovery SubagentStop adapter (Claude Code, Codex, GitHub
+    Copilot) takes its decision from this module. A stop whose agent type is not
+    a discovery specialist is skipped, so ordinary and epic stop validation keeps
+    its existing path. For a discovery specialist the stop result is derived from
+    the protected invocation bound to the host-assigned agent identity, never from
+    the final assistant message: the invocation must be finalized through the
+    gateway, its completion receipt must be the gateway-written `validation-receipt`
+    for this invocation, session, role and gate mode, bound to the current
+    activation and workspace, with every required output still present, every
+    input unchanged since the receipt (re-read and re-hashed) and output_valid
+    true; only the migration-coverage-reviewer may stop on a valid failing report.
+    Filenames or success prose in the final text cannot admit a stop, and a blank
+    final text cannot skip the validation.
+
+    Store and workspace access flows through injected seams; no process is invoked
+    and no orchestrator checkpoint is read or written.
+
+.NOTES
+    Issue #980. Compatible with PowerShell 7+. Depends only on the sibling
+    DiscoveryEncoding, DiscoveryAuthority, DiscoveryManifest, DiscoveryPayload and
+    DiscoveryStartRecord modules.
+    CONVENTION: this module fails fast at module scope and imports its siblings with -ErrorAction Stop.
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+Import-Module (Join-Path $PSScriptRoot 'DiscoveryEncoding.psm1') -ErrorAction Stop
+Import-Module (Join-Path $PSScriptRoot 'DiscoveryAuthority.psm1') -ErrorAction Stop
+Import-Module (Join-Path $PSScriptRoot 'DiscoveryManifest.psm1') -ErrorAction Stop
+Import-Module (Join-Path $PSScriptRoot 'DiscoveryPayload.psm1') -ErrorAction Stop
+Import-Module (Join-Path $PSScriptRoot 'DiscoveryStartRecord.psm1') -ErrorAction Stop
+
+$script:ReceiptsPartition = 'receipts'
+$script:ReviewerRole = 'migration-coverage-reviewer'
+$script:ResultTokenPattern = '(?<![A-Za-z])(PASS|FAIL|BLOCKED)(?![A-Za-z])'
+$script:CorrelationIdPattern = '^[A-Za-z0-9][A-Za-z0-9._:-]*$'
+$script:RuntimeKeys = @('build_sha256', 'package_version', 'policy_sha256', 'policy_version', 'schema_version')
+
+function Get-DiscoveryStopOutcome {
+    <#
+    .SYNOPSIS
+        Builds one stop outcome (skip, allow or block) with its code and reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)][ValidateSet('skip', 'allow', 'block')][string]$Decision,
+        [Parameter(Mandatory = $true)][string]$Code,
+        [Parameter(Mandatory = $true)][string]$Reason,
+        [Parameter(Mandatory = $false)][AllowNull()][object]$Receipt = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][object]$Invocation = $null
+    )
+
+    return [pscustomobject]@{ Decision = $Decision; Code = $Code; Reason = $Reason; Receipt = $Receipt; Invocation = $Invocation }
+}
+
+function Read-DiscoveryStopJson {
+    <#
+    .SYNOPSIS
+        Reads one JSON object from the store, returning Text and Record or $null members.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)][hashtable]$Store,
+        [Parameter(Mandatory = $true)][string]$Path
+    )
+
+    $text = Invoke-DiscoveryStoreSeam -Seam $Store.ReadText -Arguments @($Path)
+    if ($null -eq $text) { return [pscustomobject]@{ Text = $null; Record = $null } }
+    try { $record = ConvertFrom-Json -InputObject ([string]$text) -Depth 16 } catch { $record = $null }
+    if ($record -isnot [System.Management.Automation.PSCustomObject]) { $record = $null }
+    return [pscustomobject]@{ Text = [string]$text; Record = $record }
+}
+
+function Find-DiscoveryAgentInvocationForStop {
+    <#
+    .SYNOPSIS
+        Finds the discovery invocations bound to the stopping agent (started or finalized).
+    .DESCRIPTION
+        Enumerates `<session>/invocations/*/invocation.json` and keeps every
+        `discovery-invocation` whose host, session, parent, agent type and agent id
+        equal the stopping principal's. An unreadable record is skipped.
+    .OUTPUTS
+        [pscustomobject] Count, Record, Directory.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)][pscustomobject]$Location,
+        [Parameter(Mandatory = $true)][pscustomobject]$Principal,
+        [Parameter(Mandatory = $true)][string]$AgentType,
+        [Parameter(Mandatory = $true)][string]$AgentId,
+        [Parameter(Mandatory = $true)][hashtable]$Store
+    )
+
+    $directory = "$(Get-DiscoverySessionDirectory -Location $Location -SessionId $Principal.SessionId)/invocations"
+    $bindings = [System.Collections.Generic.List[object]]::new()
+    foreach ($entry in @(Invoke-DiscoveryStoreSeam -Seam $Store.ListEntries -Arguments @($directory))) {
+        $read = Read-DiscoveryStopJson -Store $Store -Path "$directory/$entry/invocation.json"
+        $record = $read.Record
+        if ($null -eq $record) { continue }
+        $names = @($record.PSObject.Properties.Name)
+        $missing = @(@('artifact_kind', 'host', 'session_id', 'parent_agent_id', 'agent_id', 'state', 'deployment') | Where-Object { $names -notcontains $_ })
+        if ($missing.Count -gt 0 -or $record.deployment -isnot [System.Management.Automation.PSCustomObject]) { continue }
+        $bound = ($record.artifact_kind -eq 'discovery-invocation') -and ($record.host -eq $Principal.HostName) -and
+        ($record.session_id -eq $Principal.SessionId) -and ($record.parent_agent_id -eq $Principal.ParentAgentId) -and
+        ([string]$record.deployment.agent_name -ceq $AgentType) -and ([string]$record.agent_id -ceq $AgentId) -and
+        (@('started', 'finalized') -contains [string]$record.state)
+        if ($bound) { $bindings.Add([pscustomobject]@{ Record = $record; Directory = "$directory/$entry" }) }
+    }
+    if ($bindings.Count -ne 1) { return [pscustomobject]@{ Count = $bindings.Count; Record = $null; Directory = $null } }
+    return [pscustomobject]@{ Count = 1; Record = $bindings[0].Record; Directory = $bindings[0].Directory }
+}
+
+function Get-DiscoveryReceiptMismatch {
+    <#
+    .SYNOPSIS
+        Compares the completion receipt against the invocation, principal, activation and current workspace.
+    .DESCRIPTION
+        Returns $null when the receipt authorizes the stop, otherwise an object with
+        Code (RECEIPT, GATE, IDENTITY, FORGED, BINDING, STALE_ACTIVATION, RUNTIME,
+        OUTPUTS, OUTPUT_INVALID, RESULT, STALE_INPUTS or OUTPUT_MISSING) and Reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)][pscustomobject]$Receipt,
+        [Parameter(Mandatory = $true)][pscustomobject]$Record,
+        [Parameter(Mandatory = $true)][pscustomobject]$Principal,
+        [Parameter(Mandatory = $true)][string]$AgentId,
+        [Parameter(Mandatory = $true)][pscustomobject]$Activation,
+        [Parameter(Mandatory = $true)][string]$ActivationSha256,
+        [Parameter(Mandatory = $true)][pscustomobject]$Location,
+        [Parameter(Mandatory = $true)][scriptblock]$ReadBytes
+    )
+
+    $names = @($Receipt.PSObject.Properties.Name)
+    foreach ($required in @('artifact_kind', 'receipt_ref', 'mode', 'identity', 'writer', 'workspace', 'activation_sha256', 'runtime', 'required_outputs', 'output_valid', 'validation_result', 'input_manifest')) {
+        if ($names -notcontains $required) { return [pscustomobject]@{ Code = 'RECEIPT'; Reason = "the completion receipt lacks '$required'" } }
+    }
+    if ($Receipt.artifact_kind -ne 'validation-receipt' -or [string]$Receipt.receipt_ref -cne [string]$Record.completion_receipt_ref) {
+        return [pscustomobject]@{ Code = 'RECEIPT'; Reason = 'the completion receipt is not the validation-receipt the invocation names' }
+    }
+    if ([string]$Receipt.mode -ne 'agent-output') {
+        return [pscustomobject]@{ Code = 'GATE'; Reason = "the completion receipt was issued for gate mode '$($Receipt.mode)', not agent-output" }
+    }
+    $identity = $Receipt.identity
+    $identityBound = ($identity -is [System.Management.Automation.PSCustomObject]) -and ($identity.kind -eq 'discovery-agent') -and
+    ($identity.host -eq $Principal.HostName) -and ($identity.session_id -eq $Principal.SessionId) -and
+    ([string]$identity.agent_id -ceq $AgentId) -and ([string]$identity.role -ceq [string]$Record.role) -and
+    ([string]$identity.invocation_id -ceq [string]$Record.invocation_id)
+    if (-not $identityBound) {
+        return [pscustomobject]@{ Code = 'IDENTITY'; Reason = 'the completion receipt is bound to another agent, session, role or invocation' }
+    }
+    $writer = $Receipt.writer
+    if ($writer -isnot [System.Management.Automation.PSCustomObject] -or $writer.kind -ne 'host-gateway' -or $writer.host -ne $Principal.HostName) {
+        return [pscustomobject]@{ Code = 'FORGED'; Reason = 'the completion receipt was not written by the host gateway' }
+    }
+    $sameBinding = ([string]$Receipt.workspace.workspace_sha256 -eq $Location.WorkspaceSha256) -and
+    ([string]$Receipt.workspace.workspace_root -eq [string]$Record.workspace.workspace_root) -and
+    ([string]$Receipt.workspace.profile_path -eq [string]$Activation.profile_path) -and
+    ([string]$Receipt.workspace.profile_sha256 -eq [string]$Activation.profile_sha256)
+    if (-not $sameBinding) {
+        return [pscustomobject]@{ Code = 'BINDING'; Reason = 'the completion receipt is bound to another workspace or profile than the current activation' }
+    }
+    if ([string]$Receipt.activation_sha256 -cne $ActivationSha256) {
+        return [pscustomobject]@{ Code = 'STALE_ACTIVATION'; Reason = 'the activation record changed after the completion receipt was issued' }
+    }
+    foreach ($key in $script:RuntimeKeys) {
+        if ([string]$Receipt.runtime.$key -cne [string]$Record.runtime.$key) {
+            return [pscustomobject]@{ Code = 'RUNTIME'; Reason = "runtime pin $key of the receipt differs from the invocation" }
+        }
+    }
+    $outputs = $Receipt.required_outputs
+    if ($outputs -isnot [System.Management.Automation.PSCustomObject] -or [string]$outputs.manifest_sha256 -cne [string]$Record.required_outputs.manifest_sha256) {
+        return [pscustomobject]@{ Code = 'OUTPUTS'; Reason = 'the completion receipt does not carry the required-output manifest of the invocation' }
+    }
+    if ($Receipt.output_valid -isnot [bool] -or -not [bool]$Receipt.output_valid) {
+        return [pscustomobject]@{ Code = 'OUTPUT_INVALID'; Reason = 'the completion receipt does not mark the required outputs valid' }
+    }
+    $result = [string]$Receipt.validation_result
+    if ($result -ne 'pass' -and -not ($result -eq 'fail' -and [string]$Record.role -eq $script:ReviewerRole)) {
+        return [pscustomobject]@{ Code = 'RESULT'; Reason = "validation result '$result' does not complete role $($Record.role); only the reviewer may stop on a valid failing report" }
+    }
+    try {
+        $manifest = ConvertFrom-DiscoveryInputManifest -Value $Receipt.input_manifest
+    } catch {
+        return [pscustomobject]@{ Code = 'RECEIPT'; Reason = "the completion receipt input manifest is invalid: $($_.Exception.Message)" }
+    }
+    $comparison = Compare-DiscoveryInputManifest -Manifest $manifest -WorkspaceRoot ([string]$Record.workspace.workspace_root) `
+        -ProfilePath ([string]$Activation.profile_path) -ProfileSha256 ([string]$Activation.profile_sha256) -ReadBytes $ReadBytes
+    if ($comparison.Drift.Count -gt 0) {
+        $summary = @($comparison.Drift | ForEach-Object { "$($_.kind):$($_.path)" }) -join ', '
+        return [pscustomobject]@{ Code = 'STALE_INPUTS'; Reason = "inputs changed after the completion receipt: $summary" }
+    }
+    foreach ($output in @($outputs.outputs)) {
+        $rowNames = @($output.PSObject.Properties.Name)
+        if (@('artifact_kind', 'id', 'path') | Where-Object { $rowNames -notcontains $_ -or [string]::IsNullOrWhiteSpace([string]$output.$_) }) {
+            return [pscustomobject]@{ Code = 'OUTPUTS'; Reason = 'a required output row lacks its kind, id or path' }
+        }
+        $bytes = & $ReadBytes (Get-DiscoveryWorkspacePath -WorkspaceRoot ([string]$Record.workspace.workspace_root) -RelativePath ([string]$output.path))
+        if ($null -eq $bytes) {
+            return [pscustomobject]@{ Code = 'OUTPUT_MISSING'; Reason = "required output $($output.path) ($($output.artifact_kind) $($output.id)) is absent from the workspace" }
+        }
+    }
+    return $null
+}
+
+function Get-DiscoveryStopDecision {
+    <#
+    .SYNOPSIS
+        Decides one SubagentStop event for a native discovery adapter.
+    .DESCRIPTION
+        Order: envelope anomalies block; a non-discovery agent type is skipped; a
+        missing agent identity in the payload blocks; the activation must be active; exactly one
+        started or finalized invocation must bind this agent; the invocation must be
+        finalized with a completion receipt that passes Get-DiscoveryReceiptMismatch;
+        finally the final text must state the explicit result the receipt proves.
+        When StopHookActive is true a block becomes an allow with code CONTINUED so
+        the host does not loop; the authority remains with the receipts.
+    .OUTPUTS
+        [pscustomobject] Decision, Code, Reason, Receipt, Invocation.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)][pscustomobject]$Normalized,
+        [Parameter(Mandatory = $true)][hashtable]$HostEnvironment,
+        [Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$AssistantText = '',
+        [Parameter(Mandatory = $false)][bool]$StopHookActive = $false,
+        [Parameter(Mandatory = $false)][hashtable]$Store = (Get-DiscoveryStartStore),
+        [Parameter(Mandatory = $false)][AllowNull()][scriptblock]$ReadBytes = $null
+    )
+
+    $outcome = Get-DiscoveryStopVerdict -Normalized $Normalized -HostEnvironment $HostEnvironment `
+        -AssistantText $AssistantText -Store $Store -ReadBytes $ReadBytes
+    if ($outcome.Decision -eq 'block' -and $StopHookActive -and $outcome.Code -ne 'ENVELOPE') {
+        return Get-DiscoveryStopOutcome -Decision 'allow' -Code 'CONTINUED' -Reason "$($outcome.Reason) (a continuation was already requested; the protected receipts remain authoritative)" -Receipt $outcome.Receipt -Invocation $outcome.Invocation
+    }
+    return $outcome
+}
+
+function Get-DiscoveryStopVerdict {
+    <#
+    .SYNOPSIS
+        Evaluates the stop without the continuation rule; see Get-DiscoveryStopDecision.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $true)][pscustomobject]$Normalized,
+        [Parameter(Mandatory = $true)][hashtable]$HostEnvironment,
+        [Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$AssistantText = '',
+        [Parameter(Mandatory = $true)][hashtable]$Store,
+        [Parameter(Mandatory = $false)][AllowNull()][scriptblock]$ReadBytes = $null
+    )
+
+    if ($null -ne $Normalized.Anomaly) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'ENVELOPE' -Reason ('payload anomaly - ' + (Get-DiscoveryPayloadAnomalyReason -Code $Normalized.Anomaly))
+    }
+    $agentType = [string]$Normalized.AgentType
+    $role = Get-DiscoveryAgentRole -AgentType $agentType
+    if ($null -eq $role) {
+        return Get-DiscoveryStopOutcome -Decision 'skip' -Code 'NOT_DISCOVERY_AGENT' -Reason 'the stopping agent is not a discovery specialist; the ordinary stop validation applies'
+    }
+    # The principal (host, session, parent, agent) comes from the stop payload alone.
+    $principal = Get-DiscoveryTrustedPrincipal -Normalized $Normalized
+    if ($null -eq $principal.AgentId) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'IDENTITY' -Reason 'the native stop event carries no agent identifier for the discovery specialist'
+    }
+    $agentId = $principal.AgentId
+    if ([string]::IsNullOrWhiteSpace([string]$Normalized.Cwd)) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'WORKSPACE' -Reason 'the native event carries no workspace directory'
+    }
+    try {
+        $location = Resolve-DiscoveryAuthorityLocation -WorkspaceRoot ([string]$Normalized.Cwd) -Platform $HostEnvironment.Platform `
+            -UserHome $HostEnvironment.UserHome -LocalAppData $HostEnvironment.LocalAppData -XdgStateHome $HostEnvironment.XdgStateHome
+    } catch {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'WORKSPACE' -Reason $_.Exception.Message
+    }
+    $activation = Read-DiscoveryActivationState -Location $location -ReadText $Store.ReadText
+    if ($activation.Status -ne 'active') {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'ACTIVATION' -Reason "discovery is not active for this workspace ($($activation.Status): $($activation.Reason))"
+    }
+    $activationText = [string](Invoke-DiscoveryStoreSeam -Seam $Store.ReadText -Arguments @($activation.Path))
+    $found = Find-DiscoveryAgentInvocationForStop -Location $location -Principal $principal -AgentType $agentType -AgentId $agentId -Store $Store
+    if ($found.Count -eq 0) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'NO_INVOCATION' -Reason "no protected invocation binds agent $agentId ($agentType) in this session; the specialist stopped without an attested start"
+    }
+    if ($found.Count -gt 1) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'AMBIGUOUS' -Reason "$($found.Count) protected invocations bind agent $agentId; the stop cannot be attributed to one"
+    }
+    $record = $found.Record
+    if ([string]$record.role -cne $role) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'ROLE' -Reason "agent type $agentType acts as $role but the invocation was prepared for role $($record.role)" -Invocation $record
+    }
+    if ([string]$record.state -ne 'finalized' -or [string]::IsNullOrWhiteSpace([string]$record.completion_receipt_ref)) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'NOT_FINALIZED' -Reason "invocation $($record.invocation_id) was not finalized through finalize_discovery_agent; no output authority exists for this stop" -Invocation $record
+    }
+    $read = Read-DiscoveryStopJson -Store $Store -Path "$($found.Directory)/$($script:ReceiptsPartition)/$($record.completion_receipt_ref).json"
+    if ($null -eq $read.Record) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'RECEIPT' -Reason "the completion receipt $($record.completion_receipt_ref) is missing or unreadable in the protected store" -Invocation $record
+    }
+    if ($null -eq $ReadBytes) {
+        $ReadBytes = {
+            param([string]$Path)
+            if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return $null }
+            return [System.IO.File]::ReadAllBytes($Path)
+        }
+    }
+    $mismatch = Get-DiscoveryReceiptMismatch -Receipt $read.Record -Record $record -Principal $principal -AgentId $agentId -Activation $activation.Record `
+        -ActivationSha256 (Get-DiscoverySha256Hex -Text $activationText) -Location $location -ReadBytes $ReadBytes
+    if ($null -ne $mismatch) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code $mismatch.Code -Reason $mismatch.Reason -Receipt $read.Record -Invocation $record
+    }
+    # The final text never grants authority; it must only state the result the receipt proves.
+    $expectedToken = $(if ([string]$read.Record.validation_result -eq 'pass') { 'PASS' } else { 'FAIL' })
+    $tokens = @([regex]::Matches([string]$AssistantText, $script:ResultTokenPattern) | ForEach-Object { $_.Groups[1].Value })
+    if ($tokens -notcontains $expectedToken) {
+        return Get-DiscoveryStopOutcome -Decision 'block' -Code 'RESULT_TEXT' -Reason "the final message must state the explicit $expectedToken result the protected receipt proves" -Receipt $read.Record -Invocation $record
+    }
+    return Get-DiscoveryStopOutcome -Decision 'allow' -Code 'VALIDATED' -Reason "invocation $($record.invocation_id) of $role completed with a current $($read.Record.validation_result) receipt" -Receipt $read.Record -Invocation $record
+}
+
+Export-ModuleMember -Function `
+    Find-DiscoveryAgentInvocationForStop, `
+    Get-DiscoveryReceiptMismatch, `
+    Get-DiscoveryStopDecision, `
+    Get-DiscoveryStopVerdict