feat: add governed performance review packet

.github/workflows/performance-review-quality.yml

@@ -0,0 +1,65 @@
+name: Performance Review Quality
+
+on:
+  pull_request:
+    branches:
+      - develop
+    paths:
+      - "packages/performance-review/**"
+      - ".github/requirements/foundation-test.txt"
+      - ".github/workflows/performance-review-quality.yml"
+      - ".gitignore"
+      - ".python-version"
+      - "conftest.py"
+      - "packages/conftest.py"
+      - "pyproject.toml"
+      - "pytest.ini"
+      - "setup.cfg"
+      - "tox.ini"
+      - "docs/adr/0018-governed-performance-review.md"
+      - "docs/doctoring/performance-review-references.md"
+      - "docs/traceability/performance-review.md"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: performance-review-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit:
+    name: Performance review contract and 100% coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout exact candidate
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - name: Prove exact candidate checkout
+        env:
+          ORGMETRA_EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: test "$(git rev-parse HEAD)" = "$ORGMETRA_EXPECTED_HEAD_SHA"
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          check-latest: false
+      - name: Install reviewed test toolchain
+        run: |
+          python -m pip install --require-hashes --no-deps --only-binary=:all: -r .github/requirements/foundation-test.txt
+          python -m pip check
+      - name: Compile performance review package
+        run: python -m compileall -q packages/performance-review/src packages/performance-review/tests
+      - name: Test performance review with exact statement and branch coverage
+        env:
+          PYTHONPATH: packages/performance-review/src
+          COVERAGE_FILE: /tmp/orgmetra-performance-review.coverage
+        run: python -m pytest -c packages/performance-review/pyproject.toml packages/performance-review/tests
+      - name: Require clean checkout
+        run: |
+          git diff --exit-code
+          test -z "$(git status --porcelain)"

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to Orgmetra will be documented in this file.
 - Accepted ADRs 0001–0003 now include buyer-facing Context, Decision, and Consequences grounded in verified ISO 30400:2022, ISO 30414:2025, Uniform Guidelines (29 C.F.R. Part 1607), SIOP (2018), OpenAPI Specification v3.2.0, OpenID Connect Core 1.0 errata set 2, CloudEvents v1.0.2, Jensen and Snodgrass (1999), Snodgrass (1999), and Allen (1983) records already listed in `docs/doctoring/REFERENCES.md`. ADRs 0004 and 0005 gained APA 7th References pointers to that same bibliography without changing their Decision bodies.
 - Active-PR governed Job Analysis persistence/API on the canonical `JobAnalysisSnapshot` model: migration `0013_job_analysis_snapshot.sql` stores immutable tenant-scoped snapshot, Task, KSAO, Task–KSAO, FJA and write-command evidence; `POST /v1/tenants/{tenant_record_id}/job-analysis-snapshots` and matching GET enforce purpose-bound Keyverse scope, authenticated-principal actor authority, bounded/strict JSON handling, transactional Idempotency-Key serialization, parent-scope fail-closed integrity, forced RLS, and atomic audit/outbox evidence. ADR 0014 records the persistence decision while ADR 0007 remains the domain/evidence authority; validated evidence still requires accountable human review and non-LLM provenance, and the service does not make a high-impact employment decision.
 - Active-PR `orgmetra_selection_review` packet for PII-minimized, evidence-bound human selection review: canonical operational tenant identity, UUID-backed opaque candidate/Job/sealed-evidence/reviewer references, explicit purpose/reason/evidence version, deterministic canonical JSON and SHA-256 correlation, mandatory human decision state, redacted packet repr, and provenance-paired model evidence that remains `untrusted_draft`, with exact 100% owned statement and branch coverage required by its quality gate.
+- Active-PR `orgmetra-performance-review` packet for value-minimized, pre-rating human-review evidence: system-recorded issuance time, conservative person-reference handling until authoritative provenance and scope resolution, governed performance-cycle/criterion/goal evidence, optional development-plan provenance, issuance integrity sealing, and exact 100% owned statement and branch coverage required by its quality gate. This capability is not protected-branch truth until its current PR passes fresh gates and merges.
 - Active performance-criterion scope hardening: `criterion_observation_scope_guard` rejects criterion outcomes for a Job the worker did not effectively hold at the observation date, observations before the relevant assignment, and observations outside the referenced performance cycle while preserving valid multiple-assignment cases and existing bitemporal correction semantics. The guard evaluates current-recorded facts, derives the date coordinate from `observed_at` in UTC so session `TimeZone` cannot alter the result, uses a trusted function search path, and adds no PII or automated employment decision authority. The Foundation PostgreSQL contract also rejects a closed `recorded_to` on each time-coordinate lookup and proves UTC midnight plus non-UTC session `TimeZone` boundaries.
 - Bitemporal tenant-scoped organization hierarchy validation that rejects visible indirect parent cycles and reuses single-valued recorded-time reconstruction before graph traversal.
 - Stacked governed job-analysis evidence contract via `JobAnalysisSnapshot`, `TaskEvidence`, `KSAORequirement`, `TaskKSAOLink`, `FunctionalJobAnalysisProfile`, and `EvidenceSource`: tenant/Job-scoped observable tasks, explicit Task-to-KSAO linkage, importance/difficulty/proficiency ratings, source/version/retrieval/SHA-256 provenance, deterministic canonical snapshot bytes, current O*NET evidence support, and historical DOT Data/People/Things compatibility. Validated snapshots require accountable human review and complete non-LLM evidence; LLM-origin material remains `analysis_draft`, and the snapshot is evidence input rather than a hiring, promotion, termination, compensation, or other high-impact employment decision.

README.md

@@ -78,4 +78,6 @@ Job evidence
 
 ## Status
 
-Protected `develop` includes the employment-truth kernel, governed candidate-to-worker conversion, purpose-bound PII authorization, normalized worker-bound validity studies, criterion-observation scope, bitemporal workforce-composition evidence, the governed Naruon intent adapter, and requisition review packets. This active PR adds durable purpose-bound People mutation and confirmed-hire materialization paths for Employment, Position, and Assignment with atomic audit/outbox evidence and tenant-scoped idempotency; treat those write paths as active-PR truth until this exact head passes all fresh protected-base gates and merges.
+Protected `develop` remains the source of shipped truth and includes the employment-truth kernel, governed candidate-to-worker conversion, purpose-bound PII authorization, normalized worker-bound validity studies, criterion-observation scope, bitemporal workforce-composition evidence, the governed Naruon intent adapter, and requisition review packets.
+
+This **active PR only** adds the governed `orgmetra-performance-review` evidence packet described by ADR 0018. It prepares accountable pre-rating human-review evidence without calculating or persisting a rating or making an employment decision. Its issuance time is system-recorded inside the packet boundary rather than caller supplied, and independently supplied UUIDv4-shaped references are conservatively treated as potentially containing direct identifier content until authoritative reference provenance/opacity and Employment/Job scope are resolved. Do not describe this capability as shipped until this exact PR head satisfies fresh protected-base gates and merges.

docs/adr/0018-governed-performance-review.md

@@ -0,0 +1,57 @@
+# ADR 0018: Governed performance-review evidence packet
+
+- Status: Proposed — active PR only
+- Date: 2026-08-19
+
+## Context
+
+Orgmetra already owns authoritative Employment/Job truth and performance/criterion evidence boundaries, but a buyer-facing review workflow also needs a small pre-rating object that identifies which employment references, review period, performance cycle, criteria, goals, outcome evidence, and reviewer are being considered without copying rating values, narrative feedback, or model output into the envelope.
+
+A transport-neutral packet cannot prove merely from syntactically valid references that the Person, Employment, Job, cycle, goals, and observation snapshot all resolve to one authoritative temporal scope. Nor can UUIDv4 syntax prove that independently supplied bytes were randomly generated or contain no encoded identifier content. Treating either relationship resolution or reference opacity as established from syntax would create a misleading high-impact evidence boundary. Authoritative relationship/temporal resolution and trusted reference-provenance verification therefore remain required downstream steps before rating. UUIDv1 is still rejected for packet-owned namespaced references because its timestamp/node layout is unnecessary metadata for this boundary. The authoritative tenant identifier is different: it is issued by Orgmetra core, so this leaf package accepts the canonical non-sentinel operational UUID contract owned by that boundary rather than imposing a second version policy.
+
+System-recorded time is also audit evidence. Accepting an arbitrary caller-supplied historical `generated_at` would let a caller backdate issuance while still passing a future-only validation gate. The packet therefore owns the issuance timestamp and reads it from the host clock during construction rather than accepting it as a public constructor or builder input.
+
+U.S. OPM performance-management guidance treats performance management as a continuous cycle of planning, monitoring, developing, rating, and rewarding, and describes rating as evaluation against established elements and standards. ISO 30414:2025 Edition 2 provides current human-capital reporting requirements and recommendations across areas including productivity, skills/capabilities, and related workforce governance. Orgmetra uses those sources as design evidence, not as a claim that this packet by itself satisfies any jurisdiction-specific appraisal rule or ISO certification requirement.
+
+## Decision
+
+Introduce a transport-neutral `PerformanceReviewPacket` that remains pre-rating governance evidence.
+
+The packet MUST bind:
+
+- a canonical non-sentinel tenant identity under Orgmetra's authoritative operational UUID contract;
+- canonical non-sentinel UUIDv4-shaped namespaced Person, Employment, Job, performance-cycle and performance-review references, rejecting UUIDv1 and other non-v4 suffixes without claiming that UUIDv4 syntax proves opacity;
+- a governed criterion-set UUIDv4-shaped reference plus independent SHA-256 digest;
+- a governed performance-goal-plan UUIDv4-shaped reference plus independent SHA-256 digest;
+- an exact criterion-observation-snapshot UUIDv4-shaped reference plus independent SHA-256 digest;
+- an optional development-plan UUIDv4-shaped reference/digest pair;
+- explicit business review-period dates;
+- one accountable UUIDv4-shaped reviewer, fixed `performance_review` purpose, and a reviewed closed reason code;
+- a **system-owned** precision-preserving issuance timestamp read from the host clock inside the packet boundary, with no caller-supplied `generated_at` parameter; and
+- a bounded positive integer `evidence_version`, defaulting to `1`, that is included in canonical evidence and therefore changes the packet digest when the governed evidence version changes.
+
+The initial closed reason vocabulary contains only `scheduled_cycle_review`. Arbitrary lower-snake-case values are rejected even when syntactically well formed, because free-form reason text can encode a person name, identifier, or unreviewed decision context. Additional reasons require an explicit governed contract change and regression evidence before they can enter canonical review evidence.
+
+`evidence_version` accepts only real integers from `1` through `2147483647`; booleans, text, zero, negative values, and overflow values fail closed. The field versions the immutable review evidence envelope and does not itself prove source-version resolution, human approval, or rating completion.
+
+Because this package cannot prove independently supplied reference provenance, `contains_personal_data` and `contains_direct_person_identifiers` are both fixed to `True`. The latter is deliberately conservative: it means the envelope must be handled as potentially containing direct identifier content until an authoritative issuer/resolver verifies opacity. The packet MUST NOT carry a rating value, free-form feedback, or free-form model output. Those exclusions are machine-verifiable canonical evidence through fixed `contains_rating_value=False`, `contains_free_form_feedback=False`, and `contains_free_form_model_output=False`; mutation-by-copy that attempts to weaken any exclusion fails closed. Direct construction and mutation-by-copy MUST also fail closed unless `human_confirmation_required=True`, `decision_authority="human_review_only"`, `review_state="requires_human_review"`, and `scope_verification_state="requires_authoritative_resolution"` remain intact.
+
+`scope_verification_state` deliberately cannot be changed to `verified` inside this package. Before rating, the authoritative HRIS/performance boundary must verify reference provenance and opacity, then resolve the Person↔Employment↔Job relation, performance-cycle/review-period alignment, and governed evidence scope using current temporal truth and purpose-bound authorization. UUIDv4 shape alone is not provenance evidence; tenant UUID generation/version/privacy policy likewise remains owned by the authoritative HRIS boundary.
+
+`generated_at` is constructed from a trusted internal clock adapter. The resulting exact built-in timezone-aware `datetime` is normalized once to UTC and then sealed; future instants, missing/raising offsets, normalization overflow, datetime subclasses, or post-construction non-UTC reinjection fail closed. Tests may replace the internal clock adapter to make canonical bytes deterministic, but production callers cannot provide the issuance timestamp.
+
+The process-local HMAC issuance seal is registered exactly once for each live packet identity. A separate weak live-issued-identity registry persists for the lifetime of the packet even if current seal bytes are discarded, so seal loss is a fail-closed export condition rather than permission to issue again. Re-entering `__post_init__()` on the same live object after seal loss or after a valid-value rewrite MUST fail before replacement evidence can be installed. Canonical export continues to compare the current deterministic bytes against the original external seal when that seal exists. This registry is in-process mutation defense only and is not a portable signature, distributed uniqueness service, authorization record, or durable audit/outbox substitute.
+
+Canonical JSON and SHA-256 are immutable correlation evidence only. They do not prove the correctness of source evidence, authoritative cross-record scope, substantive validity or fairness of a criterion, lawful use, human completion, reference provenance, or the final rating.
+
+## Consequences
+
+Buyers can present a review-ready correlation envelope while keeping authoritative Employment/Job and performance evidence separable from the later human rating/feedback event. The envelope itself now carries explicit canonical proof that rating values, free-form feedback, and free-form model output are excluded from this pre-rating evidence boundary. A consumer cannot truthfully treat the packet itself as proof that all referenced records belong to the same employee/job/cycle or that UUIDv4-shaped values are opaque. Until authoritative provenance verification occurs, the packet receives the more restrictive identifier-risk classification rather than a false no-direct-identifier assertion.
+
+The system-recorded timestamp can no longer be backdated through public packet construction, and one live packet cannot renew its process-local issuance evidence after mutation or after losing its current seal bytes. Hosts still own purpose-bound authorization, durable immutable audit/outbox, retention/export controls, and the authoritative clock/runtime environment.
+
+This slice adds no database migration, no rating computation, no cross-service table access, and no automated employment decision. The pre-rating packet preserves actor, purpose, reviewed reason, evidence version, conservative identifier-risk classification, system-recorded issuance time, and explicit content-exclusion flags in its immutable correlation evidence; later authoritative rating persistence must independently preserve those values plus human confirmation, audit/outbox, temporal scope, authoritative scope/provenance resolution evidence, and any applicable policy requirements.
+
+## References
+
+See `docs/doctoring/performance-review-references.md`.

docs/adr/README.md

@@ -16,3 +16,4 @@
 | [0012](0012-governed-migration-handoff.md) | Governed migration handoff | Accepted on active implementation branch |
 | [0013](0013-governed-requisition-review-packet.md) | Governed requisition review packet | Accepted on active implementation branch |
 | [0014](0014-job-analysis-snapshot-persistence.md) | Persist governed job-analysis snapshots | Accepted on active implementation branch |
+| [0018](0018-governed-performance-review.md) | Governed performance-review evidence packet | Proposed — active PR only |

docs/doctoring/performance-review-references.md

@@ -0,0 +1,9 @@
+# Performance-review references
+
+Retrieved August 19, 2026. These references support the active-PR governance boundary in ADR 0018. Orgmetra does not reproduce proprietary ISO text or claim certification.
+
+International Organization for Standardization. (2025). *ISO 30414:2025 human resource management—Requirements and recommendations for human capital reporting and disclosure* (2nd ed.). https://www.iso.org/standard/30414
+
+U.S. Office of Personnel Management. (n.d.). *Performance management cycle*. Retrieved August 19, 2026, from https://www.opm.gov/policy-data-oversight/performance-management/performance-management-cycle/
+
+U.S. Office of Personnel Management. (n.d.). *Performance management roadmap: Best practices guide for supervisors*. Retrieved August 19, 2026, from https://www.opm.gov/policy-data-oversight/performance-management/performance-management-toolkit/best-practices/performance-management-roadmap-for-supervisors/