@salesforce/afv-skills 1.65.0 → 1.66.0

package/skills/field-service-work-rule-designer-configure/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: field-service-work-rule-designer-configure
-description: "Designs the work rules for a Salesforce Field Service scheduling policy — the hard filters that determine which resources and time slots are eligible for an appointment. Step 2 of the three-part scheduling policy design flow. Receives the policy block from sfs-scheduling-policy-designer and delegates to sfs-service-objective-designer when complete."
+description: "Designs the work rules for a Salesforce Field Service scheduling policy — the hard filters that determine which resources and time slots are eligible for an appointment. Step 2 of the three-part scheduling policy design flow; receives the policy block from sfs-scheduling-policy-designer and delegates to sfs-service-objective-designer when complete. Use this skill when a user wants to design or configure the work rules (hard eligibility filters) for a Field Service scheduling policy."
+user-invocable: false
 metadata:
   version: "1.0"
+  domains: ["Field Service"]
 ---
 
 # Salesforce Field Service – Work Rule Designer
@@ -40,119 +42,139 @@ Each row: **name — engine (DB/Apex) — what it does.** "DB w/ ESO" means the
 | **TimeSlot Designated Work** | Apex | Reserves a time slot/shift for a specific work type — only that type schedules in that window. All-or-nothing rule (no relevance groups). |
 | **Service Crew Resources Availability** | Apex | Ensures a crew-type resource is only assigned when the crew meets the parent record's minimum crew size. |
 
-### Interview order — MANDATORY
+### Requirements mapping
+
+Don't start from the rule list — start from **what the business needs**, then map each requirement to the rule(s) that satisfy it. Walk the user through this mapping:
+
+| If the requirement is… | Use this work rule |
+|---|---|
+| Resources need specific skills / proficiency levels | **Match Skills**; **Extended Match** |
+| Non-skill matching factors (e.g., serviceable postal codes) | **Match Boolean**; **Match Skills**; **Extended Match** |
+| Breaks during the day / specific or multiple breaks | **Service Resource Availability** (+ work rule entries for multiple breaks, ESO) |
+| Can work go into overtime? Can resources travel outside working hours? | **Service Resource Availability** |
+| Max number / duration of appointments per resource per day | **Count Rule** |
+| A specific resource **must** be assigned | **Required Resources** |
+| A specific resource **must not** be assigned | **Excluded Resources** |
+| Customer has specific service-call time windows | **Service Appointment Visiting Hours** |
+| Ensure crew-type resources get scheduled | **Service Crew Resources Availability** |
+| Appointments have arrival windows / required arrival times | **Match Time Rule** |
+| Cap travel distance from home / control travel cost across large territories | **Maximum Travel from Home** — ask whether the cap is by **distance** or by **travel time** (see note below) |
+| Assign specific work types to a resource for part/all of a day | **TimeSlot Designated Work** |
+| Restrict work to the resource's **primary and secondary** service territory memberships | **Working Territories** |
 
-Walk through the 16 work rule types **in the exact order of the table in *The 16 work rule types* above** — top to bottom, one rule at a time. **Do NOT split the interview into a separate "which rules apply" pass and a later "configure them" pass, and do NOT reorder the rules.** For each rule, in order:
+Always include exactly one **Service Resource Availability** rule — the only mandatory rule this skill emits. Never emit Earliest Start Permitted or Due Date — provisioned automatically.
 
-1. **Decide whether it applies.** Service Resource Availability is always in (no question). For every other rule, either the user's stated business needs already make it obviously needed, or ask the short **Applies when / ask** question in that rule's entry below. Interpret the user's needs against the *What it does* column — e.g. "resources need the right skills" → Match Skills; "cap travel from home" → Maximum Travel from Home.
-2. **If it applies and it has configuration, ask that rule's config question(s) right now** — before moving on to the next rule. Never defer configuration to the end. If the rule is selection-only (no config), just confirm it and continue.
+**Arrival Window Match Time rules (opt-in default pair).** If the user wants appointments to honor customer **arrival windows**, ask them to confirm, and if they agree, emit **two** Match Time rules with these exact default settings — do not ask the user to fill these in, they are the standard arrival-window configuration:
 
-Then continue to the next rule in the table. Ask one question at a time. Only after you have walked all 16 rules is the rule list final.
+| Setting | Rule A | Rule B |
+|---|---|---|
+| Name | `Arrival Window Start` | `Arrival Window End` |
+| Service Schedule Time Property | `SchedStartTime` | `SchedStartTime` |
+| Service Time Operator | `Later than or Equal to` | `Before or Equal to` |
+| Service Time Property | `ArrivalWindowStartTime` | `ArrivalWindowEndTime` |
+| Pass Empty Values | `true` | `true` |
 
-**Do NOT ask a relevance-group / subset question on every rule.** Most rules apply policy-wide, and asking "all or a subset?" after each one is noise. Instead:
+Emit each as a Match Time work rule whose `params` carry those four values (keys `serviceScheduleTimeProperty`, `serviceTimeOperator`, `serviceTimeProperty`, `passEmptyValues`). These are separate from the mandatory Earliest Start Permitted / Due Date rules (never emitted).
 
-- **React to scoping the user volunteers.** If while answering a rule's question the user signals the rule is only for a specific scenario, workforce, or work type — e.g. "only for part-time techs," "just for installation jobs," "tighter cap in France" — *then* pursue it: confirm the basis (Service Territory Member for a resource subset, Service Appointment for a work subset), get the Boolean field name, and record `relevanceGroup: { basis, booleanField }` on that rule. (First check the rule supports that basis under ES&O — see *Relevance Groups*.)
-- **Otherwise sweep for it once, at the end.** After all 16 rules are walked, ask a single closing question: *"Are there any constraints here that should apply only to a certain part of your workforce or to certain types of work — rather than to everyone/everything? For example, different break or travel limits for part-time vs. full-time techs, or stricter handling for a specific work type or region."* Only if the user says yes do you scope the affected rules (per the *Relevance Groups* section). If no, leave every `relevanceGroup` null.
+**Interpreting and emitting break times (clock time vs. shift-start offset):** A Service Resource Availability rule expresses breaks in one of two shapes, and **this skill decides the shape and emits the values the data-layer skill needs** — the data-layer skill never receives a clock time it has to convert. Choose the shape as follows:
 
-Always include exactly one **Service Resource Availability** rule — the only mandatory rule this skill emits. Never emit Earliest Start Permitted or Due Date — provisioned automatically.
+- **One fixed daily break at an absolute clock time** (e.g. "30 minutes at 12:00 every day") → emit it as an **absolute** break: `{ "mode": "absolute", "startClock": "12:00", "durationMinutes": 30 }`. No offset math, no working-day start needed.
+- **One or more breaks defined as an offset from the start of the working day** (e.g. "a 30-minute lunch starting 3 hours into the shift") → emit each as an **offset** break, in **minutes from the start of the working day**: `{ "mode": "offset", "earliestStartOffsetMinutes": 180, "latestEndOffsetMinutes": 240, "durationMinutes": 30 }`. All three of `earliestStartOffsetMinutes`, `latestEndOffsetMinutes`, and `durationMinutes` are **mandatory** for an offset break. **When the user states the break in offset terms already** (e.g. "3 hours after the start of day"), that offset *is* `earliestStartOffsetMinutes` (180) — **do not ask for the working-day start; you don't need it.**
+- **Breaks given as clock times but there is more than one** (e.g. "15 minutes at 10:00 and 30 minutes at 12:00") → you must use the **offset** shape, which means **converting each clock time into an offset from the start of the working day**. You cannot do that without knowing when the day starts, so **ask the user for the shift / working-day start**, then compute `earliestStartOffsetMinutes = (break start clock − day start)` in minutes for each break. Never assume the day starts at midnight (that would turn "10:00" into a wrong 600-minute offset). *(Only ask for the day start in this clock-time case — never when the break is already expressed as an offset.)*
 
----
+**Always emit `latestEndOffsetMinutes` for every offset break — ask for it directly, do not fabricate a window.** The earliest start comes from what the user stated (an offset, or a converted clock time) — **do not invent ± tolerance windows around it** (no "±1 hour" / "±2 hour" options). If the user only gave a break start (or a duration with no stated finish-by), **ask them plainly for the latest the break may end**, phrased in the *same terms they used*: if they gave an offset ("starts 3 hours after start of day"), ask "what is the latest it may end, as time after the start of the day?" and convert (e.g. "4 hours after start" → 240); if they gave a clock time, ask for a clock time and convert with the day start. If the user says the break is fixed/pinned with no flex, set `latestEndOffsetMinutes = earliestStartOffsetMinutes + durationMinutes`. Never emit an offset break missing any of the three fields, and never guess the latest-end. If a break requirement is too involved to convert reliably, ask clarifying questions or recommend the manual approach rather than guessing.
+
+**Maximum Travel from Home — establish the cap type, not the unit.** When a requirement caps how far a resource may travel from home, **ask the user whether the cap is by distance or by travel time** — the two are configured differently and the data-layer skill needs to know which. Emit the value and the type in `params`: `{ "maxTravelFromHome": 50, "maxTravelFromHomeType": "Distance" | "Travel Time" }`. Interpret the user's phrasing to set the *type* — "50 miles"/"50 km" ⇒ `Distance`, "45 minutes" ⇒ `Travel Time` — but **do not ask for or emit a distance unit (miles vs km): it is not part of the work-rule config**; the unit is governed by the org's locale/distance settings elsewhere, so the rule stores only the number. For `Travel Time` the value is minutes. Never emit the cap value without its type.
 
-### The rules, in interview order
+### Per-rule configuration
 
-Take these in the order shown — it matches the table above. For each entry: **Applies when** tells you how to decide it's needed; **Ask** lists the config questions to ask *immediately* on a yes; **Emit** gives the exact `params` keys — use them verbatim so the data-layer skill can map them.
+Once the requirements mapping has selected which rules to build, configure the specifics for each. The **`Emit` line gives the exact `params` keys** — use these verbatim so the data-layer skill can map them. Only configure rules the user selected; skip the rest.
 
 ---
 
-**1. Service Resource Availability** *(always present — the only mandatory rule)*
-Applies when: always. No applicability question.
+**Service Resource Availability** *(always present)*
+Gate: Always included — no selection needed.
 Ask:
 - "Can work run into **overtime**?" (yes/no)
 - "Can resources **travel outside working hours** to/from home?" — if yes, ask how many minutes from home (to first job) and to home (from last job); "no limit" = 120; "no" = 0 for both
-- Breaks interview (see *Interpreting and emitting break times* below)
+- Breaks interview (see *Interpreting and emitting break times*)
 
 Emit: `{ "enableOvertime": true|false, "travelFromHomeMinutes": <number>, "travelToHomeMinutes": <number>, "breaks": [ … ] }`
-Note: Travel values are minutes — 0 = no travel outside working hours, 120 = effectively unlimited. If the user gives no availability detail, emit baseline (`enableOvertime: false`, travel keys and breaks omitted).
+Note: Travel values are minutes — 0 = no travel outside working hours, 120 = effectively unlimited. If user gives no availability detail, emit baseline (`enableOvertime: false`, travel keys and breaks omitted).
 
 ---
 
-**2. Match Time Rule** *(arrival windows)*
-Applies when: appointments should honor customer **arrival windows** / required arrival times. Ask: "Should appointments honor customer arrival windows?"
-Emit: on a yes, emit the **two** default rules from the *Arrival Window Match Time rules* table below — do not ask the user to fill these in.
+**Match Time Rule** *(arrival windows)*
+Gate: Only if selected in requirements mapping.
+Ask: "Should appointments honor customer **arrival windows**?"
+Emit: Two default rules from the Arrival Window table — no further questions.
 
 ---
 
-**3. Match Skills**
-Applies when: resources need specific skills / proficiency levels.
+**Match Skills**
+Gate: Only if selected in requirements mapping.
 Ask: "Should the resource also **meet a minimum skill level** (proficiency), or is simply *having* the skill enough?"
 Emit: `{ "matchSkillLevel": true|false }`
 Note: Do not ask about skill-type AND/OR logic — this skill does not configure `skillTypeLogic`.
 
 ---
 
-**4. Match Fields**
-Applies when: one appointment field must match one resource field (1:1). (For one appointment field vs. multiple resource values, use Extended Match instead.)
+**Match Fields**
+Gate: Only if selected in requirements mapping.
 Ask: "Which Service Appointment field must match which Service Resource field, and with what operator?"
 Emit: `{ "serviceProperty": "<SA field>", "resourceProperty": "<resource field>", "booleanOperator": "=" }`
 Note: Operator is one of `=`, `>=`, `<=`, `>`, `<` (default `=`). Field names are the customer's own — pass through as given.
 
 ---
 
-**5. Match Boolean**
-Applies when: a checkbox on the resource must be true/false — including non-skill matching factors (e.g., serviceable postal codes).
+**Match Boolean**
+Gate: Only if selected in requirements mapping.
 Ask: "Which checkbox field on the resource must be true (or false)?"
 Emit: `{ "resourceProperty": "<resource field>", "value": true|false }`
 Note: Max 5 Match Boolean rules per policy.
 
 ---
 
-**6. Extended Match** *(advisory only — data-layer skill will not build this)*
-Applies when: custom-criteria matching via a junction object (e.g., serviceable postal codes, product lines).
-Ask: None — no params to collect. Advise the user to set up before deploying:
-1. A junction object with exactly **two** Master-Detail relationships (to Service Resource + matched object) — packaged trigger requires exactly two or the rule fails
-2. A Service Appointment Lookup field driving the match; a reference field on the junction matched against it
-3. Once those exist, create and configure the rule manually in Setup (Field Service Settings → Scheduling → Work Rules)
-
-Capture intended objects/fields in `prerequisites` as advisory text — do not emit in `workRules[]`.
-
----
-
-**7. Match Territory** — *(skip entirely; not part of the interview)*
-This interview never emits a standalone Match Territory rule. **Skip it silently** — do not ask a Match Territory question, and do not announce or narrate that you are skipping it. Move straight from rule 6 to rule 8 with no mention of Match Territory at all. (If a user explicitly asks for primary/relocation-only territory scoping, advise manual configuration then — but never raise it yourself. Also: don't cover a resource by both Match Territory and Working Territories.)
+**Maximum Travel from Home**
+Gate: Only if selected in requirements mapping.
+Ask: "Is the cap by **distance** or by **travel time**?" (see cap-type note in Requirements mapping)
+Emit: `{ "maxTravelFromHome": <number>, "maxTravelFromHomeType": "Distance"|"Travel Time" }`
+Note: Distance unit (miles vs km) is not part of the rule — governed by org locale. For Travel Time, value is minutes.
 
 ---
 
-**8. Working Territories**
-Applies when: work must be restricted to the resource's **primary and secondary** service territory memberships.
+**Working Territories**
+Gate: Only if selected in requirements mapping.
 Ask: None — selecting the rule is sufficient.
 Emit: `{ "workingLocationEnablePrimary": true }`
+Note: No separate Match Territory question — the interview does not emit a standalone Match Territory rule. If primary/relocation-only scoping is needed, advise manual configuration.
 
 ---
 
-**9. Maximum Travel from Home**
-Applies when: capping distance/travel time between a resource's home and any assigned appointment / controlling travel cost across large territories.
-Ask: "Is the cap by **distance** or by **travel time**?" (see the cap-type note below), plus the cap value.
-Emit: `{ "maxTravelFromHome": <number>, "maxTravelFromHomeType": "Distance"|"Travel Time" }`
-Note: Distance unit (miles vs km) is not part of the rule — governed by org locale. For Travel Time, value is minutes.
-
----
+**Service Crew Resources Availability**
+Gate: Only if selected in requirements mapping.
+Ask:
+- "Should the rule evaluate individual crew members' availability and skills, not just the crew record?" → `considerCrewMembership`
+- "What is the maximum number of extra resources beyond the base crew that can be pulled in?" → `maxAdditionalResources` (optional)
 
-**10. Required Resources** *(selection-only)*
-Applies when: any work order ever has a resource marked **Required** that must always be assigned. Ask: "Do any work orders ever have a specific resource marked *Required* that must always be assigned to that job?"
-Emit: `{}`
-Prerequisite: Resource Preference records must exist on the work order / WOLI — the rule enforces them but does not create them.
+Emit: `{ "considerCrewMembership": true|false, "maxAdditionalResources": <number> }` (omit `maxAdditionalResources` if blank)
 
 ---
 
-**11. Excluded Resources** *(selection-only)*
-Applies when: any work order ever has a resource marked **Excluded** that must never be assigned. Ask: "Do any work orders ever have a resource marked *Excluded* that must never be assigned?"
-Emit: `{}`
-Prerequisite: Resource Preference records must exist on the work order / WOLI — the rule enforces them but does not create them.
+**Extended Match** *(advisory only — data-layer skill will not build this)*
+Gate: Only if selected in requirements mapping.
+Ask: None — no params to collect.
+Advise the user to set up before deploying:
+1. A junction object with exactly **two** Master-Detail relationships (to Service Resource + matched object) — packaged trigger requires exactly two or the rule fails
+2. A Service Appointment Lookup field driving the match; a reference field on the junction matched against it
+3. Once those exist, create and configure the rule manually in Setup (Field Service Settings → Scheduling → Work Rules)
+
+Capture intended objects/fields in `prerequisites` as advisory text — do not emit in `workRules[]`.
 
 ---
 
-**12. Count Rule**
-Applies when: capping the number/duration of appointments (or a custom value) per resource per day.
+**Count Rule**
+Gate: Only if selected in requirements mapping.
 Ask: Have the user describe the limit in plain terms, then classify into:
 - `countBy` — `"Appointments"` (count of jobs), `"Hours"` (duration cap), or `"Custom"` (sum of a custom SA field)
 - `maxValue` — the numeric cap (for Hours, convert to hours)
@@ -163,67 +185,32 @@ Note: Time Resolution is always Daily; counted object is always Service Appointm
 
 ---
 
-**13. Work Capacity** *(ESO only — selection-only)*
-Applies when: Work Capacity Limit records cap how much work schedules per territory. Ask: "Do you use Work Capacity Limit records to cap how much work can be scheduled per territory?"
+**Selection-only rules** *(no config fields — each rule acts as an on/off switch that tells the scheduler to enforce constraints defined elsewhere in the org; selected in requirements mapping, no further questions needed)*
+
+**Required Resources / Excluded Resources**
+Gate: Only if selected in requirements mapping.
 Emit: `{}`
-Prerequisite: WorkCapacityLimit records must be configured per territory outside the policy.
+Prerequisite: Resource Preference records must exist on the work order / WOLI — the rule enforces them but does not create them.
 
----
+**Work Capacity** *(ESO only)*
+Gate: Only if selected in requirements mapping.
+Emit: `{}`
+Prerequisite: WorkCapacityLimit records must be configured per territory outside the policy.
 
-**14. Service Appointment Visiting Hours** *(selection-only)*
-Applies when: customers have allowed visit windows that should block scheduling outside those hours. Ask: "Do customers have allowed visit windows (e.g., weekdays only, or mornings only) that should block scheduling outside those hours?"
+**Service Appointment Visiting Hours**
+Gate: Only if selected in requirements mapping.
 Emit: `{}`
-Note: Do not ask for the windows — they are per-account data on OperatingHours records, not a policy-wide value. All-or-nothing rule — no relevance-group scoping.
+Note: Do not ask for the windows — they are per-account data on OperatingHours records, not a policy-wide value. (No relevance-group scoping.)
 Prerequisite: Each account must have visiting/operating hours populated; the Work Order's Visiting Hours must resolve from the account.
 
----
-
-**15. TimeSlot Designated Work** *(selection-only)*
-Applies when: certain time slots must be reserved for specific types of work. Ask: "Do you need to reserve certain time slots for specific types of work (e.g., install work only in morning slots)?"
+**TimeSlot Designated Work**
+Gate: Only if selected in requirements mapping.
 Emit: `{}`
-Note: Do not ask for slot→work mappings — that is data setup. Phrase the selection as "types of work," not "Work Type" (the designation is broader than the Work Type object). All-or-nothing rule — no relevance-group scoping.
+Note: Do not ask for slot→work mappings — that is data setup. Phrase the selection as "types of work," not "Work Type" (the designation is broader than the Work Type object). (No relevance-group scoping.)
 Prerequisite: Time slots must be configured to designate the intended work.
 
 ---
 
-**16. Service Crew Resources Availability**
-Applies when: crew-type resources must only be assigned when the crew meets the parent record's minimum crew size.
-Ask:
-- "Should the rule evaluate individual crew members' availability and skills, not just the crew record?" → `considerCrewMembership`
-- "What is the maximum number of extra resources beyond the base crew that can be pulled in?" → `maxAdditionalResources` (optional)
-
-Emit: `{ "considerCrewMembership": true|false, "maxAdditionalResources": <number> }` (omit `maxAdditionalResources` if blank)
-
----
-
-### Configuration reference notes
-
-These deep-dives support the **Ask** lines above; consult them when configuring the rule that references them.
-
-**Arrival Window Match Time rules (default pair — rule 2).** When the user confirms appointments should honor customer arrival windows, emit **two** Match Time rules with these exact default settings — do not ask the user to fill these in, they are the standard arrival-window configuration:
-
-| Setting | Rule A | Rule B |
-|---|---|---|
-| Name | `Arrival Window Start` | `Arrival Window End` |
-| Service Schedule Time Property | `SchedStartTime` | `SchedStartTime` |
-| Service Time Operator | `Later than or Equal to` | `Before or Equal to` |
-| Service Time Property | `ArrivalWindowStartTime` | `ArrivalWindowEndTime` |
-| Pass Empty Values | `true` | `true` |
-
-Emit each as a Match Time work rule whose `params` carry those four values (keys `serviceScheduleTimeProperty`, `serviceTimeOperator`, `serviceTimeProperty`, `passEmptyValues`). These are separate from the mandatory Earliest Start Permitted / Due Date rules (never emitted).
-
-**Interpreting and emitting break times — clock time vs. shift-start offset (rule 1).** A Service Resource Availability rule expresses breaks in one of two shapes, and **this skill decides the shape and emits the values the data-layer skill needs** — the data-layer skill never receives a clock time it has to convert. Choose the shape as follows:
-
-- **One fixed daily break at an absolute clock time** (e.g. "30 minutes at 12:00 every day") → emit it as an **absolute** break: `{ "mode": "absolute", "startClock": "12:00", "durationMinutes": 30 }`. No offset math, no working-day start needed.
-- **One or more breaks defined as an offset from the start of the working day** (e.g. "a 30-minute lunch starting 3 hours into the shift") → emit each as an **offset** break, in **minutes from the start of the working day**: `{ "mode": "offset", "earliestStartOffsetMinutes": 180, "latestEndOffsetMinutes": 240, "durationMinutes": 30 }`. All three of `earliestStartOffsetMinutes`, `latestEndOffsetMinutes`, and `durationMinutes` are **mandatory** for an offset break. **When the user states the break in offset terms already** (e.g. "3 hours after the start of day"), that offset *is* `earliestStartOffsetMinutes` (180) — **do not ask for the working-day start; you don't need it.**
-- **Breaks given as clock times but there is more than one** (e.g. "15 minutes at 10:00 and 30 minutes at 12:00") → you must use the **offset** shape, which means **converting each clock time into an offset from the start of the working day**. You cannot do that without knowing when the day starts, so **ask the user for the shift / working-day start**, then compute `earliestStartOffsetMinutes = (break start clock − day start)` in minutes for each break. Never assume the day starts at midnight (that would turn "10:00" into a wrong 600-minute offset). *(Only ask for the day start in this clock-time case — never when the break is already expressed as an offset.)*
-
-**Always emit `latestEndOffsetMinutes` for every offset break — ask for it directly, do not fabricate a window.** The earliest start comes from what the user stated (an offset, or a converted clock time) — **do not invent ± tolerance windows around it** (no "±1 hour" / "±2 hour" options). If the user only gave a break start (or a duration with no stated finish-by), **ask them plainly for the latest the break may end**, phrased in the *same terms they used*: if they gave an offset ("starts 3 hours after start of day"), ask "what is the latest it may end, as time after the start of the day?" and convert (e.g. "4 hours after start" → 240); if they gave a clock time, ask for a clock time and convert with the day start. If the user says the break is fixed/pinned with no flex, set `latestEndOffsetMinutes = earliestStartOffsetMinutes + durationMinutes`. Never emit an offset break missing any of the three fields, and never guess the latest-end. If a break requirement is too involved to convert reliably, ask clarifying questions or recommend the manual approach rather than guessing.
-
-**Maximum Travel from Home — establish the cap type, not the unit (rule 9).** When a requirement caps how far a resource may travel from home, **ask the user whether the cap is by distance or by travel time** — the two are configured differently and the data-layer skill needs to know which. Emit the value and the type in `params`: `{ "maxTravelFromHome": 50, "maxTravelFromHomeType": "Distance" | "Travel Time" }`. Interpret the user's phrasing to set the *type* — "50 miles"/"50 km" ⇒ `Distance`, "45 minutes" ⇒ `Travel Time` — but **do not ask for or emit a distance unit (miles vs km): it is not part of the work-rule config**; the unit is governed by the org's locale/distance settings elsewhere, so the rule stores only the number. For `Travel Time` the value is minutes. Never emit the cap value without its type.
-
----
-
 ## Relevance Groups
 
 A relevance group scopes a single work rule or service objective so it applies only to certain appointments or resources, instead of the whole policy. This lets one policy hold different logic for different work or resource types — e.g., different break/travel limits for part-time vs. full-time employees, or expedited scheduling for high-value accounts.
@@ -299,16 +286,3 @@ When the user confirms the work rules, delegate to `sfs-service-objective-design
 Do not start the service objective interview here. Transition message:
 
 > "Work rules are locked in. Next: service objectives — the scoring criteria that rank the eligible candidates. I'll walk through the trade-off questions one at a time."
-
-<!-- skill-validate: ignore-start -->
-<!-- codey:operations start -->
-## Operations Reference
-
-Operations this skill uses — routing and dependency reference.
-
-| Operation | Purpose | Status | Call | Depends on |
-|-----------|---------|--------|------|------------|
-| `emit-work-rules-block` | write | — | — | — |
-| `handoff-to-service-objective-designer` | delegate | — | → `sfs-setup-experience/sfs-service-objective-designer` | `emit-work-rules-block` |
-<!-- codey:operations end -->
-<!-- skill-validate: ignore-end -->

package/skills/platform-role-hierarchy-apply/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: platform-role-hierarchy-apply
+description: "Bulk-realign an existing Salesforce UserRole hierarchy from an external org-chart artifact (PDF, xlsx, or plain-text list of role-and-parent pairs) in one admin-approved manifest. Clarify scope and whether users move with roles, resolve identities that do not match verbatim, diff the artifact against the current tree, and submit create, rename, reparent, empty-role delete, and user-assignment mutations together. Triggers on \"reorganize the role hierarchy\", \"apply this org chart to roles\", \"bulk update role parents\", \"realign roles from PDF\", \"restructure the role hierarchy\", \"reparent roles from this spreadsheet\". Do not trigger for a single role create, rename, or reparent with no other changes, or for asking which roles exist or how they are nested — that is `managing-roles`. Do not trigger for territory, account, or forecast hierarchies, or for authoring sharing rules."
+metadata:
+  version: "1.0"
+---
+
+# Role Hierarchy Restructure
+
+Apply many UserRole changes from an artifact in one admin-approved manifest.
+
+If the admin only asks which roles exist or how they are nested, hand off to `managing-roles`. Do not query, do not ask the step 0 questions, and do not submit.
+
+## Inputs
+
+- PDF org chart (text-selectable), `.xlsx` / `.csv` with `role_name` and `parent_role_name` (empty parent = top-level), or plain text with one `Role: Parent` pair per line.
+- Or a pre-parsed list of `{roleName, parentRoleName}` objects.
+- Optional mapping hints when a chart name is not the org's `Name` or `DeveloperName`.
+
+## Flow
+
+### 0. Clarify before querying
+
+Ask anything still unresolved. Do not guess.
+
+- **Scope.** Default is selected branches: roles absent from the artifact stay. "Full hierarchy" still does not delete those roles unless the admin asked for each deletion.
+- **User reassignment.** Default is no. Do not emit `AssignUser` or `MoveUser` without an explicit yes.
+- **Ambiguous identities.** Resolve every role and user in one batch. See step 2.
+- **Conflicts.** Two parents for one role, or a role parented to itself: stop until the admin picks.
+
+If the artifact matches fewer than 20% of its roles to the current tree, stop and ask whether it is a greenfield replacement, the wrong file, or a mapping problem. Do not build a manifest until the admin confirms a greenfield replacement. Between 20% and 50%, show the fraction in the preview and continue.
+
+### 1. Read the current hierarchy
+
+```text
+SELECT Id, DeveloperName, Name, ParentRoleId
+FROM   UserRole
+LIMIT  10000
+```
+
+Match artifact roles by `DeveloperName`, then case-insensitive `Name`.
+
+### 2. Parse the artifact and resolve identities
+
+Normalize to `{roleName, parentRoleName, users?}` and show that list to the admin before the diff. A PDF that is not text-selectable cannot be parsed. Ask for a plain-text `Role: Parent` list.
+
+Roles: exact `DeveloperName`, then case-insensitive `Name`. No fuzzy match. When more than one role matches, list each candidate's `DeveloperName` and `Id` and wait. Do not pick one. Unresolved names go back to step 0.
+
+Users, only after reassignment was confirmed:
+
+1. 18-character id starting with `005` → `User.Id`
+2. Email → `User.Email`
+3. Username → `User.Username`
+4. Display name → `User.Name`, and only when exactly one active user matches
+
+`IsActive = false` is a non-match. A user listed under two roles is a conflict. Ask which role that user should land under, or whether to drop the reassignment. Do not submit until the admin answers.
+
+Stop on a cycle in the target graph. Report the path, for example `A → B → C → A`, and ask for a corrected artifact. Do not submit.
+
+### 3. Build the manifest
+
+Each mutation has `operationId`, `operationType`, `dependsOnOperationIds`, and one nested payload. `dependsOnOperationIds` is the order that matters.
+
+| operationType | Nested object | Use when |
+|---|---|---|
+| `CreateRole` | `createRole` | Role is in the artifact and not in the org. Set `roleReference`, `developerName`, `name`, and `parentRoleId` or `parentRoleReference`. Default the three account-owner access fields to the org defaults when the artifact omits them. |
+| `ReparentRole` | `reparentRole` | Role exists and the parent differs. Set `targetRoleId` or `targetRoleReference`, `expectedParentRoleId`, and `desiredParentRoleId` or `desiredParentRoleReference`. |
+| `RenameRole` | `renameRole` | Same role, different label or developer name. Set the expected and desired name fields. |
+| `DeleteRole` | `deleteRole` | Admin asked to remove an empty role. Set `targetRoleId`, `expectedParentRoleId`, `expectedAssignedUserIds`, and `expectedDirectChildRoleIds`. |
+| `AssignUser` or `MoveUser` | `userRoleAssignment` | Reassignment was confirmed. Set `userId`, `expectedCurrentRoleId`, and `desiredRoleId` or `desiredRoleReference`. |
+
+`DeleteRole` applies only when the role has no direct children and no assigned users at the moment it runs. Reparent those children and move those users in earlier mutations, and put those `operationId`s in `dependsOnOperationIds`. The delete's expected user and child lists are then empty. If the admin declined reassignment, do not delete a role that still has users.
+
+A mutation that names a role neither in the org nor created in this manifest is `missing-parent`. Name the roles that point at it. Ask whether to add a `CreateRole` for it in this manifest, skip those rows, or abort. Do not submit with that parent missing.
+
+A cycle in `dependsOnOperationIds` blocks the submit. Give every new role a `roleReference` string and point parents and assignments at that string.
+
+### 4. Validate, then preview
+
+Block the submit when any of these remain: a cycle, a missing parent, a duplicate `developerName`, a dependency cycle, an `AssignUser` or `MoveUser` without the step 0 yes, a `DeleteRole` whose expected user or child lists are not empty, or overlap under 20% without a confirmed greenfield replacement.
+
+On a duplicate `developerName`, show both rows and wait until the admin picks one or renames one.
+
+Warn in the preview, and continue only after an explicit yes:
+
+- A changed role is referenced by `Territory2.UserRoleId` or a forecast hierarchy override.
+- A changed role has `PortalType != 'None'`.
+- A changed role has more than 500 users (`SELECT COUNT() FROM User WHERE UserRoleId = :id`).
+
+```text
+Restructure preview
+-------------------
+  ReparentRole : 42
+  CreateRole   :  3
+  RenameRole   :  1
+  DeleteRole   :  2
+  MoveUser     :  2
+
+  Territory / forecast references : 1
+  Portal roles                    : 0
+  Roles with more than 500 users  : 2
+
+Approve this restructure? [yes / no]
+```
+
+`yes` submits. Anything else does not. Roles left in the org and absent from the artifact stay in place.
+
+### 5. Submit
+
+```text
+POST /services/data/v{version}/sharing/role-hierarchy-restructure
+{
+  "operation": "Save",
+  "mutations": [
+    {
+      "operationId": "reparent-sales-vp",
+      "operationType": "ReparentRole",
+      "dependsOnOperationIds": [],
+      "reparentRole": {
+        "targetRoleId": "00E000000000001",
+        "expectedParentRoleId": "00E000000000002",
+        "desiredParentRoleReference": "cro"
+      }
+    },
+    {
+      "operationId": "delete-legacy-region",
+      "operationType": "DeleteRole",
+      "dependsOnOperationIds": ["reparent-legacy-children"],
+      "deleteRole": {
+        "targetRoleId": "00E000000000003",
+        "expectedParentRoleId": "00E000000000002",
+        "expectedAssignedUserIds": [],
+        "expectedDirectChildRoleIds": []
+      }
+    }
+  ]
+}
+```
+
+`CreateRole`, `RenameRole`, `AssignUser`, and `MoveUser` use the same envelope with their nested object from step 3.
+
+Send the approved manifest once. Do not edit `UserRole` records one by one.
+
+### 6. Read the response
+
+- `Applied` — structural and sharing changes committed.
+- `AppliedSharingPending` — hierarchy is live; sharing catches up on its own. Do not poll.
+- `AsyncExecutionRequired` — the server queued the manifest. Do not poll.
+- `RoleOperationInProgress` — another restructure is running. Stop. Do not queue the manifest. Ask the admin to retry once the other operation finishes.
+- `NotApplied` — nothing committed. Show `reasonCodes` and stop.
+- `404` on submit — API not enabled for this client tier. Halt, tell the admin, do not retry, do not fall back to per-record `/sobjects/UserRole` edits.
+
+For each `operationResults[]` entry, `outcome` is `Applied`, `NotApplied`, or `DependencyNotApplied`. Show `reasonCode` for any entry that is not `Applied`. Do not retry and do not roll back.
+
+## Out of scope
+
+- A single role create, rename, or reparent with no other changes, and any request that only asks which roles exist or how they are nested (`managing-roles`).
+- Territory, account, and forecast hierarchies.
+- Authoring sharing rules.
+- Image-only PDFs. Ask for text.
+- Rollback. Report what the response says was committed.
+---
+
+<!-- skill-validate: ignore-start -->
+<!-- codey:operations start -->
+## Operations Reference
+
+Operations this skill uses — routing and dependency reference.
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `read-role-hierarchy` | read | — | `GET /services/data/v68.0/query` | — |
+| `count-users-per-role` | read | — | `GET /services/data/v68.0/query` | `read-role-hierarchy` |
+| `submit-role-hierarchy-restructure` | write | — | `POST /services/data/v68.0/sharing/role-hierarchy-restructure` | `read-role-hierarchy` |
+| `verify-role-hierarchy-restructure` | verify | — | `GET /services/data/v68.0/query` | `submit-role-hierarchy-restructure` |
+<!-- codey:operations end -->
+<!-- skill-validate: ignore-end -->