@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/consumer-goods-promotion-bo-api-deploy/SKILL.md

@@ -12,9 +12,7 @@ metadata:
       semver: ">=20.17.0"
     - tool: ["sf"]
       semver: ">=2.0.0"
-  accessCheck:
-    - type: license
-      value: "CGCRetailAndTPMMgmtPsl"
+  accessCheck: "License.CGCRetailAndTPMMgmtPsl"
 ---
 
 # Deploy the Promotion BO API
@@ -32,16 +30,13 @@ three REST endpoints:
 - `POST /services/apexrest/<prefix>/promotions/ingest`
 - `GET  /services/apexrest/<prefix>/promotions/status?importId=...`
 
-It is meant for **headless delivery**: point it at an org, answer the interview,
-and the skill installs the step and verifies it. The Promotion BO API ships in
-the CGCloud **managed package** (namespace `cgcloud` released, `cgcloud_dev`
-dev/beta). Every Apex identifier, object/field API name, and REST URL is derived
-from the detected package prefix at runtime — this skill never hard-codes it.
+It is meant for **headless delivery**: point it at an org, answer the interview, the skill installs and verifies the step. The Promotion BO API ships in the CGCloud **managed package** (`cgcloud` released, `cgcloud_dev` dev/beta). Every Apex identifier, object/field API name, and REST URL is derived from the detected package prefix at runtime.
 
 `derive` is out of scope here (a follow-up skill covers it). Detailed runbooks
 for the write and smoke phases live under `references/`:
 
-- `references/conventions-and-payload-rules.md` — sales-org partitioning, schema-first contract derivation, and the eight cross-workflow payload rules R1–R8.
+- `references/preflight-and-seed-queries.md` — Phase 1/2/3 SOQL (TPM entitlement, permset gate, framework-state verification, static-resource retrieve recipe, batch-chain polling).
+- `references/conventions-and-payload-rules.md` — sales-org partitioning, schema-first contract derivation, and the nine cross-workflow payload rules R1–R9.
 - `references/generate-and-wire.md` — Phase 5a (generate + deploy the class) and Phase 5b (register + wire the step), with the full `register-step.apex`.
 - `references/smoke-and-verify.md` — Phase 6 (contract derivation, payload materialization, create/update/copy legs + verification).
 - `references/reference-example-set-comment-value.md` — the shipped `SetCommentValue` preset (assets at `assets/set-comment-value/`).
@@ -83,50 +78,19 @@ Every Apex call is `${PREFIX_DOT}ClassName.method(...)`; every SOQL object/field
 Run these and stop on the first failure.
 
 1. `sf --version`; `node --version` (only if running shipped scripts).
-2. `sf org display --target-org <alias> --json` — confirm reachable, capture `instanceUrl` + org id (for display/logging only). Every REST call in later phases goes through `sf api request rest`, which uses the CLI's stored session — this skill never extracts the access token.
-3. Validate the sales org locally: length 4, uppercase, non-blank (mirrors `TPMSetupData.validateSalesOrg`). Fail fast instead of surfacing an Apex stack trace.
-4. **TPM entitlement (Permission Set License)** — the TPM app is licensed through the **`CGCRetailAndTPMMgmtPsl`** Permission Set License ("CGC Retail and Trade Promotion Management"); there is **no** `TPM App` UserLicense. Check the running user's PSL assignment:
-   ```sql
-   SELECT Id FROM PermissionSetLicenseAssign
-    WHERE Assignee.Username = '<running-user-name>'
-      AND PermissionSetLicense.DeveloperName = 'CGCRetailAndTPMMgmtPsl'
-   ```
-   On scratch/dev-hub the PSL may be legitimately unassigned; detect env with `SELECT OrganizationType, IsSandbox FROM Organization`:
-   - `OrganizationType = 'Developer Edition'` OR `IsSandbox = true` and empty → **warn** ("permset gate below is the real check"), continue.
-   - Any other org shape and empty → **stop** ("TPM Permission Set License `CGCRetailAndTPMMgmtPsl` not assigned to the running user").
-5. **Running-user permission set (TPM Admin persona)** — the setup needs a permission set granting the *TPM Master Data Admin* persona. The shipped permset is `TPM_Master_Data_Admin` (packaged; `PermissionSet.Name` is the bare name regardless of namespace), but **customers frequently clone it** under their own name — so treat a miss as "ask", not "fail". Take `<running-user-name>` from `sf org display ... .result.username`:
-   ```sql
-   SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment
-    WHERE Assignee.Username = '<running-user-name>'
-      AND (PermissionSet.Name = 'TPM_Master_Data_Admin'
-           OR PermissionSet.Label LIKE '%TPM%Master Data Admin%')
-   ```
-   Match → proceed. No match → **do not hard-fail on the name**: show `sf org assign permset --name TPM_Master_Data_Admin --target-org <alias>` as the default option, but also ask the user to confirm whether they already hold an equivalent (possibly cloned/renamed) permission set for the TPM admin persona. Pause, wait for a cloned-permset confirmation or the assignment, then re-query. Proceed only once admin access is confirmed.
+2. `sf org display --target-org <alias> --json` — confirm reachable; capture `instanceUrl` + org id (display/logging only). REST calls use `sf api request rest` on the CLI's stored session — the skill never extracts the access token.
+3. Validate sales org locally: length 4, uppercase, non-blank (mirrors `TPMSetupData.validateSalesOrg`). Fail fast.
+4. **TPM entitlement (Permission Set License)** — the `CGCRetailAndTPMMgmtPsl` PSL assignment on the running user. SOQL + warn/stop routing in `references/preflight-and-seed-queries.md` Step 4.
+5. **Running-user permission set (TPM Admin persona)** — the running user must hold `TPM_Master_Data_Admin` (or a clone matching `%TPM%Master Data Admin%`); if missing, offer `sf org assign permset --name TPM_Master_Data_Admin --target-org <alias>` and wait. SOQL in `references/preflight-and-seed-queries.md` Step 5. Proceed only once admin access is confirmed.
 6. Namespace discovery (above).
+7. **Running user's `${PREFIX_UNDER}Sales_Org__c` equals `<salesOrg>`.** Blank throws `SOU0003`; mismatch surfaces as "not found" (create/update) or `TransformationError` (copy). SOQL in `references/preflight-and-seed-queries.md` Step 7. Blank or `!= '<salesOrg>'` → stop; fix on the user record only. See `references/conventions-and-payload-rules.md` R6; category access is preflighted in Phase 6 per R9.
 
 ## Phase 2 — Verify BO API framework state
 
-Read-only; tells you whether Phase 3 needs to run. All three counts MUST be
-scoped to `<salesOrg>` — the framework rows are sales-org-partitioned.
-
-```bash
-# 1. Workflow rows for this sales org (expect 4: create/update/copy/derive)
-sf data query --target-org <alias> --json --query "
-  SELECT Name FROM ${PREFIX_UNDER}BO_API_Workflow__c
-   WHERE ${PREFIX_UNDER}BO_API__r.Name = 'Promotion'
-     AND ${PREFIX_UNDER}BO_API__r.${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
-
-# 2. Step rows for this sales org
-sf data query --target-org <alias> --json --query "
-  SELECT COUNT(Id) FROM ${PREFIX_UNDER}BO_API_Workflow_Step__c
-   WHERE ${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
-
-# 3. Junction rows whose parent workflow belongs to a Promotion BO API for this sales org
-sf data query --target-org <alias> --json --query "
-  SELECT COUNT(Id) FROM ${PREFIX_UNDER}BO_API_Workflow_Workflow_Step__c
-   WHERE ${PREFIX_UNDER}BO_API_Workflow__r.${PREFIX_UNDER}BO_API__r.Name = 'Promotion'
-     AND ${PREFIX_UNDER}BO_API_Workflow__r.${PREFIX_UNDER}BO_API__r.${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
-```
+Read-only; tells you whether Phase 3 needs to run. Run the three
+sales-org-scoped SOQL queries in `references/preflight-and-seed-queries.md`
+("Phase 2 — Verify BO API framework state"): workflow rows, step row count,
+junction row count — all scoped to `<salesOrg>`.
 
 - Zero workflow rows → fresh for this sales org, Phase 3 will seed.
 - Full state (4 workflow rows `create/update/copy/derive`; >0 step + junction rows) → Phase 3 is a no-op for this sales org (still run for idempotency; 3a shows zero net-new).
@@ -138,27 +102,10 @@ The workflows/steps/junctions/entities/input-structures ship as CSVs inside the
 packaged `TPMSetupData` static resource; `TPMSetupData.setupBOApi` reads and
 upserts them. Before running it, show the user what will land.
 
-1. Locate the resource:
-   ```bash
-   sf data query --target-org <alias> --json --query "
-     SELECT Id, Name, NamespacePrefix, SystemModStamp, BodyLength
-       FROM StaticResource WHERE Name = 'TPMSetupData'"
-   ```
-   Zero rows → stop ("TPMSetupData static resource not found — is the CGCloud package installed?"). Multiple rows → prefer the one whose `NamespacePrefix` matches Phase 1; if prefixes disagree, stop and ask.
-2. **Retrieve + expand the resource cross-platform via SFDX** — use `sf project retrieve`, which unpacks a zip StaticResource into a folder on every OS (no `curl`, no `unzip` — `unzip` isn't present on Windows by default). Retrieve into a **dedicated `setup-data/` subproject** so the read-only managed resource never mixes into the Phase-5a deploy tree (`./.promotion-bo-api-deploy/force-app`, which is what gets deployed back):
-   ```bash
-   mkdir -p ./.promotion-bo-api-deploy/setup-data/force-app/main/default
-   printf '{ "packageDirectories": [{ "path": "force-app", "default": true }], "sourceApiVersion": "60.0" }' \
-     > ./.promotion-bo-api-deploy/setup-data/sfdx-project.json
-   ( cd ./.promotion-bo-api-deploy/setup-data && sf project retrieve start \
-       --metadata "StaticResource:${PREFIX_UNDER}TPMSetupData" --target-org <alias> --json )
-   ```
-   Non-success → stop, print `result` errors.
-3. SFDX expands the zip to `./.promotion-bo-api-deploy/setup-data/force-app/main/default/staticresources/${PREFIX_UNDER}TPMSetupData/BOApi/`. `ls` it. Expected: `0_BO_API__c.csv`, `0_BO_API_Entity__c.csv`, `0_BO_API_Output_Entity__c.csv`, `0_BO_API_Workflow__c.csv`, `0_BO_API_Workflow_Entity__c.csv`, `0_BO_API_Workflow_Step__c.csv`, `0_BO_API_Workflow_Workflow_Step__c.csv`, `0_BO_API_Step_Input_Structure__c.csv`, `import.json`. Any missing → stop, print the delta.
-4. Confirm each target sObject exists: `sf sobject describe --sobject '${PREFIX_UNDER}BO_API_Workflow__c' --target-org <alias> > /dev/null` (etc.). Any describe failure → stop (package partially installed).
-5. Show a summary (row counts per object; total ~232 rows across 8 objects; "upsert on Unique_Key__c — re-running is idempotent"), plus the first 3 rows of `0_BO_API_Workflow__c.csv` and `0_BO_API_Workflow_Step__c.csv` with `{{NS}}`/`{{SALES_ORG}}` substituted.
-6. Wait for confirmation unless `--yes`. "no"/blank → abort clean, point at `./.promotion-bo-api-deploy/setup-data/force-app/main/default/staticresources/${PREFIX_UNDER}TPMSetupData/BOApi/`.
-7. On `--dry-run` → stop here; do not run 3b.
+1. Locate + retrieve the `TPMSetupData` static resource into a dedicated `setup-data/` subproject (keeps the read-only managed resource out of the Phase-5a deploy tree at `./.promotion-bo-api-deploy/force-app`), then confirm each target sObject exists. SOQL + the full retrieve recipe + 8-CSV manifest + describe loop are in `references/preflight-and-seed-queries.md` ("Phase 3a — Retrieve the packaged seed"). Any step failing → stop with the printed delta/error.
+2. Show row counts per object (total ~232 rows across 8 objects; "upsert on `Unique_Key__c` — idempotent") + first 3 rows of `0_BO_API_Workflow__c.csv` and `0_BO_API_Workflow_Step__c.csv` with `{{NS}}`/`{{SALES_ORG}}` substituted.
+3. Wait for confirmation unless `--yes`. "no"/blank → abort clean, point at the retrieved BOApi/ directory.
+4. On `--dry-run` → stop here; do not run 3b.
 
 ## Phase 3b — Apply the default seed
 
@@ -166,17 +113,8 @@ Only after 3a confirmation.
 
 1. `PHASE3_START=$(date -u +%FT%TZ)`.
 2. Run metadata-wizard setup via anon Apex: `${PREFIX_DOT}TPMSetupData.setupMetadataWizard('<salesOrg>');` → `sf apex run --target-org <alias> --file ./.promotion-bo-api-deploy/setup-metadata-wizard.apex`.
-3. Wait for the whole batch chain. `GenericDemoSetupDataBatch` self-chains via `finish()`; polling a single job id misses children. Poll by class:
-   ```bash
-   sf data query --target-org <alias> --json --query "
-     SELECT COUNT() FROM AsyncApexJob
-      WHERE ApexClass.Name = 'GenericDemoSetupDataBatch'
-        AND CreatedDate >= ${PHASE3_START}
-        AND Status NOT IN ('Completed','Failed','Aborted')"
-   ```
-   Sleep 5s between polls; break when count is zero for **two consecutive** polls (covers the gap between a parent's `finish()` and the child's `AsyncApexJob` row appearing).
-4. Final check — every child succeeded (`SELECT Id, Status, NumberOfErrors, ExtendedStatus FROM AsyncApexJob WHERE ApexClass.Name = 'GenericDemoSetupDataBatch' AND CreatedDate >= ${PHASE3_START}`). Any `Failed`/`Aborted`/`NumberOfErrors > 0` → stop, print `ExtendedStatus`.
-5. Repeat 2–4 for `${PREFIX_DOT}TPMSetupData.setupBOApi('<salesOrg>');`.
+3. Wait for the batch chain. `GenericDemoSetupDataBatch` self-chains via `finish()`, so poll by class with the two-consecutive-zero break pattern + run the final `NumberOfErrors`/`ExtendedStatus` check. SOQL in `references/preflight-and-seed-queries.md` ("Phase 3b — Poll the batch chain"). Any `Failed`/`Aborted`/`NumberOfErrors > 0` → stop.
+4. Repeat 2–3 for `${PREFIX_DOT}TPMSetupData.setupBOApi('<salesOrg>');`.
 
 ## Phase 4 — Verify the BO API framework is on
 
@@ -189,17 +127,16 @@ component failed.
 ## Phase 5 — Interview: what does the user want to customize?
 
 The framework is now on. The customization is **user-supplied** — do not skip
-the interview; do not invent an answer. Print:
+the interview or invent an answer. Print:
 
 ```text
 The Promotion BO API framework is installed. To add a custom step, tell me:
-  - Which BO API entity does it target? (e.g. Promotion or Tactic — I'll list the exact entities registered in your org)
+  - Which BO API entity does it target? (e.g. Promotion/Tactic — I'll list registered entities)
   - Which workflows should it fire in? (create, update, copy)
   - What does it read from the ingest input?
   - What does it write on the SObject or elsewhere?
-  - Any preconditions or side effects I should know about?
-If you want a worked example, say "use the SetCommentValue reference" —
-it copies the tactic input Comment onto Tactic.Comment__c.
+  - Any preconditions or side effects?
+Say "use the SetCommentValue reference" for a worked example.
 ```
 
 ### 5.1 — Answers to collect
@@ -207,11 +144,12 @@ it copies the tactic input Comment onto Tactic.Comment__c.
 | Field | Required | Notes |
 |---|---|---|
 | `stepName` | yes | PascalCase Apex class name + BO API Workflow Step `Name`. Unique across `ApexClass`. |
-| `entity` | yes | BO API entity `Name` — MUST match a row queried live from `${PREFIX_UNDER}BO_API_Entity__c` (shared, not sales-org-partitioned); do not assume a fixed list. In a current org these include `Promotion`, `Tactic`, `ProductFilter`, `ManualInputs`, `CustomState` (plus the `TPM_Promotion.*` structures). Query the org and offer the actual rows. |
+| `entity` | yes | BO API entity `Name` — MUST match a row queried live from `${PREFIX_UNDER}BO_API_Entity__c` (shared, not sales-org-partitioned). Typical rows include `Promotion`, `Tactic`, `ProductFilter`, `ManualInputs`, `CustomState`. Query the org — don't assume a fixed list. |
 | `workflows` | yes | Non-empty subset of `{create, update, copy}`. `derive` is out of scope. |
 | `actionName` | yes | Symbolic action string the class receives in `call(String action, ...)`. Convention: lowerCamelCase of `stepName`. |
 | `inputPaths` | yes (≥1) | JSON paths to read from `currentInput`, e.g. `["Comment"]`. |
 | `inputPathType` | yes | JSON type of the input paths — `String`, `Array`, `Boolean`, `Number`, `Object`. Drives the `RecordType` on each SIS row; a wrong value causes `TransformationError: Expected <Type>` at ingest. Different types → run Phase 5b once per type group. |
+| `inputPathRequired` | optional | Whether `inputPaths` must appear on the ingest payload. Defaults to `false`. Drives `BO_API_Step_Input_Structure__c.Required__c` (platform default is `true` — skill always writes explicitly). See `references/generate-and-wire.md`. |
 | `outputWrites` | yes (≥1) | `{field, source}` pairs; `field` is the target API name **without** the namespace prefix (skill adds `${PREFIX_UNDER}`), `source` references an `inputPaths` value / literal / computed expression. |
 | `description` | yes | One-sentence step description → `${PREFIX_UNDER}Description__c` + class docstring. |
 | `preconditions` | optional | Free-text guards before writing. |
@@ -219,33 +157,38 @@ it copies the tactic input Comment onto Tactic.Comment__c.
 
 ### 5.2 — Interview flow
 
-1. **Preset shortcut.** If `--preset set-comment-value` or the user says "use the SetCommentValue reference", load the answers from `references/reference-example-set-comment-value.md` (`assets/set-comment-value/interview-answers.json`) and skip the interactive interview. `--interview-file <path>` loads answers from a JSON file mirroring the 5.1 table (wins over `--preset`).
-2. **Ask the questions** one at a time (or as a block); do not proceed until every required field has a concrete value.
+1. **Preset shortcut.** `--preset set-comment-value` (or "use the SetCommentValue reference") loads answers from `references/reference-example-set-comment-value.md` (`assets/set-comment-value/interview-answers.json`) and skips the interactive interview. `--interview-file <path>` loads a JSON mirroring the 5.1 table (wins over `--preset`).
+2. **Ask the questions** one at a time (or as a block); do not proceed until every required field has a value.
 3. **Show the entity's writeable fields** after the user names the entity:
    ```bash
    sf sobject describe --target-org <alias> --sobject '${PREFIX_UNDER}<Entity>__c' --json \
      | jq -r '.fields[] | select(.updateable == true and .createable == true) | .name'
    ```
    Any `outputWrites` field must appear here; otherwise stop and ask for a different one (FLS is caller-scoped).
-4. **Confirm the plan** (recap Class/Entity/Workflows/Reads/Writes/Sort/Description → "Deploy + wire? [y/N]"). `n`/blank → save answers to `./.promotion-bo-api-deploy/interview.json` and exit. `y` → Phase 5a.
+4. **Confirm the plan** (recap Class/Entity/Workflows/Reads/Writes/Sort/Description → "Deploy + wire? [y/N]"). If `workflows` includes `copy`, flag that per-child input values come from the source promotion — `outputWrites` still fires but `<inputPaths>` values are ignored (only top-level fields like `Slogan` propagate). `n`/blank → save answers to `./.promotion-bo-api-deploy/interview.json` and exit. `y` → Phase 5a.
 
 ## Phases 5a / 5b — Generate + deploy, register + wire
 
-Runbook in `references/generate-and-wire.md`. In short: guard the class name for
-idempotency; confirm target-field writeability; generate a namespace-agnostic
-`Callable` from the interview (reads `currentInput`/`currentOutput`, derives the
-prefix from `getSObjectType()` at runtime); show + confirm; `sf project deploy
-start`. Then, in one anon-Apex transaction, upsert one `BO_API_Workflow_Step__c`
-(bare class name in `Classname__c`), one `BO_API_Workflow_Workflow_Step__c`
-junction per chosen workflow (never assume all three; `derive` dropped), and the
-`BO_API_Step_Input_Structure__c` rows (RecordType per `inputPathType`). Both
+Runbook in `references/generate-and-wire.md`. In short: guard the class name
+for idempotency; confirm target-field writeability; clean any stale
+`.cls`/`.cls-meta.xml` from
+`./.promotion-bo-api-deploy/force-app/main/default/classes/` (leftovers cause a
+silent MDAPI full-batch rollback); generate a namespace-agnostic `Callable`
+from the interview — class **and** `call` method must be `global` (packaged
+`CallableManager` resolves via `Type.forName` across the namespace boundary;
+`public` fails at runtime on managed installs — see runbook); show + confirm;
+`sf project deploy start`. Then, in one anon-Apex transaction, upsert one
+`BO_API_Workflow_Step__c` (bare class name in `Classname__c`), one
+`BO_API_Workflow_Workflow_Step__c` junction per chosen workflow (`derive`
+dropped), and the `BO_API_Step_Input_Structure__c` rows (RecordType per
+`inputPathType`, `Required__c` set explicitly from `inputPathRequired`). Both
 upserts key on `Unique_Key__c` (idempotent).
 
 ## Phase 6 — Smoke test through the REST endpoints
 
 Runbook in `references/smoke-and-verify.md`. Derive the payload contract per
 invoked workflow from `BO_API_Step_Input_Structure__c` (schema-first), apply
-rules R1–R8 from `references/conventions-and-payload-rules.md`, resolve every
+rules R1–R9 from `references/conventions-and-payload-rules.md`, resolve every
 reference in-sales-org, materialize `./out/smoke/{create,update,copy}.json`, then
 run `initialize → ingest → poll status` for each chosen workflow. Verify via a
 direct `BO_API_Transaction_Log__c` query (any row `!= 'Calculated'` → fail) plus
@@ -254,12 +197,11 @@ copy legs run only if the interview included them.
 
 ## Phase 7 — Report
 
-Short status: org, sales org, dry-run flag; namespace prefix; BO API seed rows
-before/after (Phases 2 & 4); interview (preset name or resolved `stepName`,
-`entity`, `workflows`, `inputPaths`, `outputWrites`); class deploy result +
-workflow-step id + junction ids (1–3); smoke import ids per invoked workflow, all
-`Calculated` with matching write assertions — or exactly which failed (SOQL,
-expected, actual); manual follow-ups (`none` if clean).
+Short status: org, sales org, dry-run flag; namespace prefix; seed rows
+before/after (Phases 2 & 4); interview summary; deploy result + workflow-step
+id + junction ids; smoke import ids per invoked workflow — all `Calculated`
+with matching assertions, or exactly which failed (SOQL, expected, actual);
+manual follow-ups (`none` if clean).
 
 ## Rules
 
@@ -269,7 +211,12 @@ expected, actual); manual follow-ups (`none` if clean).
 - Never hard-code the namespace prefix — compose every Apex/SOQL/REST reference from the Phase-1 detection.
 - Never invent Apex method signatures — use what the packaged `TPMSetupData` / `BO_API_*` objects and the shipping REST endpoints declare.
 - The seeded BO API metadata is packaged content — preview it and get user confirmation before invoking `TPMSetupData.setupBOApi`.
-- Never invent an interview answer. Absent a user and any `--preset`/`--interview-file`, stop and print the questions.
-- Never wire a workflow the interview did not include. `create`/`update`/`copy` are individually opt-in; `derive` is always excluded.
+- Never invent an interview answer. Absent a user and `--preset`/`--interview-file`, stop and print the questions.
+- Never wire a workflow the interview did not include. `create`/`update`/`copy` are opt-in; `derive` is always excluded.
 - Never compose a smoke payload from a hard-coded template — derive accepted paths per workflow from `BO_API_Step_Input_Structure__c` and validate user input against that contract first.
 - Never resolve a reference value without the sales-org filter. A record under a different sales org is not valid for this invocation.
+- Never generate a `Callable` step class with `public` visibility — declare the class and the `call` method `global`. `public` works only on same-namespace dev orgs and fails on managed installs with `Type "<stepName>" does not exist`; the transaction log shows a generic `Error`. See `references/generate-and-wire.md`.
+- Never re-use `./.promotion-bo-api-deploy/force-app/main/default/classes/` across step deploys — remove the prior step's `.cls`/`.cls-meta.xml` first. A stale file triggers a silent MDAPI full-batch rollback while the CLI still reports `"created": true`.
+- Never insert a `BO_API_Step_Input_Structure__c` row without setting `Required__c` explicitly. The platform defaults it to `true`; the skill defaults `false` and only opts in when `inputPathRequired` is set. Omitting the field silently makes every optional path mandatory.
+- Never proceed past Phase 1 without confirming the running user's `${PREFIX_UNDER}Sales_Org__c` equals `<salesOrg>` — blank throws `SOU0003`; mismatch surfaces as "not found" (create/update) or `TransformationError` (copy). Fix on the user record only. See `references/conventions-and-payload-rules.md` R6.
+- Never ingest a payload whose `ProductFilter.Criteria.<level>` references categories the running user lacks `Product_Category_Share__c` `Access_Level__c='ReadWrite'` on — Phase 6 preflight per `references/conventions-and-payload-rules.md` R9. Do not silently insert share rows.

package/skills/consumer-goods-promotion-bo-api-deploy/assets/set-comment-value/payloads/copy.json

@@ -4,7 +4,7 @@
   "salesOrg": "0001",
   "promotions": [
     {
-      "SourceId": "REPLACED-AT-RUNTIME-PROMOTION-ID"
+      "Id": "REPLACED-AT-RUNTIME-PROMOTION-ID"
     }
   ]
 }

package/skills/consumer-goods-promotion-bo-api-deploy/references/conventions-and-payload-rules.md

@@ -1,6 +1,6 @@
 # Conventions & payload rules (Promotion BO API)
 
-Load-bearing conventions and the eight cross-workflow payload rules the
+Load-bearing conventions and the nine cross-workflow payload rules the
 `BO_API_Step_Input_Structure__c` schema alone cannot express. The main
 `SKILL.md` references this file from Phase 5b (registering input paths) and
 Phase 6 (composing/validating smoke payloads).
@@ -33,8 +33,8 @@ subscriber orgs, or the dev-package prefix).
 | `PromotionTemplate` | `<prefix>__Promotion_Template__c` | `Name = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
 | `Tactics[*].TacticTemplate` | `<prefix>__Tactic_Template__c` | `Name = <val> AND <prefix>__Sales_Org__c = <sales-org>` (and linked to the chosen PromotionTemplate via `<prefix>__Promotion_Template_Tactic_Template__c`) |
 | `AnchorAccount` | `Account` | `<prefix>__ExternalId__c = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
-| `ProductFilter.Criteria.Brand[*]`, `.Category[*]`, `.Subcategory[*]`, `.Flavor[*]`, `.Package[*]` | `<prefix>__Product_Attribute__c` (or Category equivalents) | `Name = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
-| `ProductFilter.{Included,Excluded}Products[*]` | `Product2` | matched by external key AND `<prefix>__Sales_Org__c = <sales-org>` |
+| `ProductFilter.Criteria.Brand[*]`, `.Category[*]`, `.Subcategory[*]`, `.Flavor[*]`, `.Package[*]` | `<prefix>__Product_Attribute__c` (or Category equivalents) | `<prefix>__Consumer_Goods_External_Product_Id__c = <val> AND <prefix>__Sales_Org__c = <sales-org>` — resolve against external id, NOT `Name`/label (see R3b). |
+| `ProductFilter.{Included,Excluded}Products[*]` | `Product2` | `<prefix>__Consumer_Goods_External_Product_Id__c = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
 | `PromotionAccountSet` / `AnchorAccountSet` | `<prefix>__Account_Set__c` | `Name = <val> AND <prefix>__Sales_Org__c = <sales-org>` |
 
 Fail-fast — before any REST call — if any user-supplied reference does not
@@ -81,7 +81,7 @@ required columns).
 ## Promotion payload — cross-workflow rules the schema cannot express
 
 The `BO_API_Step_Input_Structure__c` contract declares WHICH keys the workflow
-accepts and which are `Required__c=true`, but eight additional constraints govern
+accepts and which are `Required__c=true`, but nine additional constraints govern
 whether a create/update/copy/derive call will actually succeed. Enforce them
 BEFORE the REST call — otherwise the request 202s, then dies asynchronously
 inside a workflow step with a `BO_API_Transaction_Log__c.Status__c = 'Error'`.
@@ -124,10 +124,45 @@ translate. Sending a Product2 field API name (e.g. `<prefix>__Criterion_1_Produc
 as a key fails schema validation with `"Properties other than those defined were
 not expected at #.ProductFilter.Criteria.<key>"`.
 
+Two placement/identifier constraints the schema alone cannot express:
+
+**R3a. `ProductFilter` is a top-level promotion field, NOT nested under `Tactics[]`.**
+Every entry in `promotions[]` may carry a `ProductFilter` sibling to
+`Slogan`/`DateFrom`/`Tactics`. Nesting the block under `Tactics[i]` is
+schema-valid at ingest but fails downstream with
+`"You must select at least one Category to the Promotion"` — the same error a
+missing block produces. Trial-and-error empirically discovers this;
+document once here so the skill never emits the wrong shape:
+
+```json
+"promotions": [{
+  "PromotionTemplate": "Customer Promotion",
+  "DateFrom": "2026-08-01",
+  "DateThru": "2026-08-31",
+  "Slogan": "...",
+  "ProductFilter": {
+    "Criteria": { "Category": ["<external-id>"] }
+  },
+  "Tactics": [ /* no ProductFilter here */ ]
+}]
+```
+
+**R3b. Criteria values are `<prefix>__Consumer_Goods_External_Product_Id__c` external ids, NOT `Name`/label.**
+Every value inside `ProductFilter.Criteria.<level>[]` is resolved against the
+category/attribute record's *external id* — the packaged
+`<prefix>__Consumer_Goods_External_Product_Id__c` field — NOT the display
+`Name` or label. Passing a Name (e.g. `"Chips (Canada Food)"`) yields
+`TransformationError: Could not find Products: <Name>` at ingest, and the
+misleading message suggests the underlying products are inactive when the real
+defect is the identifier field. The correct value for the same record is its
+external id (e.g. `Chips_Canada_Food`). Resolve every criteria value against
+external ids in the sales org before emitting the payload; if the user typed a
+Name, offer the external-id match(es) and ask to confirm.
+
 ```json
 "ProductFilter": {
   "Criteria": {
-    "Category": ["Snacks"],
+    "Category": ["Chips_Canada_Food"],
     "Brand":    ["YetiBar"]
   }
 }
@@ -216,6 +251,12 @@ then layer the Apex-only preconditions:
 **Copy:**
 - Schema-required: `.Id` (source promotion).
 - Apex-only: source promotion's template must have `Is_Copyable__c = true`; template `Promotion_Type__c` must equal `'Promotion'`; if template `Anchor_Type__c = 'Customer'`, `.AnchorAccount` must resolve in the sales org; if `'CustomerSet'`, `.AnchorAccountSet` must resolve.
+- Apex-only: **the running `User.Sales_Org__c` MUST equal the source PromotionTemplate's `Sales_Org__c`.** `Promotion2BoApiCoreCommon.loadPromotion` (invoked with `Operation.Copy`; the legacy shim `PromotionBoApiCopyCoreWorkflowSteps.loadPromotionBOForCopy2` delegates into the same method) throws `TransformationError: The User and the Promotion Template must have the same Sales org` when they differ, with no hint that the running user is the fix path. Create/update do not enforce this specific check, but they still resolve the operating sales org from the running user's `Sales_Org__c` via `SalesOrganizationUtil.getUserSalesOrganizationName` — a blank or mismatched value there fails every workflow, just less loudly (with `SOU0003` or misleading "not found" errors). SKILL.md Phase 1 step 7 gates the whole invocation on this match before any workflow runs; also verify at Phase 6 immediately before every ingest in case the user's `Sales_Org__c` drifted between phases. Zero-cost SOQL:
+  ```sql
+  SELECT Id, Username, ${PREFIX_UNDER}Sales_Org__c FROM User WHERE Username = '<running-user-name>' LIMIT 1
+  ```
+  If it does not match, do not silently mutate the user record — refuse and print the fix options.
+- **Copy ignores per-child input values on `Tactics[]`.** On `copy`, the framework sources per-child values from the source record's children — the payload's `Tactics[i].<field>` is accepted by the schema but has no effect on the cloned children. Custom step `outputWrites` still fire, but their input values come from the source child, not the copy payload. Only top-level promotion fields (e.g. `Slogan`) propagate from the copy payload. This is intentional and documented; the skill's confirm banner in SKILL.md Phase 5.5 must call this out so users do not expect a `create`-style customization to apply.
 
 **Derive:**
 - Schema-required: `.Id`, `.PromotionTemplate`, `.AnchorAccount` — all at the derive input root (`currentInput`), not nested (`PBACWS_REQUIRED_PROP_MISSING` fires against `Path__c` verbatim).
@@ -266,6 +307,42 @@ SELECT Id, Name, <prefix>__Promotion_Type__c
 Reject any row where `Promotion_Type__c != 'Promotion'` with:
 `"Promotion template <name> has Promotion_Type__c='<type>'; this workflow only supports templates with Promotion_Type__c='Promotion'. Sellable Promotions belong to the retail path."`
 
+### R9. Running user must hold `Product_Category_Share__c` ReadWrite on every referenced category
+
+`Promotion2BoApiCoreCommon.setPromotionAnchor` (invoked by every workflow that
+resolves a promotion anchor) calls `ProductCategoryShareService.getCategoryAccessBySalesOrgUserAnchorCategory`
+and hard-fails when the running user does not have a `<prefix>__Product_Category_Share__c`
+row with `<prefix>__Access_Level__c = 'ReadWrite'` for each category the payload
+references — either via the promotion template's anchor category, via
+`ProductFilter.Criteria.Category`, or via `Included/ExcludedProducts` whose
+category rolls up to a share-guarded category in the sales org. The error surfaces
+at ingest as `Access Denied` / `TransformationError: You do not have access to
+the category '<name>'` and does not identify the missing share row.
+
+Fail-fast before any REST call:
+
+`<userId>` comes from `sf org display --target-org <alias> --json` (`result.userId`); `<id1>`, `<id2>`, … are the category record ids resolved from the payload's criteria values in-sales-org.
+
+```sql
+SELECT <prefix>__Category__c, <prefix>__Access_Level__c
+  FROM <prefix>__Product_Category_Share__c
+ WHERE <prefix>__Sales_Org__c = '<salesOrg>'
+   AND <prefix>__User__c = '<userId>'
+   AND <prefix>__Category__c IN ('<id1>','<id2>')
+   AND <prefix>__Access_Level__c = 'ReadWrite'
+```
+
+`categoryIds` is the union of:
+1. The chosen `PromotionTemplate`'s `<prefix>__Anchor_Category__c` (if any).
+2. Every category external id in the payload's `ProductFilter.Criteria.Category`, resolved to `<prefix>__Product_Attribute__c.Id` (or the tenant's Category equivalent) in the sales org.
+
+Any missing row → stop and print:
+`"Running user <username> lacks ReadWrite Product_Category_Share on category <name> (<external-id>) in sales org <salesOrg>. Grant a Product_Category_Share__c row with Access_Level__c='ReadWrite', or re-run as a user who already has this access. Do not proceed."`
+
+Never silently insert share rows on behalf of the running user — that mutates
+sharing configuration invisibly and can leak read/write access to other
+categories via the same user in future runs.
+
 ## Wire-format quirks
 
 - `POST /promotions/initialize` deserializes lowercase `salesorg` / `nrofitems`. Always emit lowercase.

package/skills/consumer-goods-promotion-bo-api-deploy/references/generate-and-wire.md

@@ -50,6 +50,20 @@ Both phases run only on a green Phase 4 and a confirmed Phase 5 interview.
        <stepName>.cls-meta.xml
    ```
 
+   **Deploy-directory hygiene — clean stale `.cls` files before writing the new
+   step.** When the skill is invoked more than once against the same working
+   tree (a second custom step, an interview re-run), any prior step's `.cls` /
+   `.cls-meta.xml` left behind in `force-app/main/default/classes/` is picked
+   up by `sf project deploy start` in step 5 below. If that stale file is no
+   longer known to the source-tracking manifest, MDAPI evaluates the deploy
+   with `rollbackOnError: true` and rolls back the *entire* batch — including
+   the new class — while the CLI still surfaces `"created": true` for the
+   intended component. The user sees an apparent success; the class is not
+   actually in the org. Before writing the new step, delete every
+   `*.cls`/`*.cls-meta.xml` under `./.promotion-bo-api-deploy/force-app/main/default/classes/`
+   that is not the class about to be generated. Do NOT wipe `setup-data/`
+   (Phase 3a's retrieved read-only static resource lives there).
+
    `sfdx-project.json`:
    ```json
    {
@@ -188,6 +202,15 @@ for (String wf : workflows) {
 // pre-check. SIS uses RecordType to declare the JSON type (String, Array,
 // Boolean, Number, Object) — a missing RecordTypeId defaults to Array,
 // which produces "Expected List<Object>" at runtime.
+//
+// `Required__c` MUST be set explicitly. The field defaults to `true` at
+// the platform level, so omitting it silently promotes every optional
+// input path to mandatory org-wide for that workflow — every subsequent
+// ingest of a promotion that does not carry the path fails with
+// `Required property missing at #.<path>`. Default the SIS insert to
+// `false`; only set `true` for paths the interview explicitly flagged
+// as required (interview field `inputPathRequired`, defaults to `false`).
+Boolean inputPathRequired = <inputPathRequired>;  // interview answer; defaults to false
 Id sisRecordTypeId = [
   SELECT Id FROM RecordType
    WHERE SobjectType = '${PREFIX_UNDER}BO_API_Step_Input_Structure__c'
@@ -203,11 +226,21 @@ for (${PREFIX_DOT}BO_API_Step_Input_Structure__c s : [
 }
 List<${PREFIX_DOT}BO_API_Step_Input_Structure__c> sisRows =
   new List<${PREFIX_DOT}BO_API_Step_Input_Structure__c>();
+// `Path__c` carries a packaged validation rule requiring JSON-path form
+// (leading `.` or `$`). Interview values from the user typically omit the
+// leading dot (e.g. `Comment`); normalize before insert or the row rejects
+// with `FIELD_CUSTOM_VALIDATION_EXCEPTION: The Path must represent a
+// valid JSON path.: [${PREFIX_UNDER}Path__c]`. Existing-path comparison
+// also uses the normalized value so a re-run does not double-insert.
 for (String inputPath : inputPaths) {
-  if (existingPaths.contains(inputPath)) continue;
+  String normalizedPath = (inputPath.startsWith('.') || inputPath.startsWith('$'))
+    ? inputPath
+    : '.' + inputPath;
+  if (existingPaths.contains(normalizedPath)) continue;
   sisRows.add(new ${PREFIX_DOT}BO_API_Step_Input_Structure__c(
     ${PREFIX_DOT}BO_API_Workflow_Step__c = step.Id,
-    ${PREFIX_DOT}Path__c = inputPath,
+    ${PREFIX_DOT}Path__c = normalizedPath,
+    ${PREFIX_DOT}Required__c = inputPathRequired,
     RecordTypeId = sisRecordTypeId
   ));
 }

package/skills/consumer-goods-promotion-bo-api-deploy/references/preflight-and-seed-queries.md

@@ -0,0 +1,149 @@
+# Preflight + seed queries (Phases 1–3b)
+
+Load-bearing SOQL and shell recipes that `SKILL.md` Phases 1–3b hand off to.
+`PREFIX_DOT` / `PREFIX_UNDER` / `URL_NS` come from `SKILL.md` "Find the
+namespace first". Every query is **sales-org-scoped** where the underlying
+object is partitioned.
+
+## Phase 1 — Preflight queries
+
+### Step 4: TPM entitlement (Permission Set License)
+
+TPM is licensed via the `CGCRetailAndTPMMgmtPsl` PSL (no `TPM App`
+UserLicense):
+
+```sql
+SELECT Id FROM PermissionSetLicenseAssign
+ WHERE Assignee.Username = '<running-user-name>'
+   AND PermissionSetLicense.DeveloperName = 'CGCRetailAndTPMMgmtPsl'
+```
+
+Empty + `OrganizationType = 'Developer Edition'` or `IsSandbox = true` →
+**warn** (the permset gate below is the real check); any other org shape +
+empty → **stop**.
+
+### Step 5: Running-user permission set (TPM Admin persona)
+
+Need a permset granting the *TPM Master Data Admin* persona. The shipped name
+is `TPM_Master_Data_Admin` (bare, non-namespaced), but customers frequently
+clone it; treat a miss as "ask", not "fail":
+
+```sql
+SELECT PermissionSet.Name, PermissionSet.Label FROM PermissionSetAssignment
+ WHERE Assignee.Username = '<running-user-name>'
+   AND (PermissionSet.Name = 'TPM_Master_Data_Admin'
+        OR PermissionSet.Label LIKE '%TPM%Master Data Admin%')
+```
+
+Match → proceed. No match → offer
+`sf org assign permset --name TPM_Master_Data_Admin --target-org <alias>` AND
+ask if the user holds an equivalent (cloned/renamed) permset; wait for
+confirmation or assignment, then re-query. Proceed only once admin access is
+confirmed.
+
+### Step 7: Running user's `Sales_Org__c` matches `<salesOrg>`
+
+```sql
+SELECT Id, Username, ${PREFIX_UNDER}Sales_Org__c FROM User WHERE Username = '<running-user-name>'
+```
+
+Blank or `!= '<salesOrg>'` → stop; fix on the user record (confirm before
+mutating). This gate is R6 of `conventions-and-payload-rules.md` — blank
+throws `SOU0003`, mismatch surfaces as "not found" (create/update) or
+`TransformationError` (copy). Category access is preflighted in Phase 6 per
+R9.
+
+## Phase 2 — Verify BO API framework state
+
+Read-only. All three counts MUST be scoped to `<salesOrg>` — the framework
+rows are sales-org-partitioned.
+
+```bash
+# 1. Workflow rows for this sales org (expect 4: create/update/copy/derive)
+sf data query --target-org <alias> --json --query "
+  SELECT Name FROM ${PREFIX_UNDER}BO_API_Workflow__c
+   WHERE ${PREFIX_UNDER}BO_API__r.Name = 'Promotion'
+     AND ${PREFIX_UNDER}BO_API__r.${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
+
+# 2. Step rows for this sales org
+sf data query --target-org <alias> --json --query "
+  SELECT COUNT(Id) FROM ${PREFIX_UNDER}BO_API_Workflow_Step__c
+   WHERE ${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
+
+# 3. Junction rows whose parent workflow belongs to a Promotion BO API for this sales org
+sf data query --target-org <alias> --json --query "
+  SELECT COUNT(Id) FROM ${PREFIX_UNDER}BO_API_Workflow_Workflow_Step__c
+   WHERE ${PREFIX_UNDER}BO_API_Workflow__r.${PREFIX_UNDER}BO_API__r.Name = 'Promotion'
+     AND ${PREFIX_UNDER}BO_API_Workflow__r.${PREFIX_UNDER}BO_API__r.${PREFIX_UNDER}Sales_Org__c = '<salesOrg>'"
+```
+
+Outcome routing:
+- Zero workflow rows → fresh for this sales org, Phase 3 will seed.
+- Full state (4 workflow rows `create/update/copy/derive`; >0 step + junction
+  rows) → Phase 3 is a no-op for this sales org (still run for idempotency;
+  3a shows zero net-new).
+- Partial state → **error**; stop, report which rows are missing. A human
+  inspects first.
+
+## Phase 3a — Retrieve the packaged seed
+
+Fetch the `TPMSetupData` static resource into a dedicated `setup-data/`
+subproject (keeps the read-only managed resource out of the Phase-5a deploy
+tree at `./.promotion-bo-api-deploy/force-app`).
+
+1. Locate the resource:
+   ```bash
+   sf data query --target-org <alias> --json --query "
+     SELECT Id, Name, NamespacePrefix, SystemModStamp, BodyLength
+       FROM StaticResource WHERE Name = 'TPMSetupData'"
+   ```
+   Zero rows → stop ("TPMSetupData static resource not found — is the CGCloud
+   package installed?"). Multiple rows → prefer the one whose
+   `NamespacePrefix` matches Phase 1; if prefixes disagree, stop and ask.
+2. Retrieve into the dedicated subproject:
+   ```bash
+   mkdir -p ./.promotion-bo-api-deploy/setup-data/force-app/main/default
+   printf '{ "packageDirectories": [{ "path": "force-app", "default": true }], "sourceApiVersion": "60.0" }' \
+     > ./.promotion-bo-api-deploy/setup-data/sfdx-project.json
+   ( cd ./.promotion-bo-api-deploy/setup-data && sf project retrieve start \
+       --metadata "StaticResource:${PREFIX_UNDER}TPMSetupData" --target-org <alias> --json )
+   ```
+   Non-success → stop, print `result` errors. (`sf project retrieve` works
+   cross-platform; no `unzip` needed.)
+3. SFDX expands the zip to
+   `./.promotion-bo-api-deploy/setup-data/force-app/main/default/staticresources/${PREFIX_UNDER}TPMSetupData/BOApi/`.
+   Expected 8 CSVs — `0_BO_API__c.csv`, `0_BO_API_Entity__c.csv`,
+   `0_BO_API_Output_Entity__c.csv`, `0_BO_API_Workflow__c.csv`,
+   `0_BO_API_Workflow_Entity__c.csv`, `0_BO_API_Workflow_Step__c.csv`,
+   `0_BO_API_Workflow_Workflow_Step__c.csv`,
+   `0_BO_API_Step_Input_Structure__c.csv` — plus `import.json`. Any missing →
+   stop, print the delta.
+4. Confirm each target sObject exists:
+   `sf sobject describe --sobject '${PREFIX_UNDER}BO_API_Workflow__c' --target-org <alias> > /dev/null`
+   (etc.). Any describe failure → stop (package partially installed).
+
+## Phase 3b — Poll the batch chain
+
+`GenericDemoSetupDataBatch` self-chains via `finish()`, so poll by class (not
+by a single job id):
+
+```bash
+sf data query --target-org <alias> --json --query "
+  SELECT COUNT() FROM AsyncApexJob
+   WHERE ApexClass.Name = 'GenericDemoSetupDataBatch'
+     AND CreatedDate >= ${PHASE3_START}
+     AND Status NOT IN ('Completed','Failed','Aborted')"
+```
+
+Sleep 5s between polls; break when count is zero for **two consecutive** polls
+(covers the gap between a parent's `finish()` and a child's `AsyncApexJob` row
+appearing).
+
+Final check — every child succeeded:
+
+```sql
+SELECT Id, Status, NumberOfErrors, ExtendedStatus FROM AsyncApexJob
+ WHERE ApexClass.Name = 'GenericDemoSetupDataBatch' AND CreatedDate >= ${PHASE3_START}
+```
+
+Any `Failed`/`Aborted`/`NumberOfErrors > 0` → stop, print `ExtendedStatus`.