@salesforce/afv-skills 1.62.0 → 1.64.0

package/skills/automation-sandbox-post-copy-configure/references/flow_activation_path.md

@@ -0,0 +1,151 @@
+# Step G — Flow activation / deactivation (`Flows`)
+
+`Flows` entries in the post-copy config mutate
+`FlowDefinition.Metadata.activeVersionNumber` via the same
+compound-`Metadata` PATCH transport as Steps D-1/D-3, but Step D-2's
+mutation-key derivation does **not** apply — the mutation key is
+always the literal `activeVersionNumber`. Follow G-1 → G-4 below
+**instead of** Step D for `Flows` entries. Steps A + B still apply
+(`FlowDefinition` is the pinned sobject; Step B confirms the
+`Metadata` compound field exists on this org).
+
+## Fields shape
+
+Every `Flows` entry carries these keys under `Fields`:
+
+| Key | Meaning |
+|-----|---------|
+| `FlowApiName` | `DeveloperName` of the parent `FlowDefinition`. Required. |
+| `Action` | `"Activate"` or `"Deactivate"`. Required. |
+| `VersionNumber` | Integer. Required for `Activate` only when pinning a specific saved version; omit to activate the latest saved version. Ignored for `Deactivate`. |
+
+Reject `FlowApiName` that doesn't match `^[A-Za-z_][A-Za-z0-9_]*$`
+before any SOQL — the queries below interpolate it unescaped; a
+malformed name is a SOQL-injection risk. Fail-closed on mismatch
+(`API_NOT_IDENTIFIED`).
+
+## G-1 — Look up the FlowDefinition + current active version
+
+```bash
+FLOW_API_NAME='<Fields.FlowApiName>'
+SOQL="SELECT Id, DeveloperName, ActiveVersion.VersionNumber FROM FlowDefinition WHERE DeveloperName = '$FLOW_API_NAME'"
+sf data query --use-tooling-api --json --query "$SOQL" \
+  > /tmp/entry-<Slug>-flow-lookup.json
+ID=$(jq -r '.result.records[0].Id // empty' /tmp/entry-<Slug>-flow-lookup.json)
+CURRENT_ACTIVE=$(jq -r '.result.records[0].ActiveVersion.VersionNumber // empty' /tmp/entry-<Slug>-flow-lookup.json)
+```
+
+- Zero rows → `NOT_FOUND` (add Follow-ups bullet; skip PATCH).
+- `CURRENT_ACTIVE` is the currently-active version number, or empty
+  if the flow is inactive. `DeveloperName` is unique, so multiple rows
+  should not occur; guard with `AMBIGUOUS` if they do.
+
+## G-2 — Resolve target `activeVersionNumber` + apply pre-flight
+
+- If `Fields.Action == "Deactivate"`:
+  - Target = `null`.
+  - If `CURRENT_ACTIVE` is empty → record `ALREADY_INACTIVE`, skip
+    PATCH, add a Follow-ups bullet.
+- If `Fields.Action == "Activate"`:
+  - If `Fields.VersionNumber` is present → target = that integer.
+  - Otherwise → query the latest saved version:
+    ```bash
+    SOQL="SELECT VersionNumber FROM Flow WHERE DefinitionId = '$ID' ORDER BY VersionNumber DESC LIMIT 1"
+    sf data query --use-tooling-api --json --query "$SOQL" \
+      > /tmp/entry-<Slug>-flow-latest.json
+    TARGET=$(jq -r '.result.records[0].VersionNumber // empty' /tmp/entry-<Slug>-flow-latest.json)
+    ```
+    Empty result → `NOT_FOUND` (flow has no saved versions).
+  - If `CURRENT_ACTIVE == TARGET` → record `ALREADY_ACTIVE`, skip
+    PATCH, add a Follow-ups bullet.
+
+## G-3 — GET current Metadata, mutate, PATCH back
+
+Same compound-`Metadata` transport as Step D-3, with the mutation
+fixed to `activeVersionNumber`. Do NOT run
+`scripts/map-metadata-key.mjs` — the mutation key is always the
+literal `activeVersionNumber`. Preserve every other key from the GET
+below; overlay only `activeVersionNumber`. Never substitute
+`ActiveVersion`, `activeVersionId`, `Status`, or `IsActive` — they
+look like candidate keys but all fail with 400 or silent no-op.
+
+The GET returns the complete Tooling API record (`Id`, `attributes`,
+`Metadata`, …). Narrow with `?fields=Metadata` and extract the
+`Metadata` object with `jq '.Metadata'` **before** the Step D-3
+merge — the merge wraps its input as `{"Metadata": …}`, so if the
+raw record is piped in, non-metadata keys end up inside `Metadata`
+and the PATCH is rejected.
+
+```bash
+sf api request rest \
+  "/services/data/v<apiVersion>/tooling/sobjects/FlowDefinition/$ID?fields=Metadata" \
+  | jq '.Metadata' > /tmp/entry-$ID-meta.json
+
+# Build /tmp/entry-$ID-mutation.json with {"activeVersionNumber": <TARGET or null>},
+# merge with /tmp/entry-$ID-meta.json using `jq --slurpfile`, PATCH the
+# merged result. Full recipe: references/api_endpoints.md §Step D.
+```
+
+Dry-run: resolve the plan via G-1 + G-2; skip the G-3 GET + PATCH;
+record `DRY_RUN`. The plan prints the fixed mutation key
+(`activeVersionNumber`) and the resolved target without reading or
+mutating the current Metadata payload.
+
+## G-4 — Verify the change landed
+
+Re-run the G-1 SOQL and confirm `ActiveVersion.VersionNumber` matches
+the target (or is empty after Deactivate). Mismatch → `FAILED_VERIFY`.
+
+## Summary shape for a Flows entry
+
+The generic `Planned request:` block from SKILL.md's canonical output
+shape does **not** apply to a Flows entry — the Flows path dispatches
+across four distinct sub-steps (SOQL lookup, target resolution, GET+
+PATCH, verify), so the summary must record evidence that each
+sub-step ran, not just the final PATCH body. Replace the
+`Planned request:` block with the narrative below, keeping the
+single-row phase table and the Totals / Follow-ups sections unchanged.
+
+For each Flows entry's phase block, emit (in this order):
+
+1. A one-line route header:
+   ```text
+   Route: **Step G — Flows (compound-`Metadata` PATCH with fixed `activeVersionNumber` mutation)**. Mutation key is fixed, NOT derived from the describe payload — `scripts/map-metadata-key.mjs` is skipped for Flows.
+   ```
+
+2. `Pre-flight lookup (G-1):` — the G-1 SOQL and the single-row result
+   (`ActiveVersion.VersionNumber = <value or null>`), ending with the
+   decision (`Not already active → proceed to G-2` /
+   `ALREADY_INACTIVE short-circuit` / `AMBIGUOUS` / `NOT_FOUND`).
+
+3. `Target resolution (G-2):` — the branch taken (`Action = Activate`
+   with `Fields.VersionNumber` present / absent → latest-version SOQL;
+   `Action = Deactivate` → target `null`), the resolved target
+   `activeVersionNumber`, and a one-line comparison vs the pre-flight
+   state justifying no short-circuit. For `Activate` without
+   `Fields.VersionNumber`, include the latest-version SOQL verbatim
+   and its returned `VersionNumber = <N>`.
+
+4. `Request executed (G-3):` — the GET and PATCH as **two separate
+   bullets** (not a Method/Path/Body sub-structure), each with the
+   full Tooling path, then the PATCH body as
+   `{ "Metadata": { …retrieved keys preserved…, "activeVersionNumber": <target> } }`,
+   then the `204 No Content` response line. On dry-run, rename this
+   section to `Planned request (G-3, dry-run):`, drop the GET bullet,
+   render the PATCH body as the fixed-key-only
+   `{ "Metadata": { "activeVersionNumber": <target> } }` (no retrieved
+   keys — the GET is skipped), omit the response line, row Outcome is
+   `DRY_RUN`, and skip section 6 below.
+
+5. The single-row phase table (unchanged from SKILL.md's canonical
+   shape; `Describe` column may be `—` for Flows since Step B's
+   describe is prod-parity only).
+
+6. `Read-back verification (G-4):` — the re-run G-1 SOQL and the
+   observed `ActiveVersion.VersionNumber` (or `ActiveVersion = null`
+   after Deactivate), confirming the mutation landed.
+
+Short-circuit cases (`ALREADY_ACTIVE` / `ALREADY_INACTIVE` /
+`NOT_FOUND` / `AMBIGUOUS` / `API_NOT_IDENTIFIED`) emit G-1 (and G-2
+if the short-circuit is only visible after target resolution) and
+stop — skip G-3, G-4, and the row's `HTTP` column renders `—`.

package/skills/automation-sandbox-post-copy-configure/references/scheduled_apex_path.md

@@ -131,15 +131,61 @@ Skip F-4 entirely in dry-run (nothing to verify).
 
 ## Summary shape for a Step F entry
 
-Reuse the phase table from the canonical output shape:
-
-- `Sobject` column reads `CronTrigger`.
-- `Describe` column reads `—` (no describe probe on this route).
-- "Planned request" / "Request executed" is the anonymous Apex snippet
-  path (`/tmp/entry-<Slug>.apex`) and its contents inline, not a PATCH
-  path/body.
-- `HTTP` column reads `—` (no direct HTTP status; `sf apex run` bundles
-  compile+execute into one response).
+The generic `Planned request:` block from SKILL.md's canonical output
+shape does **not** apply to a ScheduledApex entry — the Step F path
+dispatches across four distinct sub-steps (pre-flight SOQL, snippet
+build, `sf apex run`, verify SOQL), so the summary must record
+evidence that each sub-step ran, not just the final `sf apex run`.
+Replace the `Planned request:` block with the labeled narrative
+below, keeping the single-row phase table and the Totals /
+Follow-ups sections unchanged.
+
+For each ScheduledApex entry's phase block, emit (in this order):
+
+1. A one-line route header:
+   ```text
+   Route: **Step F — Scheduled Apex (anonymous Apex)**. No describe probe on this route; `CronTrigger` is read-only.
+   ```
+
+2. `Pre-flight AMBIGUOUS check:` — the F-1 SOQL and the single-row
+   `totalSize` result (never a bulk count claim), ending with the
+   decision (`totalSize = 0 → proceed to F-2` /
+   `AMBIGUOUS short-circuit — N existing CronTrigger rows`). Emit the
+   SOQL verbatim, with `JobName` single-quoted as it appeared on the
+   wire (post-SOQL-escape); do not paraphrase.
+
+3. `Request executed:` — the F-2/F-3 artifacts as **three separate
+   bullets** (not Method/Path/Body sub-structure):
+   - `Snippet path:` — the `/tmp/entry-<Slug>.apex` path F-2 wrote.
+   - `Snippet body:` — the exact one-line
+     `System.schedule('<JobName>', '<CronExpression>', new <ApexClassName>());`
+     string F-2 produced, with the same single-quote-escaping F-2
+     applied (not the pre-escape input).
+   - `Command:` — the exact
+     `sf apex run --file /tmp/entry-<Slug>.apex --json` invocation
+     F-3 ran.
+   On dry-run, rename this section to `Planned request (F-2, dry-run):`,
+   keep only the `Snippet path:` and `Snippet body:` bullets (omit
+   `Command:` — F-3 is skipped), row Outcome is `DRY_RUN`, and skip
+   section 5 below.
+
+4. The single-row phase table (unchanged from SKILL.md's canonical
+   shape):
+   - `Sobject` column reads `CronTrigger`.
+   - `Describe` column reads `—` (no describe probe on this route).
+   - `HTTP` column reads `—` (no direct HTTP status; `sf apex run`
+     bundles compile + execute into one response).
+
+5. `Read-back verification:` — the F-4 SOQL verbatim and the
+   observed row (`N row(s) with CronExpression = "<value>"`),
+   confirming the schedule landed. On `0 rows → FAILED_VERIFY`
+   emit the zero-row result; on `CronExpression mismatch →
+   FAILED_VERIFY` emit both the expected and observed values.
+
+Short-circuit cases (`AMBIGUOUS` / `API_NOT_IDENTIFIED` /
+`FAILED` at F-2 or F-3 / `FAILED_VERIFY`) emit F-1 (and F-2/F-3 if
+the failure is visible later) and stop — skip F-4 and the row's
+`HTTP` column renders `—`.
 
 ## Dry-run recap
 

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"
     }
   ]
 }