feat: add governed selection outcome monitoring plan

docs/adr/0016-governed-selection-outcome-monitoring-plan.md

@@ -0,0 +1,47 @@
+# ADR 0016: Governed selection-outcome monitoring plan
+
+- **Status:** Proposed — active PR only
+- **Decision scope:** Selection validity / workforce intelligence governance
+
+## Context
+
+Orgmetra already owns Job-scoped selection and post-hire evidence boundaries, but protected `develop` does not define a buyer-facing contract for planning recurring selection-outcome monitoring without copying candidate-level protected-attribute values or turning a screening heuristic into an automated legal or employment decision. Different opaque requester/reviewer references also do not prove that the authoritative actor boundary resolves them to different accountable people, and valid UUID-backed references alone do not prove that all referenced evidence belongs to the packet tenant. Packet-owned UUIDv1 trust references additionally embed timestamp/node-derived correlation metadata. The authoritative tenant identifier is different: it is issued by Orgmetra core, so this leaf package must accept the canonical non-sentinel operational UUID contract owned by that boundary rather than silently imposing a second version policy.
+
+The EEOC's common interpretation of the Uniform Guidelines directs users to examine the total selection process first for each job, describes the four-fifths rule as a rule of thumb rather than a legal definition, and notes that small samples, statistical significance, practical significance, and other evidence can matter. ISO 30405:2023 also treats reviewing and learning as part of recruitment practice. SIOP's fifth-edition Principles provide the professional validation framework for personnel selection procedures.
+
+## Decision
+
+Orgmetra will expose a transport-neutral `SelectionOutcomeMonitoringPlan` that binds:
+
+- one canonical non-sentinel operational tenant under the authoritative Orgmetra core contract and one authoritative Job;
+- one total selection-process reference;
+- exact aggregate population and selection-outcome snapshot references and SHA-256 digests;
+- exact protected-attribute handling, small-sample interpretation, and statistical-analysis plan references and digests;
+- an accountable requester reference and an accountable reviewer reference;
+- fixed purpose and reviewed reason metadata plus a bounded positive `evidence_version` that is part of canonical evidence;
+- an explicit monitoring business-date window and evidence-generation instant.
+
+`tenant_record_id` must be canonical and non-sentinel under Orgmetra's authoritative operational UUID contract. The package does not reinterpret its UUID version because tenant identity generation and migration policy belong to the authoritative HRIS boundary. Packet-owned namespaced trust-bearing references separately require canonical non-sentinel UUIDv4 plus their expected prefix. UUIDv1 and other non-v4 suffixes fail closed for those references. Human-readable, value-bearing, sentinel, and noncanonical reference suffixes are also rejected so labels, policy values, protected-attribute concepts, or actor names cannot be carried through fields represented as opaque identifiers. `evidence_version` must be a true integer from 1 through 2147483647; changing it changes canonical JSON and the packet SHA-256, so revisions to actor/purpose/reason-bound evidence cannot silently collide.
+
+UUID syntax is not tenant authority. Before review, the host must re-resolve **every packet reference** within the exact `tenant_record_id` through the relevant authoritative boundary and reject review use if any reference belongs to another tenant or cannot be authoritatively resolved. The packet also rejects identical requester/reviewer references as an early syntactic guard; after tenant-scoped resolution, the host must prove that the two references resolve to distinct actor identities. Reference inequality alone is not separation-of-duties evidence.
+
+The contract is aggregate-only and carries no candidate identity, protected-attribute value, individual assessment score, individual employment decision, or free-form model output. It fixes `analysis_scope` to `total_selection_process_by_job`, `decision_authority` to `human_review_only`, and state to `requires_human_review`. It does not calculate selection rates, mechanically apply the four-fifths heuristic, test statistical significance, infer discrimination, or authorize a process change.
+
+Each live plan identity receives one process-local construction seal over its exact canonical bytes. Seal registration is one-shot: a repeated `__post_init__()` call cannot overwrite the original seal, including after low-level mutation to another syntactically valid value. Canonical export therefore continues to compare the live payload with the original construction evidence instead of permitting reinitialization to renew trust. This runtime mechanism is defense-in-depth only and does not replace durable immutable audit/outbox evidence, persistence uniqueness, or cross-process authorization.
+
+Any later analytics or persistence boundary must independently enforce purpose-bound authorization, authoritative tenant-scoped reference and actor resolution, minimum-necessary protected-attribute access, small-sample controls, provenance, immutable audit evidence, and accountable human interpretation. Results are evidence for review, not an automated high-impact employment decision or certification/legal conclusion.
+
+## Consequences
+
+- Buyers obtain a deterministic, explicitly versioned governance envelope for recurring selection monitoring without creating a second psychometrics/statistics engine inside Orgmetra.
+- The total-process-by-Job scope is explicit before any future component drill-down.
+- Privacy risk is reduced because individual protected-attribute values and candidate records remain outside the plan envelope and packet-owned trust references reject UUIDv1 timestamp/node metadata and value-bearing suffixes without making the leaf package incompatible with authoritative Orgmetra tenant UUIDs.
+- Cross-tenant evidence mixing is fail-closed at the host review boundary because every opaque reference must be re-resolved in the exact packet tenant.
+- Requester/reviewer separation is proven from authoritative resolved actor identities rather than inferred from different opaque strings.
+- A valid-value low-level rewrite cannot be legitimized by re-running dataclass initialization because process-local seal registration is single-use for the live identity.
+- The four-fifths rule cannot be represented as an automatic pass/fail legal rule by this contract; interpretation remains with authorized analysts and accountable humans.
+- Psychometric/statistical production compute remains owned by the appropriate Psychometrics Commons / fast-mlsirm / TEPP contract when those kernels are needed.
+
+## References
+
+See `docs/doctoring/selection-outcome-monitoring-references.md`.

docs/doctoring/selection-outcome-monitoring-references.md

@@ -0,0 +1,17 @@
+# Selection-outcome monitoring references
+
+These references support ADR 0016 and the bounded selection-monitoring contract. They do not convert Orgmetra into a legal-advice, certification, or automated adverse-impact decision service.
+
+## APA 7 references
+
+Equal Employment Opportunity Commission, Office of Personnel Management, Department of Justice, Department of Labor, & Department of the Treasury. (1979, March 2). *Questions and answers to clarify and provide a common interpretation of the Uniform Guidelines on Employee Selection Procedures*. U.S. Equal Employment Opportunity Commission. https://www.eeoc.gov/laws/guidance/questions-and-answers-clarify-and-provide-common-interpretation-uniform-guidelines
+
+International Organization for Standardization. (2023). *ISO 30405:2023 Human resource management—Guidelines on recruitment* (2nd ed.). https://www.iso.org/standard/79488.html
+
+Society for Industrial and Organizational Psychology. (2018). Principles for the validation and use of personnel selection procedures (5th ed.). *Industrial and Organizational Psychology, 11*(S1), 1–97. https://doi.org/10.1017/iop.2018.195
+
+## Applied evidence boundary
+
+The EEOC source says adverse impact is examined first for the overall selection process for each job and describes the four-fifths/eighty-percent rule as a practical rule of thumb rather than a legal definition. It also explains that small samples and statistical/practical significance can change interpretation. Consequently, the Orgmetra contract binds a Job-scoped total-process monitoring plan, a separate small-sample policy, and a separate statistical plan but does not itself calculate or adjudicate adverse impact.
+
+ISO 30405:2023 is the current published second edition and includes reviewing and learning among recruitment practices. SIOP's fifth-edition Principles are used as the professional selection-validation frame; Orgmetra does not duplicate its psychometric methods in this package.

docs/traceability/selection-outcome-monitoring.md

@@ -0,0 +1,32 @@
+# Selection-outcome monitoring traceability
+
+## Status
+
+**Active PR / proposed capability.** This file does not describe protected-`develop` behavior until the owning PR is integrated. The protected-parent reconciliation snapshot is `develop@eb9757f8649aaad026a9865508d9aad50c1a7a4f`; merge readiness still requires a fresh protected-head read and exact-head acceptance.
+
+## Buyer need → contract evidence
+
+| Buyer / governance need | Owned contract evidence | Explicit non-claim |
+|---|---|---|
+| Monitor the correct hiring/promotion process | Canonical non-sentinel `tenant_record_id` under the Orgmetra core operational-UUID contract, exact UUIDv4-backed `job_profile_reference` and `selection_process_reference`; fixed `analysis_scope=total_selection_process_by_job`; immutable next action requires every packet reference to be re-resolved within exact `tenant_record_id` | UUID syntax alone is not tenant authority or component-level causality evidence |
+| Reproduce the monitored population and outcomes | Exact UUIDv4-backed aggregate population/outcome snapshot references plus independent SHA-256 digests | No candidate-level record or protected-attribute value in the packet |
+| Preserve privacy and interpretation rules | Exact UUIDv4-backed protected-attribute handling and small-sample policy references/digests | No blanket authorization to expose protected-attribute data |
+| Prevent semantic/value/correlation smuggling through packet-owned references without duplicating tenant identity policy | `tenant_record_id` is canonical/non-sentinel under the authoritative core contract; every packet-owned governed reference requires canonical non-sentinel UUIDv4 plus its expected prefix; digest and governance text evidence require exact built-in strings before validation | UUID syntax does not prove source truth, tenant membership, or authorization |
+| Prevent cross-tenant evidence mixing | `test_actor_separation.py` requires the governed next action to re-resolve every packet reference within `tenant_record_id` before actor separation, Job scope verification, or accountable review | The packet does not itself query authoritative stores |
+| Bind the analysis method before interpretation | Exact UUIDv4-backed statistical-plan reference/digest | No statistics are calculated by this package |
+| Version actor/purpose/reason evidence explicitly | `evidence_version` is a true positive integer through signed-int32 max and participates in canonical JSON/SHA-256 | `test_evidence_version.py` proves presence, digest separation, bounds, and `dataclasses.replace(...)` revalidation |
+| Prove accountable requester/reviewer separation | Different opaque actor references as a syntactic guard plus tenant-scoped authoritative resolution requiring distinct resolved actor identities | Reference inequality alone is not identity or separation-of-duties evidence |
+| Prevent automated high-impact action | Exact boolean human confirmation, `human_review_only`, `requires_human_review`, governed next action | No automated employment-process change or legal conclusion |
+| Preserve replayable audit correlation without caller-owned timezone behavior | `generated_at` is resolved once to a built-in UTC instant at issuance; future instants, missing/raising offsets and normalization overflow fail closed; canonical JSON and SHA-256 reuse only the detached UTC value | The packet timestamp proves evidence chronology/correlation, not source truth or scientific/legal validity |
+| Prevent valid-value evidence rewrites after issuance | A process-local HMAC seal is stored outside packet-writable slots over the exact construction-time canonical JSON; seal registration is single-use per live identity, so repeated `__post_init__()` cannot renew trust; export verifies the current snapshot against the original seal and fails closed if evidence changed or issuance state is unavailable | The process-local seal is defense-in-depth only and is not durable cross-process authorization, persistence uniqueness, or immutable audit/outbox evidence |
+| Keep package-quality evidence current under the protected workflow-ownership model | Canonical `Foundation CI` invokes `tests/test_foundation_ci_dependency_hygiene.sh`, which discovers and executes `tests/test_foundation_ci_*_artifact.sh` contracts; Selection Monitoring is owned by `tests/test_foundation_ci_selection_monitoring_artifact.sh`. The isolated hash-locked package contract runs the package pytest configuration, whose 100% statement and branch coverage thresholds remain authoritative. `test_quality_workflow_trigger.py` fails if the retired leaf workflow reappears or this canonical delegation disappears. | There is no package-local Selection Monitoring workflow and no transfer of historical GREEN across a successor head |
+
+## Executable evidence
+
+`packages/selection-monitoring/tests/test_plan.py` exercises direct-constructor and builder validation, operational tenant identity, UUID-backed reference namespaces, SHA-256 digests, requester/reviewer syntactic separation, monitoring-window boundaries, governance codes, timezone handling, fractional-second evidence identity, immutable review/authority state, aggregate-only enforcement, canonical JSON, and deterministic packet hashing. `packages/selection-monitoring/tests/test_temporal_evidence_integrity.py` proves caller-defined datetime subclasses are rejected, mutable timezone providers are detached at issuance, future generation times and missing/raising offsets fail closed, UTC-normalization overflow is normalized to validation failure, and post-construction non-UTC reinjection is rejected before evidence export. `packages/selection-monitoring/tests/test_issuance_integrity.py` proves a low-level valid-value rewrite after issuance cannot emit a second canonical truth, repeated `__post_init__()` cannot overwrite the original construction seal, and missing process-local issuance evidence fails closed. `packages/selection-monitoring/tests/test_fixed_governance_runtime_integrity.py` proves fixed governance fields reject hostile runtime string subclasses before equality-based policy checks. `packages/selection-monitoring/tests/test_string_runtime_evidence_integrity.py` proves tenant, reference, purpose, reason, and SHA-256 digest evidence reject caller-defined string subclasses before canonical evidence binding. `packages/selection-monitoring/tests/test_actor_separation.py` requires the immutable next action to re-resolve every packet reference in the exact tenant before Job-scope/accountable-review use, and separately requires requester/reviewer resolution through the authoritative tenant-scoped actor boundary with distinct resolved identities. `packages/selection-monitoring/tests/test_reference_privacy.py` is the RED→GREEN privacy/interoperability contract for accepting the authoritative core UUIDv7 tenant form while rejecting human-readable/value-bearing, sentinel, noncanonical, and non-v4 packet-owned opaque-reference suffixes through both public construction and replacement paths. `packages/selection-monitoring/tests/test_evidence_version.py` requires explicit bounded evidence revision identity in canonical evidence and proves that version changes alter the packet hash. `packages/selection-monitoring/tests/test_quality_workflow_trigger.py` proves the retired package-local workflow stays absent and canonical Foundation ownership continues to discover and execute the package contract without another edit to the shared Foundation workflow.
+
+The package contract is reached only through canonical `.github/workflows/foundation-ci.yml`. `tests/test_foundation_ci_dependency_hygiene.sh` discovers delegated artifact contracts by the `tests/test_foundation_ci_*_artifact.sh` naming contract, so later packages can add an isolated artifact proof without competing edits to the shared dispatcher. The Selection Monitoring contract creates an isolated virtual environment, installs the repository's hash-locked reviewed test toolchain, compiles the package and tests, runs the selection-monitoring package under its own pytest configuration, and removes the temporary environment on exit. This preserves the existing 100% owned statement/branch threshold without restoring `.github/workflows/selection-monitoring-quality.yml`. Organization-required central review/security workflows remain separate required controls.
+
+## Ownership boundary
+
+This slice writes only Orgmetra and introduces no database migration or cross-service SQL. Future statistical computation must use the appropriate published psychometric/statistical service contract rather than duplicating foreign kernels, and future access to protected-attribute data must remain purpose-bound and minimum-necessary. Tenant UUID generation/privacy policy and authoritative tenant-scoped reference/actor resolution remain at the host/core boundary; this packet fails closed by requiring that proof before human review use. The process-local issuance registry is deliberately not a distributed attestation store: durable uniqueness, authorization, retention, and immutable audit/outbox remain responsibilities of authoritative Orgmetra persistence/host boundaries.