@raishin/vanguard-frontier-agentic 2.3.0 → 2.5.0

package/skills/salesforce/salesforce-apex-test-runner-skill/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: salesforce-apex-test-runner-skill
+description: "Executes Apex tests against a connected SANDBOX org via sf apex run test, parses results and coverage delta, identifies failures with stack traces, and suggests fixes. T1 read-only runtime (sandbox-only). Production org targets are HARD REFUSED before any API call. TRIGGER when: user wants to run Apex tests, execute a test class, check test coverage, diagnose test failures, or validate coverage before deployment. Trigger phrases: run apex tests, execute test class, test my changes, check test coverage, why is my test failing. DO NOT TRIGGER when: user needs to generate test classes (use salesforce-apex-test-generator-skill), debug without running tests (use salesforce-apex-log-analyzer-skill), static code review of test code (use salesforce-apex-lwc-code-review-skill), or user needs a deployment (use salesforce-deployment-validator-skill)."
+license: MIT
+allowed-tools: Bash(sf apex run test:*) Bash(sf org display:*) Bash(sf apex get test:*) Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-05-21"
+  category: operational
+  lifecycle: experimental
+  execution_tier: read-only-runtime
+  mcp_servers: []
+  oauth_scopes: ["api", "refresh_token"]
+  run_as_permissions:
+    required: ["View Setup and Configuration", "View All Data (sandbox-only)"]
+    denied: ["ModifyAllData", "ViewEncryptedData", "ModifyMetadata", "AuthorApex", "ManageConnectedApps"]
+---
+
+# salesforce-apex-test-runner-skill
+
+T1 read-only runtime skill for Apex test execution against a connected **sandbox** org.
+This skill runs tests, reads coverage, and diagnoses failures — it does not write code,
+deploy metadata, or touch production orgs. The **View All Data** permission is required
+by `sf apex run test` per Salesforce platform behavior; this permission must be granted
+only on the sandbox-only service account and NEVER on a production-eligible account.
+
+## When This Skill Owns the Task
+
+Use `salesforce-apex-test-runner-skill` when the work requires **live test execution**:
+
+- "Run the AccountServiceTest class in my sandbox"
+- "Execute all local tests before deployment"
+- "My test is failing with a governor limit error — run it and show me the stack trace"
+- "Check code coverage for the Order trigger after my last change"
+- "Run specific test methods: AccountServiceTest.testBulkSuccess"
+
+**Delegate elsewhere when:**
+
+| Situation | Skill to use |
+|---|---|
+| User needs test classes authored | `salesforce-apex-test-generator-skill` |
+| User needs production Apex authored | `salesforce-apex-generator-skill` |
+| Debug log analysis without running | `salesforce-apex-log-analyzer-skill` |
+| Static code review of test code | `salesforce-apex-lwc-code-review-skill` |
+| Sandbox deploy and validate | `salesforce-deployment-validator-skill` |
+
+---
+
+## Required Context to Gather First
+
+Before running any tests, confirm:
+
+1. **Target org alias** — the `--target-org` value from `sf org list`. Never accept a raw
+   instance URL or session token.
+2. **Org type** — must be sandbox. If production, **stop immediately** (see HARD REFUSAL).
+3. **Test scope** — specific class names, specific method names, or test level
+   (`RunLocalTests`, `RunAllTestsInOrg`, `RunSpecifiedTests`).
+4. **Coverage threshold** — default 75% per Salesforce deployment requirement; note if higher.
+5. **Goal** — diagnosis only, or diagnosis + fix loop?
+
+---
+
+## Recommended Workflow
+
+### Step 1 — Verify org alias and type
+
+```bash
+sf org display --target-org <alias>
+```
+
+Parse output for `instanceUrl` and check for sandbox indicators in the domain
+(`.sandbox.`, `.cs`, `.scratch.`, `.scratch.salesforce.com`). If `instanceUrl` contains
+`login.salesforce.com` or `<companyname>.my.salesforce.com` without sandbox indicators,
+**treat as production and stop**.
+
+### Step 2 — Confirm Connected App allowlist
+
+The Connected App used by the Run As service account must have the target org alias
+explicitly in its allowlist. If the allowlist cannot be confirmed, stop and request
+the Connected App administrator verify the configuration.
+
+### Step 3 — Run the targeted test set
+
+```bash
+sf apex run test \
+  --test-level RunSpecifiedTests \
+  --tests <TestClassName1> <TestClassName2> \
+  --target-org <alias> \
+  --result-format json \
+  --wait 10
+```
+
+For broader coverage checks:
+
+```bash
+sf apex run test \
+  --test-level RunLocalTests \
+  --target-org <alias> \
+  --result-format json \
+  --wait 30
+  --code-coverage
+```
+
+### Step 4 — Retrieve results if async
+
+If the run was async (no `--wait` or timeout exceeded):
+
+```bash
+sf apex get test \
+  --test-run-id <id> \
+  --target-org <alias> \
+  --result-format json \
+  --code-coverage
+```
+
+### Step 5 — Parse results
+
+From the JSON output, extract:
+- **Pass count / fail count / skip count**
+- **Overall code coverage percentage** (target: >= 75%)
+- **Per-class coverage** — identify classes below threshold
+- **Failing test methods** — extract `methodName`, `message`, `stackTrace`
+- **Governor limit hits** — scan message for "Limit" patterns
+
+### Step 6 — Diagnose failures
+
+Consult `references/failure-diagnosis.md` for common patterns:
+- `DML in @TestSetup` restrictions
+- Governor limit errors in test context
+- `CalloutException` — missing mock
+- `QueryException` — data isolation issue (SeeAllData mis-use)
+- Async result not visible — missing `Test.startTest` / `Test.stopTest`
+
+### Step 7 — Emit sanitized results with audit envelope
+
+Apply redaction rules (see Redaction Rules section) before emitting any output.
+Emit the full audit envelope regardless of pass/fail outcome.
+
+### Step 8 — Recommend next steps
+
+If failures found: recommend `salesforce-apex-test-generator-skill` for test corrections
+or `salesforce-apex-log-analyzer-skill` for deeper log analysis.
+If coverage below threshold: identify which classes are uncovered and recommend targeted
+test generation.
+
+---
+
+## Quality Scoring Rubric (100-point)
+
+Score the test run and analysis before presenting. Threshold: 80+ acceptable.
+
+| Dimension | Points | What earns full marks |
+|---|---|---|
+| **Test selection appropriateness** | 25 | Scope matches the user's goal; RunSpecifiedTests used for targeted runs; RunLocalTests for pre-deploy coverage |
+| **Sandbox-only enforcement** | 25 | **CRITICAL gate** — org type verified as sandbox before any API call; HARD REFUSAL triggered for production targets |
+| **Coverage analysis** | 20 | Coverage percentage computed and compared to 75% threshold; per-class breakdown provided; uncovered classes named |
+| **Failure diagnosis quality** | 20 | Failures categorized by type; stack trace excerpted; remediation suggested from failure-diagnosis reference |
+| **Audit envelope** | 10 | All required audit fields present; timestamp accurate; org type verified field populated |
+
+**Scoring penalties:**
+- Sandbox check skipped: score voided (immediate HARD REFUSAL required)
+- No coverage analysis when `--code-coverage` was available: -20
+- Failures reported without diagnosis: -15
+- Missing audit envelope: -15 (automatic caveat regardless of total)
+- Org type not verified before execution: -25
+
+---
+
+## T1 Least-Privilege Contract
+
+This skill operates at T1 — read-only runtime (sandbox only).
+
+- **OAuth scopes:** `api` and `refresh_token` only. No `full`, `web`, `sfap_api`, or other scopes.
+- **Run As account permissions:**
+  - REQUIRED: `View Setup and Configuration`, `View All Data` (**sandbox service account only**)
+  - DENIED: `ModifyAllData`, `ViewEncryptedData`, `ModifyMetadata`, `AuthorApex`, `ManageConnectedApps`
+- **View All Data — important note:** The `sf apex run test` command requires the `View All Data`
+  system permission for the running user per Salesforce platform behavior. This is why the Run As
+  service account for this skill must be a **sandbox-only** account. This permission must NEVER
+  be granted on an account used for production org access.
+- **No code mutation:** This skill reads test results and coverage data. It does not write,
+  deploy, modify metadata, or create records outside of test context.
+- **Org allowlist:** Connected App enforces which aliases are reachable. Skill verifies org
+  type before executing any `sf apex` command.
+
+---
+
+## HARD REFUSAL — Production Org Targets
+
+**If the target org is identified as production, stop immediately and do not execute any
+`sf apex` command.**
+
+Production refusal response:
+
+```
+HARD REFUSAL: Apex test execution is not permitted on production orgs via this skill.
+
+Reason: salesforce-apex-test-runner-skill operates at T1 sandbox-only scope. The
+View All Data system permission required by sf apex run test must never be granted
+on a production-eligible service account. Production Apex test runs also carry risk
+of long-running test locks affecting live users.
+
+Action required:
+1. Identify a sandbox org alias for this test run.
+2. Verify the Connected App allowlist includes the sandbox alias.
+3. Re-invoke this skill with the sandbox alias.
+
+If a production test run is genuinely required (e.g., for a post-deployment verification),
+route through the human approval path via salesforce-live-guard-agent.
+```
+
+---
+
+## Audit Envelope Schema
+
+Every execution emits an audit envelope. Emit even on HARD REFUSAL.
+
+```yaml
+audit_envelope:
+  matter_id: "<caller-provided-or-generated-uuid>"
+  skill_id: "salesforce-apex-test-runner-skill"
+  skill_version: "0.1.0"
+  target_org_alias: "<alias>"
+  run_as_user_id: "<user_id_placeholder>"
+  org_type_verified: "sandbox | production | unknown"
+  test_run_id: "<sf-apex-run-test-id or 'refused'>"
+  test_level: "<RunSpecifiedTests | RunLocalTests | RunAllTestsInOrg | refused>"
+  tests_requested: ["<ClassName.methodName or ClassName>"]
+  pass_count: <integer>
+  fail_count: <integer>
+  skip_count: <integer>
+  overall_coverage_pct: <float or null>
+  timestamp: "<ISO-8601-UTC>"
+  refusal_reason: "<reason if refused | null>"
+```
+
+---
+
+## Output Format
+
+```yaml
+verdict: "pass | fail | refused"
+quality_score: <0-100>
+quality_notes: "<scoring rationale>"
+
+test_summary:
+  org_alias: "<alias>"
+  org_type: "sandbox | production | unknown"
+  test_level: "<level used>"
+  pass_count: <integer>
+  fail_count: <integer>
+  skip_count: <integer>
+  overall_coverage_pct: <float>
+  coverage_threshold_met: true | false
+
+failing_tests:
+  - test: "<ClassName.methodName>"
+    message: "<error message>"
+    stack_trace_excerpt: "<first 3-5 lines>"
+    diagnosis: "<category from failure-diagnosis.md>"
+    suggested_fix: "<specific remediation>"
+
+coverage_gaps:
+  - class: "<ClassName>"
+    coverage_pct: <float>
+    suggested_action: "<add tests for X method>"
+
+audit_envelope:
+  <see Audit Envelope Schema>
+
+next_steps:
+  - "<if failures: salesforce-apex-test-generator-skill for test fixes>"
+  - "<if coverage gaps: salesforce-apex-test-generator-skill for additional tests>"
+  - "<if ready: salesforce-deployment-validator-skill for sandbox deploy>"
+
+assumptions:
+  - "<explicit list>"
+```
+
+---
+
+## Redaction Rules
+
+Apply in order before emitting any output:
+
+1. **OAuth tokens, refresh tokens, session IDs:** Never include in any output. Strip from CLI output.
+2. **Salesforce Org IDs (18-char starting with `00D`):** Replace with `<org_id_placeholder>`.
+3. **Salesforce Record IDs (15/18-char):** Replace with `<record_id_placeholder>` in output.
+4. **User IDs (OwnerId, CreatedById, RunningUserId, User.Id):** Replace with `<user_id_placeholder>`.
+5. **Test run IDs:** Retain in audit envelope (non-sensitive); redact from narrative output.
+6. **Stack trace class names and line numbers:** Retain — needed for diagnosis. Do not redact.
+7. **Exception messages:** Retain — needed for diagnosis. If message contains a Salesforce ID,
+   replace the ID but retain the rest of the message.
+8. **Instance URLs and API endpoints:** Omit from output; reference only the org alias.
+
+---
+
+## Handoff Rules
+
+| Finding | Hand off to |
+|---|---|
+| Test failures needing code fixes | `salesforce-apex-test-generator-skill` |
+| Coverage gaps needing new test methods | `salesforce-apex-test-generator-skill` |
+| Log-level failure requiring debug analysis | `salesforce-apex-log-analyzer-skill` |
+| All tests pass with coverage met | `salesforce-deployment-validator-skill` |
+| Production target attempted | `salesforce-live-guard-agent` (human approval path) |
+
+---
+
+## Stop Conditions
+
+Stop and do not continue if:
+
+- Org type cannot be determined from `sf org display` output — stop, request clarification.
+- Org type is production — HARD REFUSAL (see above), stop.
+- The Run As account is missing `View Setup and Configuration` — stop and escalate to org administrator.
+- The audit envelope cannot be populated (missing matter_id, org alias unresolvable) — stop.
+- The user requests redaction to be skipped — stop and explain the policy.
+
+---
+
+## Security Notes
+
+- **Sandbox-only:** Production org targets are hard-refused before any API call. The Connected App
+  allowlist enforces this at the platform level as a second control.
+- **View All Data — sandbox-only account:** The `View All Data` system permission required by
+  `sf apex run test` must exist only on the sandbox-only Run As service account. Separation from
+  any production-eligible account is mandatory.
+- **Read-only runtime:** No DML, no metadata mutation, no code deployment, no record creation
+  outside Apex test context (which is isolated and rolled back by the platform).
+- **Sanitized output:** All Salesforce IDs, user IDs, and OAuth tokens redacted before emission.
+- **Structured audit:** Every execution produces a complete audit envelope, including refusals.
+- **Revocable:** Rotating the Run As sandbox account's refresh token immediately revokes all access.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `references/cli-commands.md` | sf apex run test variants, --test-level options, --result-format, --wait, async retrieval |
+| `references/coverage-analysis.md` | Coverage percentage interpretation, 75% requirement, line vs branch coverage, per-class gap analysis |
+| `references/failure-diagnosis.md` | Common Apex test failure patterns: DML on setup, governor limits, callouts in tests, async test gotchas |

package/skills/salesforce/salesforce-apex-test-runner-skill/metadata.json

@@ -0,0 +1,37 @@
+{
+  "id": "salesforce-apex-test-runner-skill",
+  "name": "Salesforce Apex Test Runner Skill",
+  "type": "skill",
+  "provider": "salesforce",
+  "harnesses": ["claude-code", "codex", "cursor", "gemini", "kiro", "other"],
+  "summary": "Executes Apex tests against a connected sandbox org via sf apex run test, parses results and coverage delta, identifies failures with stack traces, and suggests fixes. T1 read-only runtime (sandbox-only). Production org targets are hard-refused before any API call. View All Data permission is required by sf apex run test and must exist only on the sandbox-only Run As service account.",
+  "source_type": "adapted",
+  "source_attribution": "Adapted from forcedotcom/sf-skills running-apex-tests (Apache-2.0). Vanguard-specific additions: T1 tier declaration, sandbox-only hard refusal, View All Data sandbox-account isolation note, structured audit envelope, redaction rules, and handoff routing model.",
+  "category": "operational",
+  "execution_tier": "read-only-runtime",
+  "oauth_scopes": ["api", "refresh_token"],
+  "mcp_servers": [],
+  "run_as_permissions": {
+    "required": ["View Setup and Configuration", "View All Data (sandbox-only)"],
+    "denied": [
+      "ModifyAllData",
+      "ViewEncryptedData",
+      "ModifyMetadata",
+      "AuthorApex",
+      "ManageConnectedApps"
+    ]
+  },
+  "sandbox_only": true,
+  "production_allowed": false,
+  "official_docs": [
+    "https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_apex_commands_unified.htm#cli_reference_apex_run_test_unified",
+    "https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing_code_coverage.htm",
+    "https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing.htm",
+    "https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm"
+  ],
+  "security_notes": "T1 read-only runtime. Sandbox-only — production org targets are hard-refused before any API call. The View All Data system permission required by sf apex run test must exist exclusively on the sandbox-only Run As service account and never on a production-eligible account. OAuth scopes restricted to api + refresh_token. No DML, no metadata mutation, no code deployment. All Salesforce IDs, user IDs, and OAuth tokens are redacted before output. Structured audit envelope emitted on every execution including refusals. Rotating the Run As sandbox account's refresh token immediately revokes all access.",
+  "last_verified": "2026-05-21",
+  "path": "skills/salesforce/salesforce-apex-test-runner-skill",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/salesforce/salesforce-apex-test-runner-skill/references/cli-commands.md

@@ -0,0 +1,162 @@
+# sf apex run test — CLI Commands Reference
+
+Adapted from forcedotcom/sf-skills running-apex-tests references (Apache-2.0).
+
+## Core Command: sf apex run test
+
+```bash
+# Run specific test classes
+sf apex run test \
+  --test-level RunSpecifiedTests \
+  --tests AccountServiceTest ContactServiceTest \
+  --target-org <alias> \
+  --result-format json \
+  --wait 10
+
+# Run specific test methods
+sf apex run test \
+  --test-level RunSpecifiedTests \
+  --tests AccountServiceTest.testBulkUpdate AccountServiceTest.testNullIdThrows \
+  --target-org <alias> \
+  --result-format json \
+  --wait 10
+
+# Run all local tests (pre-deploy coverage check)
+sf apex run test \
+  --test-level RunLocalTests \
+  --target-org <alias> \
+  --result-format json \
+  --code-coverage \
+  --wait 30
+
+# Run all tests including managed package tests (rarely needed)
+sf apex run test \
+  --test-level RunAllTestsInOrg \
+  --target-org <alias> \
+  --result-format json \
+  --code-coverage \
+  --wait 60
+```
+
+## --test-level Options
+
+| Level | What runs | When to use |
+|---|---|---|
+| `RunSpecifiedTests` | Only the named test classes/methods | Targeted debugging, single-class coverage |
+| `RunLocalTests` | All tests in the org (not managed package tests) | Pre-deploy coverage check, full regression |
+| `RunAllTestsInOrg` | All tests including managed packages | Rarely needed; very slow |
+
+## Result Format Options
+
+| Format | Use case |
+|---|---|
+| `json` | Machine-parseable; use for scripted analysis |
+| `tap` | TAP protocol; use for CI integration |
+| `junit` | JUnit XML; use for CI reporting systems |
+| `human` | Readable; use for interactive sessions |
+
+## Async Run (no --wait)
+
+For long test suites, omit `--wait` to run asynchronously and retrieve results later:
+
+```bash
+# Start async run
+sf apex run test \
+  --test-level RunLocalTests \
+  --target-org <alias> \
+  --result-format json
+# Output includes: "testRunId": "707Xx000001ABCDEF"
+
+# Retrieve results when ready
+sf apex get test \
+  --test-run-id 707Xx000001ABCDEF \
+  --target-org <alias> \
+  --result-format json \
+  --code-coverage
+```
+
+## Org Verification Commands
+
+```bash
+# Verify org alias and type
+sf org display --target-org <alias>
+# Check: instanceUrl (sandbox vs prod), connectedStatus, username
+
+# List all available orgs
+sf org list
+# Shows all authenticated orgs with type and alias
+
+# Check org limits
+sf org display --target-org <alias> --json
+```
+
+## Parsing JSON Results
+
+Key fields in the JSON output:
+
+```json
+{
+  "result": {
+    "summary": {
+      "outcome": "Passed | Failed",
+      "testsRan": 42,
+      "passing": 40,
+      "failing": 2,
+      "skipped": 0,
+      "passRate": "95%",
+      "failRate": "5%",
+      "testStartTime": "2026-05-21T12:00:00.000Z",
+      "testExecutionTime": "12345 ms",
+      "testTotalTime": "12500 ms",
+      "orgId": "00DXx000001ABCDEF",
+      "username": "deploy@myorg.sandbox"
+    },
+    "tests": [
+      {
+        "id": "07MXx000001ABCDEF",
+        "queueItemId": "7091X000002ABCDEF",
+        "stackTrace": "Class.AccountService.updateIndustry: line 45, column 1\nClass.AccountServiceTest.testBulkUpdate: line 22, column 1",
+        "message": "System.LimitException: Too many SOQL queries: 101",
+        "asyncApexJobId": "707Xx000001ABCDEF",
+        "methodName": "testBulkUpdate",
+        "outcome": "Fail",
+        "apexClass": {
+          "id": "01pXx000001ABCDEF",
+          "name": "AccountServiceTest",
+          "namespacePrefix": null
+        },
+        "runTime": 1234,
+        "testTimestamp": "2026-05-21T12:00:05.000Z",
+        "fullName": "AccountServiceTest.testBulkUpdate"
+      }
+    ],
+    "codecoverage": [
+      {
+        "id": "01pXx000001ABCDEF",
+        "name": "AccountService",
+        "type": "Class",
+        "numLinesCovered": 45,
+        "numLinesUncovered": 5,
+        "coveredPercent": 90
+      }
+    ]
+  }
+}
+```
+
+## Coverage Analysis via jq
+
+```bash
+# Extract overall pass/fail summary
+sf apex run test --test-level RunLocalTests --target-org <alias> --result-format json \
+  | jq '.result.summary | {outcome, passing, failing, passRate}'
+
+# Find classes below 75% coverage
+sf apex run test --test-level RunLocalTests --target-org <alias> --result-format json --code-coverage \
+  | jq '[.result.codecoverage[] | select(.coveredPercent < 75) | {name, coveredPercent}]'
+
+# Extract failing test details
+sf apex run test --test-level RunSpecifiedTests --tests MyClass --target-org <alias> \
+  --result-format json \
+  | jq '[.result.tests[] | select(.outcome == "Fail") | {fullName, message, stackTrace}]'
+```

package/skills/salesforce/salesforce-apex-test-runner-skill/references/coverage-analysis.md

@@ -0,0 +1,107 @@
+# Apex Code Coverage Analysis Reference
+
+Adapted from forcedotcom/sf-skills running-apex-tests references (Apache-2.0).
+
+## The 75% Rule
+
+Salesforce requires 75% aggregate code coverage across all Apex classes and triggers
+(excluding test classes) for deployment to production. This is a deployment gate —
+failing this threshold blocks all production deployments.
+
+**Key facts:**
+- 75% applies to the **aggregate** across all classes, not each class individually
+- However, any single class below 75% may still block if that class is in the deployment
+- Triggers must have at least 1% coverage (at least one line covered) to deploy
+- Classes with 0% coverage block deployment if they are included in the deployment package
+
+## Coverage Report Interpretation
+
+From `sf apex run test --code-coverage --result-format json`:
+
+```json
+{
+  "codecoverage": [
+    {
+      "name": "AccountService",
+      "numLinesCovered": 45,
+      "numLinesUncovered": 5,
+      "coveredPercent": 90,
+      "uncoveredLines": [23, 45, 67, 89, 102]
+    }
+  ]
+}
+```
+
+- `coveredPercent` = `numLinesCovered / (numLinesCovered + numLinesUncovered) * 100`
+- `uncoveredLines` — line numbers not executed by any test; these are the gaps to fill
+
+## Coverage Gap Triage
+
+When a class is below threshold, identify the gap type:
+
+| Gap type | Description | Fix strategy |
+|---|---|---|
+| **Exception path uncovered** | Try/catch blocks with no test for the catch | Add negative test that triggers the exception |
+| **Bulk path uncovered** | Code only reached with > 200 records | Add bulk test method |
+| **Conditional branch uncovered** | else/if branch never executed | Add test for each conditional branch |
+| **Async path uncovered** | Queueable/Batch execute never called | Add async test with Test.startTest/stopTest |
+| **Early return uncovered** | Guard clause never triggered | Add test with invalid/null input |
+
+## Line vs Branch Coverage
+
+Salesforce reports **line coverage** (not branch coverage). A line is "covered" if it
+was executed at least once by any test. This means:
+
+- An if/else on one line may show as covered even if only one branch was taken
+- 100% line coverage does not guarantee all code paths are tested
+- Aim for explicit positive + negative + bulk tests to cover both branches even if
+  line coverage shows 100%
+
+## Per-Class Coverage Thresholds
+
+| Coverage | Status |
+|---|---|
+| >= 90% | Excellent — deploy with confidence |
+| 75–89% | Acceptable — at or above deployment threshold |
+| 50–74% | Warning — below deployment threshold; gaps likely in exception/bulk paths |
+| < 50% | Critical — significant coverage gaps; deployment will likely fail |
+| 0% | Blocker — class will prevent deployment if included in the package |
+
+## Identifying Uncovered Lines
+
+After a test run, retrieve specific uncovered lines:
+
+```bash
+sf apex get test \
+  --test-run-id <id> \
+  --target-org <alias> \
+  --result-format json \
+  --code-coverage \
+  | jq '[.result.codecoverage[] | {name, coveredPercent, uncoveredLines}]'
+```
+
+Then read the class file to identify which code paths the uncovered lines correspond to:
+
+```bash
+# Find the class file and check uncovered lines
+grep -n "." force-app/main/default/classes/AccountService.cls | sed -n '23p;45p;67p'
+```
+
+## Coverage Strategy Recommendations
+
+For each class below 75%:
+
+1. **Check test class exists** — if no test class exists, generate one with
+   `salesforce-apex-test-generator-skill`
+2. **Check for async paths** — if Queueable/Batch methods are present, verify
+   `Test.startTest` / `Test.stopTest` wraps the enqueue call in tests
+3. **Check exception paths** — add tests that trigger catch blocks
+4. **Check bulk path** — add a test with 201+ records if trigger-context logic exists
+5. **Check conditional branches** — identify if/else and add tests for each branch
+
+## Coverage in CI/CD Context
+
+For pre-deployment validation with `salesforce-deployment-validator-skill`:
+- Use `--test-level RunLocalTests --code-coverage` to measure full org coverage
+- Set a stricter internal threshold (80-85%) to provide buffer above the 75% hard limit
+- Track per-class coverage trends across deployments to catch regressions early