@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

package/resources/claude-customizations/.claude/hooks/validate-task-researcher-output.ps1

@@ -8,17 +8,29 @@
     under one of the two tracked research roots
     (docs/features/<feature>/research/ for feature-associated research, or
     docs/research/ for one-off research), matches the documented filename
-    convention, and the file exists on disk.
+    convention, and the file exists on disk. Feature-associated research under
+    docs/features/ must also carry a complete `## Pre-Mortem` section
+    (Test-PreMortemSection in premortem-section.ps1, issue #964); one-off
+    research under docs/research/ is exempt.
 
 .NOTES
-    Reads the hook payload from CLAUDE_HOOK_INPUT as JSON. Exits 0 to allow
-    termination; exits 1 with an error message to block. Filesystem reads go
-    through Test-ResearchFile so tests can mock the boundary without writing
-    temporary files.
+    Reads the SubagentStop envelope JSON from stdin through the shared
+    envelope helper (subagentstop-envelope.ps1) and validates its
+    last_assistant_message field, the researcher's last assistant message.
+    Exits 0 to allow termination. A block writes the reason to stderr and
+    exits 2 through the shared envelope helper; an invalid envelope blocks
+    with a payload anomaly reason. A hook dependency that fails to load
+    blocks with exit 2 and the validate-task-researcher-output: prefix.
+    Filesystem reads go through Test-ResearchFile and Get-ResearchFileContent
+    so tests can mock the boundary without writing temporary files.
+    An unhandled error during validation blocks with exit 2 and a reason (issue #928).
 #>
 
 [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 { . (Join-Path $PSScriptRoot 'premortem-section.ps1') } catch { Add-HookDependencyFailure -Name 'premortem-section.ps1' -ErrorRecord $_ }
 
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
@@ -34,6 +46,16 @@ function Test-ResearchFile {
     return [bool](Test-Path -LiteralPath $Path -PathType Leaf)
 }
 
+function Get-ResearchFileContent {
+    # File seam: returns the research file text, or $null when no file exists at the path.
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory = $true)] [string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return $null }
+    return Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+}
+
 function Get-ResearchPathFromOutput {
     [CmdletBinding()]
     [OutputType([string])]
@@ -94,7 +116,7 @@ function Test-IsValidResearchFileName {
     $fileName = [System.IO.Path]::GetFileName($normalized)
     return [regex]::IsMatch(
         $fileName,
-        '^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-[A-Za-z0-9][A-Za-z0-9-]*-research\.md$'
+        '^(?:(?:\d{4}-\d{2}-\d{2}(?:T\d{2}-?\d{2})?|\d{8})-[A-Za-z0-9][A-Za-z0-9-]*[-.]research|research(?:-addendum)?\.\d{4}-\d{2}-\d{2}(?:T\d{2}-\d{2})?)\.md$'
     )
 }
 
@@ -192,7 +214,7 @@ function Test-NumericDerivationEvidence {
         if (-not $match.Success) { return @{ Ok = $false; Message = "task-researcher hook: numeric derivation evidence is missing $label." } }
         $values[$label] = $match.Groups['value'].Value.Trim()
     }
-    if ($values['Exhaustive Search Scope'] -notmatch '(?i)\b(entire|all|complete)\b.*\b(repository|repo|source tree|tree)\b') {
+    if ($values['Exhaustive Search Scope'] -notmatch '(?i)\b(entire|whole|all|complete)\b.*\b(repository|repo|worktree|source tree|tree)\b') {
         return @{ Ok = $false; Message = 'task-researcher hook: numeric derivation evidence does not declare an exhaustive repository search scope.' }
     }
     $primaryStrategy = $values['Primary Search Strategy or Query Expression']
@@ -227,29 +249,18 @@ function Invoke-TaskResearcherOutputValidation {
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
-        [string] $RawPayload
+        [AllowNull()] [AllowEmptyString()] [string] $InputText
     )
-
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
-        return @{ Ok = $false; Message = 'task-researcher hook: CLAUDE_HOOK_INPUT is empty; cannot validate task-researcher output.' }
-    }
-
-    try {
-        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        return @{ Ok = $false; Message = "task-researcher hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" }
-    }
-
-    $agentOutput = $null
-    if ($payload.PSObject.Properties.Name -contains 'output') {
-        $agentOutput = $payload.output
-    }
-    if ([string]::IsNullOrWhiteSpace($agentOutput)) {
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-task-researcher-output:'
+    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 = "task-researcher hook: payload anomaly - $(Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)" } }
+    $assistantMessage = [string]$envelope.AssistantText
+    if ([string]::IsNullOrWhiteSpace($assistantMessage)) {
         return @{ Ok = $false; Message = 'task-researcher hook: agent output is empty; researcher must return research-path before termination.' }
     }
 
-    $researchPath = Get-ResearchPathFromOutput -AgentOutput $agentOutput
+    $researchPath = Get-ResearchPathFromOutput -AgentOutput $assistantMessage
     if ($null -eq $researchPath) {
         return @{ Ok = $false; Message = 'task-researcher hook: agent output does not advertise a research-path. Researcher must report `research-path: <path>` pointing to docs/features/<feature>/research/ (feature-associated) or docs/research/ (one-off).' }
     }
@@ -266,16 +277,22 @@ function Invoke-TaskResearcherOutputValidation {
         return @{ Ok = $false; Message = "task-researcher hook: researcher advertised research-path '$researchPath' but no file exists at that location." }
     }
 
-    $feasibilityResult = Test-AutomationFeasibilitySection -ResearchFilePath $researchPath -AgentOutput $agentOutput
+    $feasibilityResult = Test-AutomationFeasibilitySection -ResearchFilePath $researchPath -AgentOutput $assistantMessage
     if (-not $feasibilityResult.Ok) {
         return @{ Ok = $false; Message = $feasibilityResult.Message }
     }
 
-    if (Test-Path -LiteralPath $researchPath -PathType Leaf) {
-        $numericEvidenceResult = Test-NumericDerivationEvidence -Content (Get-Content -LiteralPath $researchPath -Raw -ErrorAction Stop)
+    try { $researchContent = Get-ResearchFileContent -Path $researchPath } catch { return @{ Ok = $false; Message = "task-researcher hook: failed to read research-path '$researchPath': $($_.Exception.Message)" } }
+    if ($null -ne $researchContent) {
+        $numericEvidenceResult = Test-NumericDerivationEvidence -Content $researchContent
         if (-not $numericEvidenceResult.Ok) {
             return $numericEvidenceResult
         }
+        # Issue #964: feature research carries a Pre-Mortem; one-off research under docs/research/ is exempt.
+        if ((($researchPath -replace '\\', '/') -replace '^\./', '').StartsWith('docs/features/', [System.StringComparison]::OrdinalIgnoreCase)) {
+            $preMortem = Test-PreMortemSection -Content ([string]$researchContent)
+            if (-not $preMortem.Ok) { return @{ Ok = $false; Message = "task-researcher hook: feature research '$researchPath' $($preMortem.Message)" } }
+        }
     }
 
     return @{ Ok = $true; Message = $null }
@@ -284,11 +301,10 @@ function Invoke-TaskResearcherOutputValidation {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
-
-$result = Invoke-TaskResearcherOutputValidation -RawPayload $env:CLAUDE_HOOK_INPUT
-if (-not $result.Ok) {
-    Write-Error $result.Message
-    exit 1
-}
-
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('validate-task-researcher-output: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-task-researcher-output:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
+try { $result = Invoke-TaskResearcherOutputValidation }
+catch { Exit-SubagentStopBlock -Message ('validate-task-researcher-output: validator error: ' + ([string]$_.Exception.Message -split "`r?`n")[0] + '; the gate fails closed.' + "`n" + 'This condition is not repairable by the subagent. Report it to the operator and halt.') }
+if (-not $result.Ok) { Exit-SubagentStopBlock -Message $result.Message }
 exit 0

package/resources/claude-customizations/.claude/lib/bash/mutate-parallel-run.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# mutate-parallel-run.sh: destination-portable command-line entry point for the
+# decision and audit-record steps of the parallel-add, parallel-close, and
+# parallel-orchestrate skills (issue #890). It exists so a workspace that
+# received the Claude customization payload can run those steps with nothing
+# but bash -- no interpreter, no repository checkout.
+#
+# Usage:
+#   bash .claude/lib/bash/mutate-parallel-run.sh admit --candidate <key> \
+#       [--edges "<a>:<b> ..."] --in-flight "<k> ..." \
+#       --current-cohort-members "<k> ..."
+#   bash .claude/lib/bash/mutate-parallel-run.sh recolor --unstarted "<k> ..." \
+#       [--edges "<a>:<b> ..."] --pinned "<k> ..." --generation <g> \
+#       --current-cohort <c> --highest-pinned-cohort <h>
+#   bash .claude/lib/bash/mutate-parallel-run.sh add-entry --item <key> \
+#       --deferred true|false --generation <g> [--at <timestamp>]
+#   bash .claude/lib/bash/mutate-parallel-run.sh close --items "<k>:<state> ..."
+#   bash .claude/lib/bash/mutate-parallel-run.sh close-entry --generation <g> \
+#       [--at <timestamp>]
+#   bash .claude/lib/bash/mutate-parallel-run.sh requeue-entry --item <key> \
+#       --generation <g> [--at <timestamp>]
+#
+# `--edges` is optional; `--in-flight`, `--current-cohort-members`,
+# `--unstarted`, `--pinned`, and `--items` accept an empty string. Integer
+# tokens match `-?(0|[1-9][0-9]*)`. An `--items` token is an integer, a colon,
+# and a `[A-Za-z_]+` state; a duplicate key is a usage error. `--at` defaults to
+# the current UTC time as yyyy-MM-ddTHH-mm; the clock is read only when `--at`
+# is omitted.
+#
+# Exit-code contract (identical to remove-parallel-item.sh):
+#   exit 0  success; one compact JSON object on stdout
+#   exit 1  rule rejection; the reference implementation's exact message as
+#           one stderr line
+#   exit 2  usage error; one stderr line beginning
+#           "PARALLEL_MUTATION_ERROR: usage error:"
+# Argument validation runs first, then rule rejection, then output.
+#
+# Parity reference: scripts/dev_tools/parallel_mutation_protocol.py
+# (decide_admission, recolor_unstarted, decide_close) and
+# scripts/dev_tools/_parallel_mutation_entries.py (build_add_entry,
+# build_close_entry, build_requeue_entry).
+#
+# Declared divergences (also listed in both parity lanes):
+#   1. A duplicate key in `close --items` is a usage error (exit 2); the Python
+#      mapping would silently keep the last record for that key.
+#   2. `at` is a caller-supplied string instead of a `datetime`.
+#   3. Option abbreviations are rejected.
+#   4. `admit` has no rejection branch, in either implementation.
+set -euo pipefail
+
+# Resolve this script's own directory so the libraries source regardless of cwd.
+MPR_SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-mutation-ops.sh
+# shellcheck disable=SC1091
+source "$MPR_SCRIPT_DIR/parallel-mutation-ops.sh"
+# shellcheck source=.claude/lib/bash/parallel-mutation-cli.sh
+# shellcheck disable=SC1091
+source "$MPR_SCRIPT_DIR/parallel-mutation-cli.sh"
+
+pc_enforce_c_locale
+
+mpr_admit() {
+	# Run the admit subcommand.
+	local candidate edges in_flight members rc=0
+	pmcli_parse_options "candidate edges in-flight current-cohort-members" "$@"
+	pmcli_require candidate in-flight current-cohort-members
+	pmcli_integer "${PMCLI_OPTS[candidate]}" "--candidate"
+	candidate="$PMCLI_VALUE"
+	pmcli_edge_list "${PMCLI_OPTS[edges]-}"
+	edges="$PMCLI_VALUE"
+	pmcli_integer_list "${PMCLI_OPTS["in-flight"]}" "--in-flight"
+	in_flight="$PMCLI_VALUE"
+	pmcli_integer_list "${PMCLI_OPTS["current-cohort-members"]}" "--current-cohort-members"
+	members="$PMCLI_VALUE"
+	pm_decide_admission "$candidate" "$edges" "$in_flight" "$members" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_recolor() {
+	# Run the recolor subcommand; same options as remove-parallel-item.sh.
+	local unstarted edges pinned generation current highest rc=0
+	pmcli_parse_options "unstarted edges pinned generation current-cohort highest-pinned-cohort" "$@"
+	pmcli_require unstarted pinned generation current-cohort highest-pinned-cohort
+	pmcli_integer_list "${PMCLI_OPTS[unstarted]}" "--unstarted"
+	unstarted="$PMCLI_VALUE"
+	pmcli_edge_list "${PMCLI_OPTS[edges]-}"
+	edges="$PMCLI_VALUE"
+	pmcli_integer_list "${PMCLI_OPTS[pinned]}" "--pinned"
+	pinned="$PMCLI_VALUE"
+	pmcli_integer "${PMCLI_OPTS[generation]}" "--generation"
+	generation="$PMCLI_VALUE"
+	pmcli_integer "${PMCLI_OPTS["current-cohort"]}" "--current-cohort"
+	current="$PMCLI_VALUE"
+	pmcli_integer "${PMCLI_OPTS["highest-pinned-cohort"]}" "--highest-pinned-cohort"
+	highest="$PMCLI_VALUE"
+	pm_recolor_unstarted "$unstarted" "$edges" "$pinned" "$generation" "$current" "$highest" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_add_entry() {
+	# Run the add-entry subcommand.
+	local item deferred generation at rc=0
+	pmcli_parse_options "item deferred generation at" "$@"
+	pmcli_require item deferred generation
+	pmcli_integer "${PMCLI_OPTS[item]}" "--item"
+	item="$PMCLI_VALUE"
+	deferred="${PMCLI_OPTS[deferred]}"
+	[[ $deferred == true || $deferred == false ]] ||
+		pmcli_usage_error "--deferred must be true or false; found: $deferred"
+	pmcli_integer "${PMCLI_OPTS[generation]}" "--generation"
+	generation="$PMCLI_VALUE"
+	pmcli_timestamp
+	at="$PMCLI_VALUE"
+	pm_build_add_entry "$item" "$deferred" "$generation" "$at" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_close() {
+	# Run the close subcommand over every `<key>:<state>` token.
+	local token key state canonical="" seen=" " rc=0
+	pmcli_parse_options "items" "$@"
+	pmcli_require items
+	pcoh_split_words "${PMCLI_OPTS[items]}"
+	local -a tokens=("${PCOH_WORDS[@]}")
+	for token in "${tokens[@]}"; do
+		[[ $token =~ ^(-?(0|[1-9][0-9]*)):([A-Za-z_]+)$ ]] ||
+			pmcli_usage_error "--items token must be <key>:<state>; found: $token"
+		state="${BASH_REMATCH[3]}"
+		key=$((BASH_REMATCH[1]))
+		# A duplicate key would let one record silently replace another, so it
+		# is rejected before the library runs (declared divergence 1).
+		[[ $seen != *" $key "* ]] || pmcli_usage_error "--items key given more than once: $key"
+		seen="$seen$key "
+		canonical="$canonical $key:$state"
+	done
+	pm_decide_close "${canonical# }" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_close_entry() {
+	# Run the close-entry subcommand.
+	local generation at rc=0
+	pmcli_parse_options "generation at" "$@"
+	pmcli_require generation
+	pmcli_integer "${PMCLI_OPTS[generation]}" "--generation"
+	generation="$PMCLI_VALUE"
+	pmcli_timestamp
+	at="$PMCLI_VALUE"
+	pm_build_close_entry "$generation" "$at" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_requeue_entry() {
+	# Run the requeue-entry subcommand.
+	local item generation at rc=0
+	pmcli_parse_options "item generation at" "$@"
+	pmcli_require item generation
+	pmcli_integer "${PMCLI_OPTS[item]}" "--item"
+	item="$PMCLI_VALUE"
+	pmcli_integer "${PMCLI_OPTS[generation]}" "--generation"
+	generation="$PMCLI_VALUE"
+	pmcli_timestamp
+	at="$PMCLI_VALUE"
+	pm_build_requeue_entry "$item" "$generation" "$at" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_main() {
+	# Dispatch on the subcommand.
+	(($# > 0)) ||
+		pmcli_usage_error "missing subcommand; expected one of admit, recolor, add-entry, close, close-entry, requeue-entry"
+	local subcommand="$1"
+	shift
+	case "$subcommand" in
+	admit) mpr_admit "$@" ;;
+	recolor) mpr_recolor "$@" ;;
+	add-entry) mpr_add_entry "$@" ;;
+	close) mpr_close "$@" ;;
+	close-entry) mpr_close_entry "$@" ;;
+	requeue-entry) mpr_requeue_entry "$@" ;;
+	*) pmcli_usage_error "unknown subcommand: $subcommand" ;;
+	esac
+}
+
+# Guard so the file can be sourced without executing main. main's return code
+# is captured and re-exited explicitly as the final statement.
+if [[ ${BASH_SOURCE[0]} == "${0}" ]]; then
+	mpr_rc=0
+	mpr_main "$@" || mpr_rc=$?
+	exit "$mpr_rc"
+fi

package/resources/claude-customizations/.claude/lib/bash/parallel-cohorts.sh

@@ -52,14 +52,19 @@ PCOH_RESULT=""
 PCOH_WORDS=()
 
 pcoh_split_words() {
-	# Populate PCOH_WORDS by splitting a space-separated string.
+	# Populate PCOH_WORDS by splitting a whitespace-separated string.
 	#
 	# Args: $1 = the string to split. An empty or whitespace-only string yields
 	# an empty array, which is the empty-graph and empty-cohort case. `read -ra`
 	# is used rather than an unquoted expansion so a token is never subjected to
-	# pathname expansion.
+	# pathname expansion. Newline, CR, VT, and FF are converted to spaces first:
+	# `read` consumes one newline-terminated record and splits it on IFS only, so
+	# without the conversion every token after the first newline is dropped and
+	# CR, VT, and FF are not separators. With it, the separator set is space, tab,
+	# LF, CR, VT, and FF, which matches Python str.split() for ASCII.
+	local text="${1-}"
 	PCOH_WORDS=()
-	read -ra PCOH_WORDS <<<"${1-}"
+	read -ra PCOH_WORDS <<<"${text//[$'\n\r\v\f']/ }"
 }
 
 pcoh_fail() {
@@ -123,9 +128,14 @@ pcoh_build_adjacency() {
 	PCOH_ADJACENT=()
 	pcoh_split_words "$keys"
 	local -a key_list=("${PCOH_WORDS[@]}")
+	# Rebuild the membership haystack from the split tokens. The endpoint checks
+	# below match a space-delimited word, so they would miss a key that the caller
+	# separated with a newline, tab, CR, VT, or FF instead of a single space.
+	keys=""
 	# Seed every declared key so an isolated vertex survives into the coloring
 	# step; inferring vertices from the edge list alone would drop it.
 	for key in "${key_list[@]}"; do
+		keys="$keys $key"
 		PCOH_DEGREE["$key"]=0
 		PCOH_NEIGHBORS["$key"]=""
 	done

package/resources/claude-customizations/.claude/lib/bash/parallel-mutation-cli.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# parallel-mutation-cli.sh: sourceable command-line helpers shared by the two
+# parallel mutation entry points, remove-parallel-item.sh (issue #791) and
+# mutate-parallel-run.sh (issue #890). It holds option parsing, required-option
+# checks, integer, key-list, and edge-list validation, the `--at` timestamp, and
+# the result printer, so both entry points apply one grammar and one exit-code
+# contract.
+#
+# Grammar. Every option takes exactly one value. An unknown name, an
+# abbreviation, a `--name=value` form, a repeated option, or a missing value is
+# a usage error; a value beginning with `--` counts as missing. Integer tokens
+# match `-?(0|[1-9][0-9]*)`. `--at` matches `[0-9A-Za-z:.+-]+` and defaults to
+# the current UTC minute as yyyy-MM-ddTHH-mm.
+#
+# Exit-code contract carried by these helpers:
+#   exit 2  usage error; one stderr line beginning
+#           "PARALLEL_MUTATION_ERROR: usage error:" (pmcli_usage_error)
+#   exit 1  rule rejection; PM_ERROR printed as one stderr line (pmcli_emit)
+#   exit 0  success; PM_RESULT printed as one stdout line (pmcli_emit)
+#
+# Dependencies. pmcli_emit reads PM_RESULT and PM_ERROR, which
+# parallel-mutation.sh owns; an entry point sources that library before calling
+# it. The only external command is `date`, run solely when `--at` is omitted.
+#
+# shellcheck disable=SC2034
+# SC2034 is disabled file-wide because PMCLI_OPTS and PMCLI_VALUE are written
+# here and read by the two entry points, which shellcheck analyses separately.
+
+# Resolve this file's own directory so its dependencies source regardless of
+# the caller's working directory.
+PMCLI_LIB_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-cohorts.sh
+# shellcheck disable=SC1091
+source "$PMCLI_LIB_DIR/parallel-cohorts.sh"
+
+# Parsed option values, keyed by option name without the leading dashes.
+declare -gA PMCLI_OPTS=()
+
+# The canonical value stored by the most recent validator.
+PMCLI_VALUE=""
+
+pmcli_usage_error() {
+	# Print one usage-error line on stderr and exit 2.
+	#
+	# Args: $1 = the specific reason.
+	printf 'PARALLEL_MUTATION_ERROR: usage error: %s\n' "$1" >&2
+	exit 2
+}
+
+pmcli_parse_options() {
+	# Parse `--name value` pairs into PMCLI_OPTS against an allowed-name list.
+	#
+	# Args: $1 = space-separated allowed option names, then the arguments.
+	local allowed="$1" name
+	shift
+	PMCLI_OPTS=()
+	while (($# > 0)); do
+		name="${1#--}"
+		if [[ $1 != --* ]] || ! pc_contains_word "$allowed" "$name"; then
+			pmcli_usage_error "unknown option: $1"
+		fi
+		if [[ -n ${PMCLI_OPTS["$name"]+set} ]]; then
+			pmcli_usage_error "option given more than once: $1"
+		fi
+		if (($# < 2)) || [[ $2 == --* ]]; then
+			pmcli_usage_error "option $1 requires a value"
+		fi
+		PMCLI_OPTS["$name"]="$2"
+		shift 2
+	done
+}
+
+pmcli_require() {
+	# Exit with a usage error unless every named option was supplied.
+	#
+	# Args: the option names that are required.
+	local name
+	for name in "$@"; do
+		[[ -n ${PMCLI_OPTS["$name"]+set} ]] || pmcli_usage_error "missing required option: --$name"
+	done
+}
+
+pmcli_integer() {
+	# Validate one integer token and store it in canonical form in PMCLI_VALUE.
+	#
+	# Args: $1 = the token, $2 = a label naming where it came from. The
+	# validators store their result in a global instead of echoing it, because
+	# a usage error raised inside a command substitution would exit only the
+	# subshell.
+	if [[ ! $1 =~ ^-?(0|[1-9][0-9]*)$ ]]; then
+		pmcli_usage_error "$2 must be a decimal integer matching -?(0|[1-9][0-9]*); found: $1"
+	fi
+	PMCLI_VALUE=$(($1))
+}
+
+pmcli_integer_list() {
+	# Validate a whitespace-separated key list; store it space separated.
+	#
+	# Args: $1 = the list, $2 = a label naming the option.
+	local token canonical=""
+	pcoh_split_words "$1"
+	local -a tokens=("${PCOH_WORDS[@]}")
+	for token in "${tokens[@]}"; do
+		pmcli_integer "$token" "$2 key"
+		canonical="$canonical $PMCLI_VALUE"
+	done
+	PMCLI_VALUE="${canonical# }"
+}
+
+pmcli_edge_list() {
+	# Validate a whitespace-separated `a:b` edge list; store it canonical.
+	#
+	# Args: $1 = the edge list.
+	local token first canonical=""
+	pcoh_split_words "$1"
+	local -a tokens=("${PCOH_WORDS[@]}")
+	for token in "${tokens[@]}"; do
+		if [[ $token != *:* || $token == *:*:* ]]; then
+			pmcli_usage_error "edge must be <a>:<b>; found: $token"
+		fi
+		pmcli_integer "${token%%:*}" "edge endpoint"
+		first="$PMCLI_VALUE"
+		pmcli_integer "${token#*:}" "edge endpoint"
+		canonical="$canonical $first:$PMCLI_VALUE"
+	done
+	PMCLI_VALUE="${canonical# }"
+}
+
+pmcli_timestamp() {
+	# Store the validated `--at` value, or the current UTC minute when omitted.
+	if [[ -n ${PMCLI_OPTS[at]+set} ]]; then
+		PMCLI_VALUE="${PMCLI_OPTS[at]}"
+		[[ $PMCLI_VALUE =~ ^[0-9A-Za-z:.+-]+$ ]] ||
+			pmcli_usage_error "--at must match [0-9A-Za-z:.+-]+; found: $PMCLI_VALUE"
+	else
+		# The only clock read of either entry point, taken only when --at is
+		# omitted.
+		PMCLI_VALUE=$(date -u +%Y-%m-%dT%H-%M)
+	fi
+}
+
+pmcli_emit() {
+	# Print the library outcome and return the matching exit code.
+	#
+	# Args: $1 = the library function's return code.
+	if (($1 != 0)); then
+		printf '%s\n' "$PM_ERROR" >&2
+		return 1
+	fi
+	printf '%s\n' "$PM_RESULT"
+	return 0
+}