FEATURE SPEC

Questions or comments?

Post them as a comment on the tracking issue -- requires a GitHub account with access to this repo.

Core HR Transaction Bundle: Personal Data, Job Data, Promotion, Demotion, Salary & Bonus

Novaworks AI | x_novaw_corehcm_* — nova-corehcm-agent decision routing + nova-corehcm-sn-app transaction framework

Parent Feature Set: ../concept.md.

Major Change History

Version	Date	Author / Notes
1	2026-08-11	Ravi Buddharaju — Initial draft, derived from the 6 sub-issues' policy/spec/JTBD document trios.
2	2026-08-11	Ravi Buddharaju — Bonus and Incentive Awards deferred out of this build pass (no existing home in nova-compensation-sn-app, skipped rather than pulling that team in now); document/attachment handling resolved to block on worker-document-management; Job Data Changes' storage mechanism resolved to a new effective-dated Job Assignment entry, not a Job Profile/override-field question.

Problem Statement

None of Personal Data Updates, Job Data Changes, Promotion, Demotion, Salary Changes, or Bonus and Incentive Awards has a configured transaction in Nova's transaction framework today. A Worker cannot self-serve an address or dependent change; a Direct Manager cannot initiate a job-description update, promotion, or demotion through a system that knows the difference between them; an HRBP has no tracked queue for the compliance approvals (dependents, tax withholding, compensation-band checks) each of these transactions requires; HR Operations has no audit trail proving any of these six changes happened correctly. Per the parent concept.md, all six were named directly on the 7/16–7/22 Core Transaction Priorities call as blockers for Ateko's go-live.

Use Cases

Use Case 1 (Personal Data Updates): A Worker moves apartments and needs to update their address. Today there is no self-service path at all — the change would have to go through HR regardless of the fact that an address change carries no compliance risk, which matters because it turns a zero-risk update into an unnecessary HR queue item.

Use Case 2 (Job Data Changes): A Direct Manager needs to update a report's job description and skill tags because the role's day-to-day scope shifted, without changing their job level. Today there's no way to make this update without it being ambiguous whether it's actually a level change, which matters because a level change carries compensation-band and approval requirements this change doesn't need and shouldn't trigger.

Use Case 3 (Promotion): An HR Business Partner needs to move a worker to a higher-level role with a corresponding compensation-band adjustment. Today there's no guided approval chain distinguishing this from a routine job data change, which matters because a promotion's compensation-band and multi-approver requirements are exactly the kind of thing that gets missed in an ad hoc process.

Use Case 4 (Demotion): An HR Business Partner or Department Head needs to move a worker to a lower-level role, often as part of a broader performance or restructuring decision. Today there's no tracked workflow separating the decision/communication side from the compensation-change side, which matters because a demotion carries the same compliance stakes as a promotion but is more likely to be handled entirely off-system.

Use Case 5 (Salary Changes): A Direct Manager proposes a merit increase or compensation adjustment for a report. Today there's no system path validating the change against budget or requiring the right second approval, which matters because an ungoverned salary change is a direct payroll and compliance risk.

Use Case 6 (Bonus and Incentive Awards): A Direct Manager or HR Business Partner needs to record a target or actual bonus/incentive award. Today there's no tracked record linking the award nomination through to payroll, which matters because an award that's approved but never reaches payroll is a direct financial and trust failure.

Scope

Six transactions were originally scoped; five are built in this pass — Bonus and Incentive Awards is deferred (see Out of Scope). Each is configured against Nova's existing transaction framework (TransactionContextRunnerService + Decision Table routing in nova-corehcm-sn-app, orchestrated by nova-corehcm-agent's decision node) — not a new, one-off workflow per type. What's autonomous vs. human-gated is set per transaction by its own Decision Table, not uniformly:

1. Personal Data Updates (#105)

Covers address, contact info, dependent, and tax-withholding changes. - Required: worker reference, field being updated, new value. - Optional: effective date (defaults to today for address/contact; required for tax withholding), supporting documentation (required for dependent additions and most tax withholding changes). - Autonomous: address/contact info — format-validated and applied immediately, no approval gate. - Human-gated: dependent info and tax withholding — routed to the HR Business Partner for compliance review before finalizing. - Validation: address must match a valid postal format for the country on file; tax withholding must reference current rules for the worker's legal jurisdiction; adding a dependent requires supporting documentation before the record is finalized.

2. Job Data Changes (#667)

Covers job description text and skill-tag updates only — explicitly not job level. - Required: worker reference, field being changed (description, skill tags), new value, effective date. - Optional: reason code (role refresh, skills update, job architecture alignment). - Human-gated: Direct Manager confirms the update reflects how the role is actually performed. - Mechanism (resolved): writes a new Job Assignment entry with the new value and the change's effective date as its job_start_date; the prior Job Assignment entry is closed by setting its job_end_date to that same effective date, kept for historical record rather than overwritten — the same effective-dating pattern already used by other transactions (e.g. department transfer, manager change), not a shared Job Profile edit and not a new override field. - Validation: a submission that changes job level is rejected and redirected to Promotion/Demotion instead of being processed here; effective date cannot be retroactive without HR override; worker must not have another job change transaction open for the same effective date.

3. Promotion (#666)

Moves a worker to a higher job level, with the corresponding compensation-band change. - Required: worker, new job level, new job title, effective date. - Optional: notes/business justification. - Human-gated: HR Business Partner confirms the new level and compensation-band alignment with promotion guidelines; Department Head approves within band and budget. - Validation: new job level must be higher than current; new compensation must fall within the target level's band unless HR override is applied; effective date must be future-dated.

4. Demotion (#665)

Moves a worker to a lower job level, with the corresponding compensation-band change. - Required: worker, new job level, new job title, effective date, reason. - Optional: notes/documentation of the decision (e.g. performance, restructuring). - Human-gated: HR Business Partner and Department Head approve, both informed of the applicable compensation change. - Validation: new job level must be lower than current; compensation change is tracked separately from the job-level change itself; effective date must be future-dated.

5. Salary Changes (#673)

Covers merit increases and compensation adjustments (base salary), by percentage or flat amount, with an effective date. - Required: worker, new salary/adjustment amount, adjustment type (merit increase, market adjustment, promotion-related), effective date. - Optional: notes; linked performance-cycle reference. - Human-gated: Direct Manager proposes; HR Business Partner or Compensation reviewer confirms the change is within budget and correctly recorded before it's approved. - Validation: actual amount ratio to target amount is checked; reason code required if the change deviates from the standard merit cycle; annual increase cap enforced unless HR override is applied.

Out of Scope

• Bonus and Incentive Awards (#674) — deferred out of this build pass. Confirmed during implementation planning to have no existing home in nova-compensation-sn-app (no field, table, or service method supports a target/actual recurring award); rather than pulling that app's team in as a stakeholder now, this transaction is skipped. Revisit as its own Feature once that stakeholder engagement happens. (Kept documented above under Use Case 6 for context on the original ask.)
• Cost Center Change (#664) and Org Restructuring/Reorganizations/Hierarchies (#672) — no policy/spec/JTBD material exists for either yet; per the parent concept.md's Open Question #7, these are deferred to a later Feature under this same Feature Set (or a new one) rather than blocking this bundle.
• Any document/attachment storage mechanism itself (the underlying capability to attach and store supporting documentation for dependents/tax withholding) — resolved to block on worker-document-management; this Feature does not build any part of that capability itself. See Dependencies below.

Value

Ships all six of Ateko's named go-live blockers as configuration against Nova's existing transaction framework rather than six bespoke builds — the fastest path to Ateko's go-live, and the first real proof that adding a new Core HR transaction type is a configuration exercise (Decision Table + context scripts), not a new feature build each time.

Delivery

UX Description

Two surfaces: a Worker-facing self-service view (address/contact, dependent, tax withholding) inside the Nova HR portal, and a Manager/HRBP approval queue (ServiceNow task list) for every transaction requiring review. Both are also reachable conversationally through nova-corehcm-agent's natural-language interface (e.g. "update my address," "promote Jane Doe to Senior Engineer effective next month"), which resolves intent and required fields before handing off to the same underlying transaction.

Key User Flows

1. Deterministic self-service (address/contact): Worker opens their profile → edits the field → system validates format → change applies immediately → worker sees confirmation with the new value and effective date. No approval step.
2. Compliance-gated self-service (dependent/tax withholding): Worker submits the change with supporting documentation → system creates a Pending Approval transaction → HRBP reviews in their task queue → approve applies the change and notifies the worker; deny returns the transaction with the stated reason and lets the worker resubmit.
3. Manager-initiated job/comp change (promotion, demotion, salary change): Manager (or HR Business Partner, for promotion/demotion) submits the transaction with required parameters → system runs validation (level direction, band, budget) → routes to the configured approval chain (HRBP, Department Head, or both) → on full approval, the SOR update executes and the worker and manager are notified with the effective date; on denial, the transaction closes with the approver's stated reason and the initiator can resubmit as a new transaction.
4. Conversational entry via nova-corehcm-agent: User states the request in natural language → agent extracts entities and validates them against ServiceNow → agent surfaces any missing required fields as a clarifying question → once complete, the request proceeds through the same decision-routing and approval flow as the portal path above → agent returns the same completion/approval-pending/denial response.

Human Override & Fallback Strategy

• Worker — no override point for address/contact (fully deterministic); can resubmit a dependent/tax-withholding change if denied or if a validation error is shown.
• Direct Manager — approves/denies Job Data Changes; proposes Salary Changes; can resubmit any denied transaction with corrections.
• HR Business Partner — approves/denies Personal Data Updates' dependent/tax fields, Promotion, Demotion, and Salary Changes; can apply an HR override on band/cap/retroactive-date validations where the policy allows it.
• Department Head — second approver on Promotion and Demotion, informed of the associated compensation change.
• Fallback for low-confidence agent extraction: when nova-corehcm-agent can't confidently resolve an entity (e.g. ambiguous worker name, unclear new job level), it asks the user a clarifying question rather than guessing or proceeding; a validation failure at submission returns the specific rule that failed so the initiator can correct and resubmit rather than being told only that the change failed.

AI Feedback Loop

• Explicit: the initiator can correct any entity nova-corehcm-agent extracted before final submission (e.g. wrong worker resolved from a name); an approver denying a transaction states a reason, which is itself a correction signal fed back to the initiator.
• Explicit: HR Operations' periodic audit of applied transactions (named in each transaction's policy) surfaces incorrect approvals or data after the fact, which is a delayed but explicit correction mechanism.
• Implicit: resubmission rate after a validation failure or denial, tracked per transaction type, signals where the agent's entity extraction or the Decision Table's routing is producing avoidable friction.
• Implicit: HR override frequency on band/cap/retroactive-date validations signals where a hard-coded rule is too strict relative to real HR judgment.

Acceptance Criteria

Personal Data Updates - A Worker changing their address or contact info sees the new value reflected on their profile immediately, with no approval step and no notification sent to HR. - A Worker adding a dependent without attaching supporting documentation cannot finalize the change; the system blocks the submission until documentation is attached. - A dependent or tax-withholding change creates a Pending Approval transaction routed to the HR Business Partner; on approval, the Worker record and any linked payroll/benefits fields update and the worker is notified. - HR Operations can retrieve a per-worker log of every personal data change and its approval status for periodic compliance audit.

Job Data Changes - A submission that includes a job-level change is rejected at validation with a message directing the initiator to Promotion or Demotion instead of being processed as a Job Data Change. - A Direct Manager approving a Job Data Change results in a new effective-dated Job Assignment entry carrying the worker's updated job description and/or skill tags, with the prior entry closed (job_end_date set to the same effective date) rather than overwritten, reflected in skills-inventory and internal mobility matching. - A worker with an already-open Job Data Change transaction for the same effective date cannot submit a second one until the first resolves.

Promotion - A Promotion is rejected at validation if the new job level is not higher than the worker's current level. - A Promotion requires both HR Business Partner and Department Head approval before the Job Assignment and compensation update; either approver denying halts the transaction and notifies the initiator with the stated reason. - On full approval, the worker's job level, title, and compensation update on the effective date, and the worker is notified.

Demotion - A Demotion is rejected at validation if the new job level is not lower than the worker's current level. - A Demotion requires both HR Business Partner and Department Head approval; either approver denying halts the transaction and notifies the initiator with the stated reason. - On full approval, the worker's job level, title, and compensation update on the effective date, logged separately in job history and compensation-change history.

Salary Changes - A Salary Change proposed by a Direct Manager routes to an HR Business Partner or Compensation reviewer before it's applied to the Worker's compensation record. - A Salary Change that exceeds the annual increase cap is blocked unless an HR override is applied. - On approval, the new compensation amount and effective date update on the Worker's compensation record, and both the worker and the proposing manager are notified.

Bonus and Incentive Awards has no acceptance criteria in this pass — deferred, see Out of Scope.

Dependencies / Related Features

• worker-document-management (separate Feature Set): Personal Data Updates' dependent-addition and tax-withholding flows require attaching supporting documentation, and no document/attachment reference exists on Person/Worker today (per schema/core-hr-schema.md's Open items). Resolved: this Feature blocks on worker-document-management for all document/attachment handling — it does not build any part of that capability itself.
• A future Cost Center Change / Org Restructuring Feature (same Feature Set, not yet scoped): shares the same transaction-framework pattern; no direct data dependency.

Risks

Risk	Severity	Mitigation
Personal Data Updates' human-gated paths depend on worker-document-management, a separate Feature Set not yet scoped	High	This Feature blocks on that dependency (resolved decision) — sequencing risk, not a design open item
Unclear whether Worker supports multi-jurisdiction tax withholding	Medium	Confirm with Architect during schema-delta drafting; single-jurisdiction may be an acceptable v1 scope cut if flagged explicitly
x_nova_corehcm_* vs. x_novaw_corehcm_* table-prefix conflict still open	Low	Confirm with EL/PM before any table reference in the eventual schema-changes.md is finalized

Open Questions

• Does Worker need multi-jurisdiction tax-withholding support in this Feature's v1, or is single-jurisdiction an acceptable initial scope cut?
• What reason-code values are required for Job Data Changes — is "role refresh / skills update / job architecture alignment" the final set, or does HR need more?
• No JTBD job map (feature-sets/critical-core-hr-transactions/jbtd-critical-core-hr-transactions/) exists yet for the personas this bundle serves — the 6 JTBD canvases in corehr-tns/ cover the same ground per-transaction but aren't in the formal job-map format this repo's convention expects. Not blocking, but worth reconciling later.

---

For internal engineering review only.

Novaworks AI | Confidential