@salesforce/afv-skills 1.41.0 → 1.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.41.0",
+  "version": "1.43.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [
@@ -14,13 +14,9 @@
     "@salesforce/ui-bundle-template-app-react-sample-b2e": "^11.57.2",
     "@salesforce/ui-bundle-template-app-react-sample-b2x": "^11.57.2",
     "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.117.1",
-    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.117.1",
-    "@types/js-yaml": "^4.0.9",
-    "js-yaml": "^4.1.1",
-    "tsx": "^4.21.0"
+    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.117.1"
   },
   "scripts": {
-    "validate:skills": "tsx scripts/validate-skills.ts",
     "sync-react-b2e-sample": "node scripts/sync-react-b2e-sample.js",
     "sync-react-b2x-sample": "node scripts/sync-react-b2x-sample.js"
   }

package/skills/automation-sandbox-post-copy-config-generate/SKILL.md

@@ -2,6 +2,9 @@
 name: automation-sandbox-post-copy-config-generate
 description: "Generate the JSON config file that the Salesforce sandbox post-copy automation tool consumes, from a customer SOP in any format (PDF, xlsx, csv, JSON, docx, Markdown, plain text, or a screenshot of an endpoint table). Use when the user asks to create, build, generate, produce, or convert a post-copy or post-refresh automation config — turning a sandbox-refresh SOP into a JSON array of OutboundMessages and RemoteSiteSettings entries with ConfigurationName, Label, Fields, IsActive, and ExecutionOrder. Also trigger for phrasings like \"post-copy config\", \"post-refresh automation JSON\", \"update the outbound message (OBM) endpoints after refresh\", \"convert this SOP to config\", \"remote site settings JSON\", \"refresh planner to JSON\", or \"sandbox refresh config\". DO NOT TRIGGER when: user wants to deploy the generated config to an org (use platform-metadata-deploy), or apply/execute/run/dry-run the post-copy automation JSON against a sandbox (use automation-sandbox-post-copy-configure)."
 metadata:
+  relatedSkills:
+    - "automation-sandbox-post-copy-configure"
+    - "platform-metadata-deploy"
   version: "1.0"
   domains: ["Automation"]
 ---

package/skills/automation-sandbox-post-copy-configure/SKILL.md

@@ -3,6 +3,10 @@ name: automation-sandbox-post-copy-configure
 description: "Apply a Salesforce sandbox post-copy automation JSON config against a target org. For each entry, the skill derives the correct Tooling API sobject from the entry's `ConfigurationName`, verifies the derivation via a describe probe, resolves the record Id via SOQL-over-REST, then PATCHes the record via the compound `Metadata` field using `sf api request rest`. Use when the user asks to apply, run, execute, dry-run, or preview a post-copy or post-refresh config file (e.g. `post-copy-config.json`) against a sandbox. Trigger phrases: \"apply post-copy config\", \"run post-copy automation\", \"execute sandbox post-refresh JSON\", \"apply sandbox refresh config\", \"configure sandbox after refresh\". DO NOT TRIGGER for generating the config JSON from an SOP (delegate to `automation-sandbox-post-copy-config-generate`), or for deploying metadata XML."
 allowed-tools: Bash Read Write
 metadata:
+  relatedSkills:
+    - "automation-sandbox-post-copy-config-generate"
+    - "dx-org-permission-set-assign"
+    - "platform-metadata-deploy"
   version: "1.0"
   domains: ["Automation"]
   cliTools:

package/skills/design-systems-slds-validate/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: design-systems-slds-validate
-description: "Audit Lightning Web Components for SLDS design-system compliance and produce a scored quality report. Runs the SLDS linter and analyzes CSS for theming hook usage and pairing, scoring SLDS findings across categories into an overall grade. Use when asked to \"score my component's SLDS\", \"SLDS scorecard\", \"SLDS quality report\", \"audit SLDS compliance\", \"how good is my SLDS\", \"check SLDS quality\", \"rate my SLDS styling\", \"evaluate my component's SLDS\", \"is this component's SLDS ready to ship?\", \"look at my LWC for SLDS issues\", \"audit SLDS before I submit\", \"review my component's SLDS before code review\", or any time a user wants an SLDS quality assessment or SLDS production-readiness check on an LWC. Not for fixing violations (use design-systems-slds2-migrate), building new components (use design-systems-slds-apply), or accessibility/WCAG/ARIA audits (use experience-lwc-accessibility-validate)."
+description: "Audit Lightning Web Components for SLDS design-system compliance and produce a scored quality report. Runs the SLDS linter and analyzes CSS for theming hook usage and pairing, scoring SLDS findings across categories into an overall grade. Use when asked to \"score my component's SLDS\", \"SLDS scorecard\", \"SLDS quality report\", \"audit SLDS compliance\", \"how good is my SLDS\", \"check SLDS quality\", \"rate my SLDS styling\", \"evaluate my component's SLDS\", \"is this component's SLDS ready to ship?\", \"look at my LWC for SLDS issues\", \"audit SLDS before I submit\", \"review my component's SLDS before code review\", or any time a user wants an SLDS quality assessment or SLDS production-readiness check on an LWC. Not for fixing violations (use design-systems-slds2-migrate), building new components (use design-systems-slds-apply), or accessibility/WCAG/ARIA audits (use experience-accessibility-validate)."
 metadata:
   version: "1.0"
   domains: ["Design Systems"]
   relatedSkills:
     - "design-systems-slds-apply"
     - "design-systems-slds2-migrate"
-    - "experience-lwc-accessibility-validate"
+    - "experience-accessibility-validate"
   cliTools:
     - tool: ["npx"]
       semver: ">=7.0.0"

package/skills/dx-app-analytics-query/SKILL.md

@@ -1,12 +1,11 @@
 ---
 name: dx-app-analytics-query
-description: "ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings. Use this skill when the user asks about retrieving managed package usage data, configuring App Analytics simulation mode, querying subscriber snapshots, or understanding the AppAnalyticsQueryRequest lifecycle (New → Pending → Complete → Expired). TRIGGER when: user mentions App Analytics, AppAnalyticsQueryRequest, AppAnalyticsSettings, package usage data, subscriber analytics, ISV analytics, or simulation mode for app analytics. DO NOT TRIGGER when: the task is about standard Salesforce reports/dashboards (use reporting skills), custom SOQL on Account/Contact (use platform-soql-query), or Data Cloud query/search (use data360-query)."
+description: "ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings. Use this skill when the user asks about retrieving managed package usage data, configuring App Analytics simulation mode, querying subscriber snapshots, or understanding the AppAnalyticsQueryRequest lifecycle (New → Pending → Complete → Expired). TRIGGER when: user mentions App Analytics, AppAnalyticsQueryRequest, AppAnalyticsSettings, package usage data, subscriber analytics, ISV analytics, or simulation mode for app analytics. DO NOT TRIGGER when: the task is about standard Salesforce reports/dashboards (use reporting skills), custom SOQL on Account/Contact (use platform-soql-query)."
 metadata:
   cliTools:
     - tool: ["sf"]
       semver: ">=2.0.0"
   relatedSkills:
-    - "data360-query"
     - "platform-metadata-deploy"
     - "platform-soql-query"
   version: "1.0"
@@ -29,7 +28,6 @@ Use `dx-app-analytics-query` when the work involves:
 
 Delegate elsewhere when the user is:
 - Running standard CRM SOQL queries → platform-soql-query
-- Working with Data Cloud SQL or DMOs → data360-query
 - Building reports/dashboards on standard objects → reporting skills
 - Deploying or retrieving generic metadata XML → platform-metadata-deploy / retrieving-metadata
 

package/skills/dx-devops-conflict-resolve/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: dx-devops-conflict-resolve
+description: "Use this skill to diagnose and resolve what blocks a DevOps Center promotion of a work item's feature branch: Git merge conflicts and deployment failures. DevOps Center is Git-backed, so overlapping metadata changes surface as merge conflicts against the target stage branch, resolved with git (detect, resolve markers, commit, push). Deploy failures often cite a missing dependency a full promotion can fix when the component already exists on the branch. TRIGGER when the user wants to check a work item for conflicts before promoting, resolve merge conflicts or leftover conflict markers in metadata files (.xml, .object-meta.xml, .cls), reconcile a feature branch with its target stage branch, or diagnose why a DevOps Center promotion or deployment failed and whether a full promotion or a missing-dependency fix will resolve it. DO NOT TRIGGER for running the promotion itself (use dx-devops-promote), creating or updating work items (use dx-devops-work-item-manage), or deploying metadata directly to an org."
+metadata:
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "58.0"
+  relatedSkills:
+    - "dx-devops-promote"
+    - "dx-devops-work-item-manage"
+  cliTools:
+    - tool: ["git"]
+      semver: ">=2.23"
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck:
+    - type: "orgPref"
+      value: "ALMDevopsCorePref"
+    - type: "userPerm"
+      value: "UserHasDevOpsCore"
+---
+
+# DevOps Center Conflict & Deploy-Failure Resolution
+
+Diagnoses and resolves what blocks a DevOps Center promotion of a work item's feature branch. DevOps Center is Git-backed: each work item is a feature branch and each pipeline stage has a target branch. A promotion can fail two ways — a **Git merge conflict** (two work items changed the same metadata) or a **deployment failure** (the deploy itself errors, often on a **missing dependency**). There is no `sf devops conflict` CLI command; both cases are diagnosed and resolved with standard **git** against the connected repository. This skill runs in a local clone of that repo.
+
+## Scope
+
+- **In scope**: (a) Detect merge conflicts between a work item's feature branch and the target stage branch (non-destructively), resolve conflicted files (choose a side or manually merge conflict markers), commit, and push the feature branch DevOps Center tracks; (b) Diagnose a promotion **deploy failure** — classify it as a merge conflict vs. a deploy error, parse a missing dependency, and determine whether a **full promotion** can fix it (the component exists on the feature branch) or the component must be added first
+- **Out of scope**: Running the promotion, full promotion, or combine (use `dx-devops-promote`), creating/updating work items or their status (use `dx-devops-work-item-manage`), deploying metadata directly to an org, pipeline or project setup (separate skills)
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Local clone** of the DevOps Center connected Git repository (the agent runs git commands here). Confirm the working tree is clean before starting.
+- **Feature branch name** — the branch backing the work item. If the user gives a work item ID/subject instead, resolve it to its branch (see the Reference File Index for the `sf devops work-item` lookup).
+- **Target stage branch name** — the branch of the pipeline stage the work item promotes into (e.g. the integration/UAT branch).
+- **Remote name** — defaults to `origin`.
+- **Deploy error text** (deploy-failure track only) — the promotion's error output/summary. Needed to classify the failure and parse a missing dependency. Capture it to a file or pipe it into the diagnosis script.
+
+Defaults unless specified:
+- Remote: `origin`
+- Merge direction: merge the **target stage branch into the feature branch** (reconcile the work item with where it is going)
+
+If the user names both branches ("resolve conflicts on `feature/WI-101` against `uat`"), proceed. If they give a work item, resolve its branch first.
+
+---
+
+## Workflow
+
+DevOps Center promotion blockers are Git-level. Detection and diagnosis are deterministic (scripts); resolving each conflicted file requires judgment (prose). Never resolve without first detecting on a clean tree.
+
+**Route first.** Pick the track from the user's situation:
+
+- **Merge conflict track** — the user wants a pre-promotion conflict check, or a promotion failed and the cause is (or is suspected to be) a merge conflict → Phases 1–4 below.
+- **Deploy-failure track** — a promotion's *deploy* failed with an error message and the user wants to know why and how to fix it → Phase D below. If Phase D classifies the failure as a merge conflict, fall through to the merge-conflict track.
+
+### Phase 1 — Authenticate and orient
+
+1. **Confirm the local repo and clean tree.** Run in the repo clone:
+   ```bash
+   git rev-parse --is-inside-work-tree && git status --porcelain
+   ```
+   - If `git status --porcelain` prints anything, the tree is dirty — instruct the user to commit or stash first. A trial merge on a dirty tree is unsafe.
+2. **Resolve a work item to its branch (only if the user gave a work item, not a branch).** Verify org auth with `sf org display --json`; if it fails, tell the user to run `sf org login web --set-default --alias <alias>`. Then look up the branch — see `references/git-conflict-resolution.md`.
+
+### Phase 2 — Detect (non-destructive)
+
+3. **Run the detection script.** It fetches, trial-merges the target branch into the feature branch without committing, lists conflicted files, and aborts the trial so the tree is left untouched:
+   ```bash
+   scripts/detect-conflicts.sh <feature-branch> <target-branch> [remote]
+   ```
+   - Exit `0` = clean merge (no conflicts) → report "safe to promote" and STOP.
+   - Exit `2` = conflicts found → the script prints the conflicting file list; proceed to Phase 3.
+   - Exit `1` = error (dirty tree, unknown branch, fetch failure) → report the error and STOP; do not treat an error as "no conflicts".
+
+### Phase 3 — Resolve
+
+4. **Start the real merge** to bring conflict markers into the working tree:
+   ```bash
+   git checkout <feature-branch>
+   git merge --no-ff <remote>/<target-branch>
+   ```
+   List the conflicted files deterministically:
+   ```bash
+   git diff --name-only --diff-filter=U
+   ```
+5. **Resolve each conflicted file** — this is the judgment step:
+   - When one side is unambiguously correct, take it: `git checkout --ours -- <file>` (keep the feature branch's version) or `git checkout --theirs -- <file>` (take the target branch's version). For DevOps Center, "ours" is the feature branch, "theirs" is the target stage branch.
+   - When both sides contain needed changes (divergent edits to the same component), open the file and manually merge — reconcile the `<<<<<<<` / `=======` / `>>>>>>>` regions into a single correct version, preserving both intents. Be especially careful with XML metadata (`.xml`, `.object-meta.xml`, `.field-meta.xml`): keep the file well-formed and do not duplicate elements.
+   - Stage each resolved file: `git add <file>`.
+6. **Confirm no markers remain** before committing:
+   ```bash
+   git diff --check
+   git diff --name-only --diff-filter=U
+   ```
+   - `git diff --check` must report nothing, and the unmerged-file list must be empty. If either shows leftovers, keep resolving — do not commit.
+
+### Phase 4 — Finalize and report
+
+7. **Commit and push the resolution** to the tracked feature branch so DevOps Center picks it up:
+   ```bash
+   git commit --no-edit          # completes the merge with the default merge message
+   git push <remote> <feature-branch>
+   ```
+8. **Report the outcome**:
+   - No conflicts: "No merge conflicts between `<feature>` and `<target>`. Safe to promote."
+   - Resolved: list the files resolved and how (took a side vs. manual merge), and state that the feature branch was pushed. Then hand off: "Re-validate and promote via `dx-devops-promote`."
+
+### Phase D — Diagnose a deployment failure
+
+Use this track when a promotion's **deploy** failed with an error and the user wants to know why and how to fix it. Diagnosis is deterministic (a script); do not eyeball the error.
+
+D1. **Capture the deploy error text** to a file, or pipe it directly into the diagnosis script.
+
+D2. **Run the diagnosis script** from the repo clone. It classifies the failure, parses any missing dependency, and checks whether that component exists on the feature branch (via `git show`):
+   ```bash
+   scripts/diagnose-deploy-failure.sh <error-file|-> <feature-branch> [target-branch] [remote]
+   # or:  <deploy command> 2>&1 | scripts/diagnose-deploy-failure.sh - <feature-branch> <target-branch>
+   ```
+   Act on the exit code and the printed `REASON` / `RECOMMENDATION`:
+   - Exit `0` (`dependency_in_feature_branch`) → the missing component **exists on the feature branch** but was left out of the deployed set. A **full promotion** should fix it. Report this, confirm with the user, and hand off to `dx-devops-promote` to run a full promotion. This skill does not promote.
+   - Exit `2` (`merge_conflict`) → the failure is a merge conflict, not a deploy error. Fall through to the **merge-conflict track** (Phase 1 onward).
+   - Exit `3` (`dependency_not_in_feature_branch`) → the missing component is **not** on the feature branch, so promoting cannot supply it. Report that the component must be added and committed to the feature branch (or the owning work item included) before promoting.
+   - Exit `4` (`no_dependency_parsed`) → the error is not a recognizable missing dependency. Report the raw error and advise fixing the underlying issue (e.g. test coverage, invalid metadata); a full promotion will not help.
+   - Exit `1` → environment/usage error (not in a git repo, unreadable error file) → report and stop.
+
+D3. **Report the diagnosis** with the `REASON`, whether a full promotion can fix it, the missing component (if any) and where it lives, and the concrete next step. Never re-promote blindly — only recommend a full promotion when the diagnosis is `dependency_in_feature_branch`.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Never trial-merge or merge on a dirty working tree | An in-progress merge on uncommitted changes can clobber the user's work irrecoverably |
+| Always detect (Phase 2) before resolving (Phase 3) | Detection is non-destructive; jumping to a live merge without knowing the conflict set risks a messy half-merge |
+| Detect conflicts with the script, not by eyeballing | `scripts/detect-conflicts.sh` produces a deterministic, reproducible conflict list and always cleans up its trial merge |
+| A non-zero detection error is NOT "no conflicts" | Only exit `0` (clean) means safe to promote; exit `1` means the check failed and must be reported |
+| Merge the target stage branch INTO the feature branch | Reconciles the work item with its destination; DevOps Center promotes the feature branch, so the resolution must live there |
+| Verify no conflict markers remain (`git diff --check`) before committing | Committing unresolved markers corrupts the metadata and the promotion |
+| Preserve XML well-formedness when manually merging metadata | Malformed `-meta.xml` breaks deployment; never leave duplicated or truncated elements |
+| Push only the work item's feature branch | The resolution belongs to the work item's branch; never push to a stage/integration branch directly |
+| This skill does not promote or deploy | Resolution ends at a pushed, conflict-free branch or a diagnosis; promotion (including full promotion) is `dx-devops-promote` |
+| Diagnose deploy failures with the script, not by eyeballing | `scripts/diagnose-deploy-failure.sh` deterministically classifies the failure and verifies branch presence with `git show` |
+| Recommend a full promotion ONLY when the missing component is on the feature branch | If the component is absent, promoting the branch cannot supply it — a re-promote just fails again |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| **No `sf devops conflict` CLI command exists** | DevOps Center conflicts are Git conflicts — resolve them with `git`, not a `sf devops` subcommand. This skill is git-based by design |
+| **Dirty working tree** | `git status --porcelain` must be empty; instruct the user to commit or stash before detecting/resolving |
+| **User gave a work item, not a branch** | Resolve the work item to its feature branch first via `sf devops work-item` — see `references/git-conflict-resolution.md` |
+| **Non-zero script exit treated as clean** | Exit `2` = conflicts, exit `1` = error. Only exit `0` is "safe to promote" |
+| **Committing with markers still present** | Run `git diff --check` and confirm the `--diff-filter=U` list is empty before `git commit`; leftover `<<<<<<<`/`>>>>>>>` markers corrupt metadata |
+| **`--ours` / `--theirs` reversed** | When merging the target INTO the feature branch, `--ours` = feature branch, `--theirs` = target stage branch |
+| **Manually merged XML is malformed** | Keep `-meta.xml` well-formed; do not duplicate elements. Re-check the file parses before staging |
+| **Detached HEAD / stale branch** | `git fetch` first; check out the feature branch as a tracking branch before merging (the script fetches for you) |
+| **Conflict reappears after promotion still fails** | The target branch moved; re-run detection against the current target branch and resolve again |
+| **Re-promoting a deploy failure without diagnosing** | Run `scripts/diagnose-deploy-failure.sh` first: exit `0` = component on the branch, a full promotion fixes it; exit `2` = it's a merge conflict (switch tracks); exit `3` = component absent, add and commit it (or include the owning work item) before promoting — promotion alone cannot supply it |
+
+---
+
+## Output Expectations
+
+This skill produces a **conflict-free feature branch** or a **deploy-failure diagnosis**, not org changes:
+
+- **No conflicts**: confirmation that the feature branch merges cleanly into the target stage branch — safe to promote
+- **Conflicts resolved**: a merge commit on the work item's feature branch reconciling it with the target stage branch, pushed to the remote, plus a report of which files were resolved and how (took a side vs. manual merge)
+- **Deploy-failure diagnosis**: a report stating the failure reason (merge conflict / missing dependency in-branch / missing dependency not-in-branch / unrecognized), whether a full promotion can fix it, the missing component and where it lives, and the concrete next step
+
+No metadata is deployed and no org state is mutated. The deliverable is the pushed, conflict-free branch or the diagnosis and recommended next step.
+
+---
+
+## Cross-Skill Integration
+
+| When | Action |
+|------|--------|
+| The branch is conflict-free (or resolved and pushed) and ready to advance | Delegate to `dx-devops-promote` to validate and promote |
+| A work item name/ID must be resolved to its feature branch, or candidate work items listed | Use `dx-devops-work-item-manage` |
+| Work items share metadata and could promote as one unit instead of resolving separately | Consider combining via `dx-devops-promote`'s combine step rather than a manual merge |
+| A promote deploy already failed on a conflict | Re-detect against the current target branch, resolve, push, then re-promote via `dx-devops-promote` |
+| Diagnosis says a full promotion can fix the failure (`dependency_in_feature_branch`) | Hand off to `dx-devops-promote` to run the full promotion — this skill does not promote |
+| Missing component must be added to the feature branch before promoting | Author/commit the component (or include the owning work item) — for metadata generation use the relevant domain skill, then re-promote via `dx-devops-promote` |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `scripts/detect-conflicts.sh` | Phase 2 — run it to non-destructively detect merge conflicts between the feature branch and the target stage branch |
+| `scripts/diagnose-deploy-failure.sh` | Phase D — run it to classify a promotion deploy failure and decide whether a full promotion (or a missing-dependency fix) resolves it |
+| `references/git-conflict-resolution.md` | When you need the full git command reference, the `sf devops work-item`-to-branch lookup, or `--ours`/`--theirs` and XML-merge guidance |
+| `references/deploy-failure-resolution.md` | Phase D — when you need the deploy-failure decision tree, the error-parsing patterns, or the full-promotion reasoning behind the diagnosis script |
+| `examples/conflict-workflows.md` | When the user's request matches a common pattern (pre-promotion conflict check, take-a-side resolution, manual XML merge, troubleshooting a failed promotion, or diagnosing a deploy failure) |

package/skills/dx-devops-conflict-resolve/examples/conflict-workflows.md

@@ -0,0 +1,165 @@
+# DevOps Center Conflict Resolution Examples
+
+Common end-to-end patterns. Every pattern runs in a local clone of the DevOps Center connected Git repo, starts from a **clean working tree**, and **detects before resolving**. Detection is non-destructive; resolution ends with a commit pushed to the work item's feature branch. Promotion itself is `dx-devops-promote`, not this skill.
+
+---
+
+## Example 1 — Pre-promotion conflict check (no conflicts)
+
+**User prompt:** "Before I promote `feature/WI-101` to UAT, is there anything that will conflict?"
+
+```bash
+# 1. Confirm a clean tree
+git status --porcelain    # must be empty
+
+# 2. Detect (non-destructive) — target stage branch is uat
+scripts/detect-conflicts.sh feature/WI-101 uat origin
+# → CLEAN: no merge conflicts between feature/WI-101 and origin/uat   (exit 0)
+```
+
+**Report:** "No merge conflicts between `feature/WI-101` and `uat`. Safe to promote — hand off to `dx-devops-promote`."
+
+---
+
+## Example 2 — Resolve by taking one side
+
+**User prompt:** "`feature/WI-101` conflicts with `uat` on the README — keep my branch's version."
+
+```bash
+# 1. Detect
+scripts/detect-conflicts.sh feature/WI-101 uat origin
+# → CONFLICTS: merging origin/uat into feature/WI-101 conflicts on these files:
+#   docs/README.md                                                   (exit 2)
+
+# 2. Real merge to bring in the markers
+git checkout feature/WI-101
+git merge --no-ff origin/uat
+
+# 3. Keep the feature branch's version (ours = feature branch when merging target → feature)
+git checkout --ours -- docs/README.md
+git add docs/README.md
+
+# 4. Verify nothing left, then finalize
+git diff --check
+git diff --name-only --diff-filter=U    # empty
+git commit --no-edit
+git push origin feature/WI-101
+```
+
+**Report:** "Resolved `docs/README.md` by keeping the feature branch's version; merged `uat` into `feature/WI-101` and pushed. Re-validate and promote via `dx-devops-promote`."
+
+---
+
+## Example 3 — Manual merge of conflicting XML metadata
+
+**User prompt:** "Two work items both edited the `Account` object — resolve the conflict on `feature/WI-205` against `integration`, keeping both sets of fields."
+
+```bash
+# 1. Detect
+scripts/detect-conflicts.sh feature/WI-205 integration origin
+# → CONFLICTS: ... force-app/main/default/objects/Account/Account.object-meta.xml   (exit 2)
+
+# 2. Real merge
+git checkout feature/WI-205
+git merge --no-ff origin/integration
+
+# 3. Hand-merge the XML: open the file, reconcile the
+#    <<<<<<< / ======= / >>>>>>> regions so BOTH work items' <fields> blocks
+#    are present exactly once, keep the document well-formed, no duplicated elements.
+#    (Edit Account.object-meta.xml here.)
+
+# 4. Sanity-check it still parses, then stage
+xmllint --noout force-app/main/default/objects/Account/Account.object-meta.xml   # if available
+git add force-app/main/default/objects/Account/Account.object-meta.xml
+
+# 5. Verify + finalize
+git diff --check
+git diff --name-only --diff-filter=U    # empty
+git commit --no-edit
+git push origin feature/WI-205
+```
+
+**Report:** "Manually merged `Account.object-meta.xml`, preserving both work items' field additions; XML validated, merged `integration` into `feature/WI-205`, and pushed. Consider combining these work items via `dx-devops-promote` if they should promote as one unit."
+
+---
+
+## Example 4 — Prefer combine over manual merge
+
+**User prompt:** "WI-301 and WI-302 keep conflicting on the same Apex class every promotion."
+
+When two work items legitimately share components, resolving the same metadata by hand on every promotion is wasted effort. Detect to confirm the overlap, then recommend combining rather than merging:
+
+```bash
+scripts/detect-conflicts.sh feature/WI-301 uat origin
+# → CONFLICTS: ... force-app/main/default/classes/AccountService.cls   (exit 2)
+```
+
+**Report:** "WI-301 and WI-302 both modify `AccountService.cls`. Rather than hand-merging on each promotion, combine them into one promotion unit via `dx-devops-promote`'s combine step so they deploy together. If you must keep them separate, resolve now: merge `uat` into `feature/WI-301`, reconcile the class, commit, and push."
+
+---
+
+## Example 5 — Troubleshoot a promotion that failed on a conflict
+
+**User prompt:** "My promote just failed with a deploy conflict — fix it."
+
+```bash
+# 1. The target branch may have moved since the last check. Re-detect against
+#    the CURRENT target stage branch on a clean tree.
+git status --porcelain      # must be empty
+scripts/detect-conflicts.sh feature/WI-410 main origin
+
+# 2a. If exit 0 (CLEAN): the conflict was transient/stale — re-run dx-devops-promote.
+# 2b. If exit 2 (CONFLICTS): resolve as in Examples 2/3, then push:
+git checkout feature/WI-410
+git merge --no-ff origin/main
+# ...resolve each file, git add...
+git diff --check
+git commit --no-edit
+git push origin feature/WI-410
+```
+
+**Report:** "Re-detected against the current `main`; resolved `<files>` and pushed `feature/WI-410`. Re-run the promotion via `dx-devops-promote`."
+
+---
+
+## Example 6 — Diagnose a deployment failure (full promotion can fix)
+
+**User prompt:** "My promotion of WI-101 to UAT failed with `Variable does not exist: BillingService`. What do I do?"
+
+```bash
+# 1. Diagnose deterministically from the repo clone. The class BillingService is
+#    referenced but was left out of a partial deployed set.
+echo "Problem: Variable does not exist: BillingService" \
+  | scripts/diagnose-deploy-failure.sh - feature/WI-101 uat origin
+# → MISSING_DEPENDENCY_TYPE=ApexClass
+#   MISSING_DEPENDENCY_NAME=BillingService
+#   IN_FEATURE_BRANCH=true
+#   REASON=dependency_in_feature_branch
+#   CAN_FULL_PROMOTION_FIX=true                                        (exit 0)
+```
+
+**Report:** "`BillingService` (ApexClass) exists on `feature/WI-101` but wasn't in the deployed set, so the deploy failed on a missing dependency. A **full promotion** will include it and should fix the failure. Confirm, then run the full promotion via `dx-devops-promote`."
+
+---
+
+## Example 7 — Diagnose a deployment failure (component missing from the branch)
+
+**User prompt:** "Promotion failed: `no ApexClass named TaxHelper found`. Just re-run it as a full promotion?"
+
+```bash
+sf project deploy start ... 2>&1 \
+  | scripts/diagnose-deploy-failure.sh - feature/WI-210 integration origin
+# → MISSING_DEPENDENCY_TYPE=ApexClass
+#   MISSING_DEPENDENCY_NAME=TaxHelper
+#   IN_FEATURE_BRANCH=false
+#   REASON=dependency_not_in_feature_branch
+#   CAN_FULL_PROMOTION_FIX=false                                       (exit 3)
+```
+
+**Report:** "No — `TaxHelper` is **not** on `feature/WI-210`, so promoting the branch (full or partial) cannot supply it. Add and commit `TaxHelper` to the feature branch (or include the work item that owns it), then re-promote via `dx-devops-promote`." (If exit `4`/`no_dependency_parsed`, report the raw error and advise fixing the underlying issue — e.g. test coverage — since a full promotion won't help. If exit `2`/`merge_conflict`, switch to the conflict-resolution track above.)
+
+---
+
+## Idempotency note
+
+Detection is always safe to re-run — it aborts its trial merge and restores the checkout. If a live merge is interrupted (`MERGE_HEAD exists`), either finish it (`git commit`) or abort it (`git merge --abort`) before re-detecting; never start a second merge on top of an unfinished one.

package/skills/dx-devops-conflict-resolve/references/deploy-failure-resolution.md

@@ -0,0 +1,75 @@
+# DevOps Center Deploy-Failure Resolution Reference
+
+DevOps Center promotes a work item by **deploying its feature branch** into the target stage branch. That deploy can fail, and the fix depends on *why*. This reference covers the decision tree the `scripts/diagnose-deploy-failure.sh` script implements, the error patterns it recognizes, and the reasoning behind recommending a **full promotion**.
+
+## The two failure classes
+
+| Class | Symptom | Can a re-promote / full promotion fix it? |
+|-------|---------|-------------------------------------------|
+| **Merge conflict** | Error mentions `MERGE_CONFLICT` or `CONFLICTS:` | **No.** The branches conflict — resolve the conflict first (see `git-conflict-resolution.md`), then re-promote. |
+| **Deploy error** | The deploy runs but errors (missing dependency, invalid metadata, test failure, …) | **Sometimes.** A *full* promotion helps only when the deploy failed on a **missing dependency that already exists on the feature branch** but was left out of a partial deployed set. |
+
+## Why a "full promotion" is the lever
+
+DevOps Center can promote a **subset** of a work item's changes. When the deployed subset references a component it did not include (e.g. an Apex class that calls another class not in the set), the deploy fails with a *missing dependency* error. If that referenced component is **already committed on the feature branch**, promoting **everything** (a full promotion) includes it and the deploy succeeds. If the component is **not** on the branch, no promotion can supply it — it must be authored/committed first (or the work item that owns it must be included).
+
+## The decision tree
+
+```text
+deploy error
+├─ matches MERGE_CONFLICT / CONFLICTS:      → merge conflict; resolve, don't re-promote   (exit 2)
+└─ otherwise, parse a missing dependency
+   ├─ none parsed                            → generic fix; full promotion won't help      (exit 4)
+   └─ dependency <Type> <Name> parsed
+      ├─ present on feature branch           → FULL PROMOTION can fix; confirm & promote    (exit 0)
+      └─ absent from feature branch          → add/commit the component first, then promote (exit 3)
+```
+
+## Recognized error patterns
+
+The parser (mirrors the DevOps Center provider) extracts a metadata **type** and **component name** from these shapes:
+
+| Error shape | Parsed as |
+|-------------|-----------|
+| `Variable does not exist: Foo` (or `Problem: Variable does not exist: Foo`) | `ApexClass` `Foo` |
+| `no ApexClass named Foo found` (also `ApexTrigger`/`ApexPage`/`CustomObject`/`Flow`) | that type + `Foo` |
+| `In field: apexClass - no ApexClass named Foo found (profiles/…)` | `ApexClass` `Foo` |
+| `... Component: Foo, Type: ApexClass ...` (when not a "Variable does not exist"/"Problem:" line) | that type + `Foo` |
+
+Anything else parses to *no dependency* → generic guidance.
+
+## Branch-presence check
+
+For a parsed `<Type> <Name>`, the script builds candidate source paths for the standard SFDX layout and asks git whether any exist on the branch:
+
+```bash
+git show <feature-branch>:force-app/main/default/classes/<Name>.cls        # local ref
+git show origin/<feature-branch>:force-app/main/default/classes/<Name>.cls # remote ref fallback
+```
+
+Path templates by type:
+
+| Type | Candidate paths (first match wins) |
+|------|------------------------------------|
+| `ApexClass` | `…/classes/<Name>.cls` (under `force-app/main/default/`, `main/default/`, or `classes/`) |
+| `ApexTrigger` | `…/triggers/<Name>.trigger` |
+| `ApexPage` | `…/pages/<Name>.page` |
+| `Profile` | `…/profiles/<Name>.profile-meta.xml` |
+| `CustomObject` | `…/objects/<Name>/<Name>.object-meta.xml` |
+| `Flow` | `…/flows/<Name>.flow-meta.xml` |
+
+If a project uses a non-standard package directory (custom `packageDirectories` in `sfdx-project.json`), the standard templates may miss the file and the script reports `dependency_not_in_feature_branch` conservatively — verify manually with `git show <branch>:<actual-path>` before concluding.
+
+## Running the script
+
+```bash
+# From the repo clone. Pass an error file, or pipe the deploy output with '-'.
+scripts/diagnose-deploy-failure.sh deploy-error.txt feature/WI-101 uat origin
+sf project deploy start ... 2>&1 | scripts/diagnose-deploy-failure.sh - feature/WI-101 uat
+```
+
+It prints `REASON`, `CAN_FULL_PROMOTION_FIX`, `RECOMMENDATION`, and (when parsed) `MISSING_DEPENDENCY_TYPE` / `MISSING_DEPENDENCY_NAME` / `IN_FEATURE_BRANCH` (+ `IN_TARGET_BRANCH` when a target branch is given). Exit codes: `0` full promotion can fix, `2` merge conflict, `3` dependency absent, `4` unparsed, `1` usage/env error.
+
+## Handing off
+
+This skill diagnoses; it does not promote. When the diagnosis is `dependency_in_feature_branch`, confirm with the user and hand the **full promotion** to `dx-devops-promote`. When a component must be added, author it with the relevant domain skill, commit it to the feature branch, then re-promote. When the diagnosis is a merge conflict, switch to the conflict-resolution track in `git-conflict-resolution.md`.