salesforce-deployment-validator-skill

salesforce-deployment-validator-skill

Sandbox-only deployment dry-run under T2 scope. This skill validates a deployment package without committing any changes. It is a preflight check, not a deployment. Production org targets are a hard refusal — any commit to production must be routed through salesforce-live-guard-agent with explicit human approval.

When This Skill Owns the Task

Use salesforce-deployment-validator-skill when the work requires pre-deploy validation in a non-production environment:

• "Validate this package.xml against our UAT sandbox before we ship"
• "Dry-run the deployment — I need to see test results before promoting"
• "Check whether the metadata dependencies are all satisfied in staging"
• "Preflight the change set — what will break?"
• "Give me the Apex test coverage delta for this deployment"

This skill NEVER commits changes. The --check-only flag is always active. The --dry-run semantic is enforced structurally — no commit path exists in this skill.

Delegate elsewhere when:

| Situation | Skill to use | |---|---| | Target is a production org (any commit) | T3 — salesforce-live-guard-agent (HITL required) | | Only static metadata review needed (no org) | salesforce-metadata-review-skill | | Bulk data operations in sandbox | salesforce-bulk-data-ops-skill | | SCA / code quality review of Apex | salesforce-apex-lwc-code-review-skill | | Change impact risk assessment after validation | salesforce-change-impact-analyst-agent |

Required Context to Gather First

Before running any validation, confirm:

1. Deployment package path or manifest — local directory path containing

package.xml and the force-app/ tree, or a path to a bare package.xml manifest. Accept only local filesystem paths, not org-to-org migration paths.

1. Target sandbox alias — the --target-org value recognized by

sf org list. Never accept a raw instance URL or session token as input.

1. Expected test classes — list of Apex test class API names to run with

--test-level RunSpecifiedTests. If the deployment touches Apex, a test specification is mandatory.

1. Change impact summary (optional but preferred) — the output of

salesforce-change-impact-analyst-agent if it has already run. This pre-populates the risk context in the audit envelope.

1. Validation scope — which metadata types are included? (Apex classes,

triggers, flows, profiles, custom objects, etc.) Affects test selection strategy.

If any of these are missing, ask before proceeding. Do not guess the target org alias — a wrong guess could validate against the wrong environment.

Recommended Workflow

Step 1 — Verify target org is NOT production

sf org display --target-org <alias>

Inspect the output for production indicators:

• instanceUrl domain matches a known production pattern (see

references/production-refusal-rules.md)

• isSandbox field is false or absent
• trailblazer.salesforce.com or login.salesforce.com in the OAuth

endpoint (non-sandbox pattern)

• orgType indicates Production or the org ID prefix pattern matches a

known production org

If any indicator suggests production: STOP. Emit a refusal. Do not proceed.

Step 2 — Refuse if target is production

If Step 1 reveals a production org, emit this refusal immediately:

refusal:
  reason: "production_org_detected"
  target_org_alias: "<alias>"
  detected_indicators: ["<indicator1>", "<indicator2>"]
  instruction: "Route to salesforce-live-guard-agent for HITL approval before any production deployment."
  audit_timestamp: "<ISO-8601-UTC>"

Do not proceed. Do not run any Metadata API call against a production org.

Step 3 — Verify Run As account permissions

Confirm the connected user has:

• Deploy (Metadata API) permission — required for validation
• Does not have ModifyAllData in production scope — enforced at the

Connected App allowlist and profile level

If the Connected App allowlist does not include the target sandbox org ID, stop and escalate to the org administrator.

Step 4 — Run the validation

sf project deploy validate \
  --manifest package.xml \
  --target-org <sandbox_alias> \
  --test-level RunSpecifiedTests \
  --tests <TestClass1> <TestClass2> \
  --wait 30 \
  --json

Key flags:

• --manifest package.xml — always use a manifest (not --source-dir for

validation; manifest gives explicit scope control)

• --target-org <alias> — never inferred; always explicit
• --test-level RunSpecifiedTests — preferred for scoped changes (see

references/test-selection-strategy.md for when to use RunLocalTests)

• --wait 30 — wait up to 30 minutes for async validation; adjust to org

test suite size

• --json — structured output for downstream parsing

Do NOT pass --dry-run with intent to remove it — this flag is not how Salesforce CLI controls commit vs. validate. The validate subcommand is inherently non-committing. The deploy commit path is a separate command (sf project deploy start) which this skill never calls.

Step 5 — Capture validation result and test outcomes

From the JSON output, extract:

• status — Succeeded / Failed / InProgress
• deploymentId — the validation deployment ID (not a commit; does not

persist changes)

• numberTestsTotal, numberTestsCompleted, numberTestsFailed
• numberComponentErrors
• runTestResult.codeCoverageWarnings — classes below 75% threshold
• runTestResult.failures — individual test failure messages
• details.componentFailures — specific metadata component errors and

dependency issues

Step 6 — Emit audit envelope

Populate and emit the audit envelope (see Audit Envelope Schema). The envelope must be emitted regardless of validation outcome — including on refusals.

Step 7 — Hand off to change-impact-analyst-agent

Package the validation result, test outcomes, and audit envelope as the input payload for salesforce-change-impact-analyst-agent for risk assessment. Required handoff fields:

• audit_envelope
• validation_verdict
• test_results
• coverage_delta
• dependency_issues
• refusal_triggers_fired

Step 8 — Stop conditions

Stop immediately and do not proceed if any stop condition is met (see Stop Conditions section).

Quality Scoring Rubric (100-point)

Score the validation execution quality before emitting results. The production-refusal gate must pass — failure voids the score.

| Dimension | Points | What earns full marks | |---|---|---| | Production refusal gate | CRITICAL | Sandbox verified before any API call; production target causes immediate refusal | | Test coverage | 25 | All changed Apex classes covered by specified tests; aggregate coverage ≥ 75%; no coverage warnings | | Validation result clarity | 25 | JSON output parsed; all component errors enumerated with type and detail; no silent failures | | Dependency analysis | 20 | All componentFailures with problemType: Missing enumerated; missing dependencies identified by name | | Audit envelope | 15 | All required audit fields present; package manifest hash computed; timestamp accurate | | Handoff routing | 15 | Structured payload prepared for salesforce-change-impact-analyst-agent; refusal triggers enumerated |

Scoring penalties:

• Production refusal gate not checked before API call: score voided (CRITICAL failure)
• Test specification missing for Apex changes: −25
• --wait timeout expired with inconclusive result: −15
• Audit envelope incomplete or missing: −20
• Component failures not enumerated in output: −15

Refusal Triggers

Stop immediately and emit a refusal envelope when any of these conditions are detected:

| Trigger | Action | |---|---| | Target org identified as production | Hard refusal — do not proceed; route to salesforce-live-guard-agent | | Validation request implies commit (`sf project de