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

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.

packages/document-record-evidence/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## Unreleased
+
+- Add value-minimized HR document-record metadata evidence with Orgmetra-generated record identity and system-recorded time.
+- Bind artifact integrity, source provenance and retention-policy evidence without copying document content or HR field values.
+- Reject valid-value post-issuance rewrites by comparing each export against a process-local creation-time canonical evidence digest; durable immutability remains owned by authoritative audit/outbox persistence.
+- Add an exact-head, installed-wheel quality lane with 100% owned statement/branch coverage requirement.

packages/document-record-evidence/README.md

@@ -0,0 +1,15 @@
+# Orgmetra document-record evidence
+
+This package creates **value-minimized metadata evidence** for an HR document artifact. It is intended for the `document_records` bounded context described by Orgmetra's accepted architecture.
+
+A `DocumentRecordEvidence` binds one tenant, Person, Employment, uploader correlation, reviewed document category, immutable artifact reference and SHA-256 digest, source-provenance digest, retention-policy reference/digest, the business receipt time, and a system-generated recorded time. The evidence intentionally contains **no document bytes, document title, free-form notes, credentials, compensation, rating, or other HR field values**.
+
+The packet is not a storage credential, legal retention determination, or employment-decision authorization. Before content access, export, retention/disposition, or a high-impact HR action, the authoritative Orgmetra host must re-resolve tenant/actor/purpose/resource scope, retention/legal-hold state, artifact integrity and human authority, then persist immutable audit/outbox evidence through the owning service.
+
+`document_record_reference` and `recorded_at` are generated inside the Orgmetra issuance boundary so callers cannot claim a chosen system-recorded identity or timestamp. Caller-owned `received_at` remains separate business-event time and must be exact built-in UTC and no later than issuance.
+
+The Python value also keeps its creation-time canonical evidence digest in a process-local weak issuance registry outside packet-writable slots. Every export validates the live fields, snapshots them once, and compares that exact snapshot with the issuance digest before returning document or JSON evidence. This is **defense in depth against accidental or same-process post-construction rewriting**, not durable cryptographic attestation: authoritative persistence must store the already-emitted canonical evidence and digest through Orgmetra's immutable audit/outbox boundary.
+
+The closed initial document-category vocabulary is `employment_contract`, `policy_acknowledgement`, and `qualification_document`. New categories require a reviewed contract change rather than free-form metadata.
+
+This package does not fetch or mutate Clearfolio, NewsDOM, or any other dedicated-writer CWL service and introduces no cross-service application-table SQL.

packages/document-record-evidence/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orgmetra-document-record-evidence"
+version = "0.1.0"
+description = "Value-minimized HR document-record evidence for Orgmetra."
+requires-python = ">=3.14.7,<3.15"
+
+[project.optional-dependencies]
+test = ["pytest>=8.3", "pytest-cov>=5.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+  "--cov=orgmetra_document_record_evidence",
+  "--cov-branch",
+  "--cov-report=term-missing",
+  "--cov-fail-under=100",
+]

packages/document-record-evidence/src/orgmetra_document_record_evidence/__init__.py

@@ -0,0 +1,8 @@
+"""Public Orgmetra HR document-record evidence contract."""
+
+from orgmetra_document_record_evidence.evidence import (
+    DocumentRecordEvidence,
+    build_document_record_evidence,
+)
+
+__all__ = ["DocumentRecordEvidence", "build_document_record_evidence"]