docs(copy): speak customer actions instead of internals

docs/STORYBOARD.md

@@ -22,7 +22,7 @@ flowchart LR
 4. Recruiters evaluate candidates against the published job profile.
 5. Interviews focus on evidence gaps and critical KSAO requirements.
 6. Selection decisions are recorded with evidence sufficiency and uncertainty.
-7. Hired candidates become workers through append-only candidate-worker links.
+7. Hired candidates become workers through permanent, auditable candidate-to-worker records.
 8. Work opportunities, assignments, and criterion observations accumulate over time.
 9. Validation studies analyze predictive validity, bias, criterion quality, and drift.
 10. HR revises job architecture, assessment policy, or performance criteria based on evidence.

packages/candidate-evidence/src/orgmetra_candidate_evidence/packet.py

@@ -23,8 +23,8 @@
 _REVIEW_STATE = "requires_human_review"
 _ALLOWED_REASON_CODES = frozenset({"requisition_candidate_review"})
 _NEXT_ACTION = (
-    "Re-resolve every packet reference within tenant_record_id through its authoritative "
-    "boundary; verify candidate, requisition, and Job correlation; then verify job relevance, "
+    "Re-resolve every packet reference within your tenant through its authoritative "
+    "source; verify candidate, requisition, and Job correlation; then verify job relevance, "
     "source provenance, permitted handling, retention, and evidence completeness before "
     "requesting authoritative evidence sealing and accountable human review."
 )

packages/candidate-evidence/tests/test_packet.py

@@ -31,8 +31,8 @@
 DIGEST_D = "d" * 64
 DIGEST_E = "e" * 64
 EXPECTED_NEXT_ACTION = (
-    "Re-resolve every packet reference within tenant_record_id through its authoritative "
-    "boundary; verify candidate, requisition, and Job correlation; then verify job relevance, "
+    "Re-resolve every packet reference within your tenant through its authoritative "
+    "source; verify candidate, requisition, and Job correlation; then verify job relevance, "
     "source provenance, permitted handling, retention, and evidence completeness before "
     "requesting authoritative evidence sealing and accountable human review."
 )

packages/candidate-evidence/tests/test_tenant_scope.py

@@ -34,7 +34,7 @@ def _packet():
 def test_sealing_requires_every_reference_to_resolve_in_exact_tenant() -> None:
     """Prevent cross-tenant evidence mixing behind syntactically valid opaque references."""
     action = _packet().next_action
-    tenant_clause = "Re-resolve every packet reference within tenant_record_id"
+    tenant_clause = "Re-resolve every packet reference within your tenant"
     correlation_clause = "verify candidate, requisition, and Job correlation"
     provenance_clause = "verify job relevance, source provenance"
     sealing_clause = "authoritative evidence sealing"

packages/hris-kernel/src/orgmetra_hris_kernel/assignment.py

@@ -131,7 +131,7 @@ def validate_assignment_employment_coverage(
                 raise EmploymentCoverageError(
                     "Assignment intersects contradictory employment versions in this tenant.",
                     next_action=(
-                        "Close the superseded recorded employment version, then save the assignment again."
+                        "Close the outdated employment version that should have been replaced, then save the assignment again."
                     ),
                 )
     visible = [

packages/hris-kernel/src/orgmetra_hris_kernel/correction.py

@@ -40,6 +40,6 @@ def close_recorded_interval(fact: FactT, *, recorded_to: datetime) -> FactT:
     if recorded_to <= recorded.start:
         raise CorrectionError(
             "Recorded end must be strictly later than recorded start.",
-            next_action="Choose a close time after the original recorded_from, then save.",
+            next_action="Choose a close time after the version's original recorded start, then save.",
         )
     return replace(fact, recorded=RecordedInterval(start=recorded.start, end=recorded_to))

packages/hris-kernel/src/orgmetra_hris_kernel/organization.py

@@ -62,7 +62,7 @@ def validate_organization_hierarchy(
                 raise OrganizationHierarchyError(
                     "Visible organization parent links form a cycle in this tenant.",
                     next_action=(
-                        "Close or correct the superseded parent link, then validate the organization chart again."
+                        "Close or correct the outdated parent link, then validate the organization chart again."
                     ),
                 )
             seen.add(current)

packages/hris-kernel/src/orgmetra_hris_kernel/resolution.py

@@ -86,7 +86,7 @@ def resolve_single_valued_fact(
     if len(visible) > 1:
         raise SingleValuedFactError(
             "One tenant-scoped identity resolved to more than one version.",
-            next_action="Close the prior recorded interval, then insert exactly one replacement.",
+            next_action="Close the previous version's record period, then insert exactly one replacement.",
         )
     if not visible:
         return None

packages/hris-kernel/src/orgmetra_hris_kernel/workforce.py

@@ -152,7 +152,7 @@ def _visible_assignments(
             raise SingleValuedFactError(
                 "One assignment identity resolved to more than one visible assignment fact.",
                 next_action=(
-                    "Close the superseded recorded assignment interval, then rebuild the workforce snapshot."
+                    "Close the outdated assignment version that should have been replaced, then rebuild the workforce snapshot."
                 ),
             )
         seen.add(fact.assignment_record_id)

packages/offer-approval/src/orgmetra_offer_approval/packet.py

@@ -26,9 +26,9 @@
 _REVIEW_STATE = "requires_human_approval"
 _DELIVERY_STATE = "not_authorized_to_send"
 _NEXT_ACTION = (
-    "Within tenant_record_id, re-resolve every packet reference through its authoritative "
-    "boundary; specifically re-resolve requester_reference and approver_reference and verify "
-    "their resolved actor identities are distinct; then verify authoritative Job/Position "
+    "Within your tenant, re-resolve every packet reference through its authoritative "
+    "source; specifically re-resolve the requester and approver actor references and verify "
+    "their resolved actor identities are distinct people; then verify authoritative Job/Position "
     "scope, selected-candidate evidence, compensation-package provenance, and offer-terms "
     "provenance before recording accountable human approval through the authoritative offer "
     "workflow and before communicating or executing the offer."

packages/offer-approval/tests/test_actor_separation.py

@@ -38,14 +38,14 @@ def test_requester_and_approver_require_authoritative_actor_separation() -> None
         _build(approver_reference="actor:99999999-9999-4999-8999-999999999999")
 
     normalized_next_action = _build().next_action.lower()
-    assert "requester_reference and approver_reference" in normalized_next_action
+    assert "requester and approver actor references" in normalized_next_action
     assert "resolved actor identities are distinct" in normalized_next_action
 
 
 def test_approval_requires_every_reference_to_resolve_in_the_exact_tenant() -> None:
     """Prevent cross-tenant offer evidence mixing behind syntactically valid UUID references."""
     action = _build().next_action
-    tenant_clause = "Within tenant_record_id, re-resolve every packet reference"
+    tenant_clause = "Within your tenant, re-resolve every packet reference"
     actor_clause = "verify their resolved actor identities are distinct"
     scope_clause = "verify authoritative Job/Position scope"
     approval_clause = "accountable human approval"

packages/requisition-review/src/orgmetra_requisition_review/packet.py

@@ -22,8 +22,8 @@
 _REVIEW_STATE = "requires_human_approval"
 _ALLOWED_REASON_CODES = frozenset({"approved_growth_plan"})
 _NEXT_ACTION = (
-    "Within tenant_record_id, re-resolve hiring_manager_actor_reference and "
-    "approver_actor_reference through the authoritative actor boundary and verify their "
+    "Within your tenant, re-resolve the hiring manager's and approver's actor references "
+    "through the authoritative identity source and verify their "
     "resolved actor identities are distinct; then confirm the opening is tied to the "
     "approved Job requirements and authorized headcount before recording accountable human "
     "requisition approval."

packages/requisition-review/tests/test_packet.py

@@ -177,7 +177,7 @@ def test_hiring_manager_and_approver_require_authoritative_separation():
         packet(approver_actor_reference=HIRING_MANAGER)
 
     normalized_next_action = packet().next_action.lower()
-    assert "hiring_manager_actor_reference and approver_actor_reference" in normalized_next_action
+    assert "hiring manager's and approver's actor references" in normalized_next_action
     assert "resolved actor identities are distinct" in normalized_next_action
 
 

services/people-api/src/orgmetra_people_api/hire_http.py

@@ -301,7 +301,7 @@ async def __call__(self, scope: Mapping[str, object], receive: AsgiReceive, send
                 status=404,
                 payload={
                     "error": "hire_decision_not_found",
-                    "message": "Verify the confirmed hire decision, tenant, and sealed evidence, then retry.",
+                    "message": "Verify the confirmed hire decision, tenant, and finalized evidence set, then retry.",
                 },
             )
             return
@@ -311,7 +311,7 @@ async def __call__(self, scope: Mapping[str, object], receive: AsgiReceive, send
                 status=409,
                 payload={
                     "error": "hire_integrity_conflict",
-                    "message": "The hire cannot be materialized safely; ask an Orgmetra operator to inspect the decision lineage.",
+                    "message": "The confirmed hire cannot be recorded safely; ask an Orgmetra operator to inspect the hire decision history.",
                 },
             )
             return

services/people-api/src/orgmetra_people_api/http.py

@@ -175,7 +175,7 @@ async def __call__(self, scope: Mapping[str, object], receive: AsgiReceive, send
                 status=409,
                 payload={
                     "error": "worker_integrity_conflict",
-                    "message": "The worker record cannot be returned safely; ask an Orgmetra operator to inspect the authoritative lineage.",
+                    "message": "The worker record cannot be returned safely; ask an Orgmetra operator to inspect the worker record history.",
                 },
             )
             return

tests/validate_repository.py

@@ -139,7 +139,7 @@ def _expected_manifest_document() -> dict[str, Any]:
     return {
         "package": "orgmetra-foundation-pack",
         "version": "0.1.0",
-        "generated_for_branch": "feat/audit-outbox-envelope",
+        "generated_for_branch": "chore/customer-copy-audit",
         "files": files,
     }
 
@@ -153,10 +153,10 @@ def _manifest_entries() -> dict[str, dict[str, Any]]:
 
     if not isinstance(manifest, dict) or not isinstance(manifest.get("files"), list):
         _fail("manifest.json must contain a files array")
-    if manifest.get("generated_for_branch") != "feat/audit-outbox-envelope":
+    if manifest.get("generated_for_branch") != "chore/customer-copy-audit":
         _fail(
             "manifest generated_for_branch must identify the active generation branch "
-            "feat/audit-outbox-envelope"
+            "chore/customer-copy-audit"
         )
 
     entries: dict[str, dict[str, Any]] = {}