feat(workforce): add Position span-of-control evidence

[seonghobae]

Buyer-visible gap

Parent #94 makes solid-line Position-to-Position reporting reconstructable at one business/system coordinate, but Orgmetra still cannot derive a PII-minimized structural span-of-control snapshot for workforce design and diligence. This dependency-first child adds direct-report Position-seat counts only. It never counts workers, infers supervision from Person/Assignment, recommends an "optimal" span, or authorizes an employment decision.

Test-first repair sequence

• Contract-first head ecdba2eeeda9132f449a12f9bd0be9970564dc1e added the focused stacked-base workflow and regression surface before production orgmetra_hris_kernel.span_of_control existed. That short-lived head was superseded before a terminal hosted RED completed, so no cancelled/absent execution is claimed as RED evidence.
• Root implementation added PositionSpanOfControlSnapshot, PositionSpanOfControlError, build_position_span_of_control_snapshot(...), package-root exports, beginner-readable package docs, ADR 0133, primary-research doctoring, and traceability.
• Exact head 5311da5e47e3e33be8b2ffae159303431d89521c, run 33089026577 / job 98576486262, checked out that SHA and passed all 204 HRIS-kernel tests, but correctly failed the exact coverage gate at 99.53%: span_of_control.py had three unexercised direct-construction fail-closed branches (noncanonical aggregate counts, mutable top-level span collection, mutable span entry). That was treated as non-passing evidence rather than weakening the gate.
• Coverage-repair head 7ba443be7622a6e8e213ad3e15ff01df3bd5596c adds realistic adversarial regressions for those three boundaries without changing production semantics.

Governed behavior

PositionSpanOfControlSnapshot consumes one exact governed PositionReportingSnapshot and preserves its tenant, business-date and UTC system-knowledge coordinate. Because the parent dataclass can also be constructed directly, this child revalidates the parent runtime type, non-sentinel opaque UUIDs, immutable two-item edge tuples, single manager per subordinate, no self-edge and cycle freedom before deriving evidence.

The output stores only deterministic manager-Position UUID/direct-report-Position counts, fixed structural_workforce_evidence state, fixed not_authorized_for_employment_decision authority, and SHA-256-addressed canonical JSON. Person, Employment and Assignment identifiers are absent. The API is exported from the HRIS-kernel package root.

Scientific boundary

Span of control is a descriptive organizational-structure measure, not a universal target. Primary research recorded under docs/doctoring/position-span-of-control-references.md shows that observed span relationships vary with work complexity, organizational level and organizational goals. Orgmetra therefore does not encode a single “good” span, performance score, staffing recommendation, promotion/termination signal or compensation implication.

Exact-current-head evidence

Base/parent: #94 feat/position-reporting-hierarchy@2ff1262b976029e447dc736e6472eebbac30a7f5.
Current child head: 139c715062c044fa3cb13967d94268069310c7b3.
GitHub reports open · Draft · mergeable.

Position Span of Control Quality run 33215365348, job 98997658110, is terminal SUCCESS on the exact child head 139c7150…; the exact focused workflow passed 213 HRIS-kernel tests with 100% statement and branch coverage (908 statements, 370 branches).

This is focused stack-local evidence only. #94 checks/reviews do not transfer, and this child is not protected-develop product truth.

Dependency / merge governance

Keep Draft and process #94 first. After #94 actually integrates, retarget/revalidate #133 against fresh develop, reconcile any parent changes, then rerun every applicable Workforce/People/Job-Analysis/Foundation/Recovery/SAST/Security and central required workflow on one new exact head. Obtain qualifying independent non-author review under the live ruleset/commercial policy before merge.

Do not self-approve, use routine administrator bypass, race another lifecycle writer, transfer predecessor evidence, turn a structural count into a high-impact decision rule, or mutate a dedicated-writer dependency.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}