feat(document-records): add governed HR document evidence

.github/workflows/document-record-evidence-quality.yml

@@ -0,0 +1,74 @@
+name: Document Record Evidence Quality
+
+on:
+  pull_request:
+    branches:
+      - develop
+    paths:
+      - "packages/document-record-evidence/**"
+      - ".github/requirements/foundation-test.txt"
+      - ".github/workflows/document-record-evidence-quality.yml"
+      - "docs/adr/0098-governed-document-record-evidence.md"
+      - "docs/doctoring/document-record-evidence-references.md"
+      - "docs/traceability/document-record-evidence.md"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: document-record-evidence-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit:
+    name: Document record evidence 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 exact Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14.7"
+          check-latest: false
+      - name: Install reviewed test and build toolchain
+        run: |
+          python -m pip install --require-hashes --no-deps --only-binary=:all: -r .github/requirements/foundation-test.txt
+          printf '%s\n' 'setuptools==84.0.0 --hash=sha256:51a52592b3b99e102b609654876bd65f19f999935166d1352678931132b0c670' > /tmp/orgmetra-document-record-build.txt
+          python -m pip install --require-hashes --no-deps --only-binary=:all: -r /tmp/orgmetra-document-record-build.txt
+          python -m pip check
+      - name: Compile package and tests
+        run: python -m compileall -q packages/document-record-evidence/src packages/document-record-evidence/tests
+      - name: Build and install exact package artifact
+        run: |
+          rm -rf /tmp/orgmetra-document-record-build-src /tmp/orgmetra-document-record-dist /tmp/orgmetra-document-record-venv
+          cp -a packages/document-record-evidence /tmp/orgmetra-document-record-build-src
+          mkdir -p /tmp/orgmetra-document-record-dist
+          python -m pip wheel --no-deps --no-build-isolation --wheel-dir /tmp/orgmetra-document-record-dist /tmp/orgmetra-document-record-build-src
+          test "$(find /tmp/orgmetra-document-record-dist -maxdepth 1 -type f -name '*.whl' | wc -l)" -eq 1
+          python -m venv /tmp/orgmetra-document-record-venv
+          /tmp/orgmetra-document-record-venv/bin/python -m pip install --require-hashes --no-deps --only-binary=:all: -r "$GITHUB_WORKSPACE/.github/requirements/foundation-test.txt"
+          wheel_path="$(find /tmp/orgmetra-document-record-dist -maxdepth 1 -type f -name '*.whl' -print -quit)"
+          wheel_sha="$(sha256sum "$wheel_path" | awk '{print $1}')"
+          printf 'orgmetra-document-record-evidence[test] @ file://%s --hash=sha256:%s\n' "$wheel_path" "$wheel_sha" > /tmp/orgmetra-document-record-install.txt
+          /tmp/orgmetra-document-record-venv/bin/python -m pip install --require-hashes --no-deps -r /tmp/orgmetra-document-record-install.txt
+          /tmp/orgmetra-document-record-venv/bin/python -m pip check
+      - name: Test installed artifact with exact statement and branch coverage
+        env:
+          COVERAGE_FILE: /tmp/orgmetra-document-record.coverage
+        run: |
+          cd /tmp
+          /tmp/orgmetra-document-record-venv/bin/python -m pytest -c "$GITHUB_WORKSPACE/packages/document-record-evidence/pyproject.toml" "$GITHUB_WORKSPACE/packages/document-record-evidence/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 `DocumentRecordEvidence` for value-minimized HR document metadata: tenant/Person/Employment scope, reviewed category, opaque artifact and provenance/retention digests, separate business receipt and Orgmetra-generated system-recorded time, process-local tamper detection, and no document content or employment-decision authority.
 - 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.

docs/adr/0098-governed-document-record-evidence.md

@@ -0,0 +1,29 @@
+# ADR 0098: Governed HR document-record evidence
+
+**Status: Proposed**
+
+## Context
+
+Orgmetra's accepted architecture assigns document metadata, source evidence and immutable artifact references to `document_records`. Protected `develop` has no executable value object for that boundary, creating a commercial diligence gap: a buyer cannot yet point to code that binds an HR document artifact to HR scope, provenance, retention-policy evidence and system-recorded time without copying content into a second evidence store.
+
+## Decision
+
+Add a transport-neutral `DocumentRecordEvidence` value that binds tenant, Person, Employment, pseudonymous uploader correlation, one reviewed document category, an opaque artifact reference plus SHA-256 digest, source-provenance SHA-256, retention-policy reference/digest, caller-owned business receipt time, and Orgmetra-generated document-record identity/system-recorded time.
+
+Canonical evidence is classified `restricted_hr`, records only `artifact_reference_only`, and is explicitly `not_authorized_for_employment_decision`. The initial category vocabulary is closed. Document bytes, titles, free-form notes, credentials, compensation, ratings and unrelated HR values are excluded.
+
+`received_at` and `recorded_at` remain distinct: receipt time is business/event time supplied by the source boundary; recorded time is generated by Orgmetra at evidence issuance and cannot precede receipt time.
+
+A process-local weak issuance registry stores the creation-time canonical evidence digest outside packet-writable slots. Canonical export validates the live fields, snapshots the payload once, compares that exact snapshot against the creation digest, and returns only the verified snapshot. This rejects valid-value `object.__setattr__` rewriting after issuance without pretending that an in-process Python object is durable cryptographic evidence.
+
+## Consequences
+
+- Document metadata can be correlated to immutable artifacts and provenance without duplicating content.
+- The packet does not authorize storage access, export, retention/disposition or an employment decision.
+- Process-local tamper detection is defense in depth only; durable immutability, uniqueness, access control and audit ordering remain responsibilities of authoritative `document_records`/`audit_provenance` persistence.
+- Clearfolio and NewsDOM remain read-only external dependencies through published contracts; this ADR creates no cross-service application-table access.
+- W3C PROV-O and NIST Privacy Framework 1.0 are design inputs only; no conformance or certification claim is made.
+
+## Follow-up
+
+A later bounded slice may add authoritative 3NF document metadata persistence, object-store authorization, lifecycle reconciliation, malware/content validation and governed preview/OCR adapters. Those changes must preserve tenant isolation, purpose-bound access, retention/legal-hold controls and immutable audit/outbox evidence.

docs/doctoring/document-record-evidence-references.md

@@ -0,0 +1,17 @@
+# Document-record evidence references
+
+Reviewed 2026-08-23.
+
+## Primary standards inputs
+
+World Wide Web Consortium. (2013, April 30). *PROV-O: The PROV Ontology* (W3C Recommendation). https://www.w3.org/TR/prov-o/
+
+PROV-O is used as a provenance-model design input: Orgmetra preserves explicit artifact and source-provenance correlation so evidence can later be mapped into a broader provenance graph. This slice does **not** claim PROV-O serialization conformance.
+
+National Institute of Standards and Technology. (2020, January). *NIST Privacy Framework: A tool for improving privacy through enterprise risk management, Version 1.0*. https://www.nist.gov/privacy-framework/privacy-framework
+
+NIST Privacy Framework 1.0 is used as a privacy-risk design input for data minimization and governed processing. At the review date, NIST's site separately presents Privacy Framework 1.1 as an Initial Public Draft; this document therefore does not mislabel 1.1 as a final standard and does not claim NIST certification or conformity.
+
+## Orgmetra interpretation
+
+The evidence contract stores document metadata, opaque correlations and SHA-256 provenance while excluding document bytes, titles, free-form notes, credentials and unrelated HR values. Retention-policy evidence is bound but no universal statutory retention period is encoded. Authoritative access, export, retention/disposition and employment decisions remain separate human-accountable Orgmetra boundaries.

docs/traceability/document-record-evidence.md

@@ -0,0 +1,26 @@
+# Document-record evidence traceability
+
+## State
+
+- **Protected-main truth:** `develop@9e3e4847510e1e612b48474ba42b177b8ed824df` defines `document_records` as the owner of document metadata, source evidence and immutable artifact references, but has no executable document-record evidence package.
+- **Active PR truth:** PR #98 adds a transport-neutral, value-minimized document metadata evidence contract. It is not protected-main/shipped truth until merged.
+- **Out of scope:** document bytes/object-store implementation, Clearfolio/NewsDOM mutations, OCR, preview generation, legal retention decisions, content export, and employment-decision authority.
+
+## Requirement → executable evidence
+
+| Requirement | Evidence |
+|---|---|
+| Tenant, Person and Employment scope is explicit | `test_builds_value_minimized_document_evidence` plus malformed-reference regressions |
+| Document content and HR values are not copied into canonical governance evidence | `test_builds_value_minimized_document_evidence` |
+| Record identity and system-recorded time are Orgmetra-generated | `test_generates_packet_owned_reference_and_system_time` |
+| Artifact, provenance and retention-policy integrity are SHA-256-bound | malformed digest regressions plus canonical digest assertion |
+| Caller business receipt time remains distinct from system-recorded time | future/non-UTC receipt-time regressions |
+| A valid-value rewrite after issuance cannot emit a second canonical truth | `test_rejects_valid_value_rewrite_after_issuance`; process-local creation digest is stored outside packet-writable slots and the verified payload snapshot is reused for export |
+| Owned production statement and branch coverage are exact 100% | `Document Record Evidence Quality` workflow |
+| Installed package, not source-tree import, is tested | exact-head hash-bound wheel build/install in `Document Record Evidence Quality` |
+
+The process-local issuance digest is defense in depth only. It is not a durable signature, MAC key-management system, or substitute for database uniqueness/immutability. Durable evidence systems persist the already-emitted canonical bytes and digest through authoritative `document_records` and immutable `audit_provenance`/outbox persistence.
+
+## Next authoritative boundary
+
+Before any content read, export, disposition or high-impact HR action, the owning Orgmetra service must freshly re-resolve tenant, actor, purpose, resource, artifact digest/provenance, retention/legal-hold state and human authority, then write immutable audit/outbox evidence atomically with any consequential operation.