feat: add bitemporal people domain kernel

.github/workflows/quality.yml

@@ -0,0 +1,51 @@
+name: Domain Quality
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: orgmetra-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  domain-quality-matrix:
+    name: domain-quality (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    env:
+      PIP_DISABLE_PIP_VERSION_CHECK: "1"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install hash-locked quality dependency
+        run: >-
+          python -m pip install
+          --only-binary=:all:
+          --require-hashes
+          -r requirements/ci.txt
+      - name: Verify domain and repository contracts
+        run: ./scripts/run_domain_quality.sh
+
+  domain-quality:
+    name: domain-quality
+    needs: domain-quality-matrix
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require every supported Python lane
+        run: |
+          echo "domain-quality-matrix result=${{ needs.domain-quality-matrix.result }}"
+          test "${{ needs.domain-quality-matrix.result }}" = "success"

AGENTS.md

@@ -24,7 +24,7 @@ Build Orgmetra as a commercial-grade, evidence-centered HRIS and HCM platform th
 
 ## Documentation rules
 
-Keep README, PRD, TRD, ARCHITECTURE, DATA_MODEL, ERD, UML, API_CONTRACT, SECURITY, THREAT_MODEL, TEST_STRATEGY, OPERABILITY, TRACEABILITY, ADRs, doctoring references, AGENTS, CLAUDE, and CHANGELOG current with code. Distinguish shipped protected-main truth from active PRs, accepted architecture, planned work, research-only work, superseded work, and out-of-scope work.
+Keep README, PRD, TRD, ARCHITECTURE, DATA_MODEL, ERD, UML, API_CONTRACT, SECURITY, THREAT_MODEL, TEST_STRATEGY, OPERABILITY, TRACEABILITY, ADRs, doctoring references, AGENTS, CLAUDE, and CHANGELOG current with code. Distinguish shipped protected default branch truth from active PRs, accepted architecture, planned work, research-only work, superseded work, and out-of-scope work.
 
 ## Quality rules
 

ARCHITECTURE.md

@@ -58,3 +58,7 @@ The foundation can start as a monorepo with separately deployable services. Serv
 ## Security posture
 
 Access is tenant, actor, purpose, resource, and lifetime scoped. High-impact decisions require evidence, explicit decision records, and human accountability. LLM outputs are draft evidence only.
+
+## Active implementation slice: bitemporal domain kernel
+
+`packages/orgmetra-domain` implements framework-independent invariants for effective/system time, distinct HRIS records, multiple assignments, and candidate-worker continuity. It has no persistence or transport dependency and can be embedded by future services. This section describes active-PR work until merged into the protected default branch.

CHANGELOG.md

@@ -6,17 +6,31 @@ All notable changes to Orgmetra will be documented in this file.
 
 ### Added
 
+- Independently importable `orgmetra-domain` package for bitemporal HRIS invariants.
+- Deterministic business-time/knowledge-time historical fact resolution that fails closed on ambiguous overlapping versions.
+- Durable organization-unit and job-profile anchors with separate bitemporal version records so Organization, Job, Position, and Assignment remain distinct HRIS concepts.
+- Multiple-membership assignment allocation validation with half-open effective intervals.
+- Append-only, idempotent candidate-to-worker linkage.
+- Hash-locked Python 3.11-3.14 quality workflow with exact 100% production statement/branch coverage and public docstring checks.
 - Foundation product baseline for Orgmetra as evidence-centered HRIS/HCM.
 - CWL federated integration boundary map.
 - Bitemporal HRIS data contract.
 - Core ERD, UML, PRD, TRD, user stories, storyboard, wireframes, Storybook inventory, security, test, and operability baseline.
 
+### Changed
+
+- Organization and job mutable descriptions now live in version records rather than durable identity anchors, preserving normalized history and stable position references.
+- Effective and system-recorded intervals are non-empty half-open periods; equal start/end bounds are rejected.
+- Assignment portfolio validation now requires an explicit timezone-aware knowledge time and excludes superseded recorded versions before calculating FTE overlap.
+- Historical fact resolution now scopes visibility and ambiguity to one caller-selected durable identity instead of conflating simultaneously visible facts from different people or entities.
+
 ### Security
 
 - Purpose-bound PII access contract.
 - LLM output constrained to draft evidence.
 - No direct cross-service database access.
+- Candidate-to-worker relink failures now return a bounded adapter-safe message with no candidate or person identifiers.
 
 ### Notes
 
-- The protected default branch contains only the minimal bootstrap commit. This baseline is proposed through `feat/foundation-product-baseline` and becomes shipped truth only after review and merge.
+- The protected default branch contains only the minimal bootstrap commit. PR #8 is the canonical foundation baseline; this domain slice remains stacked behind it and becomes shipped truth only after dependency-ordered review, fresh exact-head checks, and merge.

README.md

@@ -76,6 +76,11 @@ Job evidence
 - `docs/adr/README.md`
 - `docs/doctoring/REFERENCES.md`
 
+## Implementation slices
+
+- `packages/orgmetra-domain`: bitemporal people, employment, position, assignment, and candidate-worker invariants.
+- `.github/workflows/quality.yml`: pinned Python 3.11-3.14 quality matrix with an aggregate required check.
+
 ## Status
 
-Foundation phase. The protected default branch contains the minimal repository bootstrap; this product baseline is proposed through a reviewed pull request and must not be treated as shipped behavior before merge.
+The foundation baseline is proposed in PR #8 against the protected default `bootstrap` branch. This bitemporal domain kernel is the next stacked implementation PR and is not protected default-branch truth until PR #8 and this PR merge in dependency order with fresh exact-head evidence.

docs/TEST_STRATEGY.md

@@ -31,3 +31,20 @@ Required evidence for any Orgmetra-owned mathematical compute:
 - Exact-value table for every chart.
 - Permission-denied states.
 - High-risk confirmation preview.
+
+## Active domain-kernel test evidence
+
+The stacked implementation runs the behavioral domain suite plus repository-contract tests. It proves:
+
+- reversed and ambiguous bitemporal intervals fail closed;
+- half-open boundaries behave correctly;
+- valid values normalize without silently accepting blanks;
+- assignment allocation is evaluated at an explicit timezone-aware knowledge time so superseded recorded versions do not inflate current FTE;
+- multiple assignments visible at that coordinate can sum to one but cannot exceed one during overlap;
+- adjacent assignments do not overlap;
+- people are validated independently;
+- historical resolution scopes ambiguity to the requested durable identity while ignoring simultaneously visible facts for other identities;
+- candidate-worker registration is idempotent, cannot relink a candidate to a different person, and does not leak candidate/person UUIDs on conflict;
+- owned production statement and branch coverage are exactly 100%;
+- public modules, classes, and functions have docstrings;
+- CI actions are commit-pinned and dependencies are hash-locked.

docs/TRACEABILITY.md

@@ -2,9 +2,12 @@
 
 | Requirement | Architecture | Data object | Test family | ADR |
 |---|---|---|---|---|
-| Separate person/employment/job/position/assignment | Core bounded contexts | `person_record`, `employment_record`, `job_profile`, `position_record`, `assignment_record` | schema/domain tests | ADR-0001 |
+| Separate person/employment/organization/job/position/assignment | Core bounded contexts + `orgmetra-domain` active PR | `person_record`, `employment_record`, `organization_unit`, `job_profile`, `position_record`, `assignment_record` | `test_domain.py` record and assignment tests | ADR-0001 |
+| Durable organization/job identity with bitemporal descriptive history | People Core + `OrganizationUnitRecord` / `OrganizationUnitVersionRecord` / `JobProfileRecord` / `JobProfileVersionRecord` active PR | `organization_unit`, `organization_unit_version`, `job_profile`, `job_profile_version` | `RecordValidationTests` | ADR-0001, ADR-0003 |
+| Effective/system time | Bitemporal HRIS + `BitemporalPeriod` active PR | `effective_from`, `effective_to`, `recorded_from`, `recorded_to` | `BitemporalPeriodTests` | ADR-0003 |
+| Identity-scoped effective-known historical resolution | Bitemporal HRIS + `resolve_bitemporal_fact` active PR | version records exposing durable identity + `BitemporalPeriod` | `BitemporalResolutionTests` retroactive-correction, mixed-identity, no-match, aware-time and same-identity ambiguity cases | ADR-0003, ADR-0004 |
+| Assignment allocation at knowledge time | People Core + `validate_assignment_portfolio` active PR | bitemporal `assignment_record` versions | `AssignmentSecurityRegressionTests` superseded-version and aware-time cases; `AssignmentPortfolioTests` overlap cases | ADR-0001, ADR-0003 |
+| Candidate-worker continuity | People Core + `CandidateWorkerRegistry` active PR | `candidate_worker_link` | `CandidateWorkerRegistryTests`, including identifier-leakage regression | ADR-0001 |
 | Federated CWL integration | Integration Hub | `external_reference` conceptual | adapter contract tests | ADR-0002 |
-| Effective/system time | Bitemporal HRIS | `effective_from`, `recorded_from` | bitemporal tests | ADR-0003 |
-| Evidence-backed decisions | Talent Acquisition | `selection_decision`, `evidence_reference` | decision evidence tests | ADR-0001 |
 | Predictive validity loop | Workforce Validation | `validity_study`, `criterion_observation` | validation registry tests | ADR-0001 |
 | Purpose-bound PII access | Security architecture | field policy conceptual | authorization matrix tests | ADR-0003 |

docs/TRD.md

@@ -85,3 +85,17 @@ Adapters must fail closed, never log credentials, and never promote external dat
 - Criterion and validation registry tests.
 - Integration adapter fake-server tests.
 - Accessibility tests for role workspaces.
+
+## 8. Active implementation evidence
+
+The stacked bitemporal domain slice implements these P0 contracts as a pure Python package:
+
+- half-open effective and recorded intervals;
+- timezone-aware system timestamps;
+- distinct person, employment, and position records;
+- multiple simultaneous assignments with total allocation no greater than one per person;
+- append-only candidate-worker linkage;
+- a PEP 561 typed-package marker;
+- Python 3.11-3.14 CI, exact 100% production statement/branch coverage, and public docstring validation.
+
+Psychometric and mathematical production arithmetic is intentionally absent from this package and remains Rust-first in its owning service.

docs/adr/0004-framework-independent-domain-kernel.md

@@ -0,0 +1,34 @@
+# ADR 0004: Framework-independent domain kernel
+
+## Status
+
+Proposed in active implementation PR.
+
+## Context
+
+Core HRIS invariants must be reusable by standalone services, a modular monorepo, tests, migration workers, and future API adapters without importing a web framework or database driver. These invariants are non-mathematical and do not require the Rust psychometric compute policy.
+
+ADR 0003 requires effective/business time and system-recorded time to remain independently reconstructable. A durable person identity is different from a mutable HR fact: the domain package exposes an identity-only `PersonRecord`, while creation and retirement knowledge time are persistence-owned lifecycle metadata. The authoritative persistence contract must therefore retain `recorded_from` and `recorded_to` for the person anchor even though those columns are not duplicated as mutable attributes on the in-memory identity value. Adapters that load or persist a person anchor must carry that lifecycle metadata in their repository envelope rather than silently dropping it.
+
+## Decision
+
+Implement bitemporal people, employment, position, assignment, and candidate-worker invariants in the independently installable `orgmetra-domain` Python package. Keep persistence, authorization, transport, and external integrations outside the package. Include a PEP 561 marker and exact coverage/docstring gates.
+
+Keep durable identity anchors intentionally small. `PersonRecord` contains only the opaque durable identity; persistence owns the recorded lifecycle of that identity. Mutable person names and other effective-dated facts use explicit version records with `BitemporalPeriod`. Repository adapters are responsible for preserving the anchor's system-recorded lifecycle alongside the identity, and repository-contract tests require both lifecycle columns to remain present in the authoritative schema.
+
+## Consequences
+
+- Domain behavior is testable without infrastructure.
+- Future services can embed the same invariant layer.
+- Database constraints must mirror these rules transactionally.
+- Person-anchor creation/retirement history remains reconstructable without turning the durable identity object into a mutable fact record.
+- A repository adapter that omits the person anchor's `recorded_from` or `recorded_to` violates this ADR even if an identity-only `PersonRecord` can still be constructed.
+- Psychometric and mathematical computation remains Rust-first and is not added to this package.
+
+## Acceptance evidence
+
+- Behavioral RED/GREEN tests for every invariant.
+- Repository-contract proof that the person persistence record retains `recorded_from` and `recorded_to` while the domain anchor remains identity-only.
+- Exact 100% production statement and branch coverage.
+- Python 3.11-3.14 CI.
+- Installed-wheel smoke and `py.typed` presence verification before release.

docs/adr/README.md

@@ -5,3 +5,4 @@
 | 0001 | Accepted baseline | Orgmetra owns authoritative HRIS records |
 | 0002 | Accepted baseline | Federated CWL integration boundaries |
 | 0003 | Accepted baseline | Bitemporal HRIS data contract |
+| 0004 | Proposed in active PR | Framework-independent domain kernel |